QCanvasCustomBrush Class

Ausführliche Beschreibung

QCanvasCustomBrush ist ein Strich-/Füllpinsel mit benutzerdefinierten Vertex- und/oder Fragment-Shadern.

Diese Shader sollten in GLSL im Vulkan-Stil geschrieben sein, ähnlich wie die Shader „ Qt Quick “ und „ ShaderEffect “. Sie müssen immer eine „ QC_INCLUDE “-Anweisung enthalten, entweder mit „ "customfrag.glsl" “ oder „ "customvert.glsl" “. Dadurch werden ein Uniform-Block, die Bild- und Schriftarttexturen sowie einige Hilfsfunktionen zur Verfügung gestellt.

iTime ist ein Beispiel für ein häufig verwendetes Element im integrierten Uniform-Block. Durch den Aufruf von ` setAnimationRunning()` mit ` true ` wird dieser Wert in jedem Frame automatisch aktualisiert und kann zur Steuerung animierter Inhalte verwendet werden.

Integrierte Shader-Eingaben, Uniforms und Hilfsfunktionen

Die Anweisung ` QC_INCLUDE ` ist keine Standard-Präprozessor-Direktive. Sie wird zur Erstellungszeit von `qt_add_custom_brush_shaders()` verarbeitet, bevor der Shader an die reguläre Shader-Kompilierungspipeline übergeben wird. Die Anweisung wird durch einen Block aus GLSL-Quellcode ersetzt, der die Shader-Eingänge und -Ausgänge, die Textur-Sampler, einen gemeinsamen Uniform-Block und – bei Fragment-Shadern – eine Reihe von Hilfsfunktionen deklariert. Verwenden Sie „ "customvert.glsl" “ in Vertex-Shadern und „ "customfrag.glsl" “ in Fragment-Shadern.

Das bedeutet, dass ein benutzerdefinierter Pinsel-Shader diese Eingaben, Ausgaben, Sampler oder Uniforms nicht selbst deklariert; sie werden alle durch die Anweisung „ QC_INCLUDE “ bereitgestellt.

Vertex-Shader-Schnittstelle

Ein Vertex-Shader, der „ "customvert.glsl" “ enthält, verfügt über die folgenden deklarierten Eingänge und Ausgänge:

• in vec2 vertex - Die Vertex-Position im Canvas-Koordinatensystem.
• in vec2 tcoord - Die dem Scheitelpunkt zugeordnete Texturkoordinate.
• out vec2 texCoord - Wird an den Fragment-Shader weitergeleitet. In der Regel auf „ tcoord “ gesetzt.
• out vec2 fragCoord - Wird an den Fragment-Shader weitergeleitet. Wird in der Regel auf ` vertex` gesetzt.

Darüber hinaus stehen die folgenden transformationsbezogenen Uniforms zur Verfügung:

• vec4 viewRect - Das Viewport-Rechteck als (x, y, Breite, Höhe).
• int ndcIsYDown - Ungleich Null, wenn die Y-Achse des normalisierten Gerätekordinatensystems nach unten zeigt, wie es bei einigen Grafik-APIs der Fall ist. Berücksichtigen Sie dies bei der Berechnung von ` gl_Position`.
• mat3 vertMatrix - Die aktuelle Transformationsmatrix.

Ein Vertex-Shader muss ` gl_Position` schreiben und soll ` texCoord ` sowie ` fragCoord ` an die Fragmentstufe weiterleiten.

Ein typischer Vertex-Shader sieht wie folgt aus:

#version 440

QC_INCLUDE "customvert.glsl"

void main()
{
    texCoord = tcoord;
    fragCoord = vertex;
    vec2 v = (vertMatrix * vec3(vertex, 1.0)).xy;
    if (ndcIsYDown != 0)
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           -1.0 + 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
    else
        gl_Position = vec4(2.0 * (v.x + viewRect.x) / viewRect.z - 1.0,
                           1.0 - 2.0 * (v.y + viewRect.y) / viewRect.w, 0.0, 1.0);
}

Fragment-Shader-Schnittstelle

Ein Fragment-Shader, der „ "customfrag.glsl" “ enthält, verfügt über die folgenden deklarierten Ein- und Ausgänge:

• in vec2 texCoord - Die interpolierte Texturkoordinate.
• in vec2 fragCoord - Die interpolierte Fragmentposition im selben Koordinatensystem wie die Geometrie. Wird häufig zur Steuerung prozeduraler Effekte verwendet.
• out vec4 fragColor - Die resultierende Fragmentfarbe, die der Shader schreiben muss. Die erwartete Ausgabe verwendet vorvervielfachtes Alpha.

Es stehen zwei Textur-Sampler zur Verfügung:

• sampler2D tex - Die Bildtextur.
• sampler2D fontTex - Die Schrifttextur, die ein vorzeichenbehaftetes Distanzfeld der Glyphen enthält. Dies ist relevant, wenn der Pinsel zum Ausfüllen von Text verwendet wird.

Die Komfortkonstanten ` TAU ` (entspricht 2 * pi) und ` SQRT2 ` sind ebenfalls definiert.

