Back to Qt.io
Contact Us Blog Download Qt
Sur cette page

QSGMaterialShader Class

La classe QSGMaterialShader représente un programme de shader indépendant de toute API graphique. En savoir plus...

En-tête : #include <QSGMaterialShader>
CMake : find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake : QT += quick

Types publics

struct GraphicsPipelineState
class RenderState
enum Flag { UpdatesGraphicsPipelineState }
flags Flags

Fonctions publiques

QSGMaterialShader()
(since 6.4) int combinedImageSamplerCount(int binding) const
QSGMaterialShader::Flags flags() const
void setFlag(QSGMaterialShader::Flags flags, bool on = true)
void setFlags(QSGMaterialShader::Flags flags)
virtual bool updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual void updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)
virtual bool updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

Fonctions protégées

void setShader(QSGMaterialShader::Stage stage, const QShader &shader)
void setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)
(since 6.8) void setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

Description détaillée

QSGMaterialShader représente une combinaison de shaders de sommets et de fragments, de données définissant les changements d'état du pipeline graphique, ainsi que de la logique mettant à jour les ressources graphiques, telles que les tampons uniformes et les textures.

Remarque : toutes les classes préfixées par « QSG » doivent être utilisées exclusivement sur le thread de rendu du graphe de scène. Voir Graphe de scène et rendu pour plus d’informations.

Les classes ` QSGMaterial ` et `QSGMaterialShader` entretiennent une relation étroite. Pour un graphe de scène donné (y compris les graphes imbriqués), il existe une instance unique de QSGMaterialShader qui encapsule les shaders et les autres données utilisées par le graphe de scène pour rendre un objet avec ce matériau. Chaque « QSGGeometryNode » peut disposer d’un « QSGMaterial » unique qui définit la manière dont le pipeline graphique doit être configuré lors du dessin du nœud. Une instance de `QSGMaterialShader` n’est jamais créée explicitement par l’utilisateur ; elle est créée à la demande par le graphe de scène via ` QSGMaterial::createShader()`. Le graphe de scène crée une instance de `QSGMaterialShader` en appelant la méthode ` QSGMaterial::createShader()`, garantissant ainsi qu’il n’existe qu’une seule instance de chaque implémentation de shader.

Dans Qt 5, QSGMaterialShader était lié à OpenGL. Il s’appuyait directement sur ` QOpenGLShaderProgram ` et disposait de fonctions telles que ` updateState() ` qui pouvaient émettre des commandes OpenGL arbitraires. Ce n’est plus le cas dans Qt 6. QSGMaterialShader n’est pas strictement orienté données, ce qui signifie qu’il fournit des données (shaders et modifications souhaitées de l’état du pipeline) ainsi qu’une logique qui met à jour les données dans un tampon uniforme. L’accès à l’API graphique n’est pas fourni. Cela signifie qu’un QSGMaterialShader ne peut pas effectuer de lui-même d’appels OpenGL, Vulkan, Metal ou Direct 3D. Associé à la gestion unifiée des shaders, cela permet d’écrire un QSGMaterialShader une seule fois et de le faire fonctionner avec n’importe quelle API graphique prise en charge lors de l’exécution.

Les shaders définis en appelant la fonction protégée ` setShaderFileName()` contrôlent ce que le matériau effectue avec les données de sommets issues de la géométrie, ainsi que la manière dont les fragments sont ombrés. Un `QSGMaterialShader` définit généralement un shader de sommets et un shader de fragments lors de sa construction. Modifier les shaders par la suite peut ne pas produire l’effet escompté et doit être évité.

Dans Qt 6, l’approche par défaut consiste à livrer les fichiers ` .qsb ` avec l’application, généralement intégrés via le système de ressources, et référencés lors de l’appel de ` setShaderFileName()`. Les fichiers ` .qsb ` sont générés hors ligne, ou au plus tard lors de la compilation de l’application, à partir d’un code source GLSL de type Vulkan à l’aide de l’outil ` qsb ` du module Qt ` Shader Tools `.

