# 機能設計書 254-imgui_impl_win32

## 概要

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

### 本機能の処理概要

imgui_impl_win32は、Windows APIを使用してDear ImGuiにプラットフォーム機能を提供するバックエンドモジュールである。マウス、キーボード、ゲームパッド入力の処理、マウスカーソル形状の制御、DPIスケーリング対応などを実装する。

**業務上の目的・背景**：
Dear ImGuiは描画とプラットフォーム機能を分離したアーキテクチャを採用している。Windows環境でImGuiを使用するには、Windows固有の入力処理やウィンドウ管理をImGuiに伝える必要がある。本バックエンドは、Windows APIとDear ImGuiの橋渡し役として、32bit/64bitの両アプリケーションで動作する統一的なインターフェースを提供する。

**機能の利用シーン**：
- DirectX9/10/11/12を使用するWindowsアプリケーション
- OpenGL/Vulkanを使用するWindowsアプリケーション
- Windowsネイティブアプリケーションでのツール/エディタUI
- ゲームエンジンのエディタやデバッグUI

**主要な処理内容**：
1. バックエンドの初期化（ImGui_ImplWin32_Init）
2. 毎フレームの更新処理（ImGui_ImplWin32_NewFrame）
3. Windowsメッセージの処理（ImGui_ImplWin32_WndProcHandler）
4. マウスカーソル形状の制御
5. ゲームパッド入力の処理（XInput経由）
6. DPIスケーリング対応
7. アルファ合成による透過ウィンドウ対応

**関連システム・外部連携**：
- Windows API（user32.dll、kernel32.dll）
- XInput（ゲームパッドサポート）
- DWM API（アルファ合成）
- 描画バックエンド（DirectX、OpenGL、Vulkan等）と併用

**権限による制御**：
特別な権限は不要。DPIスケーリング機能はマニフェストでの設定または動的呼び出しで有効化。

## 関連画面

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

## 機能種別

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

## 入力仕様

### 入力パラメータ

#### ImGui_ImplWin32_Init

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| hwnd | void* (HWND) | Yes | メインウィンドウのハンドル | 有効なウィンドウハンドル |

#### ImGui_ImplWin32_WndProcHandler

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| hWnd | HWND | Yes | ウィンドウハンドル | - |
| msg | UINT | Yes | メッセージID | - |
| wParam | WPARAM | Yes | メッセージパラメータ1 | - |
| lParam | LPARAM | Yes | メッセージパラメータ2 | - |

### 入力データソース

- Windowsメッセージキュー
- QueryPerformanceCounter（時間計測）
- XInputGetState（ゲームパッド状態）
- GetKeyboardLayout（キーボードコードページ）

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 初期化（ImGui_ImplWin32_Init）
   ├─ バックエンドデータ構造の確保
   ├─ ImGuiIO設定（バックエンド名、フラグ）
   ├─ パフォーマンスカウンタ初期化
   ├─ キーボードコードページ取得
   └─ XInput DLL動的ロード
2. フレーム更新（ImGui_ImplWin32_NewFrame）
   ├─ ウィンドウサイズ取得・設定
   ├─ デルタタイム計算
   ├─ マウス位置更新
   ├─ キーイベントワークアラウンド処理
   ├─ マウスカーソル形状更新
   └─ ゲームパッド状態更新
3. メッセージ処理（ImGui_ImplWin32_WndProcHandler）
   ├─ マウスイベント処理
   ├─ キーボードイベント処理
   ├─ 文字入力処理
   └─ フォーカス/デバイス変更処理
4. 終了処理（ImGui_ImplWin32_Shutdown）
   ├─ XInput DLLアンロード
   └─ バックエンドデータ解放
