# 機能設計書 124-InputFloat2/3/4

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける複数要素浮動小数点数入力機能「InputFloat2」「InputFloat3」「InputFloat4」の設計仕様を定義する。

### 本機能の処理概要

InputFloat2/3/4は、2〜4個の浮動小数点数（float）を水平に並べて一度に入力・編集するためのウィジェット関数群である。ベクトルや座標、カラー値など、複数の関連する数値を効率的に編集できる。

**業務上の目的・背景**：GUIアプリケーションにおいて、2D/3D座標（X,Y,Z）、カラー値（RGB/RGBA）、矩形（Left,Top,Right,Bottom）など、複数の関連する浮動小数点数をまとめて編集する場面は頻繁に発生する。InputFloat2/3/4は、これらの値を単一のウィジェットとしてまとめて表示・編集することで、UIのコンパクト化とユーザー操作の効率化を実現する。

**機能の利用シーン**：
- 2D座標の入力（InputFloat2: X, Y）
- 3D座標の入力（InputFloat3: X, Y, Z）
- RGBカラーの入力（InputFloat3: R, G, B）
- RGBAカラーの入力（InputFloat4: R, G, B, A）
- 矩形パラメータの入力（InputFloat4: Left, Top, Right, Bottom）
- クォータニオンの入力（InputFloat4: X, Y, Z, W）

**主要な処理内容**：
1. 指定された数の浮動小数点入力フィールドを水平に配置する
2. 各フィールドの幅を自動的に均等に分配する
3. フォーマット文字列に従って各数値を表示する
4. 複数フィールドをグループとして管理し、統一されたIDを提供する

**関連システム・外部連携**：内部でInputScalarNを呼び出しており、データ型としてImGuiDataType_Floatを使用する。

**権限による制御**：ImGuiInputTextFlags_ReadOnlyフラグにより読み取り専用モードを指定可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 参照画面 | InputFloat2/3/4のデモ表示 |
| 23 | Widgets | 参照画面 | ウィジェットデモでの表示 |

## 機能種別

数値入力ウィジェット / 複数要素対応

## 入力仕様

### 入力パラメータ（InputFloat2）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| v | float[2] | Yes | 編集対象の2要素float配列 | NULL不可 |
| format | const char* | No | 表示フォーマット文字列（デフォルト: "%.3f"） | printf形式 |
| flags | ImGuiInputTextFlags | No | 入力動作を制御するフラグ | - |

### 入力パラメータ（InputFloat3）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| v | float[3] | Yes | 編集対象の3要素float配列 | NULL不可 |
| format | const char* | No | 表示フォーマット文字列（デフォルト: "%.3f"） | printf形式 |
| flags | ImGuiInputTextFlags | No | 入力動作を制御するフラグ | - |

### 入力パラメータ（InputFloat4）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットの識別ラベル | NULL不可 |
| v | float[4] | Yes | 編集対象の4要素float配列 | NULL不可 |
| format | const char* | No | 表示フォーマット文字列（デフォルト: "%.3f"） | printf形式 |
| flags | ImGuiInputTextFlags | No | 入力動作を制御するフラグ | - |

### 入力データソース

ユーザーが提供するfloat型配列へのポインタ（v）を直接編集する。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | いずれかの値が変更された場合にtrue |
| v[] | float[] | 編集された浮動小数点数値の配列 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. InputFloat2/3/4呼び出し
   └─ 要素数（2, 3, 4）を決定
2. InputScalarNを呼び出し
   └─ ImGuiDataType_Float、要素数、formatを渡す
3. グループ開始
   └─ BeginGroup()でウィジェットをグループ化
4. 各要素のフィールド描画
   └─ PushMultiItemsWidths()で幅を均等分配
   └─ 各要素に対してInputScalar()を呼び出し
5. ラベル描画
   └─ 末尾にテキストラベルを表示
6. グループ終了
   └─ EndGroup()でグループ終了
7. 値変更の検出と戻り値の決定
   └─ いずれかの値が変更された場合はtrueを返す
