# 機能設計書 269-imgui_impl_wgpu

## 概要

本ドキュメントは、Dear ImGuiのWebGPUレンダラーバックエンド（imgui_impl_wgpu）の機能設計を定義する。

### 本機能の処理概要

WebGPUレンダラーバックエンドは、Dear ImGuiのUI描画コマンドをWebGPU APIに変換し、画面にUIを描画する機能を提供する。WGSLシェーダーを使用し、ブラウザ環境（Emscripten経由）およびネイティブ環境（Dawn/wgpu-native）でのレンダリングをサポートする。

**業務上の目的・背景**：
WebGPUを使用するクロスプラットフォーム/Web対応アプリケーションにDear ImGuiを統合する必要がある場合に本バックエンドを使用する。WebGPUは次世代のWeb向けグラフィックスAPIであり、Vulkan/Metal/DirectX12に相当する機能をブラウザから利用可能にする。

**機能の利用シーン**：
- Webアプリケーション（Emscripten）へのImGuiデバッグUI追加
- Dawn（Google）またはwgpu-native（Mozilla）を使用したネイティブアプリケーション
- クロスプラットフォームのポータブルグラフィックスアプリケーション

**主要な処理内容**：
1. バックエンドの初期化（`ImGui_ImplWGPU_Init`）：InitInfo構造体による設定
2. デバイスオブジェクト作成（`ImGui_ImplWGPU_CreateDeviceObjects`）：パイプライン、BindGroup作成
3. フレーム開始処理（`ImGui_ImplWGPU_NewFrame`）：デバイスオブジェクト確認
4. 描画データのレンダリング（`ImGui_ImplWGPU_RenderDrawData`）：RenderPassEncoderへの描画記録
5. テクスチャ更新（`ImGui_ImplWGPU_UpdateTexture`）：WGPUTexture作成・更新・破棄
6. バックエンドの終了処理（`ImGui_ImplWGPU_Shutdown`）：リソース解放

**関連システム・外部連携**：
- プラットフォームバックエンド（GLFW、SDL2、SDL3）と組み合わせて使用
- WebGPU実装（Dawn / wgpu-native / Emscripten）

**権限による制御**：
特になし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面 | 主画面 | すべてのDear ImGuiウィジェットの描画出力先 |

## 機能種別

レンダリングバックエンド / グラフィックスAPI抽象化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|-----------------|
| init_info | ImGui_ImplWGPU_InitInfo* | Yes | 初期化設定構造体 | Device必須 |
| draw_data | ImDrawData* | Yes | 描画コマンドリスト | DisplaySize > 0 |
| pass_encoder | WGPURenderPassEncoder | Yes | レンダーパスエンコーダ | nullptr以外 |

### ImGui_ImplWGPU_InitInfo構造体

| フィールド名 | 型 | 必須 | 説明 | デフォルト |
|-------------|-----|-----|------|---------|
| Device | WGPUDevice | Yes | WebGPUデバイス | nullptr |
| NumFramesInFlight | int | No | フライト中のフレーム数 | 3 |
| RenderTargetFormat | WGPUTextureFormat | Yes | レンダーターゲット形式 | Undefined |
| DepthStencilFormat | WGPUTextureFormat | No | デプスステンシル形式 | Undefined |
| PipelineMultisampleState | WGPUMultisampleState | No | マルチサンプル設定 | count=1 |

### 入力データソース

- ImGui_ImplWGPU_InitInfo構造体
- ImDrawData構造体
- ImTextureData構造体

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 初期化結果 | bool | Init関数の成功/失敗 |
| テクスチャID | WGPUTextureView | テクスチャビュー |
| RenderPassEncoder出力 | WebGPUコマンド | レンダーパスエンコーダへの描画コマンド記録 |

### 出力先

- WGPURenderPassEncoder
- io.BackendRendererUserData
- platform_io.Renderer_RenderState（コールバック用）

## 処理フロー

### 処理シーケンス

