# 機能設計書 132-ColorPicker4

## 概要

本ドキュメントは、ImGuiライブラリにおけるRGBAカラーピッカーウィジェット `ColorPicker4` の機能仕様を定義するものである。

### 本機能の処理概要

ColorPicker4は、ユーザーがRGBA色（アルファチャンネル含む）を視覚的に選択するためのカラーピッカーウィジェットを作成する機能である。

**業務上の目的・背景**：GUIアプリケーションにおいて、透明度を含む色の選択は、半透明なオーバーレイ、パーティクルエフェクト、グラデーション効果など多くの場面で必要とされる。ColorPicker4は、RGB色に加えてアルファチャンネル（透明度）も視覚的に選択できる完全なカラーピッカーUIを提供する。Hueホイール+SV三角形モード、またはHueバー+SV矩形モードの2種類のピッカースタイルをサポートし、ユーザーの好みに応じた操作感を実現する。

**機能の利用シーン**：スタイルエディタでの半透明UI色設定、画像編集ソフトでのレイヤー透明度指定、ゲームエディタでの半透明エフェクト色設定、データビジュアライゼーションでの色と透明度の同時指定など、アルファチャンネルを含む色選択が必要なあらゆる場面で使用される。

**主要な処理内容**：
1. ピッカータイプ（Hueホイール/Hueバー）に応じたUI描画
2. 彩度・明度（SV）の選択UI描画
3. アルファバーの描画（オプション）
4. マウス操作によるH/S/V/A各値の変更処理
5. RGB/HSV相互変換とグレースケール時のHue復元
6. オプションメニューによるピッカー設定変更
7. リファレンスカラーとの比較表示（オプション）

**関連システム・外部連携**：ColorEdit3/4関数から呼び出されることもある。ドラッグ&ドロップによる色の受け渡しにも対応。SetColorEditOptionsで設定したグローバルオプションを参照する。

**権限による制御**：ImGuiItemFlags_ReadOnlyフラグが設定されている場合、ピッカーの値は変更できない（読み取り専用モード）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 主画面 | スタイルエディタでのRGBAカラー編集 |
| 23 | Widgets | 参照画面 | カラーエディタのデモ表示 |

## 機能種別

ユーザー入力処理 / ウィジェット描画

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットのラベル（ID生成にも使用） | NULL不可 |
| col | float[4] | Yes | RGBA色値の配列（0.0〜1.0） | 各要素は0.0〜1.0の範囲が推奨 |
| flags | ImGuiColorEditFlags | No | カラーエディタの動作オプション | デフォルトは0 |
| ref_col | const float* | No | 比較用のリファレンスカラー | NULLで無効 |

### 入力データソース

- ユーザーが指定するfloat配列（アプリケーションが管理）
- マウス入力によるピッカー操作
- グローバル設定（g.ColorEditOptions）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 色が変更された場合true、それ以外false |
| col | float[4] | 更新されたRGBA色値（入出力パラメータ） |

### 出力先

- 引数で渡されたfloat配列への直接書き込み
- 画面上へのウィジェット描画

## 処理フロー

### 処理シーケンス

