Outil Shadergen

L'outil Shadergen est une application en ligne de commande qui fait partie du pipeline de préparation des ressources d'Qt Quick 3D. Il peut être activé par projet ou exécuté manuellement depuis 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 ralentissements indésirables lors de l'exécution, car la création d'un shader de matériau à l'exécution peut être coûteuse en ressources.

L’un des principaux obstacles pour le générateur de shaders hors ligne réside dans le nombre de matériaux différents pouvant être générés, qui dépend non seulement des propriétés des matériaux elles-mêmes, mais aussi de la configuration du reste de la scène ; par exemple, le nombre de lumières, leur type, les ombres, etc. ont tous une incidence sur le ou les shaders générés. Si l’on tient également compte des propriétés dynamiques, le nombre de combinaisons possibles de shaders de matériaux peut très rapidement rendre impossible leur génération complète au moment de la compilation. Afin de limiter le nombre de shaders que l’outil doit générer, celui-ci s’efforce de ne générer que les shaders dont il estime que l’application a besoin. Les heuristiques utilisées par l’outil ne permettent pas toujours de détecter les matériaux à générer, ce qui est particulièrement vrai pour les propriétés qui changent lors de l’exécution. Pour vérifier que les shaders de matériaux ont bien été générés et qu’ils sont corrects, l’outil devrait avoir généré un fichier .qsbc qui peut être inspecté afin de s’assurer que son contenu correspond au matériau utilisé par l’application. Il est également possible de vérifier que le matériau a bien été chargé à partir du cache pré-compilé en définissant la variable d'environnement QT_RHI_SHADER_DEBUG=1 et en recherchant dans les messages de débogage les mentions indiquant que le moteur a chargé avec succès le shader pré-généré.

Les limitations connues sont les suivantes :

• Les scènes comportant plus d'un « View3D ».
• L’ajout ou la suppression dynamique de lumières n’est pas pris en charge 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 leur dépendance vis-à-vis des mécanismes 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 de 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}
)

Vous pouvez également lancer l'outil shadergen manuellement depuis la ligne de commande, comme suit :

shadergen main.qml Material.qml

Normalement, l'outil shadergen doit être exécuté depuis le dossier de projet de votre application, mais il est également possible de lui indiquer de changer son répertoire de travail actuel via l'argument « -C ».

Si aucun chemin de sortie n’est spécifié, l’outil enregistrera 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 doit disposer d’informations sur l’ensemble de la scène et pas seulement sur le ou les matériaux. Par exemple, le nombre de lumières dans la scène influe également sur la manière dont les matériaux sont générés ; tous les fichiers QML pertinents doivent donc être ajoutés à la liste des fichiers que l’outil doit traiter.

Arguments de ligne de commande

Contenu généré

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

shadergen -l qtappshaders.qsbc

Propriétés dynamiques

Comme l’outil est exécuté au moment de la compilation, il a une capacité limitée à déterminer quelles propriétés sont susceptibles de changer au moment de l’exécution. Les propriétés dont la valeur varie uniquement à l'intérieur d'une plage donnée, par exemple la valeur de rugosité, n'auront aucun effet sur le shader de matériau généré ; en revanche, les propriétés qui peuvent être activées ou désactivées, par exemple la définition d'une image de carte à l'exécution, nécessiteraient 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 fonctionnalités dans le matériau ou dans la scène, soient déclarées comme des composants individuels ; cela aidera l’outil à générer les shaders de matériau corrects.

L’exemple suivant présente un cas de figure artificiel où l’on souhaite ajouter une carte de couleur de base à un matériau lors de l’exécution. Notez que le composant MaterialRedExtended n’est jamais utilisé dans cet exemple ; il est uniquement défini pour aider l’outil Shadergen à générer les shaders nécessaires à la définition dynamique de l’ baseColorMap lors de 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
    }
}