# 機能設計書 265-imgui_impl_dx11

## 概要

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

### 本機能の処理概要

DirectX11レンダラーバックエンドは、Dear ImGuiのUI描画コマンドをDirectX11のシェーダーベースAPIに変換し、画面にUIを描画する機能を提供する。Shader Model 4.0を使用し、ID3D11DeviceとID3D11DeviceContextを通じてレンダリングを行う。

**業務上の目的・背景**：
DirectX11を使用するWindowsアプリケーションにDear ImGuiを統合する必要がある場合に本バックエンドを使用する。DirectX11はWindows 7以降でサポートされ、DirectX10の改良版として、デバイスコンテキスト分離によるマルチスレッドレンダリング対応を特徴とする。

**機能の利用シーン**：
- DirectX11アプリケーションへのImGuiデバッグUI追加
- Windows 7/8/10/11環境でのDirectX11使用アプリケーション
- マルチスレッドレンダリング環境でのUI統合

**主要な処理内容**：
1. バックエンドの初期化（`ImGui_ImplDX11_Init`）：デバイス・デバイスコンテキスト取得、DXGIファクトリ取得
2. デバイスオブジェクト作成（`ImGui_ImplDX11_CreateDeviceObjects`）：シェーダーコンパイル（vs_4_0/ps_4_0）
3. フレーム開始処理（`ImGui_ImplDX11_NewFrame`）：デバイスオブジェクト確認
4. 描画データのレンダリング（`ImGui_ImplDX11_RenderDrawData`）：VB/IB更新、描画実行
5. テクスチャ更新（`ImGui_ImplDX11_UpdateTexture`）：テクスチャ/SRV作成・更新・破棄
6. バックエンドの終了処理（`ImGui_ImplDX11_Shutdown`）：リソース解放

**関連システム・外部連携**：
- プラットフォームバックエンド（Win32）と組み合わせて使用
- DirectX11ランタイム、D3DCompiler

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|-----------------|
| device | ID3D11Device* | Yes | Direct3D11デバイス | nullptr以外 |
| device_context | ID3D11DeviceContext* | Yes | Direct3D11デバイスコンテキスト | nullptr以外 |
| draw_data | ImDrawData* | Yes | 描画コマンドリスト | DisplaySize > 0 |
| tex | ImTextureData* | Yes | テクスチャデータ | Status確認必須 |

### 入力データソース

- ID3D11Deviceインスタンス
- ID3D11DeviceContextインスタンス
- ImDrawData構造体
- ImTextureData構造体

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 初期化結果 | bool | Init関数の成功/失敗 |
| テクスチャID | ID3D11ShaderResourceView* | SRVとして使用 |
| 画面出力 | Direct3D11描画 | バックバッファへのUI描画結果 |

### 出力先

- Direct3D11バックバッファ
- io.BackendRendererUserData
- platform_io.Renderer_RenderState（コールバック用）

## 処理フロー

### 処理シーケンス

```
1. ImGui_ImplDX11_Init(device, device_context)
   ├─ DXGIファクトリ取得（QueryInterface経由）
   ├─ デバイス参照カウント増加
   └─ デバイスコンテキスト参照カウント増加

2. ImGui_ImplDX11_CreateDeviceObjects()
   ├─ D3DCompileでシェーダーコンパイル（vs_4_0, ps_4_0）
   ├─ CreateVertexShader / CreatePixelShader
   ├─ CreateInputLayout
   ├─ CreateBuffer（定数バッファ）
   ├─ CreateBlendState
   ├─ CreateRasterizerState
   ├─ CreateDepthStencilState
   └─ CreateSamplerState（Linear/Nearest）

3. [毎フレーム] ImGui_ImplDX11_NewFrame()
   └─ シェーダー未作成なら CreateDeviceObjects()

4. [毎フレーム] ImGui_ImplDX11_RenderDrawData(draw_data)
   ├─ テクスチャ更新
   ├─ VB/IB作成・拡張
   ├─ VB/IB Map/Unmap（データアップロード）
   ├─ DX11状態のバックアップ（BACKUP_DX11_STATE）
   ├─ SetupRenderState
   ├─ RenderState設定（コールバック用）
   ├─ 描画コマンド実行（DrawIndexed）
   └─ DX11状態の復元

5. ImGui_ImplDX11_Shutdown()
   └─ InvalidateDeviceObjects
```

