ShaderEffect QML 类型

将自定义着色器应用于矩形。 更多...

• 所有成员的列表，包括继承的成员

属性

• blending : bool
• cullMode : 枚举
• fragmentShader : url
• log : 字符串
• mesh : 变体
• status : 枚举
• supportsAtlasTextures : bool (自 QtQuick 2.4)
• vertexShader : url

详细描述

ShaderEffect 类型将自定义的 顶点 和 片段（像素） 着色器应用于矩形。它允许将像阴影、模糊、着色和翻页等效果添加到 QML 场景中。

着色器

在 Qt 5 中，效果以 GLSL（OpenGL 着色语言）源代码的形式提供，通常作为字符串嵌入到 QML 中。从 Qt 5.8 开始，也可以引用文件，无论是本地文件还是 Qt 资源系统中的文件。

在 Qt 6 中，Qt Quick 也支持图形 API，例如 Vulkan、Metal 和 Direct3D 11。因此，使用 GLSL 源字符串已不再可行。相反，新的着色器管道是基于将与 Vulkan 兼容的 GLSL 代码编译成 SPIR-V，然后收集反射信息并将其转换为其他着色语言，例如 HLSL、Metal 着色语言和各种 GLSL 版本。生成的资产被打包成一个单一的包，通常以 .qsb 扩展名保存的文件中。此过程在离线或在应用程序构建时最新完成。在运行时，场景图和底层图形抽象消耗这些 .qsb 文件。因此，ShaderEffect 在 Qt 6 中期望文件（本地或 qrc）引用，而不是内联着色器代码。

在 Qt 6 中，vertexShader 和 fragmentShader 属性是 URL，它们工作方式与 Image.source 非常相似。但是，ShaderEffect 只支持 file 和 qrc 两种方案。还可以省略 file 方案，以方便的方式指定相对路径。这样的路径是在组件的位置（即 .qml 文件的位置）解析的。

着色器输入和资源

vertexShader 有两种类型的输入：uniform 和 vertex inputs。

以下输入是预定义的

• vec4 qt_Vertex 位置 0 - 顶点位置，左上角的顶点位置为 (0, 0)，右下角位置为 (width, height)。
• vec2 qt_MultiTexCoord0 位置 1 - 纹理坐标，左上角坐标为 (0, 0)，右下角为 (1, 1)。如果 supportsAtlasTextures 为 true，则坐标将基于图集中的位置。

以下 uniform 预定义为

• mat4 qt_Matrix - 组合变换矩阵，从根项到此 ShaderEffect 矩阵的乘积和一个正交投影。
• float qt_Opacity - 组合不透明度，从根项到此 ShaderEffect 不透明度的乘积。

此外，可以映射到 GLSL 类型的任何属性都可以供着色器使用。以下列表显示属性如何映射

• bool, int, qreal -> bool, int, float - 如果着色器中的类型与 QML 中的类型不同，则值会自动转换。
• QColor -> vec4 - 当颜色传递到着色器时，它们首先会被预处理。例如，Qt.rgba(0.2, 0.6, 1.0, 0.5) 在着色器中变为 vec4(0.1, 0.3, 0.5, 0.5)。
• QRect、QRectF -> vec4 - Qt.rect(x, y, w, h) 在着色器中变为 vec4(x, y, w, h)。
• QPoint、QPointF、QSize、QSizeF -> vec2
• QVector3D -> vec3
• QVector4D -> vec4
• QTransform -> mat3
• QMatrix4x4 -> mat4
• QQuaternion -> vec4，标量值为 w。
• Image -> sampler2D - 原点位于左上角，颜色值是预先乘以的。纹理按原样提供，不包括 Image 项的填充模式。要包括填充模式，请使用 ShaderEffectSource 或 Image::layer::enabled。
• ShaderEffectSource -> sampler2D - 原点位于左上角，颜色值是预乘的。

在着色器代码中，采样器仍然声明为独立的统一变量。着色器可以自由选择这些变量的任何绑定点，除了 0，因为这被保留用于统一块。

一些着色语言和API有一个概念，即分离的图像和采样器对象。Qt Quick始终与着色器中的复合图像采样器对象一起工作，这是SPIR-V支持的。因此，为ShaderEffect提供的着色器应该始终使用layout(binding = 1) uniform sampler2D tex;样式的采样器声明。底层的抽象层和着色器管道负责在所有支持的API和着色语言中透明地使这一切工作。

场景图的底层可能选择在纹理图集中分配纹理。如果在图集中分配的纹理传递给ShaderEffect，它默认会从纹理图集复制到独立纹理中，以便纹理坐标从0到1，并得到期望的包装模式。然而，这将增加内存使用量。为了避免复制纹理，为使用qt_MultiTexCoord0的简单着色器或为每个"uniform sampler2D <name>"声明一个"uniform vec4 qt_SubRect_<name>"，这将分配纹理的正常化源矩形。对于独立纹理，源矩形是[0, 1]x[0, 1]。对于图集中的纹理，源矩形对应于纹理图集中存储纹理的部分。在纹理图集中名为"source"的纹理的正确纹理坐标计算方法是"qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0"。

