# 機能設計書 255-imgui_impl_glfw

## 概要

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

### 本機能の処理概要

imgui_impl_glfwは、GLFWライブラリを使用してDear ImGuiにプラットフォーム機能を提供するクロスプラットフォームバックエンドモジュールである。マウス、キーボード、ゲームパッド入力の処理、マウスカーソル形状の制御、クリップボードアクセスなどを実装する。

**業務上の目的・背景**：
GLFWは、OpenGL、Vulkan、WebGPU等のグラフィックスAPIとウィンドウ管理を抽象化するクロスプラットフォームライブラリである。本バックエンドは、Windows、macOS、Linux、Emscripten等の複数プラットフォームで統一的なImGuiインテグレーションを提供する。

**機能の利用シーン**：
- OpenGL/Vulkan/WebGPUを使用するクロスプラットフォームアプリケーション
- GLFWベースのゲームエンジン
- Emscripten（WebAssembly）でのWeb公開
- 教育用途でのシンプルなグラフィックスアプリケーション

**主要な処理内容**：
1. バックエンドの初期化（ImGui_ImplGlfw_InitForOpenGL/Vulkan/Other）
2. 毎フレームの更新処理（ImGui_ImplGlfw_NewFrame）
3. GLFWコールバック処理（マウス、キーボード、スクロール等）
4. マウスカーソル形状の制御
5. ゲームパッド入力の処理
6. クリップボードアクセス
7. コンテンツスケール（DPI）対応

**関連システム・外部連携**：
- GLFWライブラリ（3.0以上、推奨3.3以上）
- 描画バックエンド（OpenGL3、Vulkan、WebGPU等）と併用
- プラットフォーム固有API（X11、Wayland、Win32、Cocoa）

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

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

#### ImGui_ImplGlfw_InitForOpenGL

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| window | GLFWwindow* | Yes | GLFWウィンドウハンドル | 有効なウィンドウ |
| install_callbacks | bool | Yes | コールバック自動インストール | - |

### 入力データソース

- GLFWイベントコールバック
- glfwGetTime()（時間計測）
- glfwGetGamepadState()（ゲームパッド状態、GLFW 3.3+）
- glfwGetClipboardString()/glfwSetClipboardString()（クリップボード）

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 初期化（ImGui_ImplGlfw_InitFor*）
   ├─ バックエンドデータ構造の確保
   ├─ ImGuiIO設定（バックエンド名、フラグ）
   ├─ Wayland検出
   ├─ クリップボードハンドラ設定
   ├─ マウスカーソル作成（GLFW 3.1+）
   ├─ コールバックインストール（オプション）
   └─ Windows向けWndProcフック（マウスソース識別用）
2. フレーム更新（ImGui_ImplGlfw_NewFrame）
   ├─ ウィンドウサイズ・フレームバッファスケール取得
   ├─ デルタタイム計算
   ├─ マウスデータ更新
   ├─ マウスカーソル形状更新
   └─ ゲームパッド状態更新
3. コールバック処理
   ├─ ImGui_ImplGlfw_MouseButtonCallback
   ├─ ImGui_ImplGlfw_ScrollCallback
   ├─ ImGui_ImplGlfw_KeyCallback
   ├─ ImGui_ImplGlfw_CharCallback
   ├─ ImGui_ImplGlfw_CursorPosCallback
   ├─ ImGui_ImplGlfw_CursorEnterCallback
   └─ ImGui_ImplGlfw_WindowFocusCallback
4. 終了処理（ImGui_ImplGlfw_Shutdown）
   ├─ コールバック復元
   ├─ マウスカーソル破棄
   ├─ Windows WndProcフック復元
   └─ バックエンドデータ解放
```

### フローチャート

```mermaid
flowchart TD
    A[ImGui_ImplGlfw_Init] --> B[glfwPollEvents]
    B --> C[GLFWコールバック処理]
    C --> D[ImGui_ImplGlfw_NewFrame]
    D --> E[ImGui処理]
    E --> F[描画]
    F --> B
    G[Shutdown] --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-255-01 | レンダラー併用必須 | 描画バックエンドと併用必須 | 常に適用 |
| BR-255-02 | GLFW初期化必須 | glfwInit()後に使用 | 初期化時 |
| BR-255-03 | コールバックチェーン | ユーザーコールバックをチェーン呼び出し | install_callbacks=true時 |
| BR-255-04 | マルチコンテキスト | GLFWウィンドウとImGuiContextのマッピング管理 | 複数コンテキスト時 |

### 計算ロジック

