ShaderEffect QML Type

Wendet benutzerdefinierte Shader auf ein Rechteck an. Mehr...

• Liste aller Mitglieder, einschließlich geerbter Mitglieder

Eigenschaften

• blending : bool
• cullMode : enumeration
• fragmentShader : url
• log : string
• mesh : variant
• status : enumeration
• supportsAtlasTextures : bool (since QtQuick 2.4)
• vertexShader : url

Ausführliche Beschreibung

Der Typ „ShaderEffect“ wendet einen benutzerdefinierten Shader vom Typ „ vertex “ und „ fragment (pixel) “ auf ein Rechteck an. Er ermöglicht das Hinzufügen von Effekten wie Schlagschatten, Weichzeichnen, Einfärben und Seitenwölbung in die QML-Szene.

Shader

In Qt 5 wurden Effekte in Form von GLSL-Quellcode (OpenGL Shading Language) bereitgestellt, der häufig als Zeichenketten in QML eingebettet war. Ab Qt 5.8 ist es zudem möglich, auf Dateien zu verweisen, sei es auf lokale Dateien oder auf solche im Qt-Ressourcensystem.

In Qt 6 unterstützt „ Qt Quick “ auch Grafik-APIs wie Vulkan, Metal und Direct3D 11. Daher ist die Arbeit mit GLSL-Quelltext-Zeichenketten nicht mehr möglich. Stattdessen basiert die neue Shader-Pipeline darauf, Vulkan-kompatiblen GLSL-Code in SPIR-V zu kompilieren, anschließend Reflektionsinformationen zu sammeln und diese in andere Shading-Sprachen wie HLSL, die Metal Shading Language und verschiedene GLSL-Versionen zu übersetzen. Die resultierenden Assets werden in einem einzigen Paket zusammengefasst, das in der Regel in Dateien mit der Erweiterung „ .qsb “ gespeichert wird. Dieser Vorgang erfolgt offline oder spätestens zum Zeitpunkt des Anwendungsbuilds. Zur Laufzeit nutzen der Szenengraph und die zugrunde liegende Grafikabstraktion diese „ .qsb “-Dateien. Daher erwartet ShaderEffect in Qt 6 Dateiverweise (lokal oder qrc) anstelle von Inline-Shader-Code.

Die Eigenschaften „ vertexShader “ und „ fragmentShader “ sind in Qt 6 URLs und funktionieren sehr ähnlich wie beispielsweise „ Image.source “. Mit ShaderEffect werden jedoch nur die Schemata „ file “ und „ qrc “ unterstützt. Es ist auch möglich, das Schema „ file “ wegzulassen, wodurch sich auf bequeme Weise ein relativer Pfad angeben lässt. Ein solcher Pfad wird relativ zum Speicherort der Komponente (der „ .qml “-Datei) aufgelöst.

Shader-Eingaben und Ressourcen

Es gibt zwei Arten von Eingaben für den „ vertexShader “: Uniforms und Vertex-Eingaben.

Die folgenden Eingaben sind vordefiniert:

• vec4 qt_Vertex an Position 0 – Vertexposition; der obere linke Vertex hat die Position (0, 0), der untere rechte (width, height).
• vec2 qt_MultiTexCoord0 an Position 1 – Texturkoordinate; die Koordinate oben links ist (0, 0), die unten rechts (1, 1). Ist supportsAtlasTextures wahr, basieren die Koordinaten stattdessen auf der Position im Atlas.

Die folgenden Uniforms sind vordefiniert:

• mat4 qt_Matrix – kombinierte Transformationsmatrix, das Produkt aus den Matrizen vom Stammelement bis zu diesem ShaderEffect und einer orthogonalen Projektion.
• float qt_Opacity – kombinierte Deckkraft, das Produkt der Deckkraftwerte vom Stammelement bis zu diesem ShaderEffect.

Darüber hinaus kann jede Eigenschaft, die einem GLSL-Typ zugeordnet werden kann, den Shadern zur Verfügung gestellt werden. Die folgende Liste zeigt, wie Eigenschaften zugeordnet werden:

