# 機能設計書 226-ColorConvertFloat4ToU32

## 概要

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

### 本機能の処理概要

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

**業務上の目的・背景**：ImGuiでは色を複数の形式で扱う。ユーザー向けのAPIや内部計算ではImVec4（0.0-1.0の浮動小数点）が使いやすく、描画コマンドではImU32（32ビットパック形式）が効率的である。本機能は、これら2つの形式間の変換を提供し、スタイル設定や色計算の結果を描画コマンドで使用可能な形式に変換する。

**機能の利用シーン**：
- カラーエディタで編集した色を描画コマンドに渡す前の変換
- スタイル設定の色値を描画APIで使用する形式に変換
- 色のブレンドや補間計算の結果を描画用に変換
- ImColorクラス内部でのImU32への暗黙変換

**主要な処理内容**：
1. 各色成分を0-255の範囲にスケーリング（飽和演算）
2. 各成分をビットシフトして正しい位置に配置
3. ビットOR演算で1つのImU32値に結合

**関連システム・外部連携**：ColorConvertU32ToFloat4と対になる関数。ImColor構造体で暗黙変換演算子として使用される。

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

## 関連画面

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

## 機能種別

データ変換（計算処理）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| in | const ImVec4& | Yes | 正規化された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成分 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ImU32 | パック形式のRGBA色値 |

### ImU32色形式の構造

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 各色成分の変換
   ├─ R = IM_F32_TO_INT8_SAT(in.x) << IM_COL32_R_SHIFT
   ├─ G = IM_F32_TO_INT8_SAT(in.y) << IM_COL32_G_SHIFT
   ├─ B = IM_F32_TO_INT8_SAT(in.z) << IM_COL32_B_SHIFT
   └─ A = IM_F32_TO_INT8_SAT(in.w) << IM_COL32_A_SHIFT
2. ビットOR演算で結合
   └─ out = R | G | B | A
3. 結果を返却
```

### IM_F32_TO_INT8_SATマクロの処理

```cpp
// 0.0-1.0を0-255に変換（飽和演算付き）
#define IM_F32_TO_INT8_SAT(_VAL) ((int)(ImSaturate(_VAL) * 255.0f + 0.5f))
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B["out = 0"]
    B --> C["R = IM_F32_TO_INT8_SAT(in.x) << R_SHIFT"]
    C --> D["out |= R"]
    D --> E["G = IM_F32_TO_INT8_SAT(in.y) << G_SHIFT"]
    E --> F["out |= G"]
    F --> G["B = IM_F32_TO_INT8_SAT(in.z) << B_SHIFT"]
    G --> H["out |= B"]
    H --> I["A = IM_F32_TO_INT8_SAT(in.w) << A_SHIFT"]
    I --> J["out |= A"]
    J --> K["return out"]
    K --> L[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 飽和演算 | 入力値は0.0-1.0にクランプされる | 常時 |
| BR-002 | 四捨五入 | 変換時に0.5を加算して四捨五入 | 常時 |
| BR-003 | ビットシフト定数 | IM_COL32_*_SHIFTマクロでプラットフォーム依存のビット位置を抽象化 | 常時 |

### 計算ロジック

```cpp
ImU32 out;
out  = ((ImU32)IM_F32_TO_INT8_SAT(in.x)) << IM_COL32_R_SHIFT;
out |= ((ImU32)IM_F32_TO_INT8_SAT(in.y)) << IM_COL32_G_SHIFT;
out |= ((ImU32)IM_F32_TO_INT8_SAT(in.z)) << IM_COL32_B_SHIFT;
out |= ((ImU32)IM_F32_TO_INT8_SAT(in.w)) << IM_COL32_A_SHIFT;
return out;
```

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

なし

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

該当なし

## パフォーマンス要件

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

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

特になし

## 備考

- ColorConvertU32ToFloat4と対になる逆変換関数
- ImColorクラスのImU32への変換演算子で使用
- 入力値が0.0-1.0の範囲外でも飽和演算により安全に処理

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | IM_COL32マクロ定義 - パック色の作成方法 |
| 1-2 | imgui.h | `imgui.h` | IM_F32_TO_INT8_SATマクロ - 浮動小数点から整数への変換 |
| 1-3 | imgui.h | `imgui.h` | ImColor構造体（2961行目） - 暗黙変換での使用例 |

**読解のコツ**: IM_F32_TO_INT8_SATマクロはImSaturate関数を内部で使用し、0.0-1.0へのクランプを行う。0.5を加算することで四捨五入効果を得ている。

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

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

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

**主要処理フロー**:
1. **2796行目**: `ImU32 out;` - 出力変数
2. **2797-2800行目**: 各成分の変換とビットシフト
3. **2801行目**: `return out;` - 結果返却

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

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

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

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

```
ImGui::ColorConvertFloat4ToU32()
    │
    ├─ IM_F32_TO_INT8_SAT（マクロ）
    │      │
    │      └─ ImSaturate()
    │
    ├─ IM_COL32_R_SHIFT（マクロ）
    ├─ IM_COL32_G_SHIFT（マクロ）
    ├─ IM_COL32_B_SHIFT（マクロ）
    └─ IM_COL32_A_SHIFT（マクロ）
```

### データフロー図

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

ImVec4(r, g, b, a) ───▶ 飽和演算・スケーリング ───▶ ImU32 (0xAABBGGRR)
   (0.0-1.0)                   │
                               ├─ R: 0-255にスケール→シフト
                               ├─ G: 0-255にスケール→シフト
                               ├─ B: 0-255にスケール→シフト
                               └─ A: 0-255にスケール→シフト
                                          │
                                          └─ ビットOR結合
```

### 関連ファイル一覧

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