qt_add_shaders

Compile les shaders et les ajoute à une ressource Qt.

La commande est définie dans le composant « ShaderTools » du paquet « Qt6 », qui peut être chargé à l'aide de :

find_package(Qt6 REQUIRED COMPONENTS ShaderTools)

Syntaxe

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 les commandes sans version sont désactivées, utilisez plutôt qt6_add_shaders(). Elle prend en charge le même ensemble d’arguments que cette commande.

Description

Lance l'outil qsb au moment de la compilation sur chaque fichier source de shader répertorié dans FILES, puis ajoute les fichiers .qsb résultants au système de ressources Qt sous le préfixe de ressource indiqué par PREFIX.

La ressource générée est nommée resource_name, de la même manière que pour qt_add_resources().

Par défaut, qt_add_shaders appelle qsb comme suit :

qsb --glsl "100 es,120,150" --hlsl 50 --msl 12 -o <output>.qsb <input>

Cela produit un paquet contenant du SPIR-V (pour Vulkan 1.0), du GLSL ES 100 (pour OpenGL ES 2.0 et versions ultérieures), du GLSL 120 (pour OpenGL profil non-core), du GLSL 150 (pour OpenGL profil core), HLSL pour Shader Model 5.0 (Direct3D 11.1) et Metal Shading Language 1.2 (Metal).

Sur WebAssembly, les valeurs par défaut deviennent :

qsb --glsl "100 es,300 es" -o <output>.qsb <input>

ce qui génère des shaders compatibles avec WebGL 1 et WebGL 2.

Les fichiers source des shaders d’origine ne sont pas intégrés dans l’exécutable de l’application et n’ont pas besoin d’être fournis. Les erreurs de compilation générées par le compilateur glslang sont signalées au moment de la compilation et celle-ci échoue. Les modifications apportées aux fichiers source des shaders sont automatiquement prises en compte lors de la compilation suivante, comme pour tout autre fichier source.

Type de shader

Le type de shader est déduit de l’extension du fichier :

• .vert — shaders de sommets
• .tesc — shaders de contrôle de tessellation
• .tese — shaders d’évaluation de tessellation
• .geom — shaders de géométrie
• .frag — shaders de fragment (pixel)
• .comp — shaders de calcul

Options de langue cible

• GLSL — Demande le code source GLSL pour la liste de versions donnée, séparées par des virgules. Par exemple, un shader de calcul nécessite généralement "310 es,430" plutôt que les valeurs par défaut. L’espace avant le suffixe es est facultatif.
• NOGLSL — Désactive la génération du code source GLSL. Convient aux applications qui ne ciblent pas du tout OpenGL.
• HLSL — Demande le code source HLSL pour la liste donnée de versions de Shader Model. qsb utilise la numérotation de type GLSL : 50 correspond au Shader Model 5.0, 51 au 5.1.
• NOHLSL — Désactive la génération du code source HLSL. Convient aux applications qui ne ciblent absolument pas Direct 3D.
• MSL — Demande le code source du Metal Shading Language pour la version indiquée. 12 correspond à MSL 1.2, 20 à 2.0.
• NOMSL — Désactive la génération du code source MSL. Convient aux applications qui ne ciblent pas du tout Metal.

Exemple — augmentation de la version GLSL pour les shaders utilisant les fonctionnalités d’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
)

Qt Quick options

• BATCHABLE — Obligatoire pour les shaders de sommets utilisés avec « Qt Quick », que ce soit dans un « ShaderEffect » ou un « QSGMaterialShader ». N’a aucun effet sur les shaders de fragments ou de calcul ; différents types de shaders peuvent être mélangés en toute sécurité dans la même liste « FILES », car le mot-clé ne s’applique qu’aux fichiers « .vert ». Équivalent à l’argument « -b » de « qsb ».
• ZORDER_LOC — Lorsque ` BATCHABLE ` est spécifié, une entrée de sommet supplémentaire est injectée par défaut à l’emplacement ` 7 `. Utilisez ce mot-clé pour modifier cet emplacement afin d’éviter tout conflit avec une entrée existante.

Options de tessellation

