QOpenGLContext Class
La clase `QOpenGLContext` representa un contexto nativo de OpenGL, lo que permite el renderizado OpenGL en un ` QSurface`. Más información...
| Encabezado: | #include <QOpenGLContext> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake: | QT += gui |
| Heredado de: | QObject |
- Lista de todos los miembros, incluidos los heredados
- QOpenGLContext forma parte de «Renderización en 3D».
Tipos públicos
| enum | OpenGLModuleType { LibGL, LibGLES } |
Funciones públicas
| QOpenGLContext(QObject *parent = nullptr) | |
| virtual | ~QOpenGLContext() |
| bool | create() |
| GLuint | defaultFramebufferObject() const |
| void | doneCurrent() |
| QSet<QByteArray> | extensions() const |
| QOpenGLExtraFunctions * | extraFunctions() const |
| QSurfaceFormat | format() const |
| QOpenGLFunctions * | functions() const |
| QFunctionPointer | getProcAddress(const QByteArray &procName) const |
| QFunctionPointer | getProcAddress(const char *procName) const |
| bool | hasExtension(const QByteArray &extension) const |
| bool | isOpenGLES() const |
| bool | isValid() const |
| bool | makeCurrent(QSurface *surface) |
| QNativeInterface * | nativeInterface() const |
| QScreen * | screen() const |
| void | setFormat(const QSurfaceFormat &format) |
| void | setScreen(QScreen *screen) |
| void | setShareContext(QOpenGLContext *shareContext) |
| QOpenGLContext * | shareContext() const |
| QOpenGLContextGroup * | shareGroup() const |
| QSurface * | surface() const |
| void | swapBuffers(QSurface *surface) |
Señales
| void | aboutToBeDestroyed() |
Miembros públicos estáticos
| bool | areSharing(QOpenGLContext *first, QOpenGLContext *second) |
| QOpenGLContext * | currentContext() |
| QOpenGLContext * | globalShareContext() |
| QOpenGLContext::OpenGLModuleType | openGLModuleType() |
| bool | supportsThreadedOpenGL() |
Descripción detallada
QOpenGLContext representa el estado OpenGL de un contexto OpenGL subyacente. Para configurar un contexto, establece su pantalla y su formato de modo que coincidan con los de la superficie o superficies con las que se pretende utilizar el contexto; si es necesario, haz que comparta recursos con otros contextos mediante ` setShareContext()` y, por último, llama a ` create()`. Utiliza el valor devuelto o ` isValid()` para comprobar si el contexto se ha inicializado correctamente.
Se puede establecer un contexto como actual respecto a una superficie determinada llamando a ` makeCurrent()`. Cuando finalice el renderizado de OpenGL, llame a ` swapBuffers()` para intercambiar los búferes delantero y trasero de la superficie, de modo que el contenido recién renderizado quede visible. Para poder dar soporte a determinadas plataformas, QOpenGLContext requiere que se vuelva a llamar a ` makeCurrent()` antes de comenzar a renderizar un nuevo fotograma, tras haber llamado a ` swapBuffers()`.
Si el contexto no se necesita temporalmente, por ejemplo, cuando la aplicación no está renderizando, puede resultar útil eliminarlo para liberar recursos. Puedes conectarte a la señal « aboutToBeDestroyed()» para liberar cualquier recurso que se haya asignado con una propiedad distinta a la del propio QOpenGLContext.
Una vez que se ha establecido un `QOpenGLContext` como contexto actual, se puede renderizar en él de forma independiente de la plataforma utilizando los habilitadores de OpenGL de Qt, como ` QOpenGLFunctions`, ` QOpenGLBuffer`, ` QOpenGLShaderProgram` y ` QOpenGLFramebufferObject`. También es posible utilizar directamente la API de OpenGL de la plataforma, sin recurrir a los habilitadores de Qt, aunque esto puede afectar a la portabilidad. Esto último es necesario cuando se desea utilizar OpenGL 1.x u OpenGL ES 1.x.
Para obtener más información sobre la API de OpenGL, consulta la documentación oficial de OpenGL.
Para ver un ejemplo de cómo utilizar QOpenGLContext, consulta el ejemplo «OpenGL Window ».
Afinidad de subprocesos
moveToThread() permite trasladar un QOpenGLContext a un hilo diferente. No llames a makeCurrent() desde un hilo distinto al que pertenece el objeto QOpenGLContext. Un contexto solo puede ser el activo en un hilo y para una superficie a la vez, y un hilo solo tiene un contexto activo a la vez.
Compartición de recursos entre contextos
Recursos como las texturas y los objetos de búfer de vértices se pueden compartir entre contextos. Utilice ` setShareContext()` antes de llamar a ` create()` para especificar que los contextos deben compartir estos recursos. QOpenGLContext realiza un seguimiento interno de un objeto ` QOpenGLContextGroup `, al que se puede acceder mediante ` shareGroup()` y que se puede utilizar para encontrar todos los contextos de un grupo de uso compartido determinado. Un grupo de uso compartido está formado por todos los contextos que se han inicializado correctamente y que comparten recursos con un contexto ya existente en dicho grupo. Un contexto que no comparte recursos tiene un grupo de uso compartido formado por un único contexto.
Bufé de fotogramas predeterminado
En determinadas plataformas, un framebuffer distinto de 0 podría ser el framebuffer por defecto, dependiendo de la superficie actual. En lugar de llamar a `glBindFramebuffer(0)`, se recomienda utilizar `glBindFramebuffer(ctx->defaultFramebufferObject()),` para garantizar que la aplicación sea portátil entre diferentes plataformas. Sin embargo, si utilizas ` QOpenGLFunctions::glBindFramebuffer()`, esto se realiza automáticamente.
Advertencia: WebAssembly
Recomendamos que solo se establezca como actual un QOpenGLContext mediante un QSurface durante todo el ciclo de vida del QSurface. En caso de que se utilice más de un contexto, es importante tener en cuenta que, en la plataforma WebAssembly, varias instancias de QOpenGLContext pueden estar respaldadas por el mismo contexto nativo subyacente. Por lo tanto, llamar a ` makeCurrent()` con el mismo ` QSurface ` en dos objetos `QOpenGLContext` puede hacer que no se cambie a un contexto nativo diferente en la segunda llamada. Como resultado, cualquier cambio en el estado de OpenGL realizado después de la segunda llamada a ` makeCurrent()` puede alterar también el estado del primer `QOpenGLContext`, ya que todos están respaldados por el mismo contexto nativo.
Nota: Esto significa que, al compilar para WebAssembly con código Qt existente basado en OpenGL, puede ser necesario realizar algunas adaptaciones para hacer frente a estas limitaciones.
Consideraciones de seguridad
Se espera que todos los datos utilizados por `QOpenGLContext` y las clases que se basan en él, como ` QOpenGLFunctions`, las clases del módulo ` QtOpenGL ` y ` QRhi ` con su backend de OpenGL, sean contenido de confianza. Esto incluye el código fuente de los shaders, los datos de vértices e índices, las texturas y otros datos de píxeles, así como todos los parámetros pasados a las funciones de OpenGL. Qt no valida ni depura nada de esto.
Ten en cuenta también que getProcAddress() devuelve un puntero de función sin procesar, resuelto por su nombre a partir de la implementación de OpenGL. Qt no puede comprobar que la firma a la que lo convierte el llamante coincida con la que proporciona la implementación; un error en este sentido da lugar a un comportamiento indefinido.
La implementación de OpenGL —es decir, el controlador y, en las plataformas que lo tienen, la biblioteca que lo invoca— es una dependencia de la plataforma de confianza, integrada en el proceso. Qt la carga y la invoca directamente, sin ningún tipo de aislamiento en un entorno de pruebas ni verificación, del mismo modo que trata la implementación de Vulkan.
La biblioteca que se carga viene determinada por el orden habitual de búsqueda de bibliotecas compartidas de la plataforma y, en algunas plataformas, por las variables de entorno. Esa selección forma parte de la configuración de confianza del despliegue: un despliegue que no la controle tampoco controla qué código nativo se ejecuta dentro del proceso.
Advertencia: Se recomienda a los desarrolladoresde aplicaciones que consideren cuidadosamente las posibles implicaciones antes de permitir la incorporación de contenido proporcionado por el usuario que no forme parte de la aplicación y no esté bajo el control de los desarrolladores.
Véase también QOpenGLFunctions, QOpenGLBuffer, QOpenGLShaderProgram y QOpenGLFramebufferObject.
Documentación sobre los tipos de miembro
enum QOpenGLContext::OpenGLModuleType
Esta enumeración define el tipo de la implementación subyacente de OpenGL.
| Constante | Valor | Descripción |
|---|---|---|
QOpenGLContext::LibGL | 0 | OpenGL |
QOpenGLContext::LibGLES | 1 | OpenGL ES 2.0 o superior |
Documentación de funciones de miembro
[explicit] QOpenGLContext::QOpenGLContext(QObject *parent = nullptr)
Crea una nueva instancia de contexto OpenGL con el objeto padre ` parent`.
Antes de poder utilizarla, es necesario establecer el formato adecuado y llamar a create().
Véanse también create() y makeCurrent().
[virtual noexcept] QOpenGLContext::~QOpenGLContext()
Destruye el objeto ` QOpenGLContext `.
Si este es el contexto actual del hilo, también se llama a ` doneCurrent()`.
[signal] void QOpenGLContext::aboutToBeDestroyed()
Esta señal se emite antes de que se destruya el contexto nativo de OpenGL subyacente, de modo que los usuarios puedan liberar los recursos de OpenGL que, de otro modo, podrían quedar pendientes en el caso de los contextos compartidos de OpenGL.
Si deseas establecer el contexto como actual para realizar la limpieza, asegúrate de conectarte a la señal únicamente mediante una conexión directa.
Nota: En Qt for Python, esta señal no se recibirá cuando se emita desde el destructor de QOpenGLWidget o QOpenGLWindow, ya que la instancia de Python ya habrá sido destruida. Recomendamos realizar las limpiezas en QWidget::hideEvent() en su lugar.
[static] bool QOpenGLContext::areSharing(QOpenGLContext *first, QOpenGLContext *second)
Devuelve « true » si los contextos « first » y « second » comparten recursos de OpenGL.
bool QOpenGLContext::create()
Intenta crear el contexto OpenGL con la configuración actual.
La configuración actual incluye el formato, el contexto compartido y la pantalla.
Si la implementación de OpenGL en tu sistema no admite la versión solicitada del contexto de OpenGL, QOpenGLContext intentará crear la versión más cercana. Las propiedades reales del contexto creado se pueden consultar mediante el objeto ` QSurfaceFormat ` devuelto por la función ` format()`. Por ejemplo, si solicitas un contexto que admita el perfil «Core» de OpenGL 4.3, pero el controlador o el hardware solo admiten contextos del perfil «Core» de la versión 3.2, obtendrás un contexto del perfil «Core» de la versión 3.2.
Devuelve « true » si el contexto nativo se ha creado correctamente y está listo para utilizarse con « makeCurrent()», « swapBuffers()», etc.
Nota: Si el contexto ya existe, esta función destruye primero el contexto existente y, a continuación, crea uno nuevo.
Véase también makeCurrent() y format().
[static] QOpenGLContext *QOpenGLContext::currentContext()
Devuelve el último contexto que llamó a ` makeCurrent ` en el hilo actual, o ` nullptr` si no hay ningún contexto activo.
GLuint QOpenGLContext::defaultFramebufferObject() const
Llama a esta función para obtener el objeto de framebuffer predeterminado de la superficie actual.
En algunas plataformas (por ejemplo, iOS), el objeto framebuffer predeterminado depende de la superficie en la que se está realizando el renderizado, y puede ser distinto de 0. Por lo tanto, en lugar de llamar a glBindFramebuffer(0), debes llamar a glBindFramebuffer(ctx->defaultFramebufferObject()) si quieres que tu aplicación funcione en diferentes plataformas de Qt.
Si utilizas la función glBindFramebuffer() de QOpenGLFunctions, no tienes que preocuparte por esto, ya que vincula automáticamente el defaultFramebufferObject() del contexto actual cuando se pasa el valor 0.
Nota: Los widgets que se representan mediante objetos de framebuffer, como QOpenGLWidget y QQuickWidget, anularán el valor devuelto por esta función cuando el proceso de dibujo esté activo, ya que en ese momento el framebuffer «predeterminado» correcto es el framebuffer de respaldo asociado al widget, y no el específico de la plataforma que pertenece a la superficie de la ventana de nivel superior. Esto garantiza el comportamiento esperado para esta función y otras clases que dependen de ella (por ejemplo, QOpenGLFramebufferObject::bindDefault() o QOpenGLFramebufferObject::release()).
Véase también QOpenGLFramebufferObject.
void QOpenGLContext::doneCurrent()
Función práctica para llamar a ` makeCurrent ` con una superficie igual a 0.
Esto hace que no haya ningún contexto activo en el hilo actual.
Véanse también ` makeCurrent()` y ` currentContext()`.
QSet<QByteArray> QOpenGLContext::extensions() const
Devuelve el conjunto de extensiones de OpenGL compatibles con este contexto.
El contexto o un contexto compartido debe estar activo.
Véase también hasExtension().
QOpenGLExtraFunctions *QOpenGLContext::extraFunctions() const
Obtén la instancia de QOpenGLExtraFunctions para este contexto.
QOpenGLContext Esto ofrece una forma cómoda de acceder a QOpenGLExtraFunctions sin tener que gestionarlo manualmente.
El contexto o un contexto compartido deben estar activos.
La instancia de « QOpenGLExtraFunctions » devuelta está lista para su uso y no es necesario llamar a `initializeOpenGLFunctions()`.
Nota: ` QOpenGLExtraFunctions ` contiene funcionalidades cuya disponibilidad en tiempo de ejecución no está garantizada. La disponibilidad en tiempo de ejecución depende de la plataforma, el controlador gráfico y la versión de OpenGL solicitada por la aplicación.
Véase también QOpenGLFunctions y QOpenGLExtraFunctions.
QSurfaceFormat QOpenGLContext::format() const
Devuelve el formato del contexto de la plataforma subyacente, si se ha llamado a create().
En caso contrario, devuelve el formato solicitado.
El formato solicitado y el real pueden diferir. Solicitar una versión determinada de OpenGL no significa que el contexto resultante vaya a corresponder exactamente a la versión solicitada. Solo se garantiza que la combinación de versión, perfil y opciones del contexto creado sea compatible con la solicitud, siempre y cuando el controlador sea capaz de proporcionar dicho contexto.
Por ejemplo, solicitar un contexto de perfil básico de OpenGL versión 3.x puede dar lugar a un contexto de perfil básico de OpenGL 4.x. Del mismo modo, una solicitud de OpenGL 2.1 puede dar lugar a un contexto de OpenGL 3.0 con funciones obsoletas habilitadas. Por último, dependiendo del controlador, las versiones no compatibles pueden dar lugar a un error en la creación del contexto o a un contexto para la versión más alta compatible.
Pueden darse diferencias similares en los tamaños de los búferes; por ejemplo, el contexto resultante puede tener un búfer de profundidad mayor que el solicitado. Esto es perfectamente normal.
Véase también setFormat().
QOpenGLFunctions *QOpenGLContext::functions() const
Obtén la instancia de QOpenGLFunctions para este contexto.
QOpenGLContext Esto ofrece una forma cómoda de acceder a QOpenGLFunctions sin tener que gestionarlo manualmente.
El contexto o un contexto compartido deben estar activos.
La instancia de ` QOpenGLFunctions ` devuelta está lista para su uso y no es necesario llamar a `initializeOpenGLFunctions()`.
QFunctionPointer QOpenGLContext::getProcAddress(const QByteArray &procName) const
Resuelve el puntero a una función de extensión de OpenGL, identificada por ` procName`.
Utiliza esta función para acceder a funciones de extensión de OpenGL o a funciones básicas que pueden no estar disponibles como símbolos enlazados en todas las plataformas.
El puntero devuelto puede depender de la plataforma. Algunos sistemas pueden devolver un puntero que no sea nullptr, incluso si la función no es válida o no está soportada.
Para comprobar de forma fiable la disponibilidad de una función, comprueba si la extensión es compatible llamando a ` QOpenGLContext::hasExtension()` (). Para las funciones básicas, comprueba la versión del contexto actual mediante ` version()` en el ` QSurfaceFormat ` devuelto por ` QOpenGLContext::format()` ().
QFunctionPointer QOpenGLContext::getProcAddress(const char *procName) const
Esta es una función sobrecargada.
[static] QOpenGLContext *QOpenGLContext::globalShareContext()
Devuelve el contexto OpenGL compartido por toda la aplicación, si existe. De lo contrario, devuelve ` nullptr`.
Esto resulta útil si necesitas cargar objetos OpenGL (búferes, texturas, etc.) antes de crear o mostrar un ` QOpenGLWidget ` o un ` QQuickWidget`.
Advertencia: No intentes establecer como contexto actual en ninguna superficie el contexto devuelto por esta función. En su lugar, puedes crear un nuevo contexto que comparta el contexto global y, a continuación, establecer ese nuevo contexto como actual.
Véase también Qt::AA_ShareOpenGLContexts, setShareContext() y makeCurrent().
bool QOpenGLContext::hasExtension(const QByteArray &extension) const
Devuelve ` true ` si este contexto de OpenGL admite el ` extension` de OpenGL especificado; en caso contrario, devuelve ` false `.
El contexto o un contexto compartido debe estar activo.
Véase también extensions().
bool QOpenGLContext::isOpenGLES() const
Devuelve «true» si el contexto es un contexto de OpenGL ES.
Si el contexto aún no se ha creado, el resultado se basa en el formato solicitado mediante setFormat().
Véanse también create(), format() y setFormat().
bool QOpenGLContext::isValid() const
Devuelve un valor si este contexto es válido, es decir, si se ha creado correctamente.
En algunas plataformas, el valor de retorno de ` false ` para un contexto que se había creado correctamente anteriormente indica que se ha perdido el contexto de OpenGL.
La forma habitual de gestionar los casos de pérdida de contexto en las aplicaciones es comprobar mediante esta función si ` makeCurrent()` falla y devuelve ` false`. Si esta función devuelve entonces ` false`, vuelve a crear el contexto OpenGL nativo subyacente llamando a ` create()`, vuelve a llamar a ` makeCurrent()` y, a continuación, reinicializa todos los recursos de OpenGL.
En algunas plataformas, las situaciones de pérdida de contexto no se pueden evitar. En otras, sin embargo, puede ser necesario activarlas de forma explícita. Esto se puede hacer habilitando ResetNotification en QSurfaceFormat. Esto provocará que RESET_NOTIFICATION_STRATEGY_EXT se establezca en LOSE_CONTEXT_ON_RESET_EXT en el contexto OpenGL nativo subyacente. A continuación, QOpenGLContext supervisará el estado mediante glGetGraphicsResetStatusEXT() en cada llamada a makeCurrent().
Véase también create().
bool QOpenGLContext::makeCurrent(QSurface *surface)
Establece el contexto como actual en el hilo actual, en relación con el surface especificado. Devuelve true si la operación se realiza correctamente; en caso contrario, devuelve false. Esto último puede ocurrir si la superficie no está expuesta o si el hardware gráfico no está disponible, por ejemplo, porque la aplicación se encuentra suspendida.
Si surface es nullptr, esto equivale a llamar a doneCurrent().
Evita llamar a esta función desde un hilo distinto al que alberga la instancia de ` QOpenGLContext `. Si deseas utilizar ` QOpenGLContext ` desde un hilo distinto, primero debes asegurarte de que no esté activa en el hilo actual, llamando a ` doneCurrent()` si es necesario. A continuación, llama a `moveToThread(otherThread)` antes de utilizarla en el otro hilo.
Por defecto, Qt realiza una comprobación que garantiza el cumplimiento de la condición anterior en cuanto a la afinidad de subprocesos. No obstante, es posible desactivar esta comprobación configurando el atributo de aplicación Qt::AA_DontCheckOpenGLContextThreadAffinity. Asegúrate de comprender las consecuencias de utilizar objetos QObject desde fuera del subproceso en el que residen, tal y como se explica en la documentación de QObject thread affinity.
Véase también ` functions()`, ` doneCurrent()` y ` Qt::AA_DontCheckOpenGLContextThreadAffinity`.
template <typename QNativeInterface> QNativeInterface *QOpenGLContext::nativeInterface() const
Devuelve una interfaz nativa del tipo indicado para el contexto.
Esta función proporciona acceso a la funcionalidad específica de la plataforma de ` QOpenGLContext`, tal y como se define en el espacio de nombres ` QNativeInterface `:
Interfaz nativa para un NSOpenGLContext en macOS | |
Interfaz nativa para un contexto EGL | |
Interfaz nativa para un contexto GLX | |
Interfaz nativa para un contexto WGL en Windows |
Si la interfaz solicitada no está disponible, se devuelve un objeto ` nullptr `.
[static] QOpenGLContext::OpenGLModuleType QOpenGLContext::openGLModuleType()
Devuelve el tipo de implementación subyacente de OpenGL.
En plataformas en las que la implementación de OpenGL no se carga dinámicamente, el valor de retorno se determina en tiempo de compilación y nunca cambia.
Nota: Es posible queuna implementación de OpenGL para ordenador de sobremesa también pueda crear contextos compatibles con ES. Por lo tanto, en la mayoría de los casos es más adecuado comprobar ` QSurfaceFormat::renderableType()` o utilizar la función de conveniencia ` isOpenGLES()`.
Nota: Esta función requiere que la instancia de ` QGuiApplication ` ya esté creada.
QScreen *QOpenGLContext::screen() const
Devuelve la pantalla para la que se creó el contexto.
Véase también setScreen().
void QOpenGLContext::setFormat(const QSurfaceFormat &format)
Establece el ` format ` con el que debe ser compatible el contexto de OpenGL. Es necesario llamar a ` create()` para que surta efecto.
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 contextos, las llamadas individuales a esta función pueden sustituirse por una única llamada a ` QSurfaceFormat::setDefaultFormat()` antes de crear el primer contexto.
Véase también format().
void QOpenGLContext::setScreen(QScreen *screen)
Establece el ` screen ` para el que debe ser válido el contexto de OpenGL. Es necesario llamar a ` create()` para que surta efecto.
Véase también screen().
void QOpenGLContext::setShareContext(QOpenGLContext *shareContext)
Hace que este contexto comparta texturas, sombreadores y otros recursos de OpenGL con shareContext. Es necesario llamar a create() para que surta efecto.
Véase también shareContext().
QOpenGLContext *QOpenGLContext::shareContext() const
Devuelve el contexto de uso compartido con el que se creó este contexto.
Si la plataforma subyacente no ha podido admitir el uso compartido solicitado, devolverá 0.
Véase también setShareContext().
QOpenGLContextGroup *QOpenGLContext::shareGroup() const
Devuelve el grupo de recursos compartidos al que pertenece este contexto.
[static] bool QOpenGLContext::supportsThreadedOpenGL()
Devuelve ` true ` si la plataforma admite el renderizado OpenGL fuera del hilo principal (GUI).
El valor viene determinado por el complemento de la plataforma que se esté utilizando y también puede depender de los controladores gráficos.
QSurface *QOpenGLContext::surface() const
Devuelve la superficie que se ha establecido como actual en el contexto.
Se trata de la superficie pasada como argumento a la función ` makeCurrent()`.
void QOpenGLContext::swapBuffers(QSurface *surface)
Intercambia los búferes delantero y trasero de ` surface`.
Llama a esta función para finalizar un fotograma de renderizado de OpenGL y asegúrate de volver a llamar a makeCurrent() antes de ejecutar cualquier otro comando de OpenGL, por ejemplo, como parte de un nuevo fotograma.
© 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.