QOpenGLWidget Class

Description détaillée

QOpenGLWidget fournit une fonctionnalité permettant d'afficher des graphiques OpenGL intégrés dans une application Qt. Il est très simple à utiliser : Faites en sorte que votre classe en hérite et utilisez la sous-classe comme n'importe quelle autre QWidget, sauf que vous avez le choix entre l'utilisation de 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 typiques :

• paintGL() - Rend la scène OpenGL. Elle est appelée chaque fois que le widget doit être mis à jour.
• resizeGL() - Configure le viewport OpenGL, la projection, etc. Est appelé chaque fois que le widget a été redimensionné (et également lorsqu'il est affiché pour la première fois, car tous les widgets nouvellement créés reçoivent automatiquement un événement de redimensionnement).
• initializeGL() - Configure les ressources et l'état OpenGL. Elle est appelée une fois avant le premier appel à resizeGL() ou paintGL().

Si vous devez déclencher un repeint à 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 programmer une mise à jour.

Le contexte de rendu OpenGL de votre widget est mis à jour 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 peinture), vous devez d'abord appeler makeCurrent().

Tous les rendus sont effectués dans un objet framebuffer OpenGL. makeCurrent L'appel à () permet de s'assurer 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 paintGL(). Ne reliez jamais le framebuffer avec l'ID 0. Au lieu de cela, appelez defaultFramebufferObject() pour obtenir l'ID qui doit être lié.

QOpenGLWidget permet d'utiliser différentes versions et profils OpenGL lorsque la plateforme le supporte. Il suffit de définir le format requis via setFormat(). Gardez cependant à l'esprit qu'avoir plusieurs instances de QOpenGLWidget dans la 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 surmonter ce problème, préférez utiliser QSurfaceFormat::setDefaultFormat() au lieu de setFormat().

Techniques de peinture

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

• Réimplémenter les fonctions initializeGL() et resizeGL() pour configurer l'état OpenGL et fournir une transformation de perspective.
• Réimplémenter paintGL() pour peindre la scène 3D, en appelant uniquement les fonctions OpenGL.

Il est également possible de dessiner des graphiques 2D sur une sous-classe de QOpenGLWidget en utilisant QPainter:

• Dans paintGL(), au lieu d'émettre des commandes OpenGL, construisez un objet QPainter à utiliser sur le widget.
• Dessinez des primitives en utilisant les fonctions membres de QPainter.
• Les commandes OpenGL directes peuvent toujours être émises. Cependant, vous devez vous assurer qu'elles sont entourées d'un appel aux fonctions beginNativePainting() et endNativePainting() du peintre.

Lorsque le dessin est effectué uniquement à l'aide de QPainter, il est également possible d'effectuer la peinture comme pour les widgets ordinaires : en réimplémentant paintEvent().

• Réimplémentez la fonction paintEvent().
• Construire un objet QPainter ciblant le widget. Passez le widget au constructeur ou à la fonction QPainter::begin().
• Dessiner des primitives à l'aide des fonctions membres de QPainter.
• La peinture est terminée et l'instance QPainter est détruite. Il est également possible d'appeler QPainter::end() explicitement.

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

