/****************************************************************************
**
** Copyright (C) 2021 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the Qt Shader Tools module
**
** $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$
**
****************************************************************************/

/*!
\title Qt Shader Tools
\page qtshadertools-index.html

\section1 Introduction

The Qt Shader Tools module builds on the SPIR-V Open Source Ecosystem as
described at \l{https://www.khronos.org/spir/}{the Khronos SPIR-V web site}. For
compiling into SPIR-V \l{https://github.com/KhronosGroup/glslang}{glslang} is
used, while translating and reflecting is done via
\l{https://github.com/KhronosGroup/SPIRV-Cross}{SPIRV-Cross}.

In order to allow shader code to be written once in Qt applications and
libraries, all shaders are expected to be written in a single language which is
then compiled into SPIR-V. This shading language is Vulkan-compatible GLSL at
the moment. This is different from the OpenGL-style GLSL Qt 5.x expects. See the
\l{https://github.com/KhronosGroup/GLSL/blob/master/extensions/khr/GL_KHR_vulkan_glsl.txt}{GL_KHR_vulkan_glsl
specification} for an overview of the differences.

Source code for other shading languages, such as, GLSL, HLSL and the Metal
Shading Language, are then generated from translating the SPIR-V bytecode,
together with reflection information (inputs, outputs, shader resources). For
GLSL in particular, this also involves generating multiple variants, meaning
source code suitable for different GLSL versions, such as, GLSL ES 100, GLSL ES
300, GLSL 120, 150, etc. This is then all packed into serializable QShader
container objects, typically stored in disk in form of files an extension of
\c{.qsb}. The Qt Rendering Hardware Interface consumes QShader instances
directly, picking the shader source or bytecode that is best suited for the
graphics API used at run time. A QShader object is typically deserialized from
\c{.qsb} files shipped with the application or Qt itself in the Qt Resource
System.

Some platforms provide the option of compiling shader source code to an
intermediate format similar to SPIR-V. This involves running platform-specific
tools. With Direct 3D, the \c qsb tool provides the option to invoke
\l{https://docs.microsoft.com/en-us/windows/win32/direct3dtools/fxc}{the fxc
tool from the Windows SDK} once the HLSL source code has been generated. It then
replaces the HLSL source code with the \c DXBC binary generated by \c fxc. This
can have a positive effect on applications' run time performance since they no
longer need to do the first phase of compilation (HLSL source to DXBC)
themselves. For macOS and iOS the
\l{https://developer.apple.com/documentation/metal/libraries/building_a_library_with_metal_s_command-line_tools?language=objc}{XCode
SDK provides similar tools}. The downside of this approach that running these
tools is only possible on their respective platforms. Therefore, this is best
suited for use in combination with qsb's CMake integration since doing shader
conditioning at application build time implicitly comes with the knowledge
needed about the target platform and what platform-specific tools can be
invoked.

The following diagram describes the steps that happen during an invocation of
the \c qsb tool:

\image shaderconditioning.png

The main components of the Qt shader conditioning system are:

\list
\li the \c qsb command-line tool
\li CMake integration for the \c qsb tool
\li QShader (part of the QtGui module)
\li QShaderBaker (part of this module, the library equivalent of the \c qsb tool)
\endlist

\note As of Qt \QtVer, the C++ APIs are considered private. They are not
recommended for direct usage from applications. Rather, use the \c qsb
command-line tool either directly, or indirectly from CMake projects.

\section1 Typical Usage with Qt Quick

Application developers typically encounter the need to work with custom shader
code in Qt Quick scenes that have:

\list

\li \l ShaderEffect items, or

\li \l QQuickItem subclasses that use scene graph nodes in combination with custom
materials built by subclassing \l QSGMaterial.

\endlist

For example, consider the following QML snippet:

\qml
ShaderEffect {
    width: 100; height: 100
    fragmentShader: "myeffect.frag.qsb"
}
\endqml

Here the \l{ShaderEffect::fragmentShader}{fragmentShader} URL refers to a
\c{.qsb} file relative to the \c{.qml} file's location. The application is
expected to ship \c{myeffect.frag.qsb} next to the \c{.qml} file. To generate
that file from the Vulkan-style GLSL source (which itself does not need to be
shipped with the application), the application must use the \c qsb tool either
directly or via CMake.

\section1 Typical Usage with Qt Quick 3D

Qt Quick 3D uses the Shader Tools module directly to perform shader conditioning
at run time. In addition, it provides solutions for pre-generating shaders for
materials at build time, in case a run time dependency to shader compilers and
other tools is not seen ideal. In either case developers do not need to work
directly with the \c qsb tool since it is encapsulated by the Qt Quick 3D's own
framework and tools.

\section1 Licenses and Attributions

Qt Shader Tools is available under commercial licenses from \l{The Qt Company}.
In addition, it is available under the
\l{GNU General Public License, version 3}.
See \l{Qt Licensing} for further details.

Furthermore, Qt Shader Tools in \QtVersion may contain third party
modules under following permissive licenses:

\generatelist{groupsbymodule attributions-qtshadertools}

\section1 Guides and Other Information

\list
    \li \l {QSB Manual}
    \li \l {Qt Shader Tools Build System Integration}
    \li \l {Qt Shader Tools C++ Classes}
\endlist

*/
