# 機能設計書 258-imgui_impl_glut

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるGLUT/FreeGLUTプラットフォームバックエンド（imgui_impl_glut）の設計仕様を定義する。

### 本機能の処理概要

imgui_impl_glutは、GLUT（OpenGL Utility Toolkit）およびFreeGLUTライブラリを使用してDear ImGuiに基本的なプラットフォーム機能を提供するバックエンドモジュールである。部分的なキーボードサポート、マウス入力処理を実装するが、GLUTの制約により機能は限定的である。

**業務上の目的・背景**：
GLUTは1990年代に開発されたOpenGLのユーティリティツールキットであり、教育目的や非常に単純なアプリケーションでのみ使用が推奨される。本バックエンドは、レガシーコードベースやGLUTを使用せざるを得ない環境でのImGui統合を可能にする。

**機能の利用シーン**：
- 教育目的でのOpenGL学習環境
- レガシーGLUTアプリケーションの移行
- 最小限のセットアップを求める単純なデモ

**主要な処理内容**：
1. バックエンドの初期化（ImGui_ImplGLUT_Init）
2. GLUTコールバックのインストール（ImGui_ImplGLUT_InstallFuncs）
3. 毎フレームの更新処理（ImGui_ImplGLUT_NewFrame）
4. キーボード入力処理（通常キーおよび特殊キー）
5. マウス入力処理（位置、ボタン、ホイール）
6. ウィンドウリサイズ処理

**関連システム・外部連携**：
- GLUT/FreeGLUTライブラリ
- 描画バックエンド（OpenGL2等）と併用

**権限による制御**：
特別な権限は不要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 全てのImGuiウィンドウの基盤として機能 |

## 機能種別

プラットフォームバックエンド

## 入力仕様

### 入力パラメータ

#### ImGui_ImplGLUT_Init

パラメータなし。

#### ImGui_ImplGLUT_KeyboardFunc

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| c | unsigned char | Yes | 文字コード | 0-255 |
| x | int | Yes | マウスX座標 | - |
| y | int | Yes | マウスY座標 | - |

### 入力データソース

- GLUTコールバック（キーボード、マウス、リサイズ）
- glutGet(GLUT_ELAPSED_TIME)（時間計測）
- glutGetModifiers()（修飾キー状態）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ImGuiIO.DisplaySize | ImVec2 | ウィンドウサイズ |
| ImGuiIO.DeltaTime | float | フレーム間隔 |
| ImGuiIO（入力イベント） | - | マウス/キーボードイベント |

### 出力先

ImGuiIO構造体への入力イベント登録

## 処理フロー

### 処理シーケンス

```
1. 初期化（ImGui_ImplGLUT_Init）
   ├─ ImGuiIO設定（バックエンド名）
   └─ 時間変数初期化
2. コールバックインストール（ImGui_ImplGLUT_InstallFuncs）
   ├─ glutReshapeFunc設定
   ├─ glutMotionFunc/glutPassiveMotionFunc設定
   ├─ glutMouseFunc設定
   ├─ glutMouseWheelFunc設定（FreeGLUT）
   ├─ glutKeyboardFunc/glutKeyboardUpFunc設定
   └─ glutSpecialFunc/glutSpecialUpFunc設定
3. フレーム更新（ImGui_ImplGLUT_NewFrame）
   ├─ 経過時間取得
   └─ デルタタイム計算
4. コールバック処理
   ├─ ImGui_ImplGLUT_ReshapeFunc（ウィンドウサイズ）
   ├─ ImGui_ImplGLUT_MotionFunc（マウス移動）
   ├─ ImGui_ImplGLUT_MouseFunc（マウスボタン）
   ├─ ImGui_ImplGLUT_MouseWheelFunc（マウスホイール）
   ├─ ImGui_ImplGLUT_KeyboardFunc（通常キー押下）
   ├─ ImGui_ImplGLUT_KeyboardUpFunc（通常キー解放）
   ├─ ImGui_ImplGLUT_SpecialFunc（特殊キー押下）
   └─ ImGui_ImplGLUT_SpecialUpFunc（特殊キー解放）
5. 終了処理（ImGui_ImplGLUT_Shutdown）
   └─ バックエンド名クリア
```

### フローチャート

```mermaid
flowchart TD
    A[ImGui_ImplGLUT_Init] --> B[ImGui_ImplGLUT_InstallFuncs]
    B --> C[glutMainLoop]
    C --> D[GLUTコールバック]
    D --> E[ImGui_ImplGLUT_NewFrame]
    E --> F[ImGui処理]
    F --> G[描画]
    G --> C
    H[Shutdown] --> I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-258-01 | レンダラー併用必須 | 描画バックエンドと併用必須 | 常に適用 |
| BR-258-02 | GLUT初期化必須 | glutInit()後に使用 | 初期化時 |
| BR-258-03 | コールバック設定 | InstallFuncsで自動設定または手動設定 | 初期化時 |
| BR-258-04 | レガシー非推奨 | GLUTは非推奨、GLFW/SDL推奨 | 常に |

### 計算ロジック

**デルタタイム計算**:
```cpp
int current_time = glutGet(GLUT_ELAPSED_TIME);
int delta_time_ms = (current_time - g_Time);
if (delta_time_ms <= 0)
    delta_time_ms = 1;
