QOffscreenSurface Class
La clase QOffscreenSurface representa una superficie fuera de pantalla en la plataforma subyacente. Más...
| Cabecera: | #include <QOffscreenSurface> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Hereda: | 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á pensado para ser utilizado con QOpenGLContext para permitir el renderizado con OpenGL en un hilo arbitrario sin necesidad de crear un QWindow.
Aunque la superficie es típicamente renderizable, los píxeles de la superficie no son accesibles. QOffscreenSurface sólo debe utilizarse para crear recursos OpenGL como texturas u objetos framebuffer.
Una aplicación suele utilizar QOffscreenSurface para realizar algunas tareas que consumen mucho tiempo en un subproceso separado con el fin de evitar el estancamiento del subproceso de renderizado principal. Los recursos creados en el contexto de QOffscreenSurface pueden compartirse con el contexto principal de OpenGL. Algunos casos de uso común son la carga asíncrona de texturas o el renderizado en 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 o soporta superficies fuera de pantalla, QOffscreenSurface utilizará internamente un QWindow invisible.
Nota: Debido al hecho de que QOffscreenSurface está respaldado por un QWindow en algunas plataformas, las aplicaciones multiplataforma deben asegurarse de que create() sólo se llama en el hilo principal (GUI). La QOffscreenSurface es entonces seguro para ser utilizado con makeCurrent() en otros hilos, pero la inicialización y la destrucción siempre debe ocurrir en el hilo principal (GUI).
Nota: Para crear una superficie fuera de pantalla que garantice su compatibilidad con un contexto y una ventana dados, asegúrate de establecer el formato al formato real del contexto o de la ventana, es decir, el QSurfaceFormat devuelto por QOpenGLContext::format() o QWindow::format() después de que el contexto o la ventana hayan sido creados. Pasar el formato devuelto por QWindow::requestedFormat() a setFormat() puede dar como resultado 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 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á superficie nativa subyacente. Para los casos de uso de QOffscreenSurface (renderizado a FBOs, carga de texturas) esto no es un problema.
Documentación de las funciones miembro
[explicit] QOffscreenSurface::QOffscreenSurface(QScreen *targetScreen = nullptr, QObject *parent = nullptr)
Crea una superficie fuera de pantalla para el targetScreen con el parent dado.
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 la pantalla.
void QOffscreenSurface::create()
Asigna los recursos de 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 sea llamada en el hilo principal (GUI).
Véase también destroy().
void QOffscreenSurface::destroy()
Libera los recursos nativos de la plataforma 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 actual de esta superficie fuera de pantalla.
Una vez creada la superficie fuera de pantalla, esta función devolverá el formato real de la superficie. Puede diferir del formato solicitado si la plataforma no ha podido cumplirlo.
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 dado para la superficie.
Esta función proporciona acceso a la funcionalidad específica de 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 nullptr.
QSurfaceFormat QOffscreenSurface::requestedFormat() const
Devuelve el formato de superficie solicitado para esta superficie fuera de pantalla.
Si el formato solicitado no es compatible con la implementación de la plataforma, el formato solicitado diferirá del formato real de la superficie fuera de pantalla.
Este es el valor establecido con setFormat().
Véase 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 la dirección screen de una superficie fuera de pantalla, ya sea estableciéndose explícitamente con setScreen(), o automáticamente cuando se retira la pantalla de la ventana.
void QOffscreenSurface::setFormat(const QSurfaceFormat &format)
Establece la superficie fuera de pantalla format.
El formato de la superficie se resolverá en la función create(). Llamar a esta función después de create() no volverá a resolver el formato de superficie 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 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.
