# 帳票設計書 1-TTYログ出力

## 概要

本ドキュメントは、Dear ImGuiライブラリのTTY（標準出力）ログ出力機能に関する帳票設計書である。GUIのテキスト出力をstdoutにキャプチャしてログとして出力する機能について記述する。

### 本帳票の処理概要

TTYログ出力機能は、ImGuiウィジェットから生成されるテキスト出力をリアルタイムでTTY（端末/標準出力）にキャプチャする機能である。

**業務上の目的・背景**：GUI開発において、ウィジェットの状態やユーザー操作をコンソール上で追跡することは、デバッグやテスト時に非常に重要である。TTYログ出力機能により、アプリケーション実行中のGUI状態を端末上でリアルタイムに監視でき、グラフィカルなデバッグツールが利用できない環境（リモートサーバー、CI環境など）でも有効な診断情報を得ることが可能となる。

**帳票の利用シーン**：主にデバッグ目的で利用される。開発者がウィンドウ構造、ウィジェット階層、ユーザー入力などを確認したい場合に、LogToTTY関数を呼び出してログキャプチャを開始し、LogFinish関数で終了する。また、LogButtons関数によりGUI上のボタンからも簡便にログ出力を開始できる。

**主要な出力内容**：
1. ウィジェットのテキストラベル（Button、Text、TreeNodeなど）
2. ツリー構造のインデント（TreeDepthに応じた4スペースのインデント）
3. LogText関数で直接出力されたカスタムテキスト
4. ウィジェットの装飾テキスト（prefix/suffix）

**帳票の出力タイミング**：LogToTTY関数が呼び出された時点からログキャプチャが開始され、LogFinish関数が呼び出されるまで継続する。出力はリアルタイムでstdoutに書き出される。

**帳票の利用者**：アプリケーション開発者、QAエンジニア、テスト自動化担当者

## 帳票種別

ログ出力（テキストストリーム形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | 任意のImGuiウィンドウ | - | LogToTTY()関数呼び出し |
| - | デモウィンドウ | - | LogButtonsからの「Log To TTY」ボタン |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | テキストストリーム（stdout） |
| 用紙サイズ | N/A（コンソール出力） |
| 向き | N/A |
| ファイル名 | N/A（標準出力へ直接出力） |
| 出力方法 | stdout（端末/コンソール） |
| 文字コード | システム依存（通常UTF-8） |

### TTY固有設定

| 項目 | 内容 |
|-----|------|
| 出力先 | stdout |
| バッファリング | fflush()による即時フラッシュ |
| 無効化マクロ | IMGUI_DISABLE_TTY_FUNCTIONS |

## 帳票レイアウト

### レイアウト概要

テキストベースのログ出力であり、階層構造をインデントで表現する。

```
[ウィンドウ/ウィジェットテキスト]
    [子ウィジェットテキスト（4スペースインデント）]
        [孫ウィジェット（8スペースインデント）]
[改行による区切り]
```

### 出力項目

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | テキスト内容 | ウィジェットが表示するテキスト | ImGui::LogRenderedText | プレーンテキスト |
| 2 | インデント | ツリー深度に応じた空白 | TreeDepth * 4 | スペース文字 |
| 3 | 改行 | 行の区切り | IM_NEWLINE | LF または CRLF |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| LogEnabled | ログ機能が有効であること | Yes |
| TTY Functions未無効化 | IMGUI_DISABLE_TTY_FUNCTIONSが定義されていないこと | Yes |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | 描画順 | 昇順（ウィジェット描画順） |

### 改ページ条件

N/A（ストリーム出力のため改ページ概念なし）

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

### 参照テーブル一覧

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

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

