On this page

QCCustomBrush Class

QCCustomBrush is a brush with custom shaders. More...

Header: #include <QCCustomBrush>
CMake: find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)
target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)
Since: Qt 6.11
Inherits: QCBrush
Status: Technical Preview

Public Functions

QCCustomBrush()
QCCustomBrush(const QString &fragmentShader, const QString &vertexShader = {})
~QCCustomBrush()
void setData1(const QVector4D &data)
void setData2(const QVector4D &data)
void setData3(const QVector4D &data)
void setData4(const QVector4D &data)
void setFragmentShader(const QShader &fragmentShader)
void setFragmentShader(const QString &fragmentShader)
void setTimeRunning(bool running)
void setVertexShader(const QShader &vertexShader)
void setVertexShader(const QString &vertexShader)
bool timeRunning() const
QVariant operator QVariant() const
bool operator!=(const QCCustomBrush &brush) const
bool operator==(const QCCustomBrush &brush) const

Detailed Description

QCCustomBrush is a stroke/fill brush with custom vertex and/or fragment shaders.

These shaders are expected to be written in Vulkan-style GLSL, similarly to Qt Quick ShaderEffect shaders. They must always contain a QC_INCLUDE statement, either with "customfrag.glsl" or "customvert.glsl". This makes available a uniform block, the image and font textures, and a few helper functions.

Below is a simple example of a custom fragment shader:

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

iTime is an example of a commonly used member in the built-in uniform block. Calling setTimeRunning() with true will make this value update automatically every frame, and can be used to drive animated content.

Shaders that are used with QCCustomBrush must always be added to the application project via the qc_add_shaders() CMake function, provided by the Qt Canvas Painter package. This function performs additional preprocessing at build time before internally invoking the standard qt_add_shaders().

For example:

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

At run time, the generated .qsb file can be used for example like this:

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

The QCCustomBrush can then be used in a fill, for example:

painter->setFillStyle(customBrush);

See also Qt Canvas Painter - Gallery Example.

Member Function Documentation

QCCustomBrush::QCCustomBrush()

Constructs a default custom brush.

QCCustomBrush::QCCustomBrush(const QString &fragmentShader, const QString &vertexShader = {})

Constructs a custom brush.

The fragment shader is fragmentShader and the vertex shader is vertexShader. This constructor takes two filenames, where both files are expected to be .qsb files that are read and deserialized into QShader objects. The files can be a local file or embedded in the application via the The Qt Resource System.

When not specified, vertexShader defaults to an empty string, which implies that the default, standard shader is used for the vertex stage. It is also possible to pass an empty string as fragmentShader, and only provide a custom shader for vertexShader.

See also setFragmentShader and setVertexShader.

[noexcept] QCCustomBrush::~QCCustomBrush()

Destroys the custom brush.

void QCCustomBrush::setData1(const QVector4D &data)

Sets the uniform data1 value to data. This allows setting custom data into shaders.

void QCCustomBrush::setData2(const QVector4D &data)

Sets the uniform data2 value to data. This allows setting custom data into shaders.

void QCCustomBrush::setData3(const QVector4D &data)

Sets the uniform data3 value to data. This allows setting custom data into shaders.

void QCCustomBrush::setData4(const QVector4D &data)

Sets the uniform data4 value to data. This allows setting custom data into shaders.

void QCCustomBrush::setFragmentShader(const QShader &fragmentShader)

Sets the custom brush to use fragmentShader.

void QCCustomBrush::setFragmentShader(const QString &fragmentShader)

Sets the custom brush to use fragmentShader. This must be path to a valid qsb file. The file can be a local file or embedded in the application via the The Qt Resource System.

void QCCustomBrush::setTimeRunning(bool running)

Sets the time running state to running. When this is true, the shader uniform iTime is updated automatically, and can be used to get the current animation running time in the shader.

The default value is false.

See also timeRunning().

void QCCustomBrush::setVertexShader(const QShader &vertexShader)

Sets the custom brush to use vertexShader.

void QCCustomBrush::setVertexShader(const QString &vertexShader)

Sets the custom brush to use vertexShader. This must be path to a valid qsb file. The file can be a local file or embedded in the application via the The Qt Resource System.

bool QCCustomBrush::timeRunning() const

Returns true if the time is running.

See also setTimeRunning().

QVariant QCCustomBrush::operator QVariant() const

Returns the custom brush as a QVariant.

bool QCCustomBrush::operator!=(const QCCustomBrush &brush) const

Returns true if the custom brush is different from the given brush; otherwise false.

See also operator==().

bool QCCustomBrush::operator==(const QCCustomBrush &brush) const

Returns true if the custom brush is equal to the given brush; otherwise false.

See also operator!=().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.