ShaderEffect QML Type

Applies custom shaders to a rectangle. More...

• List of all members, including inherited members

Properties

• blending : bool
• cullMode : enumeration
• fragmentShader : url
• log : string
• mesh : variant
• status : enumeration
• supportsAtlasTextures : bool
• vertexShader : url

Detailed Description

The ShaderEffect type applies a custom vertex and fragment (pixel) shader to a rectangle. It allows adding effects such as drop shadow, blur, colorize and page curl into the QML scene.

Shaders

In Qt 5, effects were provided in form of GLSL (OpenGL Shading Language) source code, often embedded as strings into QML. Starting with Qt 5.8, referring to files, either local ones or in the Qt resource system, became possible as well.

In Qt 6, Qt Quick has support for graphics APIs, such as Vulkan, Metal, and Direct3D 11 as well. Therefore, working with GLSL source strings is no longer feasible. Rather, the new shader pipeline is based on compiling Vulkan-compatible GLSL code into SPIR-V, followed by gathering reflection information and translating into other shading languages, such as HLSL, the Metal Shading Language, and various GLSL versions. The resulting assets are packed together into a single package, typically stored in files with an extension of .qsb. This process is done offline or at application build time at latest. At run time, the scene graph and the underlying graphics abstraction consumes these .qsb files. Therefore, ShaderEffect expects file (local or qrc) references in Qt 6 in place of inline shader code.

The vertexShader and fragmentShader properties are URLs in Qt 6, and work very similarly to Image.source, for example. Only the file and qrc schemes are supported with ShaderEffect, however. It is also possible to omit the file scheme, allowing to specify a relative path in a convenient way. Such a path is resolved relative to the component's (the .qml file's) location.

Shader Inputs and Resources

There are two types of input to the vertexShader: uniforms and vertex inputs.

The following inputs are predefined:

• vec4 qt_Vertex with location 0 - vertex position, the top-left vertex has position (0, 0), the bottom-right (width, height).
• vec2 qt_MultiTexCoord0 with location 1 - texture coordinate, the top-left coordinate is (0, 0), the bottom-right (1, 1). If supportsAtlasTextures is true, coordinates will be based on position in the atlas instead.

The following uniforms are predefined:

• mat4 qt_Matrix - combined transformation matrix, the product of the matrices from the root item to this ShaderEffect, and an orthogonal projection.
• float qt_Opacity - combined opacity, the product of the opacities from the root item to this ShaderEffect.

In addition, any property that can be mapped to a GLSL type can be made available to the shaders. The following list shows how properties are mapped:

• bool, int, qreal -> bool, int, float - If the type in the shader is not the same as in QML, the value is converted automatically.
• QColor -> vec4 - When colors are passed to the shader, they are first premultiplied. Thus Qt.rgba(0.2, 0.6, 1.0, 0.5) becomes vec4(0.1, 0.3, 0.5, 0.5) in the shader, for example.
• QRect, QRectF -> vec4 - Qt.rect(x, y, w, h) becomes vec4(x, y, w, h) in the shader.
• QPoint, QPointF, QSize, QSizeF -> vec2
• QVector3D -> vec3
• QVector4D -> vec4
• QTransform -> mat3
• QMatrix4x4 -> mat4
• QQuaternion -> vec4, scalar value is w.
• Image -> sampler2D - Origin is in the top-left corner, and the color values are premultiplied. The texture is provided as is, excluding the Image item's fillMode. To include fillMode, use a ShaderEffectSource or Image::layer::enabled.
• ShaderEffectSource -> sampler2D - Origin is in the top-left corner, and the color values are premultiplied.

Samplers are still declared as separate uniform variables in the shader code. The shaders are free to choose any binding point for these, except for 0 because that is reserved for the uniform block.

Some shading languages and APIs have a concept of separate image and sampler objects. Qt Quick always works with combined image sampler objects in shaders, as supported by SPIR-V. Therefore shaders supplied for ShaderEffect should always use layout(binding = 1) uniform sampler2D tex; style sampler declarations. The underlying abstraction layer and the shader pipeline takes care of making this work for all the supported APIs and shading languages, transparently to the applications.

The QML scene graph back-end may choose to allocate textures in texture atlases. If a texture allocated in an atlas is passed to a ShaderEffect, it is by default copied from the texture atlas into a stand-alone texture so that the texture coordinates span from 0 to 1, and you get the expected wrap modes. However, this will increase the memory usage. To avoid the texture copy, set supportsAtlasTextures for simple shaders using qt_MultiTexCoord0, or for each "uniform sampler2D <name>" declare a "uniform vec4 qt_SubRect_<name>" which will be assigned the texture's normalized source rectangle. For stand-alone textures, the source rectangle is [0, 1]x[0, 1]. For textures in an atlas, the source rectangle corresponds to the part of the texture atlas where the texture is stored. The correct way to calculate the texture coordinate for a texture called "source" within a texture atlas is "qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0".