• bool, int, qreal -> bool, int, float – Wenn der Typ im Shader nicht mit dem in QML übereinstimmt, wird der Wert automatisch konvertiert.
• QColor -> vec4 – Wenn Farben an den Shader übergeben werden, werden sie zunächst vormultipliziert. So wird beispielsweise Qt.rgba(0,2; 0,6; 1,0; 0,5) im Shader zu vec4(0,1; 0,3; 0,5; 0,5).
• QRect, QRectF -> vec4 – Qt.rect(x, y, w, h) wird im Shader zu vec4(x, y, w, h).
• QPoint, QPointF, QSize, QSizeF -> vec2
• QVector3D -> vec3
• QVector4D -> vec4
• QTransform -> mat3
• QMatrix4x4 -> mat4
• QQuaternion -> vec4, der Skalarwert lautet w.
• Image -> sampler2D – Der Ursprung liegt in der oberen linken Ecke, und die Farbwerte sind vormultipliziert. Die Textur wird unverändert bereitgestellt, ohne den fillMode des Image-Elements. Um den fillMode einzubeziehen, verwenden Sie „ ShaderEffectSource “ oder „Image::layer::enabled“.
• ShaderEffectSource -> sampler2D – Der Ursprung liegt in der oberen linken Ecke, und die Farbwerte sind vormultipliziert.

Sampler werden im Shader-Code weiterhin als separate Uniform-Variablen deklariert. Die Shader können hierfür beliebige Bindungspunkte wählen, mit Ausnahme von ` 0 `, da dieser für den Uniform-Block reserviert ist.

Einige Shading-Sprachen und APIs kennen das Konzept separater Bild- und Sampler-Objekte. „ Qt Quick “ arbeitet in Shadern stets mit kombinierten Bild-Sampler-Objekten, wie sie von SPIR-V unterstützt werden. Daher sollten für „ShaderEffect“ bereitgestellte Shader stets Sampler-Deklarationen im Stil von „ layout(binding = 1) uniform sampler2D tex; “ verwenden. Die zugrunde liegende Abstraktionsschicht und die Shader-Pipeline sorgen dafür, dass dies für alle unterstützten APIs und Shading-Sprachen funktioniert – für die Anwendungen transparent.

Das QML-Szenengraph-Backend kann Texturen in Texturatlasen zuweisen. Wird eine in einem Atlas zugewiesene Textur an einen „ShaderEffect“ übergeben, wird sie standardmäßig aus dem Texturatlas in eine eigenständige Textur kopiert, sodass die Texturkoordinaten von 0 bis 1 reichen und die erwarteten Wrap-Modi erzielt werden. Dies erhöht jedoch den Speicherbedarf. Um das Kopieren der Textur zu vermeiden, setzen Sie bei einfachen Shadern, die `qt_MultiTexCoord0` verwenden, ` supportsAtlasTextures `, oder deklarieren Sie für jeden „uniform sampler2D <name>“ einen „uniform vec4 qt_SubRect_<name>“, dem das normalisierte Quellrechteck der Textur zugewiesen wird. Bei eigenständigen Texturen ist das Quellrechteck [0, 1]x[0, 1]. Bei Texturen in einem Atlas entspricht das Quellrechteck dem Teil des Texturatlas, in dem die Textur gespeichert ist. Die korrekte Berechnung der Texturkoordinate für eine Textur namens „source“ innerhalb eines Texturatlas lautet „qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0“.

Die Ausgabe von „ fragmentShader “ sollte vormultipliziert sein. Wenn „ blending “ aktiviert ist, wird „Source-Over“-Blending verwendet. Additives Blending lässt sich jedoch durch die Ausgabe von Null im Alphakanal erzielen.

import QtQuick 2.0

Rectangle {
    width: 200; height: 100
    Row {
        Image { id: img;
                sourceSize { width: 100; height: 100 } source: "qt-logo.png" }
        ShaderEffect {
            width: 100; height: 100
            property variant src: img
            vertexShader: "myeffect.vert.qsb"
            fragmentShader: "myeffect.frag.qsb"
        }
    }
}

