qt_add_shaders
Compila los shaders y los añade a un recurso de Qt.
El comando está definido en el componente « ShaderTools » del paquete « Qt6 », que se puede cargar con:
find_package(Qt6 REQUIRED COMPONENTS ShaderTools)Sinopsis
qt_add_shaders(<target> <resource_name>
PREFIX <path>
FILES <file,...>
[BASE <path>]
[GLSL <version,...>]
[NOGLSL]
[HLSL <version,...>]
[NOHLSL]
[MSL <version,...>]
[NOMSL]
[BATCHABLE]
[ZORDER_LOC <number>]
[PERTARGETCOMPILE]
[TESSELLATION]
[TESSELLATION_VERTEX_COUNT <count>]
[TESSELLATION_MODE <mode>]
[VIEW_COUNT <count>]
[MULTIVIEW]
[PRECOMPILE]
[OPTIMIZED]
[DEBUGINFO]
[QUIET]
[DEFINES <name=value,...>]
[OUTPUTS <file,...>]
[ORIGINAL_FILES <file,...>]
[OUTPUT_TARGETS <variable>]
[MEDIUMP])Si los comandos sin versión están desactivados, utiliza qt6_add_shaders() en su lugar. Admite el mismo conjunto de argumentos que este comando.
Descripción
Invoca la herramienta qsb en el momento de la compilación para cada archivo fuente de shader incluido en FILES, y añade los archivos .qsb resultantes al sistema de recursos de Qt bajo el prefijo de recurso especificado por PREFIX.
El recurso generado recibe el nombre resource_name, al igual que en el caso de qt_add_resources().
Por defecto, qt_add_shaders invoca a qsb de la siguiente manera:
qsb --glsl "100 es,120,150" --hlsl 50 --msl 12 -o <output>.qsb <input>Esto genera un paquete que contiene SPIR-V (para Vulkan 1.0), GLSL ES 100 (para OpenGL ES 2.0 y versiones posteriores), GLSL 120 (para el perfil no básico de OpenGL), GLSL 150 (para el perfil básico de OpenGL), HLSL para Shader Model 5.0 (Direct3D 11.1) y Metal Shading Language 1.2 (Metal).
En WebAssembly, los valores por defecto cambian a:
qsb --glsl "100 es,300 es" -o <output>.qsb <input>lo que genera shaders compatibles con WebGL 1 y WebGL 2.
Los archivos fuente originales de los shaders no se incrustan en el ejecutable de la aplicación y no es necesario incluirlos en la distribución. Los errores de compilación del compilador glslang se notifican en el momento de la compilación y esta falla. Los cambios en los archivos fuente de los shaders se detectan automáticamente en la siguiente compilación, al igual que con cualquier otro archivo fuente.
Nota: El ` target ` pasado como primer argumento debe existir antes de llamar a ` qt_add_shaders `.
Nota: Se admitenvarias llamadas a ` qt_add_shaders `. El argumento ` resource_name ` debe ser único para cada llamada en el mismo destino.
Tipo de shader
El tipo de sombreador se deduce a partir de la extensión del archivo:
.vert— sombreadores de vértices.tesc— sombreadores de control de teselación.tese— sombreadores de evaluación de teselación.geom— sombreadores de geometría.frag— sombreadores de fragmentos (píxeles).comp— sombreadores de cálculo
Nota: Actualmente, Direct 3D (HLSL) no admite los sombreadores de control y evaluaciónde teselación . Una posible solución alternativa es crear manualmente sombreadores de casco y de dominio e inyectarlos mediante la sintaxis de sustitución de archivos en FILES.
Opciones de lenguaje de destino
GLSL— Solicita el código fuente GLSL para la lista de versiones dada, separadas por comas. Por ejemplo, un sombreador de cálculo suele necesitar"310 es,430"en lugar de los valores predeterminados. El espacio antes del sufijoeses opcional.NOGLSL— Desactiva la generación del código fuente GLSL. Adecuado para aplicaciones que no están destinadas a OpenGL en absoluto.HLSL— Solicita el código fuente HLSL para la lista dada de versiones de Shader Model.qsbutiliza la numeración al estilo GLSL:50corresponde a Shader Model 5.0,51a 5.1.NOHLSL— Desactiva la generación de código fuente HLSL. Adecuado para aplicaciones que no utilizan Direct 3D en absoluto.MSL— Solicita el código fuente de Metal Shading Language para la versión indicada.12corresponde a MSL 1.2,20a 2.0.NOMSL— Desactiva la generación de código fuente MSL. Adecuado para aplicaciones que no están destinadas en absoluto a Metal.
Ejemplo: aumentar la versión de GLSL para los sombreadores que utilizan características de OpenGL 3.x:
qt_add_shaders(exampleapp "res_gl3shaders"
GLSL "300es,330"
PREFIX
"/shaders"
FILES
shaders/ssao.vert
shaders/ssao.frag
shaders/skybox.vert
shaders/skybox.frag
)Nota: El espacio antes del sufijo es es opcional.
Qt Quick opciones
BATCHABLE— Obligatorio para los sombreadores de vértices utilizados con « Qt Quick », ya sea en un « ShaderEffect » o en un « QSGMaterialShader ». No tiene ningún efecto sobre los sombreadores de fragmentos ni los de cálculo; se pueden mezclar sin problemas diferentes tipos de sombreadores en la misma lista «FILES», ya que la palabra clave solo se aplica a los archivos «.vert». Equivalente al argumento «-b» de «qsb».ZORDER_LOC— Cuando se especifica «BATCHABLE», se inserta de forma predeterminada una entrada de vértice adicional en la ubicación «7». Utiliza esta palabra clave para cambiar la ubicación y evitar conflictos con una entrada ya existente.
Opciones de teselación
TESSELLATION— Indica que los sombreadores pertenecen a un canal de teselación. Solo es relevante para los sombreadores de vértices cuando la generación de MSL no está desactivada; habilita un procesamiento especial y una traducción para dichos sombreadores cuando el destino es Metal.Esta opción se introdujo en Qt 6.5.
TESSELLATION_VERTEX_COUNT— Especifica el recuento de vértices de salida de la etapa de control de teselación. Es obligatorio para los sombreadores de evaluación de teselación destinados a Metal. El valor por defecto es3. Si el valor no coincide con el de la etapa de control, el código MSL generado no funcionará correctamente.Esta opción se introdujo en Qt 6.5.
TESSELLATION_MODE— Especifica el modo de teselación:"triangles"(por defecto) o"quads". Debe establecerse cuando un shader de control de teselación figure enFILES, y debe coincidir con la etapa de evaluación de la teselación.Esta opción se introdujo en Qt 6.5.
Opciones de vistas múltiples
VIEW_COUNT— Especifica el número de vistas para el renderizado multivista (GL_OVR_multiview2, VK_KHR_multiview, instanciación de vistas de D3D12, etc.). Establece un valor igual o superior a 2 para que los sombreadores de vértices pertinentes generen una salida GLSL correcta. Al establecer «VIEW_COUNT», se inserta la definición del preprocesador «QSHADER_VIEW_COUNT» y, para valores iguales o superiores a 2, se añade automáticamente «#extension GL_EXT_multiview : require» en los sombreadores de vértices. Versiones mínimas requeridas del lenguaje al utilizar multivista: GLSL 330 y 300 es, HLSL 61. Evite establecer «VIEW_COUNT» en sombreadores de vértices que no utilicen multivista; en su lugar, agrúpelos en llamadas separadas a «qt_add_shaders()».Esta opción se introdujo en Qt 6.7.
MULTIVIEW— Genera tanto un conjunto de sombreadores sin multivista como otro con un recuento de vistas igual a 2. Se trata de una forma más cómoda de realizar dos llamadas separadas a `qt_add_shaders()` con los argumentos GLSL/HLSL/MSL/VIEW_COUNT adecuados. Los ajustes implícitos para las variantes multivista son GLSL330,300es, HLSL61, MSL21y VIEW_COUNT2. Las variantes multivista se almacenan añadiendo el sufijo.mv2qsbal nombre de archivo.qsb.Esta opción se introdujo en Qt 6.8.
Opciones de herramientas externas
PRECOMPILE— En Windows (cuando HLSL no está desactivado), invocafxcdel SDK de Windows para compilar el código fuente HLSL a bytecode DXBC en tiempo de compilación en lugar de en tiempo de ejecución. El archivo resultante.qsbcontiene el bytecode intermedio compilado en lugar del código fuente HLSL original. Equivalente al argumento «-c» de «qsb». No tiene ningún efecto en plataformas distintas de Windows.OPTIMIZED— Invoca a `spirv-opt` del SDK de Vulkan para realizar optimizaciones en el código byte SPIR-V. Equivalente al argumento `-O` de `qsb`.
Otras opciones
BASE— Prefijo de ruta utilizado para calcular el alias (nombre dentro del recurso) de los archivos.qsbgenerados. Cuando se estableceBASE, cada ruta de salida se convierte en relativa aBASEen lugar de mantenerse tal cual. Esto es análogo al argumentoBASEde qt_add_resources().DEFINES— Define las macros activas durante la compilación del shader, con el formato"name1=value1;name2=value2". Alternativamente, las entradas pueden separarse mediante saltos de línea, al igual que enFILES. Equivalente al argumento-Ddeqsb.OUTPUTS— Cuando el nombre del archivo generado.qsbdeba ser diferente del nombre del archivo fuente (por ejemplo, cuando un archivo de shader sirva como fuente para varios archivos.qsbdiferenciados porDEFINES), se debe proporcionar un nombre de archivo de salida por cada entrada enFILES. Cada nombre se pasa mediante el argumento-oaqsben lugar de añadir.qsbal nombre del archivo fuente.ORIGINAL_FILES— Cuando los archivos.qsbdeban depender de archivos fuente de shaders distintos de los que figuran enFILES, proporcione aquí una entrada por cada elemento deFILES. Cuando esté presente, la entrada correspondiente deORIGINAL_FILESse escribe en el archivo de dependencias de CMake a través de--orig-filey se añade a la cláusulaDEPENDSdeladd_custom_command()subyacente. Esto resulta útil cuando los archivos pasados aqt_add_shaders()son recursos generados intermedios y los archivos finales.qsbdeben seguir los archivos fuente originales.PERTARGETCOMPILE— Compila a SPIR-V y traduce a cada versión del lenguaje de salida por separado, una vez por cada lenguaje de destino. Este proceso es más lento que el enfoque predeterminado de una sola pasada, pero permite la compilación condicional mediante las macros del preprocesadorQSHADER_<LANG>[_VERSION]. Equivalente al argumento-pdeqsb.DEBUGINFO— Genera información de depuración completa para SPIR-V, lo que permite que herramientas como RenderDoc muestren el código fuente completo al inspeccionar un pipeline o al realizar la depuración de vértices o fragmentos. Cuando también se establece `PRECOMPILE`, indica a `fxc` que incruste información de depuración en el bytecode DXBC generado. Equivalente al argumento `-g` de `qsb`.QUIET— Suprime la salida de depuración y advertencias deqsb. Solo se muestran los errores fatales. Equivalente al argumento-sdeqsb.OUTPUT_TARGETS— Al utilizarqt_add_shaderscon bibliotecas estáticas, se generan uno o más objetivos especiales. Pasa un nombre de variable para recuperar dichos objetivos y procesarlos posteriormente.MEDIUMP— Solicita números flotantes de precisión media como valor por defecto en los shaders de fragmento GLSL ES. No tiene ningún efecto en otros objetivos, incluido el GLSL no ES.
Sustitución de sombreadores personalizados
La lista « FILES » admite una sintaxis especial para sustituir una variante específica de sombreador del paquete « .qsb » por un archivo creado manualmente. Esto equivale a la opción « -r » de « qsb »:
FILES
"shaders/externalsampler.frag@glsl,100es,shaders/externalsampler_gles.frag"Un nombre de archivo puede ir seguido de cualquier número de especificaciones de sustitución separadas por « @ ». Cada una de ellas especifica el lenguaje de sombreado, la versión y el archivo que se va a leer, separados por comas. Los caracteres de @ que aparezcan en el nombre del archivo o en la ruta del directorio se gestionan correctamente y no afectan al análisis sintáctico. Consulte el Manual de QSB para obtener más detalles.
Ejemplos
Uso básico
find_package(Qt6 COMPONENTS ShaderTools)
qt6_add_executable(exampleapp main.cpp)
qt6_add_shaders(exampleapp "exampleapp_shaders"
PREFIX
"/"
FILES
"wobble.frag"
)Esto hace que :/wobble.frag.qsb esté disponible en tiempo de ejecución. El código fuente original de wobble.frag no se incluye en el ejecutable.
Tesselación
Se puede configurar una canalización gráfica de cuatro etapas —vértice (vertex.vert), control de teselación (tess.tesc), evaluación de teselación (tess.tese) y fragmento (fragment.frag)— de la siguiente manera.
Los sombreadores de vértices y de fragmentos se compilan en primer lugar. TESSELLATION habilita la traducción especial de Metal para el sombreador de vértices, y se eleva la versión de GLSL porque la teselación requiere OpenGL 4.x o ES 3.2.
qt6_add_shaders(project "shaders_tessellation_part1"
PREFIX
"/shaders"
GLSL
"410,320es"
TESSELLATION
FILES
"vertex.vert"
"fragment.frag"
)Los sombreadores de teselación se enumeran en una llamada separada porque se necesita NOHLSL para ellos: los sombreadores de teselación HLSL deben escribirse manualmente e inyectarse. Los parámetros de teselación de Metal se especifican explícitamente.
qt6_add_shaders(project "shaders_tessellation_part2"
PREFIX
"/shaders"
NOHLSL
GLSL
"410,320es"
TESSELLATION_VERTEX_COUNT
3
TESSELLATION_MODE
"triangles"
FILES
"tess.tesc@hlsl,50,tess_hull.hlsl"
"tess.tese@hlsl,50,tess_domain.hlsl"
)Nota: Se recomiendaescribir manualmente los sombreadores HLSL de casco y dominio solo a usuarios avanzados. Las construcciones como los búferes constantes requieren especial atención para mantener las interfaces de recursos y los diseños compatibles con los sombreadores SPIR-V/GLSL/MSL.
© 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.