qtquick3d-requirements.qdoc

Go to the documentation of this file.

// Copyright (C) 2019 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
 
/*!
\page qtquick3d-requirements.html
\title Qt Quick 3D Graphics Requirements
\brief OpenGL requirements and considerations
 
\section1 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.
 
\list
\li \l{https://www.khronos.org/opengl/}{OpenGL} 3.0 or higher; OpenGL 3.3 or higher is strongly recommended
\li \l{https://www.khronos.org/opengles/}{OpenGL ES} 2.0 or higher; OpenGL ES 3.0 or higher is strongly recommended
\li \l{https://docs.microsoft.com/en-us/windows/win32/direct3d11/atoc-dx-graphics-direct3d-11}{Direct3D 11.1}
\li \l{https://learn.microsoft.com/en-us/windows/win32/direct3d12/what-is-directx-12-}{Direct3D 12}
\li \l{https://www.khronos.org/vulkan/}{Vulkan} 1.0 or higher
\li \l{https://developer.apple.com/metal/}{Metal} 1.2 or higher
\endlist
 
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 \l{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.
 
\section2 Choosing the graphics API
 
As Qt Quick 3D does not initialize rendering or a window on its own, but rather
relies on \l QQuickWindow or \l QQuickView or the \l Window QML type, everything
related to graphics API selection that applies to the
\l{qtquick-visualcanvas-scenegraph.html}{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:
 
\table 100%
\header
  \li Environment Variable
  \li Possible Values
  \li Description
 
  \row
   \li \c QSG_RHI_BACKEND
   \li \c vulkan, \c metal, \c opengl, \c d3d11, \c d3d12
   \li 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.
 
  \row
   \li \c QSG_RHI_DEBUG_LAYER
   \li \c 1
   \li Where applicable (Vulkan, Direct3D), enables the graphics API implementation's debug
   and/or validation layers, if available.
 
  \row
   \li \c QSG_INFO
   \li \c 1
   \li 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.
\endtable
 
Applications wishing to always run with a single given graphics API can request
this via the \c QSG_RHI_BACKEND enivronment variable, as well as with C++. For
example, the following call made early in \c main(), before constructing any
QQuickWindow, forces the use of Vulkan (and will fail otherwise).
 
\code
    QQuickWindow::setGraphicsApi(QSGRendererInterface::Vulkan);
\endcode
 
\note The \l{qtquick-visualcanvas-adaptations-software.html}{software
adaptation} of Qt Quick is not supported for 3D content.
 
\section2 OpenGL specifics
 
Well written Qt Quick 3D applications are expected to call
\l{QQuick3D::idealSurfaceFormat()} in their main() function, and use the
returned QSurfaceFormat as the default:
 
\code
    QSurfaceFormat::setDefaultFormat(QQuick3D::idealSurfaceFormat());
\endcode
 
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.
 
\section2 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:
 
\list
\li Image based lighting, light probes, skybox
\li Shadow mapping
\li Screen space ambient occlusion
\li Multisampling
\li Certain post-processing effects
\li Custom materials that use shaders relying on GLSL features not present in GLSL ES 100
\endlist
*/