QOpenGLWidget Class

Description détaillée

QOpenGLWidget fournit des fonctionnalités permettant d'afficher des graphiques OpenGL intégrés à une application Qt. Son utilisation est très simple : faites en sorte que votre classe en hérite et utilisez la sous-classe comme n'importe quelle autre classe de la classe « QWidget », à la différence près que vous avez le choix entre utiliser « QPainter » et les commandes de rendu OpenGL standard.

QOpenGLWidget fournit trois fonctions virtuelles pratiques que vous pouvez réimplémenter dans votre sous-classe pour effectuer les tâches OpenGL courantes :

• paintGL() - Effectue le rendu de la scène OpenGL. Est appelée chaque fois que le widget doit être mis à jour.
• resizeGL() - Configure la fenêtre d’affichage OpenGL, la projection, etc. Elle est appelée chaque fois que le widget a été redimensionné (ainsi que lors de sa première affichage, car tous les widgets nouvellement créés reçoivent automatiquement un événement de redimensionnement).
• initializeGL() - Configure les ressources et l’état OpenGL. Est appelée une seule fois avant le premier appel à ` resizeGL()` ou ` paintGL()`.

Si vous devez déclencher un rafraîchissement à partir d'autres endroits que paintGL() (un exemple typique est l'utilisation de timers pour animer des scènes), vous devez appeler la fonction update() du widget pour planifier une mise à jour.

Le contexte de rendu OpenGL de votre widget devient actif lorsque paintGL(), resizeGL() ou initializeGL() est appelé. Si vous devez appeler les fonctions standard de l’API OpenGL depuis d’autres endroits (par exemple dans le constructeur de votre widget ou dans vos propres fonctions de dessin), vous devez d’abord appeler makeCurrent().

Tout le rendu s'effectue dans un objet framebuffer OpenGL. La fonction makeCurrent() garantit qu'il est lié au contexte. Gardez cela à l'esprit lorsque vous créez et liez des objets framebuffer supplémentaires dans le code de rendu de la fonction paintGL(). Ne reliez jamais le framebuffer avec l'ID 0. Appelez plutôt la fonction defaultFramebufferObject() pour obtenir l'ID qui doit être lié.

QOpenGLWidget permet d’utiliser différentes versions et différents profils OpenGL lorsque la plate-forme le prend en charge. Il suffit de définir le format souhaité via setFormat(). Gardez toutefois à l’esprit que la présence de plusieurs instances de QOpenGLWidget dans une même fenêtre nécessite qu’elles utilisent toutes le même format, ou au moins des formats qui ne rendent pas les contextes non partageables. Pour contourner ce problème, privilégiez l’utilisation de QSurfaceFormat::setDefaultFormat() plutôt que setFormat().

Techniques de rendu

Comme décrit ci-dessus, sous-classez QOpenGLWidget pour afficher du contenu 3D pur de la manière suivante :

• Réimplémentez les fonctions ` initializeGL()` et ` resizeGL()` pour configurer l’état OpenGL et fournir une transformation de perspective.
• Réimplémentez la méthode paintGL() pour dessiner la scène 3D, en n'appelant que des fonctions OpenGL.

Il est également possible de dessiner des graphiques 2D sur une sous-classe de QOpenGLWidget à l'aide de QPainter:

• Dans paintGL(), au lieu d’émettre des commandes OpenGL, créez un objet QPainter destiné à être utilisé sur le widget.
• Dessinez des primitives à l’aide des fonctions membres de ` QPainter`.
• Il est toujours possible d'émettre des commandes OpenGL directes. Cependant, vous devez vous assurer que celles-ci sont encadrées par un appel aux fonctions beginNativePainting() et endNativePainting() du « painter ».

Lorsque vous effectuez un dessin en utilisant uniquement ` QPainter `, il est également possible d’effectuer le dessin comme pour les widgets ordinaires : en réimplémentant ` paintEvent()`.

