En esta página

qt_add_custom_brush_shaders

Prepara sombreadores de pincel personalizados y los añade al sistema de recursos de Qt

El comando está definido en el componente « CanvasPainter » del paquete « Qt6 », que se puede cargar de la siguiente manera:

find_package(Qt6 REQUIRED COMPONENTS CanvasPainter)

Este comando se introdujo en Qt 6.12.

Sinopsis

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

Si los comandos sin versión están desactivados, utiliza en su lugar qt6_add_custom_brush_shaders(). Admite el mismo conjunto de argumentos que este comando.

Descripción

Al utilizar ` qt_add_custom_brush_shaders`, el sistema de compilación invoca automáticamente un paso de preprocesamiento de Qt Canvas Painter seguido de la herramienta `qsb`, y los archivos ` .qsb ` resultantes se añaden al sistema de recursos de forma implícita. En tiempo de ejecución, la aplicación accede al archivo ` .qsb ` generado a través del sistema de recursos de Qt y pasa su ruta a un ` QCanvasCustomBrush`.

Ejemplo

Supongamos que tenemos una aplicación que quiere renderizar con un pincel personalizado cuyo sombreador de fragmentos está implementado en brush1.frag. El archivo QCanvasCustomBrush hace referencia a brush1.frag.qsb. Para garantizar que este archivo .qsb se genere en el momento de la compilación:

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
)

Lo anterior es suficiente para que la aplicación pueda acceder a :/shaders/brush1.frag.qsb en tiempo de ejecución:

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

El código fuente GLSL original al estilo Vulkan (brush1.frag) no se incluye en el ejecutable de la aplicación y no es necesario distribuirlo. Si hay errores en el código del shader, los mensajes del compilador se muestran en el momento de la compilación y esta falla. Al modificar el archivo fuente del shader, los cambios se incorporan automáticamente en la siguiente compilación, al igual que ocurriría con los archivos fuente de C++ y otros lenguajes.

Relación con qt_add_shaders

qt_add_custom_brush_shaders está dedicado a los shaders que se utilizan con QCanvasCustomBrush. Realiza un preprocesamiento adicional en el momento de la compilación antes de invocar internamente la función estándar qt_add_shaders() del módulo Qt Shader Tools.

Nota: Los sombreadores para pinceles personalizados deben contener siempre una instrucción ` QC_INCLUDE `, ya sea con ` "customfrag.glsl" ` o ` "customvert.glsl"`, y deben añadirse al proyecto mediante ` qt_add_custom_brush_shaders`. La función estándar ` qt_add_shaders ` no es adecuada para los sombreadores de pinceles personalizados, ya que no realiza el preprocesamiento específico de Qt Canvas Painter.

Consulta qt_add_shaders() para conocer los conceptos generales sobre cómo trabajar con código de sombreadores multiplataforma en Qt, y QCanvasCustomBrush para obtener detalles sobre la creación de sombreadores de pincel personalizados.

Lenguajes de destino

qt_add_custom_brush_shaders traduce el código del sombreador a un conjunto fijo de destinos, adecuados para las API gráficas que admite Qt Canvas Painter:

  • SPIR-V (para Vulkan)
  • GLSL 300 es (para OpenGL ES 3.0 y versiones posteriores)
  • GLSL 150 (para OpenGL 3.2 y versiones posteriores)
  • GLSL 130 (para OpenGL 3.0, principalmente para dar soporte a rasterizadores OpenGL de software más antiguos)
  • 5.0 o HLSL (para Direct 3D)
  • 1.2 de MSL (para Metal)

A diferencia de `qt_add_shaders()`, actualmente no se ofrece ninguna otra opción de configuración para el conjunto de lenguajes y versiones de destino.

Argumentos

El tipo de sombreador se deduce de la extensión del archivo, que debe ser .frag para los sombreadores de fragmentos o .vert para los sombreadores de vértices.

Los dos primeros argumentos son posicionales: ` target ` es el destino al que se añaden los recursos generados, y ` resource_name ` es el nombre del recurso generado. El nombre debe ser único para cada llamada a ` qt_add_custom_brush_shaders ` dentro del proyecto.

Nota: El target pasado como primer argumento debe existir antes de llamar a qt_add_custom_brush_shaders.

Nota: Se admitenvarias llamadas a qt_add_custom_brush_shaders y cada una debe utilizar un resource_name único.

Los argumentos restantes se basan en palabras clave:

  • FILES - La lista de archivos fuente de shaders (.frag o .vert) que se van a compilar. Esta palabra clave es obligatoria.
  • PREFIX - El prefijo de la ruta de recursos bajo el cual los archivos .qsb generados estarán disponibles en el sistema de recursos.
  • BASE - Una ruta base que se elimina de los alias de recursos generados, de forma análoga al argumento BASE de qt_add_resources.
  • OUTPUTS - Cuando el nombre de un archivo « .qsb » generado deba ser diferente del del archivo fuente, esta lista puede contener una entrada para cada elemento de ` FILES`, especificando el nombre del archivo de salida. Esto se utiliza normalmente cuando una fuente de shader sirve como entrada para varios archivos « .qsb » que difieren a través de ` DEFINES`.
  • DEFINES - Define las macros que están activas durante la compilación del sombreador. La lista tiene el formato "name1=value1;name2=value2".
  • OUTPUT_TARGETS - Al utilizar qt_add_custom_brush_shaders con bibliotecas estáticas, se generan uno o más objetivos especiales. Pase aquí un nombre de variable para recuperar estos objetivos, por ejemplo, para realizar un procesamiento adicional sobre ellos.

Véase también QCanvasCustomBrush y qt_add_shaders().

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