Das Beispiel geht davon aus, dass „ myeffect.vert “ und „ myeffect.frag “ GLSL-Code im Vulkan-Stil enthalten, der vom Tool „ qsb “ verarbeitet wird, um die „ .qsb “-Dateien zu generieren.

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb, vec3(0.344, 0.5, 0.156))), tex.a) * qt_Opacity;
}

Nur ein Shader

Die Angabe von „ vertexShader “ und „ fragmentShader “ ist nicht zwingend erforderlich. In der Praxis werden viele ShaderEffect-Implementierungen nur einen Fragment-Shader bereitstellen wollen, während sie sich auf den standardmäßigen, integrierten Vertex-Shader verlassen.

Der Standard-Vertex-Shader übergibt die Texturkoordinate als „ vec2 qt_TexCoord0 “ an der Position „ 0 “ an den Fragment-Shader.

Der Standard-Fragment-Shader erwartet, dass die Texturkoordinate vom Vertex-Shader als „ vec2 qt_TexCoord0 “ an der Position „ 0 “ übergeben wird, und er nimmt eine Abtastung aus einem „sampler2D“ namens „ source “ am Bindungspunkt „ 1 “ vor.

ShaderEffect und Item-Ebenen

Der Typ „ShaderEffect“ kann mit „ layered items “ kombiniert werden.

Ebene mit deaktiviertem Effekt

Ebene mit aktiviertem Effekt

