PSO のリファレンス

PSO キャッシング オプションの完全リファレンス。

Windows
MacOS
Linux

以下のページで Pipeline State Object (PSO) キャッシング システムで使用可能な各種コマンドおよびオプションのすべてを説明します。

プロパティ

プロパティ

説明

SetBatchMode Background

インタラクティブ メニューのバックグラウンドで使用されます。

SetBatchMode Fast

ロード画面や動画の表示中に使用され、より多くの PSO のコンパイルを可能にします。

ResumeBatching

バッチ処理を再起動するために使用されます。

NumPrecompilesRemaining

未コンパイル PSO の総数を検出するために使用されます。

NumPrecompilesActive

このフレームのプリコンパイルがアクティブなパイプラインの数を返します。

OpenPipelineFileCache

シェーダ パイプライン キャッシュ ファイルを利用可能であれば LastOpened 設定で、利用可能でなければプロジェクト名で開きます。

SavePipelineFileCache

現在のシェーダ パイプライン キャッシュを、インクリメント アプローチを使用する Fast または、全データをファイルに統合する Slow いずれかの保存モードでディスクに保存します。

ClosePipelineFileCache

既存のパイプライン キャッシュを閉じて、異なるファイルかつ / または異なるシェーダ プラットフォームで再オープンできるようにします。暗黙的に Fast 保存を実行します。

ShaderLibraryStateChanged

FShaderCodeLibrary によって呼び出される。シェーダ コード ライブラリの状態が変化したためシェーダの利用状態を再評価する必要があることを通知します。

SetGameUsageMaskWithComparison

現在の PSO Game Usage Mask と比較関数を設定します。このマスクが古いマスクと異なる場合は true を、そうでないか、キャッシュ システムまたはマスク機能が無効の場合は false を返します。新しい PSO が見つかるとこの値と共にロギングされるか、既存 PSO のマスクが更新されます。詳細については FPipelineFileCache を参照してください。

FShaderPipelineCache

FShaderPipelineCache は FShaderCache に代わる新たな PSO のロギング、シリアル化およびプリコンパイル処理の仕組みを提供します。パイプライン ステート オブジェクトのキャッシングとディスクへの初期化子のシリアル化により、次回ゲーム実行時にこれらの状態をプリコンパイル処理してヒッチを減らします。FShaderPipelineCache は FShaderCodeLibrary と「Share Material Shader Code」および RHI レベルのバックエンド FPipelineFileCache に依存します。

基本的なランタイムの使用方法

以下のコマンドは、PSO キャッシング実行中の PSO データのコンパイル中にプロジェクトがヒッチすることを防ぐのに役立ちます。

  • r.ShaderPipelineCache.Enabled = 1 としてキャッシュを有効にして、パイプライン キャッシュが既存データをディスクからロードしてプリコンパイルします。 

  • r.ShaderPipelineCache.BatchSize = X でデフォルト バッチ サイズを設定します。X はデフォルトの Fast BatchMode でプリコンパイルする場合に、ひとつのバッチでコンパイルされる PSO の最大数です。

  • r.ShaderPipelineCache.BackgroundBatchSize = X でバックグラウンドのバッチ サイズを設定します。X はバックグラウンド バッチ モード時にコンパイルされる PSO の最大数です。 

  • FShaderPipelineCache::SetBatchMode を呼び出すゲーム コードを実装して、ファスト モードとバックグラウンド モードを切り替えます。 

  • BatchMode::Fast を使用することで、ロード画面または動画の描画中に、より多くの PSO のコンパイルが可能になります。一方で、Background はインタラクティブ メニューのバックグラウンドで使用されます。必要に応じて NumPrecompilesRemaining を呼び出して、コンパイルすべき未処理の PSO の総数を調べて、終了するまでロード中の画面または動画を表示し続けます。 

  • ゲームと対象プラットフォームのパフォーマンスに応じて、 PauseBatching を呼び出してゲームプレイ中のプリコンパイル処理を一時停止して ロード画面、メニューや動画のバックグラウンドで ResumeBatching によりプリコンパイル処理を再開する必要もあるかもしれません。

その他のランタイム オプション

