# 機能設計書 13-ShowMetricsWindow

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるShowMetricsWindow関数の機能設計を記載する。この関数はImGuiの内部状態を詳細に表示するメトリクス/デバッガウィンドウを提供し、開発者がアプリケーションのデバッグや最適化を行う際に活用できる。

### 本機能の処理概要

ShowMetricsWindow関数は、Dear ImGuiの内部動作状態を可視化するデバッグウィンドウを表示する。このウィンドウでは、ウィンドウ一覧、描画コマンド、各種メトリクス（頂点数、インデックス数、FPS等）、設定状態など、ImGuiの内部構造を詳細に確認できる。開発者はこの情報を活用して、パフォーマンス問題の特定やUI動作の検証を行うことができる。

**業務上の目的・背景**：GUIアプリケーション開発において、UIの動作を正確に把握することは重要である。ShowMetricsWindowは、ImGuiが内部でどのような処理を行っているかを可視化し、開発者がパフォーマンスボトルネックの特定、レイアウト問題の診断、メモリ使用状況の確認などを行えるようにする。これにより、高品質なUIの実装と維持が可能となる。

**機能の利用シーン**：
- UIのパフォーマンス問題をデバッグする際
- ウィンドウやウィジェットの内部状態を確認する際
- 描画コマンド数や頂点数を最適化する際
- メモリアロケーションの状況を確認する際
- IDスタックやフォーカス関連の問題を調査する際

**主要な処理内容**：
1. フレームレートと基本メトリクス（頂点数、インデックス数、ウィンドウ数）の表示
2. Tools セクション（Item Picker、Debug Log、ID Stack Tool等へのアクセス）
3. Windows セクション（アクティブウィンドウの詳細情報）
4. DrawLists セクション（描画コマンドの詳細）
5. Fonts セクション（フォントアトラス情報）
6. Settings セクション（永続化設定の確認）
7. Internal state セクション（ImGuiContext内部状態）

**関連システム・外部連携**：
- ShowDebugLogWindow（デバッグログウィンドウ）
- ShowIDStackToolWindow（IDスタックツールウィンドウ）
- DebugStartItemPicker（アイテムピッカーツール）

**権限による制御**：本機能に権限制御はない。ただし、IMGUI_DISABLE_DEBUG_TOOLSが定義されている場合は空の関数となる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Metrics/Debugger Window | 主画面 | メトリクス/デバッガウィンドウの表示 |
| 3 | Debug Log Window | 遷移先画面 | Toolsセクションから遷移可能 |
| 4 | ID Stack Tool Window | 遷移先画面 | Toolsセクションから遷移可能 |

## 機能種別

デバッグ・診断 / 内部状態可視化

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| p_open | bool* | No | ウィンドウの開閉状態を制御するポインタ。NULLの場合は閉じるボタンなし | NULL許容 |

### 入力データソース

- ImGuiContext（現在のコンテキスト）
- ImGuiMetricsConfig（メトリクスウィンドウの設定状態）
- 各種内部データ構造（Windows、DrawLists、Fonts等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | void | 戻り値なし |
| *p_open | bool | ユーザーがウィンドウを閉じた場合falseに設定 |

### 出力先

- ImGuiウィンドウとして画面に描画

## 処理フロー

### 処理シーケンス

```
1. 関連ウィンドウの表示
   └─ cfg->ShowDebugLog/ShowIDStackToolに基づき関連ウィンドウを表示
2. メインウィンドウの開始
   └─ Begin("Dear ImGui Metrics/Debugger", p_open)
3. デバッグブレークデータのクリア
   └─ DebugBreakClearData()
4. 基本情報の表示
   └─ バージョン、FPS、頂点数、インデックス数、ウィンドウ数等
5. Toolsセクションの表示
   └─ Item Picker、Debug breaks、各種可視化オプション
6. 各デバッグセクションの表示
   └─ Windows、DrawLists、Fonts、Settings、Internal state等
7. ウィンドウの終了
   └─ End()
```

### フローチャート

