# 機能設計書 189-LogToTTY

## 概要

本ドキュメントは、ImGuiライブラリのLogToTTY関数の機能設計を記述する。この関数はImGuiのテキスト出力をTTY（stdout）にログ出力するためのAPIである。

### 本機能の処理概要

LogToTTY関数は、ImGuiのUI出力（テキストウィジェット等）を標準出力（stdout）にキャプチャしてログ出力する機能を開始する。ロギングが有効な間、すべてのテキスト出力がstdoutにミラーリングされる。

**業務上の目的・背景**：デバッグやテスト目的で、ImGuiの画面出力をテキストとして記録する必要がある場合がある。LogToTTYは、UIの内容をコンソールに出力することで、自動テストやログ記録、デバッグ作業を支援する。

**機能の利用シーン**：
- デバッグ時のUI内容の確認
- 自動テストでのUI出力の検証
- コンソールへのUIテキストのリアルタイム出力
- スタイルエディタでの設定エクスポート

**主要な処理内容**：
1. ロギングが既に有効かどうかの確認
2. LogBegin内部関数の呼び出し（ImGuiLogFlags_OutputTTY）
3. g.LogFileをstdoutに設定
4. ロギング状態の有効化

**関連システム・外部連携**：
- LogFinishとの連携（ロギング終了）
- LogTextとの連携（直接テキスト出力）
- LogButtonsとの連携（UIボタン）
- 標準出力（stdout）への出力

**権限による制御**：本機能に権限制御はない。ただし、IMGUI_DISABLE_TTY_FUNCTIONSが定義されている場合は無効化される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Style Editor | 補助機能 | スタイルのエクスポート |

## 機能種別

ログ出力処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| auto_open_depth | int | No | ツリーノードの自動展開深度（デフォルト: -1） | -1で無制限、0以上で深度指定 |

### 入力データソース

- グローバルコンテキスト（g.LogEnabled）
- ロギング設定（g.LogDepthToExpandDefault）

## 出力仕様

### 出力データ

なし（void関数）

### 出力先

- 標準出力（stdout）
- グローバルロギング状態（g.LogEnabled, g.LogFile, g.LogFlags）

## 処理フロー

### 処理シーケンス

```
1. 既にロギングが有効かチェック
   └─ 有効な場合は即座にreturn
2. LogBegin内部関数の呼び出し
   └─ ImGuiLogFlags_OutputTTYフラグで初期化
3. g.LogFileをstdoutに設定
   └─ 出力先を標準出力に設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{g.LogEnabled?}
    B -->|Yes| C[return]
    B -->|No| D{TTY無効化?}
    D -->|Yes| C
    D -->|No| E[LogBegin呼び出し]
    E --> F[g.LogFile = stdout]
    F --> G[終了]
    C --> G
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-189-01 | 排他制御 | 一度に1つのロギングモードのみ有効 | 常時 |
| BR-189-02 | 終了必須 | LogFinishで明示的に終了する必要がある | ロギング開始後 |
| BR-189-03 | TTY無効化 | IMGUI_DISABLE_TTY_FUNCTIONSで無効化可能 | ビルド設定 |
| BR-189-04 | ツリー展開 | ロギング中はツリーノードが自動展開される | ロギング中 |

### 計算ロジック

特になし

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

該当なし（ImGuiはUIライブラリであり、データベース操作は行わない）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 無視 | 既にロギングが有効 | 何もしない |
| N/A | 無効化 | IMGUI_DISABLE_TTY_FUNCTIONS定義時 | コンパイル時に無効化 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- ロギングによるパフォーマンスへの影響は最小限であること
- stdoutへの書き込みはバッファリングされる

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

- 標準出力にUIの内容が出力されるため、機密情報を含む可能性がある

## 備考

- IMGUI_DISABLE_TTY_FUNCTIONSが定義されている場合、この関数は何もしない
- IMGUI_DISABLE_DEFAULT_FILE_FUNCTIONSが定義されている場合もLogToTTYは無効になる
- ロギング中はデフォルトでツリーノードが自動展開される
- LogFinishを呼び出すとfflush(stdout)が実行される

---

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

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

### 推奨読解順序

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

まず、ロギングに関連するデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiLogFlags列挙型 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiContext構造体のLogEnabled, LogFile, LogFlagsフィールド |

**読解のコツ**: ImGuiLogFlagsは出力先を示し、ImGuiLogFlags_OutputTTYがstdout出力を表す。

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

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

**主要処理フロー**:
1. **15177-15179行目**: LogEnabled確認
2. **15180行目**: IM_UNUSED（auto_open_depth）
3. **15181-15182行目**: IMGUI_DISABLE_TTY_FUNCTIONSチェックとLogBegin呼び出し
4. **15183行目**: g.LogFile = stdout

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | LogBegin関数（ロギング初期化） |
| 3-2 | imgui.cpp | `imgui.cpp` | LogFinish関数（15229-15261行目）でのTTYフラッシュ処理 |

**主要処理フロー**:
- LogBeginでロギング状態を初期化
- LogFinishでfflush(g.LogFile)を実行

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

```
ImGui::LogToTTY(auto_open_depth)
    │
    ├─ (チェック: g.LogEnabled)
    │
    ├─ LogBegin(ImGuiLogFlags_OutputTTY, auto_open_depth)
    │      └─ ロギング状態の初期化
    │
    └─ g.LogFile = stdout
```

### データフロー図

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

auto_open_depth ───▶ LogToTTY() ──────────▶ g.LogEnabled = true
                           │                  g.LogFile = stdout
                           │                  g.LogFlags = OutputTTY
                           │
                           └─ LogBegin()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | LogToTTY実装 |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | ImGuiLogFlags定義 |
| imconfig.h | `imconfig.h` | 設定 | IMGUI_DISABLE_TTY_FUNCTIONS設定 |
