# 機能設計書 24-Begin

## 概要

本ドキュメントは、Dear ImGuiライブラリにおけるBegin機能の設計仕様を記述する。この機能は、新しいウィンドウをウィンドウスタックにプッシュし、そのウィンドウへのウィジェット追加を開始するための中核的な関数である。

### 本機能の処理概要

**業務上の目的・背景**：Dear ImGuiの即時モードGUIにおいて、ウィンドウは最も基本的なコンテナである。Begin関数はウィンドウを作成または再利用し、その中にウィジェットを配置するための領域を確保する。同一フレーム内で同じウィンドウ名に対してBegin/Endを複数回呼び出すことで、コンテンツを追記することも可能である。

**機能の利用シーン**：
- 新しいウィンドウを作成してウィジェットを配置する場合
- 既存のウィンドウにコンテンツを追記する場合
- 閉じるボタン付きのウィンドウを作成する場合
- 特定のフラグを持つウィンドウ（リサイズ不可、移動不可等）を作成する場合

**主要な処理内容**：
1. ウィンドウ名からウィンドウを検索または新規作成する
2. ウィンドウフラグの処理とウィンドウ状態の更新
3. ウィンドウスタックへのプッシュとコンテキストの設定
4. ウィンドウの位置、サイズ、スクロール等の初期化・更新
5. ウィンドウの描画（タイトルバー、背景、境界線等）
6. クリッピング領域の設定とコンテンツ領域の準備

**関連システム・外部連携**：ImGuiのウィンドウ管理システム、描画システム、入力システムと密接に連携する。

**権限による制御**：特になし。すべてのユーザーが任意のタイミングで呼び出し可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | Demo Window | 主機能 | ウィンドウの開始処理 |
| 2 | Metrics/Debugger Window | 主機能 | ウィンドウの開始処理 |
| 3 | Debug Log Window | 主機能 | ウィンドウの開始処理 |
| 4 | ID Stack Tool Window | 主機能 | ウィンドウの開始処理 |
| 5 | About Window | 主機能 | ウィンドウの開始処理 |
| 6 | Style Editor | 主機能 | ウィンドウの開始処理 |
| 10-22 | 各種ウィンドウ | 主機能 | ウィンドウの開始処理 |

## 機能種別

ウィンドウ管理 / UI構造制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | const char* | Yes | ウィンドウの識別子（タイトル）。##や###マーカーを使用してID制御可能 | NULL不可、空文字列不可 |
| p_open | bool* | No | 閉じるボタンの状態を受け取るポインタ。NULLの場合は閉じるボタン非表示 | NULLまたは有効なポインタ |
| flags | ImGuiWindowFlags | No | ウィンドウの動作を制御するフラグ | ImGuiWindowFlags_の組み合わせ |

### 入力データソース

- SetNextWindow*系関数で事前設定されたウィンドウパラメータ
- 前フレームからのウィンドウ状態（.iniファイルからの復元を含む）
- グローバルスタイル設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | bool | ウィンドウが折りたたまれていない場合はtrue、折りたたまれている場合はfalse。falseでも必ずEnd()を呼び出す必要がある |

### 出力先

- グローバルコンテキスト（現在のウィンドウ、ウィンドウスタック等）
- ウィンドウの描画リスト

## 処理フロー

### 処理シーケンス

```
1. ウィンドウの検索または作成
   └─ FindWindowByName()で既存ウィンドウを検索、なければCreateNewWindow()で作成
2. ウィンドウ状態の更新
   └─ Appearingフラグ、LastFrameActive等の更新
3. ウィンドウスタックへのプッシュ
   └─ CurrentWindowStack に追加、g.CurrentWindow を設定
4. フォーカススコープの設定
   └─ PushFocusScope() の呼び出し
5. SetNextWindow*パラメータの処理
   └─ 位置、サイズ、折りたたみ状態等の適用
6. ウィンドウのサイズ・位置計算
   └─ 制約の適用、自動リサイズの計算
7. ウィンドウの描画
   └─ 背景、タイトルバー、リサイズグリップ等の描画
8. クリッピングとコンテンツ領域の設定
   └─ PushClipRect() の呼び出し、DC.CursorPos の設定
```

### フローチャート

