qt_add_shaders

Kompiliert Shader und fügt sie einer Qt-Ressource hinzu.

Der Befehl ist in der Komponente „ ShaderTools “ des Pakets „ Qt6 “ definiert, das mit folgendem Befehl geladen werden kann:

find_package(Qt6 REQUIRED COMPONENTS ShaderTools)

Syntax

qt_add_shaders(<target> <resource_name>
               PREFIX <path>
               FILES <file,...>
               [BASE <path>]
               [GLSL <version,...>]
               [NOGLSL]
               [HLSL <version,...>]
               [NOHLSL]
               [MSL <version,...>]
               [NOMSL]
               [BATCHABLE]
               [ZORDER_LOC <number>]
               [PERTARGETCOMPILE]
               [TESSELLATION]
               [TESSELLATION_VERTEX_COUNT <count>]
               [TESSELLATION_MODE <mode>]
               [VIEW_COUNT <count>]
               [MULTIVIEW]
               [PRECOMPILE]
               [OPTIMIZED]
               [DEBUGINFO]
               [QUIET]
               [DEFINES <name=value,...>]
               [OUTPUTS <file,...>]
               [ORIGINAL_FILES <file,...>]
               [OUTPUT_TARGETS <variable>]
               [MEDIUMP])

Wenn versionlose Befehle deaktiviert sind, verwenden Sie stattdessen „ qt6_add_shaders() “. Dieser Befehl unterstützt dieselben Argumente wie der vorliegende Befehl.

Beschreibung

Ruft das qsb-Tool zur Erstellungszeit für jede in ` FILES` aufgeführte Shader-Quelldatei auf und fügt die resultierenden ` .qsb `-Dateien unter dem durch ` PREFIX` angegebenen Ressourcenpräfix zum Qt-Ressourcensystem hinzu.

Die generierte Ressource erhält den Namen „ resource_name “, genau wie bei `qt_add_resources()`.

Standardmäßig ruft „ qt_add_shaders “ „ qsb “ wie folgt auf:

qsb --glsl "100 es,120,150" --hlsl 50 --msl 12 -o <output>.qsb <input>

Dadurch wird ein Paket erstellt, das SPIR-V (für Vulkan 1.0), GLSL ES 100 (für OpenGL ES 2.0 und neuer), GLSL 120 (für OpenGL mit Nicht-Core-Profil), GLSL 150 (für OpenGL mit Core-Profil), HLSL für Shader Model 5.0 (Direct3D 11.1) sowie Metal Shading Language 1.2 (Metal).

Bei WebAssembly ändern sich die Standardeinstellungen wie folgt:

qsb --glsl "100 es,300 es" -o <output>.qsb <input>

wodurch Shader generiert werden, die mit WebGL 1 und WebGL 2 kompatibel sind.

Die ursprünglichen Shader-Quelldateien werden nicht in die ausführbare Datei der Anwendung eingebettet und müssen nicht mitgeliefert werden. Build-Fehler des „ glslang “-Compilers werden zum Zeitpunkt des Builds gemeldet, und der Build schlägt fehl. Änderungen an Shader-Quelldateien werden beim nächsten Build automatisch übernommen, wie bei jeder anderen Quelldatei auch.

Shader-Typ

Der Shader-Typ wird aus der Dateiendung abgeleitet:

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

Optionen für die Zielsprache

• GLSL — Fordert GLSL-Quellcode für die angegebene, durch Kommas getrennte Liste von Versionen an. Beispielsweise benötigt ein Compute-Shader in der Regel "310 es,430" anstelle der Standardwerte. Das Leerzeichen vor dem Suffix „ es “ ist optional.
• NOGLSL — Deaktiviert die GLSL-Quellcode-Generierung. Geeignet für Anwendungen, die überhaupt nicht auf OpenGL abzielen.
• HLSL — Fordert HLSL-Quellcode für die angegebene Liste von Shader-Model-Versionen an. qsb verwendet die GLSL-Konvention: 50 entspricht Shader Model 5.0, 51 entspricht 5.1.
• NOHLSL — Deaktiviert die Generierung von HLSL-Quellcode. Geeignet für Anwendungen, die Direct 3D überhaupt nicht nutzen.
• MSL — Fordert den Metal Shading Language-Quellcode für die angegebene Version an. 12 entspricht MSL 1.2, 20 entspricht 2.0.
• NOMSL — Deaktiviert die Generierung von MSL-Quellcode. Geeignet für Anwendungen, die überhaupt nicht auf Metal ausgerichtet sind.

