En esta página

QCanvasCustomBrush Class

QCanvasCustomBrush es un pincel con sombreadores personalizados. Más información...

Encabezado: #include <QCanvasCustomBrush>
CMake: find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)
target_link_libraries(mytarget PRIVATE Qt6::CanvasPainter)
Desde: Qt 6.11
Estado: Versión preliminar

Esta clase se encuentra en fase de vista previa tecnológica y está sujeta a cambios.

Funciones públicas

QCanvasCustomBrush()
QCanvasCustomBrush(QCanvasCustomBrush &&)
~QCanvasCustomBrush()
bool isAnimationRunning() const
void setAnimationRunning(bool running)
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 setVertexShader(const QShader &vertexShader)
void setVertexShader(const QString &vertexShader)
operator QVariant() const
bool operator!=(const QCanvasCustomBrush &lhs, const QCanvasCustomBrush &rhs)
QDataStream &operator<<(QDataStream &stream, const QCanvasCustomBrush &brush)
bool operator==(const QCanvasCustomBrush &lhs, const QCanvasCustomBrush &rhs)
QDataStream &operator>>(QDataStream &stream, QCanvasCustomBrush &brush)

Descripción detallada

QCanvasCustomBrush es un pincel de trazo/relleno con sombreadores de vértices y/o fragmentos personalizados.

Se espera que estos sombreadores estén escritos en GLSL al estilo de Vulkan, de forma similar a los sombreadores de Qt Quick ShaderEffect . Deben contener siempre una instrucción QC_INCLUDE, ya sea con "customfrag.glsl" o "customvert.glsl". Esto pone a disposición un bloque «uniform», las texturas de imagen y fuente, y algunas funciones auxiliares.

iTime es un ejemplo de un miembro de uso habitual en el bloque «uniform» integrado. Al llamar a ` setAnimationRunning()` con ` true `, este valor se actualizará automáticamente en cada fotograma y podrá utilizarse para controlar contenido animado.

Entradas de shader integradas, uniformes y funciones auxiliares

La instrucción QC_INCLUDE no es una directiva estándar del preprocesador. Es gestionada por qt_add_custom_brush_shaders() en tiempo de compilación, antes de que el sombreador se pase al proceso habitual de compilación de sombreadores. La instrucción se sustituye por un bloque de código fuente GLSL que declara las entradas y salidas del sombreador, los muestreadores de texturas, un bloque de uniformes compartidos y, en el caso de los sombreadores de fragmentos, un conjunto de funciones auxiliares. Utiliza ` "customvert.glsl" ` en los sombreadores de vértices y ` "customfrag.glsl" ` en los sombreadores de fragmentos.

Esto significa que un sombreador de pincel personalizado no declara por sí mismo estas entradas, salidas, muestreadores ni uniformes; todos ellos quedan disponibles gracias a la instrucción « QC_INCLUDE ».

Interfaz del sombreador de vértices

Un sombreador de vértices que incluye "customvert.glsl" tiene declaradas las siguientes entradas y salidas:

  • in vec2 vertex - La posición del vértice en el sistema de coordenadas del lienzo.
  • in vec2 tcoord - La coordenada de textura asociada al vértice.
  • out vec2 texCoord - Se reenvía al sombreador de fragmentos. Normalmente se establece en ` tcoord`.
  • out vec2 fragCoord - Se reenvía al sombreador de fragmentos. Normalmente se establece en ` vertex`.

Nota: Estas variables están disponibles de forma implícita a través de la directiva QC_INCLUDE. El fragmento de código del sombreador de vértices no debe declararlas.

Además, están disponibles los siguientes uniformes relacionados con la transformación:

  • vec4 viewRect - El rectángulo de la ventana gráfica, como (x, y, anchura, altura).
  • int ndcIsYDown - Diferente de cero cuando el eje Y del sistema de coordenadas normalizado del dispositivo apunta hacia abajo, como ocurre con algunas API gráficas. Ten esto en cuenta al calcular ` gl_Position`.
  • mat3 vertMatrix - La matriz de transformación actual.

Un sombreador de vértices debe escribir ` gl_Position`, y se espera que reenvíe ` texCoord ` y ` fragCoord ` a la etapa de fragmentos.

Nota: Los sombreadores de vérticespersonalizados son menos habituales. Se espera que la mayoría de los pinceles personalizados utilicen el sombreador de vértices predeterminado e integrado, en combinación con un sombreador de fragmentos personalizado proporcionado por la aplicación.

Un sombreador de vértices típico tiene este aspecto:

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