• TESSELLATION — Indique que les shaders appartiennent à un pipeline de tessellation. Ne s’applique qu’aux shaders de sommets lorsque la génération MSL n’est pas désactivée ; active un traitement et une conversion spécifiques pour ces shaders lors de la ciblage de Metal.

  Cette option a été introduite dans Qt 6.5.

• TESSELLATION_VERTEX_COUNT — Spécifie le nombre de sommets en sortie de l’étape de contrôle de tessellation. Obligatoire pour les shaders d’évaluation de tessellation ciblant Metal. La valeur par défaut est ` 3`. Si la valeur ne correspond pas à celle de l’étape de contrôle, le code MSL généré ne fonctionnera pas correctement.

  Cette option a été introduite dans Qt 6.5.

• TESSELLATION_MODE — Spécifie le mode de tessellation : "triangles" (par défaut) ou "quads". Doit être défini lorsqu’un shader de contrôle de tessellation figure dans FILES, et doit correspondre à l’étape d’évaluation de la tessellation.

  Cette option a été introduite dans Qt 6.5.

Options multi-vues

• VIEW_COUNT — Spécifie le nombre de vues pour le rendu multivue (GL_OVR_multiview2, VK_KHR_multiview, instanciation de vues D3D12, etc.). Définissez-la sur une valeur égale ou supérieure à 2 pour que les shaders de sommets concernés produisent une sortie GLSL correcte. La valeur « VIEW_COUNT » injecte la définition du préprocesseur « QSHADER_VIEW_COUNT » et, pour les valeurs égales ou supérieures à 2, ajoute automatiquement « #extension GL_EXT_multiview : require » dans les shaders de sommets. Versions minimales requises du langage lors de l’utilisation du rendu multivue : GLSL 330 et 300 es, HLSL 61. Évitez de définir « VIEW_COUNT » sur les shaders de sommets qui n’utilisent pas le rendu multivue ; regroupez-les plutôt dans des appels « qt_add_shaders() » distincts.

  Cette option a été introduite dans Qt 6.7.

• MULTIVIEW — Génère à la fois un ensemble de shaders non multivue et un ensemble de shaders avec un nombre de vues égal à 2. Il s'agit d'une fonctionnalité pratique équivalente à deux appels distincts à ` qt_add_shaders() ` avec les arguments GLSL/HLSL/MSL/VIEW_COUNT appropriés. Les paramètres implicites pour les variantes multivue sont GLSL 330,300es, HLSL 61, MSL 21 et VIEW_COUNT 2. Les variantes multivue sont stockées avec le suffixe .mv2qsb ajouté au nom de fichier .qsb.

  Cette option a été introduite dans Qt 6.8.

Options des outils externes

• PRECOMPILE — Sous Windows (lorsque HLSL n’est pas désactivé), appelle la fonction fxc du SDK Windows pour compiler le code source HLSL en bytecode DXBC au moment de la compilation plutôt qu’au moment de l’exécution. Le fichier .qsb résultant contient le bytecode intermédiaire compilé plutôt que le code source HLSL d’origine. Équivalent à l’argument ` -c ` de ` qsb`. N’a aucun effet sur les plateformes autres que Windows.
• OPTIMIZED — Appelle la fonction ` spirv-opt ` du SDK Vulkan pour effectuer des optimisations sur le bytecode SPIR-V. Équivalent à l’argument ` -O ` de ` qsb`.

Autres options