Beispiel – Anhebung der GLSL-Version für Shader, die OpenGL 3.x-Funktionen nutzen:

qt_add_shaders(exampleapp "res_gl3shaders"
    GLSL "300es,330"
    PREFIX
        "/shaders"
    FILES
        shaders/ssao.vert
        shaders/ssao.frag
        shaders/skybox.vert
        shaders/skybox.frag
)

Qt Quick Optionen

• BATCHABLE — Erforderlich für Vertex-Shader, die mit „ Qt Quick “ verwendet werden, entweder in einem „ ShaderEffect “ oder einem „ QSGMaterialShader “. Hat keine Auswirkungen auf Fragment- oder Compute-Shader; verschiedene Shader-Typen können problemlos in derselben „ FILES “-Liste gemischt werden, da das Schlüsselwort nur auf „ .vert “-Dateien angewendet wird. Entspricht dem Argument „ -b “ von „ qsb “.
• ZORDER_LOC — Wenn „ BATCHABLE “ angegeben ist, wird standardmäßig an der Position „ 7 “ ein zusätzlicher Vertex-Eingang eingefügt. Verwenden Sie dieses Schlüsselwort, um die Position zu ändern und Konflikte mit einem vorhandenen Eingang zu vermeiden.

Tessellationsoptionen

• TESSELLATION — Gibt an, dass die Shader zu einer Tessellations-Pipeline gehören. Dies ist nur für Vertex-Shader relevant, wenn die MSL-Generierung nicht deaktiviert ist; ermöglicht spezielle Verarbeitung und Übersetzung für diese Shader bei der Zielplattform Metal.

  Diese Option wurde in Qt 6.5 eingeführt.

• TESSELLATION_VERTEX_COUNT — Legt die Anzahl der Ausgangs-Vertexe aus der Tessellations-Steuerungsstufe fest. Obligatorisch für Tessellationsauswertungs-Shader, die auf Metal abzielen. Der Standardwert ist „ 3 “. Wenn der Wert nicht mit der Steuerungsstufe übereinstimmt, funktioniert der generierte MSL-Code nicht korrekt.

  Diese Option wurde in Qt 6.5 eingeführt.

• TESSELLATION_MODE — Legt den Tessellationsmodus fest: „ "triangles" “ (Standard) oder „ "quads" “. Muss gesetzt werden, wenn ein Tessellationssteuerungs-Shader unter „ FILES “ aufgeführt ist, und muss mit der Tessellationsauswertungsstufe übereinstimmen.

  Diese Option wurde in Qt 6.5 eingeführt.

Multiview-Optionen

• VIEW_COUNT — Legt die Anzahl der Ansichten für das Multiview-Rendering fest (GL_OVR_multiview2, VK_KHR_multiview, D3D12-View-Instancing usw.). Setzen Sie den Wert auf 2 oder höher, damit die entsprechenden Vertex-Shader korrekte GLSL-Ausgaben erzeugen. Die Einstellung „ VIEW_COUNT “ fügt die Präprozessor-Definition „ QSHADER_VIEW_COUNT “ ein und fügt bei Werten von 2 oder größer automatisch „ #extension GL_EXT_multiview : require “ in die Vertex-Shader ein. Mindestanforderungen an die Sprachversionen bei Verwendung von Multiview: GLSL 330 und 300 es, HLSL 61. Vermeiden Sie die Einstellung „ VIEW_COUNT “ bei Vertex-Shadern, die kein Multiview verwenden; gruppieren Sie diese stattdessen in separate „ qt_add_shaders() “-Aufrufe.

  Diese Option wurde in Qt 6.7 eingeführt.