• Réimplémentez la fonction paintEvent().
• Créez un objet ` QPainter ` en ciblant le widget. Passez le widget soit au constructeur, soit à la fonction ` QPainter::begin()`.
• Dessinez des primitives à l’aide des fonctions membres d’ QPainter.
• Une fois le dessin terminé, l’instance de ` QPainter ` est détruite. Vous pouvez également appeler explicitement la fonction ` QPainter::end()`.

Appels de fonctions OpenGL, en-têtes et QOpenGLFunctions

Lors de l’appel de fonctions OpenGL, il est fortement recommandé d’éviter d’appeler les fonctions directement. Préférez plutôt utiliser ` QOpenGLFunctions ` (lors de la création d’applications portables) ou les variantes versionnées (par exemple, ` QOpenGLFunctions_3_2_Core ` et similaires, lorsque vous ciblez une version moderne d’OpenGL réservée aux ordinateurs de bureau). De cette manière, l’application fonctionnera correctement dans toutes les configurations de compilation Qt, y compris celles qui effectuent un chargement dynamique de l’implémentation OpenGL, ce qui signifie que les applications ne se lient pas directement à une implémentation GL et que, par conséquent, les appels de fonction directs ne sont pas possibles.

Dans ` paintGL()` (), le contexte actuel est toujours accessible en appelant ` QOpenGLContext::currentContext()` (). À partir de ce contexte, une instance ` QOpenGLFunctions ` déjà initialisée et prête à l’emploi peut être récupérée en appelant ` QOpenGLContext::functions()` (). Une alternative au préfixage de chaque appel GL consiste à hériter de ` QOpenGLFunctions ` et à appeler ` QOpenGLFunctions::initializeOpenGLFunctions()` () dans ` initializeGL()` ().

En ce qui concerne les en-têtes OpenGL, notez que dans la plupart des cas, il ne sera pas nécessaire d’inclure directement des en-têtes tels que GL.h. Les en-têtes Qt liés à OpenGL incluront qopengl.h, qui inclura à son tour l’en-tête approprié pour le système. Il peut s’agir d’un en-tête OpenGL ES 3.x ou 2.0, de la version la plus récente disponible, ou d’un fichier gl.h fourni par le système. De plus, une copie des en-têtes d’extension (appelés glext.h sur certains systèmes) est fournie avec Qt, tant pour OpenGL que pour OpenGL ES. Ceux-ci seront inclus automatiquement sur les plateformes où cela est possible. Cela signifie que les constantes et les typedefs de pointeurs de fonction provenant des extensions ARB, EXT et OES sont automatiquement disponibles.

Exemples de code

Pour commencer, la sous-classe QOpenGLWidget la plus simple pourrait ressembler à ceci :

class MyGLWidget : public QOpenGLWidget
{
public:
    MyGLWidget(QWidget *parent) : QOpenGLWidget(parent) { }

protected:
    void initializeGL() override
    {
        // Set up the rendering context, load shaders and other resources, etc.:
        QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
        f->glClearColor(1.0f, 1.0f, 1.0f, 1.0f);
        ...
    }

    void resizeGL(int w, int h) override
    {
        // Update projection matrix and other size related settings:
        m_projection.setToIdentity();
        m_projection.perspective(45.0f, w / float(h), 0.01f, 100.0f);
        ...
    }

    void paintGL() override
    {
        // Draw the scene:
        QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
        f->glClear(GL_COLOR_BUFFER_BIT);
        ...
    }

};

Il est également possible d’éviter d’avoir à préfixer chaque appel OpenGL en dérivant plutôt de la classe ` QOpenGLFunctions ` :

class MyGLWidget : public QOpenGLWidget, protected QOpenGLFunctions
{
    ...
    void initializeGL() override
    {
        initializeOpenGLFunctions();
        glClearColor(...);
        ...
    }
    ...
};

Pour obtenir un contexte compatible avec une version ou un profil OpenGL donné, ou pour demander des tampons de profondeur et de stencil, appelez setFormat() :

