QShaderBaker Class

Documentation des fonctions membres

QShaderBaker::QShaderBaker()

Crée un nouvel objet QShaderBaker.

[noexcept] QShaderBaker::~QShaderBaker()

Destructeur.

QShader QShaderBaker::bake()

Lance le processus de compilation et de traduction.

Renvoie une instance de ` QShader `. Pour vérifier si le processus s'est déroulé correctement, appelez ` QShader::isValid()`. Lorsque cette fonction indique ` false`, appelez ` errorMessage()` pour récupérer le journal.

Il s’agit d’une opération coûteuse en ressources. Lorsque vous appelez cette fonction depuis des applications, il peut être conseillé de le faire sur un thread distinct.

QString QShaderBaker::errorMessage() const

Renvoie le message d'erreur issu 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 « QShader::BatchableVertexShader », le paramètre « location » spécifie l'emplacement d'entrée pour l'entrée de sommet insérée. La valeur par défaut est 7 et ne doit être modifiée que si le shader de sommet utilise déjà l'emplacement d'entrée 7.

void QShaderBaker::setBreakOnShaderTranslationError(bool enable)

Définit le comportement en cas d’échec de la conversion du shader (de SPIR-V vers GLSL/HLSL/MSL). Par défaut, ce paramètre est défini sur `true`, ce qui fait que la fonction ` bake()` renvoie une erreur si le shader demandé ne peut pas être généré. Si ce comportement n’est pas souhaité et que l’objectif est de générer ce qui est possible tout en ignorant silencieusement le reste, définissez ` enable ` sur `false`.

Le ciblage de plusieurs versions de GLSL peut entraîner des erreurs lorsqu’une fonctionnalité n’est pas traduisible vers une version donnée. Par exemple, tenter de traduire un shader utilisant textureSize() vers GLSL ES 100 entraînerait l’échec de l’appel bake() dans son intégralité, avec le message d’erreur « textureSize n’est pas pris en charge dans ESSL 100 ». Si l’absence d’un shader GLSL ES 100 dans le résultat est acceptable, même s’il a été demandé, alors définir cet indicateur sur « false » permet à l’ bake() de s’exécuter avec succès.

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

Spécifie quelles variantes de shader sont générées. Chaque version de shader peut comporter plusieurs variantes dans le fichier QShader généré.

