# 機能設計書 130-ColorEdit4

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるRGBAカラーエディタ機能「ColorEdit4」の設計仕様を定義する。

### 本機能の処理概要

ColorEdit4は、RGBA（赤・緑・青・アルファ）の4成分カラーを編集するためのウィジェット関数である。数値入力（スライダー/ドラッグ）とカラーピッカーポップアップを組み合わせた直感的なカラー編集インターフェースを提供する。ColorEdit3の全機能に加え、透明度（アルファ）の編集をサポートする。

**業務上の目的・背景**：GUIアプリケーションにおいて、透明度を含む色を選択・編集する必要がある場面は多い。UIデザイン、画像編集、ゲーム開発など、様々なアプリケーションで半透明のカラーは重要な要素である。ColorEdit4は、RGB表示、HSV表示、16進数表示など複数の形式に対応し、透明度も含めた完全なカラー編集機能を提供する。

**機能の利用シーン**：
- 半透明オブジェクトの色設定
- UI要素の背景色（透明度付き）の設定
- スタイルエディタでのRGBAカラー編集
- パーティクルやエフェクトの色設定
- グラデーションの設定

**主要な処理内容**：
1. 4つの数値入力フィールド（R, G, B, A）を描画する
2. カラープレビュー（色付き四角形、アルファ付き）を表示する
3. クリックでカラーピッカーポップアップを開く
4. RGB/HSV/Hex形式での数値入力をサポートする
5. ドラッグ&ドロップによるカラー転送をサポートする
6. アルファバー（縦バー）の表示をサポートする

**関連システム・外部連携**：ColorEdit3から呼び出される基盤関数。ColorPicker4を内部で使用してカラーピッカーポップアップを表示する。

**権限による制御**：特になし（全ユーザーが使用可能）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 主機能 | RGBAカラーの編集 |
| 20 | Custom Rendering | 参照画面 | 図形の色設定 |
| 23 | Widgets | 参照画面 | カラーエディタのデモ |

## 機能種別

カラー編集ウィジェット / RGBA対応

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| col | float[4] | Yes | 編集対象のRGBAカラー配列（各成分0.0〜1.0） | NULL不可 |
| flags | ImGuiColorEditFlags | No | 表示・動作を制御するフラグ | - |

### ImGuiColorEditFlags（主要なもの）

| フラグ | 説明 |
|-------|------|
| ImGuiColorEditFlags_NoAlpha | アルファ成分を無視（3成分として扱う） |
| ImGuiColorEditFlags_NoPicker | カラーピッカーポップアップを無効化 |
| ImGuiColorEditFlags_NoOptions | 右クリックメニューを無効化 |
| ImGuiColorEditFlags_NoSmallPreview | 小さいカラープレビューを非表示 |
| ImGuiColorEditFlags_NoInputs | 入力スライダーを非表示 |
| ImGuiColorEditFlags_NoTooltip | ツールチップを無効化 |
| ImGuiColorEditFlags_DisplayRGB | RGB形式で表示 |
| ImGuiColorEditFlags_DisplayHSV | HSV形式で表示 |
| ImGuiColorEditFlags_DisplayHex | 16進数形式で表示 |
| ImGuiColorEditFlags_Uint8 | 0〜255の整数で表示 |
| ImGuiColorEditFlags_Float | 0.0〜1.0の浮動小数点で表示 |
| ImGuiColorEditFlags_AlphaBar | ピッカーにアルファバーを表示 |
| ImGuiColorEditFlags_AlphaOpaque | プレビューでアルファを不透明にする |
| ImGuiColorEditFlags_HDR | HDRモード（0.0〜1.0制限なし） |
| ImGuiColorEditFlags_NoDragDrop | ドラッグ&ドロップを無効化 |

### 入力データソース

ユーザーが提供するfloat[4]配列（col）を直接編集する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | カラーが変更された場合にtrue |
| col[4] | float[4] | 編集されたRGBAカラー値 |

### 出力先

提供されたfloat配列（col[]）に編集結果が直接書き込まれる。

## 処理フロー

### 処理シーケンス

```
1. ColorEdit4呼び出し
   └─ フラグの解析とデフォルト設定の適用
2. オプションメニューの処理
   └─ 右クリックでポップアップ表示
3. 入力形式に応じた変換
   └─ RGB/HSV/Hex形式間の変換
4. 入力フィールドの描画
   └─ RGB/HSV: DragInt/DragFloatで4成分
   └─ Hex: InputTextで#RRGGBBAA形式
5. カラープレビューの描画
   └─ ColorButton()でアルファ付きプレビュー
6. ピッカーポップアップの処理
   └─ クリックでColorPicker4()を表示
7. 値変更の検出と戻り値の決定
   └─ カラーが変更された場合はtrueを返す
```

### フローチャート