**フレームバッファスケール計算（X11）**:
```cpp
fb_scale_x = (w > 0) ? (float)display_w / (float)w : 1.0f;
fb_scale_y = (h > 0) ? (float)display_h / (float)h : 1.0f;
// Waylandでない場合は1.0f固定
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | カーソル作成失敗 | X11でカーソル未設定 | 矢印カーソルで代替 |
| - | 時間逆行 | glfwGetTime()が単調増加しない | 最小増分で対応 |

### リトライ仕様

リトライ機能なし。

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

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

## パフォーマンス要件

- NewFrame: O(1)（固定時間処理）
- コールバック: O(1)（イベント処理）
- 高フレームレート（10k+ FPS）でのカーソル更新最適化

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

- クリップボード操作はGLFW経由で安全に処理
- コールバックチェーンでユーザーコードを呼び出すため信頼性に注意

## 備考

- GLFW 3.0以上必須、3.3+/3.4+で全機能サポート
- Emscriptenでは特別な初期化が必要
- X11/Waylandの違いを自動検出
- 複数Dear ImGuiコンテキストのサポート（1.91.6+）

---

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

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

### 推奨読解順序

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

バックエンドデータ構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_impl_glfw.cpp | `backends/imgui_impl_glfw.cpp` | ImGui_ImplGlfw_Data構造体（199-233行目） |
| 1-2 | imgui_impl_glfw.cpp | `backends/imgui_impl_glfw.cpp` | コンテキストマッピング（185-189行目） |

**読解のコツ**: GLFWwindow*とImGuiContext*のマッピングはg_ContextMapで管理される。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_impl_glfw.h | `backends/imgui_impl_glfw.h` | 関数宣言（33-37行目） |
| 2-2 | imgui_impl_glfw.cpp | `backends/imgui_impl_glfw.cpp` | ImGui_ImplGlfw_Init実装（668-775行目） |

**主要処理フロー**:
1. **670-673行目**: ImGuiIOとバージョン確認
2. **676-679行目**: バックエンドデータ確保とフラグ設定
3. **691-698行目**: クリップボードハンドラ設定
4. **708-727行目**: マウスカーソル作成
5. **733-734行目**: コールバックインストール

#### Step 3: フレーム更新処理を理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_impl_glfw.cpp | `backends/imgui_impl_glfw.cpp` | ImGui_ImplGlfw_NewFrame実装（1002-1024行目） |

**主要処理フロー**:
- **1009行目**: ウィンドウサイズ・フレームバッファスケール取得
- **1013-1017行目**: デルタタイム計算（単調増加保証）
- **1019行目**: マウスデータ更新
- **1020行目**: マウスカーソル更新
- **1023行目**: ゲームパッド更新

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_impl_glfw.cpp | `backends/imgui_impl_glfw.cpp` | ImGui_ImplGlfw_KeyCallback（480-497行目） |
| 4-2 | imgui_impl_glfw.cpp | `backends/imgui_impl_glfw.cpp` | ImGui_ImplGlfw_MouseButtonCallback（419-429行目） |

**主要処理フロー**:
- **421-423行目**: ユーザーコールバックチェーン
- **425-428行目**: ImGuiへのイベント伝達

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

```
アプリケーション
    │
    ├─ glfwInit()
    │
    ├─ ImGui_ImplGlfw_InitForOpenGL(window, install_callbacks)
    │      ├─ ImGui_ImplGlfw_Init
    │      │      ├─ クリップボードハンドラ設定
    │      │      ├─ マウスカーソル作成
    │      │      └─ ImGui_ImplGlfw_InstallCallbacks (オプション)
    │      └─ コンテキストマッピング登録
    │
    ├─ メインループ
    │      ├─ glfwPollEvents()
    │      │      └─ GLFWコールバック
    │      │              ├─ ImGui_ImplGlfw_KeyCallback
    │      │              ├─ ImGui_ImplGlfw_MouseButtonCallback
    │      │              ├─ ImGui_ImplGlfw_ScrollCallback
    │      │              └─ ImGui_ImplGlfw_CharCallback
    │      │
    │      └─ ImGui_ImplGlfw_NewFrame
    │              ├─ ImGui_ImplGlfw_UpdateMouseData
    │              ├─ ImGui_ImplGlfw_UpdateMouseCursor
    │              └─ ImGui_ImplGlfw_UpdateGamepads
    │
    └─ ImGui_ImplGlfw_Shutdown
           ├─ ImGui_ImplGlfw_RestoreCallbacks
           ├─ カーソル破棄
           └─ コンテキストマッピング解除
```

### データフロー図

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

GLFWコールバック ─────────▶ コールバック関数 ───────▶ ImGuiIO入力イベント
glfwGetTime() ───────────▶ NewFrame ──────────────▶ ImGuiIO.DeltaTime
glfwGetWindowSize() ─────▶ NewFrame ──────────────▶ ImGuiIO.DisplaySize
glfwGetFramebufferSize() ▶ NewFrame ──────────────▶ ImGuiIO.DisplayFramebufferScale
glfwGetGamepadState() ───▶ UpdateGamepads ────────▶ ImGuiIO入力イベント
```

### 関連ファイル一覧

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