Back to Qt.io
Contact Us Blog Download Qt
Auf dieser Seite

QSGMaterialShader Class

Die Klasse „QSGMaterialShader“ stellt ein von der Grafik-API unabhängiges Shader-Programm dar. Mehr...

Header: #include <QSGMaterialShader>
CMake: find_package(Qt6 REQUIRED COMPONENTS Quick)
target_link_libraries(mytarget PRIVATE Qt6::Quick)
qmake: QT += quick

Öffentliche Typen

struct GraphicsPipelineState
class RenderState
enum Flag { UpdatesGraphicsPipelineState }
flags Flags

Öffentliche Funktionen

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)

Geschützte Funktionen

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)

Ausführliche Beschreibung

QSGMaterialShader stellt eine Kombination aus Vertex- und Fragment-Shadern, Daten, die Zustandsänderungen in der Grafik-Pipeline definieren, sowie Logik dar, die Grafikressourcen wie Uniform-Puffer und Texturen aktualisiert.

Hinweis: Alle Klassen mit dem Präfix „QSG“ sollten ausschließlich im Rendering-Thread des Szenengraphen verwendet werden. Weitere Informationen finden Sie unter „Szenengraph und Rendering “.

Der „ QSGMaterial “ und der „QSGMaterialShader“ stehen in enger Beziehung zueinander. Für einen Szenengraphen (einschließlich verschachtelter Graphen) gibt es eine eindeutige „QSGMaterialShader“-Instanz, die die Shader und andere Daten kapseln, die der Szenengraph verwendet, um ein Objekt mit diesem Material zu rendern. Jeder „ QSGGeometryNode “ kann einen eindeutigen „ QSGMaterial “ haben, der definiert, wie die Grafikpipeline beim Zeichnen des Knotens konfiguriert werden muss. Eine Instanz von `QSGMaterialShader` wird niemals explizit vom Benutzer erstellt, sondern bei Bedarf vom Szenengraphen über ` QSGMaterial::createShader()` angelegt. Der Szenengraph erstellt eine Instanz von `QSGMaterialShader` durch Aufruf der Methode ` QSGMaterial::createShader()`, wodurch sichergestellt wird, dass es von jeder Shader-Implementierung nur eine Instanz gibt.

In Qt 5 war QSGMaterialShader an OpenGL gebunden. Es basierte direkt auf „ QOpenGLShaderProgram “ und verfügte über Funktionen wie „ updateState() “, die beliebige OpenGL-Befehle ausgeben konnten. Dies ist in Qt 6 nicht mehr der Fall. QSGMaterialShader ist nicht streng datenorientiert, d. h., er stellt Daten (Shader und die gewünschten Änderungen des Pipeline-Zustands) zusammen mit einer Logik bereit, die die Daten in einem einheitlichen Puffer aktualisiert. Ein Zugriff auf die Grafik-API wird nicht bereitgestellt. Das bedeutet, dass ein `QSGMaterialShader` nicht eigenständig OpenGL-, Vulkan-, Metal- oder Direct 3D-Aufrufe ausführen kann. Zusammen mit der einheitlichen Shader-Verwaltung ermöglicht dies, dass ein `QSGMaterialShader` einmal geschrieben wird und zur Laufzeit mit jeder der unterstützten Grafik-APIs funktioniert.

Die Shader, die durch den Aufruf der geschützten Funktion ` setShaderFileName()` festgelegt werden, steuern, wie das Material die Vertex-Daten aus der Geometrie verarbeitet und wie die Fragmente schattiert werden. Ein `QSGMaterialShader` legt in der Regel beim Erstellen einen Vertex- und einen Fragment-Shader fest. Eine nachträgliche Änderung der Shader führt möglicherweise nicht zum gewünschten Ergebnis und sollte vermieden werden.

In Qt 6 besteht der Standardansatz darin, ` .qsb `-Dateien mit der Anwendung auszuliefern, die in der Regel über das Ressourcensystem eingebettet sind und beim Aufruf von ` setShaderFileName()` referenziert werden. Die ` .qsb `-Dateien werden offline oder spätestens zum Zeitpunkt der Anwendungserstellung aus GLSL-Quellcode im Vulkan-Stil mithilfe des Tools ` qsb ` aus dem Qt-Modul ` Shader Tools ` generiert.

Es gibt drei virtuelle Methoden, die überschrieben werden können. Diese stellen die Daten oder die Logik zur Erzeugung der Daten für Uniform-Puffer, Texturen und Änderungen des Pipeline-Zustands bereit.

updateUniformData() ist die Funktion, die in Unterklassen am häufigsten neu implementiert wird. Von dieser Funktion wird erwartet, dass sie den Inhalt eines ` QByteArray ` aktualisiert, der dann den Shadern als Uniform-Puffer zur Verfügung gestellt wird. Jeder `QSGMaterialShader`, der einen Uniform-Block in seinem Vertex- oder Fragment-Shader enthält, muss ` updateUniformData()` neu implementieren.

