# 機能設計書 1-CreateContext

## 概要

本ドキュメントはDear ImGuiライブラリのCreateContext関数に関する機能設計書である。CreateContextはImGuiコンテキストを作成し、ライブラリの初期化を行う最も基本的な関数である。

### 本機能の処理概要

CreateContext関数は、ImGuiライブラリを使用するための中心的なデータ構造であるImGuiContextを新規に作成・初期化する機能を提供する。

**業務上の目的・背景**：ImGuiはImmediate Mode GUIライブラリであり、すべてのUI状態やレンダリング情報を単一のコンテキスト（ImGuiContext）で管理する。アプリケーションがImGuiを使用してGUIを描画するためには、まずこのコンテキストを作成する必要がある。複数のコンテキストを作成することで、複数の独立したGUI環境を構築することも可能である。DLL境界を跨ぐ場合やマルチスレッド環境では、適切なコンテキスト管理が必要となる。

**機能の利用シーン**：
- アプリケーション起動時のImGui初期化処理
- 複数の独立したImGui環境が必要な場合（例：複数ウィンドウ、プラグインシステム）
- DLL/共有ライブラリを使用する場合のコンテキスト管理
- テスト環境での独立したGUIコンテキスト作成

**主要な処理内容**：
1. 新しいImGuiContextインスタンスをヒープメモリ上に確保
2. フォントアトラスの設定（引数で指定された共有アトラスまたは新規作成）
3. 現在のコンテキストとして設定
4. Initialize()関数による内部状態の初期化
5. 以前のコンテキストが存在した場合は復元

**関連システム・外部連携**：
- ImFontAtlas：フォントアトラスの共有が可能
- プラットフォームバックエンド（Win32、GLFW、SDL等）：バックエンドの初期化に先立って呼び出す必要がある
- レンダラーバックエンド（OpenGL、DirectX、Vulkan等）：同様にレンダラー初期化前に必要

**権限による制御**：特になし。ただし、DLL境界を跨ぐ場合はSetCurrentContext()とSetAllocatorFunctions()の追加呼び出しが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 全ての画面の前提となる初期化処理 |

## 機能種別

初期化処理 / コンテキスト管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| shared_font_atlas | ImFontAtlas* | No | 複数コンテキスト間で共有するフォントアトラス。NULLの場合は新規作成 | NULLまたは有効なImFontAtlasポインタ |

### 入力データソース

- アプリケーションコード（オプショナル引数）
- 既存のImFontAtlasインスタンス（共有する場合）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ImGuiContext* | 新規作成されたImGuiContextへのポインタ |

### 出力先

- ヒープメモリ上に確保されたImGuiContextインスタンス
- グローバル変数GImGui（最初のコンテキストの場合）

## 処理フロー

### 処理シーケンス

