QuadTextureProvider QML Type | Qt Quick 3D | Qt 6.12.0
Description: Used to render a quad texture using a custom fragment shader.
Keywords: qmltype

- Qt 6.12
- Qt Quick 3D
- QML Types
- QtQuick3D.Helpers
- QuadTextureProvider
- Qt Quick 3D | Commercial or GPLv3

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

## Property Documentation

### format : enumeration `[default: TexureData.RGBA16F, since 6.12]`

This property holds the format of the output texture.

Constant | Description
--- | ---
`TexureData.RGBA8` | The color format is considered as 8-bit integer in R, G, B and alpha channels.
`TexureData.RGBA16F` | The color format is considered as 16-bit float in R,G,B and alpha channels.
`TexureData.RGBA32F` | The color format is considered as 32-bit float in R, G, B and alpha channels.
`TexureData.RGBE8` | The color format is considered as 8-bit mantissa in the R, G, and B channels and 8-bit shared exponent.
`TexureData.R8` | The color format is considered as 8-bit integer in R channel.
`TexureData.R16` | The color format is considered as 16-bit integer in R channel.
`TexureData.R16F` | The color format is considered as 16-bit float in R channel.
`TexureData.R32F` | The color format is considered as 32-bit float R channel. Note: With the exception of `TexureData.RGBA8`, not every format is supported at runtime as this depends on which backend is being used as well which hardware is being used.

This property was introduced in Qt 6.12.

### fragmentShader : url `[since 6.12]`

Specifies the file with the snippet of custom fragment shader code.

The value is a URL and must either be a local file or use the qrc scheme to access files embedded via the Qt resource system. Relative file paths (without a scheme) are also accepted, in which case the file is treated as relative to the component (the `.qml` file).

Warning: Shader snippets are assumed to be trusted content. Application developers are advised to carefully consider the potential implications before allowing the loading of user-provided content that is not part of the application.

Note: If set, fragmentShaderCode will take precedence over fragmentShader.

This property was introduced in Qt 6.12.

See also fragmentShaderCode.

### fragmentShaderCode : string `[since 6.12]`

Specifies a snippet of custom fragment shader code.

Used as a way to inline shader code as a string instead of providing a file.

Note: If set, this property will take precedence over fragmentShader.

This property was introduced in Qt 6.12.

See also fragmentShader.

### height : int `[default: 128, since 6.12]`

Specifies the height in pixels of the output texture.

This property was introduced in Qt 6.12.

See also width.

### width : int `[default: 128, since 6.12]`

Specifies the width in pixels of the output texture.

This property was introduced in Qt 6.12.

See also height.