# 帳票設計書 7-メトリクスウィンドウ

## 概要

本ドキュメントは、Dear ImGuiライブラリのメトリクスウィンドウ（Metrics/Debugger Window）機能に関する帳票設計書である。ImGuiの内部状態（ウィンドウ、描画コマンド、メモリ使用量など）を詳細に表示するデバッグ用ウィンドウについて記述する。

### 本帳票の処理概要

メトリクスウィンドウ（ShowMetricsWindow）は、ImGuiライブラリの内部状態を包括的に可視化するデバッガーウィンドウである。フレームレート、頂点数、ウィンドウ情報、描画リスト、テーブル、入力状態など、ImGuiのほぼ全ての内部データにアクセスできる。

**業務上の目的・背景**：ImGuiを使用したアプリケーション開発において、パフォーマンス問題、レイアウト問題、描画問題などの診断には、内部状態の詳細な把握が不可欠である。メトリクスウィンドウにより、ウィンドウ階層、描画コマンド数、メモリ使用量などを一目で確認でき、問題の特定と解決が大幅に効率化される。また、Item Pickerツールにより、特定のウィジェットを視覚的に選択してデバッグブレークポイントを設定することも可能。

**帳票の利用シーン**：開発者がImGuiアプリケーションのパフォーマンスや動作を診断したい場合に、ShowMetricsWindow関数を呼び出してウィンドウを表示する。デモウィンドウのToolsメニューからも呼び出し可能。ウィンドウ内のツリー構造を展開して、必要な情報にアクセスする。

**主要な出力内容**：
1. フレームレート（FPS）とフレーム時間
2. 描画頂点数・インデックス数・三角形数
3. 可視ウィンドウ数とメモリ割り当て状況
4. ウィンドウ一覧と各ウィンドウの詳細情報
5. 描画リスト・描画コマンドの詳細
6. テーブル・フォント・入力状態の情報
7. 設定管理（INI保存・クリア機能）

**帳票の出力タイミング**：ShowMetricsWindow関数が呼び出されている間、毎フレーム更新される。

**帳票の利用者**：アプリケーション開発者、ImGuiライブラリ開発者、パフォーマンスエンジニア

## 帳票種別

デバッグ出力（リアルタイム更新ウィンドウ）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Metrics/Debugger Window | - | ShowMetricsWindow()関数呼び出し |
| - | デモウィンドウ | - | Tools > Metricsメニュー |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | N/A（ウィンドウ表示） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A |
| 出力方法 | ImGuiウィンドウ表示 |
| 文字コード | UTF-8 |

### 表示セクション

| セクション | 内容 |
|-----------|------|
| 基本情報 | バージョン、FPS、頂点数等 |
| Tools | デバッグツール群 |
| Windows | ウィンドウ一覧と詳細 |
| Drawlists | 描画リスト情報 |
| Textures/Fonts | テクスチャ・フォント情報 |
| Tables | テーブル情報 |
| Inputs | 入力状態 |
| Settings | INI設定管理 |

## 帳票レイアウト

### レイアウト概要

ツリー構造で階層的に情報を表示。各セクションは折りたたみ可能。

```
Dear ImGui X.XX (XXXXX)
Application average X.XXX ms/frame (XX.X FPS)
XXXX vertices, XXXX indices (XXXX triangles)
XX visible windows, XX current allocations

[Tools]
  - Item Picker
  - Debug breaks
  - Visualize

[Windows]
  - Window "Name" ...

[DrawLists]
  ...
```

### 出力項目

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | バージョン | ImGuiバージョン | IMGUI_VERSION | X.XX (build) |
| 2 | コンテキスト名 | マルチコンテキスト時 | g.ContextName | 文字列 |
| 3 | フレーム時間 | 平均フレーム時間 | io.Framerate | X.XXX ms/frame |
| 4 | FPS | フレームレート | io.Framerate | XX.X FPS |
| 5 | 頂点数 | 描画頂点数 | io.MetricsRenderVertices | 数値 |
| 6 | インデックス数 | 描画インデックス数 | io.MetricsRenderIndices | 数値 |
| 7 | 三角形数 | 描画三角形数 | MetricsRenderIndices/3 | 数値 |
| 8 | 可視ウィンドウ数 | 表示中ウィンドウ数 | io.MetricsRenderWindows | 数値 |
| 9 | 割り当て数 | 現在のメモリ割り当て数 | TotalAllocCount - TotalFreeCount | 数値 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| なし | いつでも表示可能 | - |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | セクション固定順 | - |

## データベース参照仕様

### 参照テーブル一覧

N/A（データベースは使用しない）

### 内部データ構造参照

| データ構造 | 用途 | アクセス方法 |
|-----------|------|-------------|
| ImGuiContext | コンテキスト全体 | g |
| ImGuiIO | IO情報 | g.IO |
| ImGuiWindow | ウィンドウ情報 | g.Windows |
| ImDrawList | 描画リスト | window->DrawList |
| ImGuiTable | テーブル情報 | g.Tables |
| ImGuiMetricsConfig | 表示設定 | g.DebugMetricsConfig |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| フレーム時間 | 1000.0f / io.Framerate | 小数点3桁 | ms単位 |
| 三角形数 | io.MetricsRenderIndices / 3 | 整数 | - |
| 現在割り当て | TotalAllocCount - TotalFreeCount | 整数 | - |

