// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page studio-3d-custom-effects-materials.html
    \previouspage studio-3d-custom-shaders.html
    \nextpage studio-3d-lights.html

    \title Custom effects and materials in Qt 5

    Use custom shader utilities to create custom effects in previous \QDS
    versions built with \uicontrol {Qt 5} and \uicontrol {Qt 5.15}.

    \note To learn how to use and create effects in \QDS projects built
    with \uicontrol {Qt 6} as \uicontrol {Target Qt Version}, see \l Effects.

     \section1 Creating custom effects and materials

    Create custom effects and materials using the \l{Custom shaders in Qt 5}
    {custom shader utilities} available in \uicontrol Components >
    \uicontrol {Qt Quick 3D Custom Shader Utilities}. Each effect or material
    must have a fragment shader that completes all the functions needed to calculate
    the shaded color. The material system also offers ready-made functions to help you
    implement the material.

    You can create 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}.

    \section2 Creating custom effects

    \note Use the method described here to create custom effects in \QDS 4.0 or older
    versions in projects created with \uicontrol {Qt 5} or \uicontrol {Qt 5.15} as
    \uicontrol {Target Qt Version}.

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

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

    The fragment shader component has a placeholder for the path to the shader file.
    You need to create shader files in code. For more information,
    see \l {Creating Shader Files}. Specify the path to the shader file to use in the
    \uicontrol Properties view.

    To create a custom effect:

    \list 1
        \li Drag an \uicontrol Effect component from \uicontrol Components
            > \uicontrol {Qt Quick 3D Effects} >
            \uicontrol {Qt Quick 3D Custom Shader Utilities} to a model
            component in \l Navigator.
        \li Select the \uicontrol Effect component in \uicontrol Navigator
            to adjust the values of its properties in the \l Properties view.
            \image studio-qtquick-3d-custom-effect.png "Custom effect properties"
        \li Use the \uicontrol Passes property to select the pass components for
            the effect.
        \li Select the \uicontrol renderPass component in \uicontrol Navigator to
            specify values for its properties in \uicontrol Properties.
            \image studio-qtquick-3d-pass.png "Pass properties"
        \li To run commands during the pass, drag the following
            command components from \uicontrol Components >
            \uicontrol {Qt Quick 3D Custom Shader Utilities} to \uicontrol Effect
            > \uicontrol renderPass in \uicontrol Navigator:
            \list
                \li \uicontrol Blending
                \li \uicontrol Buffer
                \li \uicontrol {Buffer Blit}
                \li \uicontrol {Buffer Input}
                \li \uicontrol {Cull Mode}
                \li \uicontrol {Depth Input}
                \li \uicontrol {Render State}
                \li \uicontrol {Set Uniform Value}
            \endlist
        \li Select the \uicontrol fragShader component in \uicontrol Navigator >
            \uicontrol Effect to set the path to the shader files using the
            \uicontrol Source property in \uicontrol Properties.
            \image studio-qtquick-3d-shader-properties.webp "Shader properties"
    \endlist

    \section1 Creating custom materials

    \note Use the method described here to create custom materials in \QDS 3.4 or
    older versions in projects created with \uicontrol {Qt 5} or \uicontrol {Qt 5.15}
    as \uicontrol {Target Qt Version}.

    By default, the \uicontrol {Custom Material} component contains two \uicontrol Shader
    components, a \uicontrol {Shader Info}, and a \uicontrol Pass component. 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 have placeholders for the paths to the
    shader files. Specify the paths to the shader files to use in the shader properties.

    The \uicontrol {Shader Info} component specifies the shader component 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.

    Use shaders with the \uicontrol Pass component to customize the material.
    A pass can contain multiple rendering passes and other commands. Use a
    \uicontrol Buffer component to allocate a buffer for storing intermediate
    rendering results.

    To create a custom material:

    \list 1
        \li Drag a \uicontrol {Custom Material} component from
            \uicontrol Components > \uicontrol {Qt Quick 3D Custom Shader Utils}
            to a model component in \uicontrol Navigator.
        \li Select the \uicontrol {Custom Material} component in \uicontrol Navigator
            to adjust 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, and \uicontrol Refraction to specify that the
            material is \l{Using Highlights and Reflections}{reflective}.
        \li Select the \uicontrol {Always dirty} check box to refresh the
            the material every time it is used.
        \li In the \uicontrol {Shader Info} field, select the shader info
            component to use, and 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 \uicontrol shaderInfo component in \uicontrol Navigator
            to adjust the values for its properties in \uicontrol Properties.
            \image studio-qtquick-3d-shader-info.png "Shader Info properties"
        \li Select the \uicontrol renderPass component in \uicontrol Navigator
            to adjust the values for its properties in \uicontrol Properties.
            \image studio-qtquick-3d-pass.png "Pass properties"
        \li To execute commands during the pass, drag the following command
            components from \uicontrol Components to the \uicontrol renderPass
            component in \uicontrol Navigator:
            \list
                \li \uicontrol Blending
                \li \uicontrol {Buffer Blit}
                \li \uicontrol {Buffer Input}
                \li \uicontrol {Cull Mode},
                \li \uicontrol {Depth Input}
                \li \uicontrol {Render State}
                \li \uicontrol {Set Uniform Value}
            \endlist
            \QDS creates the command components at the same level as the pass component
            and automatically adds them to the \uicontrol Commands field.
        \li To allocate a buffer for the pass, drag a \uicontrol Buffer
            component to the \uicontrol {Custom Material} component. Then select
            the buffer in the \uicontrol Buffer field.
        \li To add a shader to a pass, drag a \uicontrol Shader
            component from \uicontrol Components to the pass component in
            \uicontrol Navigator. \QDS creates the shader components at the same
            level as the pass component and automatically adds them to the
            \uicontrol Shaders 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.webp "Shader properties"
    \endlist
*/
