Herramienta Shadergen

La herramienta shadergen es una aplicación de línea de comandos que forma parte del proceso de acondicionamiento de activos de Qt Quick 3D. Puede habilitarse por proyecto o ejecutarse manualmente desde la línea de comandos. Pre-generar los shaders de material puede tener un impacto significativo en el tiempo de arranque y/o evitar paradas no deseadas en tiempo de ejecución, ya que los procesos de creación de un shader de material en tiempo de ejecución pueden ser costosos.

Uno de los mayores obstáculos para el generador de shaders offline es la cantidad de materiales diferentes que se pueden generar, no sólo basándose en las propiedades del material en sí, sino también en cómo está configurado el resto de la escena; por ejemplo, el número de luces, el tipo de luz, las sombras, etc. afectan al shader generado. Cuando también tenemos en cuenta las propiedades dinámicas, la cantidad de permutaciones de sombreadores de materiales puede hacer inviable la generación de todos ellos en tiempo de compilación. Para limitar la cantidad de sombreadores que debe generar la herramienta, ésta intenta generar sólo los sombreadores que cree que necesita la aplicación. La heurística utilizada en la herramienta puede no ser siempre capaz de detectar qué materiales deben ser generados, esto es especialmente cierto para las propiedades que cambian en tiempo de ejecución. Para verificar que los shaders de material se han generado correctamente, la herramienta debe haber generado un archivo .qsbc que puede ser inspeccionado para verificar que el contenido coincide con el material utilizado por la aplicación. También es posible verificar que el material se ha cargado desde la caché pregenerada configurando 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 es posible añadir o eliminar luces dinámicamente cuando se usan materiales generados.
• Los shaders generados están estrictamente ligados a la versión de Qt utilizada debido a su dependencia de los internos del renderizador. Por lo tanto, no se puede garantizar la compatibilidad de los shaders generados entre versiones.

Utilización

Para habilitar la generación offline de shaders 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}
)

Alternativamente, la herramienta shadergen puede ser invocada manualmente desde la línea de comandos, así:

shadergen main.qml Material.qml

Normalmente, la herramienta shadergen debe ejecutarse desde la carpeta del proyecto de su aplicación, pero también es posible indicar a la herramienta que cambie su directorio de trabajo actual a través del argumento -C.

Si no se indica ninguna ruta de salida, la herramienta escribirá los archivos generados en el directorio actual. La ruta de salida puede cambiarse con la opción -o.

Tenga en cuenta que para que la herramienta genere los materiales esperados necesitará conocer toda la escena y no sólo el material(es), por ejemplo, el número de luces en 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

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 más algunos metadatos sobre los distintos shaders de materiales, como la cadena de propiedades única de cada material. Para inspeccionar el contenido del archivo .qsbc puede utilizar el argumento -l con la herramienta shadergen, de la siguiente manera:

shadergen -l qtappshaders.qsbc

Propiedades dinámicas

Dado que la herramienta se ejecuta en tiempo de compilación, tiene una capacidad limitada para razonar sobre qué propiedades podrían cambiar en tiempo de ejecución. Las propiedades cuyo valor sólo cambie dentro del rango de propiedades, por ejemplo el valor de rugosidad, no afectarán al sombreado del material generado, pero las propiedades que estén activadas o desactivadas, por ejemplo la configuración de un mapa de imagen en tiempo de ejecución, requerirán que se genere un tipo de material diferente. Por lo tanto, se recomienda que todas las variantes de un material, que activa o desactiva las características en el material, o la escena, se declaran como componentes individuales, esto ayudará a la herramienta para generar los sombreadores de materiales correctos.

El siguiente ejemplo muestra un ejemplo artificial de un material en el que queremos añadir un mapa de color base a un material en tiempo de ejecución. Tenga en cuenta que el componente MaterialRedExtended nunca se utiliza en el ejemplo, es puramente definido para ayudar a la herramienta shadergen generar los shaders necesarios para establecer dinámicamente la 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

Model {
    position: Qt.vector3d(0, -30, 0)
    scale: Qt.vector3d(4, 4, 4)
    source: "#Sphere"
    materials: MaterialRed {
        id: redMaterial
    }
MouseArea {
    anchors.fill: parent
    onClicked: {
    if (redMaterial.baseColorMap === null)
        redMaterial.baseColorMap = baseColorMap
    else
        redMaterial.baseColorMap = null
    }
}