# 機能設計書 112-SliderFloat

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける浮動小数点スライダー機能「SliderFloat」の設計を詳細に記述したものである。

### 本機能の処理概要

SliderFloatは、単精度浮動小数点数（float型）の値を視覚的なスライダーインターフェースで調整するウィジェットを作成する機能である。マウスでスライダーのグラブ（つまみ）をドラッグするか、スライダー上の任意の位置をクリックすることで値を設定できる。

**業務上の目的・背景**：ゲーム開発やグラフィックスツール開発において、0.0から1.0のアルファ値、角度、スケール値など、特定の範囲内で浮動小数点数を調整する場面は非常に多い。SliderFloatは直感的で精密な数値調整インターフェースを提供し、開発者とエンドユーザー双方の生産性を向上させる。ドラッグスライダー（DragFloat）との違いは、スライダーには明確な最小値と最大値があり、グラブの位置で現在の値が視覚的に分かる点である。

**機能の利用シーン**：
- 色のRGBA各成分（0.0〜1.0）を調整するとき
- オブジェクトのスケール値や透明度を設定するとき
- 音量やエフェクトの強度パラメータを調整するとき
- 物理シミュレーションのパラメータ（重力、摩擦係数など）を設定するとき

**主要な処理内容**：
1. ウィンドウとスタイルの取得、ウィジェットIDの生成
2. フレーム領域とラベル領域の計算
3. マウスホバーとクリック検出によるアクティブ状態の制御
4. Ctrl+クリックでテキスト入力モードへ切り替え
5. SliderScalar関数の呼び出し（float型を指定）
6. グラブ（つまみ）の位置計算と描画

**関連システム・外部連携**：本機能は単体で動作し、外部システムとの直接的な連携はない。内部的にSliderScalarを呼び出し、SliderScalarはさらにSliderBehaviorを使用する。

**権限による制御**：ImGuiItemFlags_ReadOnlyフラグまたはImGuiSliderFlags_ReadOnlyフラグにより読み取り専用モードを設定可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 補助機能 | 各種スライダーの表示デモ |
| 6 | Style Editor | 補助機能 | スタイル値の調整スライダー |
| 15 | Auto Resize | 補助機能 | 行数調整スライダー |
| 23 | Widgets | 主機能 | スライダーウィジェットのデモ |

## 機能種別

インタラクティブウィジェット / ユーザー入力処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットのラベル（ID生成にも使用） | NULL不可 |
| v | float* | Yes | 編集対象の値へのポインタ | NULL不可 |
| v_min | float | Yes | スライダーの最小値 | v_max未満を推奨 |
| v_max | float | Yes | スライダーの最大値 | v_min超を推奨 |
| format | const char* | No | 表示フォーマット文字列（デフォルト: "%.3f"） | printf形式 |
| flags | ImGuiSliderFlags | No | 動作制御フラグ（デフォルト: 0） | 有効なフラグの組み合わせ |

### 入力データソース

ユーザーからのマウス操作（クリック・ドラッグ）およびキーボード入力（テキスト入力モード時、矢印キーによる微調整）。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | 値が変更された場合true |
| *v | float | 更新されたスライダー値 |

### 出力先

呼び出し元への戻り値、およびvが指すメモリ領域への値の書き込み。

## 処理フロー

### 処理シーケンス

```
1. SliderScalarを呼び出し
   └─ data_type = ImGuiDataType_Float, p_min = &v_min, p_max = &v_max
2. SliderScalar内部処理
   ├─ ウィンドウ取得とスキップ判定
   ├─ ID生成と領域計算
   ├─ ItemSizeとItemAddの呼び出し
   ├─ ホバー・クリック検出とアクティブ状態制御
   ├─ テキスト入力モードの判定と処理
   ├─ フレームの描画
   ├─ SliderBehaviorの呼び出し（グラブ位置計算と値更新）
   ├─ グラブの描画
   └─ 値とラベルの表示
3. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[SliderFloat呼び出し] --> B[SliderScalar呼び出し]
    B --> C{window->SkipItems?}
    C -->|Yes| D[return false]
    C -->|No| E[ID生成と領域計算]
    E --> F[ItemSize/ItemAdd]
    F --> G{ItemAdd成功?}
    G -->|No| D
    G -->|Yes| H[ホバー・クリック検出]
    H --> I{テキスト入力モード?}
    I -->|Yes| J[TempInputScalar]
    J --> K[return 結果]
    I -->|No| L[フレーム描画]
    L --> M[SliderBehavior]
    M --> N[グラブ描画]
    N --> O[値とラベル表示]
    O --> P[return value_changed]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-112-1 | 範囲制限 | 値は常にv_minとv_maxの範囲内に制限される | 常時 |
| BR-112-2 | グラブ位置 | グラブの位置は値の比率（0.0〜1.0）に比例する | 線形モード時 |
| BR-112-3 | 対数スケール | Logarithmicフラグ設定時、対数スケールでグラブ位置を計算 | Logarithmicフラグ設定時 |
| BR-112-4 | 精度表示 | デフォルトで小数点以下3桁を表示 | format未指定時 |
| BR-112-5 | テキスト入力クランプ | AlwaysClampフラグ設定時、テキスト入力値も範囲内にクランプ | AlwaysClampフラグ設定時 |

### 計算ロジック

グラブ位置から値への変換：

```
線形モード:
  t = (mouse_pos - slider_min) / slider_usable_sz  // 0.0〜1.0の比率
  value = v_min + t * (v_max - v_min)

