QOpenGLWindow Class
La clase `QOpenGLWindow` es una subclase de conveniencia de ` QWindow ` que permite realizar operaciones de dibujo con OpenGL. Más información...
| Encabezado: | #include <QOpenGLWindow> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS OpenGL) target_link_libraries(mytarget PRIVATE Qt6::OpenGL) |
| qmake: | QT += opengl |
| Heredan: | QPaintDeviceWindow |
Tipos públicos
| enum | UpdateBehavior { NoPartialUpdate, PartialUpdateBlit, PartialUpdateBlend } |
Funciones públicas
| QOpenGLWindow(QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr) | |
| QOpenGLWindow(QOpenGLContext *shareContext, QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr) | |
| virtual | ~QOpenGLWindow() |
| QOpenGLContext * | context() const |
| GLuint | defaultFramebufferObject() const |
| void | doneCurrent() |
| QImage | grabFramebuffer() |
| bool | isValid() const |
| void | makeCurrent() |
| QOpenGLContext * | shareContext() const |
| QOpenGLWindow::UpdateBehavior | updateBehavior() const |
Señales
| void | frameSwapped() |
Funciones protegidas
| virtual void | initializeGL() |
| virtual void | paintGL() |
| virtual void | paintOverGL() |
| virtual void | paintUnderGL() |
| virtual void | resizeGL(int w, int h) |
Funciones protegidas reimplementadas
| virtual void | paintEvent(QPaintEvent *event) override |
| virtual void | resizeEvent(QResizeEvent *event) override |
Descripción detallada
QOpenGLWindow es una versión mejorada de ` QWindow ` que permite crear fácilmente ventanas que realizan renderizado OpenGL utilizando una API compatible con QOpenGLWidget. A diferencia de QOpenGLWidget, QOpenGLWindow no depende del módulo de widgets y ofrece un mejor rendimiento.
Una aplicación típica creará una subclase de QOpenGLWindow y reimplementará las siguientes funciones virtuales:
- initializeGL() para inicializar los recursos de OpenGL
- resizeGL() para configurar las matrices de transformación y otros recursos dependientes del tamaño de la ventana
- paintGL() para emitir comandos de OpenGL o dibujar utilizando QPainter
Para programar un redibujado, llama a la función update(). Ten en cuenta que esto no provocará inmediatamente una llamada a paintGL(). Llamar a update() varias veces seguidas no cambiará el comportamiento en absoluto.
Se trata de una ranura, por lo que puede conectarse a una señal de ` QChronoTimer::timeout()` para realizar animaciones. Sin embargo, ten en cuenta que, en el mundo actual de OpenGL, es mucho mejor optar por sincronizarse con la frecuencia de refresco vertical de la pantalla. Consulta ` setSwapInterval()` para obtener una descripción del intervalo de intercambio. Con un intervalo de intercambio de 1, que es el valor predeterminado en la mayoría de los sistemas, la llamada a ` swapBuffers()`, que QOpenGLWindow ejecuta internamente tras cada repintado, se bloqueará y esperará a la sincronización vertical (vsync). Esto significa que, cada vez que se realice el intercambio, se podrá programar de nuevo una actualización llamando a ` update()`, sin necesidad de recurrir a temporizadores.
Para solicitar una configuración específica para el contexto, utiliza ` setFormat()` como harías con cualquier otro ` QWindow`. Esto permite, entre otras cosas, solicitar una versión y un perfil de OpenGL determinados, o habilitar los búferes de profundidad y de plantilla.
Nota: Corresponde a la aplicación asegurarse de que se soliciten los búferes de profundidad y de estencil a la interfaz del sistema de ventanas subyacente. Si no se solicita un tamaño de búfer de profundidad distinto de cero, no hay garantía de que haya un búfer de profundidad disponible y, en consecuencia, las operaciones de OpenGL relacionadas con las pruebas de profundidad podrían no funcionar como se espera.
Los tamaños de búfer de profundidad y de plantilla más utilizados son 24 y 8, respectivamente. Por ejemplo, una subclase de `QOpenGLWindow` podría hacer lo siguiente en su constructor:
QSurfaceFormat format;
format.setDepthBufferSize(24);
format.setStencilBufferSize(8);
setFormat(format);A diferencia de QWindow, QOpenGLWindow permite abrir un «painter» sobre sí misma y realizar dibujos basados en « QPainter ».
QOpenGLWindow admite múltiples comportamientos de actualización. El valor por defecto, « NoPartialUpdate », equivale a un « QWindow » normal basado en OpenGL. Por el contrario, « PartialUpdateBlit » y « PartialUpdateBlend » se ajustan más al funcionamiento de « QOpenGLWidget », donde siempre hay presente un objeto de búfer de fotogramas adicional y dedicado. Estos modos permiten, a costa de sacrificar algo de rendimiento, redibujar solo un área más pequeña en cada actualización y conservar el resto del contenido del fotograma anterior. Esto resulta útil para aplicaciones que realizan el renderizado de forma incremental utilizando QPainter, ya que de este modo no tienen que redibujar todo el contenido de la ventana en cada llamada a paintGL().
De forma similar a QOpenGLWidget, QOpenGLWindow admite el atributo Qt::AA_ShareOpenGLContexts. Cuando está habilitado, los contextos OpenGL de todas las instancias de QOpenGLWindow se compartirán entre sí. Esto permite acceder a los recursos OpenGL compartibles de las demás instancias.
Para obtener más información sobre gráficos en Qt, consulta Gráficos.
Documentación de tipos de miembros
enum QOpenGLWindow::UpdateBehavior
Esta enumeración describe la estrategia de actualización de la clase ` QOpenGLWindow`.
| Constante | Valor | Descripción |
|---|---|---|
QOpenGLWindow::NoPartialUpdate | 0 | Indica que toda la superficie de la ventana se redibujará en cada actualización, por lo que no se necesitan framebuffers adicionales. Esta es la configuración utilizada en la mayoría de los casos y equivale al funcionamiento que tendría el dibujo directo mediante ` QWindow `. |
QOpenGLWindow::PartialUpdateBlit | 1 | Indica que el dibujo realizado en ` paintGL()` no cubre toda la ventana. En este caso, se crea internamente un objeto de búfer de fotogramas adicional, y el renderizado realizado en ` paintGL()` se dirigirá a este búfer de fotogramas. A continuación, este búfer de fotogramas se copia en el búfer de fotogramas predeterminado de la superficie de la ventana después de cada pintado. Esto permite tener código de dibujo basado en « QPainter » en ` paintGL()` que solo repinta un área más pequeña cada vez, ya que, a diferencia de `NoPartialUpdate`, se conserva el contenido anterior. |
QOpenGLWindow::PartialUpdateBlend | 2 | Es similar a PartialUpdateBlit, pero en lugar de utilizar blits de búfer de fotogramas, el contenido del búfer de fotogramas adicional se representa dibujando un cuadrilátero texturizado con la mezcla activada. Esto, a diferencia de PartialUpdateBlit, permite contenido con mezcla alfa y funciona incluso cuando glBlitFramebuffer no está disponible. En cuanto al rendimiento, es probable que esta configuración sea algo más lenta que PartialUpdateBlit. |
Documentación de las funciones miembro
[explicit] QOpenGLWindow::QOpenGLWindow(QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr)
Crea una nueva ventana `QOpenGLWindow` con los valores proporcionados en ` parent ` y ` updateBehavior`.
Véase también QOpenGLWindow::UpdateBehavior.
[explicit] QOpenGLWindow::QOpenGLWindow(QOpenGLContext *shareContext, QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr)
Crea una nueva ventana `QOpenGLWindow` con los valores proporcionados para ` parent ` y ` updateBehavior`. El contexto de la ventana `QOpenGLWindow` se compartirá con ` shareContext`.
Véase también QOpenGLWindow::UpdateBehavior y shareContext.
[virtual noexcept] QOpenGLWindow::~QOpenGLWindow()
Destruye la instancia de ` QOpenGLWindow `, liberando sus recursos.
El contexto de OpenGLWindow se establece como actual en el destructor, lo que permite la destrucción segura de cualquier objeto secundario que pueda necesitar liberar recursos de OpenGL pertenecientes al contexto proporcionado por esta ventana.
Advertencia: si tienes objetos que envuelven recursos de OpenGL (como ` QOpenGLBuffer`, ` QOpenGLShaderProgram`, etc.) como miembros de una subclase de ` QOpenGLWindow `, es posible que también tengas que añadir una llamada a ` makeCurrent()` en el destructor de esa subclase. Debido a las reglas de destrucción de objetos en C++, dichos objetos se destruirán antes de que se llame a esta función (pero después de que se haya ejecutado el destructor de la subclase), por lo que establecer el contexto de OpenGL como actual en esta función se produce demasiado tarde para garantizar su eliminación segura.
Véase también makeCurrent.
QOpenGLContext *QOpenGLWindow::context() const
Devuelve el objeto ` QOpenGLContext ` utilizado por esta ventana o ` 0 ` si aún no se ha inicializado.
GLuint QOpenGLWindow::defaultFramebufferObject() const
El identificador del objeto framebuffer utilizado por esta ventana.
Cuando el comportamiento de actualización se establece en « NoPartialUpdate », no hay ningún objeto framebuffer independiente. En este caso, el valor devuelto es el ID del framebuffer predeterminado.
En caso contrario, el valor del identificador del objeto framebuffer o « 0 » si aún no se ha inicializado.
void QOpenGLWindow::doneCurrent()
Libera el contexto.
En la mayoría de los casos no es necesario llamar a esta función, ya que el widget se asegurará de que el contexto se vincule y se libere correctamente al invocar ` paintGL()`.
Véase también makeCurrent().
[signal] void QOpenGLWindow::frameSwapped()
Esta señal se emite una vez que se ha ejecutado la función ` buffer swap `, que puede provocar bloqueos. Las aplicaciones que deseen actualizar la pantalla de forma continua y sincronizada con la frecuencia de refresco vertical deben llamar a la función ` update()` al recibir esta señal. Esto permite una experiencia mucho más fluida en comparación con el uso tradicional de temporizadores.
QImage QOpenGLWindow::grabFramebuffer()
Devuelve una copia del búfer de fotogramas.
Nota: Se trata de una operación que puede resultar costosa, ya que se basa en glReadPixels() para leer los píxeles. Esto puede ralentizar el proceso y bloquear el pipeline de la GPU.
Nota: Cuando se utiliza junto con el comportamiento de actualización NoPartialUpdate, es posible que la imagen devuelta no contenga el contenido deseado si se invoca después de que se hayan intercambiado los búferes delantero y trasero (a menos que se haya habilitado el intercambio conservado en la interfaz del sistema de ventanas subyacente). En este modo, la función lee desde el búfer trasero y es posible que su contenido no coincida con el de la pantalla (el búfer delantero). En este caso, los únicos lugares donde esta función se puede utilizar de forma segura son paintGL() o paintOverGL().
[virtual protected] void QOpenGLWindow::initializeGL()
Esta función virtual se invoca una vez antes de la primera llamada a ` paintGL()` o ` resizeGL()`. Reimplementa esta función en una subclase.
Esta función debe configurar los recursos y el estado de OpenGL necesarios.
No es necesario llamar a ` makeCurrent()` porque esto ya se ha hecho al invocar esta función. Ten en cuenta, sin embargo, que el búfer de fotogramas, en caso de que se utilice el modo de actualización parcial, aún no está disponible en esta fase, por lo que debes evitar realizar llamadas de dibujo desde aquí. Aplaza dichas llamadas a ` paintGL()`.
Véanse también paintGL() y resizeGL().
bool QOpenGLWindow::isValid() const
Devuelve « true » si los recursos OpenGL de la ventana, como el contexto, se han inicializado correctamente. Ten en cuenta que el valor devuelto es siempre « false » hasta que la ventana se muestra.
void QOpenGLWindow::makeCurrent()
Prepara la representación de contenido OpenGL para esta ventana estableciendo como contexto actual el correspondiente y vinculando el objeto de búfer de fotogramas, si existe, a dicho contexto.
En la mayoría de los casos no es necesario llamar a esta función, ya que se invoca automáticamente antes de llamar a ` paintGL()`. No obstante, se proporciona para dar soporte a escenarios avanzados multihilo en los que un hilo distinto del de la interfaz gráfica de usuario o del hilo principal pueda querer actualizar el contenido de la superficie o del búfer de fotogramas. Consulta QOpenGLContext para obtener más información sobre cuestiones relacionadas con los hilos.
Esta función también es adecuada para invocarla cuando la ventana de la plataforma subyacente ya ha sido destruida. Esto significa que es seguro llamar a esta función desde el destructor de una subclase de ` QOpenGLWindow `. Si ya no existe ninguna ventana nativa, se utiliza en su lugar una superficie fuera de pantalla. Esto garantiza que las operaciones de limpieza de recursos de OpenGL en el destructor funcionen siempre, siempre y cuando se llame primero a esta función.
Véase también QOpenGLContext, context(), paintGL() y doneCurrent().
[override virtual protected] void QOpenGLWindow::paintEvent(QPaintEvent *event)
Reimplementa: QPaintDeviceWindow::paintEvent(QPaintEvent *event).
Pinta el controlador de « event ». Llama a « paintGL()».
Véase también paintGL().
[virtual protected] void QOpenGLWindow::paintGL()
Esta función virtual se invoca cada vez que es necesario dibujar el contenido de la ventana. Reimplementa esta función en una subclase.
No es necesario llamar a ` makeCurrent()` porque esto ya se ha hecho al invocar esta función.
Antes de invocar esta función, se vinculan el contexto y el búfer de fotogramas (si lo hay), y se configura la ventana de visualización mediante una llamada a glViewport(). El marco de trabajo no establece ningún otro estado ni realiza ningún borrado ni dibujo.
Nota: Cuando se utiliza un comportamiento de actualización parcial, como PartialUpdateBlend, se conserva el resultado de la llamada anterior a paintGL() y, tras el dibujo adicional realizado en la invocación actual de la función, el contenido se superpone o se fusiona con el contenido dibujado directamente en la ventana mediante paintUnderGL().
Véase también initializeGL(), resizeGL(), paintUnderGL(), paintOverGL() y UpdateBehavior.
[virtual protected] void QOpenGLWindow::paintOverGL()
Esta función virtual se invoca tras cada llamada a ` paintGL()`.
Cuando el modo de actualización está configurado en ` NoPartialUpdate`, no hay diferencia entre esta función y ` paintGL()`, ya que el renderizado en cualquiera de ellas da el mismo resultado.
Al igual que paintUnderGL(), el renderizado en esta función se dirige al framebuffer predeterminado de la ventana, independientemente del comportamiento de actualización. Se invoca después de que paintGL() haya devuelto un valor y se haya realizado el blit (PartialUpdateBlit) o el dibujo de cuádruples (PartialUpdateBlend).
Véase también paintGL(), paintUnderGL() y UpdateBehavior.
[virtual protected] void QOpenGLWindow::paintUnderGL()
La función virtual se invoca antes de cada llamada a ` paintGL()`.
Cuando el modo de actualización está configurado en ` NoPartialUpdate`, no hay diferencia entre esta función y ` paintGL()`, ya que el renderizado en cualquiera de ellas da el mismo resultado.
La diferencia cobra importancia cuando se utiliza ` PartialUpdateBlend`, en cuyo caso se emplea un objeto de búfer de fotogramas adicional. En ese caso, ` paintGL()` se dirige a este objeto de búfer de fotogramas adicional, que conserva su contenido, mientras que `paintUnderGL()` y ` paintOverGL()` se dirigen al búfer de fotogramas predeterminado, es decir, directamente a la superficie de la ventana, cuyo contenido se pierde tras cada fotograma mostrado.
Nota: Evita recurrir a esta función cuando el comportamiento de actualización sea « PartialUpdateBlit ». Este modo implica copiar el búfer de fotogramas adicional utilizado por paintGL() al búfer de fotogramas predeterminado tras cada llamada a paintGL(), sobrescribiendo así todo el dibujo generado en esta función.
Véanse también paintGL(), paintOverGL() y UpdateBehavior.
[override virtual protected] void QOpenGLWindow::resizeEvent(QResizeEvent *event)
Reimplementa: QWindow::resizeEvent(QResizeEvent *ev).
Maneja el evento de cambio de tamaño de ` event `. Llama a ` resizeGL()`.
Véase también resizeGL().
[virtual protected] void QOpenGLWindow::resizeGL(int w, int h)
Esta función virtual se invoca cada vez que se cambia el tamaño del widget. Reimplementa esta función en una subclase. El nuevo tamaño se pasa a través de ` w ` y ` h`.
Nota: Se trata simplementede una función de conveniencia para proporcionar una API compatible con QOpenGLWidget. A diferencia de lo que ocurre con QOpenGLWidget, las clases derivadas pueden optar por sobrescribir resizeEvent() en lugar de esta función.
Nota: Evita emitir comandos OpenGL desde esta función, ya que puede que no haya ningún contexto activo cuando se invoque. Si no se puede evitar, llama a makeCurrent().
Nota: No es necesarioprogramar actualizaciones desde aquí. Los sistemas de ventanas enviarán eventos de exposición que activarán una actualización automáticamente.
Véanse también initializeGL() y paintGL().
QOpenGLContext *QOpenGLWindow::shareContext() const
Devuelve el objeto ` QOpenGLContext ` que se ha solicitado compartir con el objeto ` QOpenGLContext` de esta ventana.
QOpenGLWindow::UpdateBehavior QOpenGLWindow::updateBehavior() const
Devuelve el comportamiento de actualización de este ` QOpenGLWindow`.
© 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.