```
1. ImGui_ImplWGPU_Init(init_info)
   ├─ InitInfo構造体のコピー
   ├─ wgpuDeviceGetQueue
   └─ フレームリソース配列の初期化

2. ImGui_ImplWGPU_CreateDeviceObjects()
   ├─ ImGui_ImplWGPU_CreateShaderModule（WGSL）
   ├─ wgpuDeviceCreateSampler
   ├─ wgpuDeviceCreateBuffer（Uniforms）
   ├─ wgpuDeviceCreateBindGroupLayout
   ├─ wgpuDeviceCreateBindGroup（CommonBindGroup）
   ├─ wgpuDeviceCreatePipelineLayout
   └─ wgpuDeviceCreateRenderPipeline

3. [毎フレーム] ImGui_ImplWGPU_NewFrame()
   └─ パイプライン未作成なら CreateDeviceObjects()

4. [毎フレーム] ImGui_ImplWGPU_RenderDrawData(draw_data, pass_encoder)
   ├─ テクスチャ更新
   ├─ VB/IB作成・拡張
   ├─ wgpuQueueWriteBuffer（データアップロード）
   ├─ SetupRenderState
   │      ├─ wgpuQueueWriteBuffer（Uniforms：MVP/Gamma）
   │      ├─ wgpuRenderPassEncoderSetViewport
   │      ├─ wgpuRenderPassEncoderSetVertexBuffer
   │      ├─ wgpuRenderPassEncoderSetIndexBuffer
   │      ├─ wgpuRenderPassEncoderSetPipeline
   │      └─ wgpuRenderPassEncoderSetBindGroup
   └─ 描画コマンド実行
          ├─ wgpuRenderPassEncoderSetScissorRect
          ├─ ImGui_ImplWGPU_CreateImageBindGroup
          └─ wgpuRenderPassEncoderDrawIndexed

5. ImGui_ImplWGPU_Shutdown()
   └─ InvalidateDeviceObjects
```

### フローチャート