Gemeinsame Uniforms

Sowohl Vertex- als auch Fragment-Shader, die „ QC_INCLUDE “ verwenden, haben Zugriff auf einen gemeinsamen Uniform-Block. Die am häufigsten verwendeten Elemente sind:

• float iTime - Ein Zeitwert in Sekunden, der bei jedem Frame aktualisiert wird, solange isAnimationRunning() gleich true ist. Verwenden Sie ihn zur Steuerung von Animationen. Siehe setAnimationRunning().
• vec4 data1, ` vec4 data2`, ` vec4 data3`, ` vec4 data4 ` - Benutzerdefinierte Daten, die dem Shader zur Verfügung gestellt werden. Diese werden in C++ über ` setData1()`, ` setData2()`, ` setData3()` und ` setData4()` gesetzt.
• float globalAlpha - Die aktuelle globale Deckkraft des Painters. Fragment-Shader sollten normalerweise fragColor mit diesem Wert multiplizieren.
• vec4 colorEffects - Die Parameter des aktiven Farbeffekts. Werden normalerweise über `applyColorEffects()` angewendet und nicht direkt abgerufen.
• float fontAlphaMin, float fontAlphaMax – Die Schwellenwerte für das Signed-Distance-Field, die beim Antialiasing von Glyphen verwendet werden.

Hilfsfunktionen für Fragment-Shader

Die Fragment-Shader-Include-Datei stellt die folgenden Hilfsfunktionen bereit:

• float clipMask() - Gibt die Clip- (Scheren-)Abdeckung im Bereich [0, 1] für das aktuelle Fragment zurück. Multiplizieren Sie „ fragColor “ mit diesem Wert, um das Clipping des Painters zu berücksichtigen.
• float antialiasingAlpha() - Gibt die Antialiasing-Abdeckung im Bereich [0, 1] zurück, die aus ` texCoord` abgeleitet wird. Multiplizieren Sie ` fragColor ` mit diesem Wert, um antialiasierte Kanten zu erhalten.
• float sdfFontAlphaRaw() - Gibt den rohen, vorzeichenbehafteten Distance-Field-Wert zurück, der an der Position ` texCoord` aus ` fontTex ` abgetastet wurde, ohne Antialiasing. Wenden Sie ` smoothstep() ` bei Bedarf manuell an.
• float sdfFontAlpha() - Gibt den Glyphen-Alpha-Wert zurück, der von fontTex an der Position texCoord abgetastet wurde, wobei das standardmäßige Anti-Aliasing basierend auf fontAlphaMin und fontAlphaMax angewendet wird.
• void applyColorEffects(inout vec4 color) - Wendet die aktiven Kontrast-, Helligkeits- und Sättigungseffekte direkt auf color an.

Ein typischer Fragment-Shader berechnet fragColor, multipliziert diesen Wert mit globalAlpha, multipliziert ihn optional mit clipMask() und antialiasingAlpha(), um Clipping und Anti-Aliasing zu unterstützen, und ruft schließlich applyColorEffects() auf.

Wenn es um Text geht, sollte auch sdfFontAlpha() berücksichtigt werden. Zum Beispiel:

#version 440

QC_INCLUDE "customfrag.glsl"

void main()
{
    float a = 0.6 + 0.2 * sin(0.1 * fragCoord.x + 4.0 * iTime);
    vec4 color = vec4(a, a, a, 1.0);
    fragColor = sdfFontAlpha() * globalAlpha * color;
    applyColorEffects(fragColor);
}

Hinzufügen der Shader zum Projekt

Shader, die mit `QCanvasCustomBrush` verwendet werden, müssen immer über die CMake-Funktion `qt_add_custom_brush_shaders` – die vom Qt Canvas Painter-Paket bereitgestellt wird – zum Anwendungsprojekt hinzugefügt werden. Diese Funktion führt zur Build-Zeit eine zusätzliche Vorverarbeitung durch, bevor intern die Standardfunktion ` qt_add_shaders()` aufgerufen wird.

Beispiel:

qt_add_custom_brush_shaders(app "app_custombrush_shaders"
    PREFIX
        "/shaders"
    FILES
        brush1.frag
)

Verwendung des Pinsels

Zur Laufzeit kann die generierte Datei ` .qsb ` beispielsweise wie folgt verwendet werden:

QCanvasCustomBrush customBrush(":/shaders/brush1.frag.qsb"));
customBrush.setAnimationRunning(true); // iTime updates automatically
// expose custom data to the shader in data1
customBrush.setData1(QVector4D(1.0, 2.0, 3.0, 4.0));

Der `QCanvasCustomBrush` kann dann beispielsweise in einer Füllung verwendet werden:

painter->setFillStyle(customBrush);

Shader Tools Einzelheiten zur CMake-Funktion finden Sie unter `qt_add_custom_brush_shaders`, und Informationen zur Arbeit mit plattformübergreifendem Shader-Code in Qt finden Sie in der Dokumentation zum Qt XML-ph-0000@deepl.internal-Modul.