Item { id: layerRoot layer.enabled: true layer.effect: ShaderEffect { fragmentShader: "effect.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D source; void main() { vec4 p = texture(source, qt_TexCoord0); float g = dot(p.xyz, vec3(0.344, 0.5, 0.156)); fragColor = vec4(g, g, g, p.a) * qt_Opacity; }

Es ist auch möglich, mehrere überlagerte Elemente zu kombinieren:

Rectangle { id: gradientRect; width: 10 height: 10 gradient: Gradient { GradientStop { position: 0; color: "white" } GradientStop { position: 1; color: "steelblue" } } visible: false; // should not be visible on screen. layer.enabled: true; layer.smooth: true } Text { id: textItem font.pixelSize: 48 text: "Gradient Text" anchors.centerIn: parent layer.enabled: true // This item should be used as the 'mask' layer.samplerName: "maskSource" layer.effect: ShaderEffect { property var colorSource: gradientRect; fragmentShader: "mask.frag.qsb" } } #version 440 layout(location = 0) in vec2 qt_TexCoord0; layout(location = 0) out vec4 fragColor; layout(std140, binding = 0) uniform buf { mat4 qt_Matrix; float qt_Opacity; }; layout(binding = 1) uniform sampler2D colorSource; layout(binding = 2) uniform sampler2D maskSource; void main() { fragColor = texture(colorSource, qt_TexCoord0) * texture(maskSource, qt_TexCoord0).a * qt_Opacity; }

Weitere Hinweise

Standardmäßig besteht der „ShaderEffect“ aus vier Eckpunkten, einem für jede Ecke. Für nichtlineare Eckpunkttransformationen, wie z. B. „Page Curl“, können Sie ein feines Gitter aus Eckpunkten festlegen, indem Sie eine „ mesh “-Auflösung angeben.

Migration von Qt 5

Für Qt-5-Anwendungen mit ShaderEffect-Elementen umfasst die Migration zu Qt 6 Folgendes:

• das Verschieben des Shader-Codes in separate „ .vert “- und „ .frag “-Dateien,
• die Shader auf Vulkan-kompatibles GLSL zu aktualisieren,
• Ausführen des Tools „ qsb “ auf diesen Dateien,
• Einbinden der resultierenden „ .qsb “-Dateien in die ausführbare Datei mithilfe des Qt-Ressourcensystems,
• und die Datei in den Eigenschaften „ vertexShader “ und „ fragmentShader “ referenzieren.

Shader ToolsWie im Qt XML-ph-0000@deepl.internal-Modul beschrieben, lassen sich einige dieser Schritte automatisieren, indem CMake das Tool „ qsb “ während der Kompilierung aufruft. Weitere Informationen und Beispiele finden Sie unter qt_add_shaders().

Im Hinblick auf die Aktualisierung des Shader-Codes finden Sie im Folgenden eine Übersicht über die üblicherweise erforderlichen Änderungen.

attribute highp vec4 qt_Vertex;
attribute highp vec2 qt_MultiTexCoord0;
varying highp vec2 coord;
uniform highp mat4 qt_Matrix;
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

#version 440
layout(location = 0) in vec4 qt_Vertex;
layout(location = 1) in vec2 qt_MultiTexCoord0;
layout(location = 0) out vec2 coord;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
void main() {
    coord = qt_MultiTexCoord0;
    gl_Position = qt_Matrix * qt_Vertex;
}

Der Konvertierungsprozess umfasst hauptsächlich die Anpassung des Codes, um die Kompatibilität mit GL_KHR_vulkan_glsl herzustellen. Es ist zu beachten, dass „ Qt Quick “ eine Teilmenge der von GLSL und Vulkan bereitgestellten Funktionen nutzt, weshalb der Konvertierungsprozess für typische ShaderEffect-Shader in der Regel unkompliziert ist.

• Die Anweisung ` version ` sollte ` 440 ` oder ` 450` lauten, obwohl die Angabe anderer GLSL-Versionen ebenfalls funktionieren kann, da die Erweiterung `GL_KHR_vulkan_glsl ` für GLSL 140 und höher geschrieben wurde.
• Eingaben und Ausgaben müssen die modernen GLSL-Schlüsselwörter „ in “ und „ out “ verwenden. Darüber hinaus ist die Angabe eines Speicherorts erforderlich. Die Namensräume für Eingabe- und Ausgabestellen sind getrennt, daher ist die Zuweisung von Speicherorten beginnend bei 0 für beide sicher.
• Was die Eingaben des Vertex-Shaders betrifft, sind bei ShaderEffect die einzigen Möglichkeiten der Speicherort „ 0 “ für die Vertex-Position (traditionell als „ qt_Vertex “ bezeichnet) und der Speicherort „ 1 “ für Texturkoordinaten (traditionell als „ qt_MultiTexCoord0 “ bezeichnet).
• Die Vertex-Shader-Ausgänge und Fragment-Shader-Eingänge müssen im Shader-Code definiert werden. Der Fragment-Shader muss einen „ vec4 “-Ausgang an Position 0 haben (üblicherweise als „ fragColor “ bezeichnet). Um maximale Portabilität zu gewährleisten, sollten Vertex-Ausgänge und Fragment-Eingänge sowohl dieselbe Positionsnummer als auch denselben Namen verwenden. Wenn nur ein Fragment-Shader angegeben wird, werden die Texturkoordinaten vom integrierten Vertex-Shader als „ vec2 qt_TexCoord0 “ an der Position „ 0 “ übergeben, wie in den obigen Beispielausschnitten gezeigt.
• Uniform-Variablen außerhalb eines Uniform-Blocks sind nicht zulässig. Stattdessen müssen Uniform-Daten in einem Uniform-Block mit dem Bindungspunkt „ 0 “ deklariert werden.
• Der Uniform-Block sollte den Qualifizierer „std140“ verwenden.
• Zur Laufzeit erhalten der Vertex- und der Fragment-Shader denselben Uniform-Puffer, der an den Bindungspunkt 0 gebunden ist. Daher müssen die Deklarationen des Uniform-Blocks in der Regel in beiden Shadern identisch sein. Dies gilt auch für Elemente, die in einem der Shader nicht verwendet werden. Die Elementnamen müssen übereinstimmen, da bei einigen Grafik-APIs der Uniform-Block für die Anwendung transparent in ein traditionelles „struct uniform“ umgewandelt wird.
• Wenn Sie nur einen der Shader bereitstellen, beachten Sie bitte, dass die integrierten Shader am Anfang des Uniform-Blocks die Elemente „ qt_Matrix “ und „ qt_Opacity “ erwarten. (Genauer gesagt jeweils am Offset 0 und 64.) Als allgemeine Regel gilt: Fügen Sie diese immer als erstes und zweites Element in den Block ein.
• Im Beispiel gibt der Uniform-Block den Blocknamen ` buf` an. Dieser Name kann frei geändert werden, muss aber zwischen den Shadern übereinstimmen. Die Verwendung eines Instanznamens wie ` layout(...) uniform buf { ... } instance_name; ` ist optional. Wenn er angegeben wird, müssen alle Zugriffe auf die Elemente mit `instance_name` qualifiziert werden.

varying highp vec2 coord;
uniform lowp float qt_Opacity;
uniform sampler2D src;
void main() {
    lowp vec4 tex = texture2D(src, coord);
    gl_FragColor = vec4(vec3(dot(tex.rgb,
                        vec3(0.344, 0.5, 0.156))),
                             tex.a) * qt_Opacity;
}

#version 440
layout(location = 0) in vec2 coord;
layout(location = 0) out vec4 fragColor;
layout(std140, binding = 0) uniform buf {
    mat4 qt_Matrix;
    float qt_Opacity;
};
layout(binding = 1) uniform sampler2D src;
void main() {
    vec4 tex = texture(src, coord);
    fragColor = vec4(vec3(dot(tex.rgb,
                     vec3(0.344, 0.5, 0.156))),
                          tex.a) * qt_Opacity;
}

• Präzisionsqualifizierer (lowp, mediump, highp) werden derzeit nicht verwendet.
• Der Aufruf integrierter GLSL-Funktionen muss den modernen GLSL-Namen folgen, insbesondere „ texture() “ anstelle von „ texture2D() “.
• Sampler müssen Bindungspunkte verwenden, die bei 1 beginnen.
• Wenn „ Qt Quick “ bei aktiviertem „ multiview “ gerendert wird – z. B. weil es Teil einer 3D-Szenenwiedergabe in einer VR/AR-Umgebung ist, in der die Inhalte für das linke und rechte Auge in einem einzigen Durchgang erzeugt werden –, müssen die Shader des „ShaderEffect“ unter Berücksichtigung dieser Tatsache geschrieben werden. Bei einer Ansichtsanzahl von beispielsweise 2 gibt es „ 2 “-Matrizen (qt_Matrix ist ein Array von mat4 mit zwei Elementen). Vom Vertex-Shader wird erwartet, dass er „ gl_ViewIndex “ berücksichtigt. Allgemeine Informationen zum Erstellen von Shadern mit Multiview-Unterstützung finden Sie im Abschnitt „ Multiview “ im QSB-Handbuch.

Siehe auch „ Item Layers“ , das QSB-Handbuch und „qt_add_shaders“.

Dokumentation zu den Eigenschaften

blending : bool

Wenn diese Eigenschaft auf „true“ gesetzt ist, wird die Ausgabe des „ fragmentShader “ mithilfe des Mischmodus „Source-Over“ mit dem Hintergrund überblendet. Ist sie auf „false“ gesetzt, wird der Hintergrund ignoriert. Das Überblenden beeinträchtigt die Leistung, daher sollten Sie diese Eigenschaft auf „false“ setzen, wenn kein Überblenden erforderlich ist. Der Standardwert ist „true“.

cullMode : enumeration

Diese Eigenschaft legt fest, welche Seiten des Elements sichtbar sein sollen.

Die Standardeinstellung ist „NoCulling“.

fragmentShader : url

Diese Eigenschaft enthält einen Verweis auf eine Datei mit dem vorverarbeiteten Fragment-Shader-Paket, typischerweise mit der Erweiterung „ .qsb “. Der Wert wird ähnlich wie bei anderen QML-Typen, beispielsweise „Image“, als „ URL “ behandelt. Es muss sich entweder um eine lokale Datei handeln oder es muss das „qrc“-Schema verwendet werden, um auf Dateien zuzugreifen, die über das Qt-Ressourcensystem eingebettet sind. Die URL kann absolut oder relativ zur URL der Komponente sein.

Siehe auch „ vertexShader “.

log : string [read-only]

Diese Eigenschaft enthält ein Protokoll mit Warnungen und Fehlern aus dem letzten Versuch, die Shader zu kompilieren. Sie wird aktualisiert, sobald „ status “ auf „Compiled“ oder „Error“ gesetzt wird.

Siehe auch „ status “.

mesh : variant

Diese Eigenschaft definiert das Gitter, das zum Zeichnen des „ ShaderEffect “ verwendet wird. Sie kann jedes beliebige „ GridMesh “-Objekt enthalten. Wird dieser Eigenschaft ein Größenwert zugewiesen, verwendet der „ ShaderEffect “ implizit ein „ GridMesh “ mit dem Wert „ mesh resolution “. Standardmäßig hat diese Eigenschaft die Größe 1x1.

Siehe auch GridMesh.

status : enumeration [read-only]

Diese Eigenschaft gibt den aktuellen Status der Shader an.

Beim Festlegen des Quellcodes für den Fragment- oder Vertex-Shader wechselt der Status auf „Uncompiled“. Beim ersten Rendern des „ ShaderEffect “ mit neuem Shader-Quellcode werden die Shader kompiliert und verknüpft, und der Status wird auf „Compiled“ oder „Error“ aktualisiert.

Wenn keine Laufzeitkompilierung verwendet wird und die Shader-Eigenschaften auf Dateien mit Bytecode verweisen, lautet der Status immer „Kompiliert“. Der Inhalt des Shaders wird (abgesehen von einer grundlegenden Reflexion zur Ermittlung von Vertex-Eingabeelementen und Konstantenpufferdaten) erst später in der Rendering-Pipeline überprüft, sodass potenzielle Fehler (wie Layout- oder Root-Signatur-Nichtübereinstimmungen) erst zu einem späteren Zeitpunkt erkannt werden.

Siehe auch log.

supportsAtlasTextures : bool [since QtQuick 2.4]

Setzen Sie diese Eigenschaft auf „true“, um zu bestätigen, dass Ihr Shader-Code nicht davon ausgeht, dass qt_MultiTexCoord0 relativ zum Mesh im Bereich von (0,0) bis (1,1) liegt. In diesem Fall richtet sich der Wertebereich von `qt_MultiTexCoord0` stattdessen nach der Position der Textur innerhalb des Atlas. Diese Eigenschaft hat derzeit keine Auswirkung, wenn weniger oder mehr als ein Sampler-Uniform als Eingabe für Ihren Shader verwendet wird.

Dies unterscheidet sich von der Bereitstellung von „qt_SubRect_<name>“-Uniforms darin, dass Letztere das Zeichnen einer oder mehrerer Texturen aus dem Atlas in einem einzigen „ ShaderEffect “-Element ermöglichen, während „supportsAtlasTextures“ es erlaubt, mehrere Instanzen einer „ ShaderEffect “-Komponente, die unterschiedliche Quellbilder aus dem Atlas verwenden, in einem einzigen Zeichnungsvorgang zu bündeln. Beide verhindern, dass eine Textur aus dem Atlas kopiert wird, wenn sie von einem ` ShaderEffect` referenziert wird.

Der Standardwert ist „false“.

Diese Eigenschaft wurde in QtQuick 2.4 eingeführt.

vertexShader : url

Diese Eigenschaft enthält einen Verweis auf eine Datei mit dem vorverarbeiteten Vertex-Shader-Paket, typischerweise mit der Erweiterung „ .qsb “. Der Wert wird als „ URL “ behandelt, ähnlich wie bei anderen QML-Typen, beispielsweise „Image“. Es muss sich entweder um eine lokale Datei handeln oder das „qrc“-Schema verwendet werden, um auf Dateien zuzugreifen, die über das Qt-Ressourcensystem eingebettet sind. Die URL kann absolut oder relativ zur URL der Komponente sein.

Siehe auch „ fragmentShader “.