/****************************************************************************
**
** Copyright (C) 2020 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-tool-shadergen.html
\title Shadergen Tool
\brief Command line tool for generating Qt Quick 3D material shaders at build-time.

The shadergen tool is a command line application that is part of Qt Quick 3D's
asset conditioning pipeline. It can be enable per project or run manually from the command line.
Pre-generating the material shaders can have a significant impact on the start-up time and/or avoid
unwanted stalls at run-time, as the processes of creating a material shader at run-time can be costly.

\note This tool is experimental and under development, but most common use-cases should work already.

One of the biggest obstacles for the offline shader generator is the amount of different materials
that can be generated, not only based on the material properties themeself but also how the rest of
the scene is set-up; for example, light count, light type, shadows, etc. all affect the generated
shader(s). When we also take \l{Dynamic properties} {dynamic properties} into account, the share amount
of material shader permutations can very quickly make it unfeasible to generate them all at build-time.
To limit the amount of shaders the tool needs to generate, the tool tries to only generate the shaders
it think the application needs. The heuristics used in the tool might not always be able to detect
which materials should be generate, this is espcecially true for properties that change at run-time.
To verify that the material shaders were successfully, and correctly, generated, the tool should have
generated a \l{Generated content}{.qsbc} file which can be inspected to verify that the content
matches the material used by the application. It's also possible to verify that the material
was loaded from the pre-built cache by setting the environment variable \b QT_RHI_SHADER_DEBUG=1
and looking at the debug output for mentions of the engine loading the \b pregenerated
shader successfully.

Known limitations are:
\list
  \li Scenes with more then one \l{View3D}.
  \li Dynamically adding or removing lights are not supported when using generating materials.
  \li The generated shaders are strictly tied to the Qt version used due to its dependency on
      the internals of the renderer. Compatibility of the generated shaders can therefore
      not be guaranteed between versions.
\endlist

\section1 Usage

To enable offline generation of material shaders in your project, add the following to your
project file:

CMake:
\code
qt6_quick3d_generate_materials(offlineshaders "shaders"
    PREFIX
        "/"
    FILES
        ${qml_resource_files}
)
\endcode

Alternatively the shadergen tool can be invoked manually from the command line, like this:

\code
shadergen main.qml Material.qml
\endcode

Normally the shadergen tool should be run from your application's project folder, but it's also
possible to instruct the tool to change its current working directory through the \c -C argument.

If no output path is provided then the tool will write the generated files to the current
directory. The output path can be changed with the \c -o option.

Note that for the tool to generate the expected materials it will need to know about the whole
scene and not just the material(s), for example the number of lights in the scene does also
affect how the materials get generated, so all relevant qml files should be added to the list of
files the tool needs to process.

\section2 Command line arguments

\table
  \header
    \li
      Short
    \li
      Full
    \li
      Description
  \row
    \li
      -C <PATH>
    \li
      --directory <PATH>
    \li
      Changes the current directory to \c <PATH>. This argument is optional.
  \row
    \li
      -o <PATH>
    \li
      --output-dir <PATH>
    \li
      Sets the output path to <PATH>. This is the location where the files generated by the tool
      will be placed under. If no path is given the path is current directory.
  \row
    \li
      -r <NAME>
    \li
      --resource-file <NAME>
    \li
      Changes the name of the generated resource file to \c <NAME>. This argument is optional.
  \row
    \li
      -l <FILE>
    \li
      --list-qsbc <FILE>
    \li
      List the content of the qsbc file.
\endtable

\section1 Generated content

The shadergen tools main output file is a .qsbc file. The .qsbc file contains a collection of
\l {Qt Shader Tools} {.qsb} files plus some meta-data about the various material shaders,
like the unique property string for each material.

\sa {Qt Shader Tools} {QtShaderTools}

The .qsbc file can be inspected by calling the shadergen tool with the \c -d argument:

\code
shadergen -d qtappshaders.qsbc
\endcode

\section1 Dynamic properties

Since the tool is run at build-time it has limited ability to reason about which properties
might change at run-time. Properties where a value is only changing within the properties range, for
example the roughness value, will not have any affect on the generated material shader, but properties
that are either \b on or \b off, e.g., setting an image map at run-time, would require a different type of
material to be generated. It is therefore recommended that all variants of a material, which enables
or disables features in the material, or the scene, are declared as individual components, this will
help the tool to generated the correct material shaders.

The following example shows a contrived example of a material where we want to add a base color
map to a material at run-time. Note that we don't actually use the MaterialRedExtended
component in this case, it's purely defined for the shadergen tool to generated the needed
material shaders that will be need at run-time to set the map on the \c redMaterial material.

MaterialRed.qml

\snippet offlineshaders/MaterialRed.qml baseMaterial

MaterialRedWithNormal.qml

\snippet offlineshaders/MaterialRedExtended.qml extendedMaterial

main.qml

\snippet offlineshaders/main.qml redMaterial

\snippet offlineshaders/main.qml setMap

*/
