# 画面設計書 17-Simple Overlay

## 概要

本ドキュメントは、Dear ImGuiのサンプルアプリケーション「Simple Overlay」画面の設計仕様を定義する。本画面は、半透明のオーバーレイウィンドウのサンプル実装である。

### 本画面の処理概要

本画面は、画面の隅に固定されたデコレーションなしのオーバーレイウィンドウを実演する。ゲームのHUD、デバッグ情報表示、通知などに使用されるパターンである。コンテキストメニューから表示位置を変更できる。

**業務上の目的・背景**：ゲームやツールでは、メインコンテンツの上に情報を重ねて表示するオーバーレイが必要になることがある。本画面は、ImGuiでフローティングオーバーレイを実装する方法を示す。タイトルバーなし、背景半透明、画面端への固定配置など、オーバーレイに必要な設定を実演する。

**画面へのアクセス方法**：Demo Windowのメニューバーから「Examples」メニューを選択し、「Simple Overlay」を選択することで表示される。または、アプリケーションコード内で`ShowExampleAppSimpleOverlay(&show_app_simple_overlay)`を呼び出すことで直接表示可能。

**主要な操作・処理内容**：
1. マウス位置のリアルタイム表示
2. 右クリックコンテキストメニューで表示位置を変更
3. 5つの位置オプション（Custom, Center, 4隅）から選択
4. 半透明背景によるコンテンツの視認性確保

**画面遷移**：本画面はDemo Windowの「Examples」メニューから呼び出される。独立したウィンドウとして表示され、他の画面への直接的な遷移機能は持たない。コンテキストメニューの「Close」でウィンドウを閉じることができる。

**権限による表示制御**：本画面は権限による表示制御を持たない。すべてのユーザーが同一の機能にアクセス可能である。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | Begin | 主機能 | オーバーレイウィンドウの開始処理 |
| 25 | End | 主機能 | オーバーレイウィンドウの終了処理 |
| 35 | SetNextWindowPos | 主機能 | ウィンドウ位置の設定 |
| 42 | SetNextWindowBgAlpha | 主機能 | 背景透明度の設定 |
| 85 | Text | 補助機能 | オーバーレイ情報の表示 |
| 241 | GetMousePos | 補助機能 | マウス位置の取得・表示 |

## 画面種別

オーバーレイ（HUD/情報表示）

## URL/ルーティング

N/A（ImGuiはURLベースのルーティングを持たない。`ShowExampleAppSimpleOverlay()`関数呼び出しによりウィンドウを表示）

## 入出力項目

| 項目名 | 型 | I/O | 必須 | 説明 |
|--------|-----|-----|------|------|
| p_open | bool* | I/O | No | ウィンドウの表示状態を制御するポインタ |
| location | int (static) | I/O | No | 表示位置（-2:Center, -1:Custom, 0-3:4隅） |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| タイトル | Text | "Simple overlay" + 操作説明 |
| マウス位置 | Text | 現在のマウス座標（x, y） |
| コンテキストメニュー | Popup | 位置選択メニュー |

## イベント仕様

### 1-右クリックでコンテキストメニュー表示

オーバーレイウィンドウ上で右クリックすると、BeginPopupContextWindow()により位置選択メニューが表示される。

### 2-位置の選択

コンテキストメニューから以下の位置を選択できる：
- Custom (-1): ユーザーが自由にドラッグで移動可能
- Center (-2): ビューポートの中央に固定
- Top-left (0): 左上隅に固定
- Top-right (1): 右上隅に固定
- Bottom-left (2): 左下隅に固定
- Bottom-right (3): 右下隅に固定

### 3-マウス位置の表示

ImGui::GetIO().MousePosから現在のマウス位置を取得し、リアルタイムで表示する。マウス位置が無効な場合は「<invalid>」と表示。

### 4-Closeメニュー選択

コンテキストメニューの「Close」を選択すると、p_openがfalseに設定されウィンドウが閉じる。

## データベース更新仕様

本画面はデータベースを使用しない。

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

N/A（データベースアクセスなし）

## メッセージ仕様

| 表示テキスト | 表示場所 | 説明 |
|-------------|---------|------|
| "Simple overlay\n(right-click to change position)" | ウィンドウ上部 | タイトルと操作ガイド |
| "Mouse Position: (%.1f,%.1f)" | ウィンドウ下部 | マウス座標 |
| "Mouse Position: <invalid>" | ウィンドウ下部 | マウス位置無効時 |

## 例外処理

