QOffscreenSurface Class
La classe `QOffscreenSurface` représente une surface hors écran sur la plateforme sous-jacente. En savoir plus...
| En-tête : | #include <QOffscreenSurface> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake : | QT += gui |
| Hérite de : | QObject et QSurface |
Fonctions publiques
| QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr) | |
| virtual | ~QOffscreenSurface() |
| void | create() |
| void | destroy() |
| bool | isValid() const |
| QNativeInterface * | nativeInterface() const |
| QSurfaceFormat | requestedFormat() const |
| QScreen * | screen() const |
| void | setFormat(const QSurfaceFormat &format) |
| void | setScreen(QScreen *newScreen) |
Fonctions publiques réimplémentées
| virtual QSurfaceFormat | format() const override |
| virtual QSize | size() const override |
| virtual QSurface::SurfaceType | surfaceType() const override |
Signaux
| void | screenChanged(QScreen *screen) |
Description détaillée
QOffscreenSurface est destinée à être utilisée avec QOpenGLContext pour permettre le rendu avec OpenGL dans un thread arbitraire sans avoir à créer d'QWindow.
Même si la surface est généralement rendable, ses pixels ne sont pas accessibles. QOffscreenSurface ne doit être utilisée que pour créer des ressources OpenGL telles que des textures ou des objets de tampon de trame.
Une application utilise généralement QOffscreenSurface pour effectuer des tâches chronophages dans un thread distinct afin d’éviter de bloquer le thread de rendu principal. Les ressources créées dans le contexte de QOffscreenSurface peuvent être partagées avec le contexte OpenGL principal. Parmi les cas d’utilisation courants, on peut citer les chargements asynchrones de textures ou le rendu dans une surface hors écran ( QOpenGLFramebufferObject).
La mise en œuvre de la surface hors écran dépend de la plateforme sous-jacente, mais elle utilise généralement un tampon de pixels (pbuffer). Si la plateforme n’implémente pas ou ne prend pas en charge les surfaces hors écran, QOffscreenSurface utilisera en interne un « QWindow » invisible.
Remarque : étant donné que QOffscreenSurface s’appuie sur une surface hors écran ( QWindow ) sur certaines plateformes, les applications multiplateformes doivent s’assurer que la fonction ` create()` n’est appelée que sur le thread principal (GUI). La QOffscreenSurface peut alors être utilisée en toute sécurité avec la fonction ` makeCurrent()` sur d’autres threads, mais l’initialisation et la destruction doivent toujours s’effectuer sur le thread principal (GUI).
Remarque : afin de créer une surface hors écran dont la compatibilité avec un contexte et une fenêtre donnés est garantie, veillez à définir le format sur le format réel du contexte ou de la fenêtre, c'est-à-dire l'QSurfaceFormat renvoyé par QOpenGLContext::format() ou QWindow::format() après la création du contexte ou de la fenêtre. Le fait de passer le format renvoyé par QWindow::requestedFormat() à setFormat() peut entraîner une surface hors-écran incompatible, car l’interface du système de fenêtrage sous-jacente peut proposer un ensemble différent de configurations pour les surfaces de fenêtre et de pbuffer.
Remarque : certaines plateformes peuvent utiliser une extension de contexte sans surface (par exemple EGL_KHR_surfaceless_context) lorsqu’elle est disponible. Dans ce cas, il n’y aura pas de surface native sous-jacente. Pour les cas d’utilisation de QOffscreenSurface (rendu vers des FBO, chargement de textures), cela ne pose pas de problème.
Documentation des fonctions membres
[explicit] QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr)
Crée une surface hors écran pour l'targetScreen, avec l'parent spécifiée.
La surface de la plateforme sous-jacente n'est créée qu'au moment de l'appel de la fonction create().
Voir également setScreen() et create().
[virtual noexcept] QOffscreenSurface::~QOffscreenSurface()
Supprime la surface hors écran.
void QOffscreenSurface::create()
Alloue les ressources de la plateforme associées à la surface hors écran.
C'est à ce stade que le format de surface défini à l'aide de la fonction setFormat() est converti en une surface native réelle.
Appelez la fonction ` destroy()` pour libérer les ressources de la plateforme si nécessaire.
Remarque : certaines plateformes exigent que cette fonction soit appelée sur le thread principal (GUI).
Voir également destroy().
void QOffscreenSurface::destroy()
Libère les ressources natives de la plateforme associées à cette surface hors écran.
Voir également create().
[override virtual] QSurfaceFormat QOffscreenSurface::format() const
Réimplémente : ` QSurface::format()` const.
Renvoie le format réel de cette surface hors écran.
Une fois la surface hors écran créée, cette fonction renvoie le format réel de cette surface. Celui-ci peut différer du format demandé si ce dernier n’a pas pu être pris en charge par la plate-forme.
Voir également setFormat(), create() et requestedFormat().
bool QOffscreenSurface::isValid() const
Renvoie « true » si cette surface hors écran est valide ; sinon, renvoie « false ».
La surface hors écran est valide si les ressources de la plate-forme ont été allouées avec succès.
Voir également create().
template <typename QNativeInterface> QNativeInterface *QOffscreenSurface::nativeInterface() const
Renvoie une interface native du type spécifié pour la surface.
Cette fonction permet d'accéder aux fonctionnalités spécifiques à la plateforme de QOffScreenSurface, telles que définies dans l'espace de noms QNativeInterface:
Interface native vers une surface hors écran sur Android |
Si l'interface demandée n'est pas disponible, une valeur de type ` nullptr ` est renvoyée.
QSurfaceFormat QOffscreenSurface::requestedFormat() const
Renvoie le format de surface demandé pour cette surface hors écran.
Si le format demandé n'est pas pris en charge par l'implémentation de la plate-forme, le format demandé (requestedFormat) sera différent du format réel de la surface hors écran.
Il s'agit de la valeur définie avec la fonction setFormat().
Voir également setFormat() et format().
QScreen *QOffscreenSurface::screen() const
Renvoie l'écran auquel la surface hors écran est connectée.
Voir également setScreen().
[signal] void QOffscreenSurface::screenChanged(QScreen *screen)
Ce signal est émis lorsque l'screen e d'une surface hors écran change, soit parce qu'elle a été définie explicitement à l'aide de la fonction ` setScreen()`, soit automatiquement lorsque la fenêtre est retirée de l'écran.
void QOffscreenSurface::setFormat(const QSurfaceFormat &format)
Définit la surface hors écran format.
Le format de la surface sera déterminé dans la fonction ` create()`. L'appel de cette fonction après ` create()` ne redéfinira pas le format de la surface native.
Voir également format(), create() et destroy().
void QOffscreenSurface::setScreen(QScreen *newScreen)
Définit l'écran auquel la surface hors écran est associée.
Si la surface hors écran a été créée, elle sera recréée sur la surface « newScreen ».
Voir également screen().
[override virtual] QSize QOffscreenSurface::size() const
Réimplémente : QSurface::size() const.
Renvoie la taille de la surface hors écran.
[override virtual] QSurface::SurfaceType QOffscreenSurface::surfaceType() const
Réimplémente : ` QSurface::surfaceType()` const.
Renvoie le type de surface de la surface hors écran.
Le type de surface d'une surface hors écran est toujours « QSurface::OpenGLSurface ».
© 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.