Lors des appels de fonctions OpenGL, il est fortement recommandé d'éviter d'appeler les fonctions directement. A la place, préférez utiliser QOpenGLFunctions (lors de la création d'applications portables) ou les variantes versionnées (par exemple, QOpenGLFunctions_3_2_Core et similaires, lors de l'utilisation d'OpenGL moderne, uniquement pour les ordinateurs de bureau). De cette manière, l'application fonctionnera correctement dans toutes les configurations de compilation de Qt, y compris celles qui effectuent un chargement dynamique de l'implémentation OpenGL, ce qui signifie que les applications ne sont pas directement liées à une implémentation GL et que les appels directs de fonctions ne sont donc pas réalisables.

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 à être utilisée peut être récupérée en appelant QOpenGLContext::functions(). Une alternative au préfixage de chaque appel GL est d'hériter de QOpenGLFunctions et d'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 comme GL.h. Les en-têtes Qt liés à OpenGL incluront qopengl.h qui inclura à son tour un en-tête approprié pour le système. Cela peut être un en-tête OpenGL ES 3.x ou 2.0, la plus haute version disponible, ou un gl.h fourni par le système. De plus, une copie des en-têtes d'extension (appelée glext.h sur certains systèmes) est fournie dans Qt à la fois pour OpenGL et OpenGL ES. Ceux-ci seront inclus automatiquement sur les plates-formes où cela est possible. Cela signifie que les constantes et les typedefs de pointeurs de fonctions des extensions ARB, EXT, OES sont automatiquement disponibles.

Exemples de code

Pour commencer, la sous-classe la plus simple de QOpenGLWidget pourrait ressembler à ce qui suit :

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);
        ...
    }

};

Alternativement, le préfixage de chaque appel OpenGL peut être évité en dérivant de 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 les 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

Dans les contextes OpenGL 3.0+, lorsque la portabilité n'est pas importante, les variantes versionnées de QOpenGLFunctions donnent un accès facile à toutes les fonctions modernes d'OpenGL 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 robuste de définir le format demandé de manière globale afin qu'il s'applique à toutes les fenêtres et à tous les contextes pendant 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();
}

Multi-échantillonnage

Pour activer le multi-échantillonnage, définissez le nombre d'échantillons demandés dans le fichier QSurfaceFormat transmis à setFormat(). Sur les systèmes qui ne le supportent pas, la demande peut être ignorée.

La prise en charge du multi-échantillonnage nécessite la prise en charge des renderbuffers multi-échantillonnés et des blits de framebuffer. Sur les implémentations d'OpenGL ES 2.0, il est probable que ces éléments ne soient pas présents. Cela signifie que le multi-échantillonnage ne sera pas disponible. Avec les versions modernes d'OpenGL et OpenGL ES 3.0 et plus, ce n'est généralement plus un problème.

Le threading

Effectuer un rendu hors écran sur des threads de travail, par exemple pour générer des textures qui sont ensuite utilisées dans le GUI/main thread dans paintGL(), est supporté en exposant le widget QOpenGLContext de sorte que des contextes additionnels le partageant puissent être créés sur chaque thread.

Dessiner directement dans le framebuffer du QOpenGLWidget en dehors du GUI/thread principal est possible en réimplémentant paintEvent() pour ne rien faire. L'affinité du contexte avec le thread doit être modifiée via QObject::moveToThread(). Après cela, makeCurrent() et doneCurrent() sont utilisables sur le thread du travailleur. Veillez à replacer le contexte dans le thread GUI/principal par la suite.

Déclencher un échange de tampon uniquement pour le QOpenGLWidget n'est pas possible puisqu'il n'y a pas de surface native réelle à l'écran pour lui. C'est à la pile du widget de gérer la composition et les changements de tampon sur le thread de l'interface graphique. Lorsqu'un thread a fini de mettre à jour le framebuffer, appelez update() sur le thread principal de l'interface graphique pour planifier la composition.

Des précautions supplémentaires doivent être prises pour éviter d'utiliser le framebuffer lorsque le thread GUI/main est en train d'effectuer la composition. Les signaux aboutToCompose() et frameSwapped() sont émis au début et à la fin de la composition. Ils sont émis sur le fil d'exécution principal de l'interface graphique. Cela signifie qu'en utilisant une connexion directe, aboutToCompose() peut bloquer le fil d'exécution principal de l'interface graphique jusqu'à ce que le fil d'exécution de l'assistant ait terminé son rendu. Après cela, le fil d'exécution du travailleur ne doit plus effectuer de rendu jusqu'à ce que le signal frameSwapped() soit émis. Si cela n'est pas acceptable, le fil d'exécution doit mettre en œuvre un mécanisme de double mise en mémoire tampon. Cela implique de dessiner en utilisant une cible de rendu alternative, qui est entièrement contrôlée par le thread, par exemple un objet framebuffer supplémentaire, et de blitter dans le framebuffer de QOpenGLWidget à un moment approprié.

