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

QSGMaterialShader Class

La classe QSGMaterialShader représente un programme de nuanceur indépendant de l'API graphique. Plus d'informations...

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 vertex et de fragment shaders, de données qui définissent les changements d'état du pipeline graphique et de logique qui met à jour les ressources graphiques, telles que les tampons uniformes et les textures.

Remarque : toutes les classes portant le préfixe QSG doivent être utilisées uniquement sur le thread de rendu du graphe de scène. Voir Graphique de scène et rendu pour plus d'informations.

Le site QSGMaterial et le QSGM MaterialShader sont étroitement liés. Pour un graphe de scène (y compris les graphes imbriqués), il existe une instance unique de QSGMaterialShader qui encapsule les shaders et les autres données que le graphe de scène utilise pour effectuer le rendu d'un objet avec ce matériau. Chaque site QSGGeometryNode peut avoir une adresse 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(), ce qui garantit qu'il n'y a qu'une seule instance de chaque implémentation de shader.

Dans Qt 5, QSGMaterialShader était lié à OpenGL. Il était construit directement sur QOpenGLShaderProgram et avait des fonctions comme 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 changements d'état du pipeline souhaités) avec 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 faire d'appels OpenGL, Vulkan, Metal ou Direct 3D de son propre chef. Avec la gestion unifiée des shaders, cela permet à un QSGMaterialShader d'être écrit une seule fois et d'être fonctionnel avec n'importe quelle API graphique prise en charge au moment de l'exécution.

Les shaders définis en appelant la fonction protégée setShaderFileName() contrôlent ce que fait le matériau avec les données de vertex de la géométrie, et comment les fragments sont ombrés. Un QSGMaterialShader définit généralement un nuanceur de vertex et un nuanceur de fragment lors de la construction. Changer les shaders par la suite peut ne pas conduire à l'effet désiré et doit être évité.

Dans Qt 6, l'approche par défaut consiste à fournir des 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 à setShaderFileName(). Les fichiers .qsb sont générés hors ligne, ou au plus tard au moment de la construction de l'application, à partir du code source GLSL de style Vulkan à l'aide de l'outil qsb du module Qt Shader Tools.

Il existe trois virtualités qui peuvent être remplacées. Ils fournissent les données, ou la logique pour générer les données, pour les tampons uniformes, les textures et les changements d'état du pipeline.

updateUniformData() est la fonction qui est le plus souvent réimplémentée dans les sous-classes. Cette fonction est censée mettre à jour le contenu d'une page QByteArray qui sera ensuite exposée aux shaders en tant que tampon uniforme. Tout QSGMaterialShader qui possède un bloc uniforme dans son nuanceur de sommets ou de fragments doit réimplémenter updateUniformData().

updateSampledImage() est utile lorsque le code du shader échantillonne des textures. La fonction sera invoquée pour chaque échantillonneur (ou échantillonneur d'images combinées, dans les API le cas échéant), en lui donnant la possibilité de spécifier quelles QSGTexture doivent être exposées au nuanceur.

Les changements d'état du pipeline de nuanceurs sont moins souvent utilisés. Un cas d'utilisation est celui des matériaux qui souhaitent utiliser un mode de fusion spécifique. La fonction correspondante est updateGraphicsPipelineState(). Cette fonction n'est pas appelée à moins que le QSGMaterialShader n'ait opté pour ce mode en définissant l'indicateur UpdatesGraphicsPipelineState. La tâche de la fonction est de mettre à jour l'instance de la structure GraphicsPipelineState qui lui est transmise avec les changements souhaités. Actuellement, seules les fonctionnalités liées au mélange et à l'élimination sont disponibles, les autres états ne peuvent pas être contrôlés par les matériaux.

Un exemple minimal, qui inclut également la prise en charge des textures, pourrait être le suivant. Nous supposons ici que Material est le QSGMaterial qui crée une instance de Shader dans son createShader(), et qu'il contient un QSGTexture que nous voulons échantillonner dans le fragment shader. Le nuanceur de sommets s'appuie uniquement sur la matrice de projection de la vue du modèle.

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 style Vulkan pour les nuanceurs pourrait ressembler à ce qui 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 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);
}

Note : Toutes les classes avec le préfixe QSG doivent être utilisées uniquement sur le thread de rendu du graphe de scène. Voir Scene Graph and Rendering pour plus d'informations.

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

Documentation des types de membres

enum QSGMaterialShader::Flag
flags QSGMaterialShader::Flags

Valeurs des drapeaux indiquant les propriétés spéciales des matériaux.

