# アーキテクチャ設計書

## 概要

本ドキュメントは、Dear ImGui (Version 1.92.7 WIP) のアーキテクチャ設計を記載するものである。Dear ImGuiは、C++で実装されたブラウザやゲームエンジン等に組み込み可能なImmediate Mode GUI (IMGUI)ライブラリであり、プラットフォームとレンダラーを抽象化するバックエンドアーキテクチャを採用している。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図.md](./アーキテクチャ構成図.md) を参照。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| プラットフォームAPI (Win32, SDL, GLFW等) | Platform Backend経由 | マウス/キーボード入力、ウィンドウ管理、クリップボード、IME |
| グラフィックスAPI (DirectX, OpenGL, Vulkan等) | Renderer Backend経由 | テクスチャ生成・更新、描画コマンドのレンダリング |
| フォントローダー (stb_truetype, FreeType) | 内部統合/オプション連携 | TTF/OTFフォントのラスタライズ |
| ホストアプリケーション | ImGui API呼び出し | UI定義、イベント処理、描画データ取得 |

## レイヤー構成

### アーキテクチャスタイル

**Immediate Mode GUI (IMGUI) パラダイム + バックエンド抽象化レイヤー**

- 従来のRetained Mode GUIとは異なり、UIの状態をライブラリ側で保持せず、毎フレームUIを再構築する設計
- プラットフォーム依存部分をBackendとして分離し、コアライブラリのポータビリティを確保
- シングルパス・ラスタライザ実装により、効率的な描画データ生成を実現

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Public API Layer | エンドユーザー向けAPI提供、ウィジェット・ウィンドウ管理 | `ImGui::` namespace関数、imgui.h |
| Core Layer | コンテキスト管理、レイアウト計算、入力処理、スタイリング | ImGuiContext, ImGuiIO, ImGuiStyle, imgui.cpp |
| Widget Layer | 各種ウィジェットの実装 | imgui_widgets.cpp (Button, InputText, Slider等) |
| Table Layer | テーブル・カラム機能の実装 | imgui_tables.cpp |
| Drawing Layer | 描画コマンドリスト生成、フォントアトラス管理 | ImDrawList, ImDrawData, ImFontAtlas, imgui_draw.cpp |
| Backend Layer | プラットフォーム・レンダラー抽象化 | imgui_impl_xxx.cpp/h (backends/) |
| Demo/Debug Layer | デモウィンドウ、デバッグツール | imgui_demo.cpp, ShowMetricsWindow等 |

### レイヤー間の依存関係ルール

```
[Host Application]
       |
       v
[Public API Layer] <-- ユーザーコードからの唯一のエントリポイント
       |
       v
[Core Layer] <------> [Widget Layer] <------> [Table Layer]
       |
       v
[Drawing Layer] ----> 描画データ(ImDrawData)を生成
       |
       v
[Backend Layer] ----> プラットフォーム固有のレンダリング実行
```

**依存の方向性:**
- 上位レイヤーは下位レイヤーに依存可能
- 下位レイヤーから上位レイヤーへの依存は禁止 (コールバック経由を除く)
- Core/Widget/TableレイヤーはDrawing Layerに依存し描画コマンドを発行
- Backend LayerはDrawing Layerの出力 (ImDrawData) を消費
- imgui_internal.hを経由することでCore Layerの内部構造にアクセス可能 (互換性保証なし)

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| コアシステム | コンテキスト管理、初期化/終了、設定、I/O | imgui.cpp, ImGuiContext, ImGuiIO |
| ウィジェット | UI要素の描画と入力処理 | imgui_widgets.cpp |
| テーブル | テーブル/カラムレイアウトと描画 | imgui_tables.cpp |
| 描画 | 頂点バッファ生成、フォント管理 | imgui_draw.cpp, ImDrawList, ImFontAtlas |
| デモ/デバッグ | デモウィンドウ、メトリクス、デバッグツール | imgui_demo.cpp |
| プラットフォーム | OS/ウィンドウシステム統合 | imgui_impl_win32, imgui_impl_glfw, imgui_impl_sdl等 |
| レンダラー | グラフィックスAPI統合 | imgui_impl_dx11, imgui_impl_opengl3, imgui_impl_vulkan等 |

### パッケージ構造

