# 機能設計書 100-Image

## 概要

本ドキュメントはImGuiのImage機能について、その処理内容、入出力仕様、実装詳細を記述した機能設計書である。

### 本機能の処理概要

Imageは、テクスチャ画像を表示するためのUI機能である。GPU上のテクスチャへの参照（ImTextureRef）を受け取り、指定されたサイズで画像を描画する。UV座標を指定することで、テクスチャの一部のみを表示することも可能。バージョン1.92以降ではImTextureRef型が導入され、より柔軟なテクスチャ管理が可能になった。

**業務上の目的・背景**：GUIアプリケーションにおいて、画像の表示は不可欠な機能である。アイコン、サムネイル、プレビュー、バナー、ロゴ、グラフィカルな装飾など、様々な用途で画像表示が必要とされる。Imageウィジェットは、グラフィックスAPIに依存しない統一されたインターフェースで画像表示を実現する。

**機能の利用シーン**：アイコン表示、画像プレビュー、サムネイル一覧、テクスチャアトラスからのスプライト表示、フォントアトラスの確認、カスタムUIグラフィックスなどで使用される。

**主要な処理内容**：
1. 画像のサイズを計算する（指定サイズ + ボーダーパディング）
2. バウンディングボックスを確定し、領域を確保する
3. 背景色がある場合は背景を描画する
4. 画像を描画する（丸角対応）
5. ボーダーがある場合はボーダーを描画する

**関連システム・外部連携**：ImGuiのDrawList描画システム、各種グラフィックスバックエンド（OpenGL、DirectX、Vulkan等）と連携。ImTextureRef/ImTextureIDによるテクスチャ参照管理。

**権限による制御**：特になし（読み取り専用表示ウィジェット）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | Font Atlas | 補助機能 | フォントアトラステクスチャの表示 |
| 22 | Assets Browser | 補助機能 | アセットのサムネイル表示 |

## 機能種別

UIウィジェット / 画像表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| tex_ref | ImTextureRef | Yes | テクスチャへの参照 | 有効なテクスチャ参照 |
| image_size | const ImVec2& | Yes | 表示サイズ（ピクセル） | 正の値 |
| uv0 | const ImVec2& | No | UV座標の左上 | デフォルト: (0, 0) |
| uv1 | const ImVec2& | No | UV座標の右下 | デフォルト: (1, 1) |

### 入力データソース

- 呼び出し元からの直接指定
- グラフィックスバックエンドから取得したテクスチャID/参照
- ImGuiStyleからのスタイル設定値（ImageBorderSize、ImageRounding）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし |

### 出力先

- ImDrawList（現在のウィンドウの描画リスト）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウの取得とスキップチェック
   └─ GetCurrentWindow()で現在のウィンドウを取得
   └─ SkipItemsがtrueの場合はreturn

2. サイズ計算
   └─ padding = ImageBorderSize
   └─ 全体サイズ = image_size + padding * 2

3. アイテム登録
   └─ ItemSize()でレイアウト領域を確保
   └─ ItemAdd()で描画リストに追加

4. 描画
   └─ ImageWithBg内部関数を呼び出し
   └─ 背景色がある場合はAddRectFilledで背景を描画
   └─ ImageRounding > 0の場合: AddImageRoundedで角丸画像を描画
   └─ ImageRounding == 0の場合: AddImageで画像を描画
   └─ ImageBorderSize > 0の場合: AddRectでボーダーを描画
```

### フローチャート

```mermaid
flowchart TD
    A[開始: Image] --> B[ImageWithBg呼び出し]
    B --> C{SkipItems?}
    C -->|Yes| D[return]
    C -->|No| E[サイズ計算<br/>image_size + padding*2]
    E --> F[ItemSize/ItemAdd]
    F --> G{ItemAdd成功?}
    G -->|No| D
    G -->|Yes| H{bg_col.w > 0?}
    H -->|Yes| I[AddRectFilled<br/>背景描画]
    H -->|No| J{ImageRounding > 0?}
    I --> J
    J -->|Yes| K[AddImageRounded<br/>角丸画像描画]
    J -->|No| L[AddImage<br/>画像描画]
    K --> M{ImageBorderSize > 0?}
    L --> M
    M -->|Yes| N[AddRect<br/>ボーダー描画]
    M -->|No| D
    N --> D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-100-01 | ボーダーパディング | 画像の周囲にImageBorderSizeのパディングを追加 | 常時 |
