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

Detaillierte Beschreibung

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

Shader

In Qt 5 wurden Effekte in Form von GLSL (OpenGL Shading Language) Quellcode zur Verfügung gestellt, oft eingebettet als Strings in QML. Ab Qt 5.8 wurde es auch möglich, auf Dateien zu verweisen, entweder lokal oder im Qt-Ressourcensystem.

In Qt 6 hat Qt Quick auch Unterstützung für Grafik-APIs wie Vulkan, Metal und Direct3D 11. Daher ist die Arbeit mit GLSL-Quelltexten nicht mehr möglich. Stattdessen basiert die neue Shader-Pipeline auf der Kompilierung von Vulkan-kompatiblem GLSL-Code in SPIR-V, gefolgt von der Erfassung von Reflexionsinformationen und der Übersetzung in andere Shading-Sprachen wie HLSL, die Metal Shading Language und verschiedene GLSL-Versionen. Die daraus resultierenden Assets werden in ein einziges Paket gepackt, das in der Regel in Dateien mit der Erweiterung .qsb gespeichert wird. Dieser Prozess wird offline oder spätestens bei der Erstellung der Anwendung durchgeführt. Zur Laufzeit verbrauchen der Szenegraph und die zugrunde liegende Grafikabstraktion diese .qsb Dateien. Daher erwartet ShaderEffect in Qt 6 Dateireferenzen (lokal oder qrc) anstelle von Inline-Shader-Code.

Die Eigenschaften vertexShader und fragmentShader sind URLs in Qt 6 und funktionieren sehr ähnlich wie z.B. Image.source. Es werden jedoch nur die Schemata file und qrc von ShaderEffect unterstützt. Es ist auch möglich, das file Schema wegzulassen, was es erlaubt, einen relativen Pfad auf bequeme Art und Weise anzugeben. 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: Uniformen und Vertex-Eingaben.

Die folgenden Eingaben sind vordefiniert:

• vec4 qt_Vertex mit der Position 0 - vertex position, der obere linke vertex hat die Position (0, 0), der untere rechte (width, height).
• vec2 qt_MultiTexCoord0 mit der Position 1 - Texturkoordinate, die obere linke Koordinate ist (0, 0), die untere rechte (1, 1). Wenn supportsAtlasTextures wahr ist, werden die Koordinaten stattdessen auf der Position im Atlas basieren.

Die folgenden Uniformen sind vordefiniert:

• mat4 qt_Matrix - kombinierte Transformationsmatrix, das Produkt der Matrizen aus dem Root-Element zu diesem ShaderEffect und einer orthogonalen Projektion.
• float qt_Opacity - kombinierte Opazität, das Produkt der Opazitäten vom Stammelement bis zu diesem ShaderEffect.

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

• bool, int, qreal -> bool, int, float - Wenn der Typ im Shader nicht derselbe ist wie in QML, wird der Wert automatisch konvertiert.
• QColor -> vec4 - Wenn Farben an den Shader übergeben werden, werden sie zunächst vormultipliziert. So wird zum Beispiel 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 -> matte4
• QQuaternion -> vec4, Skalarwert ist w.
• Image -> sampler2D - Der Ursprung liegt in der linken oberen Ecke, und die Farbwerte werden vormultipliziert. Die Textur wird ohne den fillMode des Elements Image bereitgestellt. Um fillMode einzuschließen, verwenden Sie ShaderEffectSource oder Image::layer::enabled.
• ShaderEffectSource -> sampler2D - Der Ursprung liegt in der linken oberen Ecke, und die Farbwerte werden vormultipliziert.

Sampler werden nach wie vor als separate einheitliche Variablen im Shader-Code deklariert. Den Shadern steht es frei, einen beliebigen Bindungspunkt für diese zu wählen, mit Ausnahme von 0, da dieser für den Uniform-Block reserviert ist.

Einige Shading-Sprachen und APIs haben ein Konzept von getrennten Bild- und Sampler-Objekten. Qt Quick arbeitet immer mit kombinierten Bild-Sampler-Objekten in Shadern, wie von SPIR-V unterstützt. Daher sollten Shader, die für ShaderEffect geliefert werden, immer 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 transparent für die Anwendungen funktioniert.

