QOpenGLWindow Class
La classe QOpenGLWindow est une sous-classe de commodité de QWindow pour réaliser des peintures OpenGL. Plus d'informations...
| En-tête : | #include <QOpenGLWindow> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS OpenGL)target_link_libraries(mytarget PRIVATE Qt6::OpenGL) |
| qmake : | QT += opengl |
| Héritages : | QPaintDeviceWindow |
Types publics
| enum | UpdateBehavior { NoPartialUpdate, PartialUpdateBlit, PartialUpdateBlend } |
Fonctions publiques
| QOpenGLWindow(QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr) | |
| QOpenGLWindow(QOpenGLContext *shareContext, QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr) | |
| virtual | ~QOpenGLWindow() |
| QOpenGLContext * | context() const |
| GLuint | defaultFramebufferObject() const |
| void | doneCurrent() |
| QImage | grabFramebuffer() |
| bool | isValid() const |
| void | makeCurrent() |
| QOpenGLContext * | shareContext() const |
| QOpenGLWindow::UpdateBehavior | updateBehavior() const |
Signaux
| void | frameSwapped() |
Fonctions protégées
| virtual void | initializeGL() |
| virtual void | paintGL() |
| virtual void | paintOverGL() |
| virtual void | paintUnderGL() |
| virtual void | resizeGL(int w, int h) |
Fonctions protégées réimplémentées
| virtual void | paintEvent(QPaintEvent *event) override |
| virtual void | resizeEvent(QResizeEvent *event) override |
Description détaillée
QOpenGLWindow est une version améliorée de QWindow qui permet de créer facilement des fenêtres qui effectuent un rendu OpenGL en utilisant une API compatible avec QOpenGLWidget. Contrairement à QOpenGLWidget, QOpenGLWindow ne dépend pas du module widgets et offre de meilleures performances.
Une application typique sous-classera QOpenGLWindow et réimplémentera les fonctions virtuelles suivantes :
- initializeGL() pour initialiser les ressources OpenGL
- resizeGL() pour configurer les matrices de transformation et les autres ressources dépendantes de la taille de la fenêtre
- paintGL() pour émettre des commandes OpenGL ou dessiner à l'aide de l'interface de la fenêtre. QPainter
Pour programmer un repeint, appelez la fonction update(). Notez que cela n'entraînera pas immédiatement un appel à paintGL(). Appeler update() plusieurs fois de suite ne changera en rien le comportement.
Il s'agit d'un slot qui peut donc être connecté à un signal QChronoTimer::timeout() pour réaliser une animation. Notez cependant que dans le monde moderne d'OpenGL, il est préférable de s'appuyer sur la synchronisation avec le taux de rafraîchissement vertical de l'écran. Voir setSwapInterval() pour une description de l'intervalle de permutation. Avec un intervalle de permutation de 1, ce qui est le cas par défaut sur la plupart des systèmes, l'appel swapBuffers(), qui est exécuté en interne par QOpenGLWindow après chaque repeint, bloquera et attendra vsync. Cela signifie qu'à chaque fois que la permutation est faite, une mise à jour peut être programmée à nouveau en appelant update(), sans dépendre des timers.
Pour demander une configuration spécifique pour le contexte, utilisez setFormat() comme pour tout autre QWindow. Cela permet, entre autres, de demander une version et un profil OpenGL donnés, ou d'activer les tampons de profondeur et de pochoir.
Note : Il appartient à l'application de s'assurer que les tampons de profondeur et de stencil sont demandés à l'interface du système de fenêtrage sous-jacent. Sans demander une taille de tampon de profondeur non nulle, il n'y a aucune garantie qu'un tampon de profondeur sera disponible, et par conséquent les opérations OpenGL liées au test de profondeur peuvent ne pas fonctionner comme prévu.
Les tailles de tampon de profondeur et de stencil couramment demandées sont 24 et 8, respectivement. Par exemple, une sous-classe de QOpenGLWindow pourrait faire cela dans son constructeur :
QSurfaceFormat format; format.setDepthBufferSize(24); format.setStencilBufferSize(8); setFormat(format);
Contrairement à QWindow, QOpenGLWindow permet d'ouvrir un peintre sur lui-même et d'effectuer des dessins basés sur QPainter.
QOpenGLWindow supporte plusieurs comportements de mise à jour. Le comportement par défaut, NoPartialUpdate, est équivalent à celui d'une fenêtre ordinaire, basée sur OpenGL, QWindow. En revanche, PartialUpdateBlit et PartialUpdateBlend sont plus en ligne avec la façon de travailler de QOpenGLWidget, où il y a toujours un objet framebuffer supplémentaire dédié présent. Ces modes permettent, en sacrifiant certaines performances, de ne redessiner qu'une petite zone à chaque peinture et de conserver le reste du contenu de l'image précédente. Ceci est utile pour les applications qui effectuent un rendu incrémental à l'aide de QPainter, car elles n'ont pas à redessiner l'ensemble du contenu de la fenêtre à chaque appel à paintGL().
Comme pour QOpenGLWidget, QOpenGLWindow supporte l'attribut Qt::AA_ShareOpenGLContexts. Lorsqu'il est activé, les contextes OpenGL de toutes les instances de QOpenGLWindow sont partagés. Cela permet d'accéder aux ressources OpenGL partageables des autres.
Pour plus d'informations sur les graphiques dans Qt, voir Graphics.
Documentation sur les types de membres
enum QOpenGLWindow::UpdateBehavior
Cette énumération décrit la stratégie de mise à jour du site QOpenGLWindow.
| Constante | Valeur | Description |
|---|---|---|
QOpenGLWindow::NoPartialUpdate | 0 | Indique que toute la surface de la fenêtre sera redessinée à chaque mise à jour et qu'aucun framebuffer supplémentaire n'est donc nécessaire. C'est le paramètre utilisé dans la plupart des cas et il est équivalent à la façon dont le dessin directement via QWindow fonctionnerait. |
QOpenGLWindow::PartialUpdateBlit | 1 | Indique que le dessin effectué dans paintGL() ne couvre pas la totalité de la fenêtre. Dans ce cas, un objet framebuffer supplémentaire est créé sous le capot, et le rendu effectué dans paintGL() ciblera ce framebuffer. Ce framebuffer est ensuite intégré au framebuffer par défaut de la surface de la fenêtre après chaque peinture. Cela permet d'avoir un code de dessin basé sur QPainter dans paintGL() qui ne repeint qu'une petite zone à la fois, car, contrairement à NoPartialUpdate, le contenu précédent est préservé. |
QOpenGLWindow::PartialUpdateBlend | 2 | Similaire à PartialUpdateBlit, mais au lieu d'utiliser le framebuffer blits, le contenu du framebuffer supplémentaire est rendu en dessinant un quad texturé avec le blending activé. Contrairement à PartialUpdateBlit, cette méthode permet d'utiliser un contenu en mélange alpha et fonctionne même si le glBlitFramebuffer n'est pas disponible. Du point de vue des performances, ce paramètre sera probablement un peu plus lent que PartialUpdateBlit. |
Documentation des fonctions membres
[explicit] QOpenGLWindow::QOpenGLWindow(QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr)
Construit une nouvelle QOpenGLWindow avec les données parent et updateBehavior.
Voir aussi QOpenGLWindow::UpdateBehavior.
[explicit] QOpenGLWindow::QOpenGLWindow(QOpenGLContext *shareContext, QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr)
Construit une nouvelle QOpenGLWindow avec les données parent et updateBehavior. Le contexte de la QOpenGLWindow sera partagé avec shareContext.
Voir aussi QOpenGLWindow::UpdateBehavior et shareContext.
[virtual noexcept] QOpenGLWindow::~QOpenGLWindow()
Détruit l'instance QOpenGLWindow, en libérant ses ressources.
Le contexte de l'OpenGLWindow est mis à jour dans le destructeur, permettant une destruction sûre de tout objet enfant qui pourrait avoir besoin de libérer les ressources OpenGL appartenant au contexte fourni par cette fenêtre.
Attention : si vous avez des objets enveloppant des ressources OpenGL (comme QOpenGLBuffer, QOpenGLShaderProgram, etc.) en tant que membres d'une sous-classe QOpenGLWindow, vous pouvez avoir besoin d'ajouter un appel à makeCurrent() dans le destructeur de cette sous-classe également. En raison des règles de destruction des objets C++, ces objets seront détruits avant d' appeler cette fonction (mais après que le destructeur de la sous-classe se soit exécuté), donc rendre le contexte OpenGL courant dans cette fonction arrive trop tard pour leur permettre de se débarrasser d'eux en toute sécurité.
Voir aussi makeCurrent.
QOpenGLContext *QOpenGLWindow::context() const
Retourne le site QOpenGLContext utilisé par cette fenêtre ou 0 s'il n'a pas encore été initialisé.
GLuint QOpenGLWindow::defaultFramebufferObject() const
La poignée de l'objet framebuffer utilisé par cette fenêtre.
Lorsque le comportement de mise à jour est défini sur NoPartialUpdate, il n'y a pas d'objet framebuffer séparé. Dans ce cas, la valeur renvoyée est l'ID du framebuffer par défaut.
Sinon, la valeur de l'ID de l'objet framebuffer ou 0 s'il n'a pas encore été initialisé.
void QOpenGLWindow::doneCurrent()
Libère le contexte.
Il n'est pas nécessaire d'appeler cette fonction dans la plupart des cas, puisque le widget s'assurera que le contexte est lié et libéré correctement lors de l'invocation de paintGL().
Voir également makeCurrent().
[signal] void QOpenGLWindow::frameSwapped()
Ce signal est émis après l'exécution de buffer swap, qui peut être bloquante. Les applications qui souhaitent repeindre continuellement en synchronisation avec le rafraîchissement vertical doivent émettre un signal update() à ce moment-là. Cela permet une expérience beaucoup plus fluide que l'utilisation traditionnelle de temporisateurs.
QImage QOpenGLWindow::grabFramebuffer()
Renvoie une copie du framebuffer.
Remarque : il s'agit d'une opération potentiellement coûteuse car elle repose sur glReadPixels() pour relire les pixels. Cette opération peut être lente et bloquer le pipeline du GPU.
Remarque : lorsqu'elle est utilisée avec le comportement update NoPartialUpdate, l'image renvoyée peut ne pas contenir le contenu souhaité si elle est appelée après que les tampons avant et arrière ont été échangés (à moins que l'échange préservé ne soit activé dans l'interface du système de fenêtrage sous-jacent). Dans ce mode, la fonction lit à partir du tampon arrière et le contenu de celui-ci peut ne pas correspondre au contenu de l'écran (le tampon avant). Dans ce cas, le seul endroit où cette fonction peut être utilisée en toute sécurité est paintGL() ou paintOverGL().
[virtual protected] void QOpenGLWindow::initializeGL()
Cette fonction virtuelle est appelée une fois avant le premier appel à paintGL() ou resizeGL(). Réimplémentez-la dans une sous-classe.
Cette fonction devrait mettre en place toutes les ressources et états OpenGL nécessaires.
Il n'est pas nécessaire d'appeler makeCurrent() car cela a déjà été fait lorsque cette fonction est appelée. Notez cependant que le framebuffer, dans le cas où le mode de mise à jour partielle est utilisé, n'est pas encore disponible à ce stade, donc évitez d'émettre des appels de dessin à partir d'ici. Reportez plutôt ces appels à paintGL().
Voir aussi paintGL() et resizeGL().
bool QOpenGLWindow::isValid() const
Retourne true si les ressources OpenGL de la fenêtre, comme le contexte, ont été initialisées avec succès. Notez que la valeur de retour est toujours false jusqu'à ce que la fenêtre soit exposée (affichée).
void QOpenGLWindow::makeCurrent()
Prépare le rendu du contenu OpenGL pour cette fenêtre en rendant le contexte correspondant actuel et en liant l'objet framebuffer, s'il y en a un, dans ce contexte.
Il n'est pas nécessaire d'appeler cette fonction dans la plupart des cas, car elle est appelée automatiquement avant d'invoquer paintGL(). Elle est néanmoins fournie pour prendre en charge les scénarios avancés et multithreads dans lesquels un thread différent du GUI ou du thread principal peut vouloir mettre à jour la surface ou le contenu du framebuffer. Voir QOpenGLContext pour plus d'informations sur les questions liées au threading.
Cette fonction peut être appelée même lorsque la fenêtre de la plate-forme sous-jacente est déjà détruite. Cela signifie qu'il est possible d'appeler cette fonction à partir du destructeur d'une sous-classe de QOpenGLWindow. S'il n'y a plus de fenêtre native, une surface hors écran est utilisée à la place. Cela garantit que les opérations de nettoyage des ressources OpenGL dans le destructeur fonctionneront toujours, tant que cette fonction est appelée en premier.
Voir aussi QOpenGLContext, context(), paintGL(), et doneCurrent().
[override virtual protected] void QOpenGLWindow::paintEvent(QPaintEvent *event)
Réimplémente : QPaintDeviceWindow::paintEvent(QPaintEvent *event).
Gestionnaire de peinture event. Appelle paintGL().
Voir également paintGL().
[virtual protected] void QOpenGLWindow::paintGL()
Cette fonction virtuelle est appelée chaque fois que le contenu de la fenêtre doit être peint. Réimplémentez-la dans une sous-classe.
Il n'est pas nécessaire d'appeler makeCurrent() car cela a déjà été fait lorsque cette fonction est appelée.
Avant d'invoquer cette fonction, le contexte et le framebuffer, s'il y en a un, sont liés, et la fenêtre est configurée par un appel à glViewport(). Aucun autre état n'est défini et aucun effacement ou dessin n'est effectué par le cadre.
Remarque : lors de l'utilisation d'un comportement de mise à jour partielle, comme PartialUpdateBlend, le résultat de l'appel précédent à paintGL() est préservé et, après le dessin supplémentaire effectué dans l'invocation actuelle de la fonction, le contenu est estompé ou fondu sur le contenu dessiné directement sur la fenêtre dans paintUnderGL().
Voir également initializeGL(), resizeGL(), paintUnderGL(), paintOverGL() et UpdateBehavior.
[virtual protected] void QOpenGLWindow::paintOverGL()
Cette fonction virtuelle est appelée après chaque invocation de paintGL().
Lorsque le mode de mise à jour est défini sur NoPartialUpdate, il n'y a pas de différence entre cette fonction et paintGL(), l'exécution du rendu dans l'une ou l'autre conduit au même résultat.
Comme pour paintUnderGL(), le rendu dans cette fonction cible le framebuffer par défaut de la fenêtre, quel que soit le comportement de mise à jour. Elle est appelée après le retour de paintGL() et la réalisation du blit (PartialUpdateBlit) ou du dessin quadratique (PartialUpdateBlend).
Voir aussi paintGL(), paintUnderGL() et UpdateBehavior.
[virtual protected] void QOpenGLWindow::paintUnderGL()
La fonction virtuelle est appelée avant chaque invocation de paintGL().
Lorsque le mode de mise à jour est défini sur NoPartialUpdate, il n'y a pas de différence entre cette fonction et paintGL(), l'exécution du rendu dans l'une ou l'autre conduit au même résultat.
La différence devient significative lors de l'utilisation de PartialUpdateBlend, où un objet framebuffer supplémentaire est utilisé. Dans ce cas, paintGL() cible cet objet framebuffer supplémentaire, qui préserve son contenu, tandis que paintUnderGL() et paintOverGL() ciblent le framebuffer par défaut, c'est-à-dire directement la surface de la fenêtre, dont le contenu est perdu après chaque image affichée.
Note : Evitez de vous fier à cette fonction lorsque le comportement de mise à jour est PartialUpdateBlit. Ce mode implique le blitting du framebuffer supplémentaire utilisé par paintGL() sur le framebuffer par défaut après chaque invocation de paintGL(), écrasant ainsi tous les dessins générés dans cette fonction.
Voir également paintGL(), paintOverGL() et UpdateBehavior.
[override virtual protected] void QOpenGLWindow::resizeEvent(QResizeEvent *event)
Réimplémente : QWindow::resizeEvent(QResizeEvent *ev).
Gestionnaire de redimensionnement event. Appelle resizeGL().
Voir également resizeGL().
[virtual protected] void QOpenGLWindow::resizeGL(int w, int h)
Cette fonction virtuelle est appelée chaque fois que le widget a été redimensionné. Réimplémentez-la dans une sous-classe. La nouvelle taille est transmise dans w et h.
Remarque : il s'agit simplement d'une fonction de commodité permettant de fournir une API compatible avec QOpenGLWidget. Contrairement à QOpenGLWidget, les classes dérivées sont libres de choisir de surcharger resizeEvent() au lieu de cette fonction.
Note : Evitez d'émettre des commandes OpenGL à partir de cette fonction car il se peut qu'il n'y ait pas de contexte courant lorsqu'elle est invoquée. Si cela ne peut être évité, appelez makeCurrent().
Remarque : il n'est pas nécessaire de programmer des mises à jour à partir de cette fonction. Les systèmes de fenêtrage enverront des événements d'exposition qui déclencheront automatiquement une mise à jour.
Voir également initializeGL() et paintGL().
QOpenGLContext *QOpenGLWindow::shareContext() const
Renvoie l'adresse QOpenGLContext demandée pour être partagée avec l'adresse QOpenGLContext de cette fenêtre.
QOpenGLWindow::UpdateBehavior QOpenGLWindow::updateBehavior() const
Renvoie le comportement de mise à jour pour cette QOpenGLWindow.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