Interfaz del sombreador de fragmentos

Un sombreador de fragmentos que incluye "customfrag.glsl" tiene declaradas las siguientes entradas y salidas:

  • in vec2 texCoord - La coordenada de textura interpolada.
  • in vec2 fragCoord - La posición del fragmento interpolada, en el mismo sistema de coordenadas que la geometría. Se utiliza habitualmente para generar efectos procedurales.
  • out vec4 fragColor - El color del fragmento resultante, que el sombreador debe escribir. La salida esperada utiliza alfa premultiplicado.

Nota: Estas variables están disponibles de forma implícita a través de la directiva « QC_INCLUDE ». El fragmento de código del sombreador de fragmentos en sí mismo no debe declararlas.

Hay dos muestreadores de textura disponibles:

  • sampler2D tex - La textura de imagen.
  • sampler2D fontTex - La textura de fuente, que contiene un campo de distancia con signo de los glifos. Es relevante cuando se utiliza el pincel para rellenar texto.

También se definen las constantes de conveniencia ` TAU ` (igual a 2 * pi) y ` SQRT2 `.

Uniformes comunes

Tanto los sombreadores de vértices como los de fragmentos que utilizan QC_INCLUDE tienen acceso a un bloque de uniformes compartido. Los miembros más utilizados son:

  • float iTime - Un valor de tiempo, en segundos, que se actualiza en cada fotograma mientras isAnimationRunning() es true. Úsalo para controlar animaciones. Consulta setAnimationRunning().
  • vec4 data1, vec4 data2, vec4 data3, vec4 data4 - Datos personalizados expuestos al shader. Configúralos desde C++ mediante setData1(), setData2(), setData3() y setData4().
  • float globalAlpha - La opacidad global actual del pintor. Normalmente, los sombreadores de fragmentos deben multiplicar fragColor por este valor.
  • vec4 colorEffects - Los parámetros del efecto de color activo. Normalmente se aplican mediante applyColorEffects() en lugar de accederse a ellos directamente.
  • float fontAlphaMin, float fontAlphaMax - Los umbrales del campo de distancia con signo que se utilizan al aplicar el suavizado a los glifos.

Funciones auxiliares del sombreador de fragmentos

El archivo de inclusión del sombreador de fragmentos proporciona las siguientes funciones auxiliares:

  • float clipMask() - Devuelve la cobertura de recorte (tijera), en el intervalo [0, 1], para el fragmento actual. Multiplica fragColor por este valor para respetar el recorte del pintor.
  • float antialiasingAlpha() - Devuelve la cobertura de suavizado, en el intervalo [0, 1], derivada de ` texCoord`. Multiplica ` fragColor ` por este valor para obtener bordes suavizados.
  • float sdfFontAlphaRaw() - Devuelve el valor sin procesar del campo de distancia con signo, muestreado de fontTex en texCoord, sin suavizado. Aplica smoothstep() manualmente según sea necesario.
  • float sdfFontAlpha() - Devuelve el alfa del glifo muestreado de fontTex en texCoord, con el suavizado predeterminado aplicado según fontAlphaMin y fontAlphaMax.
  • void applyColorEffects(inout vec4 color) - Aplica los efectos activos de contraste, brillo y saturación a color in situ.

Un sombreador de fragmentos típico calcula fragColor, lo multiplica por globalAlpha, opcionalmente lo multiplica por clipMask() y antialiasingAlpha() para admitir el recorte y el suavizado, y finalmente llama a applyColorEffects().

Cuando se trata de texto, también hay que tener en cuenta sdfFontAlpha(). Por ejemplo:

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

Añadir los shaders al proyecto

Los shaders que se utilizan con QCanvasCustomBrush deben añadirse siempre al proyecto de la aplicación mediante la función CMake qt_add_custom_brush_shaders, proporcionada por el paquete Qt Canvas Painter. Esta función realiza un preprocesamiento adicional en el momento de la compilación antes de invocar internamente el qt_add_shaders() estándar.

Por ejemplo:

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

Uso del pincel

En tiempo de ejecución, el archivo ` .qsb ` generado se puede utilizar, por ejemplo, de la siguiente manera:

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

A continuación, el `QCanvasCustomBrush` se puede utilizar en un relleno, por ejemplo:

painter->setFillStyle(customBrush);

Consulta qt_add_custom_brush_shaders para obtener más detalles sobre la función de CMake, y la documentación del módulo Qt Shader Tools para trabajar con código de shaders multiplataforma en Qt.