## 処理フロー

### 表示フロー

```mermaid
flowchart TD
    A[ShowMetricsWindow呼び出し] --> B{ShowDebugLog有効?}
    B -->|Yes| C[ShowDebugLogWindow表示]
    B -->|No| D[スキップ]
    C --> E{ShowIDStackTool有効?}
    D --> E
    E -->|Yes| F[ShowIDStackToolWindow表示]
    E -->|No| G[スキップ]
    F --> H[Metricsウィンドウ開始]
    G --> H
    H --> I[基本情報表示]
    I --> J[Toolsセクション]
    J --> K[Windowsセクション]
    K --> L[DrawListsセクション]
    L --> M[その他セクション]
    M --> N[ウィンドウ終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| なし | - | - | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 動的（ウィンドウ数等に依存） |
| 目標出力時間 | リアルタイム |
| 更新頻度 | 毎フレーム |

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

- 内部状態を詳細に表示するため、本番環境では非表示推奨
- メモリアドレスなど機密性の高い情報が表示される可能性あり

## 備考

- Item Pickerツールでウィジェットを選択し、デバッガでブレークポイントを設定可能
- io.ConfigDebugIsDebuggerPresentがtrueの場合、追加のデバッグ機能が有効化
- Settingsセクションから直接INI設定のクリア・保存が可能
- 各ウィンドウの矩形領域を可視化するオプションあり

---

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

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

### 推奨読解順序

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

まず、メトリクス表示で使用されるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 公開API（ShowMetricsWindow宣言）を確認 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiMetricsConfig構造体を確認 |
| 1-3 | imgui.h | `imgui.h` | ImGuiIOのメトリクス関連メンバを確認 |

**読解のコツ**: ImGuiIOにはMetricsRenderVertices等のメトリクス情報が格納されている。

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

処理の起点となる関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | 16401-16500行目: ShowMetricsWindow関数の冒頭部分 |

**主要処理フロー**:
1. **16406-16409行目**: ShowDebugLog/ShowIDStackToolウィンドウの表示
2. **16411-16415行目**: ウィンドウ開始、BeginCount > 1なら早期リターン
3. **16421-16429行目**: 基本情報（バージョン、FPS、頂点数等）の表示
4. **16486-16499行目**: Toolsセクション

#### Step 3: 各表示セクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | 16486-16509行目: Toolsセクション（Item Picker等） |
| 3-2 | imgui.cpp | `imgui.cpp` | 16500行目以降: Windows/DrawLists等の各セクション |

**主要処理フロー**:
- **16493-16494行目**: Item Pickerツールの表示と有効化
- **16499行目**: Debug Logへのリンク

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui.cpp | `imgui.cpp` | DebugNode系関数群（DebugNodeWindow等） |

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

```
ShowMetricsWindow(p_open)
    │
    ├─ [ShowDebugLog有効時]
    │      └─ ShowDebugLogWindow(&cfg->ShowDebugLog)
    │
    ├─ [ShowIDStackTool有効時]
    │      └─ ShowIDStackToolWindow(&cfg->ShowIDStackTool)
    │
    ├─ Begin("Dear ImGui Metrics/Debugger", p_open)
    │
    ├─ [基本情報]
    │      ├─ Text("Dear ImGui %s (%d)", ...)
    │      ├─ Text("Application average %.3f ms/frame", ...)
    │      ├─ Text("%d vertices, %d indices", ...)
    │      └─ Text("%d visible windows", ...)
    │
    ├─ TreeNode("Tools")
    │      ├─ Checkbox("Show Item Picker", ...)
    │      ├─ Checkbox("Show Debug Log", ...)
    │      └─ ...
    │
    ├─ TreeNode("Windows")
    │      └─ [各ウィンドウ]
    │             └─ DebugNodeWindow(...)
    │
    ├─ TreeNode("DrawLists")
    │      └─ [各DrawList]
    │             └─ DebugNodeDrawList(...)
    │
    ├─ TreeNode("Inputs")
    │      └─ [入力状態表示]
    │
    ├─ TreeNode("Settings")
    │      ├─ SmallButton("Clear")
    │      ├─ SmallButton("Save to memory")
    │      └─ SmallButton("Save to disk")
    │
    └─ End()
```

### データフロー図

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

ImGuiContext ────────────▶ ShowMetricsWindow()
                              │
io.Framerate ────────────────┼──────────────▶ FPS表示
                              │
io.MetricsRenderVertices ────┼──────────────▶ 頂点数表示
                              │
g.Windows ───────────────────┼──────────────▶ ウィンドウ一覧
                              │
DrawLists ───────────────────┼──────────────▶ 描画コマンド表示
                              │
g.Tables ────────────────────┼──────────────▶ テーブル情報
                              │
                              └──────────────▶ Metrics/Debuggerウィンドウ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 公開API宣言（ShowMetricsWindow等） |
| imgui.cpp | `imgui.cpp` | ソース | メトリクスウィンドウの実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiMetricsConfig、内部データ構造定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | デモウィンドウからの呼び出し例 |