• BASE — Préfixe de chemin utilisé pour calculer l’alias (nom dans la ressource) des fichiers .qsb générés. Lorsque BASE est défini, chaque chemin de sortie est rendu relatif à BASE plutôt que conservé tel quel. Ceci est analogue à l’argument BASE de qt_add_resources().
• DEFINES — Définit les macros actives lors de la compilation des shaders, sous la forme "name1=value1;name2=value2". Il est également possible de séparer les entrées par des sauts de ligne, à l’instar de FILES. Équivalent à l’argument -D de qsb.
• OUTPUTS — Lorsque le nom de fichier généré par ` .qsb ` doit différer du nom du fichier source (par exemple, lorsqu’un fichier de shader sert de source à plusieurs fichiers ` .qsb ` différenciés par ` DEFINES`), fournissez un nom de fichier de sortie par entrée dans ` FILES`. Chaque nom est transmis via l’argument ` -o ` à ` qsb ` au lieu d’ajouter ` .qsb ` au nom du fichier source.
• ORIGINAL_FILES — Lorsque les fichiers .qsb doivent dépendre de fichiers source de shaders différents de ceux de FILES, fournissez ici une entrée par élément de FILES. Lorsqu’elle est présente, l’entrée correspondante de ORIGINAL_FILES est écrite dans le fichier de dépendances CMake via --orig-file et est ajoutée à la clause DEPENDS du fichier add_custom_command() sous-jacent. Cela est utile lorsque les fichiers transmis à qt_add_shaders() sont des ressources intermédiaires générées et que les fichiers finaux .qsb doivent suivre les fichiers source d’origine.
• PERTARGETCOMPILE — Compile en SPIR-V et traduit séparément vers chaque version linguistique de sortie, une fois par langue cible. Cette méthode est plus lente que l’approche par passe unique par défaut, mais permet la compilation conditionnelle via les macros du préprocesseur QSHADER_<LANG>[_VERSION]. Équivalent à l’argument -p de qsb.
• DEBUGINFO — Génère des informations de débogage complètes pour SPIR-V, permettant à des outils tels que RenderDoc d’afficher le code source complet lors de l’inspection d’un pipeline ou du débogage de sommets/fragments. Lorsque PRECOMPILE est également défini, indique à fxc d’intégrer les informations de débogage dans le bytecode DXBC généré. Équivalent à l’argument -g de qsb.
• QUIET — Supprime l’affichage des messages de débogage et d’avertissement provenant de qsb. Seules les erreurs fatales sont affichées. Équivalent à l’argument -s de qsb.
• OUTPUT_TARGETS — Lors de l’utilisation de qt_add_shaders avec des bibliothèques statiques, une ou plusieurs cibles spéciales sont générées. Passez un nom de variable pour récupérer ces cibles en vue d’un traitement ultérieur.
• MEDIUMP — Demande l’utilisation par défaut de nombres à virgule flottante de précision moyenne dans les shaders de fragment GLSL ES. N’a aucun effet sur les autres cibles, y compris le GLSL non-ES.

Remplacement de shaders créés manuellement

La liste FILES prend en charge une syntaxe spéciale permettant de remplacer une variante de shader spécifique du paquet .qsb par un fichier créé manuellement. Cela équivaut à l’option -r de qsb:

FILES
    "shaders/externalsampler.frag@glsl,100es,shaders/externalsampler_gles.frag"

Un nom de fichier peut être suivi d’un nombre quelconque de spécifications de remplacement séparées par des virgules ( @). Chacune spécifie le langage de shader, la version et le fichier à lire, séparés par des virgules. Les caractères @ présents dans le nom de fichier ou le chemin d’accès au répertoire sont gérés correctement et n’affectent pas l’analyse syntaxique. Consultez le manuel QSB pour plus de détails.

Exemples

Utilisation de base

find_package(Qt6 COMPONENTS ShaderTools)

qt6_add_executable(exampleapp main.cpp)

qt6_add_shaders(exampleapp "exampleapp_shaders"
    PREFIX
        "/"
    FILES
        "wobble.frag"
)

Cela rend :/wobble.frag.qsb disponible au moment de l’exécution. La source originale d’ wobble.frag n’est pas incluse dans l’exécutable.

Tessellation

Un pipeline graphique comportant quatre étapes — sommet (vertex.vert), contrôle de tessellation (tess.tesc), évaluation de la tessellation (tess.tese) et fragment (fragment.frag) — peut être configuré comme suit.

Les shaders de sommets et de fragments sont d’abord compilés. La commande ` TESSELLATION ` active la traduction Metal spécifique pour le shader de sommets, et la version GLSL est mise à niveau car la tessellation nécessite OpenGL 4.x ou ES 3.2.

qt6_add_shaders(project "shaders_tessellation_part1"
    PREFIX
        "/shaders"
    GLSL
        "410,320es"
    TESSELLATION
    FILES
        "vertex.vert"
        "fragment.frag"
)

Les shaders de tessellation sont répertoriés dans un appel distinct car ils nécessitent l’option « NOHLSL » : les shaders de tessellation HLSL doivent être écrits manuellement et injectés. Les paramètres de tessellation Metal sont spécifiés explicitement.

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"
)