updateSampledImage() ist relevant, wenn der Shader-Code Texturen abtastet. Die Funktion wird für jeden Sampler (oder kombinierten Bild-Sampler, sofern in den APIs relevant) aufgerufen und bietet die Möglichkeit, anzugeben, welche ` QSGTexture ` dem Shader zur Verfügung gestellt werden soll.

Änderungen am Shader-Pipeline-Status werden seltener verwendet. Ein Anwendungsfall sind Materialien, die einen bestimmten Mischmodus verwenden möchten. Die relevante Funktion ist ` updateGraphicsPipelineState()`. Diese Funktion wird nur aufgerufen, wenn der `QSGMaterialShader` dies durch Setzen des Flags ` UpdatesGraphicsPipelineState` aktiviert hat. Die Aufgabe der Funktion besteht darin, die an sie übergebene Instanz der Struktur ` GraphicsPipelineState ` mit den gewünschten Änderungen zu aktualisieren. Derzeit sind nur Funktionen im Zusammenhang mit Überblendungen und Culling verfügbar; andere Zustände können nicht über Materialien gesteuert werden.

Ein Minimalbeispiel, das auch Texturunterstützung beinhaltet, könnte wie folgt aussehen. Hier gehen wir davon aus, dass „Material“ die Struktur „ QSGMaterial “ ist, die in ihrer Funktion „ createShader()“ eine Instanz von „Shader“ erstellt, und dass sie eine „ QSGTexture “-Struktur enthält, die wir im Fragment-Shader abtasten möchten. Der Vertex-Shader stützt sich ausschließlich auf die Model-View-Projection-Matrix.

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();
    }
};

Der GLSL-Quellcode im Vulkan-Stil für die Shader könnte wie folgt aussehen. Es wird erwartet, dass diese offline mit dem Tool „ qsb “ vorverarbeitet werden, das die im Konstruktor von „ Shader() “ referenzierten „ .qsb “-Dateien generiert.

#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);
}

Hinweis: Alle Klassen mit dem Präfix „QSG“ sollten ausschließlich im Rendering-Thread des Szenengraphen verwendet werden. Weitere Informationen finden Sie unter „Szenengraph und Rendering “.

Siehe auch „ QSGMaterial“ , „Szenengrafik – Benutzerdefiniertes Material“, „Szenengrafik – Zwei Textur-Provider“ und „Szenengrafik – Graf“.

Dokumentation zu Mitgliedstypen

enum QSGMaterialShader::Flag
flags QSGMaterialShader::Flags

Kennzeichen zur Angabe besonderer Werkstoffeigenschaften.

KonstanteWertBeschreibung
QSGMaterialShader::UpdatesGraphicsPipelineState0x0001Durch Setzen dieses Flags wird der Aufruf von ` updateGraphicsPipelineState()` ermöglicht.

Der Typ „Flags“ ist ein typedef für QFlags<Flag>. Er speichert eine ODER-Kombination von Flag-Werten.

Dokumentation der Mitgliedsfunktionen

QSGMaterialShader::QSGMaterialShader()

Erstellt einen neuen QSGMaterialShader.

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

Gibt die Anzahl der Elemente in der kombinierten Bild-Sampler-Variablen unter binding zurück. Dieser Wert wird aus dem Shader-Code ermittelt. Die Variable kann ein Array sein und mehr als eine Dimension haben.

Die Anzahl gibt die Gesamtzahl der kombinierten Bild-Sampler-Elemente in der Variablen wieder. Im folgenden Beispiel beträgt die Anzahl für „ srcA “ 1, für „ srcB “ 4 und für „ srcC “ 6.

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

Diese Anzahl entspricht der Anzahl der „ QSGTexture “-Zeiger im Texturparameter von „ QSGMaterialShader::updateSampledImage “.

Diese Funktion wurde in Qt 6.4 eingeführt.

Siehe auch „ QSGMaterialShader::updateSampledImage “.

QSGMaterialShader::Flags QSGMaterialShader::flags() const

Gibt die aktuell für diesen Material-Shader gesetzten Flags zurück.

Siehe auch „ setFlags()“.

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

Setzt die „ flags “ für diesen Material-Shader, wenn „ on “ auf „true“ gesetzt ist; andernfalls werden die angegebenen Flags zurückgesetzt.

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

Legt die „ flags “ für diesen Material-Shader fest.

Siehe auch „ flags()“.

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

Legt die „ shader “ für die angegebene „ stage “ fest.

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

Legt die „ filename “ für den Shader des angegebenen „ stage “ fest.

Die Datei soll eine serialisierte „ QShader “-Datei enthalten.

Warnung: Shader , einschließlich „ .qsb “-Dateien, gelten als vertrauenswürdige Inhalte. Anwendungsentwicklern wird empfohlen, die möglichen Auswirkungen sorgfältig abzuwägen, bevor sie das Laden von benutzerdefinierten Inhalten zulassen, die nicht Teil der Anwendung sind.

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

Legt die „ filename “ für den Shader des angegebenen „ stage “ fest.

Die Datei soll ein serialisiertes ` QShader` enthalten.

Diese Überladung wird verwendet, wenn das „ multiview “-Rendering aktiviert wird, insbesondere wenn die Komfortoption „MULTIVIEW“ des Build-Systems verwendet wird.

