qt_add_shaders

シェーダーをコンパイルし、Qtリソースに追加します。

このコマンドは、Qt6 パッケージのShaderTools コンポーネントで定義されており、次のようにロードできます：

find_package(Qt6 REQUIRED COMPONENTS ShaderTools)

概要

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])

バージョン指定なしのコマンドが無効になっている場合は、代わりに `qt6_add_shaders() ` を使用してください。このコマンドと同じ引数セットをサポートしています。

説明

ビルド時に、FILES にリストされている各シェーダーソースファイルに対してqsbツールを呼び出し、その結果として生成された.qsb ファイルを、PREFIX で指定されたリソースプレフィックスの下に Qt リソースシステムに追加します。

生成されるリソースの名前は、qt_add_resources() と同様にresource_name となります。

デフォルトでは、qt_add_shaders は次のようにqsb を呼び出します。

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

これにより、SPIR-V（Vulkan 1.0用）、GLSL ES 100（OpenGL ES 2.0以降用）、GLSL 120（非コアプロファイルOpenGL用）、GLSL 150（コアプロファイルOpenGL用）、 シェーダーモデル 5.0（Direct3D 11.1）用の HLSL、および Metal シェーディング言語 1.2（Metal）を含むパッケージが生成されます。

WebAssemblyでは、デフォルト設定が次のように変更されます：

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

これにより、WebGL 1 および WebGL 2 と互換性のあるシェーダーが生成されます。

元のシェーダーソースファイルはアプリケーションの実行ファイルに埋め込まれず、同梱する必要もありません。glslang コンパイラによるビルドエラーはビルド時に報告され、ビルドは失敗します。シェーダーソースファイルへの変更は、他のソースファイルと同様に、次回のビルドで自動的に反映されます。

シェーダーの種類

シェーダーのタイプはファイル拡張子から判別されます：

• .vert — 頂点シェーダー
• .tesc — テッセレーション制御シェーダー
• .tese — テッセレーション評価シェーダー
• .geom — ジオメトリシェーダー
• .frag — フラグメント（ピクセル）シェーダー
• .comp — コンピュートシェーダー

ターゲット言語オプション

• GLSL — カンマ区切りのバージョンリストに対して GLSL ソースを生成します。たとえば、コンピュートシェーダーでは通常、デフォルト設定ではなく"310 es,430" が必要です。es という接尾辞の前のスペースは省略可能です。
• NOGLSL — GLSLソースの生成を無効にします。OpenGLをまったくターゲットとしていないアプリケーションに適しています。
• HLSL — 指定されたシェーダーモデルバージョンのリストに対する HLSL ソースを要求します。qsb では GLSL 形式の番号付けが使用されます。つまり、50 はシェーダーモデル 5.0、51 は 5.1 となります。
• NOHLSL — HLSLソースの生成を無効にします。Direct 3Dをまったく対象としていないアプリケーションに適しています。
• MSL — 指定されたバージョンの Metal Shading Language ソースを要求します。12 は MSL 1.2 に、20 は 2.0 に対応します。
• NOMSL — MSLソースの生成を無効にします。Metalをまったくターゲットとしていないアプリケーションに適しています。

例 — OpenGL 3.x の機能を使用するシェーダーの GLSL バージョンを上げる場合：

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 オプション

• BATCHABLE — `Qt Quick` と共に使用される頂点シェーダー（`ShaderEffect ` または `QSGMaterialShader` 内）で必須です。フラグメントシェーダーやコンピュートシェーダーには影響しません。このキーワードは `.vert ` ファイルにのみ適用されるため、異なる種類のシェーダーを同じ `FILES ` リスト内で安全に混在させることができます。これは、qsb の `-b ` 引数と同等です。
• ZORDER_LOC — `BATCHABLE ` が指定された場合、デフォルトでは位置 `7 ` に追加の頂点入力が挿入されます。既存の入力を妨げないよう、このキーワードを使用して位置を変更してください。