QOpenGLWidget *widget = new QOpenGLWidget(parent);
QSurfaceFormat format;
format.setDepthBufferSize(24);
format.setStencilBufferSize(8);
format.setVersion(3, 2);
format.setProfile(QSurfaceFormat::CoreProfile);
widget->setFormat(format); // must be called before the widget or its parent window gets shown

Avec les contextes OpenGL 3.0 et supérieurs, lorsque la portabilité n’est pas un critère important, les variantes versionnées de ` QOpenGLFunctions ` permettent d’accéder facilement à toutes les fonctions OpenGL modernes disponibles dans une version donnée :

    ...
    void paintGL() override
    {
        QOpenGLFunctions_3_2_Core *f = QOpenGLContext::currentContext()->versionFunctions<QOpenGLFunctions_3_2_Core>();
        ...
        f->glDrawArraysInstanced(...);
        ...
    }
    ...

Comme décrit ci-dessus, il est plus simple et plus fiable de définir le format demandé de manière globale afin qu’il s’applique à toutes les fenêtres et à tous les contextes pendant toute la durée de vie de l’application. En voici un exemple :

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QSurfaceFormat format;
    format.setDepthBufferSize(24);
    format.setStencilBufferSize(8);
    format.setVersion(3, 2);
    format.setProfile(QSurfaceFormat::CoreProfile);
    QSurfaceFormat::setDefaultFormat(format);

    MyWidget widget;
    widget.show();

    return app.exec();
}

Multisampling

Pour activer le multisampling, définissez le nombre d’échantillons requis sur l’ QSurfaceFormat transmis à la fonction ` setFormat()`. Sur les systèmes qui ne prennent pas en charge cette fonctionnalité, la requête peut être ignorée.

La prise en charge du multisampling nécessite la prise en charge des buffers de rendu multisamplés et des blits de framebuffer. Sur les implémentations OpenGL ES 2.0, il est probable que ces fonctionnalités ne soient pas présentes. Cela signifie que le multisampling ne sera pas disponible. Avec les versions modernes d’OpenGL et OpenGL ES 3.0 et versions ultérieures, cela ne pose généralement plus de problème.

Multithreading

Le rendu hors écran sur des threads de travail, par exemple pour générer des textures qui seront ensuite utilisées dans l’interface graphique ou le thread principal via ` paintGL()`, est pris en charge en exposant l’interface ` QOpenGLContext ` du widget, ce qui permet de créer des contextes supplémentaires partagés avec celui-ci sur chaque thread.

Il est possible de dessiner directement dans le framebuffer du QOpenGLWidget en dehors du thread de l’interface graphique ou du thread principal en réimplémentant la méthode ` paintEvent()` pour qu’elle ne fasse rien. L’affinité de thread du contexte doit être modifiée via ` QObject::moveToThread()`. Après cela, les méthodes ` makeCurrent()` et ` doneCurrent()` sont utilisables sur le thread de travail. Veillez à replacer ensuite le contexte sur le thread GUI/principal.

Il n’est pas possible de déclencher un échange de tampon uniquement pour le `QOpenGLWidget`, car il ne dispose pas de véritable surface native à l’écran. C’est à la pile de widgets qu’il revient de gérer la composition et les échanges de tampons sur le thread GUI. Lorsqu’un thread a terminé la mise à jour du tampon de trame, appelez ` update()` sur le thread GUI/principal pour planifier la composition.

Il faut veiller tout particulièrement à ne pas utiliser le tampon d’image lorsque le thread GUI/principal effectue la composition. Les signaux ` aboutToCompose()` et ` frameSwapped()` sont émis au début et à la fin de la composition. Ils sont émis sur le thread GUI/principal. Cela signifie qu’en utilisant une connexion directe, ` aboutToCompose()` peut bloquer le thread GUI/principal jusqu’à ce que le thread de travail ait terminé son rendu. Après cela, le thread de travail ne doit plus effectuer de rendu jusqu’à ce que le signal ` frameSwapped()` soit émis. Si cela n’est pas acceptable, le thread de travail doit mettre en œuvre un mécanisme de double tampon. Cela implique de dessiner à l’aide d’une cible de rendu alternative, entièrement contrôlée par le thread, par exemple un objet framebuffer supplémentaire, puis de transférer le contenu vers le framebuffer du `QOpenGLWidget` au moment opportun.

