# 機能設計書 272-imgui_impl_sdlrenderer3

## 概要

本ドキュメントは、Dear ImGuiのSDL3 Rendererバックエンド（imgui_impl_sdlrenderer3）の機能設計について記述する。SDL3 Rendererを使用してDear ImGuiのUI描画をレンダリングするためのバックエンド実装を提供する。

### 本機能の処理概要

SDL3 Rendererを使用してDear ImGuiの描画データをレンダリングする機能を提供する。SDL3はSDL2の後継であり、モダンなAPIデザインと改善されたパフォーマンスを備えている。

**業務上の目的・背景**：SDL3を使用するアプリケーションにおいて、Dear ImGuiのUIを統合するために必要なレンダリングバックエンドを提供する。SDL3の新しいRendererAPIを活用し、SDL3環境でのImGui描画を可能にする。SDL2からの移行やSDL3ベースの新規プロジェクトでの利用を想定している。

**機能の利用シーン**：SDL3ベースのゲーム、ツール、エディタなどのアプリケーションにおいて、デバッグUI、設定画面、開発ツールなどを実装する際に使用される。SDL3への移行を検討しているプロジェクトや、SDL3の新機能を活用したい場合に適している。

**主要な処理内容**：
1. SDL3 Rendererの初期化とバックエンドデータの設定
2. フレームごとの状態更新（NewFrame）
3. テクスチャの作成・更新・破棄（動的フォントアトラス対応）
4. 描画データのレンダリング（8ビットカラーからフロートカラーへの変換を含む）
5. SDL3 Renderer状態のバックアップと復元

**関連システム・外部連携**：SDL3ライブラリ（バージョン3.1.8以上推奨、3.0.0以上必須）と連携。

**権限による制御**：特になし。アプリケーションレベルで制御。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | SDL3 Rendererを使用するすべてのImGuiウィンドウのレンダリング |

## 機能種別

レンダリング処理 / バックエンド実装

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| renderer | SDL_Renderer* | Yes | SDL3 Rendererインスタンス | nullptr不可 |
| draw_data | ImDrawData* | Yes | ImGuiの描画データ | RenderDrawData呼び出し時に必要 |
| tex | ImTextureData* | No | テクスチャ更新データ | UpdateTexture呼び出し時に使用 |

### 入力データソース

- ImGui::Render()によって生成されるImDrawData
- ImGui::GetPlatformIO().Textures[]のテクスチャ更新リスト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 描画結果 | SDL_Renderer出力 | レンダリングされたImGui UI |
| SDL_Texture* | ImTextureID | 作成されたテクスチャのID |

### 出力先

SDL3 Rendererのレンダーターゲット（通常はウィンドウサーフェス）

## 処理フロー

### 処理シーケンス

```
1. Init: バックエンド初期化
   └─ ImGuiIO設定、バックエンドデータ作成
2. NewFrame: フレーム開始
   └─ 特別な処理なし（状態確認のみ）
3. Render時:
   a. テクスチャ更新チェック
      └─ WantCreate/WantUpdates/WantDestroyに応じて処理
   b. SDL_Renderer状態のバックアップ
   c. 描画コマンドリストの処理
      └─ クリッピング矩形の設定
      └─ 8ビットカラー→フロートカラー変換
      └─ テクスチャバインディング
      └─ SDL_RenderGeometryRaw()での描画
   d. SDL_Renderer状態の復元
4. Shutdown: クリーンアップ
   └─ テクスチャ破棄、メモリ解放
```

### フローチャート

