QSGMaterial Class

Dokumentation der Mitgliedsfunktionen

[virtual] int QSGMaterial::compare(const QSGMaterial *other) const

Vergleicht dieses Material mit other und gibt 0 zurück, wenn sie gleich sind; -1, wenn dieses Material vor other sortiert werden soll und 1, wenn other vorher sortiert werden soll.

Der Szenegraph kann Geometrieknoten neu anordnen, um Zustandsänderungen zu minimieren. Die Vergleichsfunktion wird während des Sortiervorgangs aufgerufen, so dass die Materialien sortiert werden können, um Zustandsänderungen bei jedem Aufruf von QSGMaterialShader::updateState() zu minimieren.

Der this-Zeiger und other haben garantiert die gleiche type().

[pure virtual] QSGMaterialShader *QSGMaterial::createShader(QSGRendererInterface::RenderMode renderMode) const

Diese Funktion gibt eine neue Instanz der QSGMaterialShader Implementierung zurück, die zum Rendern von Geometrie für eine bestimmte Implementierung von QSGMaterial verwendet wird.

Die Funktion wird für jede Kombination von Materialtyp und renderMode nur einmal aufgerufen und intern zwischengespeichert.

Für die meisten Materialien kann die renderMode ignoriert werden. Einige wenige Materialien benötigen möglicherweise eine spezielle Behandlung für bestimmte Rendermodi. Zum Beispiel, wenn das Material Antialiasing auf eine Weise implementiert, die perspektivische Transformationen berücksichtigt, wenn RenderMode3D verwendet wird.

QSGMaterial::Flags QSGMaterial::flags() const

Gibt die Flaggen des Materials zurück.

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

Setzt das Attribut flags für dieses Material, wenn on wahr ist; andernfalls wird das Attribut gelöscht.

[pure virtual] QSGMaterialType *QSGMaterial::type() const

Diese Funktion wird vom Szenengraphen aufgerufen, um einen Identifikator abzufragen, der für die durch createShader() instanziierte QSGMaterialShader eindeutig ist.

Für viele Materialien wird der typische Ansatz darin bestehen, einen Zeiger auf eine statische und damit global verfügbare QSGMaterialType -Instanz zurückzugeben. Das QSGMaterialType ist ein undurchsichtiges Objekt. Es dient lediglich als typsicherer, einfacher Weg, um eindeutige Materialbezeichner zu erzeugen.

QSGMaterialType *type() const override
{
    static QSGMaterialType type;
    return &type;
}

[since 6.8] int QSGMaterial::viewCount() const

Gibt die Anzahl der Ansichten zurück, falls das Material im Multiview-Rendering verwendet wird.

Normalerweise lautet der Rückgabewert 1. Eine Anzahl von Ansichten größer als 2 impliziert einen Multiview-Rendering-Durchgang. Von Materialien, die Multiview unterstützen, wird erwartet, dass sie viewCount() in createShader() oder in ihrem QSGMaterialShader Konstruktor abfragen und sicherstellen, dass die entsprechenden Shader ausgewählt werden. Der Vertex-Shader sollte dann gl_ViewIndex verwenden, um das Modelview-Projection-Matrix-Array zu indizieren, da es im Multiview-Modus mehrere Matrizen gibt. (eine für jede Ansicht)

Nehmen wir als Beispiel den folgenden einfachen Vertex-Shader:

#version 440

layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf {
    mat4 matrix[2];
    float opacity;
};

void main()
{
    gl_Position = matrix[gl_ViewIndex] * vertexCoord;
    color = vertexColor * opacity;
}

Dieser Shader ist darauf vorbereitet, 2 Ansichten zu verarbeiten, und zwar nur 2 Ansichten. Er ist nicht mit anderen Ansichtszahlen kompatibel. Bei der Konditionierung des Shaders muss das Werkzeug qsb mit --view-count 2 aufgerufen werden oder, bei Verwendung der CMake-Integration, muss VIEW_COUNT 2 im Befehl qt_add_shaders() angegeben werden.

