Qt para Windows: aceleración gráfica
Para Qt Quick que funcione, se necesita un controlador gráfico compatible con Direct 3D 11, Direct3D 12, Vulkan 1.0 u OpenGL 2.1 o superior. A partir de Qt 6, el valor predeterminado de la variable de entorno ` Qt Quick ` en Windows es Direct3D 11. Esto difiere de Qt 5, donde el valor predeterminado era OpenGL, ya fuera directamente o a través de ANGLE, un traductor de OpenGL a Direct3D. ANGLE ya no se incluye con Qt en la versión 6.
Para forzar el uso del rasterizador de software de Direct3D (WARP), configura la variable de entorno ` QSG_RHI_PREFER_SOFTWARE_RENDERER ` con el valor ` 1`. En algunos casos, ` Qt Quick ` realizará este cambio automáticamente para permitir la ejecución de aplicaciones Qt sin necesidad de configuración adicional. Esto ocurre cuando los controladores no proporcionan un nivel suficiente de funcionalidad D3D11, y suele darse en máquinas virtuales que no cuentan con una aceleración por GPU adecuada ni con el «passthrough» implementado. En caso de duda sobre qué dispositivo gráfico se está utilizando, o al solucionar problemas o informar de ellos a Qt, ejecuta la aplicación con la variable de entorno QSG_INFO=1 establecida y revisa la salida de depuración. La ejecución de la herramienta « qtdiag » también puede proporcionar información útil, ya que enumera todas las API 3D disponibles.
Para solicitar el uso de Vulkan, OpenGL o Direct 3D 12, configura la variable de entorno QSG_RHI_BACKEND con el valor vulkan, opengl o d3d12, o utiliza el equivalente C++ API en main(). Ten en cuenta que algunas de estas API 3D pueden requerir la instalación de los controladores adecuados.
Aunque no es la opción predeterminada para Qt Quick, OpenGL sigue utilizándose habitualmente en muchas aplicaciones Qt, por ejemplo, en aplicaciones basadas en QWidget que se compilan en QOpenGLWindow o QOpenGLWidget. Las siguientes secciones tratan algunos aspectos específicos de OpenGL en una compilación de Qt.
Carga dinámica de OpenGL
Qt permite seleccionar y cargar la implementación de OpenGL en tiempo de ejecución. Este modo es el predeterminado y puede solicitarse explícitamente pasando -opengl dynamic al script de configuración.
configure -opengl dynamicEsta configuración es la más flexible, ya que no se codifican de forma rígida dependencias ni supuestos sobre la implementación de OpenGL durante la compilación. Permite una implementación robusta de la aplicación. Cuando un entorno determinado no proporciona una implementación adecuada de OpenGL 2.0, se recurrirá automáticamente a cargar una alternativa a « opengl32.dll », cuyo nombre por defecto es « opengl32sw.dll ». Los paquetes Qt precompilados incluyen una versión de Mesa llvmpipe, una implementación de OpenGL basada en un rasterizador de software, bajo ese nombre.
Cuando se configura con -opengl dynamic, ni Qt ni las aplicaciones compiladas utilizando qmake o CMake se vincularán a opengl32.lib. En su lugar, la biblioteca se selecciona y se carga en tiempo de ejecución. Por defecto, Qt determinará si el archivo opengl32.dll del sistema proporciona funciones de OpenGL 2. Si estas están presentes, se utiliza opengl32.dll; de lo contrario, intenta cargar opengl32sw.dll. Véanse más detalles a continuación.
El mecanismo de carga se puede configurar mediante la variable de entorno ` QT_OPENGL ` y los siguientes atributos de la aplicación:
Qt::AA_UseDesktopOpenGLEquivalente a establecerQT_OPENGLendesktop.Qt::AA_UseOpenGLESNo tiene ningún efecto en Qt 6.Qt::AA_UseSoftwareOpenGLEquivalente a establecerQT_OPENGLensoftware.
Cuando se solicita explícitamente una configuración determinada, no se realizan comprobaciones al iniciar la aplicación, es decir, no se examinará el archivo opengl32.dll proporcionado por el sistema.
La carga dinámica tiene un impacto significativo en las aplicaciones que contienen llamadas nativas a OpenGL: es posible que no se puedan enlazar, ya que opengl32.lib no se especifica automáticamente al enlazador. En su lugar, se espera que las aplicaciones utilicen las funciones de OpenGL a través de la clase ` QOpenGLFunctions `. De este modo, se elimina la dependencia directa de la biblioteca OpenGL y todas las llamadas se redirigirán en tiempo de ejecución a la implementación elegida por Qt. Como alternativa, las aplicaciones pueden realizar llamadas directas a las funciones de OpenGL si añaden opengl32.lib a sus archivos de proyecto .pro: LIBS += opengl32.lib (Visual Studio) o LIBS += -lopengl32 (Mingw-w64). El resultado, desde el punto de vista de la aplicación, es equivalente a la configuración de compilación « -opengl desktop » de Qt.
Qt::AA_UseSoftwareOpenGL es especial en el sentido de que intentará cargar una implementación de OpenGL con un nombre no estándar. El nombre por defecto es opengl32sw.dll. Esto permite distribuir una implementación de OpenGL exclusivamente de software, por ejemplo, una compilación de Mesa con llvmpipe, bajo este nombre. Si es necesario, el nombre del archivo se puede anular configurando la variable de entorno QT_OPENGL_DLL.
Es posible proporcionar un archivo de configuración en formato JSON que especifique qué implementación de OpenGL se debe utilizar en función de la tarjeta gráfica y la versión del controlador. La ubicación viene dada por la variable de entorno QT_OPENGL_BUGLIST. Las rutas relativas se resuelven utilizando QLibraryInfo::SettingsPath o QStandardPaths::ConfigLocation. El archivo utiliza el formato de la lista de errores de controladores empleada en los proyectos Chromium. Consiste en una lista de entradas, cada una de las cuales especifica un conjunto de condiciones y una lista de palabras clave de características. Normalmente, se utilizan el identificador del dispositivo y el identificador del fabricante para identificar una tarjeta gráfica concreta. Estos se pueden encontrar en la salida de la herramienta qtdiag6 o dxdiag.
Las siguientes palabras clave de características son relevantes para elegir la implementación de OpenGL:
Nota: En Qt 6, se aceptan las palabras clave heredadas relacionadas con ANGLE (disable_angle, disable_d3d11, disable_d3d9), pero no tienen ningún efecto.
disable_desktopgl- Desactiva OpenGL. Esto garantiza que Qt no intente utilizar OpenGL estándar (opengl32.dll) y que se inicie directamente con ANGLE. Esto resulta útil para evitar que unos controladores de OpenGL defectuosos provoquen el bloqueo de la aplicación.disable_rotation- Obliga a la aplicación a ejecutarse siempre en orientación horizontal. No tiene ningún efecto cuando se utiliza una implementación de OpenGL por software. Está pensado para controladores que presentan problemas con la rotación.disable_program_cache- Desactiva el almacenamiento de los binarios de los programas de sombreado en el disco.
Un archivo de ejemplo tiene el siguiente aspecto:
{
"entries": [
{
"id": 1,
"description": "Disable D3D11 on older nVidia drivers",
"os": {
"type": "win"
},
"vendor_id": "0x10de",
"device_id": ["0x0DE9"],
"driver_version": {
"op": "<=",
"value": "8.17.12.6973"
},
"features": [
"disable_d3d11"
]
},
...Cuando no se especifica ` QT_OPENGL_BUGLIST `, se utilizará una lista integrada. Esta suele incluir algunas tarjetas gráficas más antiguas y de menor capacidad con la opción ` disable_desktopgl ` activada, con el fin de evitar que Qt utilice sus implementaciones inestables de OpenGL de escritorio y, en su lugar, recurra inmediatamente a intentar cargar la biblioteca alternativa basada en software.
En la práctica, se espera que las combinaciones más comunes sean las siguientes:
disable_desktopgl- En caso de que el sistema ofrezca OpenGL 2.0 o una versión más reciente, pero se sepa que el controlador es inestable y propenso a fallar.disable_desktopgl, disable_angle: cuando no se desea utilizar la ruta acelerada. Esto garantiza que la única opción que pruebe Qt sea el rasterizador de software (opengl32sw.dll). Puede resultar útil en máquinas virtuales y aplicaciones que se implementan en una amplia gama de sistemas antiguos.
Las claves compatibles para identificar una tarjeta o un controlador concretos son las siguientes. Ten en cuenta que algunas de ellas son específicas de Qt.
os.type- Sistema operativo:win,linux,macosx,androidos.version- Versión del núcleoos.release- Especifica una lista de versiones del sistema operativo en Windows:xp,vista,7,8,8.1,10.vendor_id- Fabricante según el identificador del adaptadordevice_id- Lista de ID de dispositivos PCI.driver_version- Versión del controlador a partir del identificador del adaptadordriver_description- Coincide cuando el valor es una subcadena de la descripción del controlador a partir del identificador del adaptadorgl_vendor- Coincide cuando el valor es una subcadena de la cadena «GL_VENDOR»
Para desactivar todas las listas negras, establece la variable de entorno QT_NO_OPENGL_BUGLIST en cualquier valor. De este modo, se omitirá la lectura de cualquier archivo de configuración y, en su lugar, se asumirá que nada está desactivado, independientemente del controlador o del sistema operativo.
Nota: Aunque no suele ser necesario, QT_NO_OPENGL_BUGLIST puede resultar relevante en determinados entornos virtuales en los que haya varios adaptadores gráficos, posiblemente virtuales. Si los registros de categorías como qt.qpa.gl indican que la detección del controlador y del adaptador de pantalla provoca que OpenGL se desactive incorrectamente, se recomienda establecer esta variable de entorno para que la aplicación pueda ejecutarse con normalidad. Esta variable de entorno se introdujo en Qt 5.15.
Dependencia directa de opengl32.dll
Una alternativa a las compilaciones predeterminadas de OpenGL con « dynamic » es depender directamente de opengl32.dll. Para este modo, se deben pasar las opciones de línea de comandos -opengl desktop al script de configuración.
configure -opengl desktopNota: El uso de EGL y OpenGL ES no está soportado en Windows. En Qt 6, OpenGL en Windows implica siempre el uso de WGL como interfaz del sistema de ventanas.
En dichas compilaciones de Qt, muchas bibliotecas compartidas de Qt, así como las propias aplicaciones de Qt, tendrán una dependencia de opengl32.dll, por lo que no es posible utilizar una biblioteca alternativa.
© 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.