```
1. ウィンドウスキップチェック
   └─ SkipItemsがtrueならfalse返却
2. フラグとオプションの初期化
   └─ グローバル設定との統合
3. ピッカー領域のサイズ計算
   └─ SV領域、Hueバー、Alphaバーのサイズ決定
4. 色値のRGB/HSV変換
   └─ グレースケール時のHue復元処理
5. ピッカータイプに応じたUI処理
   └─ HueホイールまたはHueバーモード
6. SV領域のマウス操作処理
   └─ クリック&ドラッグでS/V値変更
7. Hue領域のマウス操作処理
   └─ クリック&ドラッグでH値変更
8. アルファバーの処理（有効時）
   └─ クリック&ドラッグでA値変更
9. UIの描画処理
   └─ 各領域のレンダリング
10. 結果の書き戻しと返却
    └─ value_changedを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SkipItems?}
    B -->|Yes| C[return false]
    B -->|No| D[フラグ・オプション初期化]
    D --> E[ピッカーサイズ計算]
    E --> F[RGB/HSV変換]
    F --> G{PickerHueWheel?}
    G -->|Yes| H[Hueホイール処理]
    G -->|No| I[Hueバー処理]
    H --> J[SV三角形処理]
    I --> K[SV矩形処理]
    J --> L{AlphaBar?}
    K --> L
    L -->|Yes| M[アルファバー処理]
    L -->|No| N[描画処理]
    M --> N
    N --> O[結果書き戻し]
    O --> P[return value_changed]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-132-01 | ピッカータイプ排他 | HueホイールとHueバーは排他的に動作 | 常時 |
| BR-132-02 | 値の範囲 | RGBA各要素は0.0〜1.0の範囲で処理 | 常時 |
| BR-132-03 | Hue復元 | グレースケール色でもHue値を保持・復元 | RGB入力モード時 |
| BR-132-04 | オプション継承 | グローバル設定を参照し、未指定オプションを補完 | NoOptionsフラグ未設定時 |
| BR-132-05 | 読み取り専用 | ReadOnlyフラグ設定時は値変更不可 | ReadOnlyフラグ設定時 |

### 計算ロジック

- RGB→HSV変換：`ColorConvertRGBtoHSV(R, G, B, H, S, V)`
- HSV→RGB変換：`ColorConvertHSVtoRGB(H, S, V, R, G, B)`
- Hue角度計算：`H = atan2(y, x) / PI * 0.5`
- 三角形内座標計算：重心座標系（Barycentric coordinates）を使用

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

### 操作別データベース影響一覧

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ウィンドウスキップ | window->SkipItemsがtrue | falseを返却して処理終了 |

### リトライ仕様

リトライ処理は不要（即時応答型）

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

トランザクション管理は不要

## パフォーマンス要件

- 毎フレーム呼び出されることを想定した実装
- 三角関数や重心座標計算を使用するため、ColorEdit4より若干重い

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

特になし（ローカルUI操作のみ）

## 備考

- ColorPicker3からも呼び出される（NoAlphaフラグ付き）
- ref_col引数を使用すると、元の色と新しい色の比較表示が可能
- 右クリックでオプションメニューを表示（NoOptionsフラグ未設定時）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiColorEditFlags列挙型の定義（1871-1910行目） |

**読解のコツ**: PickerMask_、InputMask_、DisplayMask_などのマスク定数がオプション管理に重要。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | ColorPicker4の関数宣言（735行目） |

**主要処理フロー**:
1. **735行目**: 関数シグネチャの確認、ref_col引数の存在

#### Step 3: 実装コアロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorPicker4の実装（6017-6384行目） |

**主要処理フロー**:
- **6019-6030行目**: コンテキスト取得と初期化
- **6032-6036行目**: PushIDとBeginGroupでグループ化
- **6046-6053行目**: オプションフラグの読み込みと適用
- **6055-6078行目**: ピッカーサイズの計算
- **6080-6091行目**: RGB/HSV変換処理
- **6096-6130行目**: Hueホイール+SVトライアングルモードの処理
- **6131-6145行目**: SV矩形モードの処理
- **6150-6180行目**: Hueバーモードの処理
- **6185-6210行目**: アルファバーの処理
- **6220-6350行目**: 描画処理

#### Step 4: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | RenderArrowsForVerticalBar（6003-6011行目） |
| 4-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | ColorEditRestoreHS関数 |

**主要処理フロー**:
- **6003-6011行目**: 縦バー用の矢印マーカー描画

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

```
ColorPicker4 (imgui_widgets.cpp:6017)
    │
    ├─ GetCurrentWindow
    ├─ CalcItemWidth
    ├─ PushID / PopID
    ├─ BeginGroup / EndGroup
    │
    ├─ ColorPickerOptionsPopup
    │      └─ BeginPopup / EndPopup
    │
    ├─ InvisibleButton
    │      └─ ButtonBehavior
    │
    ├─ ColorConvertRGBtoHSV
    ├─ ColorConvertHSVtoRGB
    ├─ ColorEditRestoreHS
    │
    ├─ RenderArrowsForVerticalBar
    │      └─ RenderArrowPointingAt
    │
    └─ DrawList操作
           ├─ AddRectFilledMultiColor
           ├─ AddCircleFilled
           ├─ AddTriangleFilled
           └─ AddLine
```

### データフロー図

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

float col[4] ─────┬─▶ RGB→HSV変換 ─────▶ H,S,V値
(RGBA)            │        │
                  │        ▼
const float*      │   ピッカーUI操作
ref_col ──────────┤   (マウス入力)
(比較用色)        │        │
                  │        ▼
ImGuiColorEdit    │   HSV→RGB変換
Flags flags ──────┘        │
                           ▼
                   col[4]に書き戻し ──────▶ float col[4]
                           │                 (RGBA)
                           ▼
                   return value_changed ──▶ bool
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言とフラグ定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | ColorPicker4の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | 内部関数宣言、ColorEditRestoreHS等 |
| imgui_draw.cpp | `imgui_draw.cpp` | ソース | 描画プリミティブ実装 |
