CustomMaterial QML Type | Qt Quick 3D 5.15.2

- Qt 5.15
- Qt Quick 3D
- QML Types
- CustomMaterial QML Type
- Qt Quick 3D | Commercial or GPLv3

# CustomMaterial QML Type

Base component for creating custom materials used to shade models. More...

Import Statement: | import QtQuick3D.Materials 1.15
Inherits: | Material

- List of all members, including inherited members

## Properties

- alwaysDirty : bool
- hasRefraction : bool
- hasTransparency : bool
- passes : list
- shaderInfo : ShaderInfo

## Detailed Description

The custom material allows the user of QtQuick3D to access its material library and implement own materials. There are two types of custom materials, which differ on how they are using the material library. First one uses the custom material interface provided by the library to implement materials similarly to many of the materials in the material library without implementing it's own main function. This type of material must implement all the required functions of the material. The second type implements it's own main function, but can still use functionality from the material library. See reference on how to implement the material using the material interface.

     CustomMaterial {
         // These properties names need to match the ones in the shader code!
         property bool uEnvironmentMappingEnabled: false
         property bool uShadowMappingEnabled: false
         property real roughness: 0.0
         property vector3d metal_color: Qt.vector3d(0.805, 0.395, 0.305)

         shaderInfo: ShaderInfo {
             version: "330"
             type: "GLSL"
             shaderKey: ShaderInfo.Glossy
         }

         property TextureInput uEnvironmentTexture: TextureInput {
                 enabled: uEnvironmentMappingEnabled
                 texture: Texture {
                     id: envImage
                     source: "maps/spherical_checker.png"
                 }
         }
         property TextureInput uBakedShadowTexture: TextureInput {
                 enabled: uShadowMappingEnabled
                 texture: Texture {
                     id: shadowImage
                     source: "maps/shadow.png"
                 }
         }

         Shader {
             id: copperFragShader
             stage: Shader.Fragment
             shader: "shaders/copper.frag"
         }

         passes: [ Pass {
                 shaders: copperFragShader
             }
         ]
     }

The example here from CopperMaterial shows how the material is built. First, the shader parameters are specified as properties. The names and types must match the names in the shader code. Textures use TextureInput to assign texture into the shader variable. The shaderInfo property specifies more information about the shader and also configures some of its features on or off when the custom material is built by QtQuick3D shader generator. Then the material can use Shader type to specify shader source and shader stage. These are used with passes to create the resulting material. The passes can contain multiple rendering passes and also other commands. Normally only the fragment shader needs to be passed to a pass. The material library generates the vertex shader for the material. The material can also create buffers to store intermediate rendering results. Here is an example from GlassRefractiveMaterial:

     Buffer {
         id: tempBuffer
         name: "temp_buffer"
         format: Buffer.Unknown
         textureFilterOperation: Buffer.Linear
         textureCoordOperation: Buffer.ClampToEdge
         sizeMultiplier: 1.0
         bufferFlags: Buffer.None // aka frame
     }

     passes: [ Pass {
             shaders: simpleGlassRefractiveFragShader
             commands: [ BufferBlit {
                     destination: tempBuffer
                 }, BufferInput {
                     buffer: tempBuffer
                     param: "refractiveTexture"
                 }, Blending {
                     srcBlending: Blending.SrcAlpha
                     destBlending: Blending.OneMinusSrcAlpha
                 }
             ]
         }
     ]

Multiple passes can also be specified to create advanced materials. Here is an example from FrostedGlassMaterial.

     passes: [ Pass {
             shaders: noopShader
             output: dummyBuffer
             commands: [ BufferBlit {
                     destination: frameBuffer
                 }
             ]
         }, Pass {
             shaders: preBlurShader
             output: tempBuffer
             commands: [ BufferInput {
                     buffer: frameBuffer
                     param: "OriginBuffer"
                 }
             ]
         }, Pass {
             shaders: blurXShader
             output: blurXBuffer
             commands: [ BufferInput {
                     buffer: tempBuffer
                     param: "BlurBuffer"
                 }
             ]
         }, Pass {
             shaders: blurYShader
             output: blurYBuffer
             commands: [ BufferInput {
                     buffer: blurXBuffer
                     param: "BlurBuffer"
                 }, BufferInput {
                     buffer: tempBuffer
                     param: "OriginBuffer"
                 }
             ]
         }, Pass {
             shaders: mainShader
             commands: [BufferInput {
                     buffer: blurYBuffer
                     param: "refractiveTexture"
                 }, Blending {
                     srcBlending: Blending.SrcAlpha
                     destBlending: Blending.OneMinusSrcAlpha
                 }
             ]
         }
     ]

## Property Documentation

alwaysDirty : bool

Specifies that the material state is always dirty, which indicates that the material needs to be refreshed every time it is used by the QtQuick3D.

hasRefraction : bool

Specifies that the material has refraction.

hasTransparency : bool

Specifies that the material has transparency.

passes : list

Contains a list of render passes implemented by the material.

shaderInfo : ShaderInfo

Specifies the ShaderInfo of the material.