QOffscreenSurface Class
La clase `QOffscreenSurface` representa una superficie fuera de pantalla en la plataforma subyacente. Más información...
| Encabezado: | #include <QOffscreenSurface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Heredado de: | QObject y QSurface |
Funciones públicas
| 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) |
Funciones públicas reimplementadas
| virtual QSurfaceFormat | format() const override |
| virtual QSize | size() const override |
| virtual QSurface::SurfaceType | surfaceType() const override |
Señales
| void | screenChanged(QScreen *screen) |
Descripción detallada
QOffscreenSurface está pensada para utilizarse junto con ` QOpenGLContext `, con el fin de permitir el renderizado con OpenGL en un hilo arbitrario sin necesidad de crear un ` QWindow`.
Aunque la superficie suele ser renderizable, no se puede acceder a sus píxeles. QOffscreenSurface solo debe utilizarse para crear recursos de OpenGL, como texturas u objetos de búfer de fotogramas.
Normalmente, una aplicación utilizará QOffscreenSurface para realizar algunas tareas que requieren mucho tiempo en un hilo independiente, con el fin de evitar que se bloquee el hilo principal de renderizado. Los recursos creados en el contexto de QOffscreenSurface pueden compartirse con el contexto principal de OpenGL. Algunos casos de uso habituales son las cargas asíncronas de texturas o el renderizado en un ` QOpenGLFramebufferObject`.
La forma en que se implementa la superficie fuera de pantalla depende de la plataforma subyacente, pero normalmente utilizará un búfer de píxeles (pbuffer). Si la plataforma no implementa ni admite superficies fuera de pantalla, QOffscreenSurface utilizará internamente un « QWindow » invisible.
Nota: Dado que, en algunas plataformas, QOffscreenSurface se basa en un QWindow, las aplicaciones multiplataforma deben asegurarse de que create() solo se llame en el hilo principal (GUI). De este modo, QOffscreenSurface puede utilizarse con seguridad con makeCurrent() en otros subprocesos, pero la inicialización y la destrucción deben realizarse siempre en el subproceso principal (GUI).
Nota: Para crear una superficie fuera de pantalla que sea compatible con un contexto y una ventana determinados, asegúrate de establecer el formato en el formato real del contexto o de la ventana, es decir, el objeto ` QSurfaceFormat ` devuelto por ` QOpenGLContext::format()` o ` QWindow::format()` tras la creación del contexto o la ventana. Pasar el formato devuelto por QWindow::requestedFormat() a setFormat() puede dar lugar a una superficie fuera de pantalla incompatible, ya que la interfaz del sistema de ventanas subyacente puede ofrecer un conjunto diferente de configuraciones para las superficies de ventana y de pbuffer.
Nota: Algunas plataformas pueden utilizar una extensión de contexto sin superficie (por ejemplo, EGL_KHR_surfaceless_context) cuando esté disponible. En este caso, no habrá ninguna superficie nativa subyacente. Para los casos de uso de QOffscreenSurface (renderizado a FBO, carga de texturas), esto no supone ningún problema.
Documentación de las funciones miembro
[explicit] QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr)
Crea una superficie fuera de pantalla para la ` targetScreen ` con el ` parent` indicado.
La superficie de la plataforma subyacente no se crea hasta que se llama a create().
Véase también setScreen() y create().
[virtual noexcept] QOffscreenSurface::~QOffscreenSurface()
Destruye la superficie fuera de pantalla.
void QOffscreenSurface::create()
Asigna los recursos de la plataforma asociados a la superficie fuera de pantalla.
Es en este momento cuando el formato de superficie establecido mediante ` setFormat()` se resuelve en una superficie nativa real.
Llama a ` destroy()` para liberar los recursos de la plataforma si es necesario.
Nota: Algunas plataformas requieren que esta función se llame en el hilo principal (GUI).
Véase también destroy().
void QOffscreenSurface::destroy()
Libera los recursos de la plataforma nativa asociados a esta superficie fuera de pantalla.
Véase también create().
[override virtual] QSurfaceFormat QOffscreenSurface::format() const
Reimplementa: ` QSurface::format()` const.
Devuelve el formato real de esta superficie fuera de pantalla.
Una vez creada la superficie fuera de pantalla, esta función devolverá el formato real de la superficie. Este podría diferir del formato solicitado si la plataforma no pudiera satisfacer dicho formato.
Véase también setFormat(), create() y requestedFormat().
bool QOffscreenSurface::isValid() const
Devuelve ` true ` si esta superficie fuera de pantalla es válida; en caso contrario, devuelve ` false`.
La superficie fuera de pantalla es válida si los recursos de la plataforma se han asignado correctamente.
Véase también create().
template <typename QNativeInterface> QNativeInterface *QOffscreenSurface::nativeInterface() const
Devuelve una interfaz nativa del tipo indicado para la superficie.
Esta función proporciona acceso a la funcionalidad específica de la plataforma de QOffScreenSurface, tal y como se define en el espacio de nombres QNativeInterface:
Interfaz nativa para una superficie fuera de pantalla en Android |
Si la interfaz solicitada no está disponible, se devuelve un objeto ` nullptr `.
QSurfaceFormat QOffscreenSurface::requestedFormat() const
Devuelve el formato de superficie solicitado de esta superficie fuera de pantalla.
Si la implementación de la plataforma no admite el formato solicitado, el «requestedFormat» diferirá del formato real de la superficie fuera de pantalla.
Este es el valor establecido con ` setFormat()`.
Véanse también setFormat() y format().
QScreen *QOffscreenSurface::screen() const
Devuelve la pantalla a la que está conectada la superficie fuera de pantalla.
Véase también setScreen().
[signal] void QOffscreenSurface::screenChanged(QScreen *screen)
Esta señal se emite cuando cambia el valor de « screen » de una superficie fuera de pantalla, ya sea al establecerlo explícitamente con « setScreen()», o de forma automática cuando se elimina la pantalla de la ventana.
void QOffscreenSurface::setFormat(const QSurfaceFormat &format)
Establece la superficie fuera de pantalla format.
El formato de la superficie se determinará en la función create(). Llamar a esta función después de create() no volverá a determinar el formato de la superficie nativa.
Véase también format(), create() y destroy().
void QOffscreenSurface::setScreen(QScreen *newScreen)
Establece la pantalla a la que está conectada la superficie fuera de pantalla.
Si se ha creado la superficie fuera de pantalla, se volverá a crear en la newScreen.
Véase también screen().
[override virtual] QSize QOffscreenSurface::size() const
Reimplementa: ` QSurface::size()` const.
Devuelve el tamaño de la superficie fuera de pantalla.
[override virtual] QSurface::SurfaceType QOffscreenSurface::surfaceType() const
Reimplementa: ` QSurface::surfaceType()` const.
Devuelve el tipo de superficie de la superficie fuera de pantalla.
El tipo de superficie de una superficie fuera de pantalla es siempre ` 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.