Qt Quick 3D Graphics Requirements
Supported graphics APIs, versions, and shading languages
Qt Quick 3D supports operating with all the graphics APIs and shading languages supported by Qt Quick in Qt 6.0. In some cases, with OpenGL and OpenGL ES in particular, the version requirement may be higher for Qt Quick 3D than for Qt Quick.
- OpenGL 3.0 or higher; OpenGL 3.3 or higher is strongly recommended
- OpenGL ES 2.0 or higher; OpenGL ES 3.0 or higher is strongly recommended
- Direct3D 11.1
- Direct3D 12
- Vulkan 1.0 or higher
- Metal 1.2 or higher
The shader pipeline is based on the standard approach of Qt 6: Vulkan-compatible GLSL shader code is compiled to SPIR-V, which is then translated to GLSL, HLSL, and MSL source code. Refer to the Qt Shader Tools module documentation for details.
Qt Quick 3D does not directly work with any of the graphics APIs mentioned above. Rather, it uses the Qt Rendering Hardware Interface abstractions, similarly to Qt Quick.
Choosing the graphics API
As Qt Quick 3D does not initialize rendering or a window on its own, but rather relies on QQuickWindow or QQuickView or the Window QML type, everything related to graphics API selection that applies to the Qt Quick Scene Graph applies to Qt Quick 3D as well. It is possible to control the behavior of the scene graph by setting specific environment variables as listed below:
| Environment Variable | Possible Values | Description |
|---|---|---|
QSG_RHI_BACKEND | vulkan, metal, opengl, d3d11, d3d12 | Requests the specific RHI backend. By default the targeted graphics API is chosen based on the platform, unless overridden by this variable or the equivalent C++ APIs. The defaults are currently Direct3D 11 for Windows, Metal for macOS, OpenGL elsewhere. |
QSG_RHI_DEBUG_LAYER | 1 | Where applicable (Vulkan, Direct3D), enables the graphics API implementation's debug and/or validation layers, if available. |
QSG_INFO | 1 | Like with the OpenGL-based rendering path, setting this enables printing system information when initializing the Qt Quick scene graph. This can be very useful for troubleshooting. |
Applications wishing to always run with a single given graphics API can request this via the QSG_RHI_BACKEND enivronment variable, as well as with C++. For example, the following call made early in main(), before constructing any QQuickWindow, forces the use of Vulkan (and will fail otherwise).
QQuickWindow::setGraphicsApi(QSGRendererInterface::Vulkan);
Note: The software adaptation of Qt Quick is not supported for 3D content.
OpenGL specifics
Well written Qt Quick 3D applications are expected to call QQuick3D::idealSurfaceFormat() in their main() function, and use the returned QSurfaceFormat as the default:
QSurfaceFormat::setDefaultFormat(QQuick3D::idealSurfaceFormat());
Calling this has no effect when a graphics API other than OpenGL is used, but is highly beneficial when the API is OpenGL as it will lead to creating an OpenGL context that is best suited for Qt Quick 3D's needs.
OpenGL ES 2.0 support
Qt Quick 3D supports running on OpenGL ES 2.0, but with a significantly limited feature set. The following list contains some of the features that will be unavailable or disfunctional:
- Image based lighting, light probes, skybox
- Shadow mapping
- Screen space ambient occlusion
- Multisampling
- Certain post-processing effects
- Custom materials that use shaders relying on GLSL features not present in GLSL ES 100
Note: Qt Quick 3D requires OpenGL ES 3.0 / WebGL 2 on the WebAssembly platform. OpenGL ES 2.0 / WebGL 1 is not supported.