• MULTIVIEW — Erzeugt sowohl einen Nicht-Multiview- als auch einen View-Count-2-Satz von Shadern. Dies ist eine bequeme Alternative zu zwei separaten „ qt_add_shaders() “-Aufrufen mit den entsprechenden GLSL/HLSL/MSL/VIEW_COUNT-Argumenten. Die impliziten Einstellungen für die Multiview-Varianten lauten GLSL 330,300es, HLSL 61, MSL 21 und VIEW_COUNT 2. Multiview-Varianten werden mit dem Suffix „ .mv2qsb “ gespeichert, das an den Dateinamen „ .qsb “ angehängt wird.

  Diese Option wurde in Qt 6.8 eingeführt.

Optionen für externe Tools

• PRECOMPILE — Unter Windows (sofern HLSL nicht deaktiviert ist) wird „ fxc “ aus dem Windows SDK aufgerufen, um HLSL-Quellcode bereits zur Erstellungszeit statt zur Laufzeit in DXBC-Bytecode zu kompilieren. Die resultierende Datei „ .qsb “ enthält den kompilierten Zwischen-Bytecode anstelle des ursprünglichen HLSL-Quellcodes. Entspricht dem Argument „ -c “ von „ qsb “. Hat auf Nicht-Windows-Plattformen keine Auswirkung.
• OPTIMIZED — Ruft „ spirv-opt “ aus dem Vulkan-SDK auf, um Optimierungen am SPIR-V-Bytecode durchzuführen. Entspricht dem Argument „ -O “ von „ qsb “.

Weitere Optionen

• BASE — Ein Pfadpräfix, das zur Berechnung des Alias (In-Resource-Namens) der generierten „ .qsb “-Dateien verwendet wird. Wenn „ BASE “ gesetzt ist, wird jeder Ausgabepfad relativ zu „ BASE “ gebildet, anstatt unverändert beibehalten zu werden. Dies entspricht dem Argument „ BASE “ von „qt_add_resources()“.
• DEFINES — Definiert Makros, die während der Shader-Kompilierung aktiv sind, in der Form „ "name1=value1;name2=value2" “. Alternativ können Einträge durch Zeilenumbrüche getrennt werden, genau wie bei „ FILES “. Entspricht dem Argument „ -D “ von „ qsb “.
• OUTPUTS — Wenn sich der generierte Dateiname „ .qsb “ vom Quelldateinamen unterscheiden muss (beispielsweise, wenn eine Shader-Datei als Quelle für mehrere „ .qsb “-Dateien dient, die durch „ DEFINES “ unterschieden werden), geben Sie pro Eintrag in „ FILES “ einen Ausgabedateinamen an. Jeder Name wird über das Argument „ -o “ an „ qsb “ übergeben, anstatt „ .qsb “ an den Quelldateinamen anzuhängen.
• ORIGINAL_FILES — Wenn die Dateien unter .qsb von anderen Shader-Quelldateien abhängen sollen als denen unter FILES, geben Sie hier einen Eintrag pro Element unter FILES an. Falls vorhanden, wird der entsprechende Eintrag aus ORIGINAL_FILES über --orig-file in die CMake-Abhängigkeitsdatei geschrieben und der Klausel DEPENDS der zugrunde liegenden Datei add_custom_command() hinzugefügt. Dies ist nützlich, wenn die an qt_add_shaders() übergebenen Dateien zwischengenerierte Assets sind und die endgültigen Dateien unter .qsb den ursprünglichen Quelldateien folgen sollen.
• PERTARGETCOMPILE — Kompiliert zu SPIR-V und übersetzt separat in jede Ausgabesprachversion, einmal pro Zielsprache. Dies ist langsamer als der standardmäßige Single-Pass-Ansatz, ermöglicht jedoch bedingte Kompilierung über die Präprozessor-Makros „ QSHADER_<LANG>[_VERSION] “. Entspricht dem Argument „ -p “ von „ qsb “.
• DEBUGINFO — Erzeugt vollständige Debug-Informationen für SPIR-V, wodurch Tools wie RenderDoc den vollständigen Quellcode anzeigen können, wenn eine Pipeline untersucht oder ein Vertex-/Fragment-Debugging durchgeführt wird. Wenn zusätzlich „ PRECOMPILE “ gesetzt ist, weist dies „ fxc “ an, Debug-Informationen in den generierten DXBC-Bytecode einzubetten. Entspricht dem Argument „ -g “ von „ qsb “.
• QUIET — Unterdrückt Debug- und Warnungsausgaben von „ qsb “. Es werden nur schwerwiegende Fehler ausgegeben. Entspricht dem Argument „ -s “ von „ qsb “.
• OUTPUT_TARGETS — Bei Verwendung von ` qt_add_shaders ` mit statischen Bibliotheken werden ein oder mehrere spezielle Ziele generiert. Übergeben Sie einen Variablennamen, um diese Ziele zur weiteren Verarbeitung abzurufen.
• MEDIUMP — Fordert in GLSL-ES-Fragment-Shadern standardmäßig Gleitkommazahlen mittlerer Genauigkeit an. Hat keine Auswirkungen auf andere Ziele, einschließlich Nicht-ES-GLSL.

