qt_add_custom_brush_shaders

准备自定义画笔着色器并将其添加到 Qt 资源系统中

该命令定义在Qt6 包的CanvasPainter 组件中，可按以下方式加载：

find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)

该命令于 Qt 6.12 中引入。

语法

qt_add_custom_brush_shaders(target resource_name
    FILES file1 [file2 ...]
    [PREFIX resource_path]
    [BASE base_path]
    [OUTPUTS output1 [output2 ...]]
    [DEFINES "name1=value1;name2=value2"]
    [OUTPUT_TARGETS out_targets_var]
)

如果禁用了无版本命令，请改用qt6_add_custom_brush_shaders() 。它支持与本命令相同的参数集。

说明

使用 `qt_add_custom_brush_shaders` 时，构建系统会自动调用 Qt Canvas Painter 预处理步骤，随后自动执行qsb工具，生成的.qsb 文件会隐式添加到资源系统中。运行时，应用程序通过 Qt 资源系统访问生成的.qsb 文件，并将该文件的路径传递给QCanvasCustomBrush 。

示例

假设我们有一个应用程序，希望使用自定义画笔进行渲染，其片段着色器在brush1.frag 中实现。QCanvasCustomBrush 引用了brush1.frag.qsb 。为了确保该.qsb 文件在构建时生成：

find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)

qt_add_executable(exampleapp
    main.cpp
)

qt_add_custom_brush_shaders(exampleapp "exampleapp_custombrush_shaders"
    PREFIX
        "/shaders"
    FILES
        brush1.frag
)

上述配置已足以让应用程序在运行时访问:/shaders/brush1.frag.qsb ：

QCanvasCustomBrush customBrush(":/shaders/brush1.frag.qsb");

原始的 Vulkan 风格 GLSL 源代码（brush1.frag ）未包含在应用程序的可执行文件中，也无需随应用程序发布。如果着色器代码中存在错误，编译器会在构建时输出错误信息，且构建将失败。 修改着色器源文件时，系统会像处理 C++ 和其他源文件一样，在下次构建时自动采用这些更改。

与 qt_add_shaders 的关系

qt_add_custom_brush_shaders 专用于与 `QCanvasCustomBrush` 配合使用的着色器。它在构建时执行额外的预处理，然后在内部调用来自Qt `Shader Tools` 模块的标准 `qt_add_shaders()` 函数。

有关在 Qt 中处理跨平台着色器代码的一般概念，请参阅qt_add_shaders()；有关编写自定义画笔着色器的详细信息，请参阅QCanvasCustomBrush 。

目标语言

qt_add_custom_brush_shaders 将着色器代码编译为一组固定的目标语言，适用于 Qt Canvas Painter 支持的图形 API：

• SPIR-V（用于 Vulkan）
• GLSL300 es （适用于 OpenGL ES 3.0 及更高版本）
• GLSL150 （适用于 OpenGL 3.2 及更高版本）
• GLSL130 （适用于 OpenGL 3.0，主要用于支持旧版软件的 OpenGL 光栅化器）
• HLSL5.0 （适用于 Direct 3D）
• MSL1.2 （适用于 Metal）

与qt_add_shaders() 不同，目前针对目标语言和版本的集合没有提供进一步的可配置性。

参数

着色器的类型由文件扩展名推断得出，片段着色器必须为.frag ，顶点着色器必须为.vert 。

前两个参数是位置参数：target 是要添加生成的资源的目标，resource_name 是生成的资源的名称。在项目内的每次qt_add_custom_brush_shaders 调用中，该名称必须是唯一的。

其余参数基于关键字：

• FILES - 要编译的着色器源文件（.frag 或.vert ）列表。此关键字为必填项。
• PREFIX - 生成的.qsb 文件在资源系统中可用的资源路径前缀。
• BASE - 用于从生成的资源别名中剥离的基础路径，类似于 `qt_add_resources` 中的 `BASE ` 参数。
• OUTPUTS - 当生成的.qsb 文件名称需要与源文件不同时，此列表可针对FILES 中的每个条目包含一项，以指定输出文件名。这通常用于一个着色器源文件作为多个.qsb 文件的输入，而这些文件通过DEFINES 相互区别的情况。
• DEFINES - 定义在着色器编译期间生效的宏。该列表的格式为"name1=value1;name2=value2" 。
• OUTPUT_TARGETS - 当在静态库中使用qt_add_custom_brush_shaders 时，会生成一个或多个特殊目标。在此处传入变量名可获取这些目标，例如对它们进行额外处理。