# 機能設計書 223-GetForegroundDrawList

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける`GetForegroundDrawList`関数の機能設計書である。この関数は、すべてのImGuiコンテンツの前面（最後）に描画される描画リストを取得するためのユーティリティ関数である。

### 本機能の処理概要

`GetForegroundDrawList`関数は、ImGuiのウィンドウやウィジェットよりも前（前景側）に描画されるImDrawListを取得する機能を提供する。取得したImDrawListに対して図形やテキストを追加することで、ImGuiの標準UIコンテンツの上にカスタム描画を行うことができる。

**業務上の目的・背景**：GUIアプリケーション開発において、標準的なウィジェット描画の上に、ツールチップ、ドラッグ中の視覚フィードバック、デバッグ情報のオーバーレイ、選択範囲のハイライトなどを描画したい場合がある。本機能は、これらの前景描画を簡潔に実装するための手段を提供する。特に、ドラッグ操作中にマウス位置から元の位置への線を描画するなど、インタラクティブな視覚フィードバックの実装に有用である。

**機能の利用シーン**：
- ドラッグ操作中のビジュアルフィードバック（例：ドラッグ元からマウス位置への線描画）
- デバッグ用のオーバーレイ情報表示
- 選択範囲のハイライト描画
- カスタムツールチップやポップオーバーの描画
- ゲーム開発でUI層の上に追加の視覚効果を描画

**主要な処理内容**：
1. 引数なしのオーバーロードはメインビューポートの前景描画リストを返す
2. ビューポート引数ありのオーバーロードは指定ビューポートの前景描画リストを返す
3. 内部的にGetViewportBgFgDrawList関数を呼び出して描画リストを取得・初期化

**関連システム・外部連携**：レンダラーバックエンドが最終的な描画処理を担当する。描画リストのコマンドはImDrawDataを通じてバックエンドに渡される。

**権限による制御**：特にない。いつでも呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | Custom Rendering | 主画面 | カスタム描画のデモ（前景描画リストの使用例） |

## 機能種別

描画リスト取得（読み取り・書き込み可能なオブジェクト取得）

## 入力仕様

### 入力パラメータ

#### オーバーロード1（引数なし）
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | メインビューポートの前景描画リストを返す | - |

#### オーバーロード2（ビューポート指定）
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| viewport | ImGuiViewport* | Yes | 対象のビューポート | 有効なビューポートポインタ |

### 入力データソース

ImGuiコンテキスト（GImGui）内のビューポート情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ImDrawList* | 前景描画リストへのポインタ |

### ImDrawListの主要機能

| メソッド名 | 説明 |
|-----------|------|
| AddLine | 線を描画 |
| AddRect | 矩形（枠線）を描画 |
| AddRectFilled | 塗りつぶし矩形を描画 |
| AddCircle | 円（枠線）を描画 |
| AddCircleFilled | 塗りつぶし円を描画 |
| AddText | テキストを描画 |

### 出力先

呼び出し元への戻り値として返却。描画コマンドは内部的にImDrawDataに蓄積される。

## 処理フロー

### 処理シーケンス

```
1. 引数なしオーバーロードの場合
   └─ メインビューポート(Viewports[0])を取得
2. GetViewportBgFgDrawList内部関数を呼び出し
   └─ drawlist_no = 1（前景用）を指定
3. 描画リストが未作成の場合は新規作成
   └─ ImDrawList構造体を確保・初期化
4. フレーム開始時にリセット処理
   └─ 新フレームの場合は_ResetForNewFrameを呼び出し
5. クリップ矩形とテクスチャをプッシュ
   └─ ビューポート全体をクリップ領域として設定
6. 描画リストを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{引数あり?}
    B -->|No| C[メインビューポート取得]
    B -->|Yes| D[指定ビューポート使用]
    C --> E[GetViewportBgFgDrawList呼び出し]
    D --> E
    E --> F{描画リスト存在?}
    F -->|No| G[ImDrawList新規作成]
    F -->|Yes| H{新フレーム?}
    G --> H
    H -->|Yes| I[リセット処理]
    H -->|No| J[描画リスト返却]
    I --> J
    J --> K[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 描画順序 | 前景描画リストは最後にレンダリングされる | 常時 |
| BR-002 | フレーム毎のリセット | 新フレーム開始時に描画リストはリセットされる | 毎フレーム |
| BR-003 | クリップ矩形初期化 | ビューポート全体がデフォルトのクリップ矩形 | 描画リスト取得時 |

### 計算ロジック

特になし

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| なし | - | 本関数はエラーを発生させない | - |

### リトライ仕様

なし

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

該当なし

## パフォーマンス要件

- 描画リストは遅延初期化（初回呼び出し時に作成）
- フレーム毎のリセットは軽量な処理
- 描画コマンドはバッファに蓄積され、Render時にまとめて処理

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

特になし

## 備考

- GetBackgroundDrawListと対になる関数
- 旧API（GetOverlayDrawList）から名前変更された（バージョン1.69以降）
- dockingブランチではビューポート指定版の使用が重要になる

---

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

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

### 推奨読解順序

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

まず、描画リストを表現するImDrawList構造体を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImDrawList構造体の定義（3264-3380行目付近） |

**読解のコツ**: ImDrawListはCmdBuffer、IdxBuffer、VtxBufferの3つの主要バッファを持つ。これらがレンダラーに渡される描画データとなる。

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

GetForegroundDrawList関数のAPI宣言と実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 関数宣言（1033行目） |
| 2-2 | imgui.cpp | `imgui.cpp` | 関数実装（5186-5195行目） |

**主要処理フロー**:
1. **5191-5195行目**: 引数なし版の実装。Viewports[0]を引数に渡す
2. **5186-5189行目**: ビューポート指定版。GetViewportBgFgDrawListを呼び出し

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

GetViewportBgFgDrawList関数の詳細を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | GetViewportBgFgDrawList関数（5148-5173行目） |

**主要処理フロー**:
- **5152-5162行目**: 描画リストが未作成の場合の初期化処理
- **5165-5171行目**: 新フレーム開始時のリセット処理

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

```
ImGui::GetForegroundDrawList()
    │
    ├─ ImGui::GetForegroundDrawList(ImGuiViewport*)
    │      │
    │      └─ GetViewportBgFgDrawList(viewport, 1, "##Foreground")
    │             │
    │             ├─ ImDrawList初期化（初回のみ）
    │             │
    │             └─ _ResetForNewFrame()（フレーム毎）
    │
    └─ GImGui->Viewports[0]（メインビューポート）
```

### データフロー図

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

なし/Viewport ───▶ GetViewportBgFgDrawList ───▶ ImDrawList*
                           │
                           ├─ 描画リスト作成/取得
                           │
                           └─ クリップ矩形・テクスチャ設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | ImDrawList構造体定義、API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | GetForegroundDrawList関数実装 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（8093行目、10169行目） |
