QOpenGLWindow Class
La clase QOpenGLWindow es una subclase de conveniencia de QWindow para realizar pintado OpenGL. Más...
| Cabecera: | #include <QOpenGLWindow> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS OpenGL)target_link_libraries(mytarget PRIVATE Qt6::OpenGL) |
| qmake: | QT += opengl |
| Hereda: | 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 un QWindow mejorado que permite crear fácilmente ventanas que realizan renderizado OpenGL usando un API compatible con QOpenGLWidget A diferencia de QOpenGLWidget, QOpenGLWindow no tiene dependencia del módulo widgets y ofrece un mejor rendimiento.
Una aplicación típica subclasificará QOpenGLWindow y reimplementará las siguientes funciones virtuales:
- initializeGL() para realizar la inicialización de los recursos OpenGL
- resizeGL() para configurar las matrices de transformación y otros recursos dependientes del tamaño de la ventana
- paintGL() para emitir comandos OpenGL o dibujar usando QPainter
Para programar un repintado, llame a la función update(). Tenga en cuenta que esto no resultará inmediatamente en una llamada a paintGL(). Llamar a update() varias veces seguidas no cambiará el comportamiento de ninguna manera.
Este es un slot por lo que puede ser conectado a una señal QChronoTimer::timeout() para realizar la animación. Tenga en cuenta, sin embargo, que en el mundo moderno de OpenGL es una opción mucho mejor confiar en la sincronización con la frecuencia de actualización vertical de la pantalla. Ver setSwapInterval() para una descripción del intervalo de intercambio. Con un intervalo de intercambio de 1, que es el caso en la mayoria de los sistemas por defecto, la llamada a swapBuffers(), que es ejecutada internamente por QOpenGLWindow despues de cada repintado, se bloqueara y esperara por vsync. Esto significa que cada vez que se realiza el swap, se puede programar de nuevo una actualización llamando a update(), sin depender de temporizadores.
Para solicitar una configuración específica para el contexto, utilice setFormat() como para cualquier otro QWindow. Esto permite, entre otras cosas, solicitar una versión y un perfil OpenGL determinados, o habilitar las memorias intermedias de profundidad y de plantilla.
Nota: Es responsabilidad de la aplicación asegurarse de que los búferes de profundidad y stencil se solicitan desde 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, como resultado, las operaciones de OpenGL relacionadas con las pruebas de profundidad pueden no funcionar como se espera.
Las peticiones de tamaño de búfer de profundidad y stencil más comunes son 24 y 8, respectivamente. Por ejemplo, una subclase de QOpenGLWindow podría hacer esto en su constructor:
QSurfaceFormat format; format.setDepthBufferSize(24); format.setStencilBufferSize(8); setFormat(format);
A diferencia de QWindow, QOpenGLWindow permite abrir un pintor sobre sí mismo y realizar dibujos basados en QPainter.
QOpenGLWindow soporta múltiples comportamientos de actualización. Por defecto, NoPartialUpdate es equivalente a un dibujo normal basado en OpenGL QWindow. Por el contrario, PartialUpdateBlit y PartialUpdateBlend están más en línea con la forma de trabajar de QOpenGLWidget, donde siempre hay un objeto framebuffer extra dedicado presente. Estos modos permiten, sacrificando algo de rendimiento, redibujar sólo un área más pequeña en cada pintura y conservar el resto del contenido del fotograma anterior. Esto es útil para aplicaciones que renderizan incrementalmente usando QPainter, porque de esta forma no tienen que redibujar todo el contenido de la ventana en cada llamada a paintGL().
Similar a QOpenGLWidget, QOpenGLWindow soporta el atributo Qt::AA_ShareOpenGLContexts. Cuando esta habilitado, los contextos OpenGL de todas las instancias de QOpenGLWindow compartiran entre si. Esto permite acceder a los recursos OpenGL compartibles de cada uno.
Para más información sobre gráficos en Qt, ver Gráficos.
Documentación de tipos de miembros
enum QOpenGLWindow::UpdateBehavior
Este enum describe la estrategia de actualización de 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 es equivalente a cómo funcionaría el dibujo directamente a través de QWindow. |
QOpenGLWindow::PartialUpdateBlit | 1 | Indica que el dibujo realizado en paintGL() no cubre toda la ventana. En este caso, se crea un objeto framebuffer adicional bajo el capó, y el renderizado realizado en paintGL() se dirigirá a este framebuffer. Este framebuffer se mezcla con el framebuffer por defecto de la superficie de la ventana después de cada pintura. Esto permite tener código de dibujo basado en QPainter en paintGL() que sólo repinta un área más pequeña a la vez, porque, a diferencia de NoPartialUpdate, el contenido anterior se conserva. |
QOpenGLWindow::PartialUpdateBlend | 2 | Similar a PartialUpdateBlit, pero en vez de usar framebuffer blits, el contenido del framebuffer extra se renderiza dibujando un quad texturizado con blending activado. Esto, a diferencia de PartialUpdateBlit, permite el contenido mezclado alfa y funciona incluso cuando glBlitFramebuffer no está disponible. Desde el punto de vista del 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)
Construye una nueva QOpenGLWindow con los datos parent y updateBehavior.
Ver también QOpenGLWindow::UpdateBehavior.
[explicit] QOpenGLWindow::QOpenGLWindow(QOpenGLContext *shareContext, QOpenGLWindow::UpdateBehavior updateBehavior = NoPartialUpdate, QWindow *parent = nullptr)
Construye una nueva QOpenGLWindow con los datos parent y updateBehavior. El contexto de QOpenGLWindow sera compartido con shareContext.
Ver tambien QOpenGLWindow::UpdateBehavior y shareContext.
[virtual noexcept] QOpenGLWindow::~QOpenGLWindow()
Destruye la instancia QOpenGLWindow, liberando sus recursos.
El contexto de OpenGLWindow se actualiza en el destructor, permitiendo la destrucción segura de cualquier objeto hijo que pueda necesitar liberar recursos OpenGL pertenecientes al contexto proporcionado por esta ventana.
Advertencia: si tienes objetos que envuelven recursos OpenGL (como QOpenGLBuffer, QOpenGLShaderProgram, etc.) como miembros de una subclase QOpenGLWindow, puede que necesites añadir también una llamada a makeCurrent() en el destructor de esa subclase. Debido a las reglas de destrucción de objetos de C++, esos objetos serán destruidos antes de llamar a esta función (pero después de que el destructor de la subclase se haya ejecutado), por lo tanto hacer el contexto OpenGL actual en esta función ocurre demasiado tarde para su eliminación segura.
Véase también makeCurrent.
QOpenGLContext *QOpenGLWindow::context() const
Devuelve El QOpenGLContext utilizado por esta ventana o 0 si aún no se ha inicializado.
GLuint QOpenGLWindow::defaultFramebufferObject() const
El manejador del objeto framebuffer utilizado por esta ventana.
Cuando el comportamiento de actualización es NoPartialUpdate, no hay un objeto framebuffer separado. En este caso el valor devuelto es el ID del framebuffer por defecto.
En otro caso, el valor del ID del objeto framebuffer o 0 si aún no se ha inicializado.
void QOpenGLWindow::doneCurrent()
Libera el contexto.
No es necesario llamar a esta función en la mayoría de los casos, ya que el widget se asegurará de que el contexto está ligado y liberado correctamente al invocar paintGL().
Véase también makeCurrent().
[signal] void QOpenGLWindow::frameSwapped()
Esta señal se emite después de que se haya realizado el potencial bloqueo buffer swap. Las aplicaciones que deseen repintar continuamente de forma sincronizada con el refresco vertical, deben emitir un update() ante 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 framebuffer.
Nota: Esta es una operación potencialmente cara porque depende de glReadPixels() para volver a leer los píxeles. Esto puede ser lento y bloquear el pipeline de la GPU.
Nota: Cuando se utiliza junto con el comportamiento de actualización NoPartialUpdate, la imagen devuelta puede no contener el contenido deseado cuando se llama después de que los buffers frontal y posterior hayan sido intercambiados (a menos que el intercambio preservado esté habilitado en la interfaz del sistema de ventanas subyacente). En este modo, la función lee del búfer trasero y su contenido puede no coincidir con el de la pantalla (el búfer delantero). En este caso, el único lugar donde esta función puede utilizarse con seguridad es paintGL() o paintOverGL().
[virtual protected] void QOpenGLWindow::initializeGL()
Esta función virtual se llama una vez antes de la primera llamada a paintGL() o resizeGL(). Reimpleméntala en una subclase.
Esta función debería configurar cualquier recurso y estado OpenGL necesarios.
No hay necesidad de llamar a makeCurrent() porque esto ya se ha hecho cuando se llama a esta función. Ten en cuenta, sin embargo, que el framebuffer, en caso de que se utilice el modo de actualización parcial, no está disponible en este momento, así que evita realizar llamadas a dibujar desde aquí. En su lugar, difiera dichas llamadas a paintGL().
Véase 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. Tenga en cuenta que el valor de retorno es siempre false hasta que la ventana se exponga (se muestre).
void QOpenGLWindow::makeCurrent()
Prepara la renderización del contenido OpenGL para esta ventana haciendo actual el contexto correspondiente y vinculando el objeto framebuffer, si existe, en ese contexto.
No es necesario llamar a esta función en la mayoría de los casos, porque se llama automáticamente antes de invocar paintGL(). No obstante, se proporciona para soportar escenarios avanzados, multihilo, en los que un hilo distinto del GUI o hilo principal puede querer actualizar la superficie o el contenido del framebuffer. Ver QOpenGLContext para más información sobre temas relacionados con hilos.
Esta función es adecuada para llamarla también cuando la ventana de la plataforma subyacente ya está destruida. Esto significa que es seguro llamar a esta función desde el destructor de una subclase de QOpenGLWindow. Si ya no hay ventana nativa, se utiliza en su lugar una superficie fuera de pantalla. Esto asegura que las operaciones de limpieza de recursos OpenGL en el destructor siempre funcionarán, siempre y cuando esta función sea llamada primero.
Ver también QOpenGLContext, context(), paintGL(), y doneCurrent().
[override virtual protected] void QOpenGLWindow::paintEvent(QPaintEvent *event)
Reimplementa: QPaintDeviceWindow::paintEvent(QPaintEvent *event).
Pinta event handler. Llama a paintGL().
Ver también paintGL().
[virtual protected] void QOpenGLWindow::paintGL()
Esta función virtual es llamada cada vez que el contenido de la ventana necesita ser pintado. Reimpleméntela en una subclase.
No es necesario llamar a makeCurrent() porque esto ya se ha hecho cuando se llama a esta función.
Antes de invocar esta función, el contexto y el framebuffer, si lo hay, están vinculados, y la ventana gráfica se configura mediante una llamada a glViewport(). No se establece ningún otro estado y el framework no realiza ningún borrado o dibujo.
Nota: Cuando se utiliza un comportamiento de actualización parcial, como PartialUpdateBlend, la salida de la llamada anterior a paintGL() se conserva y, después del dibujo adicional realizado en la invocación actual de la función, el contenido se mezcla o blitted sobre el contenido dibujado directamente en la ventana en paintUnderGL().
Véase también initializeGL(), resizeGL(), paintUnderGL(), paintOverGL(), y UpdateBehavior.
[virtual protected] void QOpenGLWindow::paintOverGL()
Esta función virtual es llamada después de cada invocación de paintGL().
Cuando el modo de actualización se establece en NoPartialUpdate, no hay diferencia entre esta función y paintGL(), realizar el renderizado en cualquiera de ellas conduce al mismo resultado.
Al igual que paintUnderGL(), el renderizado en esta función tiene como objetivo el framebuffer por defecto de la ventana, independientemente del comportamiento de actualización. Se llama después de que paintGL() haya devuelto y se haya realizado el blit (PartialUpdateBlit) o el quad drawing (PartialUpdateBlend).
Ver también paintGL(), paintUnderGL(), y UpdateBehavior.
[virtual protected] void QOpenGLWindow::paintUnderGL()
La función virtual es llamada antes de cada invocación de paintGL().
Cuando el modo de actualización se establece en NoPartialUpdate, no hay diferencia entre esta función y paintGL(), realizar el renderizado en cualquiera de ellas conduce al mismo resultado.
La diferencia se hace significativa cuando se utiliza PartialUpdateBlend, donde se utiliza un objeto framebuffer extra. Allí, paintGL() se dirige a este objeto framebuffer adicional, que preserva su contenido, mientras que paintUnderGL() y paintOverGL() se dirigen al framebuffer por defecto, es decir, directamente a la superficie de la ventana, cuyo contenido se pierde después de cada frame mostrado.
Nota: Evite confiar en esta función cuando el comportamiento de actualización sea PartialUpdateBlit. Este modo implica el blitting del framebuffer extra utilizado por paintGL() sobre el framebuffer por defecto después de cada invocación de paintGL(), sobrescribiendo así todo el dibujo generado en esta función.
Véase también paintGL(), paintOverGL(), y UpdateBehavior.
[override virtual protected] void QOpenGLWindow::resizeEvent(QResizeEvent *event)
Reimplementa: QWindow::resizeEvent(QResizeEvent *ev).
Redimensiona event handler. Llama a resizeGL().
Ver también resizeGL().
[virtual protected] void QOpenGLWindow::resizeGL(int w, int h)
Esta función virtual es llamada cada vez que el widget ha sido redimensionado. Reimpleméntala en una subclase. El nuevo tamaño se pasa en w y h.
Nota: Se trata simplemente de una función de conveniencia para proporcionar una API compatible con QOpenGLWidget. A diferencia de QOpenGLWidget, las clases derivadas son libres de anular resizeEvent() en lugar de esta función.
Nota: Evite emitir comandos OpenGL desde esta función ya que puede no haber un contexto actual cuando es invocada. Si no puede evitarse, llame a makeCurrent().
Nota: Programar actualizaciones desde aquí no es necesario. Los sistemas de ventanas enviarán eventos de exposición que desencadenarán una actualización automáticamente.
Véase también initializeGL() y paintGL().
QOpenGLContext *QOpenGLWindow::shareContext() const
Devuelve El QOpenGLContext solicitado para ser compartido con el QOpenGLContext de esta ventana.
QOpenGLWindow::UpdateBehavior QOpenGLWindow::updateBehavior() const
Devuelve el comportamiento de actualización para 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.