```
imgui-master/
├── imgui.h                    # パブリックAPI宣言
├── imgui.cpp                  # コア実装
├── imgui_internal.h           # 内部API/構造体宣言 (互換性保証なし)
├── imgui_widgets.cpp          # ウィジェット実装
├── imgui_tables.cpp           # テーブル/カラム実装
├── imgui_draw.cpp             # 描画/フォント実装
├── imgui_demo.cpp             # デモウィンドウ実装
├── imconfig.h                 # コンパイル時設定
├── imstb_rectpack.h           # 組み込みライブラリ (stb_rect_pack)
├── imstb_textedit.h           # 組み込みライブラリ (stb_textedit)
├── imstb_truetype.h           # 組み込みライブラリ (stb_truetype)
├── backends/                  # バックエンド実装
│   ├── imgui_impl_win32.cpp/h     # Platform: Win32
│   ├── imgui_impl_glfw.cpp/h      # Platform: GLFW
│   ├── imgui_impl_sdl2.cpp/h      # Platform: SDL2
│   ├── imgui_impl_sdl3.cpp/h      # Platform: SDL3
│   ├── imgui_impl_osx.mm/h        # Platform: macOS
│   ├── imgui_impl_android.cpp/h   # Platform: Android
│   ├── imgui_impl_glut.cpp/h      # Platform: GLUT
│   ├── imgui_impl_dx9.cpp/h       # Renderer: DirectX 9
│   ├── imgui_impl_dx10.cpp/h      # Renderer: DirectX 10
│   ├── imgui_impl_dx11.cpp/h      # Renderer: DirectX 11
│   ├── imgui_impl_dx12.cpp/h      # Renderer: DirectX 12
│   ├── imgui_impl_opengl2.cpp/h   # Renderer: OpenGL 2 (Legacy)
│   ├── imgui_impl_opengl3.cpp/h   # Renderer: OpenGL 3/4/ES/WebGL
│   ├── imgui_impl_vulkan.cpp/h    # Renderer: Vulkan
│   ├── imgui_impl_metal.mm/h      # Renderer: Metal
│   ├── imgui_impl_wgpu.cpp/h      # Renderer: WebGPU
│   ├── imgui_impl_sdlrenderer2.cpp/h  # Renderer: SDL_Renderer (SDL2)
│   ├── imgui_impl_sdlrenderer3.cpp/h  # Renderer: SDL_Renderer (SDL3)
│   ├── imgui_impl_sdlgpu3.cpp/h   # Renderer: SDL_GPU (SDL3)
│   ├── imgui_impl_allegro5.cpp/h  # Combined: Allegro5
│   └── imgui_impl_null.cpp/h      # Null backend (テスト用)
├── examples/                  # サンプルアプリケーション
│   ├── example_glfw_opengl3/
│   ├── example_sdl2_opengl3/
│   ├── example_win32_directx11/
│   └── ...                    # 各プラットフォーム/レンダラー組み合わせ
├── misc/                      # ユーティリティ
│   ├── cpp/                   # C++標準ライブラリ連携
│   ├── debuggers/             # デバッガサポート (natvis等)
│   ├── fonts/                 # フォント関連ユーティリティ
│   ├── freetype/              # FreeType統合
│   └── single_file/           # 単一ファイルビルド用
└── docs/                      # ドキュメント
```

### コンポーネント依存関係

**主要コンポーネント:**

1. **ImGuiContext** - 中央コンテキスト、全グローバル状態を保持
2. **ImGuiIO** - 入出力設定、マウス/キーボード状態、表示サイズ
3. **ImGuiStyle** - スタイリング設定 (色、サイズ、パディング等)
4. **ImDrawList** - 描画コマンドリスト (頂点・インデックス・描画コマンド)
5. **ImDrawData** - フレームの全描画データ (複数ImDrawListの集合)
6. **ImFontAtlas** - フォントテクスチャアトラス
7. **ImFont** - 個別フォントデータ

**依存関係:**
- `ImGuiContext` は `ImGuiIO`, `ImGuiStyle`, `ImFontAtlas`, 複数の `ImDrawList` を保持
- `ImDrawList` は描画プリミティブを `ImDrawCmd`, `ImDrawVert`, `ImDrawIdx` として蓄積
- `ImDrawData` は複数の `ImDrawList` への参照を保持し、Backendに渡される
- `ImFontAtlas` は複数の `ImFont` と `ImTextureData` を管理

## ミドルウェア構成

### データベース

Dear ImGuiはデータベースを使用しない。全ての状態はインメモリで管理される。

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| RDB | N/A | N/A | N/A |
| NoSQL | N/A | N/A | N/A |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| インメモリ (ImGuiStorage) | 組み込み | ウィジェット状態の一時保存 (展開状態等) | セッション内 |
| フォントアトラスキャッシュ | 組み込み | ベイク済みフォントグリフ | 永続 (明示的再構築まで) |

### メッセージキュー

Dear ImGuiはメッセージキューを使用しない。イベント処理は同期的に行われる。

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| N/A | N/A | N/A |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| N/A | N/A | N/A |

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| stb_truetype | 組み込み (imstb_truetype.h) | TrueTypeフォントのラスタライズ |
| stb_rect_pack | 組み込み (imstb_rectpack.h) | テクスチャアトラスのレクタングルパッキング |
| stb_textedit | 組み込み (imstb_textedit.h) | テキスト編集ウィジェットの内部処理 |
| FreeType | オプション (misc/freetype/) | 高品質フォントラスタライズ (要外部ライブラリ) |