```mermaid
flowchart TD
    A[Init] --> B[NewFrame]
    B --> C{Pipeline作成済み?}
    C -->|No| D[CreateDeviceObjects]
    C -->|Yes| E[RenderDrawData]
    D --> E
    E --> F[Update Textures]
    F --> G[Create/Resize VB/IB]
    G --> H[WriteBuffer]
    H --> I[SetupRenderState]
    I --> J[SetViewport]
    J --> K[SetVertexBuffer/IndexBuffer]
    K --> L[SetPipeline]
    L --> M[For each DrawList/DrawCmd]
    M --> N[SetScissorRect]
    N --> O[CreateImageBindGroup]
    O --> P[SetBindGroup]
    P --> Q[DrawIndexed]
    Q --> R[Shutdown]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | シェーダー形式 | WGSL（WebGPU Shading Language） | シェーダーモジュール作成時 |
| BR-002 | テクスチャ形式 | WGPUTextureFormat_RGBA8Unorm | テクスチャ作成時 |
| BR-003 | 大規模メッシュ対応 | 64K頂点以上サポート | wgpuRenderPassEncoderDrawIndexedのVtxOffset使用 |
| BR-004 | フレームリソース | NumFramesInFlight分のVB/IBを保持 | マルチバッファリング |
| BR-005 | ガンマ補正 | sRGBフォーマット時gamma=2.2、それ以外gamma=1.0 | フラグメントシェーダー |
| BR-006 | バックエンド選択 | IMGUI_IMPL_WEBGPU_BACKEND_DAWN or IMGUI_IMPL_WEBGPU_BACKEND_WGPU | コンパイル時 |

### 計算ロジック

**正射影行列**（行311-317）:
```cpp
float mvp[4][4] = {
    { 2.0f/(R-L),   0.0f,           0.0f,       0.0f },
    { 0.0f,         2.0f/(T-B),     0.0f,       0.0f },
    { 0.0f,         0.0f,           0.5f,       0.0f },
    { (R+L)/(L-R),  (T+B)/(B-T),    0.5f,       1.0f },
};
```

**ガンマ補正（WGSLシェーダー）**:
```wgsl
let corrected_color = pow(color.rgb, vec3<f32>(uniforms.gamma));
```

## データベース操作仕様

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| IM_ASSERT | 初期化エラー | 二重初期化 | 初期化状態確認 |
| IM_ASSERT | コンパイルエラー | 両方のバックエンドが定義/未定義 | 片方のみ定義 |

### リトライ仕様

リトライなし

## トランザクション仕様

該当なし

## パフォーマンス要件

- wgpuQueueWriteBufferによるバッファ更新
- ImageBindGroupのキャッシュ（ImGuiStorage使用）
- フレームリソースの再利用（NumFramesInFlight分）

## セキュリティ考慮事項

- デバイスポインタの検証

## 備考

- IMGUI_IMPL_WEBGPU_BACKEND_DAWNまたはIMGUI_IMPL_WEBGPU_BACKEND_WGPUの定義が必須
- Emscripten 4.0.10+ではデフォルトでIMGUI_IMPL_WEBGPU_BACKEND_DAWNを使用
- ImGui_ImplWGPU_RenderState構造体でコールバック用状態を公開
- ヘルパー関数群（デバッグ/サーフェス作成）を提供

---

## コードリーディングガイド

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_impl_wgpu.h | `backends/imgui_impl_wgpu.h` | ImGui_ImplWGPU_InitInfo構造体（行58-72）を確認 |
| 1-2 | imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | ImGui_ImplWGPU_Data構造体（行110-123）を確認 |
| 1-3 | imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | ImGui_ImplWGPU_Texture構造体（行79-83）を確認 |
| 1-4 | imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | RenderResources構造体（行85-92）を確認 |
| 1-5 | imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | FrameResources構造体（行94-102）を確認 |

**読解のコツ**: WebGPUではBindGroupを使用してリソースをパイプラインにバインドする。CommonBindGroup（Uniforms/Sampler）とImageBindGroup（テクスチャ）を分離している。

#### Step 2: WGSLシェーダーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | 頂点シェーダー（行136-164）を確認 |
| 2-2 | imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | フラグメントシェーダー（行166-188）を確認 |

**主要処理フロー**:
- **頂点シェーダー**: uniforms.mvpによる頂点変換
- **フラグメントシェーダー**: textureSampleでテクスチャサンプリング、pow(gamma)でガンマ補正

#### Step 3: レンダリング処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | RenderDrawData関数（行368-）を確認 |
| 3-2 | imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | SetupRenderState関数（行300-364）を確認 |

**主要処理フロー**:
- **行318**: wgpuQueueWriteBuffer（MVP行列）
- **行349**: wgpuQueueWriteBuffer（ガンマ値）
- **行353**: wgpuRenderPassEncoderSetViewport
- **行356-357**: wgpuRenderPassEncoderSetVertexBuffer / SetIndexBuffer
- **行358**: wgpuRenderPassEncoderSetPipeline
- **行359**: wgpuRenderPassEncoderSetBindGroup（CommonBindGroup）

### プログラム呼び出し階層図

```
アプリケーション
    │
    ├─ ImGui_ImplWGPU_Init(init_info)
    │      ├─ InitInfo コピー
    │      ├─ wgpuDeviceGetQueue()
    │      └─ pFrameResources 配列初期化
    │
    ├─ [フレームループ]
    │      │
    │      ├─ ImGui_ImplWGPU_NewFrame()
    │      │      └─ ImGui_ImplWGPU_CreateDeviceObjects()
    │      │             ├─ ImGui_ImplWGPU_CreateShaderModule() [WGSL]
    │      │             ├─ wgpuDeviceCreateSampler()
    │      │             ├─ wgpuDeviceCreateBuffer() [Uniforms]
    │      │             ├─ wgpuDeviceCreateBindGroupLayout()
    │      │             ├─ wgpuDeviceCreateBindGroup() [CommonBindGroup]
    │      │             ├─ wgpuDeviceCreatePipelineLayout()
    │      │             └─ wgpuDeviceCreateRenderPipeline()
    │      │
    │      └─ ImGui_ImplWGPU_RenderDrawData()
    │             ├─ ImGui_ImplWGPU_UpdateTexture()
    │             ├─ wgpuDeviceCreateBuffer() [VB/IB]
    │             ├─ wgpuQueueWriteBuffer()
    │             ├─ ImGui_ImplWGPU_SetupRenderState()
    │             │      ├─ wgpuQueueWriteBuffer() [MVP/Gamma]
    │             │      ├─ wgpuRenderPassEncoderSetViewport()
    │             │      ├─ wgpuRenderPassEncoderSetVertexBuffer()
    │             │      ├─ wgpuRenderPassEncoderSetIndexBuffer()
    │             │      ├─ wgpuRenderPassEncoderSetPipeline()
    │             │      └─ wgpuRenderPassEncoderSetBindGroup()
    │             │
    │             ├─ wgpuRenderPassEncoderSetScissorRect()
    │             ├─ ImGui_ImplWGPU_CreateImageBindGroup()
    │             └─ wgpuRenderPassEncoderDrawIndexed()
    │
    └─ ImGui_ImplWGPU_Shutdown()
           └─ ImGui_ImplWGPU_InvalidateDeviceObjects()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_impl_wgpu.h | `backends/imgui_impl_wgpu.h` | ヘッダー | 公開API宣言、InitInfo/RenderState構造体（131行） |
| imgui_impl_wgpu.cpp | `backends/imgui_impl_wgpu.cpp` | ソース | バックエンド実装本体、WGSLシェーダー埋め込み |
| webgpu/webgpu.h | システム | ヘッダー | WebGPU API宣言 |
| webgpu/wgpu.h | オプショナル | ヘッダー | wgpu-native固有の宣言 |
