QOffscreenSurface Class
Die Klasse „QOffscreenSurface“ repräsentiert eine Offscreen-Oberfläche auf der zugrunde liegenden Plattform. Mehr...
| Header: | #include <QOffscreenSurface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Erbt von: | QObject und QSurface |
Öffentliche Funktionen
| 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) |
Neu implementierte öffentliche Funktionen
| virtual QSurfaceFormat | format() const override |
| virtual QSize | size() const override |
| virtual QSurface::SurfaceType | surfaceType() const override |
Signale
| void | screenChanged(QScreen *screen) |
Ausführliche Beschreibung
QOffscreenSurface ist für die Verwendung mit „ QOpenGLContext “ vorgesehen, um das Rendern mit OpenGL in einem beliebigen Thread zu ermöglichen, ohne dass ein „ QWindow “ erstellt werden muss.
Obwohl die Oberfläche in der Regel renderbar ist, sind die Pixel der Oberfläche nicht zugänglich. QOffscreenSurface sollte ausschließlich zum Erstellen von OpenGL-Ressourcen wie Texturen oder Framebuffer-Objekten verwendet werden.
Eine Anwendung nutzt QOffscreenSurface in der Regel, um zeitaufwändige Aufgaben in einem separaten Thread auszuführen und so ein Blockieren des Haupt-Rendering-Threads zu vermeiden. Im Kontext von QOffscreenSurface erstellte Ressourcen können mit dem Haupt-OpenGL-Kontext gemeinsam genutzt werden. Häufige Anwendungsfälle sind das asynchrone Hochladen von Texturen oder das Rendern in ein „ QOpenGLFramebufferObject “.
Die Implementierung der Offscreen-Oberfläche hängt von der zugrunde liegenden Plattform ab, erfolgt jedoch in der Regel mithilfe eines Pixelpuffers (pbuffer). Falls die Plattform keine Offscreen-Oberflächen implementiert oder unterstützt, verwendet `QOffscreenSurface` intern einen unsichtbaren ` QWindow `.
Hinweis: Da QOffscreenSurface auf einigen Plattformen auf einer „ QWindow “ basiert, müssen plattformübergreifende Anwendungen sicherstellen, dass „ create()“ ausschließlich im Haupt- (GUI-)Thread aufgerufen wird. Die `QOffscreenSurface` kann dann problemlos mit ` makeCurrent()` in anderen Threads verwendet werden, doch die Initialisierung und Freigabe müssen stets im Haupt- (GUI-)Thread erfolgen.
Hinweis: Um eine Offscreen-Oberfläche zu erstellen, die garantiert mit einem bestimmten Kontext und Fenster kompatibel ist, stellen Sie sicher, dass das Format auf das tatsächliche Format des Kontexts oder des Fensters gesetzt wird, d. h. auf den Wert ` QSurfaceFormat `, der von ` QOpenGLContext::format()` oder ` QWindow::format()` nach der Erstellung des Kontexts oder Fensters zurückgegeben wird. Die Übergabe des von ` QWindow::requestedFormat()` zurückgegebenen Formats an ` setFormat()` kann zu einer inkompatiblen Offscreen-Oberfläche führen, da die zugrunde liegende Schnittstelle des Fenstersystems möglicherweise unterschiedliche Konfigurationen für Fenster- und Pbuffer-Oberflächen bereitstellt.
Hinweis: Einige Plattformen nutzen möglicherweise eine Erweiterung für kontextlose Oberflächen (z. B. EGL_KHR_surfaceless_context), sofern diese verfügbar ist. In diesem Fall gibt es keine zugrunde liegende native Oberfläche. Für die Anwendungsfälle von `QOffscreenSurface` (Rendering in FBOs, Textur-Upload) stellt dies kein Problem dar.
Dokumentation der Mitgliedsfunktionen
[explicit] QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr)
Erstellt eine Offscreen-Oberfläche für die „ targetScreen “ mit der angegebenen „ parent “.
Die zugrunde liegende Plattformoberfläche wird erst erstellt, wenn create() aufgerufen wird.
Siehe auch ` setScreen()` und ` create()`.
[virtual noexcept] QOffscreenSurface::~QOffscreenSurface()
Löscht die Fläche außerhalb des Bildschirms.
void QOffscreenSurface::create()
Weist die mit der Offscreen-Oberfläche verbundenen Plattformressourcen zu.
An dieser Stelle wird das mit ` setFormat()` festgelegte Oberflächenformat in eine tatsächliche native Oberfläche aufgelöst.
Rufen Sie bei Bedarf ` destroy()` auf, um die Plattformressourcen freizugeben.
Hinweis: Bei einigen Plattformen muss diese Funktion im Haupt- (GUI-)Thread aufgerufen werden.
Siehe auch ` destroy()`.
void QOffscreenSurface::destroy()
Gibt die nativen Plattformressourcen frei, die mit dieser Offscreen-Oberfläche verbunden sind.
Siehe auch „ create()“.
[override virtual] QSurfaceFormat QOffscreenSurface::format() const
Implementiert neu: ` QSurface::format()` const.
Gibt das tatsächliche Format dieser Offscreen-Oberfläche zurück.
Nachdem die Offscreen-Oberfläche erstellt wurde, gibt diese Funktion das tatsächliche Oberflächenformat der Oberfläche zurück. Es kann vom angeforderten Format abweichen, wenn das angeforderte Format von der Plattform nicht erfüllt werden konnte.
Siehe auch setFormat(), create() und requestedFormat().
bool QOffscreenSurface::isValid() const
Gibt „ true “ zurück, wenn diese Offscreen-Oberfläche gültig ist; andernfalls wird „ false “ zurückgegeben.
Die Offscreen-Oberfläche ist gültig, wenn die Plattformressourcen erfolgreich zugewiesen wurden.
Siehe auch create().
template <typename QNativeInterface> QNativeInterface *QOffscreenSurface::nativeInterface() const
Gibt eine native Schnittstelle des angegebenen Typs für die Oberfläche zurück.
Diese Funktion ermöglicht den Zugriff auf plattformspezifische Funktionen von `QOffScreenSurface`, wie im Namespace ` QNativeInterface ` definiert:
Native Schnittstelle zu einer Offscreen-Oberfläche unter Android |
Ist die angeforderte Schnittstelle nicht verfügbar, wird ein ` nullptr ` zurückgegeben.
QSurfaceFormat QOffscreenSurface::requestedFormat() const
Gibt das angeforderte Oberflächenformat dieser Offscreen-Oberfläche zurück.
Wenn das angeforderte Format von der Plattformimplementierung nicht unterstützt wurde, weicht das „requestedFormat“ vom tatsächlichen Offscreen-Oberflächenformat ab.
Dies ist der Wert, der mit ` setFormat()` festgelegt wurde.
Siehe auch „ setFormat()“ und „ format()“.
QScreen *QOffscreenSurface::screen() const
Gibt den Bildschirm zurück, mit dem die Offscreen-Oberfläche verbunden ist.
Siehe auch „ setScreen()“.
[signal] void QOffscreenSurface::screenChanged(QScreen *screen)
Dieses Signal wird ausgelöst, wenn sich die Eigenschaft „ screen “ einer Offscreen-Oberfläche ändert – entweder durch explizite Festlegung mit ` setScreen()` oder automatisch, wenn der Bildschirm des Fensters entfernt wird.
void QOffscreenSurface::setFormat(const QSurfaceFormat &format)
Legt die Offscreen-Oberfläche fest: format.
Das Oberflächenformat wird in der Funktion ` create()` ermittelt. Ein Aufruf dieser Funktion nach ` create()` führt nicht zu einer erneuten Ermittlung des Oberflächenformats der nativen Oberfläche.
Siehe auch „ format()“, „ create()“ und „ destroy()“.
void QOffscreenSurface::setScreen(QScreen *newScreen)
Legt den Bildschirm fest, mit dem die Offscreen-Oberfläche verbunden ist.
Wenn die Offscreen-Oberfläche bereits erstellt wurde, wird sie auf dem „ newScreen “ neu erstellt.
Siehe auch „ screen()“.
[override virtual] QSize QOffscreenSurface::size() const
Implementiert neu: ` QSurface::size()` const.
Gibt die Größe der Offscreen-Oberfläche zurück.
[override virtual] QSurface::SurfaceType QOffscreenSurface::surfaceType() const
Implementiert neu: ` QSurface::surfaceType()` const.
Gibt den Oberflächentyp der Offscreen-Oberfläche zurück.
Der Oberflächentyp einer Offscreen-Oberfläche ist immer ` 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.