Trois méthodes virtuelles peuvent être redéfinies. Celles-ci fournissent les données, ou la logique permettant de générer ces données, pour les tampons uniformes, les textures et les changements d’état du pipeline.

updateUniformData() est la fonction la plus couramment réimplémentée dans les sous-classes. Cette fonction est censée mettre à jour le contenu d’un objet ` QByteArray `, qui sera ensuite exposé aux shaders en tant que tampon uniforme. Tout `QSGMaterialShader` comportant un bloc uniforme dans son shader de sommets ou de fragments doit réimplémenter la fonction ` updateUniformData()`.

updateSampledImage() est pertinente lorsque le code du shader échantillonne des textures. La fonction sera appelée pour chaque échantillonneur (ou échantillonneur d’images combinées, dans les API où cela s’applique), ce qui lui donne la possibilité de spécifier quelle QSGTexture doit être exposée au shader.

Les modifications d’état du pipeline de shaders sont moins fréquemment utilisées. Un cas d’utilisation concerne les matériaux qui souhaitent utiliser un mode de fusion spécifique. La fonction correspondante est ` updateGraphicsPipelineState()`. Cette fonction n’est appelée que si le `QSGMaterialShader` l’a activée en définissant l’indicateur ` UpdatesGraphicsPipelineState`. Le rôle de cette fonction est de mettre à jour l’instance de la structure ` GraphicsPipelineState ` qui lui est transmise avec les modifications souhaitées. Actuellement, seules les fonctionnalités liées au mélange et au culling sont disponibles ; les autres états ne peuvent pas être contrôlés par les matériaux.

Un exemple minimal, incluant également la prise en charge des textures, pourrait être le suivant. Nous partons ici du principe que `Material` est l’ QSGMaterial qui crée une instance de `Shader` dans son ` createShader()` et qu’il contient une ` QSGTexture ` que nous souhaitons échantillonner dans le shader de fragment. Le shader de sommet s’appuie uniquement sur la matrice de projection modèle-vue.

class Shader : public QSGMaterialShader
{
public:
    Shader()
    {
        setShaderFileName(VertexStage, QLatin1String(":/materialshader.vert.qsb"));
        setShaderFileName(FragmentStage, QLatin1String(":/materialshader.frag.qsb"));
    }

    bool updateUniformData(RenderState &state, QSGMaterial *, QSGMaterial *)
    {
        bool changed = false;
        QByteArray *buf = state.uniformData();
        if (state.isMatrixDirty()) {
            const QMatrix4x4 m = state.combinedMatrix();
            memcpy(buf->data(), m.constData(), 64);
            changed = true;
        }
        return changed;
    }

    void updateSampledImage(RenderState &, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *)
    {
        Material *mat = static_cast<Material *>(newMaterial);
        if (binding == 1)
            *texture = mat->texture();
    }
};

Le code source GLSL de type Vulkan pour les shaders pourrait se présenter comme suit. Ceux-ci sont censés être prétraités hors ligne à l’aide de l’outil qsb, qui génère les fichiers .qsb référencés dans le constructeur de Shader().

#version 440
layout(location = 0) in vec4 aVertex;
layout(location = 1) in vec2 aTexCoord;
layout(location = 0) out vec2 vTexCoord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
} ubuf;
out gl_PerVertex { vec4 gl_Position; };
void main() {
    gl_Position = ubuf.qt_Matrix * aVertex;
    vTexCoord = aTexCoord;
}
#version 440
layout(location = 0) in vec2 vTexCoord;
layout(location = 0) out vec4 fragColor;
layout(binding = 1) uniform sampler2D srcTex;
void main() {
    vec4 c = texture(srcTex, vTexCoord);
    fragColor = vec4(c.rgb * 0.5, 1.0);
}

Remarque : toutes les classes préfixées par « QSG » doivent être utilisées exclusivement sur le thread de rendu du graphe de scène. Voir Graphe de scène et rendu pour plus d’informations.

Voir également QSGMaterial, Graphique de scène - Matériau personnalisé, Graphique de scène - Deux fournisseurs de textures et Graphique de scène - Graphique.

