# 機能設計書 190-LogToFile

## 概要

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

### 本機能の処理概要

LogToFile関数は、ImGuiのUI出力（テキストウィジェット等）をファイルにキャプチャしてログ出力する機能を開始する。ファイル名を指定しない場合は、io.LogFilename（デフォルト: "imgui_log.txt"）が使用される。

**業務上の目的・背景**：UI出力を永続的に保存してデバッグやテストに活用するニーズがある。LogToFileは、UIの内容をファイルに保存することで、後からの分析やログ記録を可能にする。

**機能の利用シーン**：
- UIの出力内容を記録してデバッグ
- 自動テストでのUI出力の保存
- 設定やスタイルのエクスポート
- UI状態のスナップショット保存

**主要な処理内容**：
1. ロギングが既に有効かどうかの確認
2. ファイル名の決定（パラメータまたはio.LogFilename）
3. ファイルのオープン（バイナリ追記モード "ab"）
4. LogBegin内部関数の呼び出し
5. g.LogFileにファイルハンドルを設定

**関連システム・外部連携**：
- LogFinishとの連携（ロギング終了、ファイルクローズ）
- LogTextとの連携（直接テキスト出力）
- io.LogFilenameとの連携（デフォルトファイル名）
- ファイルシステムへの出力

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

## 関連画面

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

## 機能種別

ファイル出力処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| auto_open_depth | int | No | ツリーノードの自動展開深度（デフォルト: -1） | -1で無制限、0以上で深度指定 |
| filename | const char* | No | 出力ファイル名（デフォルト: NULL） | NULLの場合はio.LogFilenameを使用 |

### 入力データソース

- グローバルコンテキスト（g.LogEnabled）
- IO設定（io.LogFilename）

## 出力仕様

### 出力データ

なし（void関数）

### 出力先

- 指定されたファイル（またはio.LogFilename）
- グローバルロギング状態（g.LogEnabled, g.LogFile, g.LogFlags）

## 処理フロー

### 処理シーケンス

```
1. 既にロギングが有効かチェック
   └─ 有効な場合は即座にreturn
2. ファイル名の決定
   └─ filenameがNULLの場合はio.LogFilenameを使用
3. ファイル名の検証
   └─ 空の場合は即座にreturn
4. ファイルのオープン
   └─ バイナリ追記モード "ab" でオープン
5. オープン失敗時の処理
   └─ アサーション、return
6. LogBegin内部関数の呼び出し
7. g.LogFileにファイルハンドルを設定
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{g.LogEnabled?}
    B -->|Yes| C[return]
    B -->|No| D{filename指定?}
    D -->|No| E[filename = io.LogFilename]
    D -->|Yes| F{filename空?}
    E --> F
    F -->|Yes| C
    F -->|No| G[ImFileOpen - ab]
    G --> H{オープン成功?}
    H -->|No| I[アサーション、return]
    H -->|Yes| J[LogBegin]
    J --> K[g.LogFile = f]
    K --> L[終了]
    C --> L
    I --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-190-01 | 排他制御 | 一度に1つのロギングモードのみ有効 | 常時 |
| BR-190-02 | 終了必須 | LogFinishでファイルをクローズする必要がある | ロギング開始後 |
| BR-190-03 | デフォルトファイル | ファイル名未指定時はio.LogFilename使用 | filename=NULL時 |
| BR-190-04 | 追記モード | ファイルはバイナリ追記モードでオープン | 常時 |
| BR-190-05 | io.LogFilename無効化 | io.LogFilenameがNULLの場合はロギング無効 | 設定による |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | 無視 | 既にロギングが有効 | 何もしない |
| N/A | 無視 | ファイル名が空 | 何もしない |
| N/A | アサーション | ファイルオープン失敗 | IM_ASSERT(0)、return |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- ファイルI/Oによるパフォーマンス影響は最小限であること
- バイナリモードでの書き込みで効率化

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

- ファイルにUIの内容が出力されるため、機密情報を含む可能性がある
- ファイルのアクセス権限はOSの設定に依存

## 備考

- デフォルトのファイル名は "imgui_log.txt"（io.LogFilename）
- ファイルはバイナリ追記モード "ab" でオープンされる
- LogFinishを呼び出すとファイルがクローズされる
- IM_NEWLINEを使用しないとOS非互換の改行になる可能性がある
- io.LogFilenameをNULLに設定するとデフォルトのファイルロギングを無効化できる

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiIO構造体のLogFilenameフィールド（2405行目） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiLogFlags_OutputFile |

**読解のコツ**: io.LogFilenameはデフォルトのログファイル名を保持し、"imgui_log.txt"が初期値。

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

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

**主要処理フロー**:
1. **15190-15192行目**: LogEnabled確認
2. **15197-15200行目**: ファイル名の決定と検証
3. **15201行目**: ImFileOpenでファイルオープン
4. **15202-15206行目**: オープン失敗時の処理
5. **15208-15209行目**: LogBegin呼び出しとg.LogFile設定

#### Step 3: 終了処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | LogFinish関数のファイルクローズ処理（15243-15244行目） |

**主要処理フロー**:
- ImFileClose(g.LogFile)でファイルをクローズ

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

```
ImGui::LogToFile(auto_open_depth, filename)
    │
    ├─ (チェック: g.LogEnabled)
    │
    ├─ (ファイル名決定: filename または io.LogFilename)
    │
    ├─ ImFileOpen(filename, "ab")
    │      └─ ファイルオープン
    │
    ├─ LogBegin(ImGuiLogFlags_OutputFile, auto_open_depth)
    │      └─ ロギング状態の初期化
    │
    └─ g.LogFile = f
```

### データフロー図

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

auto_open_depth ───▶ LogToFile() ─────────▶ g.LogEnabled = true
filename                   │                  g.LogFile = file handle
io.LogFilename             │                  g.LogFlags = OutputFile
                           │
                           ├─ ファイル名決定
                           ├─ ファイルオープン
                           └─ LogBegin()
```

### 関連ファイル一覧

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