3DGS レンダリングのログとデバッグツール

このページでは、診断情報の取得方法と各ツールの読み方を説明する。現象から問題を特定する方法はトラブルシューティングを参照する。

プラグインのログを確認する

プラグインのログは 2 つのカテゴリーに分かれる。

カテゴリー	対象
`LogLCC`	LCC パイプラインと共通機能（読み込み、コリジョン、ライセンス、ユーティリティ関数）
`LogLCC2`	LCC2 パイプライン専用

エディターで確認する

Window > Output Log を開く。自分で調べるときはフィルターの入力欄に LogLCC と入力するとプラグインの情報を素早く絞り込める。コンソールで次のコマンドを実行してログのレベルを上げることもできる。

log LogLCC Verbose
log LogLCC2 Verbose

エディターのログファイルは次の場所にある。

<プロジェクトディレクトリ>/Saved/Logs/<プロジェクト名>.log

パッケージ化した後のプログラムで確認する

Development でパッケージ化する場合は -log 引数を付けて起動すると、コンソールウィンドウが表示される。ログファイルは次の場所にある。

<パッケージ出力ディレクトリ>/<プロジェクト名>/Saved/Logs/<プロジェクト名>.log

Shipping のパッケージは既定でログを出力しないので、問題を調べるときは Development のパッケージを使う。

問題を報告するときは、問題が起きた実行時の完全なログファイルを添付する。フィルターをかけてプラグイン関連の数行だけを送らないようにする。問題の特定にはプラグイン以外の文脈が必要になることが多い。

レンダリングの統計：stat XGrids

コンソールで stat XGrids を実行する。または Actor の Details パネルの Actions カテゴリーにある Stats ボタンを使う。

stat unit と合わせて見て、まずボトルネックが 3DGS にあるかを判断する。

数量の項目

もっともよく見る項目を挙げる。

統計項目	意味
`Total Splats`	データの Splat の総量
`Level0 Splats`	Level 0（最高精度）の Splat 数
`Current Render Splats`	現在のフレームで実際にレンダリングした Splat 数。レンダリングの負荷を判断するときは主にこれを見る
`Current Render Main Splats`	現在のフレームでレンダリングした主体のデータ量
`Current Render Environment Splats`	現在のフレームでレンダリングした環境のデータ量
`Total Nodes`	ノードの総数
`Current Render Nodes`	現在のフレームでレンダリングしたノード数
`Visible Node Num`	可視ノード数
`LCC Draw Call`	プラグインが発生させた Draw Call 数
`LCC Sort Num`	ソートの回数
`Camera Num`	レンダリングに参加するカメラの数

使い方：Current Render Splats が Max Splat Num の上限に張り付き続けている場合、すでに数量の制限で切り詰められており、画面のディテールが削られている状態である。上限を上げる（パフォーマンスと引き換えに画質を取る）か、Level Factor を調整して元からノードを減らす。

データの総量はコードから読むこともできる。GetSplatNumber を参照する。

処理時間の項目

段階ごとに分けた処理時間で、どこで詰まっているかを特定するのに使う。

統計項目	対応する段階
`Render LCC`	プラグインのレンダリングの合計時間
`Traversal Time`	ノードのトラバース。そのフレームでどのノードをレンダリングするかを決める
`Determine Nodes Level`	各ノードの精度の階層を計算する
`Load Data To CPU`	データをメモリに読み込む
`Upload To GPU`	データをビデオメモリにアップロードする
`Splat Sort`	Splat のソート（半透明のレンダリングに必要）
`Node Sort`	ノードのソート
`Build Mesh Batch`	描画バッチの構築
`Wait Node Ready`	ノードのデータの準備を待つ
`Component Update`	コンポーネントの更新
`Update Camera Info`	カメラ情報の更新
`Load Meta File`	メタ情報ファイルの読み込み
`Load Index Data`	インデックスデータの読み込み（LCC パイプライン）
`Load Collision Data`	コリジョンデータの読み込み
`Load Environment Data`	環境データの読み込み
`Update Collision`	コリジョンの更新
`Get Physics Trimesh Data`	物理のコリジョンメッシュの生成
`Release Memory`	メモリの解放
`Preload Node`	ノードのプリロード
`Get From Cache`	キャッシュからのデータ取得
`Create Thread`	スレッドの作成
`Draw Node Box`	ノード境界の描画（デバッグ可視化を有効にしたときのみ）