### フローチャート

```mermaid
flowchart TD
    A[Init] --> B[NewFrame]
    B --> C{Shader作成済み?}
    C -->|No| D[CreateDeviceObjects]
    C -->|Yes| E[RenderDrawData]
    D --> E
    E --> F[Update Textures]
    F --> G[Create/Map VB/IB]
    G --> H[Backup DX11 State]
    H --> I[SetupRenderState]
    I --> J[Set RenderState for Callbacks]
    J --> K[For each DrawList/DrawCmd]
    K --> L[RSSetScissorRects]
    L --> M[PSSetShaderResources]
    M --> N[DrawIndexed]
    N --> O[Restore DX11 State]
    O --> P[Shutdown]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | シェーダーモデル | Shader Model 4.0（vs_4_0/ps_4_0） | シェーダーコンパイル時 |
| BR-002 | テクスチャ形式 | DXGI_FORMAT_R8G8B8A8_UNORM | テクスチャ作成時 |
| BR-003 | 大規模メッシュ対応 | 64K頂点以上サポート | DrawIndexedのVtxOffset使用 |
| BR-004 | サンプラー種別 | Linear/Nearest両対応 | テクスチャサンプリング時 |

### 計算ロジック

**正射影行列**（行128-134）:
```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 },
};
```

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| IM_ASSERT | 初期化エラー | 二重初期化 | 初期化状態確認 |
| FAILED(hr) | シェーダーコンパイル失敗 | D3DCompile失敗 | return false |
| < 0 | バッファ作成失敗 | CreateBuffer失敗 | return |
| != S_OK | Map失敗 | VB/IB Map失敗 | return |

### リトライ仕様

リトライなし

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

該当なし

## パフォーマンス要件

- D3D11_USAGE_DYNAMIC使用によるMap/Unmapアクセス
- 状態のバックアップ・復元（BACKUP_DX11_STATE構造体）
- デバイスコンテキスト分離によるマルチスレッド対応準備

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

- デバイスポインタの検証
- デバイスコンテキストポインタの検証

## 備考

- d3dcompiler.libと自動リンク（#pragma comment）
- ImGui_ImplDX11_RenderState構造体でコールバック用状態を公開
- SamplerLinearとSamplerNearest両方を提供

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | ImGui_ImplDX11_Data構造体（行70-90）を確認 |
| 1-2 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | ImGui_ImplDX11_Texture構造体（行64-68）を確認 |
| 1-3 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | VERTEX_CONSTANT_BUFFER_DX11構造体（行92-95）を確認 |

**読解のコツ**: DX11ではデバイスとデバイスコンテキストが分離しているため、ImGui_ImplDX11_Dataで両方を保持する。

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_impl_dx11.h | `backends/imgui_impl_dx11.h` | 公開API宣言（行28-38）を確認 |
| 2-2 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | Init関数（行617-652）を確認 |

**主要処理フロー**:
- **行627-628**: ImGuiBackendFlags設定（RendererHasVtxOffset, RendererHasTextures）
- **行631**: D3D11_REQ_TEXTURE2D_U_OR_V_DIMENSIONを最大サイズに設定
- **行638-645**: QueryInterface経由でDXGIFactory取得
- **行648-649**: デバイス・デバイスコンテキスト参照カウント増加

#### Step 3: シェーダー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | CreateDeviceObjects関数（行424-591）を確認 |
| 3-2 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | 頂点シェーダーソース（行439-465）を確認 |
| 3-3 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | ピクセルシェーダーソース（行504-518）を確認 |

**主要処理フロー**:
- **行468**: D3DCompile with "vs_4_0"
- **行470**: CreateVertexShader
- **行477-482**: InputLayout作成
- **行521**: D3DCompile with "ps_4_0"
- **行523**: CreatePixelShader
- **行532-545**: CreateBlendState
- **行548-556**: CreateRasterizerState
- **行559-570**: CreateDepthStencilState
- **行574-588**: CreateSamplerState（Linear/Nearest）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | RenderDrawData関数（行163-343）を確認 |
| 4-2 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | SetupRenderState関数（行105-160）を確認 |

**主要処理フロー**:
- **行179-204**: VB/IB作成・拡張
- **行206-222**: Map/Unmap（D3D11_MAP_WRITE_DISCARD）
- **行225-248**: BACKUP_DX11_STATE構造体による状態バックアップ
- **行272-280**: RenderState構造体設定（コールバック用）
- **行317**: DrawIndexed
- **行326-342**: 状態復元

#### Step 5: テクスチャ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | UpdateTexture関数（行361-422）を確認 |
| 5-2 | imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | DestroyTexture関数（行345-359）を確認 |

**主要処理フロー**:
- **行374-389**: CreateTexture2D（D3D11_USAGE_DEFAULT）
- **行393-399**: CreateShaderResourceView
- **行416**: UpdateSubresource（部分更新）

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

```
アプリケーション
    │
    ├─ ImGui_ImplDX11_Init(device, device_context)
    │      ├─ QueryInterface(IDXGIDevice)
    │      ├─ GetParent(IDXGIAdapter)
    │      ├─ GetParent(IDXGIFactory)
    │      ├─ device->AddRef()
    │      └─ device_context->AddRef()
    │
    ├─ [フレームループ]
    │      │
    │      ├─ ImGui_ImplDX11_NewFrame()
    │      │      └─ ImGui_ImplDX11_CreateDeviceObjects()
    │      │             ├─ D3DCompile() [vs_4_0, ps_4_0]
    │      │             ├─ CreateVertexShader()
    │      │             ├─ CreatePixelShader()
    │      │             ├─ CreateInputLayout()
    │      │             ├─ CreateBuffer() [定数バッファ]
    │      │             ├─ CreateBlendState()
    │      │             ├─ CreateRasterizerState()
    │      │             ├─ CreateDepthStencilState()
    │      │             └─ CreateSamplerState() [Linear/Nearest]
    │      │
    │      └─ ImGui_ImplDX11_RenderDrawData()
    │             ├─ ImGui_ImplDX11_UpdateTexture()
    │             │      ├─ CreateTexture2D()
    │             │      ├─ CreateShaderResourceView()
    │             │      └─ UpdateSubresource()
    │             ├─ device_ctx->Map() / Unmap()
    │             ├─ ImGui_ImplDX11_SetupRenderState()
    │             │      ├─ RSSetViewports()
    │             │      ├─ Map() [定数バッファ]
    │             │      ├─ IASetInputLayout()
    │             │      ├─ IASetVertexBuffers()
    │             │      ├─ IASetIndexBuffer()
    │             │      ├─ VSSetShader()
    │             │      ├─ PSSetShader()
    │             │      ├─ PSSetSamplers()
    │             │      ├─ OMSetBlendState()
    │             │      ├─ OMSetDepthStencilState()
    │             │      └─ RSSetState()
    │             ├─ DrawIndexed()
    │             └─ [状態復元]
    │
    └─ ImGui_ImplDX11_Shutdown()
           ├─ ImGui_ImplDX11_InvalidateDeviceObjects()
           ├─ pFactory->Release()
           ├─ pd3dDevice->Release()
           └─ pd3dDeviceContext->Release()
