# 機能設計書 85-Text

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるText関数の機能設計を定義する。Textは、printf形式のフォーマット付きテキストを表示する基本的なテキストウィジェット機能である。

### 本機能の処理概要

Text関数は、printf形式のフォーマット文字列と可変長引数を受け取り、フォーマットされたテキストを現在のカーソル位置に描画する機能を提供する。ImGuiで最も頻繁に使用されるテキスト表示関数である。

**業務上の目的・背景**：GUIアプリケーションにおいて、動的なテキスト（変数値、ステータス情報、デバッグ情報等）を表示することは基本的な要件である。Text関数はprintf形式のフォーマットをサポートすることで、数値や文字列を含むテキストを簡潔に表示できる。C言語のprintf関数に慣れた開発者にとって直感的なAPIを提供する。

**機能の利用シーン**：
- 変数の値をデバッグ表示する場合
- ステータス情報やメトリクス情報を表示する場合
- ユーザーへのメッセージや説明文を表示する場合
- フォーム項目のラベルを表示する場合

**主要な処理内容**：
1. 可変長引数の展開（va_start/va_end）
2. フォーマット文字列の処理（ImFormatStringToTempBufferV）
3. 内部バッファへのテキスト生成
4. TextEx関数による実際の描画

**関連システム・外部連携**：ImGuiContext、ImGuiWindow、ImDrawList

**権限による制御**：なし。すべてのImGuiユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | Metrics/Debugger Window | 補助機能 | メトリクス情報のテキスト表示 |
| 4 | ID Stack Tool Window | 補助機能 | IDスタック情報の表示 |
| 5 | About Window | 補助機能 | バージョン情報テキストの表示 |
| 10 | Console | 補助機能 | ログテキストの表示 |
| 15 | Auto Resize | 主機能 | 動的テキストの表示 |
| 17 | Simple Overlay | 補助機能 | オーバーレイ情報の表示 |
| 19 | Window Titles | 補助機能 | ウィンドウ内テキストの表示 |

## 機能種別

表示機能 / テキストウィジェット

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fmt | const char* | Yes | printf形式のフォーマット文字列 | NULLチェックなし |
| ... | 可変長引数 | No | フォーマット引数 | フォーマット文字列に対応 |

### 入力データソース

呼び出し元コードからの直接入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | void | 戻り値なし。描画コマンドが生成される |

### 出力先

ImDrawList（ウィンドウの描画リスト）

## 処理フロー

### 処理シーケンス

```
1. 可変長引数の初期化
   └─ va_start(args, fmt)
2. TextV関数の呼び出し
   └─ 実際の処理をTextVに委譲
3. 可変長引数の終了
   └─ va_end(args)

TextV内部処理:
4. ウィンドウのSkipItems確認
   └─ SkipItemsがtrueの場合は早期リターン
5. フォーマット処理
   └─ ImFormatStringToTempBufferVでフォーマット文字列を展開
6. TextEx関数の呼び出し
   └─ 実際の描画処理を実行
```

### フローチャート

```mermaid
flowchart TD
    A[Text開始] --> B[va_start]
    B --> C[TextV呼び出し]
    C --> D{SkipItems?}
    D -->|Yes| E[va_endして終了]
    D -->|No| F[ImFormatStringToTempBufferV]
    F --> G[TextEx呼び出し]
    G --> H[va_end]
    H --> I[終了]
    E --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | フォーマット文字列 | printf形式のフォーマット指定子（%d, %s, %f等）をサポート | 常時 |
| BR-02 | バッファサイズ | 内部バッファのサイズ制限あり（非常に長い出力は切り詰められる可能性） | 常時 |
| BR-03 | IM_FMTARGS属性 | コンパイラによるフォーマット文字列チェックが有効 | コンパイル時 |

### 計算ロジック

- フォーマット文字列の処理はImFormatStringToTempBufferV関数で行われる
- 内部テンポラリバッファを使用してフォーマット済みテキストを生成

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

該当なし（メモリ内操作のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | フォーマットエラー | 不正なフォーマット指定子 | 未定義動作（コンパイラ警告で事前検出推奨） |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- フォーマット処理のオーバーヘッドあり（vsprintf相当）
- 大量のテキスト表示にはTextUnformattedを推奨
- 1フレーム内で多数回呼び出し可能

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

- ユーザー入力をフォーマット文字列として直接使用しないこと（フォーマット文字列攻撃のリスク）
- ユーザー入力を表示する場合はTextUnformattedまたはText("%s", user_input)を使用

## 備考

- TextVはva_list版であり、可変長引数を直接受け取れない場合に使用
- IM_FMTARGS(1)マクロによりコンパイラのフォーマット文字列チェックが有効
- 長いテキストの表示にはTextUnformattedを推奨

---

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

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

### 推奨読解順序

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

テキスト描画に関連する構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | IM_FMTARGSマクロの役割 |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiWindowTempData構造体 |

**読解のコツ**: IM_FMTARGS(1)はコンパイラにフォーマット文字列の位置を伝えるための属性マクロである。

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

Text関数の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | Text/TextV関数宣言（615-616行目） |
| 2-2 | imgui_widgets.cpp | `imgui_widgets.cpp` | Text/TextV関数実装（273-290行目） |

**主要処理フロー**:
1. **273-279行目**: Text関数 - va_startで可変長引数を初期化し、TextVを呼び出し、va_endで終了
2. **281-290行目**: TextV関数
   - **283-285行目**: GetCurrentWindowとSkipItems確認
   - **287-288行目**: ImFormatStringToTempBufferVでフォーマット処理
   - **289行目**: TextExで実際の描画

#### Step 3: フォーマット処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | ImFormatStringToTempBufferV関数 |

**主要処理フロー**:
- 内部テンポラリバッファにvsprintfで文字列を生成
- バッファの開始/終了ポインタを返す

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

```
ImGui::Text(fmt, ...)
    │
    ├─ va_start(args, fmt)
    │
    └─ ImGui::TextV(fmt, args)
           │
           ├─ GetCurrentWindow()
           │
           ├─ ImFormatStringToTempBufferV(&text, &text_end, fmt, args)
           │
           └─ TextEx(text, text_end, ImGuiTextFlags_NoWidthForLargeClippedText)
                  │
                  └─ RenderTextWrapped() / RenderText()
```

### データフロー図

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

fmt + ...   ───▶ va_list展開 ───▶ フォーマット処理 ───▶ TextEx ───▶ 描画コマンド
                                       │
                                       └── 内部バッファ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | Text/TextV関数の宣言（615-616行目） |
| imgui_widgets.cpp | `imgui_widgets.cpp` | ソース | Text/TextV関数の実装（273-290行目） |
| imgui.cpp | `imgui.cpp` | ソース | ImFormatStringToTempBufferV関数 |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | 内部構造体定義 |