The output from the fragmentShader should be premultiplied. If blending is enabled, source-over blending is used. However, additive blending can be achieved by outputting zero in the alpha channel.

import QtQuick 2.0

Rectangle {
    width: 200; height: 100
    Row {
        Image { id: img;
                sourceSize { width: 100; height: 100 } source: "qt-logo.png" }
        ShaderEffect {
            width: 100; height: 100
            property variant src: img
            vertexShader: "myeffect.vert.qsb"
            fragmentShader: "myeffect.frag.qsb"
        }
    }
}

The example assumes myeffect.vert and myeffect.frag contain Vulkan-style GLSL code, processed by the qsb tool in order to generate the .qsb files.

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb, vec3(0.344, 0.5, 0.156))), tex.a) * qt_Opacity;
}

Having One Shader Only

Specifying both vertexShader and fragmentShader is not mandatory. Many ShaderEffect implementations will want to provide a fragment shader only in practice, while relying on the default, built-in vertex shader.

The default vertex shader passes the texture coordinate along to the fragment shader as vec2 qt_TexCoord0 at location 0.

The default fragment shader expects the texture coordinate to be passed from the vertex shader as vec2 qt_TexCoord0 at location 0, and it samples from a sampler2D named source at binding point 1.

ShaderEffect and Item Layers

The ShaderEffect type can be combined with layered items.

Layer with effect disabled

Layer with effect enabled

Item { id: layerRoot layer.enabled: true layer.effect: ShaderEffect { fragmentShader: "effect.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D source; void main() { vec4 p = texture(source, qt_TexCoord0); float g = dot(p.xyz, vec3(0.344, 0.5, 0.156)); fragColor = vec4(g, g, g, p.a) * qt_Opacity; }

It is also possible to combine multiple layered items:

Rectangle { id: gradientRect; width: 10 height: 10 gradient: Gradient { GradientStop { position: 0; color: "white" } GradientStop { position: 1; color: "steelblue" } } visible: false; // should not be visible on screen. layer.enabled: true; layer.smooth: true } Text { id: textItem font.pixelSize: 48 text: "Gradient Text" anchors.centerIn: parent layer.enabled: true // This item should be used as the 'mask' layer.samplerName: "maskSource" layer.effect: ShaderEffect { property var colorSource: gradientRect; fragmentShader: "mask.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D colorSource; layout(binding = 2) uniform sampler2D maskSource; void main() { fragColor = texture(colorSource, qt_TexCoord0) * texture(maskSource, qt_TexCoord0).a * qt_Opacity; }

Other Notes

By default, the ShaderEffect consists of four vertices, one for each corner. For non-linear vertex transformations, like page curl, you can specify a fine grid of vertices by specifying a mesh resolution.

Migrating From Qt 5

For Qt 5 applications with ShaderEffect items the migration to Qt 6 involves:

• Moving the shader code to separate .vert and .frag files,
• updating the shaders to Vulkan-compatible GLSL,
• running the qsb tool on them,
• including the resulting .qsb files in the executable with the Qt resource system,
• and referencing the file in the vertexShader and fragmentShader properties.

As described in the Qt Shader Tools module some of these steps can be automated by letting CMake invoke the qsb tool at build time. See Qt Shader Tools Build System Integration for more information and examples.

When it comes to updating the shader code, below is an overview of the commonly required changes.

attribute highp vec4 qt_Vertex;
attribute highp vec2 qt_MultiTexCoord0;
varying highp vec2 coord;
uniform highp mat4 qt_Matrix;
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

The conversion process mostly involves updating the code to be compatible with GL_KHR_vulkan_glsl. It is worth noting that Qt Quick uses a subset of the features provided by GLSL and Vulkan, and therefore the conversion process for typical ShaderEffect shaders is usually straightforward.

• The version directive should state 440 or 450, although specifying other GLSL version may work too, because the GL_KHR_vulkan_glsl extension is written for GLSL 140 and higher.
• Inputs and outputs must use the modern GLSL in and out keywords. In addition, specifying a location is required. The input and output location namespaces are separate, and therefore assigning locations starting from 0 for both is safe.
• When it comes to vertex shader inputs, the only possibilities with ShaderEffect are location 0 for vertex position (traditionally named qt_Vertex) and location 1 for texture coordinates (traditionally named qt_MultiTexCoord0).
• The vertex shader outputs and fragment shader inputs are up to the shader code to define. The fragment shader must have a vec4 output at location 0 (typically called fragColor). For maximum portability, vertex outputs and fragment inputs should use both the same location number and the same name. When specifying only a fragment shader, the texture coordinates are passed in from the built-in vertex shader as vec2 qt_TexCoord0 at location 0, as shown in the example snippets above.
• Uniform variables outside a uniform block are not legal. Rather, uniform data must be declared in a uniform block with binding point 0.
• The uniform block is expected to use the std140 qualifier.
• At run time, the vertex and fragment shader will get the same uniform buffer bound to binding point 0. Therefore, as a general rule, the uniform block declarations must be identical between the shaders. This also includes members that are not used in one of the shaders. The member names must match, because with some graphics APIs the uniform block is converted to a traditional struct uniform, transparently to the application.
• When providing one of the shaders only, watch out for the fact that the built-in shaders expect qt_Matrix and qt_Opacity at the top of the uniform block. (more precisely, at offset 0 and 64, respectively) As a general rule, always include these as the first and second members in the block.
• In the example the uniform block specifies the block name buf. This name can be changed freely, but must match between the shaders. Using an instance name, such as layout(...) uniform buf { ... } instance_name; is optional. When specified, all accesses to the members must be qualified with instance_name.

varying highp vec2 coord;
uniform lowp float qt_Opacity;
uniform sampler2D src;
void main() {
    lowp vec4 tex = texture2D(src, coord);
    gl_FragColor = vec4(vec3(dot(tex.rgb,
                        vec3(0.344, 0.5, 0.156))),
                             tex.a) * qt_Opacity;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb,
                     vec3(0.344, 0.5, 0.156))),
                          tex.a) * qt_Opacity;
}