```

### データフロー図

```
[入力]                    [処理]                         [出力]

ID3D11Device ─────────▶ Init() ─────────────────────▶ バックエンドデータ
ID3D11DeviceContext       ├─ QueryInterface()           └─ pFactory取得
                          └─ AddRef()

ImDrawData ───────────▶ RenderDrawData() ─────────▶ Direct3D11描画
  ├─ DisplaySize           ├─ CreateBuffer()             └─ バックバッファ
  ├─ FramebufferScale      ├─ Map/Unmap
  ├─ CmdLists[]            ├─ BACKUP_DX11_STATE
  │   ├─ VtxBuffer         ├─ SetupRenderState()
  │   └─ IdxBuffer         └─ DrawIndexed()
  │
  └─ Textures[] ──────────▶ UpdateTexture() ──────────▶ ID3D11ShaderResourceView
       └─ ImTextureData       ├─ CreateTexture2D()
                              ├─ CreateShaderResourceView()
                              └─ UpdateSubresource()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_impl_dx11.h | `backends/imgui_impl_dx11.h` | ヘッダー | 公開API宣言、RenderState構造体（53行） |
| imgui_impl_dx11.cpp | `backends/imgui_impl_dx11.cpp` | ソース | バックエンド実装本体（686行） |
| d3d11.h | システム | ヘッダー | DirectX11 API宣言 |
| d3dcompiler.h | システム | ヘッダー | シェーダーコンパイラ |