viewCount sollte 2, 3 oder 4 betragen. Die „ filename “ wird automatisch entsprechend angepasst.

Warnung: Shader , einschließlich „ .qsb “-Dateien, gelten als vertrauenswürdige Inhalte. Anwendungsentwicklern wird empfohlen, die möglichen Auswirkungen sorgfältig abzuwägen, bevor sie das Laden von benutzerdefinierten Inhalten zulassen, die nicht Teil der Anwendung sind.

Diese Funktion wurde in Qt 6.8 eingeführt.

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

Diese Funktion wird vom Szenengraphen aufgerufen, damit das Material einen benutzerdefinierten Satz von Grafikzuständen bereitstellen kann. Der Satz der Zustände, die pro Material angepasst werden können, beschränkt sich auf Überblendungen und damit verbundene Einstellungen.

Hinweis: Diese Funktion wird nur aufgerufen, wenn das Flag „ UpdatesGraphicsPipelineState “ über „ setFlags()“ aktiviert wurde. Standardmäßig ist es nicht gesetzt, sodass diese Funktion niemals aufgerufen wird.

Der Rückgabewert muss „ true “ lauten, sobald eine Änderung an einem der Elemente in „ ps “ vorgenommen wurde.

Hinweis: Der Inhalt von ` ps ` bleibt zwischen Aufrufen dieser Funktion nicht erhalten.

Der aktuelle Rendering- state wird vom Szenengraphen übergeben.

Der unterklassenspezifische Zustand kann aus newMaterial extrahiert werden. Wenn oldMaterial null ist, wurde dieser Shader gerade erst aktiviert.

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

Diese Funktion wird vom Szenengraphen aufgerufen, um die Verwendung von abgetasteten Bildern im Shader vorzubereiten, typischerweise in Form von kombinierten Bild-Samplern.

binding ist die Bindungsnummer des Samplers. Die Funktion wird für jede kombinierte Bild-Sampler-Variable im Shader-Code aufgerufen, die mit dem ` QSGMaterialShader` verknüpft ist.

texture ist ein Array von Zeigern auf ` QSGTexture `. Die Anzahl der Elemente im Array entspricht der Anzahl der Elemente in der im Shader-Code angegebenen Bild-Sampler-Variablen. Diese Variable kann ein Array sein und mehr als eine Dimension haben. Die Anzahl der Elemente im Array lässt sich über QSGMaterialShader::combinedImageSamplerCount

Wenn ein Element in ` texture ` den Wert `null` hat, muss es vor der Rückgabe auf einen gültigen ` QSGTexture `-Zeiger gesetzt werden. Ist es nicht `null`, liegt es im Ermessen des Materials, zu entscheiden, ob ein neuer ` QSGTexture * ` darin gespeichert wird oder ob es einige Parameter des bereits bekannten ` QSGTexture` aktualisiert. Die Eigentumsrechte an ` QSGTexture ` werden nicht übertragen.

Der aktuelle Rendering- state wird aus dem Szenengraphen übergeben. Gegebenenfalls ist es Aufgabe des Materials, das Einreihen von Texturdaten-Uploads über ` QSGTexture::commitTextureOperations()` auszulösen.

Der unterklassenspezifische Status kann aus ` newMaterial` extrahiert werden.

oldMaterial kann verwendet werden, um Änderungen zu minimieren. Wenn ` oldMaterial ` null ist, wurde dieser Shader gerade erst aktiviert.

Siehe auch QSGMaterialShader::combinedImageSamplerCount.

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

Diese Funktion wird vom Szenengraphen aufgerufen, um den Inhalt des Uniform-Puffers des Shader-Programms zu aktualisieren. Von der Implementierung wird nicht erwartet, dass sie tatsächliche Grafikoperationen durchführt; sie ist lediglich dafür zuständig, Daten in den von ` RenderState::uniformData()` zurückgegebenen ` QByteArray ` zu kopieren. Der Szenengraph sorgt dafür, dass dieser Puffer in den Shadern sichtbar ist.

Der aktuelle Rendering- state wird vom Szenengraphen übergeben. Wenn der Status angibt, dass ein relevanter Zustand „dirty“ ist, muss die Implementierung den entsprechenden Bereich in den Pufferdaten aktualisieren, auf den über ` RenderState::uniformData()` zugegriffen werden kann. Wenn ein Zustand, wie z. B. die Matrix oder die Deckkraft, nicht „dirty“ ist, muss der entsprechende Bereich nicht geändert werden, da die Daten persistent sind.

Der Rückgabewert muss immer ` true ` sein, sobald Änderungen an den einheitlichen Daten vorgenommen wurden.

Der unterklassenspezifische Zustand, wie beispielsweise die Farbe eines „Flat Color“-Materials, sollte aus ` newMaterial ` extrahiert werden, um die entsprechenden Bereiche im Puffer entsprechend zu aktualisieren.

oldMaterial kann verwendet werden, um Änderungen am Puffer (bei denen es sich typischerweise um memcpy-Aufrufe handelt) bei der Aktualisierung von Materialzuständen zu minimieren. Wenn oldMaterial null ist, wurde dieser Shader gerade erst aktiviert.

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