Shadergenツール

Shadergenツールは、Qt Quick 3Dのアセット調整パイプラインの一部を構成するコマンドラインアプリケーションです。プロジェクトごとに有効化することも、コマンドラインから手動で実行することも可能です。 マテリアルシェーダーを事前に生成しておくことで、起動時間に大きな影響を与えるほか、実行時の不要な停止を回避できる場合があります。これは、実行時にマテリアルシェーダーを作成する処理に多大なコストがかかるためです。

オフラインシェーダージェネレータにとって最大の課題の一つは、生成可能なマテリアルの種類の多さです。これはマテリアルプロパティそのものだけでなく、シーンのその他の設定（例えば、ライトの数、ライトの種類、影など）にも依存します。これらすべてが、生成されるシェーダーに影響を与えます。 さらに動的なプロパティも考慮に入れると、マテリアルシェーダーの組み合わせの数は瞬く間に膨大になり、ビルド時にそれらをすべて生成することは現実的ではなくなってしまいます。ツールが生成する必要があるシェーダーの数を抑えるため、このツールはアプリケーションが必要とすると思われるシェーダーのみを生成するよう努めています。 このツールで使用されるヒューリスティックは、どのマテリアルを生成すべきかを常に正確に検出できるとは限りません。これは、実行時に変化するプロパティの場合に特に当てはまります。 マテリアルシェーダーが正常かつ正しく生成されたことを確認するには、ツールによって生成された.qsbcファイルを確認し、その内容がアプリケーションで使用されているマテリアルと一致しているかを確認してください。 また、環境変数QT_RHI_SHADER_DEBUG=1 を設定し、エンジンが事前に生成されたシェーダーを正常に読み込んだことを示す記述がデバッグ出力に含まれているかを確認することで、マテリアルが事前生成キャッシュから読み込まれたことを検証することも可能です。

既知の制限事項は以下の通りです。

• View3D が2つ以上存在するシーン。
• マテリアルの生成を使用している場合、ライトの動的な追加や削除はサポートされていません。
• 生成されたシェーダーは、レンダラーの内部構造に依存しているため、使用されているQtのバージョンに厳密に紐付けられています。したがって、バージョン間の生成されたシェーダーの互換性は保証されません。

使用方法

プロジェクトでマテリアルシェーダーのオフライン生成を有効にするには、プロジェクトファイルに以下を追加してください：

CMake:

qt6_add_materials(offlineshaders "shaders"
    PREFIX
        "/"
    FILES
        ${qml_resource_files}
)

あるいは、shadergen ツールをコマンドラインから手動で次のように実行することもできます:

shadergen main.qml Material.qml

通常、shadergenツールはアプリケーションのプロジェクトフォルダから実行しますが、-C 引数を指定することで、ツールの現在の作業ディレクトリを変更させることも可能です。

出力パスが指定されていない場合、ツールは生成されたファイルを現在のディレクトリに書き込みます。出力パスは-o オプションで変更できます。

なお、ツールが期待通りのマテリアルを生成するためには、マテリアルだけでなくシーン全体の情報を把握する必要があります。例えば、シーン内のライトの数もマテリアルの生成方法に影響を与えるため、関連するすべての qml ファイルを、ツールが処理する必要のあるファイルの一覧に追加する必要があります。

コマンドライン引数

生成される内容

shadergen ツールの主な出力ファイルは .qsbc ファイルです。 .qsbc ファイルには、一連の.qsbファイルに加え、各マテリアル固有のプロパティ文字列など、さまざまなマテリアルシェーダーに関するメタデータが含まれています。.qsbc ファイルの内容を確認するには、shadergen ツールで次のように `-l ` 引数を使用します。

shadergen -l qtappshaders.qsbc

動的プロパティ

このツールはビルド時に実行されるため、実行時にどのプロパティが変化する可能性があるかを判断する能力には限界があります。 値がプロパティの範囲内でのみ変化するプロパティ（例えば、ラフネス値など）は、生成されるマテリアルシェーダーに影響を与えませんが、オンまたは オフのいずれかであるプロパティ（例えば、実行時にイメージマップを設定する場合など）は、異なるタイプのマテリアルの生成が必要となります。 したがって、マテリアルやシーン内の機能を有効または無効にするマテリアルのすべてのバリエーションを、個別のコンポーネントとして宣言することを推奨します。これにより、ツールが正しいマテリアルシェーダーを生成できるようになります。

以下の例は、実行時にマテリアルにベースカラーマップを追加したい場合の、やや人工的なマテリアルの例を示しています。なお、コンポーネント `MaterialRedExtended ` はこの例では一切使用されていません。これは、Shadergenツールが実行時に `baseColorMap ` を動的に設定するために必要なシェーダーを生成できるよう、純粋に定義されているものです。

MaterialRed.qml

PrincipledMaterial {
    baseColor: "red"
    lighting: PrincipledMaterial.NoLighting
}

MaterialRedExtended.qml

MaterialRed {
    baseColorMap: Texture {
        source: "maps/metallic/basecolor.jpg"
    }
}

main.qml

Model {
    position: Qt.vector3d(0, -30, 0)
    scale: Qt.vector3d(4, 4, 4)
    source: "#Sphere"
    materials: MaterialRed {
        id: redMaterial
    }
MouseArea {
    anchors.fill: parent
    onClicked: {
    if (redMaterial.baseColorMap === null)
        redMaterial.baseColorMap = baseColorMap
    else
        redMaterial.baseColorMap = null
    }
}