QShaderBaker Class

メンバ関数のドキュメント

QShaderBaker::QShaderBaker()

新しい QShaderBaker を生成します。

[noexcept] QShaderBaker::~QShaderBaker()

デストラクタ。

QShader QShaderBaker::bake()

コンパイルおよび翻訳プロセスを実行します。

QShader インスタンスを返します。処理が正常に完了したかどうかを確認するには、QShader::isValid()を呼び出します。false が返された場合は、errorMessage()を呼び出してログを取得してください。

これは処理負荷の高い操作です。アプリケーションからこれを呼び出す場合は、別のスレッドで実行することをお勧めします。

QString QShaderBaker::errorMessage() const

最後に実行されたbake()からのエラーメッセージを返します。エラーがなかった場合は、空の文字列を返します。

void QShaderBaker::setBatchableVertexShaderExtraInputLocation(int location)

QShader::BatchableVertexShader バリアントを生成する際、location は、挿入される頂点入力の入力位置を指定します。この値はデフォルトで7に設定されており、頂点シェーダーがすでに入力位置7を使用している場合にのみ、上書きする必要があります。

void QShaderBaker::setBreakOnShaderTranslationError(bool enable)

シェーダーの変換（SPIR-V から GLSL/HLSL/MSL へ）が失敗した際の挙動を制御します。 デフォルトではこの設定は true になっており、要求されたシェーダーを生成できない場合、bake() はエラーを返します。これを望まず、生成可能な部分は生成し、残りは黙ってスキップしたい場合は、enable を false に設定してください。

複数のGLSLバージョンを対象にすると、特定の機能が指定されたバージョンに変換できない場合にエラーが発生する可能性があります。たとえば、textureSize() を使用するシェーダーを GLSL ES 100 に変換しようとすると、bake() の呼び出し全体が失敗し、「textureSize is not supported in ESSL 100」というエラーメッセージが表示されます。 要求されたにもかかわらず、結果にGLSL ES 100シェーダーが含まれなくても構わない場合は、このフラグをfalseに設定することで、bake()が成功するようになります。

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

生成されるシェーダーバリアントを指定します。各シェーダーバージョンについて、生成されるQShader には複数のバリアントが含まれる場合があります。

ほとんどの場合、v にはQShader::StandardShader という 1 つのエントリが含まれます。

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

コンパイルまたは変換するシェーダーの種類を指定します。デフォルトでは何も生成されないため、bake() を呼び出す前にこの関数を呼び出すことが必須です

たとえば、他の言語への追加の変換を行わない、最小限のベイク先としてSPIR-Vがあります。これを指定するには、次のようにします:

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

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

生成される GLSL および GLSL ES ソースに対して、追加のoptions を設定します。デフォルトでは、フラグは設定されません。

この関数は Qt 6.9 で導入されました。

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

マルチビューを使用してシェーダーをトランスパイルする場合（例：GL_OVR_multiview2、VK_KHR_multiview などに依存するレンダラー向けに gl_ViewIndex を使用する頂点シェーダーなど）、一部のターゲットでは、シェーダー内でビューの数を宣言する必要があります。 これはVulkanスタイルのGLSLコードでは行われず、SPIR-VやHLSLなどのターゲットには関係ありませんが、OpenGLおよびGLSLでは必要となるため、この値を追加のメタデータとして指定する必要があります。

デフォルトでは値は 0 であり、これにより `num_views ` ステートメントの挿入が無効になります。1 に設定しても意味がありません。なぜなら、いずれにせよそれがデフォルトの `num_views ` だからです。したがって、効果を得るためには `count ` を 2 以上に設定する必要があります。例えば 2 に設定すると、生成される GLSL シェーダーには `layout(num_views = 2) in; ` ステートメントが含まれます。

count を2以上に設定すると、いくつかのプリプロセッサステートメントも挿入されます。QSHADER_VIEW_COUNT はcount に設定され、GL_EXT_multiview 拡張機能が自動的に有効になります。したがって、適切なcount を設定することは、他の種類のシェーダーにおいても重要になる場合があります。例えば、頂点シェーダーとフラグメントシェーダー間でユニフォームバッファを共有し、両方のシェーダーが#if QSHADER_VIEW_COUNT >= 2 のような書き込みを行える必要がある場合などです。

この関数は Qt 6.7 で導入されました。

void QShaderBaker::setPerTargetCompilation(bool enable)

ターゲットごとのコンパイルをenable に設定します。デフォルトではこれは無効になっており、Vulkan/GLSLソースはバリアントごとに1回SPIR-Vにコンパイルされます（つまり、デフォルトでは1回、頂点シェーダーであり、かつ指定された「Batchable」バリアントである場合は2回コンパイルされます）。 生成されたSPIR-Vは、その後、さまざまなターゲット言語（GLSL、HLSL、MSL）に変換されます。