テッセレーションオプション

• TESSELLATION — シェーダーがテッセレーションパイプラインに属することを示します。MSL生成が無効化されていない場合、頂点シェーダーにのみ適用されます。Metalをターゲットとする場合、これらのシェーダーに対して特別な処理と変換を有効にします。

  このオプションは Qt 6.5 で導入されました。

• TESSELLATION_VERTEX_COUNT — テッセレーション制御ステージからの出力頂点数を指定します。Metal をターゲットとするテッセレーション評価シェーダーでは必須です。デフォルトは `3` です。この値が制御ステージと一致しない場合、生成された MSL コードは正しく機能しません。

  このオプションは Qt 6.5 で導入されました。

• TESSELLATION_MODE — テッセレーションモードを指定します:"triangles" （デフォルト）または"quads" です。FILES にテッセレーション制御シェーダーがリストされている場合は、このオプションを設定する必要があり、かつテッセレーション評価ステージと一致している必要があります。

  このオプションは Qt 6.5 で導入されました。

マルチビューオプション

• VIEW_COUNT — マルチビューレンダリング（GL_OVR_multiview2、VK_KHR_multiview、D3D12 ビューインスタンス化など）のビュー数を指定します。関連する頂点シェーダーが正しい GLSL 出力を生成するには、2 以上の値に設定してください。VIEW_COUNT に設定すると、プリプロセッサ定義QSHADER_VIEW_COUNT が挿入され、値が2以上の場合は、頂点シェーダーに#extension GL_EXT_multiview : require が自動的に追加されます。マルチビューを使用する際に必要な最低言語バージョンは、GLSL 330および300 es、HLSL 61です。マルチビューを使用しない頂点シェーダーでは、VIEW_COUNT の設定を避け、代わりにそれらを個別のqt_add_shaders() 呼び出しにグループ化してください。

  このオプションは Qt 6.7 で導入されました。

• MULTIVIEW — マルチビュー非対応のシェーダーと、ビューカウント2のシェーダーの両方を生成します。これは、適切な GLSL/HLSL/MSL/VIEW_COUNT 引数を指定した 2 つの個別の `qt_add_shaders() ` 呼び出しと同等の利便性を提供するものです。 マルチビュー変種の暗黙的な設定は、GLSL330,300es 、HLSL61 、MSL21 、および VIEW_COUNT2 です。マルチビュー変種は、.qsb ファイル名に.mv2qsb という接尾辞が付加された形で保存されます。

  このオプションは Qt 6.8 で導入されました。

外部ツールのオプション

• PRECOMPILE — Windows において（HLSL が無効になっていない場合）、実行時ではなくビルド時に HLSL ソースを DXBC バイトコードにコンパイルするために、Windows SDK のfxc を呼び出します。結果として生成される.qsb ファイルには、元の HLSL ソースではなく、コンパイルされた中間バイトコードが含まれます。qsb の-c 引数と同等です。Windows以外のプラットフォームでは効果はありません。
• OPTIMIZED — Vulkan SDK の `spirv-opt ` を呼び出し、SPIR-V バイトコードの最適化を実行します。`qsb` の `-O ` 引数と同等です。

その他のオプション