Dans la plupart des cas, le fichier ` 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. Par défaut, rien n'est généré ; il est donc obligatoire d'appeler cette fonction avant bake()

Par exemple, la cible de « baking » minimale possible est SPIR-V, sans aucune conversion supplémentaire vers d’autres langages. Pour demander cela, procédez comme suit :

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

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

Définit des options s supplémentaires pour les sources GLSL et GLSL ES générées. Par défaut, aucun indicateur n’est défini.

Cette fonction a été introduite dans Qt 6.9.

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

Lors de la transcompilation de shaders utilisant le mode multivue (par exemple, un shader de sommets utilisant `gl_ViewIndex` pour un moteur de rendu s'appuyant sur `GL_OVR_multiview2`, `VK_KHR_multiview`, etc.), il est nécessaire, pour certaines cibles, de déclarer le nombre de vues dans le shader. Cela n’est pas fait dans le code GLSL de type Vulkan, et n’est pas pertinent pour des cibles telles que SPIR-V ou HLSL, mais est requis pour OpenGL et GLSL ; la valeur doit donc être fournie sous forme de métadonnées supplémentaires.

Par défaut, la valeur est 0, ce qui désactive l’injection de l’instruction ` num_views `. Définir la valeur sur 1 n’est pas utile, car il s’agit de toute façon de l’ num_views par défaut. Par conséquent, ` count ` doit être >= 2 pour avoir un effet. Lorsqu’elle est définie, par exemple, sur 2, le shader GLSL généré contiendra une instruction ` layout(num_views = 2) in; `.

Définir une valeur « count » égale ou supérieure à 2 injecte également certaines instructions de préprocesseur : « QSHADER_VIEW_COUNT » est défini sur « count », tandis que l’extension « GL_EXT_multiview » est automatiquement activée. Par conséquent, définir la valeur appropriée de « count » peut également s’avérer pertinent avec d’autres types de shaders, par exemple lorsqu’un tampon uniforme est partagé entre le shader de sommet et le shader de fragment et que les deux shaders doivent pouvoir é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 sur « enable ». Par défaut, cette option est désactivée, ce qui signifie que le code source Vulkan/GLSL est compilé en SPIR-V une seule fois par variante. (Donc une fois par défaut, deux fois s’il s’agit d’un shader de sommet et si la variante « Batchable » est également demandée). Le code SPIR-V obtenu est ensuite traduit vers les différents langages cibles (GLSL, HLSL, MSL).

En mode de compilation par cible, il existe une étape de compilation GLSL vers SPIR-V distincte 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 y sont insérées. Ce processus est nettement plus long, mais permet aux applications de fournir un seul shader et d’utiliser des blocs d’ #ifdef s pour les différencier. Lorsque ce mode est désactivé, la seule façon d’obtenir le même résultat consiste à fournir plusieurs versions du fichier de shader, à traiter chacune d’elles séparément, à livrer des fichiers {.qsb} pour chacune d’entre elles et à choisir le fichier approprié en fonction d’une logique d’exécution.

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

• QSHADER_SPIRV - définie lorsque la cible est SPIR-V (généralement destiné à être utilisé par Vulkan).
• QSHADER_SPIRV_VERSION - le numéro de version SPIR-V ciblé, tel que 100.
• QSHADER_GLSL - définie lorsque la cible est GLSL ou GLSL ES (généralement utilisé par OpenGL ou OpenGL ES)
• QSHADER_GLSL_VERSION - le numéro de version de GLSL ou GLSL ES ciblé, tel que 100, 300 ou 330.
• QSHADER_GLSL_ES - défini uniquement lorsque la cible est GLSL ES
• QSHADER_HLSL - défini lorsque le ciblage est HLSL (généralement destiné à Direct 3D)
• QSHADER_HLSL_VERSION - la version du modèle de shader HLSL ciblée, telle que 50
• QSHADER_MSL - défini lorsque le langage de shaders Metal (Metal Shading Language) est ciblé (généralement utilisé par Metal)
• QSHADER_MSL_VERSION - la version ciblée du MSL, telle que 12 ou 20.

Cela permet d’écrire du code de shader comme celui-ci.

#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 une directive « preamble » personnalisée qui est traitée avant le code de shader normal.

Cela va au-delà d’un simple ajout en début de chaîne source : la validité de la directive de version GLSL, qui doit impérativement précéder tout le reste, n’est pas affectée. Les numéros de ligne dans les messages d’erreur générés restent également inchangés, le contenu de l’ preamble étant ignoré.

Les préambules permettent notamment d’insérer de manière transparente des instructions d’ #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 quelle QIODevice au lieu de se limiter aux fichiers. stage spécifie l'étape du shader, tandis que le paramètre facultatif fileName contient un nom de fichier utilisé dans les messages d'erreur.

void QShaderBaker::setSourceFileName(const QString &fileName)

Définit le nom du fichier source du shader sur « fileName ». Il s'agit du fichier qui sera lu lors de l'appel de la fonction bake(). L'étape du shader est déduite automatiquement à partir de l'extension du fichier. Si cela n'est pas souhaité ou n'est pas possible, utilisez plutôt la surcharge avec l'argument « stage ».

Les extensions de fichier prises en charge sont les suivantes :

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

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

Définit le nom du fichier source du shader sur fileName. Il s'agit du fichier qui sera lu lors de l'appel de la fonction 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 l'sourceString du shader d'entrée. ` stage ` spécifie l'étape du shader, tandis que le paramètre facultatif ` fileName ` contient un nom de fichier utilisé dans les messages d'erreur.

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

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

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

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

Si ce paramètre n'est pas défini, la valeur par défaut est « triangles ».

void QShaderBaker::setTessellationOutputVertexCount(int count)

Lors de la génération du code de shader MSL pour un shader d'évaluation de tessellation, l'count de sommets de sortie du shader de contrôle de tessellation doit être connue à l'avance. En GLSL, celle-ci est généralement déclarée dans le shader de contrôle de tessellation, mais pour Metal, elle doit également être connue lors de la génération du shader de sommets à partir du shader d'évaluation de tessellation.

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