Partage du contexte

Lorsque plusieurs QOpenGLWidgets sont ajoutés en tant qu'enfants au même widget de niveau supérieur, leurs contextes seront partagés les uns avec les autres. Cela ne s'applique pas aux instances de QOpenGLWidget qui appartiennent à des fenêtres différentes.

Cela signifie que tous les QOpenGLWidgets de la même fenêtre peuvent accéder aux ressources partageables des autres, comme les textures, et qu'il n'y a pas besoin d'un contexte supplémentaire de "partage global".

Pour mettre en place le partage entre les 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 QOpenGLContext supplémentaires qui partagent des ressources comme les textures avec le contexte du QOpenGLWidget. Il suffit de passer le pointeur retourné par context() à QOpenGLContext::setShareContext() avant d'appeler QOpenGLContext::create(). Le contexte résultant peut également être utilisé dans un autre thread, ce qui permet de générer des textures de manière threadée et de télécharger des textures de manière asynchrone.

Notez que QOpenGLWidget s'attend à une implémentation standard du partage des ressources en ce qui concerne les pilotes graphiques sous-jacents. Par exemple, certains pilotes, en particulier pour le matériel mobile et embarqué, ont des problèmes avec la mise en place du partage entre un contexte existant et d'autres qui sont créés plus tard. D'autres pilotes peuvent se comporter de manière inattendue lorsqu'ils tentent d'utiliser des ressources partagées entre différents threads.

Initialisation et nettoyage des ressources

Le contexte OpenGL associé au QOpenGLWidget est garanti d'être à jour lorsque initializeGL() et paintGL() sont invoqués. N'essayez pas de créer des ressources OpenGL avant que initializeGL() ne soit appelé. Par exemple, tenter de compiler des shaders, d'initialiser des objets tampons de vertex ou de télécharger des données de texture échouera si cela est fait dans le constructeur d'une sous-classe. Ces opérations doivent être reportées à initializeGL(). Certaines des classes d'aide OpenGL de Qt, comme QOpenGLBuffer ou QOpenGLVertexArrayObject, ont un comportement différé similaire : elles peuvent être instanciées sans contexte, mais toute l'initialisation est différée jusqu'à un appel à create(), ou similaire. Cela signifie qu'elles peuvent être utilisées comme des variables membres normales (sans pointeur) dans une sous-classe de QOpenGLWidget, mais la fonction create() ou similaire ne peut être appelée qu'à partir de initializeGL(). Sachez cependant que toutes les classes ne sont pas conçues de cette manière. En cas de doute, faites de la variable membre un pointeur et créez et détruisez l'instance dynamiquement dans initializeGL() et le destructeur, respectivement.

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

Une sous-classe typique ressemblera donc souvent à ce qui suit en ce qui concerne l'initialisation et la 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 ce n'est pas une solution générique idéale. Lorsque le widget est réparti de telle sorte qu'il se retrouve dans une fenêtre de niveau supérieur complètement différente, quelque chose de plus est nécessaire : en se connectant au signal aboutToBeDestroyed() de QOpenGLContext, un 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 correct est particulièrement important en raison du partage du contexte. Même si le contexte associé à chaque QOpenGLWidget est détruit en même temps que le QOpenGLWidget, les ressources partageables dans ce contexte, comme les textures, resteront valides jusqu'à ce que la fenêtre de niveau supérieur, dans laquelle se trouvait le QOpenGLWidget, soit détruite. En outre, des paramètres tels que Qt::AA_ShareOpenGLContexts et certains modules Qt peuvent déclencher une portée encore plus large pour le partage des contextes, conduisant potentiellement à garder les ressources en question en vie pendant toute la durée de vie de l'application. Par conséquent, le plus sûr et le plus robuste est toujours d'effectuer un nettoyage explicite pour toutes les ressources et les enveloppes de ressources utilisées 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 non-OpenGL, et les solutions de type transparent ne sont donc pas réalisables. D'autres types de dispositions, comme avoir des widgets au-dessus du QOpenGLWidget, fonctionneront comme prévu.