Documentation sur les types de membres

enum QSGMaterialShader::Flag
flags QSGMaterialShader::Flags

Valeurs d'indicateur permettant de signaler des propriétés particulières des matériaux.

ConstanteValeurDescription
QSGMaterialShader::UpdatesGraphicsPipelineState0x0001L'activation de cet indicateur permet d'appeler la fonction ` updateGraphicsPipelineState()`.

Le type Flags est un typedef pour QFlags<Flag>. Il stocke une combinaison OR de valeurs de drapeau.

Documentation des fonctions membres

QSGMaterialShader::QSGMaterialShader()

Crée un nouvel objet QSGMaterialShader.

[since 6.4] int QSGMaterialShader::combinedImageSamplerCount(int binding) const

Renvoie le nombre d'éléments contenus dans la variable d'échantillonnage d'images combinées à l'adresse binding. Cette valeur est obtenue par introspection à partir du code du shader. La variable peut être un tableau et peut comporter plusieurs dimensions.

Ce compteur reflète le nombre total d'éléments d'échantillonneur d'image combinés dans la variable. Dans l'exemple suivant, le compteur pour srcA est égal à 1, celui pour srcB à 4 et celui pour srcC à 6.

layout (binding = 0) uniform sampler2D srcA;
layout (binding = 1) uniform sampler2D srcB[4];
layout (binding = 2) uniform sampler2D srcC[2][3];

Ce nombre correspond au nombre de pointeurs QSGTexture présents dans le paramètre de texture de QSGMaterialShader::updateSampledImage.

Cette fonction a été introduite dans Qt 6.4.

Voir également QSGMaterialShader::updateSampledImage.

QSGMaterialShader::Flags QSGMaterialShader::flags() const

Renvoie les indicateurs actuellement définis pour ce shader de matériau.

Voir également setFlags().

void QSGMaterialShader::setFlag(QSGMaterialShader::Flags flags, bool on = true)

Définit l'flags sur ce shader de matériau si la valeur de « on » est « true » ; dans le cas contraire, efface les indicateurs spécifiés.

void QSGMaterialShader::setFlags(QSGMaterialShader::Flags flags)

Définit l'flags pour ce shader de matériau.

Voir aussi flags().

[protected] void QSGMaterialShader::setShader(QSGMaterialShader::Stage stage, const QShader &shader)

Définit l'shader pour l'stage spécifié.

[protected] void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename)

Définit l'filename du shader pour l'stage spécifié.

Le fichier doit contenir une instance d'QShader sérialisée.

Avertissement : les shaders , y compris les fichiers d'.qsb, sont considérés comme du contenu fiable. Il est conseillé aux développeurs d'applications d'évaluer soigneusement les implications potentielles avant d'autoriser le chargement de contenu fourni par l'utilisateur qui ne fait pas partie de l'application.

[protected, since 6.8] void QSGMaterialShader::setShaderFileName(QSGMaterialShader::Stage stage, const QString &filename, int viewCount)

Définit l'filename du shader pour l'stage spécifié.

Le fichier doit contenir une instance d'QShader sérialisée.

Cette surcharge est utilisée lors de l’activation du rendu d’ multiview, en particulier lorsque l’option de commodité MULTIVIEW du système de compilation est utilisée.

viewCount doit être égal à 2, 3 ou 4. L’ filename est ajusté automatiquement en fonction de cette valeur.

Avertissement : les shaders , y compris les fichiers d’ .qsb, sont considérés comme du contenu fiable. Il est conseillé aux développeurs d’applications d’évaluer soigneusement les implications potentielles avant d’autoriser le chargement de contenu fourni par l’utilisateur qui ne fait pas partie de l’application.

Cette fonction a été introduite dans Qt 6.8.

