QShaderBaker Class

Documentation des fonctions membres

QShaderBaker::QShaderBaker()

Construit un nouveau QShaderBaker.

[noexcept] QShaderBaker::~QShaderBaker()

Destructeur.

QShader QShaderBaker::bake()

Exécute le processus de compilation et de traduction.

Renvoie une instance de QShader. Pour vérifier si le processus a réussi, appelez QShader::isValid(). Lorsque cela indique false, appelez errorMessage() pour récupérer le journal.

Il s'agit d'une opération coûteuse. Lorsque vous l'appelez à partir d'applications, il peut être conseillé de le faire sur un thread séparé.

QString QShaderBaker::errorMessage() const

Renvoie le message d'erreur de la dernière exécution de bake(), ou une chaîne vide s'il n'y a pas eu d'erreur.

void QShaderBaker::setBatchableVertexShaderExtraInputLocation(int location)

Lors de la génération d'une variante de QShader::BatchableVertexShader, location spécifie l'emplacement d'entrée pour l'entrée de vertex insérée. La valeur est par défaut 7 et ne doit être remplacée que si le nuanceur de sommets utilise déjà l'emplacement d'entrée 7.

void QShaderBaker::setBreakOnShaderTranslationError(bool enable)

Contrôle le comportement lorsque la traduction des shaders (de SPIR-V à GLSL/HLSL/MSL) échoue. Par défaut, ce paramètre est vrai, ce qui fait que bake() renvoie une erreur si le shader demandé ne peut pas être généré. Si cela n'est pas souhaité, et que l'intention est de générer ce qui peut l'être mais d'ignorer silencieusement le reste, mettez enable à false.

Cibler plusieurs versions de GLSL peut conduire à des erreurs lorsqu'une fonctionnalité n'est pas traduisible pour une version donnée. Par exemple, tenter de traduire un shader utilisant textureSize() en GLSL ES 100 ferait échouer l'appel à bake() avec le message d'erreur "textureSize is not supported in ESSL 100". S'il est acceptable de ne pas avoir de shader GLSL ES 100 dans le résultat, même s'il a été demandé, alors le fait de mettre ce drapeau à faux permet à bake() de réussir.

void QShaderBaker::setGeneratedShaderVariants(const QList<QShader::Variant> &v)

Spécifie quelles variantes de nuanceurs sont générées. Chaque version de nuanceur peut avoir plusieurs variantes dans le résultat QShader.

Dans la plupart des cas, v contient une seule entrée, QShader::StandardShader.

void QShaderBaker::setGeneratedShaders(const QList<QShaderBaker::GeneratedShader> &v)

Spécifie le type de shaders à compiler ou à traduire. Rien n'est généré par défaut, il est donc obligatoire d'appeler cette fonction avant bake()

Par exemple, la cible de cuisson minimale possible est SPIR-V, sans aucune traduction supplémentaire dans d'autres langues. Pour demander cela, faites :

baker.setGeneratedShaders({ QShader::SpirvShader, QShaderVersion(100) });

[since 6.9] void QShaderBaker::setGlslOptions(QShaderBaker::GlslOptions options)

Définit options pour les sources GLSL et GLSL ES générées. Par défaut, aucun drapeau n'est défini.

Cette fonction a été introduite dans Qt 6.9.

[since 6.7] void QShaderBaker::setMultiViewCount(int count)

Lors de la transpilation de shaders utilisant le multiview (par exemple, un vertex shader utilisant gl_ViewIndex pour un moteur de rendu reposant sur GL_OVR_multiview2, VK_KHR_multiview, etc.), pour certaines cibles, il est nécessaire de déclarer le nombre de vues dans le shader. Ceci n'est pas fait dans le code GLSL de style Vulkan, et n'est pas pertinent pour des cibles telles que SPIR-V ou HLSL, mais est nécessaire pour OpenGL et GLSL, et donc la valeur doit être fournie comme métadonnée supplémentaire.

Par défaut, la valeur est 0, ce qui désactive l'injection de l'instruction num_views. La valeur 1 n'est pas utile puisqu'il s'agit de la valeur par défaut de num_views. Par conséquent, la valeur de count doit être >= 2 pour avoir un effet. Lorsque la valeur est fixée à 2, par exemple, le shader GLSL généré contiendra une déclaration layout(num_views = 2) in;.

La définition d'un count de 2 ou plus injecte également certaines instructions du préprocesseur : QSHADER_VIEW_COUNT est défini comme count, tandis que l'extension GL_EXT_multiview est activée automatiquement. Par conséquent, la définition d'un count approprié peut également s'avérer utile pour d'autres types de nuanceurs, par exemple lors du partage d'un tampon uniforme entre le nuanceur de sommets et le nuanceur de fragments, lorsque les deux nuanceurs doivent être en mesure d'écrire quelque chose comme #if QSHADER_VIEW_COUNT >= 2.

Cette fonction a été introduite dans Qt 6.7.

void QShaderBaker::setPerTargetCompilation(bool enable)