| BR-100-02 | 角丸対応 | ImageRounding > 0の場合、角丸で画像を描画 | ImageRounding > 0 |
| BR-100-03 | UV座標 | uv0/uv1でテクスチャの表示範囲を指定可能 | 常時 |
| BR-100-04 | ボーダー描画 | ImageBorderSize > 0の場合、ImGuiCol_Borderで枠を描画 | ImageBorderSize > 0 |

### 計算ロジック

- 全体サイズ: `image_size + ImVec2(ImageBorderSize, ImageBorderSize) * 2`
- 画像描画領域: `bb.Min + padding` から `bb.Max - padding`

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

データベース操作なし（UI描画のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 早期リターン | window->SkipItems == true | 何もせずreturn |
| - | 早期リターン | ItemAdd失敗 | 何もせずreturn |

### リトライ仕様

リトライ不要（フレームごとに再評価）

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

トランザクション管理なし（即時処理）

## パフォーマンス要件

- 単一フレーム内で多数のImageを描画可能
- 描画はドローコールのバッチ処理により最適化される

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

- テクスチャ参照の有効性は呼び出し元の責任
- 無効なテクスチャ参照は描画時にエラーを引き起こす可能性がある

## 備考

- Image関数は内部でImageWithBgを呼び出すラッパー
- ImageWithBgは背景色とティント色を指定可能
- バージョン1.91.9（2025年2月）でtint_col、border_colパラメータが削除され、スタイル設定に移行
- ImageButtonは別の関数として存在し、クリック可能な画像ボタンを作成

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 652行目: Image関数のAPI宣言を確認 |
| 1-2 | imgui.h | `imgui.h` | ImTextureRef型の定義（テクスチャ参照） |
| 1-3 | imgui.h | `imgui.h` | ImGuiStyleのImageBorderSize、ImageRounding設定 |

**読解のコツ**: ImTextureRef/ImTextureIDは、グラフィックスAPIに依存しないテクスチャ参照の抽象化。各バックエンドでの具体的な型はドキュメント参照。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1132-1135行目: Image関数の実装 |

**主要処理フロー**:
1. **1134行目**: ImageWithBgを呼び出し（内部実装に委譲）

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1107-1130行目: ImageWithBg関数の実装 |

**主要処理フロー**:
- **1114行目**: paddingをImageBorderSizeから取得
- **1115行目**: バウンディングボックス計算
- **1116-1118行目**: ItemSize/ItemAdd
- **1122-1123行目**: 背景色描画（bg_col.w > 0時）
- **1124-1127行目**: 画像描画（角丸対応）
- **1128-1129行目**: ボーダー描画（ImageBorderSize > 0時）

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

```
ImGui::Image(tex_ref, image_size, uv0, uv1)
    │
    └─ ImageWithBg(tex_ref, image_size, uv0, uv1)
           │
           ├─ GetCurrentWindow()
           │
           ├─ g.Style.ImageBorderSize
           │      └─ パディングサイズを取得
           │
           ├─ ItemSize() / ItemAdd()
           │
           ├─ GetColorU32(bg_col) [bg_col.w > 0時]
           │
           ├─ AddRectFilled() [bg_col.w > 0時]
           │      └─ 背景を描画
           │
           ├─ AddImageRounded() [ImageRounding > 0時]
           │      └─ 角丸画像を描画
           │
           ├─ AddImage() [ImageRounding == 0時]
           │      └─ 通常画像を描画
           │
           └─ AddRect() [ImageBorderSize > 0時]
                  └─ ボーダーを描画
```

### データフロー図

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

tex_ref (テクスチャ参照) ──────────────────────────────────> 画像描画パラメータ
                                │
image_size ─────────────────> サイズ計算 ───────────────────> 最終サイズ
                                │
uv0, uv1 ───────────────────────────────────────────────────> テクスチャ座標
                                │
                            ItemSize/ItemAdd
                                │
ImGuiStyle ─────────────────> ImageBorderSize ──────────────> パディング
                            ImageRounding ──────────────────> 角丸半径
                                │
                            AddRectFilled [背景] ───────────> DrawList
                            AddImage[Rounded] ──────────────> DrawList
                            AddRect [ボーダー] ─────────────> DrawList
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | Image APIの宣言、ImTextureRef定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | Image/ImageWithBgの実装 |
| imgui_draw.cpp | `imgui_draw.cpp` | ソース | AddImage、AddImageRounded、AddRectFilled等 |
| backends/imgui_impl_*.cpp | `backends/` | ソース | テクスチャ管理の実装（バックエンドごと） |