• Precision qualifiers (lowp, mediump, highp) are not currently used.
• Calling built-in GLSL functions must follow the modern GLSL names, most prominently, texture() instead of texture2D().
• Samplers must use binding points starting from 1.

See also Item Layers, QSB Manual, and Qt Shader Tools Build System Integration.

Property Documentation

blending : bool

If this property is true, the output from the fragmentShader is blended with the background using source-over blend mode. If false, the background is disregarded. Blending decreases the performance, so you should set this property to false when blending is not needed. The default value is true.

cullMode : enumeration

This property defines which sides of the item should be visible.

• ShaderEffect.NoCulling - Both sides are visible
• ShaderEffect.BackFaceCulling - only front side is visible
• ShaderEffect.FrontFaceCulling - only back side is visible

The default is NoCulling.

fragmentShader : url

This property contains a reference to a file with the preprocessed fragment shader package, typically with an extension of .qsb. The value is treated as a URL, similarly to other QML types, such as Image. It must either be a local file or use the qrc scheme to access files embedded via the Qt resource system. The URL may be absolute, or relative to the URL of the component.

See also vertexShader.

log : string

This property holds a log of warnings and errors from the latest attempt at compiling the shaders. It is updated at the same time status is set to Compiled or Error.

See also status.

mesh : variant

This property defines the mesh used to draw the ShaderEffect. It can hold any GridMesh object. If a size value is assigned to this property, the ShaderEffect implicitly uses a GridMesh with the value as mesh resolution. By default, this property is the size 1x1.

See also GridMesh.

status : enumeration

This property tells the current status of the shaders.

• ShaderEffect.Compiled - the shader program was successfully compiled and linked.
• ShaderEffect.Uncompiled - the shader program has not yet been compiled.
• ShaderEffect.Error - the shader program failed to compile or link.

When setting the fragment or vertex shader source code, the status will become Uncompiled. The first time the ShaderEffect is rendered with new shader source code, the shaders are compiled and linked, and the status is updated to Compiled or Error.

When runtime compilation is not in use and the shader properties refer to files with bytecode, the status is always Compiled. The contents of the shader is not examined (apart from basic reflection to discover vertex input elements and constant buffer data) until later in the rendering pipeline so potential errors (like layout or root signature mismatches) will only be detected at a later point.

See also log.

[since QtQuick 2.4] supportsAtlasTextures : bool

Set this property true to confirm that your shader code doesn't rely on qt_MultiTexCoord0 ranging from (0,0) to (1,1) relative to the mesh. In this case the range of qt_MultiTexCoord0 will rather be based on the position of the texture within the atlas. This property currently has no effect if there is less, or more, than one sampler uniform used as input to your shader.

This differs from providing qt_SubRect_<name> uniforms in that the latter allows drawing one or more textures from the atlas in a single ShaderEffect item, while supportsAtlasTextures allows multiple instances of a ShaderEffect component using a different source image from the atlas to be batched in a single draw. Both prevent a texture from being copied out of the atlas when referenced by a ShaderEffect.

The default value is false.

This property was introduced in QtQuick 2.4.

vertexShader : url

This property contains a reference to a file with the preprocessed vertex shader package, typically with an extension of .qsb. The value is treated as a URL, similarly to other QML types, such as Image. It must either be a local file or use the qrc scheme to access files embedded via the Qt resource system. The URL may be absolute, or relative to the URL of the component.

See also fragmentShader.