Partage de contexte

Lorsque plusieurs QOpenGLWidgets sont ajoutés en tant qu’enfants d’un même widget de niveau supérieur, leurs contextes sont partagés entre eux. Cela ne s’applique pas aux instances de QOpenGLWidget appartenant à des fenêtres différentes.

Cela signifie que tous les QOpenGLWidgets d’une même fenêtre peuvent accéder aux ressources partageables les uns des autres, comme les textures, et qu’il n’est pas nécessaire de disposer d’un contexte « global share » supplémentaire.

Pour configurer le partage entre des instances de `QOpenGLWidget` appartenant à des fenêtres différentes, définissez l’attribut d’application ` Qt::AA_ShareOpenGLContexts ` avant d’instancier ` QApplication`. Cela déclenchera le partage entre toutes les instances de `QOpenGLWidget` sans aucune autre étape.

Il est également possible de créer des instances supplémentaires de ` QOpenGLContext ` qui partagent des ressources, telles que des textures, avec le contexte de `QOpenGLWidget`. Il suffit de passer le pointeur renvoyé par ` context()` à ` QOpenGLContext::setShareContext()` avant d’appeler ` QOpenGLContext::create()`. Le contexte ainsi obtenu peut également être utilisé sur un autre thread, ce qui permet la génération de textures en multithread et le chargement asynchrone des textures.

Notez que QOpenGLWidget s’attend à une implémentation conforme aux normes en matière de partage des ressources de la part des pilotes graphiques sous-jacents. Par exemple, certains pilotes, notamment ceux destinés aux appareils mobiles et au matériel embarqué, rencontrent des problèmes lors de la configuration du partage entre un contexte existant et d’autres créés ultérieurement. D’autres pilotes peuvent se comporter de manière inattendue lorsqu’on tente d’utiliser des ressources partagées entre différents threads.

Initialisation et libération des ressources

Le contexte OpenGL associé à QOpenGLWidget est garanti d'être à jour chaque fois que les fonctions initializeGL() et paintGL() sont appelées. N'essayez pas de créer des ressources OpenGL avant l'appel de la fonction initializeGL(). Par exemple, toute tentative de compilation de shaders, d'initialisation d'objets de tampon de sommets ou de chargement de données de texture échouera si elle est effectuée dans le constructeur d'une sous-classe. Ces opérations doivent être reportées à l’appel de ` initializeGL()`. Certaines classes d’aide Qt OpenGL, telles que ` QOpenGLBuffer ` ou ` QOpenGLVertexArrayObject`, présentent un comportement différé similaire : elles peuvent être instanciées sans contexte, mais toute initialisation est reportée jusqu’à l’appel de ` create()` ou d’une fonction similaire. Cela signifie qu’elles peuvent être utilisées comme des variables membres normales (non pointeurs) dans une sous-classe de `QOpenGLWidget`, mais que la fonction ` create()` ou toute autre fonction similaire ne peut être appelée qu’à partir de ` initializeGL()`. Sachez toutefois que toutes les classes ne sont pas conçues de cette manière. En cas de doute, définissez la variable membre comme un pointeur et créez et détruisez l’instance de manière dynamique respectivement dans ` initializeGL()` et dans le destructeur.

La libération des ressources nécessite également que le contexte soit à jour. Par conséquent, les destructeurs chargés de ce nettoyage doivent appeler ` makeCurrent()` avant de procéder à la destruction des ressources OpenGL ou des wrappers. Évitez la suppression différée via ` deleteLater()` ou le mécanisme de parenté de ` QObject`. Il n'y a aucune garantie que le contexte correct soit à jour au moment où l'instance en question sera réellement détruite.

