Outil Shadergen

L'outil shadergen est une application en ligne de commande qui fait partie du pipeline de conditionnement des actifs de Qt Quick 3D. Il peut être activé par projet ou exécuté manuellement à partir de la ligne de commande. La pré-génération des shaders de matériaux peut avoir un impact significatif sur le temps de démarrage et/ou éviter des blocages indésirables lors de l'exécution, car le processus de création d'un shader de matériau lors de l'exécution peut être coûteux.

L'un des plus grands obstacles pour le générateur de shaders hors ligne est la quantité de matériaux différents qui peuvent être générés, non seulement en fonction des propriétés du matériau lui-même, mais aussi de la façon dont le reste de la scène est configuré ; par exemple, le nombre de lumières, le type de lumière, les ombres, etc. affectent tous le(s) shader(s) généré(s). Lorsque nous prenons également en compte les propriétés dynamiques, la quantité de permutations de shaders de matériaux peut très rapidement rendre impossible leur génération au moment de la construction. Pour limiter la quantité de shaders à générer, l'outil essaie de ne générer que les shaders dont il pense que l'application a besoin. L'heuristique utilisée par l'outil n'est pas toujours capable de détecter quels matériaux doivent être générés, ceci est particulièrement vrai pour les propriétés qui changent au moment de l'exécution. Pour vérifier que les shaders de matériaux ont été générés correctement, l'outil doit avoir généré un fichier .qsbc qui peut être inspecté pour vérifier que le contenu correspond au matériau utilisé par l'application. Il est également possible de vérifier que le matériau a été chargé à partir du cache préconstruit en définissant la variable d'environnement QT_RHI_SHADER_DEBUG=1 et en regardant la sortie de débogage pour des mentions du moteur chargeant le shader prégénéré avec succès.

Les limitations connues sont les suivantes :

• Scènes avec plus d'une View3D.
• L'ajout ou la suppression dynamique de lumières n'est pas possible lors de l'utilisation de matériaux générés.
• Les shaders générés sont strictement liés à la version de Qt utilisée en raison de sa dépendance à l'égard des éléments internes du moteur de rendu. La compatibilité des shaders générés ne peut donc pas être garantie d'une version à l'autre.

Utilisation

Pour activer la génération hors ligne des shaders de matériaux dans votre projet, ajoutez ce qui suit à votre fichier de projet :

CMake :

qt6_add_materials(offlineshaders "shaders"
    PREFIX
        "/"
    FILES
        ${qml_resource_files}
)

L'outil shadergen peut également être appelé manuellement à partir de la ligne de commande, comme ceci :

shadergen main.qml Material.qml

Normalement, l'outil shadergen doit être exécuté à partir du dossier du projet de votre application, mais il est également possible de demander à l'outil de changer son répertoire de travail actuel à l'aide de l'argument -C.

Si aucun chemin de sortie n'est fourni, l'outil écrira les fichiers générés dans le répertoire courant. Le chemin de sortie peut être modifié à l'aide de l'option -o.

Notez que pour que l'outil génère les matériaux attendus, il aura besoin de connaître l'ensemble de la scène et pas seulement le(s) matériau(x), par exemple le nombre de lumières dans la scène affecte également la façon dont les matériaux sont générés, donc tous les fichiers qml pertinents doivent être ajoutés à la liste des fichiers que l'outil doit traiter.

Arguments de la ligne de commande

Contenu généré

Le fichier de sortie principal des outils shadergen est un fichier .qsbc. Le fichier .qsbc contient une collection de fichiers .qsb ainsi que des métadonnées sur les différents shaders de matériaux, telles que la chaîne de propriétés unique pour chaque matériau. Pour inspecter le contenu du fichier .qsbc, vous pouvez utiliser l'argument -l avec l'outil shadergen, comme ceci :

shadergen -l qtappshaders.qsbc

Propriétés dynamiques

Étant donné que l'outil est exécuté au moment de la construction, sa capacité à raisonner sur les propriétés susceptibles d'être modifiées au moment de l'exécution est limitée. Les propriétés dont la valeur ne change qu'à l'intérieur de la plage de propriétés, par exemple la valeur de rugosité, n'auront aucun effet sur le shader de matériau généré, mais les propriétés qui sont soit activées, soit désactivées, par exemple la définition d'une carte d'image à l'exécution, nécessiteront la génération d'un type de matériau différent. Il est donc recommandé que toutes les variantes d'un matériau, qui activent ou désactivent des caractéristiques du matériau ou de la scène, soient déclarées en tant que composants individuels, ce qui aidera l'outil à générer les bons shaders de matériau.

L'exemple suivant montre un exemple artificiel de matériau dans lequel nous voulons ajouter une carte de couleurs de base à un matériau au moment de l'exécution. Notez que le composant MaterialRedExtended n'est jamais utilisé dans l'exemple, il est purement défini pour aider l'outil shadergen à générer les shaders nécessaires pour définir dynamiquement le baseColorMap à l'exécution.

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
    }
}