io.DeltaTime = delta_time_ms / 1000.0f;
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------||
| - | キー区別不可 | BackspaceとCTRL+H等 | 仕様上の制限 |
| - | 時間逆行 | GLUT_ELAPSED_TIMEが減少 | 最小増分で対応 |

### リトライ仕様

リトライ機能なし。

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

トランザクション管理なし

## パフォーマンス要件

- コールバック: O(1)（イベント処理）
- NewFrame: O(1)（固定時間処理）

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

- クリップボードサポートなし（GLUTの制限）
- 入力処理はGLUT経由で実行

## 備考

- GLUTは非推奨であり、GLFW/SDLの使用を推奨
- 水平マウスホイール非対応
- マウスカーソル形状変更非対応
- クリップボード非対応
- ゲームパッド非対応
- FreeGLUTでのみマウスホイール対応（__FREEGLUT_EXT_H__）

---

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

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

### 推奨読解順序

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

グローバル変数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_impl_glut.cpp | `backends/imgui_impl_glut.cpp` | グローバル変数g_Time（51行目） |

**読解のコツ**: GLUTバックエンドは状態をグローバル変数で管理するシンプルな構造。

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

初期化関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_impl_glut.h | `backends/imgui_impl_glut.h` | 関数宣言（30-33行目） |
| 2-2 | imgui_impl_glut.cpp | `backends/imgui_impl_glut.cpp` | ImGui_ImplGLUT_Init実装（167-180行目） |

**主要処理フロー**:
1. **169-170行目**: ImGuiIOとバージョン確認
2. **172-176行目**: バックエンド名設定（FreeGLUT判定）
3. **177行目**: 時間変数初期化

#### Step 3: コールバックインストールを理解する

InstallFuncs関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_impl_glut.cpp | `backends/imgui_impl_glut.cpp` | ImGui_ImplGLUT_InstallFuncs実装（182-195行目） |

**主要処理フロー**:
- **184-187行目**: マウス関連コールバック設定
- **188-189行目**: FreeGLUTのみマウスホイール設定
- **191-194行目**: キーボード関連コールバック設定

#### Step 4: コールバック処理を理解する

各コールバック関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_impl_glut.cpp | `backends/imgui_impl_glut.cpp` | ImGui_ImplGLUT_KeyboardFunc（231-243行目） |
| 4-2 | imgui_impl_glut.cpp | `backends/imgui_impl_glut.cpp` | ImGui_ImplGLUT_MouseFunc（272-282行目） |
| 4-3 | imgui_impl_glut.cpp | `backends/imgui_impl_glut.cpp` | ImGui_ImplGLUT_ReshapeFunc（295-299行目） |

**主要処理フロー**:
- **236-237行目**: 文字入力処理（ASCII 32以上）
- **239-241行目**: キーイベントとネイティブデータ設定
- **277-281行目**: マウスボタンイベント処理

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

```
アプリケーション
    │
    ├─ glutInit()
    ├─ glutCreateWindow()
    │
    ├─ ImGui_ImplGLUT_Init()
    │      └─ バックエンド名設定
    │
    ├─ ImGui_ImplGLUT_InstallFuncs()
    │      ├─ glutReshapeFunc → ImGui_ImplGLUT_ReshapeFunc
    │      ├─ glutMotionFunc → ImGui_ImplGLUT_MotionFunc
    │      ├─ glutPassiveMotionFunc → ImGui_ImplGLUT_MotionFunc
    │      ├─ glutMouseFunc → ImGui_ImplGLUT_MouseFunc
    │      ├─ glutMouseWheelFunc → ImGui_ImplGLUT_MouseWheelFunc
    │      ├─ glutKeyboardFunc → ImGui_ImplGLUT_KeyboardFunc
    │      ├─ glutKeyboardUpFunc → ImGui_ImplGLUT_KeyboardUpFunc
    │      ├─ glutSpecialFunc → ImGui_ImplGLUT_SpecialFunc
    │      └─ glutSpecialUpFunc → ImGui_ImplGLUT_SpecialUpFunc
    │
    ├─ glutMainLoop()
    │      ├─ GLUTコールバック呼び出し
    │      │      ├─ io.AddMousePosEvent
    │      │      ├─ io.AddMouseButtonEvent
    │      │      ├─ io.AddKeyEvent
    │      │      └─ io.AddInputCharacter
    │      │
    │      └─ ImGui_ImplGLUT_NewFrame
    │              └─ デルタタイム計算
    │
    └─ ImGui_ImplGLUT_Shutdown
           └─ バックエンド名クリア
```

### データフロー図

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

GLUTコールバック ──────────▶ コールバック関数 ───────▶ ImGuiIO入力イベント
glutGet(GLUT_ELAPSED_TIME) ▶ NewFrame ──────────────▶ ImGuiIO.DeltaTime
glutReshapeFunc ───────────▶ ReshapeFunc ────────────▶ ImGuiIO.DisplaySize
glutGetModifiers() ────────▶ UpdateKeyModifiers ─────▶ ImGuiIO修飾キー
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_impl_glut.h | `backends/imgui_impl_glut.h` | ヘッダー | 関数宣言 |
| imgui_impl_glut.cpp | `backends/imgui_impl_glut.cpp` | ソース | 実装 |
| imgui.h | `imgui.h` | ヘッダー | ImGuiIO定義 |