| 状態 | 処理内容 |
|------|----------|
| マウス位置無効 | IsMousePosValid()で判定し、「<invalid>」と表示 |
| p_openがNULL | Closeメニューを表示しない |

## 備考

- ImGuiWindowFlags_NoDecorationでタイトルバー・ボーダー等を非表示
- ImGuiWindowFlags_AlwaysAutoResizeでコンテンツに合わせたサイズ
- ImGuiWindowFlags_NoSavedSettingsで位置をimgui.iniに保存しない
- ImGuiWindowFlags_NoFocusOnAppearingでフォーカスを奪わない
- ImGuiWindowFlags_NoNavでキーボードナビゲーションを無効化
- SetNextWindowBgAlpha(0.35f)で背景を65%透明に設定
- PAD = 10.0fで画面端から10ピクセルのマージンを確保
- location >= 0の場合はNoMoveフラグを追加して移動を禁止

---

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

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

### 推奨読解順序

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

本画面は非常にシンプルで、static変数1つのみを使用する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_demo.cpp | `imgui_demo.cpp` | 9782行のstatic int location = 0 |

**読解のコツ**: locationの値によって位置計算ロジックが分岐する。ビット演算を使用した位置計算に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_demo.cpp | `imgui_demo.cpp` | ShowExampleAppSimpleOverlay()関数（9780-9828行）全体を確認 |

**主要処理フロー**:
1. **9784行**: window_flagsにNoDecoration等のフラグを設定
2. **9785-9797行**: location値に応じてウィンドウ位置を計算
3. **9805行**: SetNextWindowBgAlpha(0.35f)で透明度設定
4. **9806行**: Begin()でオーバーレイウィンドウを開始
5. **9809-9814行**: マウス位置の表示
6. **9815-9824行**: コンテキストメニューの処理

#### Step 3: 位置計算を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_demo.cpp | `imgui_demo.cpp` | 9785-9804行の位置計算ロジック |

**主要処理フロー**:
- **9788-9789行**: GetMainViewport()でワークエリアを取得
- **9791-9794行**: ビット演算でコーナー位置を計算
  - (location & 1): 水平方向（0=左、1=右）
  - (location & 2): 垂直方向（0=上、1=下）
- **9796行**: SetNextWindowPos()でピボット付きで位置設定
- **9799-9803行**: location == -2の場合は中央配置

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

```
ShowExampleAppSimpleOverlay(bool* p_open)
    |
    +-- [位置計算]
    |   +-- location >= 0: 4隅のいずれか
    |   |   +-- GetMainViewport() -> WorkPos, WorkSize取得
    |   |   +-- ビット演算で座標計算
    |   |   +-- SetNextWindowPos(window_pos, AlwaysCondition, pivot)
    |   |
    |   +-- location == -2: 中央
    |       +-- GetMainViewport()->GetCenter()
    |       +-- SetNextWindowPos(..., pivot=(0.5, 0.5))
    |
    +-- ImGui::SetNextWindowBgAlpha(0.35f)
    |
    +-- ImGui::Begin("Example: Simple overlay", p_open, window_flags)
            |
            +-- ImGui::Text("Simple overlay\n...")
            |
            +-- ImGui::Separator()
            |
            +-- [マウス位置表示]
            |   +-- IsMousePosValid() ? 座標表示 : "<invalid>"
            |
            +-- ImGui::BeginPopupContextWindow()
                    +-- MenuItem("Custom", location == -1)
                    +-- MenuItem("Center", location == -2)
                    +-- MenuItem("Top-left", location == 0)
                    +-- MenuItem("Top-right", location == 1)
                    +-- MenuItem("Bottom-left", location == 2)
                    +-- MenuItem("Bottom-right", location == 3)
                    +-- MenuItem("Close")
```

### データフロー図

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

location変数 -----------> 位置計算
                          |
                          +-> SetNextWindowPos() -------> ウィンドウ配置

マウス移動 -------------> GetIO().MousePos
                          |
                          +-> Text()表示 ---------------> マウス座標表示

右クリック -------------> BeginPopupContextWindow()
                          |
                          +-> MenuItem() ----------------> location変数更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | ShowExampleAppSimpleOverlay()関数のデモ実装 |
| imgui.h | `imgui.h` | ヘッダー | SetNextWindowPos, SetNextWindowBgAlpha, GetMainViewportの宣言 |
| imgui.cpp | `imgui.cpp` | ソース | Begin/End、ウィンドウ位置設定の実装 |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | BeginPopupContextWindow, MenuItem, Textの実装 |