ConstanteValeurDescription
QSGMaterialShader::UpdatesGraphicsPipelineState0x0001La définition de ce drapeau permet d'appeler updateGraphicsPipelineState().

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

Documentation des fonctions membres

QSGMaterialShader::QSGMaterialShader()

Construit un nouveau QSGMaterialShader.

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

Renvoie le nombre d'éléments dans la variable de l'échantillonneur d'images combinées à l'adresse binding. Cette valeur est extraite du code du nuanceur. La variable peut être un tableau et peut avoir plus d'une dimension.

Le nombre reflète le nombre total d'éléments de l'échantillonneur d'images combinées dans la variable. Dans l'exemple suivant, le nombre pour srcA est 1, srcB est 4 et srcC est 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 dans le paramètre de texture de QSGMaterialShader::updateSampledImage.

Cette fonction a été introduite dans Qt 6.4.

Voir aussi QSGMaterialShader::updateSampledImage.

QSGMaterialShader::Flags QSGMaterialShader::flags() const

Renvoie les drapeaux actuellement définis pour ce nuanceur de matériaux.

Voir aussi setFlags().

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

Définit l'adresse flags sur ce nuanceur de matériaux si on est vrai ; sinon, efface les drapeaux spécifiés.

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

Définit l'adresse flags pour ce nuanceur de matériaux.

Voir également flags().

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

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

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

Définit le filename pour le shader pour le stage spécifié.

Le fichier doit contenir une version sérialisée de QShader.

Attention : Les nuanceurs, y compris les fichiers .qsb, sont supposés être des contenus de confiance. Il est conseillé aux développeurs d'applications d'étudier attentivement les implications potentielles avant d'autoriser le chargement de contenu fourni par l'utilisateur et ne faisant pas partie de l'application.

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

Définit le filename pour le shader pour le stage spécifié.

Le fichier doit contenir un QShader sérialisé.

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

viewCount doit être 2, 3 ou 4. L'adresse filename est ajustée automatiquement en fonction de cela.

Attention : Les shaders, y compris les fichiers .qsb, 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.

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 pour permettre au matériau de fournir un ensemble personnalisé d'états graphiques. L'ensemble des états personnalisables par le matériau est limité au mélange et aux paramètres connexes.

Remarque : cette fonction n'est appelée que si le drapeau 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 chaque fois qu'une modification a été apportée à l'un des membres de ps.

Remarque : le contenu de ps n'est pas persistant entre les invocations de cette fonction.

Le rendu actuel state est transmis par 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 pour 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ées dans le code du nuanceur associé à QSGMaterialShader.

texture est un tableau de pointeurs QSGTexture. Le nombre d'éléments du tableau correspond au nombre d'éléments de la variable de l'échantillonneur d'images spécifiée dans le code du nuanceur. Cette variable peut être un tableau et peut avoir plus d'une dimension. Le nombre d'éléments dans le tableau peut être trouvé via QSGMaterialShader::combinedImageSamplerCount

Lorsqu'un élément de texture est nul, il doit être remplacé par un pointeur QSGTexture valide avant d'être renvoyé. Lorsqu'il est non nul, c'est au matériel de décider si un nouveau QSGTexture * lui est stocké ou s'il met à jour certains paramètres du QSGTexture déjà connu. La propriété de QSGTexture n'est pas transférée.

Le rendu actuel state est transmis par le graphe de scène. Le cas échéant, il appartient au matériau de déclencher la mise en file d'attente des téléchargements de données de texture via QSGTexture::commitTextureOperations().

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

oldMaterial peut être utilisé pour minimiser les changements. 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 graphique de la scène pour mettre à jour le contenu du tampon uniforme du programme shader. L'implémentation n'est pas censée effectuer de véritables opérations graphiques, elle est simplement responsable de la copie des données sur le site QByteArray renvoyé par RenderState::uniformData(). Le graphe de scène se charge de rendre ce tampon visible dans les shaders.

Le rendu actuel state est transmis par le graphe de scène. Si l'état indique qu'un état pertinent est sale, l'implémentation doit mettre à jour la région appropriée dans les données du tampon qui est accessible via RenderState::uniformData(). Lorsqu'un état, tel que la matrice ou l'opacité, n'est pas sale, il n'est pas nécessaire de toucher à la région correspondante puisque les données sont persistantes.

La valeur de retour doit être true chaque fois 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 de couleur plate, doit être extrait de newMaterial pour mettre à jour les régions concernées dans le tampon en conséquence.

oldMaterial peut être utilisé pour minimiser les changements de tampon (qui sont typiquement des appels memcpy) lors de la mise à jour des états des matériaux. Lorsque oldMaterial est null, 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.