Lorsque cela est absolument nécessaire, cette limitation peut être surmontée en définissant l'attribut Qt::WA_AlwaysStackOnTop sur le QOpenGLWidget. Sachez cependant que cela rompt l'ordre d'empilement, par exemple il ne sera pas possible d'avoir d'autres widgets au dessus du QOpenGLWidget, donc cela ne devrait être utilisé que dans des situations où un QOpenGLWidget semi-transparent avec d'autres widgets visibles en dessous est nécessaire.

Notez que cela ne s'applique pas lorsqu'il n'y a pas d'autres widgets en dessous et que l'intention est d'avoir 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, alors Qt::WA_NoSystemBackground devra être ramené à false après avoir activé Qt::WA_TranslucentBackground. De plus, demander un canal alpha pour le contexte de QOpenGLWidget via setFormat() peut aussi être nécessaire, selon le système.

QOpenGLWidget supporte plusieurs comportements de mise à jour, tout comme QOpenGLWindow. En mode préservé, le contenu rendu lors de l'appel précédent à paintGL() est disponible lors de l'appel suivant, ce qui permet un rendu incrémental. En mode non préservé, le contenu est perdu et les implémentations de paintGL() doivent redessiner tout ce qui se trouve dans la vue.

Avant Qt 5.5, le comportement par défaut de QOpenGLWidget était de préserver le contenu du rendu entre les appels à paintGL(). Depuis Qt 5.5, le comportement par défaut est la non-conservation car cela permet de meilleures performances et la majorité des applications n'ont pas besoin du contenu précédent. Cela ressemble également à la sémantique d'un QWindow basé sur OpenGL et correspond au comportement par défaut de QOpenGLWindow dans la mesure où les tampons de couleur et les tampons auxiliaires sont invalidés pour chaque image. Pour rétablir le comportement préservé, 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 nettoyé via un rendu basé sur l'OpenGL. Les widgets autres que le QOpenGLWidget continuent à dessiner leur contenu en utilisant un peintre logiciel, mais la composition finale est réalisée par l'API 3D.

Alternatives

L'ajout d'un QOpenGLWidget dans une fenêtre active la composition OpenGL pour l'ensemble de la fenêtre. Dans certains cas particuliers, cela peut ne pas être idéal, et le comportement de l'ancien QGLWidget avec une fenêtre enfant séparée et native est souhaité. Les applications de bureau qui comprennent les limites de cette approche (par exemple en ce qui concerne les chevauchements, la transparence, les vues déroulantes et les zones MDI), peuvent utiliser QOpenGLWindow avec QWidget::createWindowContainer(). C'est une alternative moderne à QGLWidget et elle est plus rapide que QOpenGLWidget en raison de l'absence d'é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 est connue pour avoir des problèmes sur certaines plateformes de bureau (par exemple macOS). La solution stable et multiplateforme est toujours QOpenGLWidget.

Rendu stéréoscopique

À partir de la version 6.5, QOpenGLWidget supporte le rendu stéréoscopique. Pour l'activer, positionnez le drapeau QSurfaceFormat::StereoBuffers globalement avant la création de la fenêtre, en utilisant QSurfaceFormat::SetDefaultFormat().

Cela déclenchera l'appel de paintGL() deux fois par image, une fois pour chaque QOpenGLWidget::TargetBuffer. Dans paintGL(), appelez currentTargetBuffer() pour demander quel est le dessin en cours.

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