[virtual] bool QSGMaterialShader::updateGraphicsPipelineState(QSGMaterialShader::RenderState &state, QSGMaterialShader::GraphicsPipelineState *ps, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

Cette fonction est appelée par le graphe de scène afin de permettre au matériau de fournir un ensemble personnalisé d'états graphiques. L'ensemble des états personnalisables par matériau se limite aux paramètres de fusion et aux paramètres associés.

Remarque : cette fonction n’est appelée que lorsque l’indicateur « UpdatesGraphicsPipelineState » a été activé via setFlags(). Par défaut, il n’est pas activé, et cette fonction n’est donc jamais appelée.

La valeur de retour doit être true dès lors qu’une modification a été apportée à l’un des membres de ps.

Remarque : le contenu de ` ps ` n’est pas conservé d’un appel à l’autre de cette fonction.

L'state de rendu actuel est transmis depuis le graphe de scène.

L’état spécifique à la sous-classe peut être extrait de newMaterial. Lorsque oldMaterial est nul, ce shader vient d’être activé.

[virtual] void QSGMaterialShader::updateSampledImage(QSGMaterialShader::RenderState &state, int binding, QSGTexture **texture, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

Cette fonction est appelée par le graphe de scène afin de préparer l'utilisation d'images échantillonnées dans le shader, généralement sous la forme d'échantillonneurs d'images combinés.

binding est le numéro de liaison de l'échantillonneur. La fonction est appelée pour chaque variable d'échantillonneur d'images combiné dans le code du shader associé à l'QSGMaterialShader.

texture est un tableau de pointeurs vers des objets ` QSGTexture `. Le nombre d’éléments du tableau correspond au nombre d’éléments de la variable d’échantillonneur d’images spécifiée dans le code du shader. Cette variable peut être un tableau et peut comporter plusieurs dimensions. Le nombre d’éléments du tableau peut être obtenu via QSGMaterialShader::combinedImageSamplerCount

Lorsqu’un élément de ` texture ` est nul, il doit être défini sur un pointeur ` QSGTexture ` valide avant le retour. Lorsqu’il n’est pas nul, il appartient au matériau de décider si une nouvelle ` QSGTexture * ` y est stockée, ou s’il met à jour certains paramètres de la ` QSGTexture` déjà connue. La propriété de la ` QSGTexture ` n’est pas transférée.

L’ state de rendu actuelle est transmise depuis le graphe de scène. Le cas échéant, c’est au matériau de déclencher la mise en file d’attente des chargements de données de texture via ` QSGTexture::commitTextureOperations()`.

L’état spécifique à la sous-classe peut être extrait de ` newMaterial`.

oldMaterial peut être utilisé pour minimiser les modifications. Lorsque oldMaterial est nul, ce shader vient d’être activé.

Voir également QSGMaterialShader::combinedImageSamplerCount.

[virtual] bool QSGMaterialShader::updateUniformData(QSGMaterialShader::RenderState &state, QSGMaterial *newMaterial, QSGMaterial *oldMaterial)

Cette fonction est appelée par le graphe de scène afin de mettre à jour le contenu du tampon uniforme du programme de shader. L’implémentation n’est pas censée effectuer d’opérations graphiques proprement dites ; elle est simplement chargée de copier les données dans l’ QByteArray renvoyé par la fonction RenderState::uniformData(). Le graphe de scène se charge de rendre ce tampon visible dans les shaders.

L’ state de rendu actuel est transmis par le graphe de scène. Si l’état indique qu’un élément pertinent est modifié, l’implémentation doit mettre à jour la zone appropriée des données du tampon, accessible via RenderState::uniformData(). Lorsqu’un élément, tel qu’une matrice ou l’opacité, n’est pas modifié, il n’est pas nécessaire de modifier la zone correspondante, car les données sont persistantes.

La valeur de retour doit être true dès lors qu’une modification a été apportée aux données uniformes.

L’état spécifique à la sous-classe, tel que la couleur d’un matériau à couleur unie, doit être extrait de newMaterial afin de mettre à jour en conséquence les régions concernées dans le tampon.

oldMaterial peut être utilisé pour minimiser les modifications du tampon (qui sont généralement des appels à memcpy) lors de la mise à jour des états des matériaux. Lorsque oldMaterial est nul, ce shader vient d’être activé.

© 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.