QOffscreenSurface Class
La classe QOffscreenSurface représente une surface hors écran dans la plate-forme sous-jacente. Plus d'informations...
| En-tête : | #include <QOffscreenSurface> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake : | QT += gui |
| Hérite : | 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 qu'il soit nécessaire de créer un QWindow.
Même si la surface peut être rendue, ses pixels ne sont pas accessibles. QOffscreenSurface ne doit être utilisé que pour créer des ressources OpenGL telles que des textures ou des objets framebuffer.
Une application utilisera généralement QOffscreenSurface pour effectuer certaines tâches fastidieuses dans un thread séparé 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. Les cas d'utilisation les plus courants sont le téléchargement asynchrone de textures ou le rendu dans un site QOpenGLFramebufferObject.
La manière dont la surface hors écran est implémentée 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 une surface invisible QWindow.
Remarque : étant donné que QOffscreenSurface est soutenue par QWindow sur certaines plates-formes, les applications multiplateformes doivent s'assurer que create() n'est appelé que sur le thread principal (GUI). La QOffscreenSurface peut alors être utilisée en toute sécurité avec makeCurrent() sur d'autres threads, mais l'initialisation et la destruction doivent toujours avoir lieu sur le thread principal (GUI).
Remarque : pour 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 au format réel du contexte ou de la fenêtre, c'est-à-dire au format QSurfaceFormat renvoyé par QOpenGLContext::format() ou QWindow::format() après la création du contexte ou de la fenêtre. Transmettre 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-jacent peut offrir un ensemble différent de configurations pour les surfaces de fenêtre et de pbuffer.
Note : 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 les FBO, télé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 le targetScreen avec le parent donné.
La surface de la plate-forme sous-jacente n'est pas créée tant que create() n'est pas appelé.
Voir également setScreen() et create().
[virtual noexcept] QOffscreenSurface::~QOffscreenSurface()
Détruit la surface hors écran.
void QOffscreenSurface::create()
Alloue les ressources de la plate-forme associées à la surface hors écran.
C'est à ce stade que le format de surface défini à l'aide de setFormat() est résolu en une surface native réelle.
Appelez destroy() pour libérer les ressources de la plate-forme 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 de la plate-forme native associées à cette surface hors écran.
Voir également create().
[override virtual] QSurfaceFormat QOffscreenSurface::format() const
Réimplémente : QSurface::format() const.
Renvoie le format actuel de cette surface hors écran.
Après la création de la surface hors écran, cette fonction renvoie le format réel de la surface. Il peut différer du format demandé si ce dernier n'a pas pu être respecté 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 donné pour la surface.
Cette fonction permet d'accéder aux fonctionnalités spécifiques à la plate-forme de QOffScreenSurface, telles que définies dans l'espace de noms QNativeInterface:
Interface native d'une surface hors écran sur Android |
Si l'interface demandée n'est pas disponible, une adresse 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é sera différent du format réel de la surface hors écran.
Il s'agit de la valeur définie avec 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'adresse screen d'une surface hors écran change, soit parce qu'elle a été définie explicitement avec setScreen(), soit automatiquement lorsque l'écran de la fenêtre est supprimé.
void QOffscreenSurface::setFormat(const QSurfaceFormat &format)
Définit la surface hors écran format.
Le format de la surface sera résolu dans la fonction create(). L'appel à cette fonction après create() ne résoudra 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 connectée.
Si la surface hors écran a été créée, elle sera recréée sur le site 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.