Une sous-classe typique ressemblera donc souvent à ce qui suit en matière d’initialisation et de destruction des ressources :

class MyGLWidget : public QOpenGLWidget
{
    ...

private:
    QOpenGLVertexArrayObject m_vao;
    QOpenGLBuffer m_vbo;
    QOpenGLShaderProgram *m_program;
    QOpenGLShader *m_shader;
    QOpenGLTexture *m_texture;
};

MyGLWidget::MyGLWidget()
    : m_program(0), m_shader(0), m_texture(0)
{
    // No OpenGL resource initialization is done here.
}

MyGLWidget::~MyGLWidget()
{
    // Make sure the context is current and then explicitly
    // destroy all underlying OpenGL resources.
    makeCurrent();

    delete m_texture;
    delete m_shader;
    delete m_program;

    m_vbo.destroy();
    m_vao.destroy();

    doneCurrent();
}

void MyGLWidget::initializeGL()
{
    m_vao.create();
    if (m_vao.isCreated())
        m_vao.bind();

    m_vbo.create();
    m_vbo.bind();
    m_vbo.allocate(...);

    m_texture = new QOpenGLTexture(QImage(...));

    m_shader = new QOpenGLShader(...);
    m_program = new QOpenGLShaderProgram(...);

    ...
}

Cela fonctionne dans la plupart des cas, mais n’est pas tout à fait idéal en tant que solution générique. Lorsque le widget est réaffecté à un parent de sorte qu’il se retrouve dans une fenêtre de niveau supérieur entièrement différente, une mesure supplémentaire est nécessaire : en se connectant au signal ` aboutToBeDestroyed()` de ` QOpenGLContext`, le nettoyage peut être effectué chaque fois que le contexte OpenGL est sur le point d’être libéré.

MyGLWidget::~MyGLWidget()
{
    cleanup();
}

void MyGLWidget::initializeGL()
{
    ...
    connect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}

void MyGLWidget::cleanup()
{
    makeCurrent();
    delete m_texture;
    m_texture = 0;
    ...
    doneCurrent();
    disconnect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}

Un nettoyage adéquat est particulièrement important en raison du partage de contexte. Même si le contexte associé à chaque `QOpenGLWidget` est détruit en même temps que le `QOpenGLWidget`, les ressources partageables de ce contexte, telles que les textures, resteront valides jusqu’à ce que la fenêtre de niveau supérieur, dans laquelle résidait le `QOpenGLWidget`, soit détruite. De plus, des paramètres tels que ` Qt::AA_ShareOpenGLContexts ` et certains modules Qt peuvent élargir encore davantage la portée du partage des contextes, ce qui peut potentiellement entraîner le maintien en vie des ressources en question pendant toute la durée de vie de l’application. Par conséquent, la solution la plus sûre et la plus robuste consiste toujours à effectuer un nettoyage explicite de toutes les ressources et de tous les wrappers de ressources utilisés dans le `QOpenGLWidget`.

Limitations et autres considérations

Placer d’autres widgets en dessous et rendre le QOpenGLWidget transparent ne donnera pas les résultats escomptés : les widgets situés en dessous ne seront pas visibles. En effet, dans la pratique, le QOpenGLWidget est dessiné avant tous les autres widgets classiques (non OpenGL) ; les solutions de type « transparence » ne sont donc pas envisageables. D'autres types de mise en page, comme le fait de placer des widgets par-dessus le QOpenGLWidget, fonctionneront comme prévu.

En cas d’absolue nécessité, cette limitation peut être contournée en définissant l’attribut ` Qt::WA_AlwaysStackOnTop ` sur le `QOpenGLWidget`. Sachez toutefois que cela perturbe l’ordre d’empilement : par exemple, il ne sera plus possible de placer d’autres widgets au-dessus du QOpenGLWidget. Cette option ne doit donc être utilisée que dans les cas où un QOpenGLWidget semi-transparent laissant apparaître les widgets situés en dessous est requis.

