QRhiGles2InitParams Struct
Parámetros de inicialización específicos de OpenGL. Más información...
| Cabecera: | #include <rhi/qrhi.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS GuiPrivate) target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate) |
| qmake: | QT += gui-private |
| Desde: | Qt 6.6 |
| Heredado de: | QRhiInitParams |
Funciones públicas
Variables públicas
| QSurface * | fallbackSurface |
| QSurfaceFormat | format |
| QOpenGLContext * | shareContext |
| QWindow * | window |
Miembros públicos estáticos
| QOffscreenSurface * | newFallbackSurface(const QSurfaceFormat &format = QSurfaceFormat::defaultFormat()) |
Descripción detallada
Nota: Se trata de una API de RHI con garantías de compatibilidad limitadas; consulta QRhi para obtener más detalles.
Un ` QRhi ` basado en OpenGL necesita un ` QSurface ` ya creado que pueda utilizarse en combinación con ` QOpenGLContext`. En la práctica, suele tratarse de un ` QOffscreenSurface `. Además, aunque es opcional, se recomienda pasar también el ` QWindow ` al que se dirigirá el primer ` QRhiSwapChain `.
QOffscreenSurface *fallbackSurface = QRhiGles2InitParams::newFallbackSurface();
QRhiGles2InitParams params;
params.fallbackSurface = fallbackSurface;
params.window = window;
rhi = QRhi::create(QRhi::OpenGLES2, ¶ms);Por defecto, QRhi crea un QOpenGLContext por sí mismo. Este enfoque funciona bien en la mayoría de los casos, incluidos los escenarios con subprocesos, en los que hay un QRhi dedicado para cada subproceso de renderizado. Dado que habrá un QOpenGLContext para cada QRhi, se cumplen los requisitos del contexto de OpenGL (un contexto solo puede ser el actual en un subproceso). El contexto creado implícitamente se destruye automáticamente junto con el QRhi.
El ` QSurfaceFormat ` del contexto se especifica en ` format`. El constructor lo establece en ` QSurfaceFormat::defaultFormat()` para que las aplicaciones que llamen a ` QSurfaceFormat::setDefaultFormat()` con la configuración adecuada antes de que se ejecute el constructor no tengan que cambiar el valor de ` format`.
Nota: Recuerda establecer los tamaños de los búferes de profundidad y de estencil en 24 y 8 cuando el renderizador utilice pruebas de profundidad o de estencil, ya sea en el valor predeterminado global QSurfaceFormat o, alternativamente, por separado en todas las instancias de QSurfaceFormat implicadas: en format, en el argumento de formato pasado a newFallbackSurface() y en cualquier QWindow que se utilice con el QRhi.
Es necesario especificar un ` QSurface ` en ` fallbackSurface`. Para evitar errores en entornos con subprocesos, el ` QRhi ` nunca lo crea automáticamente, ya que, al igual que ` QWindow`, las instancias de las subclases de ` QSurface ` a menudo solo pueden crearse en el hilo principal de la interfaz gráfica de usuario.
Para mayor comodidad, las aplicaciones pueden utilizar newFallbackSurface(), que crea y devuelve un QOffscreenSurface compatible con el QOpenGLContext que va a crear posteriormente el QRhi. Ten en cuenta que la propiedad del QOffscreenSurface devuelto se transfiere al llamante y que el QRhi no lo destruirá.
Nota: Con el backend de OpenGL, QRhiSwapChain solo puede dirigirse a instancias de QWindow cuyo tipo de superficie esté establecido en QSurface::OpenGLSurface.
Nota: ` window ` es opcional. Se recomienda especificarlo siempre que sea posible, para evitar problemas en sistemas con múltiples adaptadores y múltiples pantallas. Cuando no se establece ` window `, la primera llamada a ` QOpenGLContext::makeCurrent()` se realiza con ` fallbackSurface `, que puede ser una ventana invisible en algunas plataformas (por ejemplo, Windows) y que puede provocar problemas inesperados en algunos casos.
En caso de que se desee compartir recursos con un ` QOpenGLContext ` ya existente, ` shareContext ` puede establecerse en un ` QOpenGLContext` ya existente. Alternativamente, también se acepta ` Qt::AA_ShareOpenGLContexts `, siempre que esté habilitado.
Trabajar con contextos OpenGL existentes
Al interoperar con otro motor gráfico, puede ser necesario obtener una instancia de ` QRhi ` que utilice el mismo contexto de OpenGL. Esto se puede lograr pasando un puntero a un ` QRhiGles2NativeHandles ` a ` QRhi::create()`. En ese caso, ` QRhiGles2NativeHandles::context ` debe establecerse en un valor distinto de nulo.
Un enfoque alternativo consiste en crear un ` QOpenGLContext ` que ` shares resources ` con el contexto del otro motor y pasar ese contexto mediante ` QRhiGles2NativeHandles`.
El ` QRhi ` no asume la propiedad del ` QOpenGLContext ` pasado a través de ` QRhiGles2NativeHandles`.
Documentación de la función miembro
QRhiGles2InitParams::QRhiGles2InitParams()
Crea un nuevo objeto QRhiGles2InitParams.
format Se establece en ` QSurfaceFormat::defaultFormat()`.
[static] QOffscreenSurface *QRhiGles2InitParams::newFallbackSurface(const QSurfaceFormat &format = QSurfaceFormat::defaultFormat())
Devuelve un nuevo objeto ` QOffscreenSurface ` que se puede utilizar con un objeto ` QRhi ` pasándoselo a través de un objeto ` QRhiGles2InitParams`.
Cuando no se especifica ` format `, su valor por defecto es el formato global predeterminado que se puede configurar mediante ` QSurfaceFormat::setDefaultFormat()`.
format se ajusta según corresponda para evitar problemas posteriores debidos a un contexto y una superficie incompatibles.
Nota: Esta función solo debe invocarse en el hilo principal de la interfaz gráfica de usuario o si la integración de la plataforma admite superficies fuera de pantalla.
Nota: Es responsabilidad de la aplicación destruir el objeto ` QOffscreenSurface ` devuelto en el hilo GUI/principal una vez que se haya destruido el objeto ` QRhi ` asociado. El objeto ` QRhi ` no destruirá el objeto ` QOffscreenSurface`.
Documentación de las variables miembro
QSurface *QRhiGles2InitParams::fallbackSurface
Un ` QSurface ` compatible con ` format`. Normalmente, un ` QOffscreenSurface`. Es obligatorio proporcionar esto. Ten en cuenta las implicaciones relacionadas con los hilos: un ` QOffscreenSurface`, al igual que ` QWindow`, solo debe crearse y destruirse en el hilo principal (GUI), incluso si el ` QRhi ` se crea y funciona en otro hilo.
QSurfaceFormat QRhiGles2InitParams::format
El objeto ` QSurfaceFormat`, que por defecto se inicializa con ` QSurfaceFormat::defaultFormat()`.
QOpenGLContext *QRhiGles2InitParams::shareContext
Opcional: el objeto ` QOpenGLContext ` con el que compartir recursos. ` QRhi ` crea su propio contexto, y al asignar a este miembro un objeto válido de tipo ` QOpenGLContext `, se invoca el método ` setShareContext()` con dicho objeto.
QWindow *QRhiGles2InitParams::window
Es opcional, pero se recomienda configurarlo cuando se dirija a un QWindow con el QRhi.
© 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.