使い方：

Splat Sort が高い場合、LCC パイプラインでは Sort Factor を大きくしてソート頻度を下げられる
Wait Node Ready が高い場合、データの読み込みが追いついていないことを意味する。ディスクが遅いか、スレッド数が不足している可能性がある
Upload To GPU が高い場合、フレームごとにアップロードするデータ量が大きいことを意味する。Level Factor または Max Splat Num を調整する
Update Collision と Get Physics Trimesh Data が高い場合、Max Load Collision Distance を小さくする

完全なチューニングの流れはパフォーマンス最適化ガイドを参照する。

メモリとビデオメモリの項目

統計項目	意味
`CPU Usage`	プラグインが使用するメモリ
`GPU Usage`	プラグインが使用するビデオメモリ
`Position Data(For Raycast) Usage`	レイキャストに使う位置データの使用量
`Collision Data Usage`	コリジョンデータの使用量
`CPU Occupy Percentage`	CPU メモリの使用率
`GPU Occupy Percentage`	ビデオメモリの使用率

使用率の項目はプロジェクト設定の解放しきい値に対応する。使用率が長期的に Max GPU Usage Percetage For Free に張り付いている場合、リソースの回収が頻繁にトリガーされており、カクつきの原因になりうる。

ビデオメモリの割り当てルールと予算の上限はレンダリングを参照する。

スレッドの項目

統計項目	意味
`Collision Loader Thread Num`	コリジョン読み込みスレッド数
`Exporter Thread Num`	エクスポートスレッド数

ノード境界の可視化

Actor の Details パネルの Actions カテゴリーにある Debug Node Bound ボタンで切り替える。またはコンソールで次を実行する。

r.Xgrids.DrawNodeBox 1

現在読み込まれているノードをワイヤーフレームのボックスで描画する。ボックスのカラーはノードの Level に対応する。赤、橙、黄、緑、青、紫の順に進み、赤が Level が最も低い（精度が最も高い）、白が Level が最も高い（精度が最も低い）ことを示す。

ノードと Level の概念はレンダリングを参照する。

読み方：

遠くでまだ赤いボックスがレンダリングされている場合、精度が高すぎてパフォーマンスが無駄になっている。Level Factor を大きくする
近くが寒色のボックスばかりの場合、精度が抑えられすぎていて画面がぼやける。Level Factor を小さくするか Start Level を確認する
ボックスの数が想定を大きく超えている場合、Max Distance が大きすぎないか確認する

エディターと Development ビルドでのみ有効である。対応するコードのインターフェースは DebugNodeBound である。

コリジョンの可視化

Actor の Details パネルの Actions カテゴリーにある Show Collision ボタンで切り替える。またはコンソールで次を実行する。

r.xgrids.DrawCollision 1

読み込み済みのコリジョンボディのワイヤーフレームを描画する。

読み方：

ワイヤーフレームがまったくない：データにコリジョンファイルが含まれていないか、bEnableCollision がオフになっている。コリジョンの前提条件を参照する
近くにしかワイヤーフレームがない：正常な挙動である。コリジョンは距離に応じたストリーミング読み込みで、Max Load Collision Distance の制限を受ける
ワイヤーフレームが画面の内容とずれている：コリジョンデータとレンダリングデータが一致していない。テクニカルサポートに連絡する

レイキャストが当たらない、キャラクターがすり抜けるといった問題を調べるときは、まずこれを開いてコリジョンが実際に読み込まれているかを確認する。読み込みの仕組みはコリジョンを、コードのインターフェースは ShowCollision を参照する。