Définit la compilation par cible à enable. Par défaut, ceci est désactivé, ce qui signifie que la source Vulkan/GLSL est compilée en SPIR-V une fois par variante. (donc une fois par défaut, deux fois s'il s'agit d'un vertex shader et la variante Batchable comme demandé également). Le SPIR-V résultant est ensuite traduit dans les différents langages cibles (GLSL, HLSL, MSL).

En mode de compilation par cible, il y a une étape de compilation GLSL vers SPIR-V séparée pour chaque cible, c'est-à-dire pour chaque version GLSL/HLSL/MSL demandée via setGeneratedShaders(). La source d'entrée est la même, mais des définitions de préprocesseur spécifiques à la cible sont insérées. Cela prend beaucoup plus de temps, mais permet aux applications de fournir un seul shader et d'utiliser les blocs #ifdef pour les différencier. Lorsque ce mode est désactivé, la seule façon d'obtenir le même résultat est de fournir plusieurs versions du fichier shader, de traiter chacune séparément, d'envoyer des fichiers {.qsb} pour chacune d'entre elles et de choisir le bon fichier en fonction de la logique d'exécution.

Les macros suivantes seront automatiquement définies dans ce mode. Notez que les macros sont toujours liées aux langages d'ombrage, et non aux API graphiques.

• QSHADER_SPIRV - défini lors du ciblage de SPIR-V (pour être consommé, typiquement, par Vulkan).
• QSHADER_SPIRV_VERSION - le numéro de version de SPIR-V ciblé, tel que 100.
• QSHADER_GLSL - défini lorsqu'il s'agit de GLSL ou GLSL ES (à consommer, typiquement, par OpenGL ou OpenGL ES).
• QSHADER_GLSL_VERSION - le numéro de version de GLSL ou GLSL ES visé, tel que 100, 300, ou 330.
• QSHADER_GLSL_ES - défini uniquement lorsqu'il s'agit de GLSL ES
• QSHADER_HLSL - défini lorsqu'il s'agit de HLSL (à consommer, typiquement, par Direct 3D)
• QSHADER_HLSL_VERSION - la version du modèle de shader HLSL ciblé, par exemple 50
• QSHADER_MSL - défini lorsqu'il s'agit du Metal Shading Language (qui doit être consommé, typiquement, par Metal)
• QSHADER_MSL_VERSION - la version MSL ciblée, telle que 12 ou 20.

Cela permet d'écrire un code de nuanceur comme le suivant.

#if QSHADER_HLSL || QSHADER_MSL
vec2 uv = vec2(uv_coord.x, 1.0 - uv_coord.y);
#else
vec2 uv = uv_coord;
#endif

void QShaderBaker::setPreamble(const QByteArray &preamble)

Spécifie un preamble personnalisé qui est traité avant le code normal du shader.

Il ne s'agit pas d'un simple ajout à la chaîne source : la validité de la directive GLSL version, qui doit être placée avant tout le reste, n'est pas affectée. Les numéros de ligne dans les messages d'erreur rapportés restent également inchangés, ignorant le contenu donné dans preamble.

L'un des cas d'utilisation des préambules est l'insertion transparente d'instructions #define générées dynamiquement.

void QShaderBaker::setSourceDevice(QIODevice *device, QShader::Stage stage, const QString &fileName = QString())

Définit la source device. Cela permet d'utiliser n'importe quel QIODevice au lieu de simples fichiers. stage spécifie l'étape du shader, tandis que l'option fileName contient un nom de fichier qui est utilisé dans les messages d'erreur.

void QShaderBaker::setSourceFileName(const QString &fileName)

Définit le nom du fichier source du shader à fileName. C'est le fichier qui sera lu lors de l'appel à bake(). L'étape du shader est déduite automatiquement de l'extension du fichier. Si cela n'est pas souhaité ou possible, utilisez la surcharge avec l'argument stage à la place.

Les extensions de fichier prises en charge sont les suivantes :

• .vert - nuanceur de sommets
• .frag - nuanceur de fragment (pixel)
• .tesc - nuanceur de contrôle de tessellation (coque)
• .tese - nuanceur d'évaluation de tessellation (domaine)
• .geom - nuanceur de géométrie
• .comp - nuanceur de calcul

void QShaderBaker::setSourceFileName(const QString &fileName, QShader::Stage stage)

Définit le nom du fichier source du shader à fileName. C'est le fichier qui sera lu lors de l'appel à bake(). L'étape du shader est spécifiée par stage.

void QShaderBaker::setSourceString(const QByteArray &sourceString, QShader::Stage stage, const QString &fileName = QString())

Définit le shader d'entrée sourceString. stage spécifie l'étape du shader, tandis que l'option fileName contient un nom de fichier utilisé dans les messages d'erreur.

void QShaderBaker::setSpirvOptions(QShaderBaker::SpirvOptions options)

Définit des options supplémentaires pour le binaire SPIR-V généré. Par défaut, aucun drapeau n'est défini.

void QShaderBaker::setTessellationMode(QShaderDescription::TessellationMode mode)

Lors de la génération du code du shader MSL pour un shader de contrôle de tessellation, la tessellation mode (triangles ou quads) doit être connue à l'avance. En GLSL, elle est déclarée dans le shader d'évaluation de la tessellation, mais pour Metal, elle doit également être connue lors de la génération du shader de calcul à partir du shader de contrôle de la tessellation.

Si elle n'est pas définie, la valeur par défaut est triangles.

void QShaderBaker::setTessellationOutputVertexCount(int count)

Lors de la génération du code du shader MSL pour un shader d'évaluation de tessellation, le vertex de sortie count du shader de contrôle de tessellation doit être connu à l'avance. En GLSL, cela serait déclaré dans le shader de contrôle de tessellation typiquement, mais pour Metal, il doit être connu également lors de la génération du vertex shader à partir du shader d'évaluation de tessellation.

Si elle n'est pas définie, la valeur par défaut est 3.