QShaderBaker Class

Dokumentation der Mitgliedsfunktionen

QShaderBaker::QShaderBaker()

Erstellt einen neuen QShaderBaker.

[noexcept] QShaderBaker::~QShaderBaker()

Destruktor.

QShader QShaderBaker::bake()

Führt den Kompilierungs- und Übersetzungsprozess durch.

Gibt eine ` QShader `-Instanz zurück. Um zu überprüfen, ob der Vorgang erfolgreich war, rufen Sie ` QShader::isValid()` auf. Wenn dabei „ false “ zurückgegeben wird, rufen Sie ` errorMessage()` auf, um das Protokoll abzurufen.

Dies ist ein rechenintensiver Vorgang. Beim Aufruf aus Anwendungen heraus kann es ratsam sein, dies in einem separaten Thread durchzuführen.

QString QShaderBaker::errorMessage() const

Gibt die Fehlermeldung des letzten Aufrufs von ` bake()` zurück oder eine leere Zeichenkette, wenn kein Fehler aufgetreten ist.

void QShaderBaker::setBatchableVertexShaderExtraInputLocation(int location)

Bei der Generierung einer „ QShader::BatchableVertexShader “-Variante legt „ location “ die Eingabeposition für den eingefügten Vertex-Input fest. Der Wert ist standardmäßig 7 und muss nur dann überschrieben werden, wenn der Vertex-Shader bereits die Eingabeposition 7 verwendet.

void QShaderBaker::setBreakOnShaderTranslationError(bool enable)

Steuert das Verhalten, wenn die Shader-Übersetzung (von SPIR-V nach GLSL/HLSL/MSL) fehlschlägt. Standardmäßig ist diese Einstellung auf „true“ gesetzt, was dazu führt, dass „ bake()“ einen Fehler zurückgibt, wenn ein angeforderter Shader nicht generiert werden kann. Wenn dies nicht gewünscht ist und stattdessen beabsichtigt wird, das zu generieren, was möglich ist, den Rest jedoch stillschweigend zu überspringen, setzen Sie „ enable “ auf „false“.

Die Ausrichtung auf mehrere GLSL-Versionen kann zu Fehlern führen, wenn eine Funktion nicht in eine bestimmte Version übersetzt werden kann. Der Versuch, beispielsweise einen Shader, der `textureSize()` verwendet, nach GLSL ES 100 zu übersetzen, würde den gesamten Aufruf von ` bake()` mit der Fehlermeldung „textureSize wird in ESSL 100 nicht unterstützt“ zum Scheitern bringen. Wenn es akzeptabel ist, keinen GLSL-ES-100-Shader im Ergebnis zu haben, obwohl dieser angefordert wurde, sorgt die Einstellung dieses Flags auf „false“ dafür, dass „ bake()“ erfolgreich ausgeführt wird.

void QShaderBaker::setGeneratedShaderVariants(const QList<QShader::Variant> &v)

Legt fest, welche Shader-Varianten generiert werden. Jede Shader-Version kann mehrere Varianten in der resultierenden Datei „ QShader “ haben.

In den meisten Fällen enthält die Datei „ v “ einen einzigen Eintrag: „ QShader::StandardShader “.

void QShaderBaker::setGeneratedShaders(const QList<QShaderBaker::GeneratedShader> &v)

Legt fest, welche Art von Shadern kompiliert oder übersetzt werden sollen. Standardmäßig wird nichts generiert, daher ist der Aufruf dieser Funktion vor bake() zwingend erforderlich

Das minimal mögliche Baking-Ziel ist beispielsweise SPIR-V, ohne zusätzliche Übersetzungen in andere Sprachen. Um dies anzufordern, gehen Sie wie folgt vor:

baker.setGeneratedShaders({ QShader::SpirvShader, QShaderVersion(100) });

[since 6.9] void QShaderBaker::setGlslOptions(QShaderBaker::GlslOptions options)

Legt zusätzliche „ options “ für die generierten GLSL- und GLSL ES-Quelldateien fest. Standardmäßig sind keine Flags gesetzt.

Diese Funktion wurde in Qt 6.9 eingeführt.

[since 6.7] void QShaderBaker::setMultiViewCount(int count)