Nota: Los sombreadores para pinceles personalizados deben contener siempre la instrucción QC_INCLUDE y deben añadirse al proyecto mediante la función de CMake qt_add_custom_brush_shaders. qt_add_shaders() no es adecuada para sombreadores de pinceles personalizados.

Nota: qt_add_custom_brush_shaders traduce el código del sombreador a los siguientes formatos: GLSL 300 es, 150, 130, HLSL 5.0 y MSL 1.2. Actualmente no se ofrece ninguna otra opción de configuración para esto.

Véase también qt_add_custom_brush_shaders y Qt Canvas Painter: ejemplo de la galería.

Documentación de funciones de miembro

QCanvasCustomBrush::QCanvasCustomBrush()

Crea un pincel personalizado predeterminado.

[constexpr noexcept default] QCanvasCustomBrush::QCanvasCustomBrush(QCanvasCustomBrush &&)

Crea una instancia de ` QCanvasCustomBrush` mediante la construcción «move».

[noexcept] QCanvasCustomBrush::~QCanvasCustomBrush()

Elimina el pincel personalizado.

bool QCanvasCustomBrush::isAnimationRunning() const

Devuelve «true» si el tiempo está en marcha.

void QCanvasCustomBrush::setAnimationRunning(bool running)

Establece el estado de tiempo de ejecución en « running ». Cuando este valor es «true», la variable uniforme del shader « iTime » se actualiza automáticamente y puede utilizarse para obtener el tiempo de ejecución actual de la animación en el shader.

El valor por defecto es ` false`.

Véase también ` isAnimationRunning()`.

void QCanvasCustomBrush::setData1(const QVector4D &data)

Establece el valor de «data1» de «uniform» en « data ». Esto permite introducir datos personalizados en los shaders.

void QCanvasCustomBrush::setData2(const QVector4D &data)

Establece el valor de «data2» de «uniform» en « data ». Esto permite introducir datos personalizados en los shaders.

void QCanvasCustomBrush::setData3(const QVector4D &data)

Establece el valor de «data3» de «uniform» en « data ». Esto permite introducir datos personalizados en los shaders.

void QCanvasCustomBrush::setData4(const QVector4D &data)

Establece el valor de «data4» de «uniform» en « data ». Esto permite introducir datos personalizados en los shaders.

void QCanvasCustomBrush::setFragmentShader(const QShader &fragmentShader)

Establece el pincel personalizado que se va a utilizar: fragmentShader.

void QCanvasCustomBrush::setFragmentShader(const QString &fragmentShader)

Establece el pincel personalizado que se va a utilizar en fragmentShader. Debe ser la ruta a un archivo qsb válido. El archivo puede ser un archivo local o estar integrado en la aplicación a través del sistema de recursos de Qt.

void QCanvasCustomBrush::setVertexShader(const QShader &vertexShader)

Establece el pincel personalizado que se va a utilizar: vertexShader.

void QCanvasCustomBrush::setVertexShader(const QString &vertexShader)

Establece el pincel personalizado que se va a utilizar en vertexShader. Debe ser la ruta a un archivo qsb válido. El archivo puede ser un archivo local o estar integrado en la aplicación a través del sistema de recursos de Qt.

QCanvasCustomBrush::operator QVariant() const

Devuelve el pincel personalizado como un objeto ` QVariant`.

Elementos relacionados no miembros

[noexcept] bool operator!=(const QCanvasCustomBrush &lhs, const QCanvasCustomBrush &rhs)

Devuelve ` true ` si el pincel personalizado ` lhs ` es diferente de ` rhs`; en caso contrario, devuelve ` false `.

Véase también operator==().

QDataStream &operator<<(QDataStream &stream, const QCanvasCustomBrush &brush)

Escribe el « brush » indicado en el « stream » indicado y devuelve una referencia al « stream ».

Nota: Esta función serializa los shaders cargados desde los archivos .qsb, no los nombres de los archivos.

Véase también «Serialización detipos de datos de Qt».

[noexcept] bool operator==(const QCanvasCustomBrush &lhs, const QCanvasCustomBrush &rhs)

Devuelve « true » si el pincel personalizado « lhs » es igual a « rhs »; en caso contrario, devuelve « false ».

Véase también operator!=().

QDataStream &operator>>(QDataStream &stream, QCanvasCustomBrush &brush)

Lee el objeto ` brush ` especificado a partir del objeto ` stream ` especificado y devuelve una referencia al objeto ` stream`.

Véase también «Serialización detipos de datos de Qt».

© 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.