# 機能設計書 225-ColorConvertU32ToFloat4

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける`ColorConvertU32ToFloat4`関数の機能設計書である。この関数は、32ビット符号なし整数形式（ImU32）のRGBA色値を、4成分浮動小数点形式（ImVec4）に変換するためのユーティリティ関数である。

### 本機能の処理概要

`ColorConvertU32ToFloat4`関数は、ImGuiで使用される2つの主要な色表現形式間の変換を提供する。ImU32形式は描画APIでの使用に最適化されたパック形式であり、ImVec4形式はユーザーインターフェースでの色指定やスタイル設定に使用される正規化された浮動小数点形式である。

**業務上の目的・背景**：ImGuiでは色を複数の形式で扱う。描画コマンドではImU32（32ビットパック形式）が効率的であり、ユーザー向けのAPIや内部計算ではImVec4（0.0-1.0の浮動小数点）が使いやすい。本機能は、これら2つの形式間の変換を提供し、異なるコンテキストで色を扱う際の相互運用性を確保する。

**機能の利用シーン**：
- 描画リストから取得したパック色値を編集可能な形式に変換
- カスタム描画コードでパック色を分解して各成分を操作
- ImU32で指定された色をカラーエディタで編集可能な形式に変換
- 色のブレンドや補間計算の前処理

**主要な処理内容**：
1. 入力のImU32値から各色成分（R, G, B, A）を抽出
2. 各成分を255で割って0.0-1.0の範囲に正規化
3. ImVec4として結果を返却

**関連システム・外部連携**：ColorConvertFloat4ToU32と対になる関数。ImColor構造体でも内部的に使用される。

**権限による制御**：特にない。いつでも呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 参照画面 | カラー編集時の変換 |

## 機能種別

データ変換（計算処理）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| in | ImU32 | Yes | パック形式のRGBA色値（IM_COL32マクロで作成可能） | - |

### ImU32色形式の構造

ImU32は以下のビットレイアウトを持つ（プラットフォーム依存）：
- デフォルト（IM_COL32_R_SHIFT=0）: 0xAABBGGRR（ABGR順）
- R: ビット0-7
- G: ビット8-15
- B: ビット16-23
- A: ビット24-31

### 入力データソース

呼び出し元から直接渡される値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ImVec4 | 正規化された浮動小数点形式のRGBA色値。各成分は0.0-1.0の範囲 |

### ImVec4色形式の構造

| メンバー | 範囲 | 説明 |
|---------|------|------|
| x | 0.0-1.0 | Red成分 |
| y | 0.0-1.0 | Green成分 |
| z | 0.0-1.0 | Blue成分 |
| w | 0.0-1.0 | Alpha成分 |

### 出力先

呼び出し元への戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. 変換係数の準備
   └─ s = 1.0f / 255.0f
2. 各色成分の抽出と変換
   ├─ R = ((in >> IM_COL32_R_SHIFT) & 0xFF) * s
   ├─ G = ((in >> IM_COL32_G_SHIFT) & 0xFF) * s
   ├─ B = ((in >> IM_COL32_B_SHIFT) & 0xFF) * s
   └─ A = ((in >> IM_COL32_A_SHIFT) & 0xFF) * s
3. ImVec4を構築して返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B["s = 1.0f / 255.0f"]
    B --> C["R = ((in >> R_SHIFT) & 0xFF) * s"]
    C --> D["G = ((in >> G_SHIFT) & 0xFF) * s"]
    D --> E["B = ((in >> B_SHIFT) & 0xFF) * s"]
    E --> F["A = ((in >> A_SHIFT) & 0xFF) * s"]
    F --> G["return ImVec4(R, G, B, A)"]
    G --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 正規化範囲 | 出力値は常に0.0-1.0の範囲内 | 常時 |
| BR-002 | ビットシフト定数 | IM_COL32_*_SHIFTマクロでプラットフォーム依存のビット位置を抽象化 | 常時 |
| BR-003 | 精度保持 | 変換は可逆的だが、浮動小数点精度により微小な誤差が生じる可能性あり | 常時 |

### 計算ロジック

```cpp
float s = 1.0f / 255.0f;
return ImVec4(
    ((in >> IM_COL32_R_SHIFT) & 0xFF) * s,
    ((in >> IM_COL32_G_SHIFT) & 0xFF) * s,
    ((in >> IM_COL32_B_SHIFT) & 0xFF) * s,
    ((in >> IM_COL32_A_SHIFT) & 0xFF) * s);
```

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | 本関数はエラーを発生させない | - |

### リトライ仕様

なし

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

該当なし

## パフォーマンス要件

- O(1)の時間計算量
- メモリアロケーションなし
- 単純なビット演算と乗算のみ

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

特になし

## 備考

- ColorConvertFloat4ToU32と対になる逆変換関数
- IM_COL32マクロで作成した色値をこの関数で分解可能
- ImColorクラスでも内部的に使用されている

---

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

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

### 推奨読解順序

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

まず、色の表現形式を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | IM_COL32マクロ定義 - パック色の作成方法 |
| 1-2 | imgui.h | `imgui.h` | ImVec4構造体 - 浮動小数点色の表現 |
| 1-3 | imgui.h | `imgui.h` | ImColor構造体（2955-2967行目付近） - ヘルパークラス |

**読解のコツ**: IM_COL32_R_SHIFT等のマクロはプラットフォームによって異なる可能性がある。通常はABGR順（Rがビット0）だが、imconfig.hで変更可能。

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

ColorConvertU32ToFloat4関数のAPI宣言と実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（1049行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | 関数実装（2784-2792行目） |

**主要処理フロー**:
1. **2786行目**: `float s = 1.0f / 255.0f;` - 正規化係数
2. **2787-2791行目**: 各成分の抽出と正規化

#### Step 3: 関連関数を理解する

対になる逆変換関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | ColorConvertFloat4ToU32（2794-2802行目） |

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

```
ImGui::ColorConvertU32ToFloat4()
    │
    └─ ビット演算とスカラー演算のみ
           │
           ├─ IM_COL32_R_SHIFT（マクロ）
           ├─ IM_COL32_G_SHIFT（マクロ）
           ├─ IM_COL32_B_SHIFT（マクロ）
           └─ IM_COL32_A_SHIFT（マクロ）
```

### データフロー図

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

ImU32 (0xAABBGGRR) ───▶ ビットシフト・マスク ───▶ ImVec4(r, g, b, a)
                              │
                              ├─ R成分抽出・正規化
                              ├─ G成分抽出・正規化
                              ├─ B成分抽出・正規化
                              └─ A成分抽出・正規化
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、IM_COL32マクロ定義 |
| imgui.cpp | `imgui.cpp` | ソース | ColorConvertU32ToFloat4関数実装 |
