QShader Class
Contient plusieurs versions d'un nuanceur traduites dans plusieurs langages d'ombrage, ainsi que des métadonnées de réflexion. Plus d'informations...
| En-tête : | #include <QShader> |
| CMake : | find_package(Qt6 REQUIRED COMPONENTS Gui)target_link_libraries(mytarget PRIVATE Qt6::Gui) |
| qmake : | QT += gui |
| Depuis : | Qt 6.6 |
- Liste de tous les membres, y compris les membres hérités
- QShader fait partie de Rendering in 3D.
Types publics
| struct | NativeShaderInfo |
| struct | SeparateToCombinedImageSamplerMapping |
| NativeResourceBindingMap | |
| SeparateToCombinedImageSamplerMappingList | |
| enum class | SerializedFormatVersion { Latest, Qt_6_5, Qt_6_4 } |
| enum | Source { SpirvShader, GlslShader, HlslShader, DxbcShader, MslShader, …, WgslShader } |
| enum | Stage { VertexStage, TessellationControlStage, TessellationEvaluationStage, GeometryStage, FragmentStage, ComputeStage } |
| enum | Variant { StandardShader, BatchableVertexShader, UInt16IndexedVertexAsComputeShader, UInt32IndexedVertexAsComputeShader, NonIndexedVertexAsComputeShader, HdrCapableFragmentShader } |
Fonctions publiques
| QShader() | |
| QShader(const QShader &other) | |
(since 6.7) | QShader(QShader &&other) |
| ~QShader() | |
| QList<QShaderKey> | availableShaders() const |
| QShaderDescription | description() const |
| bool | isValid() const |
| QShader::NativeResourceBindingMap | nativeResourceBindingMap(const QShaderKey &key) const |
| QShader::NativeShaderInfo | nativeShaderInfo(const QShaderKey &key) const |
| void | removeNativeShaderInfo(const QShaderKey &key) |
| void | removeResourceBindingMap(const QShaderKey &key) |
| void | removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key) |
| void | removeShader(const QShaderKey &key) |
| QShader::SeparateToCombinedImageSamplerMappingList | separateToCombinedImageSamplerMappingList(const QShaderKey &key) const |
| QByteArray | serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const |
| void | setDescription(const QShaderDescription &desc) |
| void | setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info) |
| void | setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map) |
| void | setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list) |
| void | setShader(const QShaderKey &key, const QShaderCode &shader) |
| void | setStage(QShader::Stage stage) |
| QShaderCode | shader(const QShaderKey &key) const |
| QShader::Stage | stage() const |
(since 6.7) void | swap(QShader &other) |
(since 6.7) QShader & | operator=(QShader &&other) |
| QShader & | operator=(const QShader &other) |
Membres publics statiques
| QShader | fromSerialized(const QByteArray &data) |
Non-membres associés
| size_t | qHash(const QShader &key, size_t seed = 0) |
| bool | operator!=(const QShader &lhs, const QShader &rhs) |
| bool | operator==(const QShader &lhs, const QShader &rhs) |
Description détaillée
QShader est le point d'entrée du code de shaders dans le monde Qt agnostique aux API graphiques. Au lieu d'utiliser les sources de shaders GLSL, comme c'était l'habitude avec Qt 5.x, les nouveaux systèmes graphiques avec des backends pour plusieurs API graphiques, tels que Vulkan, Metal, Direct3D et OpenGL, prennent QShader comme point d'entrée chaque fois qu'un shader doit être spécifié.
Attention : La famille de classes QRhi du module Qt Gui, y compris QShader et QShaderDescription, offre des garanties de compatibilité limitées. Il n'existe aucune garantie de compatibilité source ou binaire pour ces classes, ce qui signifie que l'API n'est garantie de fonctionner qu'avec la version de Qt avec laquelle l'application a été développée. Les changements incompatibles avec le code source doivent cependant être réduits au minimum et ne seront apportés que dans les versions mineures (6.7, 6.8, etc.). Pour utiliser ces classes dans une application, créez un lien vers Qt::GuiPrivate (si vous utilisez CMake) et incluez les en-têtes avec le préfixe rhi, par exemple #include <rhi/qshader.h>.
Une instance de QShader est vide et donc invalide par défaut. Pour obtenir une instance utile, les deux méthodes habituelles sont les suivantes :
- Générer le contenu hors ligne, au moment de la construction ou plus tôt, à l'aide de l'outil de ligne de commande
qsb. Le résultat est un fichier binaire qui est livré avec l'application, lu via QIODevice::readAll(), puis désérialisé via fromSerialized(). Pour plus d'informations, voir QShaderBaker. - Générer au moment de l'exécution via QShaderBaker. Il s'agit d'une opération coûteuse, mais qui permet aux applications d'utiliser des chaînes de source de shaders fournies par l'utilisateur ou générées dynamiquement.
Lorsqu'elle est utilisée avec l'interface matérielle de rendu Qt XML et ses classes, comme QRhiGraphicsPipeline, aucune autre action n'est nécessaire de la part de l'application car ces classes sont prêtes à consommer un QShader chaque fois qu'un shader doit être spécifié pour une étape donnée du pipeline graphique.
Par ailleurs, les applications peuvent accéder
- au code source ou à l'octet de l'une des versions du langage d'ombrage incluses dans le QShader,
- le nom du point d'entrée du shader,
- les métadonnées de réflexion contenant une description des entrées, des sorties et des ressources du shader, comme les blocs uniformes. Ces métadonnées sont essentielles lorsqu'une application ou un cadre doit découvrir les entrées d'un nuanceur au moment de l'exécution, faute de connaître à l'avance les attributs des vertex ou la disposition des tampons uniformes utilisés par le nuanceur.
QShader ne fait aucune supposition quant au langage d'ombrage qui a été utilisé comme source pour générer les différentes versions et variantes qui sont incluses dans QShader.
QShader utilise le partage implicite de la même manière que de nombreux types Qt Core, et peut donc être renvoyé ou passé par valeur. Le détachement se fait implicitement lors de l'appel d'un setter.
À titre de référence, un site QRhi portable typique s'attend à ce qu'un QShader adapté à tous ses backends contienne au moins les éléments suivants. (ceci exclut le support des contextes OpenGL de profil central, ajoutez GLSL 150 ou plus récent pour cela)
- SPIR-V 1.0 bytecode adapté à Vulkan 1.0 ou plus récent
- Code source GLSL/ES 100 adapté à OpenGL ES 2.0 ou plus récent
- Code source GLSL 120 adapté à OpenGL 2.1 ou plus récent
- Code source HLSL Shader Model 5.0 ou bytecode DXBC correspondant adapté à Direct3D 11/12
- Code source du Metal Shading Language 1.2 ou bytecode correspondant adapté à Metal 1.2 ou plus récent.
Voir aussi QShaderBaker.
Documentation sur les types de membres
[alias] QShader::NativeResourceBindingMap
Synonyme de QMap<int, std::pair<int, int>>.
Le modèle de liaison des ressources utilisé par QRhi est basé sur SPIR-V. Cela signifie que les tampons uniformes, les tampons de stockage, les échantillonneurs d'images combinées et les images de stockage partagent un espace de points de liaison commun. Les numéros de liaison dans QShaderDescription et QRhiShaderResourceBinding sont censés correspondre au qualificateur de disposition binding dans le shader GLSL compatible avec Vulkan.
Les API graphiques autres que Vulkan peuvent utiliser un modèle de liaison des ressources qui n'est pas entièrement compatible avec ce modèle. Le générateur du code de shader traduit à partir de SPIR-V peut choisir de ne pas prendre en compte les qualificatifs de liaison de SPIR-V, pour diverses raisons. C'est le cas du backend Metal de SPIRV-Cross, par exemple. En outre, même lorsqu'une traduction automatique et implicite est généralement possible (par exemple en utilisant les points de liaison SPIR-V comme indices de registre de ressources HLSL), l'attribution de liaisons de ressources sans être contraint par les points de liaison SPIR-V peut conduire à de meilleurs résultats.
Par conséquent, un site QShader peut exposer une carte supplémentaire qui décrit le point de liaison natif pour une liaison SPIR-V donnée. Les backends QRhi, pour lesquels cela est pertinent, sont censés utiliser cette carte automatiquement, le cas échéant. La valeur est une paire, car les échantillonneurs d'images combinés peuvent correspondre à deux ressources natives (une texture et un échantillonneur) dans certains langages d'ombrage. Dans ce cas, la deuxième valeur fait référence à l'échantillonneur.
Remarque : la liaison native peut être -1, dans le cas où il n'y a pas de liaison active pour la ressource dans le shader. (La carte est toujours complète, ce qui signifie qu'il y a une entrée pour tous les blocs uniformes, blocs de stockage, objets image et échantillonneurs combinés déclarés, mais la valeur sera -1 pour ceux qui ne sont pas réellement référencés dans les fonctions de l'outil d'ombrage.
[alias] QShader::SeparateToCombinedImageSamplerMappingList
Synonyme de QList<QShader::SeparateToCombinedImageSamplerMapping>.
enum class QShader::SerializedFormatVersion
Décrit le format de sortie souhaité lors de la sérialisation de QShader.
La valeur par défaut de l'argument version de serialized() est Latest. Cette valeur est suffisante dans la grande majorité des cas. La spécification d'une autre valeur n'est nécessaire que lorsque l'intention est de générer des données sérialisées qui peuvent être chargées par des versions antérieures de Qt. Par exemple, l'outil qsb utilise ces valeurs d'énumération lorsque l'argument de ligne de commande --qsbversion est donné.
Remarque : le fait de cibler des versions antérieures rendra certaines fonctionnalités inopérantes avec la ressource générée. Ce n'est pas un problème lorsque la ressource est utilisée avec l'ancienne version de Qt spécifiée, étant donné que cette version de Qt ne dispose pas des nouvelles fonctionnalités des versions plus récentes de Qt qui reposent sur des données supplémentaires générées dans QShader et le flux de données sérialisé, mais cela peut devenir un problème si la ressource générée est ensuite utilisée avec une version plus récente de Qt.
| Constante | Valeur | Description |
|---|---|---|
QShader::SerializedFormatVersion::Latest | 0 | Version actuelle de Qt |
QShader::SerializedFormatVersion::Qt_6_5 | 1 | Qt 6.5 |
QShader::SerializedFormatVersion::Qt_6_4 | 2 | Qt 6.4 |
enum QShader::Source
Décrit le type de code de shader que contient une entrée.
| Constante | Valeur | Description de la constante |
|---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Direct3D bytecode (HLSL compilé par fxc) |
QShader::MslShader | 4 | Langage d'ombrage métallique |
QShader::DxilShader | 5 | Direct3D bytecode (HLSL compilé par dxc) |
QShader::MetalLibShader | 6 | Metal bytecode précompilé |
QShader::WgslShader | 7 | WGSL |
enum QShader::Stage
Décrit l'étape du pipeline graphique à laquelle le shader est adapté.
| Constante | Valeur | Description |
|---|---|---|
QShader::VertexStage | 0 | Nuanceur de sommet |
QShader::TessellationControlStage | 1 | Nuanceur de contrôle de tessellation (coque) |
QShader::TessellationEvaluationStage | 2 | Nuanceur d'évaluation de la tessellation (domaine) |
QShader::GeometryStage | 3 | Nuanceur de géométrie |
QShader::FragmentStage | 4 | Nuanceur de fragments (pixels) |
QShader::ComputeStage | 5 | Calculateur |
enum QShader::Variant
Décrit le type de code de shader que contient une entrée.
| Constante | Valeur | Description |
|---|---|---|
QShader::StandardShader | 0 | Version normale et non modifiée du code du nuanceur. |
QShader::BatchableVertexShader | 1 | Le nuanceur de sommets a été réécrit pour être adapté à Qt Quick scenegraph batching. |
QShader::UInt16IndexedVertexAsComputeShader | 2 | Un nuanceur de sommets destiné à être utilisé dans un pipeline Metal avec tessellation en combinaison avec des appels de dessin indexés utilisant des données d'index à partir d'un tampon d'index uint16. Pour prendre en charge le pipeline de tessellation Metal, le nuanceur de sommets est traduit en un nuanceur de calcul qui peut dépendre de l'utilisation du tampon d'index dans les appels de dessin (par exemple, si le nuanceur utilise gl_VertexIndex), d'où la nécessité de disposer de trois variantes dédiées. |
QShader::UInt32IndexedVertexAsComputeShader | 3 | Un nuanceur de vertex destiné à être utilisé dans un pipeline Metal avec tessellation en combinaison avec des appels de dessin indexés utilisant des données d'index à partir d'un tampon d'index uint32. Pour prendre en charge le pipeline de tessellation Metal, le nuanceur de sommets est traduit en un nuanceur de calcul qui peut dépendre de l'utilisation du tampon d'index dans les appels de dessin (par exemple, si le nuanceur utilise gl_VertexIndex), d'où la nécessité de trois variantes dédiées. |
QShader::NonIndexedVertexAsComputeShader | 4 | Un nuanceur de vertex destiné à être utilisé dans un pipeline Metal avec tessellation en combinaison avec des appels de dessin non indexés. Pour prendre en charge le pipeline de tessellation Metal, le nuanceur de sommets est traduit en un nuanceur de calcul qui peut dépendre de l'utilisation du tampon d'index dans les appels de dessin (par exemple, si le nuanceur utilise gl_VertexIndex), d'où la nécessité de trois variantes dédiées. |
QShader::HdrCapableFragmentShader (since Qt 6.10) | 5 | Un nuanceur de fragment réécrit pour prendre en charge le rendu de la gamme dynamique élevée dans une scène Qt Quick. |
Documentation des fonctions membres
QShader::QShader()
Construit une nouvelle instance de QShader vide (et donc invalide).
QShader::QShader(const QShader &other)
Construit une copie de other.
[noexcept, since 6.7] QShader::QShader(QShader &&other)
Move-construit un nouveau QShader à partir de other.
Remarque : l'objet déplacé other est placé dans un état partiellement formé, dans lequel les seules opérations valides sont la destruction et l'attribution d'une nouvelle valeur.
Cette fonction a été introduite dans Qt 6.7.
[noexcept] QShader::~QShader()
Destructeur.
QList<QShaderKey> QShader::availableShaders() const
Retourne la liste des versions de shaders disponibles
QShaderDescription QShader::description() const
Renvoie les métadonnées de réflexion pour le shader.
Voir aussi setDescription().
[static] QShader QShader::fromSerialized(const QByteArray &data)
Crée une nouvelle instance QShader à partir de data.
Si data ne peut pas être désérialisé avec succès, le résultat est une construction par défaut de QShader pour laquelle isValid() renvoie false.
Attention : Les paquets de shaders, y compris les fichiers .qsb dans le système de fichiers, sont supposés être des contenus de confiance. Il est conseillé aux développeurs d'applications d'examiner attentivement les implications potentielles avant d'autoriser le chargement d'un contenu fourni par l'utilisateur qui ne fait pas partie de l'application.
Voir également serialized().
bool QShader::isValid() const
Retourne true si le site QShader contient au moins une version de shader.
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
Renvoie la carte de liaison native pour key. La carte est vide si aucune correspondance n'est disponible pour key (par exemple, parce que la carte n'est pas applicable à l'API et au langage d'ombrage décrits par key).
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
Renvoie la structure native d'informations sur les shaders pour key, ou un objet vide s'il n'y a pas de données disponibles pour key, par exemple parce qu'une telle correspondance n'est pas applicable pour le langage d'ombrage ou l'étape de shaders.
Voir aussi setNativeShaderInfo().
void QShader::removeNativeShaderInfo(const QShaderKey &key)
Supprime les informations du shader natif pour key.
void QShader::removeResourceBindingMap(const QShaderKey &key)
Supprime la carte de liaison des ressources natives pour key.
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
Supprime la liste de correspondance de l'échantillonneur d'images combiné pour key.
void QShader::removeShader(const QShaderKey &key)
Supprime le code source ou binaire du shader pour un site key donné. Ne fait rien s'il n'est pas trouvé.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
Renvoie la liste des correspondances de l'échantillonneur d'images combiné pour key, ou une liste vide s'il n'y a pas de données disponibles pour key, par exemple parce qu'une telle correspondance n'est pas applicable pour le langage d'ombrage.
Voir aussi setSeparateToCombinedImageSamplerMappingList().
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
Renvoie une version binaire sérialisée de toutes les données contenues dans le site QShader, adaptée à l'écriture dans des fichiers ou d'autres périphériques d'entrée/sortie.
Par défaut, le dernier format de sérialisation est utilisé. Utilisez le paramètre version pour sérialiser pour une version Qt compatible. Ce n'est que lorsqu'on sait que le flux de données généré doit être rendu compatible avec une ancienne version de Qt au prix d'une incompatibilité avec les fonctionnalités introduites depuis cette version de Qt, qu'une autre valeur (par exemple, Qt_6_5 pour Qt 6.5) doit être utilisée.
Voir aussi fromSerialized().
void QShader::setDescription(const QShaderDescription &desc)
Définit les métadonnées de réflexion à desc.
Voir aussi description().
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
Stocke le shader natif info associé à key.
Voir aussi nativeShaderInfo().
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
Enregistre le lien de ressource natif donné map associé à key.
Voir aussi nativeResourceBindingMap().
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
Stocke le mappage de l'échantillonneur d'images combiné donné list associé à key.
Voir aussi separateToCombinedImageSamplerMappingList().
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
Stocke le code source ou binaire shader pour une version de shader donnée spécifiée par key.
Voir aussi shader().
void QShader::setStage(QShader::Stage stage)
Définit le pipeline stage.
Voir aussi stage().
QShaderCode QShader::shader(const QShaderKey &key) const
Renvoie le code source ou binaire pour une version de shader donnée, spécifiée par key.
Voir aussi setShader().
QShader::Stage QShader::stage() const
Renvoie l'étape du pipeline à laquelle le shader est destiné.
Voir aussi setStage().
[noexcept, since 6.7] void QShader::swap(QShader &other)
Remplace ce shader par other. Cette opération est très rapide et n'échoue jamais.
Cette fonction a été introduite dans Qt 6.7.
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
Move-assigne other à cette instance QShader.
Remarque : L'objet déplacé other est placé dans un état partiellement formé, dans lequel les seules opérations valables sont la destruction et l'attribution d'une nouvelle valeur.
Cette fonction a été introduite dans Qt 6.7.
QShader &QShader::operator=(const QShader &other)
Attribue other à cet objet.
Non-membres apparentés
[noexcept] size_t qHash(const QShader &key, size_t seed = 0)
Renvoie la valeur de hachage pour key, en utilisant seed comme base de calcul.
[noexcept] bool operator!=(const QShader &lhs, const QShader &rhs)
Renvoie false si les valeurs des deux objets QShader lhs et rhs sont égales ; sinon, renvoie true.
[noexcept] bool operator==(const QShader &lhs, const QShader &rhs)
Renvoie true si les deux objets QShader lhs et rhs sont égaux, ce qui signifie qu'ils correspondent à la même étape avec les mêmes ensembles de sources de shaders ou de codes binaires.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
