# 機能設計書 129-ColorEdit3

## 概要

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

### 本機能の処理概要

ColorEdit3は、RGB（赤・緑・青）の3成分カラーを編集するためのウィジェット関数である。数値入力（スライダー/ドラッグ）とカラーピッカーポップアップを組み合わせた直感的なカラー編集インターフェースを提供する。

**業務上の目的・背景**：GUIアプリケーションにおいて、ユーザーが色を選択・編集する必要がある場面は多い。ゲーム開発、画像編集、UI設計ツールなど、様々なアプリケーションで色の編集は基本的な機能である。ColorEdit3は、RGB表示、HSV表示、16進数表示など複数の形式に対応し、様々なユーザーのニーズに応える。

**機能の利用シーン**：
- オブジェクトの色設定
- 背景色の選択
- テキスト色の編集
- マテリアルの基本色設定
- スタイルエディタでの色編集

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

**関連システム・外部連携**：内部でColorEdit4を呼び出し、ImGuiColorEditFlags_NoAlphaフラグを自動的に追加する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 主機能 | RGBカラーの編集 |
| 13 | Property Editor | 補助機能 | カラープロパティの編集 |
| 23 | Widgets | 主機能 | カラーエディタのデモ |

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### ImGuiColorEditFlags（主要なもの）

| フラグ | 説明 |
|-------|------|
| 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_InputRGB | 入出力をRGB形式で |
| ImGuiColorEditFlags_InputHSV | 入出力をHSV形式で |
| ImGuiColorEditFlags_NoDragDrop | ドラッグ&ドロップを無効化 |

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. ColorEdit3呼び出し
   └─ ImGuiColorEditFlags_NoAlphaフラグを追加
2. ColorEdit4を呼び出し
   └─ 3成分のみを編集（アルファは無視）
3. 入力フィールドの描画
   └─ RGB/HSV/Hex形式に応じた入力UI
4. カラープレビューの描画
   └─ 現在の色を示す四角形
5. インタラクション処理
   └─ クリック: カラーピッカーポップアップ
   └─ 右クリック: オプションメニュー
   └─ ドラッグ&ドロップ: カラー転送
6. 値変更の検出と戻り値の決定
   └─ カラーが変更された場合はtrueを返す
```

### フローチャート

```mermaid
flowchart TD
    A[ColorEdit3開始] --> B[NoAlphaフラグ追加]
    B --> C[ColorEdit4呼び出し]
    C --> D[入力フィールド描画]
    D --> E[カラープレビュー描画]
    E --> F{ユーザー操作}
    F -->|クリック| G[カラーピッカー表示]
    F -->|右クリック| H[オプションメニュー]
    F -->|入力| I[値更新]
    F -->|ドラッグ| J[D&D処理]
    G --> K{値変更?}
    H --> K
    I --> K
    J --> K
    K -->|Yes| L[true返却]
    K -->|No| M[false返却]
    L --> N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | NoAlphaフラグ自動追加 | ImGuiColorEditFlags_NoAlphaが自動的に追加される | 常に適用 |
| BR-02 | 値の範囲 | 各カラー成分は0.0〜1.0の範囲（HDRモード時は制限なし） | HDRフラグなし時 |
| BR-03 | 表示形式切替 | 右クリックメニューでRGB/HSV/Hex形式を切り替え可能 | NoOptionsフラグなし時 |
| BR-04 | ドラッグ&ドロップ | カラーボタンからドラッグ、ColorEditへドロップ可能 | NoDragDropフラグなし時 |

### 計算ロジック

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 範囲外値 | 0.0〜1.0の範囲外入力 | HDRモードでない場合はクランプ |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- アルファ成分を含む色編集が必要な場合はColorEdit4を使用
- カラーピッカーのみが必要な場合はColorPicker3を使用
- SetColorEditOptions()でアプリケーション全体のデフォルト設定を変更可能
- style.ColorMarkerSizeでR/G/B/Aマーカーのサイズを設定可能

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiColorEditFlags_の定義（行1871-1924）。各フラグの意味を確認 |

**読解のコツ**: フラグはDisplay系、DataType系、Picker系、Input系に分類される。_DisplayMask_、_DataTypeMask_などのマスクで排他制御。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（行732）。パラメータと戻り値の仕様を確認 |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorEdit3実装（行5705-5708）。ColorEdit4へのラッパー |

**主要処理フロー**:
1. **行5707**: ColorEdit4をNoAlphaフラグ付きで呼び出し

#### Step 3: コア実装を理解する

ColorEdit4の実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorEdit4実装（行5741-5984）。メインのカラー編集ロジック |

**主要処理フロー**:
- **行5760-5778**: フラグの読み取りとデフォルト設定の適用
- **行5789-5799**: RGB/HSV変換処理
- **行5808-5856**: RGB/HSVスライダー/ドラッグの描画
- **行5857-5883**: 16進数入力の処理
- **行5886-5889**: カラーボタン（プレビュー）の描画

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

```
ImGui::ColorEdit3()
    │
    └─ ImGui::ColorEdit4() [NoAlphaフラグ追加]
           │
           ├─ ColorEditOptionsPopup() [右クリックメニュー]
           │
           ├─ 表示形式に応じた処理
           │      ├─ DragInt/DragFloat [RGB/HSV値編集]
           │      └─ InputText [16進数入力]
           │
           ├─ ColorButton() [カラープレビュー]
           │      └─ カラーピッカーポップアップのトリガー
           │
           └─ ColorPicker4() [ピッカーポップアップ内]
```

### データフロー図

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

float col[3]   ───▶  ColorEdit3()
(RGBカラー)            │
                       ▼
               ColorEdit4()
                       │
                       ├─ RGB入力
                       │      └─ DragInt/DragFloat
                       │
                       ├─ HSV入力
                       │      └─ RGB⇔HSV変換
                       │
                       └─ Hex入力
                              └─ sscanf/sprintf
                       │
                       ▼
               bool (変更有無) ───▶ 戻り値
                       │
                       ▼
               col[3] 更新    ───▶ 編集結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、ImGuiColorEditFlags定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | ColorEdit3/4、ColorPicker3/4の実装 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | カラーエディタのデモ（行990-1001, 1112-1290等） |
