Creating Custom Effects and Materials

The Qt Quick 3D Effects and 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 Qt Quick 3D 自定义材质参考 .

You can use the QML types in the Qt Quick 3D Custom Shader Utils tab of Library to create custom effects and materials. To make the Effect and 自定义材质 types appear in the tab, you must select Add Import 在 QML 导入 tab, and then select QtQuick3D.Effects and 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 Using Custom Shaders .

注意： 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 uniforms in the shader files, you must specify them as QML properties for the custom effect or material component. Qt Design Studio automatically generates the uniforms for the shaders based on the property values.

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.

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:

1. Drag and drop an Effect type from the Qt Quick 3D Custom Shader Utils tab of Library to a Model component in Navigator .
2. Select the custom effect component in Navigator to edit the values of its properties in the 特性 view.

   

3. 在 Passes field, select the pass components for the effect.
4. Select the pass component in Navigator to specify values for its properties in 特性 .

   

5. To execute commands during the pass, drag and drop the following command types from Library to the custom material in Navigator : Blending , Buffer Blit , Buffer Input , Cull Mode , Depth Input , Render State ，和 Set Uniform Value . Then select the commands in the 命令 field.
6. To allocate a buffer for the pass, drag and drop a Buffer type to the custom material. Then select the buffer in the Buffer field.
7. Select the shader component in Navigator to set the path to the shader files in the Source field in 特性 .

   

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.

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:

1. Drag and drop a 自定义材质 type from the Qt Quick 3D Custom Shader Utils tab of Library to a Model component in Navigator .
2. Select the custom material component in Navigator to edit the values of its properties in the 特性 view.

   

3. Select the Transparency check box to make the material transparent.
4. Select the Refraction check box to specify that the material is reflective .
5. Select the Always dirty check box to determine that the material needs to be refreshed every time it is used.
6. 在 Shader Info field, select the shader info type to use.
7. 在 Passes field, select the pass components for the effect.
8. 在 Material group, select the light probe , displacement map and amount ，和 culling mode to use.
9. Select the shader info component in Navigator to specify values for its properties in 特性 .

   

10. Select the pass component in Navigator to specify values for its properties in 特性 .

    

11. To execute commands during the pass, drag and drop the following command types from Library to the pass component in Navigator : Blending , Buffer Blit , Buffer Input , Cull Mode , Depth Input , Render State ，和 Set Uniform Value . The command components are created at the same level as the pass component and automatically added to the 命令 field.
12. To allocate a buffer for the pass, drag and drop a Buffer type to the custom material. Then select the buffer in the Buffer field.
13. To add a shader to the pass, drag and drop the Shader type from the Library to the pass component in Navigator . The shader components are created at the same level as the pass component and automatically added to the 着色器 field.
14. Select the shader components in Navigator to set the paths to the shader files in the Source field in 特性 .

    

Creating Shader Files

The requirements set for shaders that you can use in custom effects and materials are described in Qt Quick 3D 自定义材质参考 .

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

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

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);
}
							

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 Connection View > 特性 .

For more information about adding properties, see Specifying Dynamic Properties .