シェーダーゲンツール

shadergenツールは、Qt Quick 3Dのアセットコンディショニングパイプラインの一部であるコマンドラインアプリケーションです。プロジェクトごとに有効にしたり、コマンドラインから手動で実行することができます。実行時にマテリアルシェーダーを作成するプロセスはコストがかかるため、マテリアルシェーダーを事前に生成しておくことで、起動時間に大きな影響を与えたり、実行時の不要なストールを回避することができます。

オフラインシェーダジェネレータの最大の障害の1つは、マテリアルプロパティのテーマ自体に基づくだけでなく、シーンの残りの部分がどのようにセットアップされているかに基づいて、生成される可能性のある異なるマテリアルの量です。ダイナミックプロパティも考慮に入れると、マテリアルシェーダの並べ替えの分量が非常に多くなり、ビルド時にすべてを生成するのはすぐに実行不可能になります。ツールが生成する必要があるシェーダの量を制限するために、ツールはアプリケーションが必要と考えるシェーダのみを生成しようとします。ツールで使用されるヒューリスティックは、どのマテリアルを生成すべきかを常に検出できるとは限りません。マテリアルシェーダが正しく生成されたことを確認するために、ツールは.qsbcファイルを生成しているはずです。また、環境変数QT_RHI_SHADER_DEBUG=1を設定し、エンジンが事前に生成されたシェーダーを正常にロードしたことを示すデバッグ出力を見ることで、マテリアルが事前に構築されたキャッシュからロードされたことを確認することも可能です。

既知の制限は次のとおりです：

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

使用方法

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

をプロジェクトファイルに追加します：

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

または、次のようにコマンドラインから手動でshadergenツールを起動することもできます：

shadergen main.qml Material.qml

通常、shadergenツールはアプリケーションのプロジェクトフォルダから実行する必要がありますが、-C 引数を使用して、現在の作業ディレクトリを変更するように指示することもできます。

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

ツールが期待されるマテリアルを生成するためには、マテリアルだけでなくシーン全体について知る必要があることに注意してください。例えば、シーン内のライトの数はマテリアルの生成方法にも影響するので、関連するすべてのqmlファイルをツールが処理する必要があるファイルのリストに追加する必要があります。

コマンドライン引数

生成される内容

shadergen toolsのメイン出力ファイルは.qsbcファイルである。.qsbcファイルには、.qsbファイルのコレクションに加え、各マテリアルに固有のプロパティ文字列など、様々なマテリアルシェーダーに関するメタデータが含まれています。

.qsbcファイルは、-d 引数を指定してshadergenツールを呼び出すことで検査できます：

shadergen -d qtappshaders.qsbc

動的プロパティ

このツールはビルド時に実行されるため、実行時に変更される可能性のあるプロパティについて推論する機能は限られています。値がプロパティの範囲内でしか変化しないプロパティ、たとえば粗さの値は、生成されるマテリアルシェーダに影響を与えませんが、オンまたはオフのどちらかになるプロパティ、たとえば実行時にイメージマップを設定する場合は、生成されるマテリアルに異なるタイプが必要になります。したがって、マテリアルやシーンの機能を有効または無効にするマテリアルのすべてのバリアントは、個々のコンポーネントとして宣言することをお勧めします。

次の例は、実行時にマテリアルにベースカラーマップを追加するマテリアルの例です。この例では、コンポーネントMaterialRedExtended は決して使用されていないことに注意してください。これは、shadergenツールが実行時にbaseColorMap を動的に設定するために必要なシェーダーを生成するために定義されています。

MaterialRed.qml

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

MaterialRedExtended.qml

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

メイン.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
    }
}