```mermaid
flowchart TD
    A[ColorEdit4開始] --> B[フラグ解析]
    B --> C{NoOptions?}
    C -->|No| D[右クリックメニュー設定]
    C -->|Yes| E[スキップ]
    D --> F[RGB/HSV変換]
    E --> F
    F --> G{表示形式}
    G -->|RGB/HSV| H[DragInt/DragFloat描画]
    G -->|Hex| I[InputText描画]
    H --> J[カラーボタン描画]
    I --> J
    J --> K{クリック?}
    K -->|Yes| L[ColorPicker4ポップアップ]
    K -->|No| M[値変更チェック]
    L --> M
    M --> N{変更あり?}
    N -->|Yes| O[true返却]
    N -->|No| P[false返却]
    O --> Q[終了]
    P --> Q
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 値の範囲 | 各カラー成分は0.0〜1.0の範囲（HDRモード時は制限なし） | HDRフラグなし時 |
| BR-02 | 表示形式切替 | 右クリックメニューでRGB/HSV/Hex形式を切り替え可能 | NoOptionsフラグなし時 |
| BR-03 | ドラッグ&ドロップ | カラーボタンからドラッグ、ColorEditへドロップ可能 | NoDragDropフラグなし時 |
| BR-04 | Hex入力のアルファ | アルファ省略時は255（完全不透明）とする | Hex入力時 |
| BR-05 | HSV保持 | RGB→HSV変換でHue/Saturationが失われないよう保持 | HSV表示時 |

### 計算ロジック

- RGB→HSV変換: ColorConvertRGBtoHSV()
- HSV→RGB変換: ColorConvertHSVtoRGB()
- float→U8変換: IM_F32_TO_INT8_UNBOUND()
- float→U32変換: ColorConvertFloat4ToU32()

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 範囲外値 | 0.0〜1.0の範囲外入力 | HDRモードでない場合はクランプ |
| - | 無効なHex文字列 | 16進数でない文字入力 | パースエラー、値は変更されない |

### リトライ仕様

リトライ機能は提供されない。

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

本機能はトランザクション処理を行わない。

## パフォーマンス要件

軽量なウィジェットであり、特別なパフォーマンス考慮は不要。

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

特別なセキュリティ考慮事項はない。

## 備考

- アルファ成分が不要な場合はColorEdit3を使用（内部でColorEdit4 + NoAlphaを呼び出す）
- カラーピッカーのみが必要な場合はColorPicker4を使用
- SetColorEditOptions()でアプリケーション全体のデフォルト設定を変更可能
- style.ColorButtonPositionでカラーボタンの位置（左/右）を設定可能
- style.ColorMarkerSizeでR/G/B/Aマーカーのサイズを設定可能

---

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

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

### 推奨読解順序

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

カラー編集フラグの定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiColorEditFlags_の定義（行1871-1924）。各フラグの意味とマスクを確認 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ColorEditCurrentID等の内部状態変数（行2467） |

**読解のコツ**: フラグはDisplay系、DataType系、Picker系、Input系に分類される。_DefaultOptions_でデフォルト値を確認。

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

処理の起点となるColorEdit4関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（行733）。パラメータと戻り値の仕様を確認 |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorEdit4実装（行5741-5984）。メインのカラー編集ロジック |

**主要処理フロー**:
1. **行5743-5745**: ウィンドウがスキップ状態かチェック
2. **行5754-5758**: グループ開始とID管理
3. **行5760-5778**: フラグの読み取りとデフォルト設定の適用
4. **行5789-5799**: RGB/HSV変換処理（ColorEditRestoreHS使用）
5. **行5808-5856**: RGB/HSVスライダー/ドラッグの描画
6. **行5857-5883**: 16進数入力の処理
7. **行5886-5983**: カラーボタンとピッカーポップアップ

#### Step 3: 補助関数を理解する

HSV保持のための補助関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorEditRestoreH（行5710-5717）。Hue保持ロジック |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorEditRestoreHS（行5721-5736）。Hue/Saturation保持ロジック |

**主要処理フロー**:
- **行5730-5731**: S==0またはH==0の場合、保存されたHueを復元
- **行5734-5735**: V==0の場合、保存されたSaturationを復元

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

```
ImGui::ColorEdit4()
    │
    ├─ BeginGroup() / PushID()
    │
    ├─ ColorEditOptionsPopup() [右クリックメニュー]
    │
    ├─ ColorEditRestoreHS() [HSV保持処理]
    │
    ├─ 表示形式に応じた処理
    │      │
    │      ├─ RGB/HSV表示
    │      │      ├─ SetNextItemWidth()
    │      │      ├─ SetNextItemColorMarker() [カラーマーカー]
    │      │      └─ DragInt/DragFloat [値編集]
    │      │
    │      └─ Hex表示
    │             └─ InputText [16進数入力]
    │
    ├─ ColorButton() [カラープレビュー]
    │      │
    │      └─ BeginPopup() [クリック時]
    │             └─ ColorPicker4() [ピッカー表示]
    │
    └─ EndGroup() / PopID()
```

### データフロー図

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

float col[4]   ───▶  ColorEdit4()
(RGBAカラー)           │
                       ▼
               フラグ解析/変換
                       │
                       ├─ RGB入力
                       │      └─ DragInt/DragFloat
                       │
                       ├─ HSV入力
                       │      ├─ RGB⇔HSV変換
                       │      └─ ColorEditRestoreHS()
                       │
                       └─ Hex入力
                              └─ sscanf/sprintf
                       │
                       ├─ カラーボタンクリック
                       │      └─ ColorPicker4()
                       │
                       ▼
               bool (変更有無) ───▶ 戻り値
                       │
                       ▼
               col[4] 更新    ───▶ 編集結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、ImGuiColorEditFlags定義、スタイル設定 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | ColorEdit4、ColorPicker4、補助関数の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ColorEditCurrentID、ColorEditSavedHue等の内部状態 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | カラーエディタのデモ（行1000, 1122-1290等） |
| imgui.cpp | `imgui.cpp` | ソース | スタイル設定（ColorMarkerSize, ColorButtonPosition） |
