qt_add_custom_brush_shaders | Qt Canvas Painter | Qt 6.12.0
Description: Prepares custom brush shaders and adds them to the Qt resource system

- Qt 6.12
- Qt Canvas Painter
- qt_add_custom_brush_shaders
- Qt Canvas Painter | Commercial or GPLv3

# qt_add_custom_brush_shaders

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

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

## Description

The Qt Canvas Painter module provides a CMake macro file with the `qt_add_custom_brush_shaders` function, which applications can use in their `CMakeLists.txt` to compile the shaders used by QCanvasCustomBrush.

Note: To make the function available, the `find_package` call must request the `CanvasPainter` component:

     find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)

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.

Note: Shaders for custom brushes must always contain a `QC_INCLUDE` statement, either with `"customfrag.glsl"` or `"customvert.glsl"`, and must be added to the project via `qt_add_custom_brush_shaders`. The standard `qt_add_shaders` function is not suitable for custom brush shaders, because it does not perform the Qt Canvas Painter specific preprocessing.

See Qt Shader Tools Build System Integration 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.

Note: The `target` passed as the first argument must exist before `qt_add_custom_brush_shaders` is called.

Note: Multiple `qt_add_custom_brush_shaders` calls are supported and each must use a unique `resource_name`.

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.

See also QCanvasCustomBrush and Qt Shader Tools Build System Integration.