ShaderEffect QML Type▲
-
Import Statement: import QtQuick
-
Inherits: Item
-
Group: ShaderEffect is part of qtquick-effects
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.
Depending on the Qt Quick scenegraph backend in use, the ShaderEffect type may not be supported. For example, with the software backend effects will not be rendered at all.
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.
It is only the vertex input location that matters in practice. The names are freely changeable, while the location must always be 0 for vertex position, 1 for texture coordinates. However, be aware that this applies to vertex inputs only, and is not necessarily true for output variables from the vertex shader that are then used as inputs in the fragment shader (typically, the interpolated texture coordinates).
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.
Vulkan-style GLSL has no separate uniform variables. Instead, shaders must always use a uniform block with a binding point of 0.
The uniform block layout qualifier must always be std140.
Unlike vertex inputs, the predefined names (qt_Matrix, qt_Opacity) must not be changed.
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.
-
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.
 |
Sélectionnez |
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;
}Scene Graph textures have origin in the top-left corner rather than bottom-left which is common in OpenGL.
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.
When only one of the shaders is specified, the writer of the shader must be aware of the uniform block layout expected by the default shaders: qt_Matrix must always be at offset 0, followed by qt_Opacity at offset 64. Any custom uniforms must be placed after these two. This is mandatory even when the application-provided shader does not use the matrix or the opacity, because at run time there is one single uniform buffer that is exposed to both the vertex and fragment shader.
Unlike with vertex inputs, passing data between the vertex and fragment shader may, depending on the underlying graphics API, require the same names to be used, a matching location is not always sufficient. Most prominently, when specifying a fragment shader while relying on the default, built-in vertex shader, the texture coordinates are passed on as qt_TexCoord0 at location 0, and therefore it is strongly advised that the fragment shader declares the input with the same name (qt_TexCoord0). Failing to do so may lead to issues on some platforms, for example when running with a non-core profile OpenGL context where the underlying GLSL shader source code has no location qualifiers and matching is based on the variable names during to shader linking process.
ShaderEffect and Item Layers▲
The ShaderEffect type can be combined with layered items.
|
Layer with effect disabled |
Layer with effect enabled |
|
Sélectionnez Sélectionnez |
