/****************************************************************************
**
** Copyright (C) 2020 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of Qt Design Studio.
**
** $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 studio-3d-custom-effects-materials.html
    \previouspage studio-3d-custom-shaders.html
    \nextpage studio-3d-lights.html

    \title Creating Custom Effects and Materials

    The \l{Applying 3D Effects}{Qt Quick 3D Effects} and \l{Using 3D Materials}
    {Qt Quick 3D Materials} modules contain a set of ready-made effects and
    materials that you can apply to 3D models. If the ready-made effects and
    materials don't meet your needs, you can create custom effects and
    materials. Each effect or material must have a fragment shader that
    implements all the functions needed to calculate the shaded color. The
    material system also offers ready-made functions to help you implement
    the material.

    The material system supports dielectric, metallic, and transparent
    materials, point lights, area lights, ambient occlusion, shadowing,
    two-sided polygons, index-of-refraction, and fragment cutoff (masking).
    For more information, see \l {Qt Quick 3D Custom Material Reference}.

    You can use the QML types in the \uicontrol {Qt Quick 3D Custom Shader Utils}
    tab of \uicontrol Library to create custom effects and materials. To make
    the \uicontrol Effect and \uicontrol {Custom Material} types appear in the
    tab, you must select \uicontrol {Add Import} in the \uicontrol {QML Imports}
    tab, and then select \uicontrol QtQuick3D.Effects and
    \uicontrol QtQuick3D.Materials to import the QML types in those modules to
    your project.

    For more information about the shader utilities and commands and their
    properties, see \l {Using Custom Shaders}.

    \image studio-qtquick-3d-shader-utilities.png "Qt Quick 3D Custom Shader Utils tab in Library"

    \note You must create the actual shader source files with some other tool
    and copy them to your project folder. You can then specify the source file
    names in the custom effect or material properties. To use custom \e uniforms
    in the shader files, you must specify them as QML properties for the custom
    effect or material component. \QDS automatically generates the uniforms for
    the shaders based on the property values.

    \section1 Creating Custom Effects

    By default, a custom effect component contains a Pass type and a Shader
    type in the fragment stage. You can add passes, shaders, and other shader
    utilities to the effect.

    \image studio-qtquick-3d-custom-effect-navigator.png "Custom effect in Navigator"

    The fragment shader component is created with a placeholder for the path
    to the shader file. Specify the path to the shader file to use in the
    shader properties.

    To create a custom effect:

    \list 1
        \li Drag and drop an \uicontrol {Effect} type from the
            \uicontrol {Qt Quick 3D Custom Shader Utils} tab of
            \uicontrol Library to a Model component in \uicontrol Navigator.
        \li Select the custom effect component in \uicontrol Navigator to edit
            the values of its properties in the \uicontrol Properties view.
            \image studio-qtquick-3d-custom-effect.png "Custom effect properties"
        \li In the \uicontrol Passes field, select the pass components for
            the effect.
        \li Select the pass component in \uicontrol Navigator to specify values
            for its properties in \uicontrol Properties.
            \image studio-qtquick-3d-pass.png "Pass properties"
        \li To execute commands during the pass, drag and drop the following
            command types from \uicontrol Library to the custom material in
            \uicontrol Navigator: \uicontrol Blending, \uicontrol {Buffer Blit},
            \uicontrol {Buffer Input}, \uicontrol {Cull Mode},
            \uicontrol {Depth Input}, \uicontrol {Render State}, and
            \uicontrol {Set Uniform Value}. Then select the commands in the
            \uicontrol Commands field.
        \li To allocate a buffer for the pass, drag and drop a \uicontrol Buffer
            type to the custom material. Then select the buffer in the
            \uicontrol Buffer field.
        \li Select the shader component in \uicontrol Navigator to set the path
            to the shader files in the \uicontrol Source field in
            \uicontrol Properties.
            \image studio-qtquick-3d-shader-properties.png "Shader properties"
    \endlist

    \section1 Creating Custom Materials

    By default, a Custom Material component contains two Shader types, a Shader
    Info type, and a Pass type. You can add shaders, passes, and other shader
    utilities to the material.

    \image studio-qtquick-3d-custom-material-navigator.png "Custom material in Navigator"

    By default, fragment and vertex shaders are created with placeholders for
    the paths to the shader files. Specify the paths to the shader files to use
    in the shader properties.

    The Shader Info type specifies the shader type and version, as well
    as the options used by the shader based on the selected shader key values,
    such as diffuse or specular lighting, refraction, transparency, displacement,
    transmissiveness, glossiness, and alpha cutout.

    The shaders are used with the Pass type to create the resulting material.
    A pass can contain multiple rendering passes and other commands. You can
    use a Buffer type to allocate a buffer for storing intermediate rendering
    results.

    To create a custom material:

    \list 1
        \li Drag and drop a \uicontrol {Custom Material} type from the
            \uicontrol {Qt Quick 3D Custom Shader Utils} tab of
            \uicontrol Library to a Model component in \uicontrol Navigator.
        \li Select the custom material component in \uicontrol Navigator to
            edit the values of its properties in the \uicontrol Properties view.
            \image studio-qtquick-3d-custom-material.png "Custom material properties"
        \li Select the \uicontrol Transparency check box to make the material
            transparent.
        \li Select the \uicontrol Refraction check box to specify that the
            material is \l{Using Highlights and Reflections}{reflective}.
        \li Select the \uicontrol {Always dirty} check box to determine that
            the material needs to be refreshed every time it is used.
        \li In the \uicontrol {Shader Info} field, select the shader info
            type to use.
        \li In the \uicontrol Passes field, select the pass components for
            the effect.
        \li In the \uicontrol Material group, select the
            \l{Using Highlights and Reflections}{light probe},
            \l{Simulating Geometry Displacement}{displacement map and amount},
            and \l{Culling Faces}{culling mode} to use.
        \li Select the shader info component in \uicontrol Navigator to specify
            values for its properties in \uicontrol Properties.
            \image studio-qtquick-3d-shader-info.png "Shader Info properties"
        \li Select the pass component in \uicontrol Navigator to specify values
            for its properties in \uicontrol Properties.
            \image studio-qtquick-3d-pass.png "Pass properties"
        \li To execute commands during the pass, drag and drop the following
            command types from \uicontrol Library to the custom material in
            \uicontrol Navigator: \uicontrol Blending, \uicontrol {Buffer Blit},
            \uicontrol {Buffer Input}, \uicontrol {Cull Mode},
            \uicontrol {Depth Input}, \uicontrol {Render State}, and
            \uicontrol {Set Uniform Value}. Then select the commands in the
            \uicontrol Commands field.
        \li To allocate a buffer for the pass, drag and drop a \uicontrol Buffer
            type to the custom material. Then select the buffer in the
            \uicontrol Buffer field.
        \li Select the shader components in \uicontrol Navigator to set the
            paths to the shader files in the \uicontrol Source field in
            \uicontrol Properties.
            \image studio-qtquick-3d-shader-properties.png "Shader properties"
    \endlist

    \section1 Creating Shader Files

    The requirements set for shaders that you can use in custom effects and
    materials are described in \l {Qt Quick 3D Custom Material Reference}.

    If you use custom uniforms in the shader files, you must specify them
    as QML properties for the custom effect or material component. \QDS
    automatically generates the uniforms based on the property values.

    For example, the following code snippet shows fragment shader code that
    uses two uniforms: \c uTextureInUse and \c uInputTexture.

    \code
    out vec4 fragColor;

    in vec3 pos;
    in vec3 texCoord0;

    void main() {

        vec4 textCol;
        if (uTextureInUse)
            textCol = texture( uInputTexture, texCoord0.xy );

        fragColor = vec4(pos.x * 0.02 * textCol.x, pos.y * 0.02 * textCol.y, pos.z * 0.02, 1.0);
    }
    \endcode

    To use the above fragment shader in a custom effect or material component,
    you must remove the uniforms from the shader code and define them as
    properties for the component in \uicontrol {Connection View} >
    \uicontrol Properties.

    \image studio-custom-material-uniform-properties.png "Uniforms as properties in Connection View Properties tab"

    For more information about adding properties, see
    \l{Specifying Dynamic Properties}.
*/