# 帳票設計書 6-デバッグログ出力

## 概要

本ドキュメントは、Dear ImGuiライブラリのデバッグログ出力機能に関する帳票設計書である。ImGuiの内部イベント（ActiveId変更、フォーカス移動、ポップアップ開閉など）をログとして記録・表示する機能について記述する。

### 本帳票の処理概要

デバッグログ出力機能は、ImGuiの内部動作を可視化するための診断機能である。各種イベント（ActiveId変更、フォーカス移動、ポップアップ開閉、ナビゲーション、入力ルーティングなど）が発生するたびにログエントリが追加され、ShowDebugLogWindowで表示される。

**業務上の目的・背景**：ImGuiを使用したアプリケーション開発において、予期しない動作やバグの原因特定は困難な場合がある。デバッグログ出力機能により、ImGuiの内部状態遷移をリアルタイムで追跡でき、問題の原因究明が大幅に効率化される。特にID衝突、フォーカス問題、入力処理の問題など、目視では確認しにくい問題の診断に有効である。

**帳票の利用シーン**：開発者がImGuiの動作を詳細に追跡したい場合に、ShowDebugLogWindow関数を呼び出してデバッグログウィンドウを表示する。チェックボックスで監視対象のイベントカテゴリ（ActiveId、Focus、Popup、Nav、IO等）を選択し、リアルタイムでログを確認する。Metricsウィンドウからも「Show Debug Log」チェックボックスで表示を切り替えられる。

**主要な出力内容**：
1. フレーム番号（[00001]形式）
2. コンテキスト名（マルチコンテキスト時）
3. イベント種別とその詳細情報
4. 関連するウィジェットID、ウィンドウ名など

**帳票の出力タイミング**：DebugLog関数またはIIMGUI_DEBUG_LOGマクロが呼び出されるたびにログエントリが追加される。DebugLogFlagsで有効化されたカテゴリのみが記録される。

**帳票の利用者**：アプリケーション開発者、ImGuiライブラリ開発者

## 帳票種別

デバッグ出力（内部ログバッファ + ウィンドウ表示）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Debug Log Window | - | ShowDebugLogWindow()関数呼び出し |
| - | Metrics/Debuggerウィンドウ | - | Tools > Show Debug Logチェックボックス |
| - | デモウィンドウ | - | Tools > Debug Logメニュー |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキストログ（メモリ上） |
| 用紙サイズ | N/A（ウィンドウ表示） |
| 向き | N/A |
| ファイル名 | N/A（メモリバッファ） |
| 出力方法 | ImGuiウィンドウ表示 + オプションでTTY/デバッガ出力 |
| 文字コード | UTF-8 |

### デバッグログ固有設定

| 項目 | 内容 |
|-----|------|
| バッファ | g.DebugLogBuf（ImGuiTextBuffer） |
| インデックス | g.DebugLogIndex（ImGuiTextIndex） |
| 出力先オプション | TTY、Windowsデバッガ、テストエンジン |

## 帳票レイアウト

### レイアウト概要

行ごとにフレーム番号とイベント情報が表示される。

```
[00001] ActiveId: new = 0xABCD1234 ("ButtonName")
[00001] Focus: window = "WindowName"
[00002] Popup: open = "PopupName"
```

### 出力項目

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | コンテキスト名 | マルチコンテキスト時のみ | g.ContextName | [name] |
| 2 | フレーム番号 | 現在のフレームカウント | g.FrameCount | [00000] |
| 3 | イベント情報 | イベント種別と詳細 | DebugLog引数 | 可変フォーマット |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| IMGUI_DISABLE_DEBUG_TOOLS未定義 | デバッグツールが有効であること | Yes |
| DebugLogFlags設定 | 対象カテゴリのフラグがONであること | Yes |

### フィルタリング

| フラグ | 対象イベント |
|-------|------------|
| ImGuiDebugLogFlags_EventError | エラーイベント |
| ImGuiDebugLogFlags_EventActiveId | ActiveId変更 |
| ImGuiDebugLogFlags_EventFocus | フォーカス変更 |
| ImGuiDebugLogFlags_EventPopup | ポップアップ開閉 |
| ImGuiDebugLogFlags_EventNav | ナビゲーション |
| ImGuiDebugLogFlags_EventClipper | クリッパー動作 |
| ImGuiDebugLogFlags_EventSelection | 選択変更 |
| ImGuiDebugLogFlags_EventIO | IO処理 |
| ImGuiDebugLogFlags_EventInputRouting | 入力ルーティング |
| ImGuiDebugLogFlags_EventFont | フォント処理 |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | 記録順 | 昇順（時系列） |

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

### 参照テーブル一覧

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

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

| データ構造 | 用途 | アクセス方法 |
|-----------|------|-------------|
| ImGuiContext.DebugLogBuf | ログテキストバッファ | g.DebugLogBuf |
| ImGuiContext.DebugLogIndex | 行インデックス | g.DebugLogIndex |
| ImGuiContext.DebugLogFlags | 有効フラグ | g.DebugLogFlags |
| ImGuiContext.DebugLogAutoDisableFlags | 自動無効化フラグ | g.DebugLogAutoDisableFlags |
| ImGuiContext.DebugLogAutoDisableFrames | 自動無効化カウント | g.DebugLogAutoDisableFrames |
| ImGuiContext.DebugLogSkippedErrors | スキップされたエラー数 | g.DebugLogSkippedErrors |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| なし | - | - | - |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[DebugLog呼び出し] --> B[DebugLogBufに追記]
    B --> C[DebugLogIndexに行を追加]
    C --> D{OutputToTTYフラグ?}
    D -->|Yes| E[IMGUI_DEBUG_PRINTFでTTY出力]
    D -->|No| F[スキップ]
    E --> G{OutputToDebuggerフラグ?}
    F --> G
    G -->|Yes| H[OutputDebugStringA出力]
    G -->|No| I{OutputToTestEngineフラグ?}
    H --> I
    I -->|Yes| J[IMGUI_TEST_ENGINE_LOG出力]
    I -->|No| Z[終了]
    J --> Z