Beim Transpiling von Shadern unter Verwendung von Multiview (z. B. einem Vertex-Shader, der `gl_ViewIndex` für einen Renderer verwendet, der auf `GL_OVR_multiview2`, `VK_KHR_multiview` usw. basiert) ist es bei einigen Zielplattformen erforderlich, die Anzahl der Ansichten im Shader anzugeben. Dies geschieht im GLSL-Code im Vulkan-Stil nicht und ist für Ziele wie SPIR-V oder HLSL nicht relevant, wird jedoch für OpenGL und GLSL benötigt, weshalb der Wert als zusätzliche Metadaten angegeben werden muss.

Standardmäßig ist der Wert 0, wodurch das Einfügen der Anweisung „ num_views “ deaktiviert wird. Die Einstellung 1 ist nicht sinnvoll, da dies ohnehin der Standardwert für „ num_views “ ist. Daher sollte „ count “ ≥ 2 sein, um eine Wirkung zu erzielen. Bei einer Einstellung von beispielsweise 2 enthält der generierte GLSL-Shader eine „ layout(num_views = 2) in; “-Anweisung.

Die Einstellung von „ count “ auf 2 oder höher fügt zudem einige Präprozessor-Anweisungen ein: „ QSHADER_VIEW_COUNT “ wird auf „ count “ gesetzt, während die Erweiterung „ GL_EXT_multiview “ automatisch aktiviert wird. Daher kann die Einstellung des entsprechenden „ count “ auch bei anderen Shader-Typen relevant sein, z. B. wenn ein Uniform-Puffer zwischen dem Vertex- und dem Fragment-Shader gemeinsam genutzt wird und beide Shader in der Lage sein müssen, etwas wie „ #if QSHADER_VIEW_COUNT >= 2 “ zu schreiben.

Diese Funktion wurde in Qt 6.7 eingeführt.

void QShaderBaker::setPerTargetCompilation(bool enable)

Legt die Kompilierung pro Ziel auf „ enable “ fest. Standardmäßig ist diese Option deaktiviert, was bedeutet, dass der Vulkan/GLSL-Quellcode einmal pro Variante zu SPIR-V kompiliert wird. (Also standardmäßig einmal, zweimal, wenn es sich um einen Vertex-Shader handelt und zusätzlich die Variante „Batchable“ wie gewünscht ausgewählt wurde). Das resultierende SPIR-V wird anschließend in die verschiedenen Zielsprachen (GLSL, HLSL, MSL) übersetzt.

Im Ziel-spezifischen Kompilierungsmodus gibt es für jedes Ziel einen separaten Kompilierungsschritt von GLSL nach SPIR-V, d. h. für jede über ` setGeneratedShaders()` angeforderte GLSL-/HLSL-/MSL-Version. Die Eingabequelle ist dieselbe, jedoch werden zielspezifische Präprozessor-Definitionen eingefügt. Dies ist deutlich zeitaufwändiger, ermöglicht es Anwendungen jedoch, einen einzigen Shader bereitzustellen und mithilfe von „ #ifdef “-Blöcken zu differenzieren. Ist dieser Modus deaktiviert, besteht die einzige Möglichkeit, dasselbe zu erreichen, darin, mehrere Versionen der Shader-Datei bereitzustellen, jede separat zu verarbeiten, {.qsb}-Dateien für jede Version auszuliefern und die richtige Datei anhand der Laufzeitlogik auszuwählen.

Die folgenden Makros werden in diesem Modus automatisch definiert. Beachten Sie, dass die Makros immer an Shading-Sprachen gebunden sind, nicht an Grafik-APIs.

• QSHADER_SPIRV - wird definiert, wenn SPIR-V als Ziel gewählt wird (typischerweise zur Verwendung durch Vulkan).
• QSHADER_SPIRV_VERSION - Die Nummer der angestrebten SPIR-V-Version, z. B. „ 100 “.
• QSHADER_GLSL - wird definiert, wenn GLSL oder GLSL ES als Ziel festgelegt ist (in der Regel zur Verwendung durch OpenGL oder OpenGL ES)
• QSHADER_GLSL_VERSION - Die Zielversionsnummer für GLSL oder GLSL ES, z. B. 100, 300 oder 330.
• QSHADER_GLSL_ES - Wird nur definiert, wenn GLSL ES als Zielsprache gewählt wird
• QSHADER_HLSL - wird definiert, wenn HLSL als Zielsprache gewählt wird (wird in der Regel von Direct 3D verwendet)
• QSHADER_HLSL_VERSION - die angestrebte HLSL-Shader-Modell-Version, z. B. 50
• QSHADER_MSL - definiert, wenn die Metal Shading Language als Zielsprache gewählt wird (wird in der Regel von Metal verwendet)
• QSHADER_MSL_VERSION - die angestrebte MSL-Version, z. B. 12 oder 20.

