# 機能設計書 271-imgui_impl_sdlrenderer2

## 概要

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

### 本機能の処理概要

SDL2 Rendererを使用してDear ImGuiの描画データをレンダリングする機能を提供する。SDL2はクロスプラットフォームのマルチメディアライブラリであり、そのRendererコンポーネントを介して2D描画を行う。

**業務上の目的・背景**：SDL2を使用するアプリケーションにおいて、Dear ImGuiのUIを統合するために必要なレンダリングバックエンドを提供する。SDL_RenderGeometry()関数を活用し、頂点データを直接GPUに送信することで効率的なUI描画を実現する。特に、プロトタイプ開発やシンプルな2Dアプリケーションにおいて、複雑なグラフィックスAPIを直接扱うことなくImGuiを導入できる。

**機能の利用シーン**：SDL2ベースのゲーム、ツール、エディタなどのアプリケーションにおいて、デバッグUI、設定画面、開発ツールなどを実装する際に使用される。特にSDL2のRendererを既に使用しているプロジェクトでImGuiを追加する場合に最適。

**主要な処理内容**：
1. SDL_Rendererの初期化とバックエンドデータの設定
2. フレームごとの状態更新（NewFrame）
3. テクスチャの作成・更新・破棄（動的フォントアトラス対応）
4. 描画データのレンダリング（クリッピング、テクスチャバインディング、ジオメトリ描画）
5. SDL_Renderer状態のバックアップと復元

**関連システム・外部連携**：SDL2ライブラリ（バージョン2.0.17以上必須）と連携。SDL_RenderGeometryRaw()関数を使用するため、このバージョン以上が必要。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| renderer | SDL_Renderer* | Yes | SDL2 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 |

### 出力先

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

## 処理フロー

### 処理シーケンス

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

### フローチャート

```mermaid
flowchart TD
    A[ImGui_ImplSDLRenderer2_Init] --> B[NewFrame]
    B --> C[ImGui::Render]
    C --> D[ImGui_ImplSDLRenderer2_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[SDL_RenderGeometryRaw]
    L --> H
    H --> M[SDL状態復元]
    M --> N[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-271-01 | テクスチャフォーマット | RGBA32フォーマットのみサポート | テクスチャ作成時 |
| BR-271-02 | 大規模メッシュ対応 | VtxOffsetを使用して64k+頂点をサポート | 常に適用 |
| BR-271-03 | スケール処理 | SDL_RenderGetScaleの値に応じてスケール調整 | 描画時 |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- SDL_RenderGeometryRaw()による効率的なバッチ描画
- テクスチャは必要に応じて部分更新（UpdateRect使用）
- 最小化時は描画スキップ

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

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

## 備考

- SDL_Rendererは現在では機能が限定的とされており、高度なグラフィックスが必要な場合はSDL3+SDL_GPUまたは専用レンダラー（OpenGL、Vulkan等）の使用が推奨される
- バージョン要件: SDL 2.0.17以上（SDL_RenderGeometry()が必要）

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: ImGui_ImplSDLRenderer2_Dataはバックエンドの内部状態を保持し、io.BackendRendererUserDataに格納される。

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

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

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_impl_sdlrenderer2.cpp | `backends/imgui_impl_sdlrenderer2.cpp` | UpdateTexture関数（233-277行目） |

**主要処理フロー**:
- **237-255行目**: WantCreate - SDL_CreateTexture、SDL_UpdateTexture、ブレンドモード設定
- **256-267行目**: WantUpdates - 部分更新処理
- **268-276行目**: WantDestroy - テクスチャ破棄

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_impl_sdlrenderer2.cpp | `backends/imgui_impl_sdlrenderer2.cpp` | RenderDrawData関数（124-231行目） |

**主要処理フロー**:
- **129-140行目**: スケール計算、最小化チェック
- **144-147行目**: テクスチャ更新処理
- **149-159行目**: SDL_Renderer状態バックアップ
- **174-225行目**: 描画コマンドループ（クリッピング、ジオメトリ描画）
- **228-230行目**: 状態復元

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

```
ImGui_ImplSDLRenderer2_Init
    └─ IM_NEW(ImGui_ImplSDLRenderer2_Data)

ImGui_ImplSDLRenderer2_RenderDrawData
    ├─ ImGui_ImplSDLRenderer2_UpdateTexture (必要時)
    │      ├─ SDL_CreateTexture
    │      ├─ SDL_UpdateTexture
    │      └─ SDL_DestroyTexture
    ├─ ImGui_ImplSDLRenderer2_SetupRenderState
    │      ├─ SDL_RenderSetViewport
    │      └─ SDL_RenderSetClipRect
    └─ SDL_RenderGeometryRaw (各コマンド)

ImGui_ImplSDLRenderer2_Shutdown
    ├─ ImGui_ImplSDLRenderer2_DestroyDeviceObjects
    │      └─ ImGui_ImplSDLRenderer2_UpdateTexture (Destroy)
    └─ IM_DELETE(bd)
```

### データフロー図

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

ImDrawData ───────────▶ RenderDrawData ───────────▶ SDL_Renderer
  │                         │                           │
  ├─ CmdLists[]             ├─ クリップ矩形変換          ├─ 描画結果
  ├─ VtxBuffer              ├─ 頂点データ取得            │
  └─ IdxBuffer              └─ SDL_RenderGeometryRaw    │
                                                        │
ImTextureData ─────────▶ UpdateTexture ────────────▶ SDL_Texture*
  │                         │
  ├─ Pixels                 ├─ SDL_CreateTexture
  └─ Status                 └─ SDL_UpdateTexture
```

### 関連ファイル一覧

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