```

### 表示フロー

```mermaid
flowchart TD
    A[ShowDebugLogWindow呼び出し] --> B[ウィンドウ開始]
    B --> C[フィルターチェックボックス表示]
    C --> D[Clear/Copyボタン]
    D --> E[ログ内容をスクロール表示]
    E --> F[ウィンドウ終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| デバッグツール無効 | IMGUI_DISABLE_DEBUG_TOOLS定義時 | なし（空実装） | マクロ定義を削除 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 無制限（Clearで削除可能） |
| 目標出力時間 | 即時 |
| メモリ使用量 | DebugLogBufサイズに依存 |

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

- デバッグログには内部状態が含まれるため、本番環境では無効化を推奨
- IMGUI_DISABLE_DEBUG_TOOLSマクロでコンパイル時に無効化可能

## 備考

- Shift+クリックでフラグをONにすると、2フレーム後に自動無効化される（スパム対策）
- InputRoutingはデフォルトで除外（非常に多くのログが出力されるため）
- Clearボタンでログとスキップエラーカウントがリセットされる
- Copyボタンでログ全体をクリップボードにコピー可能

---

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

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

### 推奨読解順序

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

まず、デバッグログで使用されるデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 1142-1143行目: DebugLog関数の宣言を確認 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiDebugLogFlags列挙型を確認 |
| 1-3 | imgui_internal.h | `imgui_internal.h` | ImGuiContextのDebugLog関連メンバを確認 |

**読解のコツ**: DebugLogFlagsの各フラグが何のイベントに対応しているかを把握する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | 17610-17616行目: DebugLog関数の実装 |
| 2-2 | imgui.cpp | `imgui.cpp` | 17618-17646行目: DebugLogV関数の実装 |

**主要処理フロー**:
1. **17621行目**: old_sizeを保存（後でインデックス追加に使用）
2. **17622-17625行目**: コンテキスト名+フレーム番号のプレフィックス追加
3. **17626行目**: フォーマットされたメッセージを追加
4. **17627行目**: DebugLogIndexに行を追加
5. **17630-17645行目**: 各種出力先への出力

#### Step 3: 表示ウィンドウを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | 17683-17719行目: ShowDebugLogWindow関数 |
| 3-2 | imgui.cpp | `imgui.cpp` | 17658-17681行目: ShowDebugLogFlag関数（チェックボックス表示） |

**主要処理フロー**:
- **17694-17707行目**: 各イベントカテゴリのチェックボックス表示
- **17709-17714行目**: Clear/Copyボタン
- **17719行目以降**: ログ内容の表示

#### Step 4: 自動無効化機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui.cpp | `imgui.cpp` | 17667-17671行目: Shift+クリックによる自動無効化設定 |
| 4-2 | imgui.cpp | `imgui.cpp` | 5703-5708行目: 自動無効化の実行 |

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

```
DebugLog(fmt, ...)
    │
    └─ DebugLogV(fmt, args)
           │
           ├─ g.DebugLogBuf.appendf("[%s] [%05d] ", ...)
           │
           ├─ g.DebugLogBuf.appendfv(fmt, args)
           │
           ├─ g.DebugLogIndex.append(...)
           │
           ├─ [OutputToTTY有効時]
           │      └─ IMGUI_DEBUG_PRINTF(...)
           │
           ├─ [OutputToDebugger有効時]
           │      └─ OutputDebugStringA(...)
           │
           └─ [OutputToTestEngine有効時]
                  └─ IMGUI_TEST_ENGINE_LOG(...)

ShowDebugLogWindow(p_open)
    │
    ├─ CheckboxFlags("All", ...)
    │
    ├─ ShowDebugLogFlag("Errors", ...)
    ├─ ShowDebugLogFlag("ActiveId", ...)
    ├─ ... [各カテゴリ]
    │
    ├─ SmallButton("Clear")
    │      └─ g.DebugLogBuf.clear()
    │
    ├─ SmallButton("Copy")
    │      └─ SetClipboardText(g.DebugLogBuf.c_str())
    │
    └─ [ログ内容表示]
```

### データフロー図

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

ImGui内部イベント ──────▶ DebugLog()
                              │
                              ▼
                        DebugLogV()
                              │
                              ├──────────────────▶ g.DebugLogBuf
                              │
                              ├──────────────────▶ stdout (TTY)
                              │
                              ├──────────────────▶ OutputDebugStringA
                              │
                              └──────────────────▶ TestEngine

ShowDebugLogWindow() ◀── g.DebugLogBuf ────────▶ ウィンドウ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 公開API宣言（DebugLog, ShowDebugLogWindow等） |
| imgui.cpp | `imgui.cpp` | ソース | デバッグログ機能の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiDebugLogFlags、内部データ構造定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | デモウィンドウでの使用例 |
