qt_add_custom_brush_shaders

Prepares custom brush shaders and adds them to the Qt resource system

The command is defined in the CanvasPainter component of the Qt6 package, which can be loaded like so:

find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)

This command was introduced in Qt 6.12.

Synopsis

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]
)

If versionless commands are disabled, use qt6_add_custom_brush_shaders() instead. It supports the same set of arguments as this command.

Description

When using qt_add_custom_brush_shaders, the build system invokes a Qt Canvas Painter preprocessing step followed by the qsb tool automatically, and the resulting .qsb files get added to the resource system implicitly. At run time, the application accesses the generated .qsb file via the Qt resource system and passes its path to a QCanvasCustomBrush.

Example

Assume that we have an application that wants to render with a custom brush whose fragment shader is implemented in brush1.frag. The QCanvasCustomBrush refers to brush1.frag.qsb. To ensure this .qsb file gets generated at build time:

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
)

The above is sufficient to enable the application to access :/shaders/brush1.frag.qsb at run time:

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

The original Vulkan-style GLSL source code (brush1.frag) is not included in the application's executable and does not need to be shipped. If there are errors in the shader code, the compiler messages are printed at build time and the build fails. When changing the shader source file, the changes are picked up automatically in the next build, like they would for C++ and other source files.

Relationship to qt_add_shaders

qt_add_custom_brush_shaders is dedicated to shaders that are used with QCanvasCustomBrush. It performs additional preprocessing at build time before internally invoking the standard qt_add_shaders from the Qt Shader Tools module.

See qt_add_shaders() for the general concepts of working with cross-platform shader code in Qt, and QCanvasCustomBrush for details on authoring custom brush shaders.

Target Languages

qt_add_custom_brush_shaders translates the shader code to a fixed set of targets, suitable for the graphics APIs Qt Canvas Painter supports:

• SPIR-V (for Vulkan)
• GLSL 300 es (for OpenGL ES 3.0 and newer)
• GLSL 150 (for OpenGL 3.2 and newer)
• GLSL 130 (for OpenGL 3.0, mainly to support older software OpenGL rasterizers)
• HLSL 5.0 (for Direct 3D)
• MSL 1.2 (for Metal)

Unlike qt_add_shaders, there is currently no further configurability offered for the set of target languages and versions.

Arguments

The type of shader is deduced from the file extension, which must be .frag for fragment shaders or .vert for vertex shaders.

The first two arguments are positional: target is the target the generated resources are added to, and resource_name is a name for the generated resource. The name must be unique for each qt_add_custom_brush_shaders call within the project.

The remaining arguments are keyword based:

• FILES - The list of shader source files (.frag or .vert) to compile. This keyword is mandatory.
• PREFIX - The resource path prefix under which the generated .qsb files are made available in the resource system.
• BASE - A base path that is stripped from the generated resource aliases, analogous to the BASE argument of qt_add_resources.
• OUTPUTS - When the name of a generated .qsb file needs to be different from the source, this list can contain an entry for each item in FILES, specifying the output file name. This is typically used when one shader source serves as the input for multiple .qsb files that differ via DEFINES.
• DEFINES - Defines macros that are active during shader compilation. The list has the form "name1=value1;name2=value2".
• OUTPUT_TARGETS - When using qt_add_custom_brush_shaders with static libraries, one or more special targets are generated. Pass a variable name here to retrieve these targets, for example to perform additional processing on them.