```mermaid
flowchart TD
    A[ImGui_ImplSDLRenderer3_Init] --> B[NewFrame]
    B --> C[ImGui::Render]
    C --> D[ImGui_ImplSDLRenderer3_RenderDrawData]
    D --> E{テクスチャ更新あり?}
    E -->|Yes| F[UpdateTexture]
    E -->|No| G[SDL状態バックアップ]
    F --> G
    G --> H[描画コマンド処理ループ]
    H --> I{UserCallback?}
    I -->|Yes| J[コールバック実行]
    I -->|No| K[クリップ矩形設定]
    J --> H
    K --> L[8bit→float カラー変換]
    L --> M[SDL_RenderGeometryRaw]
    M --> H
    H --> N[SDL状態復元]
    N --> O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-272-01 | テクスチャフォーマット | RGBA32フォーマットのみサポート | テクスチャ作成時 |
| BR-272-02 | 大規模メッシュ対応 | VtxOffsetを使用して64k+頂点をサポート | 常に適用 |
| BR-272-03 | カラー変換 | 8ビットSDL_Colorを浮動小数点SDL_FColorに変換 | 描画時 |
| BR-272-04 | スケール処理 | SDL_GetRenderScaleの値に応じてスケール調整 | 描画時 |

### 計算ロジック

- カラー変換: `color_float = color_8bit / 255.0f`
- クリッピング矩形計算: `clip_min/max = (pcmd->ClipRect - clip_off) * clip_scale`
- フレームバッファサイズ: `fb_width/height = DisplaySize * render_scale`

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | renderer == nullptr | 初期化時にnullチェック |
| - | アサーション | 二重初期化 | BackendRendererUserData確認 |
| - | アサーション | テクスチャ作成失敗 | SDL_CreateTexture失敗時 |

### リトライ仕様

リトライ処理なし。エラー時はアサーションで停止。

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

該当なし（グラフィックスAPI操作のため）

## パフォーマンス要件

- SDL_RenderGeometryRaw()による効率的なバッチ描画
- ColorBufferを再利用してカラー変換のメモリ割り当てを最小化
- テクスチャは必要に応じて部分更新（UpdateRect使用）
- 最小化時は描画スキップ

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

- ユーザー提供のテクスチャポインタは直接SDL_Textureとして使用
- メモリ安全性はSDL3ライブラリに依存

## 備考

- SDL3ではSDL_RenderGeometryRaw()のuint32カラーバージョンが削除されたため、8ビットカラーからフロートカラーへの変換が必要
- SDL_Rendererは高度なグラフィックスには限定的。SDL3+SDL_GPUの使用を推奨
- バージョン要件: SDL 3.0.0以上

---

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

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_impl_sdlrenderer3.h | `backends/imgui_impl_sdlrenderer3.h` | 公開API、RenderState構造体 |
| 1-2 | imgui_impl_sdlrenderer3.cpp | `backends/imgui_impl_sdlrenderer3.cpp` | ImGui_ImplSDLRenderer3_Data構造体（56-62行目） |

**読解のコツ**: ImGui_ImplSDLRenderer3_DataにはColorBufferが追加されており、これが8bit→floatカラー変換に使用される。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_impl_sdlrenderer3.cpp | `backends/imgui_impl_sdlrenderer3.cpp` | Init関数（72-89行目）、Shutdown関数（91-105行目） |

**主要処理フロー**:
1. **72-89行目**: Init - バックエンドフラグ設定、データ構造初期化
2. **91-105行目**: Shutdown - リソース解放、ハンドラクリア

#### Step 3: カラー変換ヘルパーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_impl_sdlrenderer3.cpp | `backends/imgui_impl_sdlrenderer3.cpp` | SDL_RenderGeometryRaw8BitColor関数（123-138行目） |

**主要処理フロー**:
- **126行目**: ColorBuffer配列のリサイズ
- **128-136行目**: 8ビットカラーをフロートカラーに変換するループ
- **137行目**: SDL_RenderGeometryRaw呼び出し

#### Step 4: テクスチャ管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_impl_sdlrenderer3.cpp | `backends/imgui_impl_sdlrenderer3.cpp` | UpdateTexture関数（249-293行目） |

**主要処理フロー**:
- **253-271行目**: WantCreate - SDL_CreateTexture、SDL_UpdateTexture、ブレンドモード設定
- **272-283行目**: WantUpdates - 部分更新処理
- **284-292行目**: WantDestroy - テクスチャ破棄

#### Step 5: 描画処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | imgui_impl_sdlrenderer3.cpp | `backends/imgui_impl_sdlrenderer3.cpp` | RenderDrawData関数（140-247行目） |

**主要処理フロー**:
- **147-158行目**: スケール計算、最小化チェック
- **162-165行目**: テクスチャ更新処理
- **167-179行目**: SDL_Renderer状態バックアップ
- **194-241行目**: 描画コマンドループ（クリッピング、カラー変換、ジオメトリ描画）
- **244-246行目**: 状態復元

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

```
ImGui_ImplSDLRenderer3_Init
    └─ IM_NEW(ImGui_ImplSDLRenderer3_Data)

ImGui_ImplSDLRenderer3_RenderDrawData
    ├─ ImGui_ImplSDLRenderer3_UpdateTexture (必要時)
    │      ├─ SDL_CreateTexture
    │      ├─ SDL_UpdateTexture
    │      └─ SDL_DestroyTexture
    ├─ ImGui_ImplSDLRenderer3_SetupRenderState
    │      ├─ SDL_SetRenderViewport
    │      └─ SDL_SetRenderClipRect
    └─ SDL_RenderGeometryRaw8BitColor (各コマンド)
           └─ SDL_RenderGeometryRaw

ImGui_ImplSDLRenderer3_Shutdown
    ├─ ImGui_ImplSDLRenderer3_DestroyDeviceObjects
    │      └─ ImGui_ImplSDLRenderer3_UpdateTexture (Destroy)
    └─ IM_DELETE(bd)
```

### データフロー図

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

ImDrawData ───────────▶ RenderDrawData ───────────▶ SDL_Renderer
  │                         │                           │
  ├─ CmdLists[]             ├─ クリップ矩形変換          ├─ 描画結果
  ├─ VtxBuffer              ├─ 8bit→float変換          │
  │    └─ col (8bit)        │    └─ ColorBuffer        │
  └─ IdxBuffer              └─ SDL_RenderGeometryRaw    │
                                                        │
ImTextureData ─────────▶ UpdateTexture ────────────▶ SDL_Texture*
  │                         │
  ├─ Pixels                 ├─ SDL_CreateTexture
  └─ Status                 └─ SDL_UpdateTexture
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_impl_sdlrenderer3.h | `backends/imgui_impl_sdlrenderer3.h` | ヘッダー | 公開APIの宣言 |
| imgui_impl_sdlrenderer3.cpp | `backends/imgui_impl_sdlrenderer3.cpp` | ソース | バックエンド実装 |
| imgui.h | `imgui.h` | ヘッダー | ImGui コアAPI |
| SDL3/SDL.h | (外部ライブラリ) | ヘッダー | SDL3 API |
