# 機能設計書 241-GetMousePos

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるGetMousePos関数の機能設計について記述する。この関数は現在のマウスカーソル位置を取得するためのユーティリティ関数である。

### 本機能の処理概要

GetMousePos関数は、アプリケーション内でのマウスカーソルの現在位置をスクリーン座標として取得する機能を提供する。ImGuiIO構造体に格納されているMousePos値へのショートカットとして機能し、他のマウス関連APIと一貫性のあるインターフェースを提供する。

**業務上の目的・背景**：GUIアプリケーションでは、マウスカーソルの位置に基づいた処理が頻繁に必要となる。例えば、カスタム描画、ツールチップの位置決め、ドラッグ操作、ホバー判定などにおいて、マウス位置の取得は基本的な操作である。この関数により、開発者は一貫したAPIを通じてマウス位置にアクセスできる。

**機能の利用シーン**：カスタムウィジェットの描画時にマウス位置を参照する場合、オーバーレイウィンドウでマウス座標を表示する場合、マウス位置に基づいた動的なUI要素の配置を行う場合、ドラッグ&ドロップ操作の開始位置を特定する場合などに使用される。

**主要な処理内容**：
1. グローバルImGuiコンテキスト（GImGui）を取得
2. コンテキストのIOオブジェクトからMousePosを取得
3. ImVec2形式（x, y座標）で位置を返却

**関連システム・外部連携**：バックエンド（プラットフォーム実装）がマウス位置を更新し、ImGuiIO::MousePosに格納する。この関数はその値を読み取るのみであり、外部システムへの直接的な連携は行わない。

**権限による制御**：本機能に権限による制御は存在しない。コンテキストが有効であれば常に呼び出し可能である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 17 | Simple Overlay | 補助機能 | マウス位置の取得・表示 |
| 27 | Inputs | 主機能 | マウス位置取得のデモ |

## 機能種別

読取処理 / データ取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | 引数なし | - |

### 入力データソース

- ImGuiIO::MousePos - バックエンドがフレームごとに更新するマウス位置
- バックエンドからの入力イベント経由でImGuiIO構造体に格納される

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ImVec2 | マウスカーソルの現在位置（スクリーン座標） |
| x | float | 水平方向の位置（ピクセル単位） |
| y | float | 垂直方向の位置（ピクセル単位） |

### 出力先

- 呼び出し元への戻り値として返却
- 画面表示やカスタム描画処理で使用

## 処理フロー

### 処理シーケンス

```
1. グローバルコンテキスト参照取得
   └─ GImGuiポインタを逆参照してImGuiContext&を取得
2. IOオブジェクトからMousePos取得
   └─ g.IO.MousePosをそのまま返却
```

### フローチャート

```mermaid
flowchart TD
    A[GetMousePos呼び出し] --> B[グローバルコンテキスト取得]
    B --> C[g.IO.MousePos取得]
    C --> D[ImVec2として返却]
    D --> E[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-241-1 | 座標系 | スクリーン座標系（左上原点）で値を返す | 常時 |
| BR-241-2 | 無効位置 | マウスが利用不可の場合は(-FLT_MAX, -FLT_MAX)が返される | マウス未接続時等 |

### 計算ロジック

特別な計算処理は行わない。ImGuiIO::MousePosの値をそのまま返却する。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンテキスト未初期化 | GImGuiがNULLの場合 | CreateContext()を先に呼び出す |

### リトライ仕様

リトライ処理は不要。エラー時はアサーション違反となる。

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

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

## パフォーマンス要件

- 処理時間: O(1) - 単純なメンバ変数参照のみ
- メモリ使用: 追加のメモリ割り当てなし
- 呼び出し頻度: 毎フレーム複数回呼び出し可能

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

- マウス位置情報は機密性の低いデータ
- 入力値の検証は不要（読み取り専用）
- 外部への情報漏洩リスクなし

## 備考

- IsMousePosValid()関数と組み合わせて使用することで、有効なマウス位置かどうかを判定可能
- ImGui::GetIO().MousePosと同等の値を返すが、他のマウス関連APIとの一貫性のためにこの関数の使用が推奨される

---

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

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

### 推奨読解順序

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

マウス位置情報がどのように格納されているかを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImVec2構造体の定義（291-304行目付近）- 2D座標を格納する基本構造 |
| 1-2 | imgui.h | `imgui.h` | ImGuiIO構造体のMousePos定義 - マウス位置の格納場所 |

**読解のコツ**: ImVec2は非常にシンプルな2要素の浮動小数点ベクトルである。演算子オーバーロードも定義されており、座標計算に便利に使用できる。

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

関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | GetMousePos関数の実装（9940-9944行目） |

**主要処理フロー**:
1. **9942行目**: グローバルコンテキストGImGuiを逆参照してImGuiContext&を取得
2. **9943行目**: g.IO.MousePosをそのまま返却

#### Step 3: 関連するマウス位置関数を理解する

類似のマウス位置取得関数との関係を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | IsMousePosValid関数（9967-9973行目）- マウス位置の有効性判定 |
| 3-2 | imgui.cpp | `imgui.cpp` | GetMousePosOnOpeningCurrentPopup関数（9958-9964行目）- ポップアップ開始時の位置取得 |

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

```
GetMousePos()
    │
    └─ GImGui->IO.MousePos (直接参照)
           │
           └─ バックエンドから更新される値
```

### データフロー図

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

バックエンド                GetMousePos()        呼び出し元
(Platform実装)                 │                   │
    │                          │                   │
    └── IO.MousePos更新 ─────▶ 参照 ─────────────▶ ImVec2座標
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 関数宣言、ImVec2/ImGuiIO構造体定義 |
| imgui.cpp | `imgui.cpp` | ソース | GetMousePos関数の実装 |
| imgui_impl_*.cpp | `backends/` | バックエンド | MousePosを更新するプラットフォーム実装 |