```

### フローチャート

```mermaid
flowchart TD
    A[ImGui_ImplWin32_Init] --> B[NewFrame呼び出し]
    B --> C{メッセージあり?}
    C -->|Yes| D[WndProcHandler処理]
    C -->|No| E[ImGui処理]
    D --> E
    E --> F[描画]
    F --> B
    G[Shutdown] --> H[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-254-01 | レンダラー併用必須 | 描画バックエンドと併用必須 | 常に適用 |
| BR-254-02 | コンテキスト設定 | Init前にCreateContext必須 | 初期化時 |
| BR-254-03 | メッセージ処理 | WndProcからWndProcHandler呼び出し必要 | メッセージループ |
| BR-254-04 | XInput動的ロード | ゲームパッドDLLは実行時ロード | ゲームパッド使用時 |

### 計算ロジック

**DPIスケール計算**:
```cpp
dpi_scale = xdpi / 96.0f;
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 初期化失敗 | QueryPerformanceFrequency失敗 | falseを返却 |
| - | XInputロード失敗 | xinput DLLが見つからない | ゲームパッド無効化 |

### リトライ仕様

リトライ機能なし。

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

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

## パフォーマンス要件

- NewFrame: O(1)（固定時間処理）
- WndProcHandler: O(1)（メッセージ処理）
- ゲームパッド更新: パケット番号チェックで不要な更新をスキップ

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

- DLL動的ロードは既知のDLL名のみ使用
- ウィンドウメッセージは検証なしで処理（OSからの入力を信頼）

## 備考

- IMGUI_IMPL_WIN32_DISABLE_GAMEPADでゲームパッドサポート無効化可能
- 32bit/64bitアプリケーション両対応
- CS_DBLCLKSフラグ付きウィンドウクラスでダブルクリック対応

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_impl_win32.cpp | `backends/imgui_impl_win32.cpp` | ImGui_ImplWin32_Data構造体（114-135行目） |

**読解のコツ**: バックエンドデータはio.BackendPlatformUserDataに格納され、GetBackendData()で取得する設計パターン。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_impl_win32.h | `backends/imgui_impl_win32.h` | 関数宣言（24-27行目） |
| 2-2 | imgui_impl_win32.cpp | `backends/imgui_impl_win32.cpp` | ImGui_ImplWin32_InitEx実装（161-213行目） |

**主要処理フロー**:
1. **163-164行目**: ImGuiIOとバージョン確認
2. **174-178行目**: バックエンドデータ確保とフラグ設定
3. **192-209行目**: XInput DLL動的ロード

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_impl_win32.cpp | `backends/imgui_impl_win32.cpp` | ImGui_ImplWin32_NewFrame実装（401-434行目） |

**主要処理フロー**:
- **408-410行目**: ウィンドウサイズ取得・設定
- **413-416行目**: デルタタイム計算
- **419行目**: マウスデータ更新
- **422行目**: キーイベントワークアラウンド
- **425-430行目**: マウスカーソル更新
- **433行目**: ゲームパッド更新

#### Step 4: メッセージハンドラを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_impl_win32.cpp | `backends/imgui_impl_win32.cpp` | ImGui_ImplWin32_WndProcHandler（624-631行目） |
| 4-2 | imgui_impl_win32.cpp | `backends/imgui_impl_win32.cpp` | ImGui_ImplWin32_WndProcHandlerEx（634-831行目） |

**主要処理フロー**:
- **641-663行目**: マウス移動処理
- **687-725行目**: マウスボタン処理
- **732-775行目**: キーボード処理
- **786-798行目**: 文字入力処理

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

```
アプリケーション
    │
    ├─ ImGui_ImplWin32_Init(hwnd)
    │      ├─ ImGui_ImplWin32_InitEx
    │      └─ XInput DLL ロード
    │
    ├─ メインループ
    │      ├─ ImGui_ImplWin32_WndProcHandler
    │      │      └─ ImGui_ImplWin32_WndProcHandlerEx
    │      │              ├─ io.AddMousePosEvent
    │      │              ├─ io.AddMouseButtonEvent
    │      │              ├─ io.AddKeyEvent
    │      │              └─ io.AddInputCharacter
    │      │
    │      └─ ImGui_ImplWin32_NewFrame
    │              ├─ ImGui_ImplWin32_UpdateMouseData
    │              ├─ ImGui_ImplWin32_UpdateMouseCursor
    │              └─ ImGui_ImplWin32_UpdateGamepads
    │
    └─ ImGui_ImplWin32_Shutdown
           └─ XInput DLL アンロード
```

### データフロー図

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

Windowsメッセージ ────────▶ WndProcHandler ────────▶ ImGuiIO入力イベント
QueryPerformanceCounter ──▶ NewFrame ──────────────▶ ImGuiIO.DeltaTime
GetClientRect ────────────▶ NewFrame ──────────────▶ ImGuiIO.DisplaySize
XInputGetState ───────────▶ UpdateGamepads ────────▶ ImGuiIO入力イベント
```

### 関連ファイル一覧

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