```mermaid
flowchart TD
    A[ShowMetricsWindow呼び出し] --> B[関連ウィンドウ表示判定]
    B --> C[ShowDebugLogWindow等の呼び出し]
    C --> D[Begin - メインウィンドウ開始]
    D --> E{ウィンドウ可視?}
    E -->|No| F[End - 早期リターン]
    E -->|Yes| G[基本メトリクス表示]
    G --> H[Toolsセクション]
    H --> I[Windowsセクション]
    I --> J[DrawListsセクション]
    J --> K[Fontsセクション]
    K --> L[その他セクション...]
    L --> M[End]
    F --> N[終了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 再入防止 | 同一フレーム内での多重呼び出しを検出し早期リターン | BeginCount > 1時 |
| BR-02 | ツール連携 | ShowDebugLog/ShowIDStackToolフラグに基づき関連ウィンドウを自動表示 | 常時 |
| BR-03 | Item Picker | 有効化時はデバッグブレークポイントを設定可能 | デバッガ接続時 |

### 計算ロジック

- FPS計算: `1000.0f / io.Framerate`
- 三角形数計算: `io.MetricsRenderIndices / 3`

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

該当なし（インメモリ動作）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 早期リターン | 多重呼び出し | 同一フレーム内で複数回呼び出し | 自動的に処理をスキップ |

### リトライ仕様

該当なし（毎フレーム呼び出し）

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

該当なし

## パフォーマンス要件

- TreeNodeを使用した遅延描画により、展開されていないセクションは処理をスキップ
- 大量のウィンドウや描画コマンドがある場合も効率的に表示

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

該当なし（ローカルUI表示のみ）

## 備考

- IMGUI_DISABLE_DEBUG_TOOLSが定義されている場合、空の関数となる
- IMGUI_DEBUG_HIGHLIGHT_ALL_ID_CONFLICTSが定義されている場合、警告を表示
- デバッガが接続されている場合のみデバッグブレーク機能が有効

---

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

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

### 推奨読解順序

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

メトリクスウィンドウの設定を管理するImGuiMetricsConfig構造体を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiMetricsConfig構造体の定義 |

**読解のコツ**: ImGuiMetricsConfigはShowDebugLog、ShowIDStackTool、ShowWindowsRects等のフラグを保持する構造体。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | ShowMetricsWindow関数の宣言（408行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | ShowMetricsWindow関数の実装（16401行目〜） |

**主要処理フロー**:
1. **16403-16405行目**: コンテキストとIO、設定の取得
2. **16406-16409行目**: 関連ウィンドウの条件付き表示
3. **16411-16415行目**: Begin呼び出しと早期リターン処理
4. **16418行目**: デバッグブレークデータのクリア
5. **16421-16429行目**: 基本メトリクスの表示
6. **16486-16500行目**: Toolsセクションの表示

#### Step 3: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | GetWindowRect / GetTableRect関数（16444-16478行目） |
| 3-2 | imgui.cpp | `imgui.cpp` | DebugNodeWindow等のデバッグノード関数 |

**主要処理フロー**:
- Funcs構造体内にヘルパー関数を定義
- 各種矩形タイプ（OuterRect、InnerRect、WorkRect等）に対応

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

```
ShowMetricsWindow()
    │
    ├─ [条件付き] ShowDebugLogWindow()
    ├─ [条件付き] ShowIDStackToolWindow()
    │
    ├─ Begin("Dear ImGui Metrics/Debugger")
    │      │
    │      ├─ DebugBreakClearData()
    │      │
    │      ├─ Text() - バージョン、FPS、メトリクス表示
    │      │
    │      ├─ TreeNode("Tools")
    │      │      ├─ Checkbox("Show Item Picker")
    │      │      ├─ DebugStartItemPicker()
    │      │      ├─ Checkbox("Show Debug Log")
    │      │      └─ Checkbox("Show ID Stack Tool")
    │      │
    │      ├─ TreeNode("Windows")
    │      │      └─ DebugNodeWindow() - 各ウィンドウ
    │      │
    │      ├─ TreeNode("DrawLists")
    │      │      └─ DebugNodeDrawList()
    │      │
    │      ├─ TreeNode("Fonts")
    │      │      └─ ShowFontAtlas()
    │      │
    │      └─ その他セクション...
    │
    └─ End()
```

### データフロー図

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

ImGuiContext         ShowMetricsWindow()            Metrics Window描画
    │                      │                              │
    ├─ IO                  ├─ FPS計算                     │
    ├─ Windows             ├─ ウィンドウ情報表示          │
    ├─ DrawLists           ├─ 描画コマンド表示            │
    └─ DebugMetricsConfig  └─ 設定状態表示                │
                                                          │
p_open (bool*) ────────────────────────────────────────────┘
                         閉じるボタン押下時
                         *p_open = false
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | ShowMetricsWindow宣言（408行目） |
| imgui.cpp | `imgui.cpp` | ソース | ShowMetricsWindow実装（16401-18118行目） |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiMetricsConfig等の内部構造体定義 |
