QShader Class
Contient plusieurs versions d'un shader traduites dans plusieurs langages de shading, ainsi que des métadonnées de réflexion. En savoir plus...
| En-tête : | #include <qshader.h> |
| 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 des classes de rendu 3D et des classes partagées implicitement.
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) |
Éléments 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 vers le code de shader dans l’univers Qt, indépendant des API graphiques. Au lieu d'utiliser des sources de shaders GLSL, comme c'était le cas avec Qt 5.x, les nouveaux systèmes graphiques dotés de backends pour plusieurs API graphiques, tels que Vulkan, Metal, Direct3D et OpenGL, utilisent QShader comme entrée chaque fois qu'un shader doit être spécifié.
Avertissement : la famille de classes « QRhi » du module Qt GUI, comprenant notamment QShader et QShaderDescription, n’offre que des garanties de compatibilité limitées. Il n’existe aucune garantie de compatibilité au niveau du code source ou des binaires pour ces classes, ce qui signifie que le fonctionnement de l’API n’est garanti qu’avec la version de Qt sur laquelle l’application a été développée. Les modifications entraînant une incompatibilité au niveau du code source sont toutefois destinées à être réduites au minimum et ne seront apportées que dans les versions mineures (6.7, 6.8, etc.). Pour utiliser ces classes dans une application, liez-la à Qt::GuiPrivate (si vous utilisez CMake) et incluez les en-têtes portant 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 utilisable, les deux méthodes courantes sont les suivantes :
- Générer le contenu hors ligne, lors de la compilation ou plus tôt, à l’aide de l’outil en ligne de commande
qsb. Le résultat est un fichier binaire fourni avec l’application, lu via QIODevice::readAll(), puis désérialisé via fromSerialized(). Pour plus d’informations, consultez QShaderBaker. - Génération à 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 code source de shaders fournies par l’utilisateur ou générées dynamiquement.
Lorsqu’elle est utilisée conjointement avec l’interface matérielle de rendu Qt et ses classes, telles que ` QRhiGraphicsPipeline`, aucune action supplémentaire n’est requise de la part de l’application, car ces classes sont prêtes à utiliser un `QShader` dès qu’un shader doit être spécifié pour une étape donnée du pipeline graphique.
Sinon, les applications peuvent accéder
- le code source ou le code octet de n’importe quelle version du langage de shader incluse 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, telles que les blocs uniform. Cela est essentiel lorsqu'une application ou un framework doit découvrir les entrées d'un shader lors de l'exécution, car il ne dispose pas d'informations préalables sur les attributs de sommet ou la disposition des tampons uniform utilisés par le shader.
QShader ne fait aucune supposition quant au langage de shader qui a servi de source pour générer les différentes versions et variantes qu’il contient.
QShader utilise le partage implicite, à l’instar de nombreux types Qt Core, et peut donc être renvoyé ou transmis par valeur. Le détachement s’effectue implicitement lors de l’appel d’un setter.
À titre de référence, une « QRhi » typique et portable s’attend à ce qu’un QShader adapté à tous ses backends contienne au moins les éléments suivants. (Ceci exclut la prise en charge des contextes OpenGL de profil de base ; ajoutez GLSL 150 ou une version plus récente pour cela.)
- Un bytecode SPIR-V 1.0 compatible avec Vulkan 1.0 ou une version plus récente
- Code source GLSL/ES 100 compatible avec OpenGL ES 2.0 ou version plus récente
- Code source GLSL 120 compatible avec OpenGL 2.1 ou version plus récente
- Code source HLSL Shader Model 5.0 ou bytecode DXBC correspondant compatible avec Direct3D 11/12
- Code source Metal Shading Language 1.2 ou bytecode correspondant compatible avec Metal 1.2 ou version ultérieure
Voir également 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 sur lequel repose QRhi est basé sur SPIR-V. Cela signifie que les tampons uniformes, les tampons de stockage, les échantillonneurs d’images combinés et les images de stockage partagent un espace de points de liaison commun. Les numéros de liaison dans QShaderDescription et QRhiShaderResourceBinding doivent 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 de ressources qui n’est pas entièrement compatible avec celui-ci. Le générateur du code de shader traduit à partir de SPIR-V peut choisir de ne pas prendre en compte les qualificateurs de liaison SPIR-V, pour diverses raisons. C’est le cas, par exemple, du backend Metal de SPIRV-Cross. De plus, même lorsqu’une traduction automatique et implicite est en grande partie possible (par exemple en utilisant les points de liaison SPIR-V comme indices de registres 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 « QShader » peut exposer une correspondance supplémentaire décrivant quel est le point de liaison natif correspondant à une liaison SPIR-V donnée. Les backends d’ QRhi, pour lesquels cela est pertinent, sont censés utiliser automatiquement cette correspondance, le cas échéant. La valeur est un couple, car les échantillonneurs d’images combinés peuvent correspondre à deux ressources natives (une texture et un échantillonneur) dans certains langages de shader. Dans ce cas, la deuxième valeur fait référence à l’échantillonneur.
Remarque : la liaison native peut être égale à -1 s’il n’existe aucune liaison active pour la ressource dans le shader. (par exemple, un bloc uniforme est déclaré, mais il n’est pas utilisé dans le code du shader.) La table est toujours complète, ce qui signifie qu’il existe 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 du shader.
[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 l'QShader.
La valeur par défaut de l'argument ` version ` de la fonction ` serialized()` est ` Latest`. Cela suffit dans la grande majorité des cas. Il n'est nécessaire de spécifier une autre valeur que lorsque l'on souhaite générer des données sérialisées pouvant ê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 fourni.
Remarque : le ciblage de versions antérieures rendra certaines fonctionnalités inopérantes avec la ressource générée. Cela ne pose pas de problème lorsque l'asset est utilisé avec la version antérieure de Qt spécifiée, à condition que cette version ne dispose pas des nouvelles fonctionnalités présentes dans les versions plus récentes de Qt, qui s'appuient sur des données supplémentaires générées dans l'QShader et le flux de données sérialisées ; cela peut toutefois poser problème si l'asset généré est ensuite utilisé avec une version plus récente de Qt.
| Constante | Valeur | Description |
|---|---|---|
QShader::SerializedFormatVersion::Latest | 0 | La 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 contenu dans une entrée.
| Constante | Valeur | Description |
|---|---|---|
QShader::SpirvShader | 0 | SPIR-V |
QShader::GlslShader | 1 | GLSL |
QShader::HlslShader | 2 | HLSL |
QShader::DxbcShader | 3 | Bytecode Direct3D (HLSL compilé par fxc) |
QShader::MslShader | 4 | Metal Shading Language |
QShader::DxilShader | 5 | Bytecode Direct3D (HLSL compilé par dxc) |
QShader::MetalLibShader | 6 | Bytecode Metal 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 | Shader de sommets |
QShader::TessellationControlStage | 1 | Shader de contrôle de tessellation (hull) |
QShader::TessellationEvaluationStage | 2 | Shader d'évaluation de la tessellation (domaine) |
QShader::GeometryStage | 3 | Shader de géométrie |
QShader::FragmentStage | 4 | Shader de fragment (pixel) |
QShader::ComputeStage | 5 | Shader de calcul |
enum QShader::Variant
Décrit le type de code de shader contenu dans une entrée.
| Constante | Valeur | Description |
|---|---|---|
QShader::StandardShader | 0 | Version normale et non modifiée du code du shader. |
QShader::BatchableVertexShader | 1 | Shader de sommet réécrit pour être adapté au traitement par lots du graphe de scène d'Qt Quick. |
QShader::UInt16IndexedVertexAsComputeShader | 2 | Un shader de sommets destiné à être utilisé dans un pipeline Metal avec tessellation, en combinaison avec des appels de dessin indexés s'appuyant sur les données d'index provenant d'un tampon d'index uint16. Pour prendre en charge le pipeline de tessellation Metal, le shader de sommets est converti en un shader de calcul qui peut dépendre de l’utilisation du tampon d’index dans les appels de dessin (par exemple, si le shader utilise gl_VertexIndex), d’où la nécessité de disposer de trois variantes dédiées. |
QShader::UInt32IndexedVertexAsComputeShader | 3 | Un shader de sommets destiné à être utilisé dans un pipeline Metal avec tessellation, en combinaison avec des appels de dessin indexés s'appuyant sur des données d'index provenant d'un tampon d'index uint32. Pour prendre en charge le pipeline de tessellation Metal, le shader de sommets est converti en un shader de calcul qui peut dépendre de l’utilisation du tampon d’index dans les appels de dessin (par exemple, si le shader utilise gl_VertexIndex), d’où la nécessité de disposer de trois variantes dédiées. |
QShader::NonIndexedVertexAsComputeShader | 4 | Un shader de sommets 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 shader de sommets est converti en un shader de calcul qui peut dépendre de l’utilisation du tampon d’index dans les appels de dessin (par exemple, si le shader utilise gl_VertexIndex), d’où la nécessité de trois variantes dédiées. |
QShader::HdrCapableFragmentShader (since Qt 6.10) | 5 | Un shader de fragment réécrit pour prendre en charge le rendu à plage dynamique élevée dans un graphe de scène « Qt Quick ». |
Documentation des fonctions membres
QShader::QShader()
Crée une nouvelle instance QShader vide (et donc non valide).
QShader::QShader(const QShader &other)
Crée une copie de other.
[noexcept, since 6.7] QShader::QShader(QShader &&other)
La fonction « move » construit un nouvel objet QShader à partir de other.
Remarque : l'objet d'origine other est placé dans un état partiellement formé, dans lequel les seules opérations valides sont la destruction et l'affectation d'une nouvelle valeur.
Cette fonction a été introduite dans Qt 6.7.
[noexcept] QShader::~QShader()
Destructeur.
QList<QShaderKey> QShader::availableShaders() const
Renvoie la liste des versions de shaders disponibles
QShaderDescription QShader::description() const
Renvoie les métadonnées de réflexion du shader.
Voir également setDescription().
[static] QShader QShader::fromSerialized(const QByteArray &data)
Crée une nouvelle instance de ` QShader ` à partir de l'objet ` data` fourni.
Si la désérialisation de ` data ` échoue, le résultat est un objet ` QShader ` construit par défaut pour lequel la méthode ` isValid()` renvoie ` false`.
Avertissement : les paquetsde shaders , y compris les fichiers .qsb présents dans le système de fichiers, sont considérés comme du contenu fiable. Il est conseillé aux développeurs d’applications d’examiner attentivement les implications potentielles avant d’autoriser le chargement de contenu fourni par l’utilisateur qui ne fait pas partie de l’application.
Voir également serialized().
bool QShader::isValid() const
Renvoie « true » si l'QShader contient au moins une version de shader.
QShader::NativeResourceBindingMap QShader::nativeResourceBindingMap(const QShaderKey &key) const
Renvoie la table de correspondance native pour key. La table est vide s'il n'existe aucun mappage pour key (par exemple, parce que la table ne s'applique pas à l'API et au langage de shading décrits sur key).
QShader::NativeShaderInfo QShader::nativeShaderInfo(const QShaderKey &key) const
Renvoie la structure d'informations native du shader pour key, ou un objet vide s'il n'y a pas de données disponibles pour key, par exemple parce qu'un tel mappage n'est pas applicable au langage de shader ou à l'étape de shader.
Voir également setNativeShaderInfo().
void QShader::removeNativeShaderInfo(const QShaderKey &key)
Supprime les informations relatives au shader natif de key.
void QShader::removeResourceBindingMap(const QShaderKey &key)
Supprime la table de mappage des ressources natives pour key.
void QShader::removeSeparateToCombinedImageSamplerMappingList(const QShaderKey &key)
Supprime la liste de mappage des échantillons d'images combinés pour key.
void QShader::removeShader(const QShaderKey &key)
Supprime le code source ou le code binaire du shader correspondant à un ` key` donné. Ne fait rien si celui-ci est introuvable.
QShader::SeparateToCombinedImageSamplerMappingList QShader::separateToCombinedImageSamplerMappingList(const QShaderKey &key) const
Renvoie la liste combinée des correspondances d'échantillonnage d'images 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 au langage de shading.
Voir également setSeparateToCombinedImageSamplerMappingList().
QByteArray QShader::serialized(QShader::SerializedFormatVersion version = SerializedFormatVersion::Latest) const
Renvoie une version binaire sérialisée de toutes les données contenues dans l'QShader, adaptée à l'écriture dans des fichiers ou sur d'autres périphériques d'E/S.
Par défaut, le format de sérialisation le plus récent est utilisé. Utilisez le paramètre ` version ` pour effectuer la sérialisation dans un format compatible avec une version antérieure de Qt. Ce n’est que lorsque l’on sait que le flux de données généré doit être rendu compatible avec une version antérieure de Qt, au prix d’une incompatibilité avec les fonctionnalités introduites depuis cette version de Qt, qu’il convient d’utiliser une autre valeur (par exemple, ` Qt_6_5 ` pour Qt 6.5).
Voir également fromSerialized().
void QShader::setDescription(const QShaderDescription &desc)
Définit les métadonnées de réflexion sur « desc ».
Voir également description().
void QShader::setNativeShaderInfo(const QShaderKey &key, const QShader::NativeShaderInfo &info)
Enregistre l'info de shader natif spécifiée, associée à key.
Voir également nativeShaderInfo().
void QShader::setResourceBindingMap(const QShaderKey &key, const QShader::NativeResourceBindingMap &map)
Enregistre la liaison de ressource native spécifiée map associée à key.
Voir également nativeResourceBindingMap().
void QShader::setSeparateToCombinedImageSamplerMappingList(const QShaderKey &key, const QShader::SeparateToCombinedImageSamplerMappingList &list)
Enregistre l'list de mappage de l'échantillonneur d'images combiné spécifié, associé à key.
Voir également separateToCombinedImageSamplerMappingList().
void QShader::setShader(const QShaderKey &key, const QShaderCode &shader)
Enregistre le code source ou le code binaire shader d'une version de shader donnée, spécifiée par key.
Voir également shader().
void QShader::setStage(QShader::Stage stage)
Définit l'stage du pipeline.
Voir également stage().
QShaderCode QShader::shader(const QShaderKey &key) const
Renvoie le code source ou le code binaire correspondant à une version de shader donnée, spécifiée par key.
Voir également setShader().
QShader::Stage QShader::stage() const
Renvoie l'étape du pipeline à laquelle le shader est destiné.
Voir également setStage().
[noexcept, since 6.7] void QShader::swap(QShader &other)
Remplace ce shader par other. Cette opération est très rapide et ne rencontre jamais d'échec.
Cette fonction a été introduite dans Qt 6.7.
[noexcept, since 6.7] QShader &QShader::operator=(QShader &&other)
Cette opération d'affectation par déplacement attribue other à cette instance de QShader.
Remarque : l’objet d’origine other est placé dans un état partiellement formé, dans lequel les seules opérations valides sont la destruction et l’affectation d’une nouvelle valeur.
Cette fonction a été introduite dans Qt 6.7.
QShader &QShader::operator=(const QShader &other)
Attribue la propriété « other » à cet objet.
Non-membres associés
[noexcept] size_t qHash(const QShader &key, size_t seed = 0)
Renvoie la valeur de hachage de key, en utilisant seed comme graine pour le calcul.
[noexcept] bool operator!=(const QShader &lhs, const QShader &rhs)
Renvoie « false » si les valeurs des deux objets « QShader » lhs et rhs sont identiques ; 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 et que leurs ensembles de code source ou binaire de shader sont identiques.
© 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.