• BASE — 生成される.qsb ファイルのエイリアス（リソース内名）を計算するために使用されるパスプレフィックス。BASE が設定されている場合、各出力パスはそのまま保持されるのではなく、BASE を基準として相対パスになります。これは、qt_add_resources()のBASE 引数に類似しています。
• DEFINES — シェーダーのコンパイル中に有効となるマクロを、"name1=value1;name2=value2" の形式で定義します。あるいは、FILES と同様に、各エントリを改行で区切ることもできます。これは、qsb の-D 引数と同等です。
• OUTPUTS — 生成される `.qsb ` のファイル名をソースファイル名とは異なるものにする必要がある場合（たとえば、1つのシェーダーファイルが、`DEFINES` で区別される複数の `.qsb ` ファイルのソースとして機能する場合など）、`FILES` の各エントリに対して1つの出力ファイル名を指定します。各名前は、ソースファイル名に `.qsb ` を付加する代わりに、-o 引数を通じてqsb に渡されます。
• ORIGINAL_FILES —.qsb ファイルが、FILES にあるものとは異なるシェーダーソースファイルに依存する必要がある場合は、ここでFILES の項目ごとに 1 つのエントリを指定してください。これが指定されている場合、対応するORIGINAL_FILES のエントリは--orig-file を通じて CMake 依存関係ファイルに書き込まれ、基になるadd_custom_command() のDEPENDS 節に追加されます。これは、qt_add_shaders() に渡されるファイルが中間生成アセットであり、最終的な.qsb ファイルが元のソースファイルを追跡する必要がある場合に役立ちます。
• PERTARGETCOMPILE — SPIR-V にコンパイルし、ターゲット言語ごとに 1 回ずつ、個々の出力言語バージョンに個別に変換します。これはデフォルトのシングルパス方式よりも処理速度は遅くなりますが、QSHADER_<LANG>[_VERSION] プリプロセッサマクロによる条件付きコンパイルが可能になります。qsb の-p 引数と同等です。
• DEBUGINFO — SPIR-V 用の完全なデバッグ情報を生成します。これにより、RenderDocなどのツールが、パイプラインの検査や頂点／フラグメントのデバッグを行う際に完全なソースを表示できるようになります。PRECOMPILE も設定されている場合、fxc に対して、生成された DXBC バイトコードにデバッグ情報を埋め込むよう指示します。qsb の-g 引数と同等です。
• QUIET —qsb からのデバッグおよび警告出力を抑制します。致命的なエラーのみが表示されます。qsb の-s 引数と同等です。
• OUTPUT_TARGETS —qt_add_shaders を静的ライブラリで使用する場合、1つ以上の特別なターゲットが生成されます。変数名を指定することで、それらのターゲットを取得し、さらなる処理を行うことができます。
• MEDIUMP — GLSL ES フラグメントシェーダーのデフォルトとして、中精度浮動小数点数を要求します。非 ES GLSL を含む他のターゲットには影響しません。

手作りのシェーダーの置換

FILES リストは、.qsb パッケージ内の特定のシェーダーバリアントを手作りのファイルで置き換えるための特別な構文をサポートしています。これは、qsb の-r オプションと同等です：

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

ファイル名の後には、@ で区切られた任意の数の置換指定を記述できます。各指定では、シェーディング言語、バージョン、読み込むファイルをコンマで区切って指定します。ファイル名やディレクトリパス内の@ 文字は正しく処理され、構文解析に影響を与えません。詳細については、QSBマニュアルを参照してください。

例

基本的な使用方法

find_package(Qt6 COMPONENTS ShaderTools)

qt6_add_executable(exampleapp main.cpp)

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

これにより、実行時に:/wobble.frag.qsb が利用可能になります。元のwobble.frag ソースは実行ファイルには含まれません。

テッセレーション

頂点（vertex.vert ）、テッセレーション制御（tess.tesc ）、テッセレーション評価（tess.tese ）、フラグメント（fragment.frag ）の4つのステージからなるグラフィックスパイプラインは、次のように設定できます。

まず、頂点シェーダーとフラグメントシェーダーがコンパイルされます。TESSELLATION は、頂点シェーダーに対して特別なMetal変換を有効にし、テッセレーションにはOpenGL 4.xまたはES 3.2が必要であるため、GLSLのバージョンが引き上げられます。

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

テッセレーションシェーダーは、NOHLSL が必要であるため、別の呼び出しとしてリストされています。HLSLテッセレーションシェーダーは手動で記述し、挿入する必要があります。Metalのテッセレーションパラメータは明示的に指定されます。

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"
)