```
1. 現在のコンテキストを保存
   └─ GetCurrentContext()で既存のコンテキストを取得

2. 新しいImGuiContextを確保
   └─ IM_NEW(ImGuiContext)(shared_font_atlas)でヒープ上にインスタンス作成

3. 新しいコンテキストを現在のコンテキストとして設定
   └─ SetCurrentContext(ctx)で設定

4. 内部状態を初期化
   └─ Initialize()で設定ハンドラ登録、デフォルト値設定等

5. 以前のコンテキストを復元（存在する場合）
   └─ prev_ctxがNULLでなければSetCurrentContext(prev_ctx)

6. 新しいコンテキストを返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[現在のコンテキストを保存<br/>prev_ctx = GetCurrentContext]
    B --> C[新しいImGuiContextを作成<br/>IM_NEW ImGuiContext]
    C --> D[新しいコンテキストを設定<br/>SetCurrentContext ctx]
    D --> E[Initialize 内部初期化]
    E --> F{prev_ctx != NULL?}
    F -->|Yes| G[以前のコンテキストを復元<br/>SetCurrentContext prev_ctx]
    F -->|No| H[新しいコンテキストを維持]
    G --> I[新しいコンテキストを返却]
    H --> I
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | コンテキスト初期化 | 最初のCreateContext呼び出しでGImGuiグローバル変数が設定される | GImGuiがNULLの場合 |
| BR-02 | フォントアトラス共有 | shared_font_atlasがNULLの場合、コンテキスト独自のフォントアトラスが作成される | 引数がNULLの場合 |
| BR-03 | コンテキスト復元 | 既存のコンテキストがある場合、CreateContext後に元のコンテキストに戻す | prev_ctxがNULLでない場合 |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| IM_ASSERT | アサート失敗 | メモリ確保失敗 | メモリ不足の解消 |
| IM_ASSERT | アサート失敗 | 不正なフォントアトラスポインタ | 有効なポインタを渡す |

### リトライ仕様

特になし

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

該当なし

## パフォーマンス要件

- 初期化処理は1回のみ実行されるため、パフォーマンス要件は特になし
- 大量のメモリ確保が行われるため、起動時に十分なヒープメモリが必要

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

- DLL境界を跨ぐ場合、SetAllocatorFunctions()でメモリアロケータを統一する必要がある
- マルチスレッド環境では、thread_local変数を使用してコンテキストを分離することを推奨

## 備考

- バージョン1.60以降、CreateContext/DestroyContextの呼び出しが必須となった
- 以前のShutdown()関数はDestroyContext()に置き換えられた

---

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

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

### 推奨読解順序

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

ImGuiContextの構造を理解することが重要。この構造体はライブラリのすべての状態を保持する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_internal.h | `imgui_internal.h` | ImGuiContext構造体の定義（2189行目付近）。IO、Style、Font情報、ウィンドウ管理等のメンバを確認 |

**読解のコツ**: ImGuiContextは非常に大きな構造体であり、以下のカテゴリに分類される:
- 基本状態（Initialized、FrameCount等）
- IO/スタイル（IO、Style）
- フォント関連（Font、FontBaked、FontSize等）
- ウィンドウ管理（Windows、CurrentWindow等）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui.h | `imgui.h` | 392行目: CreateContextのAPI宣言 |
| 2-2 | imgui.cpp | `imgui.cpp` | 4076-4085行目: CreateContext関数の実装 |

**主要処理フロー**:
1. **4078行目**: 現在のコンテキストを保存 `prev_ctx = GetCurrentContext()`
2. **4079行目**: 新しいコンテキストを作成 `IM_NEW(ImGuiContext)(shared_font_atlas)`
3. **4080行目**: 新しいコンテキストを設定 `SetCurrentContext(ctx)`
4. **4081行目**: 初期化処理 `Initialize()`
5. **4082-4083行目**: 以前のコンテキストがあれば復元

#### Step 3: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | 4047-4050行目: GetCurrentContext()の実装 |
| 3-2 | imgui.cpp | `imgui.cpp` | 4052-4059行目: SetCurrentContext()の実装 |
| 3-3 | imgui.cpp | `imgui.cpp` | 4345-4416行目: Initialize()の実装 |

**主要処理フロー**:
- **4048行目**: GetCurrentContextはGImGuiグローバル変数を返す
- **4057行目**: SetCurrentContextはGImGuiグローバル変数を設定
- **4345行目以降**: Initializeは設定ハンドラの登録、ローカライゼーション設定等を行う

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

```
ImGui::CreateContext(shared_font_atlas)
    │
    ├─ ImGui::GetCurrentContext()
    │      └─ return GImGui
    │
    ├─ IM_NEW(ImGuiContext)(shared_font_atlas)
    │      └─ ImGuiContext constructor
    │
    ├─ ImGui::SetCurrentContext(ctx)
    │      └─ GImGui = ctx
    │
    ├─ ImGui::Initialize()
    │      ├─ Settings handler registration
    │      ├─ Localization setup
    │      └─ Default state initialization
    │
    └─ ImGui::SetCurrentContext(prev_ctx) [if prev_ctx != NULL]
```

### データフロー図

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

shared_font_atlas ───────▶ ImGuiContext constructor ─────▶ 新しいImGuiContext*
(optional)                         │
                                   │
                                   ▼
                           Initialize()で
                           内部状態初期化
                                   │
                                   ▼
                           GImGui（最初の場合）
                           または返却のみ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | パブリックAPI宣言（392行目） |
| imgui.cpp | `imgui.cpp` | ソース | 実装（4076-4085行目） |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | ImGuiContext構造体定義（2189行目） |
| imconfig.h | `imconfig.h` | 設定 | コンパイル時設定（IMGUI_SET_CURRENT_CONTEXT_FUNC等） |
