/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
\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://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
   \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

\noautolist
*/