| データ構造 | 用途 | アクセス方法 |
|-----------|------|-------------|
| ImGuiContext.LogFile | 出力先ファイルハンドル | g.LogFile |
| ImGuiContext.LogEnabled | ログ有効フラグ | g.LogEnabled |
| ImGuiContext.LogFlags | ログ種別フラグ | g.LogFlags |
| ImGuiContext.LogBuffer | 一時バッファ | g.LogBuffer |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| インデント幅 | TreeDepth * 4 | なし | スペース文字数 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[LogToTTY呼び出し] --> B{既にログ有効?}
    B -->|Yes| Z[終了]
    B -->|No| C[LogBegin実行]
    C --> D[LogFile = stdout設定]
    D --> E[ログキャプチャ開始]
    E --> F[ウィジェット描画]
    F --> G[LogRenderedText呼び出し]
    G --> H[テキストをstdoutへ出力]
    H --> I{LogFinish呼び出し?}
    I -->|No| F
    I -->|Yes| J[fflush実行]
    J --> K[ログ状態リセット]
    K --> Z
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| 既にログ有効 | LogToTTY呼び出し時に既にログが有効 | なし（早期リターン） | 既存ログセッションを終了後に再開 |
| TTY無効化 | IMGUI_DISABLE_TTY_FUNCTIONS定義時 | なし（関数が空実装） | マクロ定義を削除 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 無制限 |
| 目標出力時間 | リアルタイム |
| 同時出力数上限 | 1（同時に1つのログセッションのみ） |

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

- 機密情報がログに含まれる可能性があるため、本番環境での使用には注意が必要
- stdoutはリダイレクト可能であり、意図しないファイルへの書き込みに注意

## 備考

- TTY機能はIMGUI_DISABLE_TTY_FUNCTIONSマクロにより無効化可能
- auto_open_depth引数により、ツリーノードの自動展開深度を制御可能（-1でデフォルト値使用）

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | 959-965行目: LogToTTY, LogToFile, LogToClipboard, LogFinish, LogButtons, LogText関数の宣言を確認 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiLogFlags列挙型、ImGuiContextのログ関連メンバを確認 |

**読解のコツ**: imgui.hの関数宣言コメントで機能概要を把握し、imgui_internal.hで内部状態管理の仕組みを理解する。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.cpp | `imgui.cpp` | 15175-15185行目: LogToTTY関数の実装 |

**主要処理フロー**:
1. **15177行目**: ImGuiContextの取得
2. **15178-15179行目**: 既にログ有効なら早期リターン
3. **15182行目**: LogBegin関数でログセッション開始
4. **15183行目**: stdout（標準出力）をログ出力先に設定

#### Step 3: ログ基盤処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | 15149-15165行目: LogBegin関数（ログセッション初期化） |
| 3-2 | imgui.cpp | `imgui.cpp` | 15052-15064行目: LogTextV関数（テキスト出力の基盤） |
| 3-3 | imgui.cpp | `imgui.cpp` | 15087-15146行目: LogRenderedText関数（ウィジェットテキストの出力） |

**主要処理フロー**:
- **15157行目**: g.LogEnabled = trueでログ有効化
- **15161-15162行目**: ツリー深度の参照値を設定

#### Step 4: ログ終了処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui.cpp | `imgui.cpp` | 15229-15261行目: LogFinish関数 |

**主要処理フロー**:
- **15235行目**: 最終改行の出力
- **15238-15241行目**: TTYの場合はfflush実行
- **15257-15260行目**: ログ状態のリセット

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

```
LogToTTY(auto_open_depth)
    │
    ├─ LogBegin(ImGuiLogFlags_OutputTTY, auto_open_depth)
    │      ├─ g.LogEnabled = true
    │      ├─ g.LogFlags = flags
    │      └─ g.LogDepthRef = window->DC.TreeDepth
    │
    └─ g.LogFile = stdout
           │
           └─ [ウィジェット描画時]
                  │
                  └─ LogRenderedText(ref_pos, text, text_end)
                         │
                         └─ LogText(fmt, ...)
                                │
                                └─ LogTextV(g, fmt, args)
                                       │
                                       └─ fprintf(g.LogFile, ...)

LogFinish()
    │
    ├─ LogText(IM_NEWLINE)
    ├─ fflush(g.LogFile)  [TTYの場合]
    └─ g.LogEnabled = false
```

### データフロー図

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

LogToTTY() ───────────▶ LogBegin()
                              │
                              ▼
ウィジェット描画 ─────────▶ LogRenderedText()
                              │
                              ▼
                        LogTextV() ────────────────▶ stdout (TTY)
                              │
                              ▼
LogFinish() ──────────▶ fflush() ──────────────────▶ [出力完了]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | 公開API宣言（LogToTTY, LogFinish等） |
| imgui.cpp | `imgui.cpp` | ソース | ログ機能の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | 内部データ構造定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | LogButtons関数の使用例 |
| imconfig.h | `imconfig.h` | 設定 | IMGUI_DISABLE_TTY_FUNCTIONS等のマクロ定義場所 |
