Back to Qt.io
Contact Us Blog Download Qt

CustomMaterial QML Type

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

Import Statement: import QtQuick3D.Materials 1.15
Inherits:

Material

Properties

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.


© 2024 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.