# 機能設計書 101-ImageWithBg

## 概要

本ドキュメントは、ImGuiライブラリにおける`ImageWithBg`関数の機能設計を記載する。

### 本機能の処理概要

`ImageWithBg`関数は、テクスチャ画像を背景色付きでウィンドウ内に表示するためのウィジェット関数である。`Image`関数の拡張版として、背景色とティント色（色合い調整）をサポートし、より柔軟な画像表示を可能にする。

**業務上の目的・背景**：アプリケーションのGUI開発において、画像表示は基本的な要件である。画像の背景色を指定したい場合（透過PNG画像のプレビュー、サムネイル表示時の背景色統一など）に本機能を使用する。特に、アルファチャンネルを持つ画像を見やすく表示したい場合や、統一感のあるUIを構築したい場合に有用である。ImGui 1.91.9以前の`Image`関数が持っていた`tint_col`パラメータの機能を継承し、非推奨化に伴い本関数に機能が移行された。

**機能の利用シーン**：
- 透過PNG画像を背景色付きで表示する場合
- アセットブラウザやサムネイルビューでの画像プレビュー
- 色合いを調整した画像表示が必要な場合
- フォントアトラスのデバッグ表示

**主要な処理内容**：
1. ウィンドウのスキップ状態を確認し、スキップ中であれば処理を終了
2. 画像サイズと境界線サイズからバウンディングボックスを計算
3. アイテムサイズを設定し、アイテムを追加
4. 背景色が指定されている場合、背景色で矩形を塗りつぶし
5. 丸み設定に応じて画像を描画（丸み付き or 通常）
6. 境界線サイズが指定されている場合、境界線を描画

**関連システム・外部連携**：
- ImDrawList: 描画コマンドの発行
- ImTextureRef: テクスチャ参照（バックエンド実装に依存）
- スタイルシステム: ImageBorderSize, ImageRounding の参照

**権限による制御**：特になし（GUI描画機能のため）

## 関連画面

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

## 機能種別

ウィジェット描画処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| tex_ref | ImTextureRef | Yes | 表示するテクスチャの参照 | 有効なテクスチャIDであること |
| image_size | const ImVec2& | Yes | 画像の表示サイズ（ピクセル） | 正の値 |
| uv0 | const ImVec2& | No | テクスチャ座標の開始点（デフォルト: 0,0） | 0.0〜1.0の範囲 |
| uv1 | const ImVec2& | No | テクスチャ座標の終了点（デフォルト: 1,1） | 0.0〜1.0の範囲 |
| bg_col | const ImVec4& | No | 背景色（デフォルト: 透明） | RGBA各成分0.0〜1.0 |
| tint_col | const ImVec4& | No | ティント色（デフォルト: 白） | RGBA各成分0.0〜1.0 |

### 入力データソース

- ユーザー指定のパラメータ（関数引数）
- ImGuiスタイル設定（ImageBorderSize, ImageRounding）
- 現在のウィンドウ状態（CursorPos, SkipItems）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | void | なし（描画のみを行う） |

### 出力先

- ImDrawList（描画コマンドリスト）
  - 背景色の矩形
  - テクスチャ画像
  - 境界線（設定時）

## 処理フロー

### 処理シーケンス