Das QML-Szenengraph-Backend kann sich dafür entscheiden, Texturen in Texturatlanten zuzuweisen. Wenn eine in einem Atlas zugewiesene Textur an einen ShaderEffekt übergeben wird, wird sie standardmäßig aus dem Texturatlas in eine eigenständige Textur kopiert, so dass die Texturkoordinaten von 0 bis 1 reichen, und man erhält die erwarteten Wrap-Modi. Dies erhöht jedoch den Speicherverbrauch. Um die Texturkopie zu vermeiden, setzen Sie supportsAtlasTextures für einfache Shader mit qt_MultiTexCoord0, oder deklarieren Sie für jedes "uniform sampler2D <name>" ein "uniform vec4 qt_SubRect_<name>", dem das normalisierte Quellrechteck der Textur zugewiesen wird. Für eigenständige Texturen ist das Quellrechteck [0, 1]x[0, 1]. Bei Texturen in einem Atlas entspricht das Quellrechteck dem Teil des Texturatlasses, in dem die Textur gespeichert ist. Der korrekte Weg zur Berechnung der Texturkoordinate für eine Textur namens "source" innerhalb eines Texturatlasses ist "qt_SubRect_source.xy + qt_SubRect_source.zw * qt_MultiTexCoord0".

Die Ausgabe von fragmentShader sollte vormultipliziert werden. Wenn blending aktiviert ist, wird source-over blending verwendet. Additives Blending kann jedoch durch Ausgabe von Null im Alphakanal erreicht werden.

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 Dateien .qsb zu erzeugen.

#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 einen Shader haben

Die Angabe von sowohl vertexShader als auch fragmentShader ist nicht zwingend erforderlich. Viele ShaderEffect-Implementierungen werden in der Praxis nur einen Fragment-Shader bereitstellen wollen, während sie sich auf den standardmäßigen, eingebauten Vertex-Shader verlassen.

Der standardmäßige Vertex-Shader gibt die Texturkoordinate an den Fragment-Shader als vec2 qt_TexCoord0 an der Stelle 0 weiter.

Der Standard-Fragment-Shader erwartet, dass die Texturkoordinate vom Vertex-Shader als vec2 qt_TexCoord0 an der Position 0 übergeben wird, und er sampelt von einem Sampler2D namens source am Bindungspunkt 1.

ShaderEffect und Element-Ebenen

Der ShaderEffect-Typ 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 Elemente mit Ebenen 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; }

Sonstige Hinweise

Standardmäßig besteht der ShaderEffect aus vier Scheitelpunkten, einem für jede Ecke. Für nicht-lineare Scheitelpunkttransformationen, wie z.B. Page Curl, können Sie ein feines Raster von Scheitelpunkten angeben, indem Sie eine mesh Auflösung angeben.

Umstellung von Qt 5

Für Qt 5 Anwendungen mit ShaderEffect Elementen beinhaltet die Migration zu Qt 6:

• Verschieben des Shader-Codes in separate Dateien .vert und .frag,
• das Aktualisieren der Shader auf Vulkan-kompatibles GLSL,
• das Ausführen des qsb -Tools für diese Dateien,
• Einbindung der resultierenden .qsb Dateien in die ausführbare Datei mit dem Qt-Ressourcensystem,
• und die Datei in den Eigenschaften vertexShader und fragmentShader referenzieren.

Wie im Qt Shader Tools Modul beschrieben, können einige dieser Schritte automatisiert werden, indem CMake das qsb Tool zur Build-Zeit aufruft. Siehe Qt Shader Tools Build System Integration für weitere Informationen und Beispiele.

Wenn es um die Aktualisierung des Shader-Codes geht, finden Sie unten einen Überblick ü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 beinhaltet hauptsächlich die Aktualisierung des Codes, um mit GL_KHR_vulkan_glsl kompatibel zu sein. Es ist erwähnenswert, dass Qt Quick eine Teilmenge der von GLSL und Vulkan bereitgestellten Funktionen verwendet, und daher ist der Konvertierungsprozess für typische ShaderEffect-Shader in der Regel unkompliziert.