## データフロー

### リクエスト処理の流れ

**フレームループの流れ:**

1. **Platform Backend NewFrame**: `ImGui_ImplXXX_NewFrame()` - 入力イベント収集
2. **Renderer Backend NewFrame**: `ImGui_ImplXXX_NewFrame()` - レンダラー準備
3. **ImGui NewFrame**: `ImGui::NewFrame()` - フレーム開始、状態リセット
4. **UI Definition**: `ImGui::Begin/End()`, `ImGui::Button()` 等 - UIの構築
5. **ImGui Render**: `ImGui::Render()` - 描画データの確定
6. **Get Draw Data**: `ImGui::GetDrawData()` - ImDrawData取得
7. **Renderer Backend Render**: `ImGui_ImplXXX_RenderDrawData()` - GPU描画実行

### 非同期処理の流れ

Dear ImGuiは基本的に同期的なシングルスレッド設計である。非同期処理は行わない。

ただし、以下の点に注意:
1. マルチスレッドでの使用は、コンテキストを分離することで可能
2. 各コンテキストは独立した状態を持つ
3. 同一コンテキストへの同時アクセスはスレッドセーフではない

### データ永続化の流れ

**設定の永続化 (.iniファイル):**

1. `ImGuiIO::IniFilename` にファイルパスを設定
2. ウィンドウの位置・サイズ、展開状態等が自動保存
3. `ImGui::SaveIniSettingsToDisk()` で明示的保存
4. `ImGui::LoadIniSettingsFromDisk()` で読み込み

**永続化されるデータ:**
- ウィンドウの位置とサイズ
- ウィンドウの折りたたみ状態
- テーブルのカラム設定
- カスタム設定 (ImGuiSettingsHandler経由で拡張可能)

## 横断的関心事

### 認証・認可

Dear ImGuiは認証・認可機能を持たない。GUIライブラリであり、セキュリティ機能はホストアプリケーションの責務である。

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| N/A | N/A | N/A |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| デバッグログ | ImGui::ShowDebugLogWindow(), IMGUI_DEBUG_LOG | TTY/デバッグウィンドウ |
| メトリクス | ImGui::ShowMetricsWindow() | リアルタイム表示のみ |
| アサーション | IM_ASSERT マクロ (カスタマイズ可能) | imconfig.hで出力先設定 |

### エラーハンドリング

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| プログラマミス | IM_ASSERT() | アサーション失敗 (デバッグビルド) |
| 状態不整合 | ErrorCheckEndFrameRecover() | 自動リカバリー試行 |
| スタック不整合 | Begin/End ペアチェック | アサーション + 自動修復 |
| メモリ確保失敗 | IM_ALLOC失敗 | NULLポインタ返却 (未処理の可能性) |

### トランザクション管理

Dear ImGuiはトランザクション管理を行わない。UIの状態は即座に反映される。

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| N/A | N/A | N/A |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| Immediate Mode GUI | 全ウィジェット | 毎フレームUIを再構築、状態保持最小化 |
| Zero-cost abstraction回避 | コア実装全般 | 最適化されたデバッグビルド性能のため、過度な抽象化を回避 |
| 最小依存性 | コアライブラリ | 標準Cライブラリのみに依存 (libc) |
| コンパイル時設定 | imconfig.h | #define によるオプション切り替え |
| コンテキスト分離 | ImGuiContext | 複数コンテキストのサポート、DLL境界対応 |

### コーディング規約

**主要規約:**

1. **C++スタイル**: プラグマティックなC寄りのC++、高度なC++機能は使用しない
2. **名前空間**: `ImGui::` 名前空間を使用、メンバ関数は控えめに使用
3. **メモリ管理**: `ImGui::SetAllocatorFunctions()` でカスタムアロケータ設定可能
4. **ベクター型**: `ImVec2`, `ImVec4` は意図的に数学演算子を公開しない (IMGUI_DEFINE_MATH_OPERATORSで有効化可能)
5. **コンテナ**: `ImVector<>` はPOD専用、コンストラクタ/デストラクタ非対応
6. **アサーション**: `IM_ASSERT()` を積極的に使用、カスタマイズ可能
7. **バージョンチェック**: `IMGUI_CHECKVERSION()` でABI互換性検証

## 備考

### 注意事項

1. **DLL使用は非推奨**: 関数呼び出しオーバーヘッドとABI互換性の問題から、静的リンクを推奨
2. **imgui_internal.hの使用**: 内部ヘッダの使用は可能だが、後方互換性は保証されない
3. **マルチビューポート**: dockingブランチでマルチウィンドウ/ドッキングサポート
4. **テストエンジン**: imgui_test_engine による自動テストが利用可能

### バージョン情報

- **ライブラリバージョン**: 1.92.7 WIP
- **バージョン番号 (数値)**: 19262
- **ライセンス**: MIT License
- **開発者**: Omar Cornut およびコントリビューター