```
1. ウィンドウ状態確認
   └─ window->SkipItems がtrueの場合、即座にreturn
2. バウンディングボックス計算
   └─ CursorPos + image_size + padding*2 で矩形を算出
3. アイテム登録
   └─ ItemSize() でレイアウト情報を更新
   └─ ItemAdd() でアイテムを追加（falseならreturn）
4. 背景描画（bg_col.w > 0.0fの場合）
   └─ AddRectFilled() で背景色を描画
5. 画像描画
   └─ rounding > 0: AddImageRounded() で丸み付き描画
   └─ rounding == 0: AddImage() で通常描画
6. 境界線描画（ImageBorderSize > 0.0fの場合）
   └─ AddRect() で境界線を描画
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SkipItems?}
    B -->|Yes| C[return]
    B -->|No| D[バウンディングボックス計算]
    D --> E[ItemSize/ItemAdd]
    E --> F{ItemAdd成功?}
    F -->|No| C
    F -->|Yes| G{bg_col.w > 0?}
    G -->|Yes| H[背景色描画]
    G -->|No| I{rounding > 0?}
    H --> I
    I -->|Yes| J[AddImageRounded]
    I -->|No| K[AddImage]
    J --> L{BorderSize > 0?}
    K --> L
    L -->|Yes| M[境界線描画]
    L -->|No| N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-101 | パディング計算 | ImageBorderSizeをパディングとして使用 | 常時 |
| BR-102 | 背景色描画判定 | bg_col.w（アルファ）が0より大きい場合のみ背景を描画 | bg_col指定時 |
| BR-103 | 丸み設定 | ImageRoundingスタイル値を参照し丸み付き描画を選択 | rounding > 0の場合 |

### 計算ロジック

バウンディングボックス計算:
```
padding = ImVec2(ImageBorderSize, ImageBorderSize)
bb.Min = window->DC.CursorPos
bb.Max = window->DC.CursorPos + image_size + padding * 2.0f
```

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

該当なし（GUI描画機能のためデータベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 描画スキップ | window->SkipItemsがtrue | 処理を中断（正常動作） |
| - | アイテム追加失敗 | ItemAdd()がfalseを返す | 処理を中断（正常動作） |

### リトライ仕様

リトライなし（フレーム単位の描画処理のため）

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

該当なし

## パフォーマンス要件

- 単一フレーム内で複数回呼び出し可能
- 描画コマンドはImDrawListにバッファリングされ、Render()時に一括処理

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

- テクスチャIDの検証はバックエンド実装に依存
- 不正なテクスチャ参照は未定義動作を引き起こす可能性あり

## 備考

- 本関数は ImGui 1.91.9（2025年3月）以降で追加
- 旧`Image`関数の`tint_col`パラメータは非推奨となり、本関数で代替
- `Image`関数は内部的に`ImageWithBg`を呼び出す（デフォルト値で）

---

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

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

### 推奨読解順序

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

まず、画像表示に関連するデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImVec2, ImVec4, ImTextureRef の定義を確認 |
| 1-2 | imgui.h | `imgui.h` | ImGuiStyle構造体のImageBorderSize, ImageRounding を確認 |

**読解のコツ**: ImTextureRefはテクスチャ参照の抽象化で、バックエンドによって実体が異なる。ImVec2/ImVec4は2D/4D ベクトルで、座標や色を表現する。

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

処理の起点となる関数シグネチャを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 653行目: ImageWithBg関数の宣言 |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1107行目: ImageWithBg関数の実装 |

**主要処理フロー**:
1. **1109-1112行目**: ウィンドウ取得とSkipItems確認
2. **1114-1118行目**: バウンディングボックス計算とItemSize/ItemAdd
3. **1121-1129行目**: 描画処理（背景、画像、境界線）

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

描画コマンドの発行を追跡する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1122-1123行目: AddRectFilledによる背景描画 |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1124-1127行目: AddImageRounded/AddImageによる画像描画 |
| 3-3 | imgui_widgets.cpp | `imgui_widgets.cpp` | 1128-1129行目: AddRectによる境界線描画 |

**主要処理フロー**:
- **1122行目**: `bg_col.w > 0.0f`の条件で背景色描画の有無を判定
- **1124行目**: `rounding > 0.0f`の条件で丸み付き描画を選択

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

```
ImGui::ImageWithBg()
    │
    ├─ GetCurrentWindow()
    │      └─ GImGui->CurrentWindow を取得
    │
    ├─ ItemSize()
    │      └─ レイアウト情報を更新
    │
    ├─ ItemAdd()
    │      └─ アイテムをウィンドウに追加
    │
    └─ window->DrawList->
           ├─ AddRectFilled() ... 背景色描画
           ├─ AddImageRounded() ... 丸み付き画像描画
           ├─ AddImage() ... 通常画像描画
           └─ AddRect() ... 境界線描画
```

### データフロー図

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

tex_ref     ───┐
image_size  ───┼──▶ ImageWithBg() ───▶ ImDrawList
uv0/uv1     ───┤         │               (描画コマンド)
bg_col      ───┤         │
tint_col    ───┘         ▼
                    DrawList Commands:
                    - AddRectFilled (背景)
                    - AddImage/AddImageRounded (画像)
                    - AddRect (境界線)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、型定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | 関数実装 |
| imgui_draw.cpp | `imgui_draw.cpp` | ソース | ImDrawListの描画コマンド実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | 内部関数・構造体定義 |