• Die version Direktive sollte 440 oder 450 angeben, obwohl die Angabe einer anderen GLSL Version auch funktionieren kann, da die GL_KHR_vulkan_glsl Erweiterung für GLSL 140 und höher geschrieben ist.
• Ein- 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 Ausgabespeicher sind getrennt, daher ist die Zuweisung von Speicherplätzen beginnend bei 0 für beide sicher.
• Bei Vertex-Shader-Eingaben sind die einzigen Möglichkeiten mit ShaderEffect die Position 0 für die Vertex-Position (traditionell qt_Vertex genannt) und die Position 1 für die Texturkoordinaten (traditionell qt_MultiTexCoord0 genannt).
• Die Ausgaben des Vertex-Shaders und die Eingaben des Fragment-Shaders müssen vom Shader-Code definiert werden. Der Fragment-Shader muss einen vec4 -Ausgang an Position 0 haben (üblicherweise fragColor genannt). Um eine maximale Portabilität zu erreichen, sollten Vertex-Ausgänge und Fragment-Eingänge die gleiche Speicherplatznummer und den gleichen Namen verwenden. Wenn nur ein Fragment-Shader angegeben wird, werden die Texturkoordinaten vom eingebauten Vertex-Shader als vec2 qt_TexCoord0 an der Position 0 übergeben, wie in den obigen Beispielen gezeigt.
• Uniform-Variablen außerhalb eines Uniform-Blocks sind nicht zulässig. Vielmehr müssen einheitliche Daten in einem einheitlichen Block mit dem Bindungspunkt 0 deklariert werden.
• Es wird erwartet, dass der Uniform-Block den Qualifier std140 verwendet.
• Zur Laufzeit erhalten der Vertex- und der Fragment-Shader denselben Uniform-Buffer, der an den Bindepunkt 0 gebunden ist. Daher müssen die Uniform-Block-Deklarationen der Shader in der Regel identisch sein. Dies gilt auch für Mitglieder, die in einem der Shader nicht verwendet werden. Die Membernamen müssen übereinstimmen, da bei einigen Grafik-APIs der Uniform-Block für die Anwendung transparent in eine herkömmliche struct uniform umgewandelt wird.
• Wenn Sie nur einen der Shader bereitstellen, achten Sie darauf, dass die eingebauten Shader qt_Matrix und qt_Opacity am Anfang des Uniform-Blocks erwarten. (genauer gesagt, an Offset 0 bzw. 64). Als allgemeine Regel sollten Sie diese immer als erstes und zweites Mitglied in den Block aufnehmen.
• In diesem Beispiel gibt der einheitliche Block den Blocknamen buf an. Dieser Name kann frei geändert werden, muss aber zwischen den Shadern übereinstimmen. Die Verwendung eines Instanznamens, wie z. B. layout(...) uniform buf { ... } instance_name;, ist optional. Wenn er angegeben wird, müssen alle Zugriffe auf die Member 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 von eingebauten GLSL-Funktionen muss den modernen GLSL-Namen folgen, vor allem texture() anstelle von texture2D().
• Sampler müssen Bindungspunkte verwenden, die bei 1 beginnen.
• Wenn Qt Quick mit multiview gerendert wird, z. B. weil es Teil einer 3D-Szene ist, die in einer VR/AR-Umgebung gerendert wird, in der die Inhalte für das linke und das rechte Auge in einem einzigen Durchgang generiert werden, müssen die ShaderEffects-Shader unter Berücksichtigung dieser Tatsache geschrieben werden. Bei einer View-Count von z.B. 2 wird es 2 Matrizen geben (qt_Matrix ist ein Array von mat4 mit zwei Elementen). Es wird erwartet, dass der Vertex-Shader gl_ViewIndex in Betracht zieht. Siehe den Abschnitt Multiview im QSB-Handbuch für allgemeine Informationen zur Erstellung von multiview-fähigen Shadern.

Siehe auch Item Layers, QSB Manual, und Qt Shader Tools Build System Integration.

Eigenschaft Dokumentation