対数モード:
  value = ScaleValueFromRatioT(t, v_min, v_max, is_logarithmic, ...)
```

値からグラブ位置への変換：

```
線形モード:
  grab_t = (value - v_min) / (v_max - v_min)
  grab_pos = slider_usable_pos_min + grab_t * slider_usable_sz

対数モード:
  grab_t = ScaleRatioFromValueT(value, v_min, v_max, is_logarithmic, ...)
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | 無効なImGuiSliderFlagsが渡された場合 | 正しいフラグ値を使用する |
| - | アサーション | WrapAroundフラグが設定された場合 | SliderではWrapAroundは非対応 |
| - | アサーション | v_min/v_maxが型の限界値の半分を超える場合 | 適切な範囲を設定する |

### リトライ仕様

本機能はユーザー入力ウィジェットであり、リトライは適用されない。

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

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

## パフォーマンス要件

フレームごとに呼び出されるため、軽量な処理が求められる。SliderScalarは単純なラッパーであり、オーバーヘッドは最小限。

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

- format文字列の検証は呼び出し側の責任
- 値の範囲外入力はAlwaysClampフラグで防止可能

## 備考

- SliderFloat2/3/4は複数コンポーネント版で、内部でSliderScalarNを呼び出す
- 垂直スライダーが必要な場合はVSliderFloatを使用する

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | SliderFloat関数宣言（696行目）とImGuiSliderFlags定義 |

**読解のコツ**: SliderFloatはv_min/v_maxが必須パラメータであることに注目。DragFloatとの違いは明確な範囲が必要な点。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderFloat関数の実装（3423-3426行目） |

**主要処理フロー**:
1. **3423-3426行目**: SliderScalarへの単純なラッパー呼び出し

#### Step 3: 実際の処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderScalar関数（3295-3383行目） |
| 3-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderBehavior関数（3257-3291行目） |
| 3-3 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderBehaviorTテンプレート（3080-3252行目） |

**主要処理フロー**:
- **3297-3299行目**: ウィンドウ取得とスキップ判定
- **3307-3309行目**: フレーム領域の計算
- **3320-3344行目**: ホバー・クリック検出とアクティブ状態制御
- **3346-3351行目**: テキスト入力モードの処理
- **3361-3365行目**: SliderBehavior呼び出しと編集マーク
- **3367-3369行目**: グラブの描画

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

```
SliderFloat (imgui_widgets.cpp:3423)
    │
    └─ SliderScalar (imgui_widgets.cpp:3295)
           │
           ├─ GetCurrentWindow()
           ├─ CalcTextSize()
           ├─ ItemSize() / ItemAdd()
           ├─ ItemHoverable()
           │
           ├─ TempInputScalar() [テキスト入力モード時]
           │
           ├─ RenderNavCursor() / RenderFrame()
           │
           └─ SliderBehavior (imgui_widgets.cpp:3257)
                  └─ SliderBehaviorT<float> (imgui_widgets.cpp:3080)
                         ├─ ScaleRatioFromValueT()
                         ├─ ScaleValueFromRatioT()
                         └─ RoundScalarWithFormatT()
```

### データフロー図

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

v (値へのポインタ)
v_min, v_max
       │
       ▼
マウスクリック ────────▶ SliderBehavior ───────▶ 更新された値 (*v)
マウスドラッグ                │
       │                     ▼
       │              グラブ位置計算 ─────────▶ グラブ描画
       │
Ctrl+Click ──────────▶ TempInputScalar ────▶ テキスト入力による値
       │
       ▼
format ──────────────▶ 値のフォーマット ────▶ 値の表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | SliderFloat関数宣言、ImGuiSliderFlags定義 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | 内部関数宣言 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | SliderFloat/SliderScalar/SliderBehaviorの実装 |