ログの情報	意味と対処
`LCC file :<パス> does not exist.`	パスが存在しない。パスを照合する。相対パスは `Content` を基準にする
`meta.lcc file :<パス> load error,Please check.`	LCC1 のメタ情報ファイルの解析に失敗した。ファイルが破損している可能性がある
`Load Meta.lcc error,Please check your file!`	同上
`Read index.bin error,path:<パス>.`	インデックスファイルの読み取りに失敗した。`index.bin` が存在し破損していないことを確認する
`LCC4Unreal do not support this file format!`	形式が非対応である。拡張子が対応範囲内か確認する
`The data file:<パス> does not exist,Please check your file!`	データのブロックファイルが欠けている。データディレクトリが不完全な可能性がある

コリジョン関連

ログの情報	意味と対処
`There is neither collision.bin nor collision.lci in the folder:<パス>, please check.`	データディレクトリにコリジョンファイルがない。このデータではコリジョンを有効にできない
`Failed to open file <パス>`	コリジョンファイルを開けなかった。ファイルの権限と整合性を確認する
`Read collision data error,path:<パス>.`	コリジョンデータの読み取りに失敗した。ファイルが破損している可能性がある
`Invalid indices in collision data!`	コリジョンデータの内容が異常である。テクニカルサポートに連絡する

レンダリング関連

ログの情報	意味と対処
`r.PostProcessing.PropagateAlpha is 0. LCC4Unreal requires this to be enabled for correct rendering.`	この項目を有効にする必要がある。有効にしないと alpha のブレンドが正しくならない。プラグインは同時に通知も表示する
`Unlicensed: enabled clipping volumes limited to <N> ...`	無償版でクリッピングボリュームの数が枠を超えている。超えた分はレンダリングされない。エディションとライセンスを参照する
`Unlicensed: enabled section planes limited to <N> ...`	同上。断面プレーンの数が枠を超えている

GIS 関連

ログの情報	意味と対処
`This lcc does not have RTK information!`	データに RTK の地理情報が含まれておらず、地理配置を使えない
`MetaInfo's Offset has no 3 elements!`	メタ情報のオフセットのフィールドが異常である。データに問題がある可能性がある

ライセンス関連

ログの情報	意味と対処
`ProjectID is invalid; generate one in Project Settings (Project/Description). Refusing authentication.`	プロジェクトに Project ID がない。プロジェクト設定で生成する
`Failed to decode AppKey, please check.`	AppKey の内容が不完全である。もう一度コピーする
`Invalid AppKey, please check.`	AppKey の形式が誤っている
`Authorization has expired, please check.`	ライセンスの期限が切れている。再生成する
`AppKey has expired. Please generate a new one.`	同上
`Authentication Failed: <メッセージ>`	サーバー側が返した失敗の理由。メッセージの内容に従って対処する
`HTTP request failed`	ライセンスサーバーに接続できない。ネットワークを確認する
`HTTP error! Status: <コード>`	サーバーがエラーのステータスコードを返した
`Signature Verification Failed`	署名の検証に失敗した。テクニカルサポートに連絡する

プロキシメッシュ関連

ログの情報	意味と対処
`has a null StaticMesh`	プロキシメッシュの Actor に StaticMesh が割り当てられておらず、機能しない。インスタンスごとに 1 回だけ通知する

問題を報告するときに添付するもの

次のリストに沿って集めると、特定の速度が明らかに上がる。

プラグインのバージョンとエンジンのバージョン。 プラグインのバージョンはプラグインパネルの右下で確認できる。エンジンの Edit > Plugins ウィンドウで LCC4Unreal を検索して確認してもよい。
問題が起きたときの完全なログファイル。 .log ファイル自体をそのまま提供し、フィルターをかけず、エラーの 1 行だけを切り出さない。ログの前後の文脈には特定に必要な重要な情報が含まれていることが多く、フィルターをかけるとかえって手がかりが失われる。ログの場所はプラグインのログを確認するを参照する。
データの情報。 形式、おおよその規模（Total Splats）、コリジョンを含むかどうか。
再現手順。 プロジェクトを新規作成した状態から始める最小の再現手順がもっとも価値が高い。
ハードウェア環境。 グラフィックスカードの型番、ドライバーのバージョン、ビデオメモリの容量。
Project ID。 ライセンス関連の問題で必要になる。Project Settings > Project > Description で確認できる。

連絡先はお問い合わせを参照する。