QCanvasCustomBrush Class

详细说明

QCanvasCustomBrush 是一种带有自定义顶点和/或片段着色器的描边/填充画笔。

这些着色器应采用 Vulkan 风格的 GLSL 编写，与Qt Quick 中的ShaderEffect 着色器类似。它们必须始终包含一个QC_INCLUDE 语句，且该语句应使用"customfrag.glsl" 或"customvert.glsl" 之一。这将提供一个 uniform 块、图像和字体纹理以及一些辅助函数。

iTime 是内置uniform块中常用成员的一个示例。在true 环境下调用setAnimationRunning()，该值将每帧自动更新，可用于驱动动画内容。

内置着色器输入、统一变量和辅助函数

QC_INCLUDE 语句并非标准的预处理器指令。它在构建时由qt_add_custom_brush_shaders()处理，此时着色器尚未被传递到常规的着色器编译管道中。 该语句将被替换为一段 GLSL 源代码，其中声明了着色器的输入和输出、纹理采样器、一个共享统一变量块，以及（对于片段着色器）一组辅助函数。在顶点着色器中使用 `"customvert.glsl" `，在片段着色器中使用 `"customfrag.glsl" `。

这意味着自定义笔刷着色器无需自行声明这些输入、输出、采样器或统一变量；它们均由QC_INCLUDE 语句提供。

顶点着色器接口

包含"customvert.glsl" 的顶点着色器会声明以下输入和输出：

• in vec2 vertex - 画布坐标系中的顶点位置。
• in vec2 tcoord - 与顶点关联的纹理坐标。
• out vec2 texCoord - 转发至片段着色器。通常设置为 `tcoord`。
• out vec2 fragCoord - 转发至片段着色器。通常设置为 `vertex`。

此外，还可使用以下与变换相关的统一变量：

• vec4 viewRect - 视口矩形，格式为 (x, y, width, height)。
• int ndcIsYDown - 当归一化设备坐标系的 Y 轴指向下方时（某些图形 API 即为此情况），该值不为零。计算gl_Position 时请考虑这一点。
• mat3 vertMatrix - 当前变换矩阵。

顶点着色器必须写入gl_Position ，并应将texCoord 和fragCoord 转发至片段着色阶段。

典型的顶点着色器如下所示：

#version 440

QC_INCLUDE "customvert.glsl"

void main()
{
    texCoord = tcoord;
    fragCoord = vertex;
    vec2 v = (vertMatrix * vec3(vertex, 1.0)).xy;
    if (ndcIsYDown != 0)
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           -1.0 + 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
    else
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           1.0 - 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
}

片段着色器接口

包含"customfrag.glsl" 的片段着色器声明了以下输入和输出：

• in vec2 texCoord - 插值后的纹理坐标。
• in vec2 fragCoord - 插值后的片段位置，与几何体处于同一坐标系中。通常用于驱动程序化效果。
• out vec4 fragColor - 生成的片段颜色，着色器必须将其写入。预期输出采用预乘透明度（premultiplied alpha）。

提供两种纹理采样器：

• sampler2D tex - 图像纹理。
• sampler2D fontTex - 字体纹理，其中包含字符的有符号距离场。当使用画笔填充文本时，此纹理相关。

还定义了便利常量TAU （等于2 * pi）和SQRT2 。

常用统一变量

使用QC_INCLUDE 的顶点着色器和片段着色器均可访问一个共享的统一变量块。最常用的成员包括：

• float iTime - 一个以秒为单位的时间值，当isAnimationRunning() 为true 时，该值会在每帧更新。用于驱动动画。参见setAnimationRunning()。
• vec4 data1,vec4 data2,vec4 data3,vec4 data4 - 向着色器公开的自定义数据。可通过 C++ 中的setData1()、setData2()、setData3() 和setData4() 进行设置。
• float globalAlpha - 绘制器当前的全局不透明度。片段着色器通常应将 `fragColor ` 与该值相乘。
• vec4 colorEffects - 当前有效的颜色效果参数。通常通过 applyColorEffects() 应用，而非直接访问。
• float fontAlphaMin,float fontAlphaMax - 抗锯齿字形时使用的带符号距离场阈值。

片段着色器辅助函数

片段着色器头文件提供了以下辅助函数：

• float clipMask() - 返回当前片段的裁剪（剪切）覆盖范围，范围为 [0, 1]。将fragColor 乘以该值以遵守绘制器的裁剪规则。
• float antialiasingAlpha() - 返回基于 `texCoord` 计算的抗锯齿覆盖度，取值范围为 [0, 1]。将 `fragColor ` 乘以该值可获得经过抗锯齿处理的边缘。
• float sdfFontAlphaRaw() - 返回从fontTex 在texCoord 处采样的原始有符号距离场值，不包含抗锯齿处理。请根据需要手动应用smoothstep() 。
• float sdfFontAlpha() - 返回从fontTex 在坐标texCoord 处采样的字形透明度，并应用基于fontAlphaMin 和fontAlphaMax 的默认抗锯齿处理。
• void applyColorEffects(inout vec4 color) - 将当前激活的对比度、亮度和饱和度效果直接应用于color 。

典型的片段着色器会计算fragColor ，将其与globalAlpha 相乘，可选地乘以clipMask() 和antialiasingAlpha() 以支持剪裁和抗锯齿，最后调用 applyColorEffects()。

当涉及文本时，还应将sdfFontAlpha() 考虑在内。例如：

#version 440

QC_INCLUDE "customfrag.glsl"

void main()
{
    float a = 0.6 + 0.2 * sin(0.1 * fragCoord.x + 4.0 * iTime);
    vec4 color = vec4(a, a, a, 1.0);
    fragColor = sdfFontAlpha() * globalAlpha * color;
    applyColorEffects(fragColor);
}

将着色器添加到项目中

与 QCanvasCustomBrush 配合使用的着色器必须始终通过 Qt Canvas Painter 包提供的qt_add_custom_brush_shadersCMake 函数添加到应用程序项目中。该函数在构建时执行额外的预处理，然后在内部调用标准的qt_add_shaders() 。

例如：

qt_add_custom_brush_shaders(app "app_custombrush_shaders"
    PREFIX
        "/shaders"
    FILES
        brush1.frag
)

使用画笔

在运行时，可以像这样使用生成的.qsb 文件：

QCanvasCustomBrush customBrush(":/shaders/brush1.frag.qsb"));
customBrush.setAnimationRunning(true); // iTime updates automatically
// expose custom data to the shader in data1
customBrush.setData1(QVector4D(1.0, 2.0, 3.0, 4.0));

随后，QCanvasCustomBrush 即可用于填充操作，例如：

painter->setFillStyle(customBrush);

有关该 CMake 函数的详细信息，请参阅qt_add_custom_brush_shaders；关于在 Qt 中处理跨平台着色器代码的详细信息，请参阅QtShader Tools 模块的文档。