ターゲットごとのコンパイルモードでは、ターゲットごとに個別のGLSLからSPIR-Vへのコンパイルステップが行われます。つまり、setGeneratedShaders() を通じて指定された各GLSL/HLSL/MSLバージョンごとにコンパイルが行われます。入力ソースは同じですが、ターゲット固有のプリプロセッサ定義が挿入されます。 この方法は大幅に時間がかかりますが、アプリケーションが単一のシェーダーを提供し、#ifdef ブロックを使用して区別することを可能にします。このモードが無効になっている場合、同じことを実現する唯一の方法は、シェーダーファイルの複数のバージョンを用意し、それぞれを個別に処理し、それぞれに対応する{.qsb}ファイルを出力し、実行時のロジックに基づいて適切なファイルを選択することです。

このモードでは、以下のマクロが自動的に定義されます。なお、これらのマクロは常にシェーディング言語に紐づいており、グラフィックスAPIには紐づいていない点に注意してください。

• QSHADER_SPIRV - SPIR-Vをターゲットとする場合に定義されます（通常、Vulkanによって利用されます）。
• QSHADER_SPIRV_VERSION - ターゲットとするSPIR-Vのバージョン番号（例：100 ）。
• QSHADER_GLSL - GLSL または GLSL ES をターゲットとする場合に定義されます（通常、OpenGL または OpenGL ES で利用されます）。
• QSHADER_GLSL_VERSION - ターゲットとするGLSLまたはGLSL ESのバージョン番号（例：100 、300 、330 など）。
• QSHADER_GLSL_ES - GLSL ES をターゲットとする場合にのみ定義される
• QSHADER_HLSL - HLSLをターゲットとする場合に定義されます（通常、Direct 3Dで利用されます）
• QSHADER_HLSL_VERSION - 対象とする HLSL シェーダーモデルのバージョン。例：50
• QSHADER_MSL - Metal Shading Language をターゲットとする場合に定義されます（通常は Metal によって使用されます）
• QSHADER_MSL_VERSION - ターゲットとするMSLのバージョン（例：12 や20 など）。

これにより、次のようなシェーダーコードを記述できます。

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

通常のシェーダーコードの前に処理される、カスタムpreamble を指定します。

これは単にソース文字列の先頭に追加するだけではありません。他のすべての記述よりも前に配置することが求められるGLSLバージョンディレクティブの有効性には影響しません。また、preamble 内に記述された内容を無視するため、エラーメッセージに表示される行番号も変更されません。

プレアンブルの用途の一つとして、動的に生成された#define ステートメントを透過的に挿入することが挙げられます。

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

ソースdevice を設定します。これにより、ファイルだけでなく、任意のQIODevice を使用できるようになります。stage はシェーダーステージを指定し、オプションのfileName には、エラーメッセージで使用されるファイル名が格納されます。

void QShaderBaker::setSourceFileName(const QString &fileName)

シェーダーソースファイルの名前を `fileName` に設定します。これは、bake() を呼び出した際に読み込まれるファイルです。シェーダーステージはファイル拡張子から自動的に判別されます。これが望ましくない場合や不可能な場合は、代わりに `stage` 引数を持つオーバーロードを使用してください。

サポートされているファイル拡張子は以下の通りです：

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

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

シェーダーソースファイルの名前を `fileName` に設定します。これは、bake() を呼び出した際に読み込まれるファイルです。シェーダーステージは `stage` で指定されます。

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

入力シェーダーsourceString を設定します。stage はシェーダーステージを指定し、オプションのfileName にはエラーメッセージで使用されるファイル名が格納されます。

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

生成されるSPIR-Vバイナリに対して、追加のoptions を設定します。デフォルトでは、フラグは設定されません。

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

テッセレーション制御シェーダー用のMSLシェーダーコードを生成する際、テッセレーションのmode （三角形または四角形）はあらかじめ決定されている必要があります。GLSLでは、これは通常テッセレーション評価シェーダー内で宣言されますが、Metalの場合、テッセレーション制御シェーダーからコンピュートシェーダーを生成する際にも、この が既知である必要があります。

設定されていない場合、デフォルトは三角形となります。

void QShaderBaker::setTessellationOutputVertexCount(int count)

テッセレーション評価シェーダー用のMSLシェーダーコードを生成する際は、テッセレーション制御シェーダーの出力頂点count を事前に把握しておく必要があります。GLSLでは通常、これはテッセレーション制御シェーダー内で宣言されますが、Metalの場合、テッセレーション評価シェーダーから頂点シェーダーを生成する際にも、この を把握しておく必要があります。

設定されていない場合、デフォルト値は 3 です。