```

### フローチャート

```mermaid
flowchart TD
    A[InputFloat2/3/4開始] --> B[InputScalarN呼び出し]
    B --> C[BeginGroup]
    C --> D[PushMultiItemsWidths]
    D --> E[要素ループ開始]
    E --> F[InputScalar呼び出し]
    F --> G{最後の要素?}
    G -->|No| H[SameLine]
    H --> F
    G -->|Yes| I[ラベル描画]
    I --> J[EndGroup]
    J --> K{いずれか変更?}
    K -->|Yes| L[true返却]
    K -->|No| M[false返却]
    L --> N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 幅の均等分配 | 各入力フィールドの幅は利用可能なスペースを均等に分配 | 常に適用 |
| BR-02 | ステップボタンなし | InputFloat2/3/4では+/-ボタンは表示されない | 常に適用 |
| BR-03 | 統合戻り値 | いずれかの要素が変更された場合にtrueを返す | 常に適用 |
| BR-04 | デフォルトフォーマット | formatがNULLの場合、"%.3f"が使用される | 常に適用 |

### 計算ロジック

フィールド幅の計算: `(総幅 - 間隔 * (要素数-1)) / 要素数`

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パースエラー | 無効な数値文字列入力 | 該当要素の値は変更されない |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

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

## 備考

- +/-ボタンが必要な場合は、個別のInputFloatを複数配置するか、カスタム実装が必要
- カラー編集の場合はColorEdit3/4の使用を推奨（カラーピッカー付き）
- 連続的な調整が必要な場合は、DragFloat2/3/4やSliderFloat2/3/4の使用を検討

---

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

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

### 推奨読解順序

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

データ型の定義を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiDataType_Float（データ型定義）を確認 |

**読解のコツ**: InputFloat2/3/4はInputScalarNの薄いラッパーであり、要素数を指定して呼び出す。

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

処理の起点となるInputFloat2/3/4関数を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（行718-720）。3つの関数が同じパターン |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputFloat2実装（行3893-3896） |
| 2-3 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputFloat3実装（行3898-3901） |
| 2-4 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputFloat4実装（行3903-3906） |

**主要処理フロー**:
1. **行3895**: InputFloat2はInputScalarN(label, Float, v, 2, ...)を呼び出し
2. **行3900**: InputFloat3はInputScalarN(label, Float, v, 3, ...)を呼び出し
3. **行3905**: InputFloat4はInputScalarN(label, Float, v, 4, ...)を呼び出し

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

InputScalarNの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | InputScalarN実装（行3853-3886）。複数要素のループ処理 |

**主要処理フロー**:
- **行3861**: BeginGroup()でグループ化開始
- **行3863**: PushMultiItemsWidths()で各フィールドの幅を計算
- **行3865-3874**: 各要素に対してInputScalar()をループ呼び出し
- **行3877-3882**: ラベル描画
- **行3884**: EndGroup()でグループ終了

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

```
ImGui::InputFloat2/3/4()
    │
    └─ ImGui::InputScalarN()
           │
           ├─ BeginGroup()
           │
           ├─ PushMultiItemsWidths()
           │
           ├─ [要素数分ループ]
           │      │
           │      ├─ PushID(i)
           │      ├─ SameLine() [i > 0の場合]
           │      ├─ InputScalar()
           │      └─ PopID()
           │
           ├─ TextEx() [ラベル表示]
           │
           └─ EndGroup()
```

### データフロー図

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

float v[N]     ───▶  InputFloat2/3/4()
(N要素配列)            │
                       ▼
               InputScalarN()
                       │
                       ├─ v[0] ─▶ InputScalar() ─▶ v[0]更新
                       ├─ v[1] ─▶ InputScalar() ─▶ v[1]更新
                       ├─ v[2] ─▶ InputScalar() ─▶ v[2]更新 (3/4のみ)
                       └─ v[3] ─▶ InputScalar() ─▶ v[3]更新 (4のみ)
                       │
                       ▼
               bool (変更有無) ───▶ 戻り値
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言（行718-720） |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | InputFloat2/3/4、InputScalarNの実装 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | デモ実装（行937, 1940, 1948, 1956等） |