以下のコマンドは、PSO によるキャッシュのビルド時の、より細かな制御をするのに役立ちます。

  • GGameIni (それに伴い GGameUserSettingsIni も) 内でシェーダー パイプライン キャッシュに設定を保持する [**ShaderPipelineCache.CacheFile**] セクションを使用させます。

  • LastOpened 設定は、最後に開いたキャシュの名前を Open を併記して保持します。 FShaderPipelineCache::Initialize が存在する場合は、その内部で使用され、既存キャッシュを開きます。記述がなければ AppName がデフォルトになります。

  • SortMode 設定は、以下いずれかひとつの中から希望する PSO のソート モードを保持します。

    • Default:ファイルに記述された順番でロードします。

    • FirstToLatestUsed:最も低利用な最初フレームの PSO から開始して、最も高利用なものに向かって処理します。

    • MostToLeastUsed:最も高利用な PSO から開始して最も低利用なものに向かって処理します。

  • 指定がなければ FShaderPipelineCache::InitializeOpenPipelineFileCache 内で「Default」を使用します。 

  • GameVersionKey は読み取り専用の整数値で GGameIni 内で指定され、ゲーム コンテンツで互換性の無いバージョンの曖昧さ回避のためにゲーム コンテンツのバージョンを指定します。デフォルト値は FEngineVersion 変更リストから取得されます。

ログの使用

以下のコマンドを PSO データのキャプチャ時に利用できます。

  • r.ShaderPipelineCache.Enabled = 1 コマンドを使用して PSO キャッシュを有効にして、 r.ShaderPipelineCache.LogPSO = 1 コマンドにより実行時のログ取得を起動します。 

  • 上記を実行する場合、ゲームが起動時に適切なキャッシュを開いて、ゲーム プレイが可能になっていることを確認してください。 

  • PSO は検出時にログが取得されます。Unreal Engine 4 (UE4) は PSO をオフラインで クックする機能を提供していないため、このシステムは実際のレンダリングに使用されている PSO のみを収集します。 

  • そのため、ゲームをマニュアル プレイしてログを収集するか、このコードのスコープ外の処理を自動化しなければなりません。 

    • FShaderPipelineCache::SavePipelineFileCache を呼び出すことでいつでもデータを保存できます。 これは、 r.ShaderPipelineCache.SaveAfterPSOsLogged = X を設定して PSO の数を与えることで自動実行させることができます。 ここでの X は保存前にログ取得したい PSO の数です (0 で自動保存が無効)。

  • ログ ファイルはオーバヘッドを減らすために、シェーダー プラットフォーム固有です。

ファイルの場所とパッケージ化

さらに以下に、PSO データが保存される場所について記述します。

  • 書込み可能なキャッシュは常に「User Saved」ディレクトリに保存されます。

  • ゲームは「Game Content」ディレクトリ内に初期またはシード データとして使用する変更不可能なコピーを作成することができます。 

  • 開発環境で生成して UnrealEd.MergeShaderPipelineCaches でマージしたログは、関連するプラットフォームの「Game Content」ディレクトリ内にパッケージ化されます。

要件

プロジェクトでの PSO のキャプチャをセットアップするにあたっての要件は以下の通りです。

  • FShaderCodeLibrary が 「Project Settings > Packaging > Share Material Shader Code」 によって有効化されている必要があります。

  • Native Shader Libraries を有効にするかどうかは任意ですが Metal のために強くお勧めします。

追記

  • ClosePipelineFileCache (暗黙的に Fast セーブします) で既存ファイルを閉じて OpenPipelineFileCache で新規に開くことで開いているキャッシュ ファイルを変更できます。 

  • ログ取得時に、スイッチがロギングされてから新規エントリのみスイッチするとと、スイッチの前にログ取得されるはずだった PSO が失われます。これにより想定外のエントリによってキャッシュが汚れるのを防ぎます。 

  • UnrealEd.MergeShaderPipelineCaches コマンドレット を使用して同じファイルバージョン、シェーダー プラットフォーム、ゲームバージョンのキャッシュ ファイルをマージすることができます。

新しい Unreal Engine 4 ドキュメントサイトへようこそ!

あなたの声を私たちに伝えるフィードバックシステムを含め、様々な新機能について開発をおこなっています。まだ広く使える状態にはなっていないので、準備ができるまでは、ドキュメントフィードバックフォーラムで、このページについて、もしくは遭遇した問題について教えていただけると助かります。

新しいシステムが稼働した際にお知らせします。

フィードバックを送信