Entwicklern wird empfohlen, die automatisch injizierte Präprozessorvariable QSHADER_VIEW_COUNT zu verwenden, um die Handhabung der unterschiedlichen Anzahl von Ansichten zu vereinfachen. Wenn zum Beispiel die Notwendigkeit besteht, sowohl Non-Multiview als auch Multiview mit einer View-Anzahl von 2 in derselben Quelldatei zu unterstützen, könnte folgendes getan werden:

#version 440

layout(location = 0) in vec4 vertexCoord;
layout(location = 1) in vec4 vertexColor;

layout(location = 0) out vec4 color;

layout(std140, binding = 0) uniform buf {
#if QSHADER_VIEW_COUNT >= 2
    mat4 matrix[QSHADER_VIEW_COUNT];
#else
    mat4 matrix;
#endif
    float opacity;
};

void main()
{
#if QSHADER_VIEW_COUNT >= 2
    gl_Position = matrix[gl_ViewIndex] * vertexCoord;
#else
    gl_Position = matrix * vertexCoord;
#endif
    color = vertexColor * opacity;
}

Dieselbe Quelldatei kann nun zweimal durch qsb oder qt_add_shaders() laufen, einmal ohne Angabe der Anzahl der Ansichten und einmal mit der Anzahl der Ansichten auf 2. Das Material kann dann zur Laufzeit die entsprechende .qsb-Datei anhand von viewCount() auswählen.

Mit CMake könnte dies ähnlich wie im Folgenden aussehen. In diesem Beispiel wird erwartet, dass das entsprechende QSGMaterialShader zwischen :/shaders/example.vert.qsb und :/shaders/multiview/example.vert.qsb wählt, basierend auf dem Wert von viewCount(). (dasselbe gilt für den Fragment-Shader)

qt_add_shaders(application "application_shaders"
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

qt_add_shaders(application "application_multiview_shaders"
    GLSL
        330,300es
    HLSL
        61
    MSL
        12
    VIEW_COUNT
        2
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
    OUTPUTS
        shaders/multiview/example.vert
        shaders/multiview/example.frag
)

Als Bequemlichkeit gibt es auch eine MULTIVIEW Option für qt_add_shaders(). Diese führt zuerst das qsb Werkzeug normal aus, überschreibt dann VIEW_COUNT auf 2, setzt GLSL, HLSL, MSL auf einige geeignete Standardwerte und führt qsb erneut aus, wobei dieses Mal .qsb Dateien mit einem angefügten Suffix ausgegeben werden. Die Materialimplementierung kann dann die Überladung QSGMaterialShader::setShaderFileName() mit einem Argument viewCount verwenden, das automatisch die richtige .qsb-Datei auswählt.

Der folgende Aufruf ist daher weitgehend äquivalent zu dem oben gezeigten Beispielaufruf, mit der Ausnahme, dass keine manuell verwalteten Ausgabedateien angegeben werden müssen. Beachten Sie, dass es Fälle geben kann, in denen die automatisch ausgewählten Shading-Sprachversionen nicht ausreichen. In diesem Fall sollten Anwendungen weiterhin alles explizit angeben.

qt_add_shaders(application "application_multiview_shaders"
    MULTIVIEW
    PREFIX
        /
    FILES
        shaders/example.vert
        shaders/example.frag
)

Siehe QRhi::MultiView, QRhiColorAttachment::setMultiViewCount(), und QRhiGraphicsPipeline::setMultiViewCount() für weitere, tiefergehende Details zur Multiview-Unterstützung in Qt. Der Qt Quick Szenengraphen-Renderer ist darauf vorbereitet, Multiview-Renderziele zu erkennen, wenn sie über QQuickRenderTarget::fromRhiRenderTarget() oder die 3D-API-spezifischen Funktionen wie fromVulkanImage() mit einem arraySize -Argument größer als 1 angegeben werden. Der Renderer wird dann die Anzahl der Ansichten an die Grafikpipelines und die Materialien weitergeben.

Diese Funktion wurde in Qt 6.8 eingeführt.