GPU レイトレーシングのデバッグは、なぜこれほど難しいのか
NVIDIA OptiX でレイトレーシングアプリケーションを開発していると、画面が 真っ黒 になる現象に一度は遭遇するはずです。
問題は原因が多岐にわたる点にあります。
- API 引数が不正なケース
- GPU 側のバグが数千の並列スレッドの下に埋もれているケース
- シェーダーロジック自体が誤っているケース
特に OptiX は GPU カーネルが大規模並列で動作するため、printf によるデバッグでは出力が 消防ホースのように 溢れ、本当に必要な情報を見つけることがほぼ不可能です。
本記事では、NVIDIA が公開している OptiX Toolkit (OTK) を用いて、以下の 2 つの課題を整理して解決する方法を解説します。
- OptiX / CUDA API のエラーコードを 一貫した方針で チェックする方法
- GPU デバイスコードから 狙った場所だけ デバッグ出力する方法
OTK は BSD 3-clause ライセンスのため、商用プロジェクトにも自由にコピー・改変して組み込めます。実務にそのまま適用可能です。
根拠資料: NVIDIA Developer Blog – Debugging Ray Tracing Applications Using NVIDIA OptiX Toolkit
ステップ1: OptiX ログと Validation モードの理解
OptiX デバイスコンテキストを作成する際、オプション構造体に ログコールバック と Validation モード を設定できます。OPTIX_DEVICE_CONTEXT_VALIDATION_MODE_ALL を指定すると、OptiX が API 入力値を自動検証します。
検証エラーは人間が読めるメッセージとしてログに記録されます。OPTIX_ERROR_INVALID_VALUE のようなエラーが出た場合、まずログを確認する のが定石です。
注意点として、Validation は API に若干のオーバーヘッドを課します。したがって デバッグ/テストビルドでは有効化し、リリースビルドでは無効化する のが推奨されます。
ステップ2: OTK_ERROR_CHECK マクロによるエラーチェックの統一
OptiX、CUDA Runtime、CUDA Driver API はすべて類似のパターンに従います。
- エラーコード用の enum 型 (例:
OptixResult) - エラーコードのシンボリック名を文字列で返す関数
- 人間が読めるメッセージを返す関数
問題は、これを すべての API 呼び出し箇所で手動処理するのが苦痛 だという点です。そこで OTK はマクロを提供しています。
// 例外をスローするポリシー
OTK_ERROR_CHECK( expr );
// std::cerr にメッセージを出力して継続するポリシー
OTK_ERROR_CHECK_NOTHROW( expr );
マクロは最小限にとどめ、実処理は inline 関数に委譲する設計です。これにより inline 関数にブレークポイントを張れば、エラー検出時点でデバッガが停止し、原因を即座に特定できます。
マクロが渡す診断情報は以下の通りです。
expr: エラーコードを評価する式 (文字列化)__FILE__: マクロが呼び出されたソースファイル名__LINE__: マクロが呼び出された行番号
エラーメッセージのフォーマットは次のとおりです。
file(line): expr failed with error nnn (name): message
ステップ3: 実際の使用例 (3 API の統合)
OTK は API ごとに 1 つのヘッダーを提供し、すべての呼び出し箇所を 単一のマクロ でラップできます。
// CUDA Runtime API
OTK_ERROR_CHECK( cudaSetDevice( m_deviceIndex ) );
// CUDA Driver API
OTK_ERROR_CHECK( cuCtxGetCurrent( &m_cudaContext ) );
OTK_ERROR_CHECK( cuStreamCreate( &m_stream, CU_STREAM_DEFAULT ) );
// OptiX API
OTK_ERROR_CHECK( optixInit() );
これにより、3 つの API のエラーポリシーが 1 箇所で 管理されます。チーム開発で特に有用です。
ステップ4: DebugLocation による GPU デバッグ出力の標的化
printf デバッグの本質的な問題は ノイズ です。GPU 上では数千のスレッドが同時に動作しており、問題発生前の出力はすべて不要なデータにすぎません。
OTK の DebugLocation 構造体はこの問題を整理して解決します。
struct DebugLocation
{
bool enabled;
bool dumpSuppressed;
bool debugIndexSet;
uint3 debugIndex;
};
デバッグ情報は以下の条件がすべて真の場合にのみ出力されます。
enabled == truedumpSuppressed == falsedebugIndexSet == true- 現在の launch index が
debugIndexと一致
この構造体を OptiX パイプラインの launch parameters に含めることで、実行時にインタラクティブに制御できます。
コールバック構造体
struct Callback
{
void setColor( float red, float green, float blue );
void dump( const uint3& index );
};
setColor: デバッグ位置の周囲に 視覚的なボックス を描画し、画面上のどこを対象にしているか表示dump: 対象 launch index で必要な情報を出力
赤ピクセルを 1 ピクセルの黒枠で囲み、さらに 1 ピクセルの白枠で囲む構成のため、高コントラストのインジケータ となります。カラーバッファ以外の場合は RGB 値を別の値にマッピングしても問題ありません。
One-shot モードで出力の氾濫を防ぐ
DebugLocationを有効化し、通常通り launch- ユーザーがデバッグ位置を選択 →
dumpSuppressed=true,debugIndexSet=true,debugIndex=選択位置 - 以降の launch は位置表示のみで dump は行わない
- ユーザーがアプリを所望の状態に操作
- デバッグ情報が必要なタイミングで
dumpSuppressed=falseにトグル - Launch → デバッグ出力を取得
- Launch 後に再び
dumpSuppressed=true
このパターンにより、必要な瞬間のスナップショット だけを取得できます。
注意事項と限界
- Validation モードはリリースビルドでは必ず無効化してください。性能劣化が体感できる場合があります。
OTK_ERROR_CHECKの例外スローポリシーはプロジェクトの例外方針と衝突する可能性があるため、NOTHROW版やカスタムマクロでポリシーを合わせる必要があります。DebugLocationは launch parameter に含まれるため、パイプライン再コンパイルなしで 実行時トグルが可能という点が最大の利点です。
次のステップ学習の方向性
- OTK の
DemandPbrtSceneサンプルを動かしながらDebugLocationの実践的な使い方を習得 (pbrt-v3 のシーンファイルが必要) - OptiX SDK サンプルの Validation 関連コードを読む
- 長期的には、独自のロギング/レポーティング機構に OTK のエラー文字列化ロジックを移植することを推奨
まとめ: OTK でデバッグ時間を半減させる
整理すると以下のとおりです。
- API エラーチェック:
OTK_ERROR_CHECKマクロ 1 つで OptiX / CUDA Runtime / CUDA Driver を統一方針で管理 - デバイスデバッグ出力:
DebugLocation+debugInfoDumpで対象 launch index のみを狙い撃ち - One-shot モード で出力の氾濫を防ぎ、インタラクティブに問題状態を再現
OTK は NVIDIA/optix-toolkit GitHub リポジトリ から取得できます。まずはデバッグビルドで Validation を有効化し、CUDA / OptiX 呼び出しを OTK_ERROR_CHECK でラップするところから始めてください。黒画面の前で呆然とする時間が大幅に減ります。