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 Custom Material Reference.

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 Custom Material types appear in the tab, you must select Add Import in the QML Imports 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.

"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 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.

"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:

  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 Properties view.

    "Custom effect properties"

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

    "Pass properties"

  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, and Set Uniform Value. Then select the commands in the Commands 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 Properties.

    "Shader properties"

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.

"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:

  1. Drag and drop a Custom Material 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 Properties view.

    "Custom material properties"

  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. In the Shader Info field, select the shader info type to use.
  7. In the Passes field, select the pass components for the effect.
  8. In the Material group, select the light probe, displacement map and amount, and culling mode to use.
  9. Select the shader info component in Navigator to specify values for its properties in Properties.

    "Shader Info properties"

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

    "Pass properties"

  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, and Set Uniform Value. The command components are created at the same level as the pass component and automatically added to the Commands 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 Shaders field.
  14. Select the shader components in Navigator to set the paths to the shader files in the Source field in Properties.

    "Shader properties"

Creating Shader Files

The requirements set for shaders that you can use in custom effects and materials are described in 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. 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 > Properties.

"Uniforms as properties in Connection View Properties tab"

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

© 2020 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.