Herramienta Shadergen
La herramienta Shadergen es una aplicación de línea de comandos que forma parte del proceso de acondicionamiento de recursos de Qt Quick 3D. Se puede activar por proyecto o ejecutarse manualmente desde la línea de comandos. La pregeneración de los sombreadores de materiales puede tener un impacto significativo en el tiempo de arranque y/o evitar bloqueos indeseados en tiempo de ejecución, ya que los procesos de creación de un sombreador de materiales en tiempo de ejecución pueden ser costosos.
Nota: Esta herramienta era experimental y ahora ha quedado obsoleta. La funcionalidad ya existente se mantendrá tal cual, pero no se añadirán nuevas características ni correcciones.
Uno de los mayores obstáculos para el generador de sombreadores fuera de línea es la cantidad de materiales diferentes que se pueden generar, no solo en función de las propias propiedades del material, sino también de cómo está configurada el resto de la escena; por ejemplo, el número de luces, el tipo de luz, las sombras, etc., todo ello afecta a los sombreadores generados. Si además tenemos en cuenta las propiedades dinámicas, la gran cantidad de combinaciones posibles de shaders de materiales puede hacer que, en muy poco tiempo, resulte inviable generarlos todos en el momento de la compilación. Para limitar la cantidad de shaders que la herramienta debe generar, esta intenta generar únicamente aquellos que considera que la aplicación necesita. Es posible que las heurísticas utilizadas en la herramienta no siempre sean capaces de detectar qué materiales deben generarse; esto es especialmente cierto en el caso de las propiedades que cambian en tiempo de ejecución. Para comprobar que los sombreadores de materiales se han generado correctamente, la herramienta debería haber generado un archivo .qsbc que se puede inspeccionar para verificar que el contenido coincide con el material utilizado por la aplicación. También es posible comprobar que el material se ha cargado desde la caché precompilada estableciendo la variable de entorno QT_RHI_SHADER_DEBUG=1 y buscando en la salida de depuración menciones de que el motor ha cargado correctamente el shader pregenerado.
Las limitaciones conocidas son:
- Escenas con más de un « View3D ».
- No se admite añadir ni eliminar luces de forma dinámica cuando se utilizan materiales generados.
- Los shaders generados están estrictamente vinculados a la versión de Qt utilizada debido a su dependencia de los componentes internos del renderizador. Por lo tanto, no se puede garantizar la compatibilidad de los shaders generados entre versiones.
Uso
Para habilitar la generación sin conexión de sombreadores de materiales en tu proyecto, añade lo siguiente a tu archivo de proyecto:
CMake:
qt6_add_materials(offlineshaders "shaders"
PREFIX
"/"
FILES
${qml_resource_files}
)Como alternativa, la herramienta shadergen se puede ejecutar manualmente desde la línea de comandos, de la siguiente manera:
shadergen main.qml Material.qmlNormalmente, la herramienta shadergen debe ejecutarse desde la carpeta del proyecto de tu aplicación, pero también es posible indicarle que cambie su directorio de trabajo actual mediante el argumento -C.
Si no se especifica ninguna ruta de salida, la herramienta escribirá los archivos generados en el directorio actual. La ruta de salida se puede cambiar con la opción ` -o `.
Ten en cuenta que, para que la herramienta genere los materiales esperados, necesitará conocer toda la escena y no solo los materiales; por ejemplo, el número de luces de la escena también afecta a cómo se generan los materiales, por lo que todos los archivos QML relevantes deben añadirse a la lista de archivos que la herramienta necesita procesar.
Argumentos de la línea de comandos
| Breve | Completo | Descripción |
|---|---|---|
| -C <RUTA> | –directory <PATH> | Cambia el directorio actual a <PATH>. Este argumento es opcional. |
| -o <RUTA> | –output-dir <RUTA> | Establece la ruta de salida en <RUTA>. Esta es la ubicación en la que se colocarán los archivos generados por la herramienta. Si no se especifica ninguna ruta, se utilizará el directorio actual. |
| -r <NOMBRE> | –resource-file <NOMBRE> | Cambia el nombre del archivo de recursos generado a <NAME>. Este argumento es opcional. |
| -l <ARCHIVO> | –list-qsbc <ARCHIVO> | Muestra el contenido del archivo qsbc. |
Contenido generado
El archivo de salida principal de las herramientas shadergen es un archivo .qsbc. El archivo .qsbc contiene una colección de archivos .qsb, además de algunos metadatos sobre los distintos sombreadores de materiales, como la cadena de propiedades única de cada material. Para examinar el contenido del archivo .qsbc, puedes utilizar el argumento « -l » con la herramienta «shadergen», de la siguiente manera:
shadergen -l qtappshaders.qsbcPropiedades dinámicas
Dado que la herramienta se ejecuta en tiempo de compilación, tiene una capacidad limitada para determinar qué propiedades podrían cambiar en tiempo de ejecución. Las propiedades cuyo valor solo varía dentro del rango de valores permitido —por ejemplo, el valor de rugosidad— no afectarán al shader de material generado; sin embargo, las propiedades que pueden activarse o desactivarse —como, por ejemplo, la configuración de un mapa de imagen en tiempo de ejecución— requerirían la generación de un tipo de material diferente. Por lo tanto, se recomienda que todas las variantes de un material —que activen o desactiven características del material o de la escena— se declaren como componentes individuales; esto ayudará a la herramienta a generar los sombreadores de material correctos.
El siguiente ejemplo muestra un caso hipotético de un material en el que queremos añadir un mapa de color base al material en tiempo de ejecución. Tenga en cuenta que el componente MaterialRedExtended nunca se utiliza en el ejemplo; se define únicamente para ayudar a la herramienta shadergen a generar los sombreadores necesarios para establecer dinámicamente el baseColorMap en tiempo de ejecución.
MaterialRed.qml
PrincipledMaterial {
baseColor: "red"
lighting: PrincipledMaterial.NoLighting
}MaterialRedExtended.qml
MaterialRed {
baseColorMap: Texture {
source: "maps/metallic/basecolor.jpg"
}
}main.qml
Véase también QtShaderTools.
© 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.