QOpenGLWidget Class
La clase QOpenGLWidget es un widget para renderizar gráficos OpenGL. Más información...
| Encabezado: | #include <qopenglwidget.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS OpenGLWidgets) target_link_libraries(mytarget PRIVATE Qt6::OpenGLWidgets) |
| qmake: | QT += openglwidgets |
| Heredado de: | QWidget |
Tipos públicos
(since 6.5) enum | TargetBuffer { LeftBuffer, RightBuffer } |
| enum | UpdateBehavior { NoPartialUpdate, PartialUpdate } |
Funciones públicas
| QOpenGLWidget(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()) | |
| virtual | ~QOpenGLWidget() |
| QOpenGLContext * | context() const |
(since 6.5) QOpenGLWidget::TargetBuffer | currentTargetBuffer() const |
| GLuint | defaultFramebufferObject() const |
(since 6.5) GLuint | defaultFramebufferObject(QOpenGLWidget::TargetBuffer targetBuffer) const |
| void | doneCurrent() |
| QSurfaceFormat | format() const |
| QImage | grabFramebuffer() |
(since 6.5) QImage | grabFramebuffer(QOpenGLWidget::TargetBuffer targetBuffer) |
| bool | isValid() const |
| void | makeCurrent() |
(since 6.5) void | makeCurrent(QOpenGLWidget::TargetBuffer targetBuffer) |
| void | setFormat(const QSurfaceFormat &format) |
| void | setTextureFormat(GLenum texFormat) |
| void | setUpdateBehavior(QOpenGLWidget::UpdateBehavior updateBehavior) |
| GLenum | textureFormat() const |
| QOpenGLWidget::UpdateBehavior | updateBehavior() const |
Señales
| void | aboutToCompose() |
| void | aboutToResize() |
| void | frameSwapped() |
| void | resized() |
Funciones protegidas
| virtual void | initializeGL() |
| virtual void | paintGL() |
| virtual void | resizeGL(int w, int h) |
Funciones protegidas reimplementadas
| virtual bool | event(QEvent *e) override |
| virtual int | metric(QPaintDevice::PaintDeviceMetric metric) const override |
| virtual QPaintEngine * | paintEngine() const override |
| virtual void | paintEvent(QPaintEvent *e) override |
| virtual QPaintDevice * | redirected(QPoint *p) const override |
| virtual void | resizeEvent(QResizeEvent *e) override |
Descripción detallada
Qt OpenGLWidget proporciona funcionalidad para mostrar gráficos OpenGL integrados en una aplicación Qt. Su uso es muy sencillo: haz que tu clase herede de ella y utiliza la subclase como cualquier otro ` QWidget`, con la diferencia de que puedes elegir entre utilizar ` QPainter ` y los comandos de renderizado estándar de OpenGL.
QOpenGLWidget proporciona tres prácticas funciones virtuales que puedes reimplementar en tu subclase para realizar las tareas típicas de OpenGL:
- paintGL() - Representa la escena de OpenGL. Se invoca cada vez que es necesario actualizar el widget.
- resizeGL() - Configura la ventana de visualización de OpenGL, la proyección, etc. Se invoca cada vez que se cambia el tamaño del widget (y también cuando se muestra por primera vez, ya que todos los widgets recién creados reciben automáticamente un evento de cambio de tamaño).
- initializeGL() - Configura los recursos y el estado de OpenGL. Se invoca una vez antes de que se llame por primera vez a ` resizeGL()` o a ` paintGL()`.
Si necesitas provocar un repintado desde otros puntos que no sean paintGL() (un ejemplo típico es cuando se utiliza timers para animar escenas), debes llamar a la función update() del widget para programar una actualización.
El contexto de renderizado OpenGL de tu widget se establece como actual cuando se llama a paintGL(), resizeGL() o initializeGL(). Si necesitas llamar a las funciones estándar de la API de OpenGL desde otros lugares (por ejemplo, en el constructor de tu widget o en tus propias funciones de pintura), debes llamar primero a makeCurrent().
Todo el renderizado se realiza en un objeto de búfer de fotogramas de OpenGL. La función ` makeCurrent()` garantiza que esté vinculado al contexto. Ten esto en cuenta al crear y vincular objetos de búfer de fotogramas adicionales en el código de renderizado de ` paintGL()`. Nunca vuelvas a vincular el búfer de fotogramas con el ID 0. En su lugar, llama a ` defaultFramebufferObject()` para obtener el ID que debe vincularse.
QOpenGLWidget permite utilizar diferentes versiones y perfiles de OpenGL cuando la plataforma lo admite. Basta con establecer el formato deseado mediante setFormat(). Sin embargo, ten en cuenta que, si hay varias instancias de QOpenGLWidget en la misma ventana, es necesario que todas utilicen el mismo formato, o al menos formatos que no impidan compartir los contextos. Para solucionar este problema, es preferible utilizar QSurfaceFormat::setDefaultFormat() en lugar de setFormat().
Nota: En algunas plataformas (por ejemplo, macOS), es obligatoriollamar a ` QSurfaceFormat::setDefaultFormat()` antes de crear la instancia de ` QApplication ` cuando se solicita un contexto de perfil básico de OpenGL. Esto garantiza que el uso compartido de recursos entre contextos siga funcionando, ya que todos los contextos internos se crean utilizando la versión y el perfil correctos.
Técnicas de renderizado
Tal y como se ha descrito anteriormente, subclasifica QOpenGLWidget para renderizar contenido 3D puro de la siguiente manera:
- Reimplementa las funciones ` initializeGL()` y ` resizeGL()` para configurar el estado de OpenGL y proporcionar una transformación de perspectiva.
- Reimplemente ` paintGL()` para dibujar la escena 3D, llamando únicamente a funciones de OpenGL.
También es posible dibujar gráficos 2D en una subclase de QOpenGLWidget utilizando QPainter:
- En ` paintGL()`, en lugar de emitir comandos de OpenGL, crea un objeto ` QPainter ` para utilizarlo en el widget.
- Dibuja primitivas utilizando las funciones miembro de ` QPainter`.
- Aún se pueden emitir comandos OpenGL directos. Sin embargo, debes asegurarte de que estos estén enmarcados entre una llamada a las funciones beginNativePainting() y endNativePainting() del pintor.
Al realizar el dibujo utilizando únicamente ` QPainter `, también es posible llevar a cabo el pintado tal y como se hace con los widgets normales: reimplementando ` paintEvent()`.
- Reimplementa la función paintEvent().
- Crea un objeto ` QPainter ` con el widget como destino. Para ello, pasa el widget al constructor o a la función ` QPainter::begin()`.
- Dibuja primitivas utilizando las funciones miembro de ` QPainter`.
- Una vez finalizado el dibujo, se destruye la instancia de ` QPainter `. Como alternativa, llama a ` QPainter::end()` de forma explícita.
Llamadas a funciones de OpenGL, encabezados y QOpenGLFunctions
Al realizar llamadas a funciones de OpenGL, se recomienda encarecidamente evitar llamar a las funciones directamente. En su lugar, es preferible utilizar ` QOpenGLFunctions ` (al crear aplicaciones portables) o las variantes con versión (por ejemplo, ` QOpenGLFunctions_3_2_Core ` y similares, cuando se apunta a OpenGL moderno y exclusivo para escritorio). De esta forma, la aplicación funcionará correctamente en todas las configuraciones de compilación de Qt, incluidas aquellas que realizan una carga dinámica de la implementación de OpenGL, lo que significa que las aplicaciones no se vinculan directamente a una implementación de GL y, por lo tanto, las llamadas directas a funciones no son viables.
En ` paintGL()` siempre se puede acceder al contexto actual llamando a ` QOpenGLContext::currentContext()`. Desde este contexto, se puede recuperar una instancia de ` QOpenGLFunctions ` ya inicializada y lista para su uso llamando a ` QOpenGLContext::functions()`. Una alternativa a anteponer un prefijo a cada llamada a GL es heredar de ` QOpenGLFunctions ` y llamar a ` QOpenGLFunctions::initializeOpenGLFunctions()` en ` initializeGL()`.
En cuanto a los encabezados de OpenGL, ten en cuenta que, en la mayoría de los casos, no será necesario incluir directamente ningún encabezado como GL.h. Los encabezados de Qt relacionados con OpenGL incluirán qopengl.h, que a su vez incluirá el encabezado adecuado para el sistema. Puede tratarse de un encabezado de OpenGL ES 3.x o 2.0, la versión más reciente disponible, o de un gl.h proporcionado por el sistema. Además, como parte de Qt se proporciona una copia de los encabezados de extensión (denominados glext.h en algunos sistemas) tanto para OpenGL como para OpenGL ES. Estos se incluirán automáticamente en las plataformas en las que sea posible. Esto significa que las constantes y los typedefs de punteros a funciones de las extensiones ARB, EXT y OES estarán disponibles automáticamente.
Ejemplos de código
Para empezar, la subclase más sencilla de `QOpenGLWidget` podría tener el siguiente aspecto:
class MyGLWidget : public QOpenGLWidget
{
public:
MyGLWidget(QWidget *parent) : QOpenGLWidget(parent) { }
protected:
void initializeGL() override
{
// Set up the rendering context, load shaders and other resources, etc.:
QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
f->glClearColor(1.0f, 1.0f, 1.0f, 1.0f);
...
}
void resizeGL(int w, int h) override
{
// Update projection matrix and other size related settings:
m_projection.setToIdentity();
m_projection.perspective(45.0f, w / float(h), 0.01f, 100.0f);
...
}
void paintGL() override
{
// Draw the scene:
QOpenGLFunctions *f = QOpenGLContext::currentContext()->functions();
f->glClear(GL_COLOR_BUFFER_BIT);
...
}
};Como alternativa, se puede evitar el prefijo en todas y cada una de las llamadas a OpenGL derivando en su lugar de ` QOpenGLFunctions `:
class MyGLWidget : public QOpenGLWidget, protected QOpenGLFunctions
{
...
void initializeGL() override
{
initializeOpenGLFunctions();
glClearColor(...);
...
}
...
};Para obtener un contexto compatible con una versión o perfil de OpenGL determinado, o para solicitar buffers de profundidad y de estarcido, llama a ` setFormat()`:
QOpenGLWidget *widget = new QOpenGLWidget(parent);
QSurfaceFormat format;
format.setDepthBufferSize(24);
format.setStencilBufferSize(8);
format.setVersion(3, 2);
format.setProfile(QSurfaceFormat::CoreProfile);
widget->setFormat(format); // must be called before the widget or its parent window gets shownNota: Corresponde a la aplicación asegurarse de que se soliciten los búferes de profundidad y de plantilla a través de 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 la comprobación de profundidad podrían no funcionar como se espera. Los tamaños de búfer de profundidad y de plantilla más habituales son 24 y 8, respectivamente.
Con contextos OpenGL 3.0 o superiores, cuando la portabilidad no es importante, las variantes versionadas de ` QOpenGLFunctions ` facilitan el acceso a todas las funciones modernas de OpenGL disponibles en una versión determinada:
...
void paintGL() override
{
QOpenGLFunctions_3_2_Core *f = QOpenGLContext::currentContext()->versionFunctions<QOpenGLFunctions_3_2_Core>();
...
f->glDrawArraysInstanced(...);
...
}
...Como se ha descrito anteriormente, resulta más sencillo y robusto establecer el formato solicitado de forma global, de modo que se aplique a todas las ventanas y contextos durante el tiempo de ejecución de la aplicación. A continuación se muestra un ejemplo de ello:
int main(int argc, char **argv)
{
QApplication app(argc, argv);
QSurfaceFormat format;
format.setDepthBufferSize(24);
format.setStencilBufferSize(8);
format.setVersion(3, 2);
format.setProfile(QSurfaceFormat::CoreProfile);
QSurfaceFormat::setDefaultFormat(format);
MyWidget widget;
widget.show();
return app.exec();
}Multimuestreo
Para habilitar el multimuestreo, establece el número de muestras solicitadas en el ` QSurfaceFormat ` que se pasa a ` setFormat()`. En sistemas que no lo admiten, es posible que la solicitud se ignore.
La compatibilidad con el multimuestreo requiere compatibilidad con buffers de renderizado multimuestreados y blits de framebuffer. En las implementaciones de OpenGL ES 2.0 es probable que estas características no estén presentes. Esto significa que el multisampling no estará disponible. Con las versiones modernas de OpenGL y OpenGL ES 3.0 y superiores, esto ya no suele suponer un problema.
Multihilo
La realización de renderizado fuera de pantalla en subprocesos de trabajo —por ejemplo, para generar texturas que luego se utilizan en la interfaz gráfica de usuario o en el subproceso principal mediante ` paintGL()`— se admite al exponer el ` QOpenGLContext ` del widget, de modo que se puedan crear contextos adicionales que lo compartan en cada subproceso.
Es posible dibujar directamente en el búfer de fotogramas del QOpenGLWidget fuera del hilo de la GUI o del hilo principal reimplementando paintEvent() para que no haga nada. La afinidad de hilo del contexto debe modificarse mediante QObject::moveToThread(). A continuación, makeCurrent() y doneCurrent() pueden utilizarse en el hilo de trabajo. Asegúrate de volver a trasladar el contexto al hilo de la interfaz gráfica de usuario (GUI) o al hilo principal posteriormente.
No es posible activar un intercambio de búfer solo para el `QOpenGLWidget`, ya que no existe una superficie nativa real en pantalla para él. Corresponde a la pila de widgets gestionar la composición y los intercambios de búfer en el hilo de la GUI. Cuando un hilo haya terminado de actualizar el búfer de fotogramas, llama a ` update()` en el hilo de la GUI/principal para programar la composición.
Hay que tener especial cuidado para evitar utilizar el búfer de fotogramas cuando el hilo de la GUI/principal está realizando la composición. Las señales ` aboutToCompose()` y ` frameSwapped()` se emitirán al inicio y al final de la composición. Se emiten en el hilo de la GUI/principal. Esto significa que, al utilizar una conexión directa, ` aboutToCompose()` puede bloquear el hilo de la GUI o el hilo principal hasta que el hilo de trabajo haya finalizado su renderizado. A partir de ese momento, el hilo de trabajo no debe realizar ningún renderizado adicional hasta que se emita la señal ` frameSwapped()`. Si esto no es aceptable, el hilo de trabajo debe implementar un mecanismo de doble búfer. Esto implica dibujar utilizando un destino de renderizado alternativo, que esté totalmente controlado por el hilo, por ejemplo, un objeto de búfer de fotogramas adicional, y copiarlo al búfer de fotogramas de QOpenGLWidget en el momento adecuado.
Compartición de contextos
Cuando se añaden varios QOpenGLWidgets como hijos del mismo widget de nivel superior, sus contextos se comparten entre sí. Esto no se aplica a las instancias de QOpenGLWidget que pertenecen a ventanas diferentes.
Esto significa que todos los QOpenGLWidgets de la misma ventana pueden acceder a los recursos compartibles de los demás, como las texturas, y no es necesario un contexto «global compartido» adicional.
Para configurar el uso compartido entre instancias de `QOpenGLWidget` que pertenezcan a ventanas diferentes, establece el atributo de aplicación ` Qt::AA_ShareOpenGLContexts ` antes de instanciar ` QApplication`. Esto activará el uso compartido entre todas las instancias de `QOpenGLWidget` sin necesidad de realizar ningún paso adicional.
También es posible crear instancias adicionales de ` QOpenGLContext ` que compartan recursos, como texturas, con el contexto de `QOpenGLWidget`. Basta con pasar el puntero devuelto por ` context()` a ` QOpenGLContext::setShareContext()` antes de llamar a ` QOpenGLContext::create()`. El contexto resultante también se puede utilizar en un hilo diferente, lo que permite la generación de texturas en subprocesos y la carga asíncrona de texturas.
Ten en cuenta que QOpenGLWidget espera una implementación conforme al estándar de compartición de recursos por parte de los controladores gráficos subyacentes. Por ejemplo, algunos controladores, en particular los de hardware móvil e integrado, presentan problemas a la hora de configurar la compartición entre un contexto existente y otros creados posteriormente. Otros controladores pueden comportarse de forma inesperada al intentar utilizar recursos compartidos entre diferentes subprocesos.
Inicialización y limpieza de recursos
Se garantiza que el contexto OpenGL asociado a QOpenGLWidget esté actualizado siempre que se invoquen las funciones ` initializeGL()` y ` paintGL()`. No intentes crear recursos OpenGL antes de llamar a ` initializeGL()`. Por ejemplo, intentar compilar sombreadores, inicializar objetos de búfer de vértices o cargar datos de texturas fallará si se realiza en el constructor de una subclase. Estas operaciones deben aplazarse hasta initializeGL(). Algunas de las clases auxiliares de Qt OpenGL, como QOpenGLBuffer o QOpenGLVertexArrayObject, tienen un comportamiento aplazado similar: pueden instanciarse sin un contexto, pero toda la inicialización se aplaza hasta una llamada a create() o similar. Esto significa que pueden utilizarse como variables miembro normales (no punteros) en una subclase de `QOpenGLWidget`, pero la función ` create()` o similar solo puede llamarse desde ` initializeGL()`. Sin embargo, hay que tener en cuenta que no todas las clases están diseñadas de esta manera. En caso de duda, convierte la variable miembro en un puntero y crea y destruye la instancia dinámicamente en initializeGL() y en el destructor, respectivamente.
Para liberar los recursos también es necesario que el contexto esté activo. Por lo tanto, se espera que los destructores que realizan dicha limpieza llamen a ` makeCurrent()` antes de proceder a destruir cualquier recurso o envoltorio de OpenGL. Evita la eliminación diferida mediante ` deleteLater()` o el mecanismo de parentificación de ` QObject`. No hay garantía de que el contexto correcto esté activo en el momento en que la instancia en cuestión sea realmente destruida.
Por lo tanto, una subclase típica suele tener el siguiente aspecto en lo que respecta a la inicialización y destrucción de recursos:
class MyGLWidget : public QOpenGLWidget
{
...
private:
QOpenGLVertexArrayObject m_vao;
QOpenGLBuffer m_vbo;
QOpenGLShaderProgram *m_program;
QOpenGLShader *m_shader;
QOpenGLTexture *m_texture;
};
MyGLWidget::MyGLWidget()
: m_program(0), m_shader(0), m_texture(0)
{
// No OpenGL resource initialization is done here.
}
MyGLWidget::~MyGLWidget()
{
// Make sure the context is current and then explicitly
// destroy all underlying OpenGL resources.
makeCurrent();
delete m_texture;
delete m_shader;
delete m_program;
m_vbo.destroy();
m_vao.destroy();
doneCurrent();
}
void MyGLWidget::initializeGL()
{
m_vao.create();
if (m_vao.isCreated())
m_vao.bind();
m_vbo.create();
m_vbo.bind();
m_vbo.allocate(...);
m_texture = new QOpenGLTexture(QImage(...));
m_shader = new QOpenGLShader(...);
m_program = new QOpenGLShaderProgram(...);
...
}Esto funciona en la mayoría de los casos, pero no es una solución genérica totalmente ideal. Cuando el widget cambia de padre de tal forma que acaba en una ventana de nivel superior completamente diferente, se necesita algo más: al conectarse a la señal « aboutToBeDestroyed()» de « QOpenGLContext », se puede realizar la limpieza cada vez que el contexto de OpenGL esté a punto de liberarse.
Nota: Para los widgets que cambian varias veces de ventana de nivel superior asociada a lo largo de su ciclo de vida, es esencial un enfoque de limpieza combinado, tal y como se muestra en el fragmento de código siguiente. Cada vez que el widget o uno de sus padres cambia de padre de tal forma que la ventana de nivel superior pasa a ser otra, el contexto asociado al widget se destruye y se crea uno nuevo. A continuación, se realiza una llamada a ` initializeGL()``, donde deben reinicializarse todos los recursos de OpenGL. Debido a esto, la única opción para llevar a cabo una limpieza adecuada es conectarse a la señal `aboutToBeDestroyed()` del contexto. Ten en cuenta que el contexto en cuestión puede no ser el actual cuando se emita la señal. Por lo tanto, es una buena práctica llamar a ` makeCurrent()` en el slot conectado. Además, los mismos pasos de limpieza deben realizarse desde el destructor de la clase derivada, ya que es posible que el slot o la lambda conectados a la señal no se invoquen cuando se destruya el widget.
MyGLWidget::~MyGLWidget()
{
cleanup();
}
void MyGLWidget::initializeGL()
{
...
connect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}
void MyGLWidget::cleanup()
{
makeCurrent();
delete m_texture;
m_texture = 0;
...
doneCurrent();
disconnect(context(), &QOpenGLContext::aboutToBeDestroyed, this, &MyGLWidget::cleanup);
}Nota: Cuando se establece « Qt::AA_ShareOpenGLContexts », el contexto del widget nunca cambia, ni siquiera al cambiar de padre, ya que se podrá acceder a la textura asociada al widget también desde el contexto del nuevo nivel superior. Por lo tanto, no es obligatorio actuar sobre la señal aboutToBeDestroyed() del contexto cuando esta bandera está activada.
Una limpieza adecuada es especialmente importante debido al uso compartido de contextos. Aunque el contexto asociado a cada `QOpenGLWidget` se destruye junto con el propio `QOpenGLWidget`, los recursos compartibles de ese contexto, como las texturas, seguirán siendo válidos hasta que se destruya la ventana de nivel superior en la que residía el `QOpenGLWidget`. Además, configuraciones como « Qt::AA_ShareOpenGLContexts » y algunos módulos de Qt pueden ampliar aún más el alcance del uso compartido de contextos, lo que podría dar lugar a que los recursos en cuestión permanezcan activos durante todo el ciclo de vida de la aplicación. Por lo tanto, lo más seguro y robusto es realizar siempre una limpieza explícita de todos los recursos y envoltorios de recursos utilizados en el QOpenGLWidget.
Limitaciones y otras consideraciones
Colocar otros widgets debajo y hacer que el QOpenGLWidget sea transparente no dará los resultados esperados: los widgets que se encuentran debajo no serán visibles. Esto se debe a que, en la práctica, el QOpenGLWidget se dibuja antes que todos los demás widgets normales (no OpenGL), por lo que las soluciones de tipo «transparente» no son viables. Otros tipos de diseños, como colocar widgets encima del QOpenGLWidget, funcionarán según lo esperado.
Cuando sea absolutamente necesario, esta limitación puede superarse configurando el atributo « Qt::WA_AlwaysStackOnTop » en el QOpenGLWidget. Sin embargo, hay que tener en cuenta que esto altera el orden de superposición; por ejemplo, no será posible colocar otros widgets encima del QOpenGLWidget, por lo que solo debe utilizarse en situaciones en las que se requiera un QOpenGLWidget semitransparente con otros widgets visibles debajo.
Tenga en cuenta que esto no se aplica cuando no hay otros widgets debajo y la intención es tener una ventana semitransparente. En ese caso, basta con el enfoque tradicional de establecer ` Qt::WA_TranslucentBackground ` en la ventana de nivel superior. Ten en cuenta que, si solo se desean áreas transparentes en el `QOpenGLWidget`, será necesario volver a establecer ` Qt::WA_NoSystemBackground ` en ` false ` tras habilitar ` Qt::WA_TranslucentBackground`. Además, dependiendo del sistema, también puede ser necesario solicitar un canal alfa para el contexto del `QOpenGLWidget` mediante ` setFormat()`.
QOpenGLWidget admite varios comportamientos de actualización, al igual que QOpenGLWindow. En el modo «preserved», el contenido renderizado de la llamada anterior a paintGL() está disponible en la siguiente, lo que permite un renderizado incremental. En el modo «non-preserved», el contenido se pierde y se espera que las implementaciones de paintGL() vuelvan a dibujar todo lo que hay en la vista.
Antes de Qt 5.5, el comportamiento predeterminado de `QOpenGLWidget` era conservar el contenido renderizado entre llamadas a ` paintGL()`. Desde Qt 5.5, el comportamiento predeterminado es «no conservado», ya que esto proporciona un mejor rendimiento y la mayoría de las aplicaciones no necesitan el contenido anterior. Esto también se asemeja a la semántica de un ` QWindow ` basado en OpenGL y coincide con el comportamiento por defecto de ` QOpenGLWindow `, en el sentido de que el color y los búferes auxiliares se invalidan en cada fotograma. Para restablecer el comportamiento de conservación, llama a ` setUpdateBehavior()` con ` PartialUpdate`.
Nota: Al añadir dinámicamente un `QOpenGLWidget` a una jerarquía de widgets, por ejemplo, al convertir un nuevo `QOpenGLWidget` en hijo de un widget cuyo widget de nivel superior correspondiente ya se muestra en pantalla, la ventana nativa asociada puede destruirse y recrearse implícitamente si el `QOpenGLWidget` es el primero de su tipo dentro de dicha ventana. Esto se debe a que el tipo de ventana cambia de « RasterSurface » a « OpenGLSurface », lo que tiene implicaciones específicas de cada plataforma. Este comportamiento es nuevo en Qt 6.4.
Una vez que se añade un `QOpenGLWidget` a una jerarquía de widgets, el contenido de la ventana de nivel superior se vacía mediante un renderizado basado en OpenGL. Los widgets distintos del `QOpenGLWidget` siguen dibujando su contenido utilizando un pintor basado en software, pero la composición final se realiza a través de la API 3D.
Nota: La visualización de un `QOpenGLWidget` requiere un canal alfa en el almacén de respaldo de la ventana de nivel superior asociada, debido a la forma en que funciona la composición con otro contenido basado en ` QWidget`. Si no hay canal alfa, el contenido renderizado por el QOpenGLWidget no será visible. Esto puede resultar especialmente relevante en Linux/X11 en configuraciones de visualización remota (como, por ejemplo, con Xvnc), cuando se utiliza una profundidad de color inferior a 24. Por ejemplo, una profundidad de color de 16 se corresponderá normalmente con el uso de una imagen de la memoria de respaldo con el formato QImage::Format_RGB16 (RGB565), lo que no deja espacio para un canal alfa. Por lo tanto, si tiene problemas para que el contenido de un QOpenGLWidget se componga correctamente con el resto de los widgets de la ventana, asegúrese de que el servidor (por ejemplo, vncserver) esté configurado con una profundidad de 24 o 32 bits en lugar de 16.
Alternativas
Al añadir un QOpenGLWidget a una ventana, se activa la composición basada en OpenGL para toda la ventana. En algunos casos especiales, esto puede no ser lo ideal, y se prefiere el comportamiento antiguo al estilo de QGLWidget con una ventana hija nativa independiente. Las aplicaciones de escritorio que tengan en cuenta las limitaciones de este enfoque (por ejemplo, en lo que respecta a solapamientos, transparencia, vistas de desplazamiento y áreas MDI) pueden utilizar ` QOpenGLWindow ` junto con ` QWidget::createWindowContainer()`. Se trata de una alternativa moderna a `QGLWidget` y es más rápida que `QOpenGLWidget` debido a que no requiere el paso adicional de composición. Se recomienda encarecidamente limitar el uso de este enfoque a los casos en los que no haya otra opción. Ten en cuenta que esta opción no es adecuada para la mayoría de las plataformas integradas y móviles, y se sabe que también presenta problemas en determinadas plataformas de escritorio (por ejemplo, macOS). La solución estable y multiplataforma es siempre QOpenGLWidget.
Renderizado estereoscópico
A partir de la versión 6.5, QOpenGLWidget es compatible con el renderizado estereoscópico. Para habilitarlo, establezca la bandera « QSurfaceFormat::StereoBuffers » de forma global antes de crear la ventana, utilizando QSurfaceFormat::SetDefaultFormat().
Nota: El uso de setFormat() no funcionará necesariamente debido a cómo se gestiona el indicador internamente.
Esto hará que se llame a ` paintGL()` dos veces por fotograma, una por cada ` QOpenGLWidget::TargetBuffer`. En ` paintGL()`, llama a ` currentTargetBuffer()` para consultar en cuál de ellos se está dibujando actualmente.
Nota: Para tener un mayor control sobre los búferes de color izquierdo y derecho, plantéate utilizar en su lugar ` QOpenGLWindow ` + ` QWidget::createWindowContainer()`.
Nota: Este tipo de renderizado 3D tiene ciertos requisitos de hardware, como que la tarjeta gráfica esté configurada con soporte estéreo.
OpenGL es una marca comercial de Silicon Graphics, Inc. en Estados Unidos y otros países.
Véase también QOpenGLFunctions, QOpenGLWindow, Qt::AA_ShareOpenGLContexts y UpdateBehavior.
Documentación sobre tipos de miembros
[since 6.5] enum QOpenGLWidget::TargetBuffer
Especifica el búfer que se debe utilizar cuando está activada la representación estereoscópica, cuya activación o desactivación se controla mediante la configuración de ` QSurfaceFormat::StereoBuffers`.
Nota: LeftBuffer es siempre el valor predeterminado y se utiliza como valor de reserva cuando el renderizado estereoscópico está desactivado o no es compatible con el controlador gráfico.
| Constante | Valor |
|---|---|
QOpenGLWidget::LeftBuffer | 0 |
QOpenGLWidget::RightBuffer | 1 |
Esta enumeración se introdujo en Qt 6.5.
enum QOpenGLWidget::UpdateBehavior
Esta enumeración describe la semántica de actualización de QOpenGLWidget.
| Constante | Valor | Descripción |
|---|---|---|
QOpenGLWidget::NoPartialUpdate | 0 | QOpenGLWidget desechará el contenido del búfer de color y de los búferes auxiliares una vez que el objeto « QOpenGLWidget » se haya renderizado en pantalla. Este es el mismo comportamiento que cabe esperar al llamar a « QOpenGLContext::swapBuffers » con un objeto « QWindow » con OpenGL habilitado de forma predeterminada como argumento. NoPartialUpdate puede ofrecer algunas ventajas de rendimiento en determinadas arquitecturas de hardware habituales en el ámbito móvil y embebido cuando se utiliza un objeto de búfer de fotogramas como destino de renderizado. El objeto de búfer de fotogramas se invalida entre fotogramas con glInvalidateFramebuffer (si es compatible) o, como alternativa, con glDiscardFramebufferEXT (si es compatible) o una llamada a glClear. |
QOpenGLWidget::PartialUpdate | 1 | El búfer de color y los búferes auxiliares del objeto de búfer de fotogramas no se invalidan entre fotogramas. |
Véase también updateBehavior() y setUpdateBehavior().
Documentación de funciones miembro
[explicit] QOpenGLWidget::QOpenGLWidget(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
Crea un widget que es un elemento secundario de ` parent`, con los indicadores del widget establecidos en ` f`.
[virtual noexcept] QOpenGLWidget::~QOpenGLWidget()
Destruye la instancia de ` QOpenGLWidget ` y libera sus recursos.
El contexto de ` QOpenGLWidget` 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 este widget.
Advertencia: si tienes objetos que envuelven recursos de OpenGL (como ` QOpenGLBuffer`, ` QOpenGLShaderProgram`, etc.) como miembros de una subclase de `OpenGLWidget`, es posible que también tengas que añadir una llamada a ` makeCurrent()` en el destructor de dicha subclase. Debido a las reglas de destrucción de objetos en C++, dichos objetos se destruirán antes de llamar a esta función (pero después de que se haya ejecutado el destructor de la subclase), por lo que establecer el contexto OpenGL como actual en esta función se produce demasiado tarde para su eliminación segura.
Véase también makeCurrent.
[signal] void QOpenGLWidget::aboutToCompose()
Esta señal se emite cuando la ventana de nivel superior del widget está a punto de comenzar a componer las texturas de sus elementos hijos de tipo « QOpenGLWidget » y de los demás widgets.
[signal] void QOpenGLWidget::aboutToResize()
Esta señal se emite cuando se modifica el tamaño del widget y, por lo tanto, el objeto framebuffer va a ser recreado.
QOpenGLContext *QOpenGLWidget::context() const
Devuelve el objeto « QOpenGLContext » utilizado por este widget o « 0 » si aún no se ha inicializado.
Nota: El contexto y el objeto de búfer de fotogramas que utiliza el widget cambian al cambiar la relación de parentesco del widget mediante setParent().
Véase también QOpenGLContext::setShareContext() y defaultFramebufferObject().
[since 6.5] QOpenGLWidget::TargetBuffer QOpenGLWidget::currentTargetBuffer() const
Devuelve el búfer de destino actualmente activo. Por defecto, será el búfer izquierdo; el búfer derecho solo se utiliza cuando está activada la función « QSurfaceFormat::StereoBuffers ». Cuando está activado el renderizado estereoscópico, se puede consultar mediante « paintGL()» para saber qué búfer se está utilizando en ese momento. La función « paintGL()» se llamará dos veces, una por cada destino.
Esta función se introdujo en Qt 6.5.
Véase también paintGL().
GLuint QOpenGLWidget::defaultFramebufferObject() const
Devuelve el identificador del objeto framebuffer o ` 0 ` si aún no se ha inicializado.
Nota: El objeto framebuffer pertenece al contexto devuelto por context() y es posible que no sea accesible desde otros contextos.
Nota: El contexto y el objeto framebuffer utilizados por el widget cambian al reasignar el widget mediante setParent(). Además, el objeto framebuffer cambia con cada cambio de tamaño.
Véase también ` context()`.
[since 6.5] GLuint QOpenGLWidget::defaultFramebufferObject(QOpenGLWidget::TargetBuffer targetBuffer) const
Devuelve el identificador del objeto framebuffer del búfer de destino especificado o ` 0 ` si aún no se ha inicializado.
Llamar a esta sobrecarga solo tiene sentido si QSurfaceFormat::StereoBuffers está habilitado y es compatible con el hardware. De lo contrario, este método devolverá el búfer predeterminado.
Nota: El objeto framebuffer pertenece al contexto devuelto por ` context()` y es posible que no sea accesible desde otros contextos. El contexto y el objeto framebuffer utilizados por el widget cambian al reasignar el widget mediante ` setParent()`. Además, el objeto framebuffer cambia con cada cambio de tamaño.
Esta función se introdujo en Qt 6.5.
Véase también ` context()`.
void QOpenGLWidget::doneCurrent()
Libera el contexto.
En la mayoría de los casos no es necesario llamar a esta función, ya que el widget se encargará de que el contexto se vincule y se libere correctamente al invocar paintGL().
[override virtual protected] bool QOpenGLWidget::event(QEvent *e)
Reimplementa: ` QWidget::event(QEvent *event)`.
QSurfaceFormat QOpenGLWidget::format() const
Devuelve el contexto y el formato de superficie utilizados por este widget y su ventana de nivel superior.
Una vez que se han creado, redimensionado y mostrado tanto el widget como su ventana de nivel superior, esta función devolverá el formato real del contexto. Este puede diferir del formato solicitado si la plataforma no ha podido satisfacer la solicitud. También es posible obtener tamaños de búfer de color mayores que los solicitados.
Cuando la ventana del widget y los recursos OpenGL relacionados aún no se han inicializado, el valor devuelto es el formato que se ha establecido mediante setFormat().
Véanse también setFormat() y context().
[signal] void QOpenGLWidget::frameSwapped()
Esta señal se emite una vez que la ventana de nivel superior del widget ha finalizado la composición y ha regresado de su llamada a ` QOpenGLContext::swapBuffers()`, que podría ser bloqueante.
QImage QOpenGLWidget::grabFramebuffer()
Renderiza y devuelve una imagen RGB de 32 bits del búfer de fotogramas.
Nota: Se trata de una operación que puede resultar costosa, ya que depende de glReadPixels() para leer los píxeles. Esto puede ralentizar el proceso y bloquear el pipeline de la GPU.
[since 6.5] QImage QOpenGLWidget::grabFramebuffer(QOpenGLWidget::TargetBuffer targetBuffer)
Renderiza y devuelve una imagen RGB de 32 bits del búfer de fotogramas del búfer de destino especificado. Solo tiene sentido llamar a esta sobrecarga cuando está habilitada la función « QSurfaceFormat::StereoBuffers ». Al capturar el búfer de fotogramas del búfer de destino correcto, se devolverá la imagen predeterminada si el renderizado estereoscópico está desactivado o si el hardware no lo admite.
Nota: Se trata de una operación potencialmente costosa, ya que se basa en glReadPixels() para leer los píxeles. Esto puede resultar lento y bloquear el pipeline de la GPU.
Esta función se introdujo en Qt 6.5.
[virtual protected] void QOpenGLWidget::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 todos los recursos de OpenGL necesarios.
No es necesario llamar a ` makeCurrent()` porque esto ya se ha hecho al invocar esta función. Sin embargo, ten en cuenta que el framebuffer 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 QOpenGLWidget::isValid() const
Devuelve «true» si el widget y los recursos de OpenGL, como el contexto, se han inicializado correctamente. Ten en cuenta que el valor devuelto es siempre «false» hasta que se muestra el widget.
void QOpenGLWidget::makeCurrent()
Prepara la representación de contenido OpenGL para este widget estableciendo el contexto correspondiente como actual y vinculando el objeto de búfer de fotogramas 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().
Véanse también context(), paintGL() y doneCurrent().
[since 6.5] void QOpenGLWidget::makeCurrent(QOpenGLWidget::TargetBuffer targetBuffer)
Prepara el renderizado de contenido OpenGL para este widget estableciendo como contexto actual el del búfer pasado como parámetro y vinculando el objeto de búfer de fotogramas a dicho contexto.
Nota: Solo tiene sentido llamar aesta función cuando la representación estereoscópica está habilitada. No ocurrirá nada si se solicita el búfer derecho cuando está deshabilitada.
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()`.
Esta función se introdujo en Qt 6.5.
Véase también context(), paintGL() y doneCurrent().
[override virtual protected] int QOpenGLWidget::metric(QPaintDevice::PaintDeviceMetric metric) const
Reimplementa: QWidget::metric(QPaintDevice::PaintDeviceMetric m) const.
[override virtual protected] QPaintEngine *QOpenGLWidget::paintEngine() const
Reimplementa: ` QWidget::paintEngine()` const.
[override virtual protected] void QOpenGLWidget::paintEvent(QPaintEvent *e)
Reimplementa: ` QWidget::paintEvent` (`QPaintEvent *event)`.
Gestiona los eventos de pintura.
Al llamar a ` QWidget::update()` se enviará un evento de dibujo ` e`, lo que provocará la invocación de esta función. (Nota: esto es asíncrono y tendrá lugar en algún momento después de volver de ` update()`). A continuación, tras algunos preparativos, esta función llamará a la función virtual ` paintGL()` para actualizar el contenido del búfer de fotogramas de ` QOpenGLWidget`. A continuación, la ventana de nivel superior del widget compondrá la textura del búfer de fotogramas con el resto de la ventana.
[virtual protected] void QOpenGLWidget::paintGL()
Esta función virtual se invoca cada vez que es necesario dibujar el widget. 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 framebuffer, y se configura la ventana gráfica mediante una llamada a glViewport(). El marco de trabajo no establece ningún otro estado ni realiza ningún borrado ni dibujo.
La implementación por defecto realiza un glClear(). No se espera que las subclases invoquen la implementación de la clase base, sino que deben realizar el borrado por sí mismas.
Nota: Para garantizar la portabilidad, no se debe dar por sentado que el estado establecido en ` initializeGL()` persista. En su lugar, establece todo el estado necesario, por ejemplo, llamando a `glEnable()` en `paintGL()`. Esto se debe a que algunas plataformas, como WebAssembly con WebGL, pueden tener limitaciones en los contextos de OpenGL en determinadas situaciones, lo que puede dar lugar a que el contexto utilizado con el ` QOpenGLWidget ` se utilice también para otros fines.
Cuando QSurfaceFormat::StereoBuffers está habilitado, esta función se llamará dos veces: una vez por cada búfer. Consulta qué búfer está vinculado actualmente llamando a currentTargetBuffer().
Nota: El framebuffer de cada destino se dibujará incluso cuando el hardware no admita el renderizado estereoscópico. En la ventana solo será visible el búfer izquierdo.
Véase también initializeGL(), resizeGL() y currentTargetBuffer().
[override virtual protected] QPaintDevice *QOpenGLWidget::redirected(QPoint *p) const
[override virtual protected] void QOpenGLWidget::resizeEvent(QResizeEvent *e)
Reimplementa: QWidget::resizeEvent(QResizeEvent *event).
Gestiona los eventos de redimensionamiento que se pasan en el parámetro de evento de ` e `. Llama a la función virtual ` resizeGL()`.
Nota: Evita sobrescribir esta función en clases derivadas. Si ello no es posible, asegúrate de que también se invoque la implementación de ` QOpenGLWidget`. De lo contrario, el objeto framebuffer subyacente y los recursos relacionados no se redimensionarán correctamente, lo que provocará un renderizado incorrecto.
[virtual protected] void QOpenGLWidget::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`.
No es necesario llamar a makeCurrent() porque esto ya se ha hecho al invocar esta función. Además, el framebuffer también está vinculado.
Véanse también initializeGL() y paintGL().
[signal] void QOpenGLWidget::resized()
Esta señal se emite justo después de que se haya vuelto a crear el objeto framebuffer debido al cambio de tamaño del widget.
void QOpenGLWidget::setFormat(const QSurfaceFormat &format)
Establece el formato de superficie solicitado format.
Cuando el formato no se establece explícitamente mediante esta función, se utilizará el formato devuelto por ` QSurfaceFormat::defaultFormat()`. Esto significa que, al tener varios widgets de OpenGL, las llamadas individuales a esta función pueden sustituirse por una única llamada a ` QSurfaceFormat::setDefaultFormat()` antes de crear el primer widget.
Nota: Solicitar un búfer alfa mediante esta función no dará los resultados deseados cuando la intención sea hacer visibles otros widgets situados debajo. En su lugar, utiliza Qt::WA_AlwaysStackOnTop para habilitar instancias de QOpenGLWidget semitransparentes con otros widgets visibles debajo. Ten en cuenta, sin embargo, que esto altera el orden de superposición, por lo que ya no será posible tener otros widgets encima de QOpenGLWidget.
Véase también format(), Qt::WA_AlwaysStackOnTop y QSurfaceFormat::setDefaultFormat().
void QOpenGLWidget::setTextureFormat(GLenum texFormat)
Establece un formato de textura interno personalizado de texFormat.
Al trabajar con framebuffers sRGB, será necesario especificar un formato como GL_SRGB8_ALPHA8. Esto se puede conseguir llamando a esta función.
Nota: Esta función no tiene ningún efecto si se invoca después de que el widget ya se haya mostrado y, por lo tanto, haya realizado la inicialización.
Nota: Normalmente,esta función deberá utilizarse junto con una llamada a QSurfaceFormat::setColorSpace() que establezca el espacio de color en QColorSpace::SRgb.
Véase también textureFormat().
void QOpenGLWidget::setUpdateBehavior(QOpenGLWidget::UpdateBehavior updateBehavior)
Establece el comportamiento de actualización de este widget en « updateBehavior ».
Véase también updateBehavior().
GLenum QOpenGLWidget::textureFormat() const
Devuelve el formato de textura interno activo si el widget ya se ha inicializado; el formato solicitado, si se ha establecido alguno pero el widget aún no se ha hecho visible; o ` nullptr ` si no se ha llamado a ` setTextureFormat()` y el widget aún no se ha hecho visible.
Véase también ` setTextureFormat()`.
QOpenGLWidget::UpdateBehavior QOpenGLWidget::updateBehavior() const
Devuelve el comportamiento de actualización del widget.
Véase también ` setUpdateBehavior()`.
© 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.