片段着色器的输出应该是预乘的。如果启用了blending，使用源覆盖融合。然而，可以通过在alpha通道输出零来实现添加融合。

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"
        }
    }
}

示例假设myeffect.vert和myeffect.frag包含Vulkan风格的GLSL代码，由qsb工具处理，以生成.qsb文件。

#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;
}

只有一个着色器

指定vertexShader和fragmentShader不是强制性的。在实践中，许多ShaderEffect实现将只提供片段着色器，同时依赖于默认的内置顶点着色器。

默认顶点着色器将纹理坐标作为vec2 qt_TexCoord0在位置0传递到片段着色器。

默认片段着色器期望从顶点着色器以vec2 qt_TexCoord0在位置0传递纹理坐标，并从绑定点1的名为source的sampler2D中采样。

ShaderEffect和项目图层

ShaderEffect类型可以与分层项目组合。

效果禁用的图层

效果启用的图层

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; }

也可能组合多个分层项目

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; }

其他注意事项

默认情况下，ShaderEffect由四个顶点组成，每个角一个。对于非线性顶点变换，如翻页，您可以通过指定一个网格分辨率来指定一个精细的顶点网格。

从Qt 5迁移

对于具有ShaderEffect项的Qt 5应用程序，迁移到Qt 6涉及

• 将着色器代码移动到分开的.vert和.frag文件中，
• 更新着色器为与Vulkan兼容的GLSL，
• 在它们上面运行qsb工具，
• 将生成的.qsb文件包含到可执行文件中，并使用Qt资源系统引用该文件，
• 并在vertexShader和fragmentShader属性中引用该文件。

如Qt Shader Tools模块中所述，这些步骤可以通过让CMake在构建时调用qsb工具来自动化。有关更多信息和分析，请参阅Qt Shader Tools构建系统集成。

在更新着色器代码时，以下是一个常用更改的概述。

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;
}

转换过程主要涉及将代码更新为与GL_KHR_vulkan_glsl兼容。值得注意的是，Qt Quick使用GLSL和Vulkan提供的功能的一个子集，因此通常ShaderEffect着色器的转换过程相对简单。

• version指令应指定440或450，尽管指定其他GLSL版本也可能有效，因为GL_KHR_vulkan_glsl扩展是为GLSL 140及以上版本编写的。
• 输入和输出必须使用现代GLSL的in和out关键字。此外，指定位置是必需的。输入和输出位置命名空间是分开的，因此为两者都从0开始分配位置是安全的。
• 至于顶点着色器输入，ShaderEffect的仅可能性是与位置0（传统上命名为qt_Vertex）对应的顶点位置以及位置1（传统上命名为qt_MultiTexCoord0）对应的纹理坐标。
• 顶点着色器输出和片段着色器输入由着色器代码定义。片段着色器必须有一个在位置0（通常称为 fragColor）的 vec4 输出。为了最大程度的可移植性，顶点输出和片段输入应使用相同的定位号和相同的名称。当仅指定片段着色器时，纹理坐标作为 vec2 qt_TexCoord0 在位置 0 由内置顶点着色器传入，如上面示例片段所示。
• 不在uniform块之外的uniform变量是非法的。相反，uniform数据必须声明在绑定点 0 的uniform块中。
• 预期uniform块将使用std140限定符。
• 在运行时，顶点着色器和片段着色器将获取绑定到绑定点0的相同uniform缓冲区。因此，作为一般规则，着色器之间的uniform块声明必须相同。这也包括在某个着色器中未使用的成员。成员名称必须匹配，因为在某些图形API中，uniform块被透明地转换为传统的struct uniform。
• 当只提供一个着色器时，请注意内置着色器期望uniform块顶部有 qt_Matrix 和 qt_Opacity。（更精确地，分别位于偏移量0和64处）作为一般规则，始终将这些作为块的第一和第二成员。
• 在示例中，uniform块指定了块名称 buf。这个名称可以随意更改，但必须在着色器之间匹配。使用实例名称，例如 layout(...) uniform buf { ... } instance_name; 是可选的。当指定时，所有对成员的访问都必须带有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;
}

• 目前不使用精度限定符（lowp，mediump，highp）。
• 调用内置GLSL函数必须遵循现代GLSL名称，最显著的，texture() 而不是 texture2D()。
• 采样器必须使用从1开始的绑定点。

另请参阅项目层，QSB手册以及Qt着色器工具构建系统集成。

属性文档