Dies ermöglicht das Schreiben von Shader-Code wie dem folgenden.

#if QSHADER_HLSL || QSHADER_MSL
vec2 uv = vec2(uv_coord.x, 1.0 - uv_coord.y);
#else
vec2 uv = uv_coord;
#endif

void QShaderBaker::setPreamble(const QByteArray &preamble)

Legt eine benutzerdefinierte „ preamble “ fest, die vor dem normalen Shader-Code verarbeitet wird.

Dies ist mehr als nur das Voranstellen an die Quellzeichenfolge: Die Gültigkeit der GLSL-Versionsanweisung, die vor allem anderen stehen muss, wird dadurch nicht beeinträchtigt. Auch die Zeilennummern in den ausgegebenen Fehlermeldungen bleiben unverändert, wobei der Inhalt des „ preamble “ ignoriert wird.

Ein Anwendungsfall für Präambeln ist das transparente Einfügen dynamisch generierter „ #define “-Anweisungen.

void QShaderBaker::setSourceDevice(QIODevice *device, QShader::Stage stage, const QString &fileName = QString())

Legt die Quell device fest. Dadurch können beliebige QIODevice anstelle von reinen Dateien verwendet werden. stage gibt die Shader-Stufe an, während der optionale Parameter fileName einen Dateinamen enthält, der in den Fehlermeldungen verwendet wird.

void QShaderBaker::setSourceFileName(const QString &fileName)

Legt den Namen der Shader-Quelldatei auf „ fileName “ fest. Diese Datei wird beim Aufruf von ` bake()` eingelesen. Die Shader-Stufe wird automatisch aus der Dateiendung abgeleitet. Wenn dies nicht gewünscht oder nicht möglich ist, verwenden Sie stattdessen die Überladung mit dem Argument „stage“.

Die unterstützten Dateiendungen sind:

• .vert - Vertex-Shader
• .frag - Fragment- (Pixel-)Shader
• .tesc - Tessellationssteuerungs- (Hull-)Shader
• .tese - Tessellationsauswertungs- (Domain-)Shader
• .geom - Geometrie-Shader
• .comp - Compute-Shader

void QShaderBaker::setSourceFileName(const QString &fileName, QShader::Stage stage)

Legt den Namen der Shader-Quelldatei auf „ fileName “ fest. Diese Datei wird beim Aufruf von „ bake()“ eingelesen. Die Shader-Stufe wird durch „ stage “ festgelegt.

void QShaderBaker::setSourceString(const QByteArray &sourceString, QShader::Stage stage, const QString &fileName = QString())

Legt den Eingabe-Shader „ sourceString “ fest. „ stage “ gibt die Shader-Stufe an, während das optionale „ fileName “ einen Dateinamen enthält, der in den Fehlermeldungen verwendet wird.

void QShaderBaker::setSpirvOptions(QShaderBaker::SpirvOptions options)

Legt zusätzliche „ options “ für die generierte SPIR-V-Binärdatei fest. Standardmäßig sind keine Flags gesetzt.

void QShaderBaker::setTessellationMode(QShaderDescription::TessellationMode mode)

Bei der Generierung von MSL-Shader-Code für einen Tessellationssteuerungs-Shader muss die Tessellations mode e (Dreiecke oder Vierecke) im Voraus bekannt sein. In GLSL wird dies in der Regel im Tessellationsauswertungs-Shader deklariert, bei Metal muss sie jedoch bereits bei der Generierung des Compute-Shaders aus dem Tessellationssteuerungs-Shader bekannt sein.

Ist dieser Wert nicht festgelegt, gilt als Standard „Dreiecke“.

void QShaderBaker::setTessellationOutputVertexCount(int count)

Bei der Generierung von MSL-Shader-Code für einen Tessellationsauswertungs-Shader muss die Ausgangs-Vertex- count des Tessellationssteuerungs-Shaders im Voraus bekannt sein. In GLSL würde diese typischerweise im Tessellationssteuerungs-Shader deklariert werden, bei Metal muss sie jedoch bereits bei der Generierung des Vertex-Shaders aus dem Tessellationsauswertungs-Shader bekannt sein.

Ist dieser Wert nicht festgelegt, beträgt der Standardwert 3.