```mermaid
flowchart TD
    A[Begin開始] --> B[ウィンドウを検索/作成]
    B --> C{新規作成?}
    C -->|Yes| D[CreateNewWindow]
    C -->|No| E[既存ウィンドウを使用]
    D --> F[ウィンドウ状態の更新]
    E --> F
    F --> G[ウィンドウスタックにプッシュ]
    G --> H[SetNextWindow*パラメータの処理]
    H --> I[サイズ・位置の計算]
    I --> J{折りたたまれている?}
    J -->|Yes| K[最小限の描画]
    J -->|No| L[フル描画]
    K --> M[クリッピング設定]
    L --> M
    M --> N{SkipItems?}
    N -->|Yes| O[return false]
    N -->|No| P[return true]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | End必須 | Begin()を呼び出したら必ずEnd()を呼び出す必要がある | 常時 |
| BR-002 | 戻り値の意味 | falseが返っても描画処理をスキップしてEnd()を呼び出す必要がある | 常時 |
| BR-003 | ウィンドウ名の一意性 | ウィンドウ名はフレーム内で一意のIDを生成するために使用される | 常時 |
| BR-004 | ##マーカー | ウィンドウ名に##を含めると、##以降はタイトルに表示されずIDのみに使用される | ##を含む場合 |
| BR-005 | ###マーカー | ウィンドウ名に###を含めると、###以降のみがIDとして使用される | ###を含む場合 |

### 計算ロジック

- ウィンドウIDはウィンドウ名のハッシュから計算される
- ウィンドウサイズは制約、自動リサイズ、コンテンツサイズから計算される
- ウィンドウ位置はSetNextWindowPos、制約、デフォルト配置から決定される

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

### 操作別データベース影響一覧

なし（本機能はメモリ内のデータ構造のみを操作する。ただし、.iniファイルへの設定保存が関連する）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | アサーション失敗 | name が NULL または空文字列の場合 | 有効なウィンドウ名を指定する |
| - | アサーション失敗 | NewFrame()が呼び出されていない場合 | NewFrame()を先に呼び出す |
| - | アサーション失敗 | Render()/EndFrame()後にNewFrame()なしで呼び出した場合 | NewFrame()を呼び出す |

### リトライ仕様

なし

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

なし

## パフォーマンス要件

- 処理時間: ウィンドウの複雑さに依存するが、通常は数マイクロ秒から数十マイクロ秒
- メモリ使用: ウィンドウごとにImGuiWindow構造体（数KB）を使用

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

なし

## 備考

- Begin/Endは他のBeginXXX/EndXXXと異なり、Beginがfalseを返してもEndを呼び出す必要がある
- 同じウィンドウ名で複数回Begin/Endを呼び出すとコンテンツが追記される
- デフォルトで「Debug」という名前の暗黙的なウィンドウが存在する

---

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

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

### 推奨読解順序

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

ImGuiWindow構造体とImGuiWindowFlags列挙型を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiWindowFlags_列挙型（1163-1194行目） |
| 1-2 | imgui_internal.h | `imgui_internal.h` | ImGuiWindow構造体定義 |

**読解のコツ**: ImGuiWindowFlagsは約20種類のフラグを定義しており、ウィンドウの動作を細かく制御できる。

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

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

**主要処理フロー**:
1. **7353-7359行目**: 関数開始、引数検証
2. **7362-7365行目**: ウィンドウの検索または作成
3. **7379-7389行目**: Appearingフラグの更新
4. **7416-7427行目**: ウィンドウスタックへのプッシュ
5. **7457-7459行目**: SetNextWindow*パラメータの処理開始
6. **8136-8148行目**: 戻り値の決定

#### Step 3: ウィンドウ描画を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | ウィンドウ描画処理（7700行目以降） |

**主要処理フロー**:
- ウィンドウ背景の描画
- タイトルバーの描画
- リサイズグリップの描画
- スクロールバーの描画

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

```
Begin(name, p_open, flags)
    │
    ├─ FindWindowByName(name)
    │      └─ ウィンドウハッシュマップを検索
    │
    ├─ CreateNewWindow(name, flags) [新規の場合]
    │      └─ ImGuiWindow構造体の初期化
    │
    ├─ UpdateWindowParentAndRootLinks()
    │      └─ 親ウィンドウ、ルートウィンドウの設定
    │
    ├─ PushFocusScope()
    │
    ├─ ウィンドウサイズ・位置の計算
    │      ├─ ApplyWindowSettings()
    │      └─ CalcWindowSizeAfterConstraint()
    │
    ├─ ウィンドウの描画
    │      ├─ RenderWindowDecorations()
    │      └─ RenderWindowTitleBarContents()
    │
    └─ PushClipRect()
```

### データフロー図

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

name ──────────────────────▶
p_open ────────────────────▶  Begin()                 ──▶ bool (折りたたみ状態)
flags ─────────────────────▶     │
                                 ▼
SetNextWindow* で設定 ─────▶ ウィンドウ検索/作成
された値                         │
                                 ▼
                           状態更新・描画
                                 │
                                 ▼
                           g.CurrentWindow 設定 ────▶ ウィンドウスタック
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダ | API宣言、ImGuiWindowFlags_列挙型定義 |
| imgui.cpp | `imgui.cpp` | ソース | Begin関数の実装 |
| imgui_internal.h | `imgui_internal.h` | ヘッダ | ImGuiWindow構造体定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | ソース | 使用例 |