Notez que cela ne s’applique pas lorsqu’il n’y a pas d’autres widgets en dessous et que l’objectif est d’obtenir une fenêtre semi-transparente. Dans ce cas, l’approche traditionnelle consistant à définir ` Qt::WA_TranslucentBackground ` sur la fenêtre de niveau supérieur est suffisante. Notez que si les zones transparentes ne sont souhaitées que dans le `QOpenGLWidget`, il faudra alors rétablir ` Qt::WA_NoSystemBackground ` sur ` false ` après avoir activé ` Qt::WA_TranslucentBackground`. De plus, il peut également être nécessaire de demander un canal alpha pour le contexte du `QOpenGLWidget` via ` setFormat()`, selon le système.

QOpenGLWidget prend en charge plusieurs comportements de mise à jour, tout comme QOpenGLWindow. En mode « preserved », le contenu rendu lors de l’appel précédent à paintGL() est disponible lors du suivant, ce qui permet un rendu incrémental. En mode « non preserved », le contenu est perdu et les implémentations de paintGL() doivent redessiner l’intégralité de la vue.

Avant Qt 5.5, le comportement par défaut de `QOpenGLWidget` consistait à conserver le contenu rendu entre les appels à ` paintGL()`. Depuis Qt 5.5, le comportement par défaut est le mode « non conservé », car cela offre de meilleures performances et la majorité des applications n’ont pas besoin du contenu précédent. Cela s’apparente également à la sémantique d’un « QWindow » basé sur OpenGL et correspond au comportement par défaut d’ QOpenGLWindow, dans la mesure où les tampons de couleur et auxiliaires sont invalidés à chaque image. Pour rétablir le comportement de conservation, appelez ` setUpdateBehavior()` avec ` PartialUpdate`.

Une fois qu’un `QOpenGLWidget` est ajouté à une hiérarchie de widgets, le contenu de la fenêtre de niveau supérieur est mis à jour via un rendu basé sur OpenGL. Les widgets autres que le `QOpenGLWidget` continuent à dessiner leur contenu à l’aide d’un moteur de dessin logiciel, mais la composition finale s’effectue via l’API 3D.

Alternatives

L’ajout d’un QOpenGLWidget dans une fenêtre active la composition basée sur OpenGL pour l’ensemble de la fenêtre. Dans certains cas particuliers, cela peut ne pas être idéal, et l’ancien comportement de type QGLWidget, avec une fenêtre enfant native distincte, peut être préférable. Les applications de bureau qui tiennent compte des limites de cette approche (par exemple en matière de chevauchements, de transparence, de vues défilantes et de zones MDI) peuvent utiliser ` QOpenGLWindow ` avec ` QWidget::createWindowContainer()`. Il s'agit d'une alternative moderne à `QGLWidget` et cette solution est plus rapide que `QOpenGLWidget` en raison de l'absence de l'étape de composition supplémentaire. Il est fortement recommandé de limiter l’utilisation de cette approche aux cas où il n’y a pas d’autre choix. Notez que cette option n’est pas adaptée à la plupart des plateformes embarquées et mobiles, et qu’elle présente également des problèmes sur certaines plateformes de bureau (par exemple macOS). La solution stable et multiplateforme reste toujours QOpenGLWidget.

Rendu stéréoscopique

À partir de la version 6.5, QOpenGLWidget prend en charge le rendu stéréoscopique. Pour l’activer, définissez globalement le drapeau QSurfaceFormat::StereoBuffers avant la création de la fenêtre, à l’aide de QSurfaceFormat::SetDefaultFormat().

Cela entraînera l’appel de ` paintGL()` deux fois par image, une fois pour chaque ` QOpenGLWidget::TargetBuffer`. Dans ` paintGL()`, appelez ` currentTargetBuffer()` pour déterminer sur lequel le dessin est en cours d’exécution.

OpenGL est une marque déposée de Silicon Graphics, Inc. aux États-Unis et dans d'autres pays.