# 機能設計書 116-SliderInt2/3/4

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける複数要素の整数スライダー機能「SliderInt2」「SliderInt3」「SliderInt4」の設計を詳細に記述したものである。

### 本機能の処理概要

SliderInt2/3/4は、2〜4個の整数（int型）を1行にまとめて表示・編集できるスライダーウィジェット群である。各コンポーネントは独立したスライダーとして動作し、整数ベクトルやピクセル座標の編集に適している。

**業務上の目的・背景**：ゲーム開発やグラフィックスプログラミングにおいて、ピクセル座標（x,y）、タイルインデックス（row,col）、解像度（width,height）など、複数の整数値をまとめて管理する場面は非常に多い。SliderInt2/3/4はこれらの値を効率的に編集するための統合インターフェースを提供する。

**機能の利用シーン**：
- 2D座標（x,y）のピクセル単位での編集（SliderInt2）
- 3Dグリッド座標やインデックスの編集（SliderInt3）
- 矩形領域（left,top,right,bottom）の編集（SliderInt4）
- 複数の整数カウンタを一括で調整したいとき

**主要な処理内容**：
1. SliderScalarNを呼び出し（components数を2/3/4で指定）
2. SliderScalarN内部でグループ化開始
3. 各コンポーネントに対してSliderScalarを繰り返し呼び出し
4. コンポーネント間のレイアウト調整（SameLineで水平配置）
5. グループ化終了とラベル表示

**関連システム・外部連携**：本機能は単体で動作し、外部システムとの直接的な連携はない。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 23 | Widgets | 主機能 | スライダーウィジェットのデモ表示 |

## 機能種別

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

## 入力仕様

### 入力パラメータ（SliderInt2の場合）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| label | const char* | Yes | ウィジェットのラベル | NULL不可 |
| v | int[2] | Yes | 編集対象の2要素配列 | NULL不可 |
| v_min | int | Yes | スライダーの最小値 | 任意 |
| v_max | int | Yes | スライダーの最大値 | 任意 |
| format | const char* | No | 表示フォーマット文字列（デフォルト: "%d"） | printf形式 |
| flags | ImGuiSliderFlags | No | 動作制御フラグ（デフォルト: 0） | 有効なフラグの組み合わせ |

### 入力パラメータ（SliderInt3/4も同様の構造）

配列サイズがそれぞれint[3]、int[4]となる点のみ異なる。

### 入力データソース

ユーザーからのマウス操作（クリック・ドラッグ）およびキーボード入力。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | いずれかの値が変更された場合true |
| v[0..n] | int | 更新されたスライダー値（配列の各要素） |

### 出力先

呼び出し元への戻り値、およびvが指す配列への値の書き込み。

## 処理フロー

### 処理シーケンス

```
1. SliderScalarNを呼び出し
   └─ components = 2/3/4, data_type = ImGuiDataType_S32
2. SliderScalarN内部処理（SliderFloat2/3/4と同様）
   ├─ BeginGroup()
   ├─ PushID(label)
   ├─ PushMultiItemsWidths()
   ├─ ループ: SliderScalar × components回
   ├─ PopID()
   ├─ ラベル表示
   └─ EndGroup()
3. 結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[SliderInt2/3/4呼び出し] --> B[SliderScalarN呼び出し]
    B --> C{window->SkipItems?}
    C -->|Yes| D[return false]
    C -->|No| E[BeginGroup/PushID]
    E --> F[コンポーネントループ]
    F --> G[SliderScalar × n回]
    G --> H[PopID/ラベル表示]
    H --> I[EndGroup]
    I --> J[return value_changed]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-116-1 | 統一範囲 | 全コンポーネントに同じv_min/v_maxが適用される | 常時 |
| BR-116-2 | 独立変更 | 各コンポーネントは独立して変更可能 | 常時 |
| BR-116-3 | 整数単位 | 各コンポーネントは整数単位でのみ変化する | 常時 |
| BR-116-4 | 戻り値統合 | いずれかのコンポーネントが変更されればtrueを返す | 常時 |

### 計算ロジック

SliderFloat2/3/4と同様の構造だが、内部でImGuiDataType_S32を使用して整数処理を行う。

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション | 無効なフラグが渡された場合 | 正しいフラグ値を使用する |

### リトライ仕様

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

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

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

## パフォーマンス要件

フレームごとに呼び出されるため、軽量な処理が求められる。

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

- format文字列の検証は呼び出し側の責任

## 備考

- 各コンポーネントに異なる範囲を設定したい場合は、個別にSliderIntを呼び出す必要がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | SliderInt2/3/4関数宣言（702-704行目） |
| 1-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderInt2関数（3459-3462行目） |
| 1-3 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderInt3関数（3464-3467行目） |
| 1-4 | imgui_widgets.cpp | `imgui_widgets.cpp` | SliderInt4関数（3469-3472行目） |

**主要処理フロー**:
- 各関数は単にSliderScalarNを呼び出すワンライナー
- ImGuiDataType_S32を指定し、components引数が2/3/4と異なるのみ

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

```
SliderInt2/3/4 (imgui_widgets.cpp:3459-3472)
    │
    └─ SliderScalarN (imgui_widgets.cpp:3385)
           │
           ├─ BeginGroup()
           ├─ PushID(label)
           ├─ PushMultiItemsWidths(components, ...)
           │
           ├─ [ループ: i = 0 to components-1]
           │     └─ SliderScalar("", ImGuiDataType_S32, v, ...)
           │            └─ SliderBehavior(...)
           │
           ├─ PopID()
           ├─ TextEx(label)
           └─ EndGroup()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | SliderInt2/3/4関数宣言 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | SliderInt2/3/4/SliderScalarNの実装 |
