# 機能設計書 131-ColorPicker3

## 概要

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

### 本機能の処理概要

ColorPicker3は、ユーザーがRGB色を視覚的に選択するためのカラーピッカーウィジェットを作成する機能である。

**業務上の目的・背景**：GUIアプリケーションにおいて、色の選択はデザインツール、画像編集、ゲームエディタなど多くの場面で必要とされる。ColorPicker3は、ユーザーがマウス操作で直感的にRGB色を選択できるUIを提供し、複雑な色指定を視覚的かつ簡単に行えるようにする。アルファチャンネルを必要としないシンプルな色選択シーンに特化している。

**機能の利用シーン**：スタイルエディタでのUI色設定、3Dモデリングソフトでのマテリアル色指定、グラフィックデザインツールでのペンキ色選択、ゲームエディタでのライト色やオブジェクト色設定など、RGB色を選択する必要があるあらゆる場面で使用される。

**主要な処理内容**：
1. 3要素の浮動小数点配列（RGB）を一時的に4要素（RGBA）に拡張
2. ColorPicker4を内部呼び出しし、NoAlphaフラグを付与
3. 選択結果から3要素（RGB）を抽出して返却
4. ユーザー操作による色変更があればtrueを返却

**関連システム・外部連携**：ColorPicker4関数に処理を委譲する設計となっており、ColorEdit系ウィジェットとも連携可能。ドラッグ&ドロップによる色の受け渡しにも対応。

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 3要素RGB配列を4要素RGBA配列に変換
   └─ アルファ値は1.0で固定
2. ColorPicker4を呼び出し
   └─ ImGuiColorEditFlags_NoAlphaフラグを付与
3. ColorPicker4の戻り値を確認
   └─ falseの場合は処理終了
4. 4要素配列から3要素RGB値を抽出
   └─ 元の配列に書き戻し
5. trueを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[col4配列を作成]
    B --> C[col[0-2]をcol4にコピー]
    C --> D[col4[3] = 1.0f]
    D --> E{ColorPicker4呼び出し}
    E -->|false| F[return false]
    E -->|true| G[col4[0-2]をcolに書き戻し]
    G --> H[return true]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-131-01 | アルファ非表示 | NoAlphaフラグを強制付与しアルファチャンネルを非表示にする | 常時 |
| BR-131-02 | 値の範囲 | RGB各要素は0.0〜1.0の範囲で処理される | 常時 |
| BR-131-03 | 読み取り専用対応 | ReadOnlyフラグ設定時は値変更不可 | ReadOnlyフラグ設定時 |

### 計算ロジック

- RGB→HSV変換：内部でColorConvertRGBtoHSV使用
- HSV→RGB変換：内部でColorConvertHSVtoRGB使用

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

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

## パフォーマンス要件

- 毎フレーム呼び出されることを想定した軽量実装
- ColorPicker4への委譲により実装コードを最小化

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

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

## 備考

- ColorPicker4のラッパー関数として実装されている
- アルファチャンネルが必要な場合はColorPicker4を直接使用すること
- ColorEdit3とセットで使用されることが多い

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: ImGuiColorEditFlags_NoAlphaフラグがColorPicker3で強制的に使用される点に注目。

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

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

**主要処理フロー**:
1. **734行目**: 関数シグネチャの確認

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

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

**主要処理フロー**:
- **5996行目**: RGB配列を一時的なRGBA配列に変換
- **5997-5998行目**: ColorPicker4を呼び出し、NoAlphaフラグを付与
- **5999行目**: 結果をRGB配列に書き戻し
- **6000行目**: trueを返却

#### Step 4: 委譲先の処理を理解する

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

**主要処理フロー**:
- **6019-6030行目**: 初期化処理とフラグ設定
- **6046-6053行目**: オプションフラグの読み込みと適用
- **6055-6091行目**: ピッカー領域のセットアップとRGB/HSV変換
- **6096-6130行目**: Hueホイール+SVトライアングルロジック
- **6131-6145行目**: Hueバー+SV矩形ロジック

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

```
ColorPicker3 (imgui_widgets.cpp:5994)
    │
    └─ ColorPicker4 (imgui_widgets.cpp:6017)
           │
           ├─ GetCurrentWindow
           ├─ CalcItemWidth
           ├─ PushID
           ├─ BeginGroup
           ├─ ColorPickerOptionsPopup
           ├─ InvisibleButton
           ├─ ColorConvertRGBtoHSV
           ├─ ColorConvertHSVtoRGB
           ├─ ColorEditRestoreHS
           ├─ EndGroup
           └─ PopID
```

### データフロー図

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

float col[3] ───▶ col4[4]に変換 ───▶ ColorPicker4 ───▶ col[3]に書き戻し
(RGB)              (RGBA, A=1.0)         │                (RGB)
                                         │
                   ┌─────────────────────┘
                   ▼
            Hue/Saturation/Value
            マウス操作による変更
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言とフラグ定義 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | ColorPicker3/4の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | 内部関数宣言 |
