QuadTextureProvider QML Type

Used to render a quad texture using a custom fragment shader. More...

Import Statement:	`import QtQuick3D.Helpers`
Since:	Qt 6.12
Inherits:	TextureProviderExtension

List of all members, including inherited members

Properties

format : enumeration (since 6.12)
fragmentShader : url (since 6.12)
fragmentShaderCode : string (since 6.12)
height : int (since 6.12)
width : int (since 6.12)

Detailed Description

This type is used to render quad textures using custom shader code, enabling a convenient way to get programmable textures. By providing a fragment shader and wanted properties, a pass is created and a shader pipeline is built based on the provided data, passing the properties in as uniform values to the fragment shader.

Built-ins provided:

Keyword	Type	Description
MAIN		void MAIN() is the entry point. This function must always be present in the fragment shader provided.
INPUT_UV	vec2	UV coordinates for current fragment. Top-right: [1, 1] and bottom-left: [0, 0].
OUTPUT_SIZE	vec2	Size of the output texture.

Custom properties gets mapped to uniforms. Any time the values change, the updated value will become visible in the shader. This concept may already be familiar from ShaderEffect.

The name of the QML property and the GLSL variable must match. There is no separate declaration in the shader code for the individual uniforms. Rather, the QML property name can be used as-is.

The following table lists how the types are mapped:

QML Type	Shader Type	Notes
real, int, bool	float, int, bool
color	vec4	sRGB to linear conversion is performed implicitly
vector2d	vec2
vector3d	vec3
vector4d	vec4
matrix4x4	mat4
quaternion	vec4	scalar value is `w`
rect	vec4
point, size	vec2
TextureInput	sampler2D

An example of outputting a simple red texture could be done the following way:

Texture {
    textureProvider: QuadTextureProvider {
        width: 128
        height: 128
        fragmentShaderCode: `
            void MAIN() {
                FRAGCOLOR = vec4(1.0, 0.0, 0.0, 1.0);
            }
        `
    }
}

Another example sampling from a Texture property and mixing with UV colors:

Texture {
    textureProvider: QuadTextureProvider {
        fragmentShaderCode: `
        void MAIN() {
            vec2 uv = INPUT_UV;
            vec4 c = texture(checkers, uv);
            FRAGCOLOR = mix(c, vec4(uv, 1, 1), 0.5);
        }`

        property Texture checkers : Texture {
            source: "../shared/maps/checkers2.png"
        }
    }
}

The result is the following:

Note: Providing a vertex shader is not supported, only a fragment shader.

Note: If Texture properties are provided it will not render until the dependent textures are available.

Note: There is currently no support for adding / removing properties at runtime, just modifying the original ones.

See also ShaderEffect.