Ersetzen von manuell erstellten Shadern

Die Liste „ FILES “ unterstützt eine spezielle Syntax zum Ersetzen einer bestimmten Shader-Variante im Paket „ .qsb “ durch eine manuell erstellte Datei. Dies entspricht der Option „ -r “ von „ qsb “:

FILES
    "shaders/externalsampler.frag@glsl,100es,shaders/externalsampler_gles.frag"

Auf einen Dateinamen können beliebig viele, durch „ @ “ getrennte Ersetzungsangaben folgen. Jede Angabe definiert die Shading-Sprache, die Version und die einzulesende Datei, getrennt durch Kommas. „ @ “-Zeichen innerhalb des Dateinamens oder Verzeichnispfads werden korrekt verarbeitet und haben keinen Einfluss auf die Analyse. Weitere Informationen finden Sie im QSB-Handbuch.

Beispiele

Grundlegende Verwendung

find_package(Qt6 COMPONENTS ShaderTools)

qt6_add_executable(exampleapp main.cpp)

qt6_add_shaders(exampleapp "exampleapp_shaders"
    PREFIX
        "/"
    FILES
        "wobble.frag"
)

Dadurch wird „ :/wobble.frag.qsb “ zur Laufzeit verfügbar gemacht. Die ursprüngliche „ wobble.frag “-Quelle ist nicht in der ausführbaren Datei enthalten.

Tessellation

Eine Grafikpipeline mit vier Stufen – Vertex (vertex.vert), Tessellationssteuerung (tess.tesc), Tessellationsauswertung (tess.tese) und Fragment (fragment.frag) – lässt sich wie folgt einrichten.

Zunächst werden die Vertex- und Fragment-Shader kompiliert. „ TESSELLATION “ aktiviert eine spezielle Metal-Übersetzung für den Vertex-Shader, und die GLSL-Version wird angehoben, da für die Tessellation OpenGL 4.x oder ES 3.2 erforderlich ist.

qt6_add_shaders(project "shaders_tessellation_part1"
    PREFIX
        "/shaders"
    GLSL
        "410,320es"
    TESSELLATION
    FILES
        "vertex.vert"
        "fragment.frag"
)

Die Tessellations-Shader werden in einem separaten Aufruf aufgeführt, da für sie „ NOHLSL “ erforderlich ist – HLSL-Tessellations-Shader müssen manuell geschrieben und eingefügt werden. Die Metal-Tessellationsparameter werden explizit angegeben.

qt6_add_shaders(project "shaders_tessellation_part2"
    PREFIX
        "/shaders"
    NOHLSL
    GLSL
        "410,320es"
    TESSELLATION_VERTEX_COUNT
        3
    TESSELLATION_MODE
        "triangles"
    FILES
        "tess.tesc@hlsl,50,tess_hull.hlsl"
        "tess.tese@hlsl,50,tess_domain.hlsl"
)