# 機能設計書 221-GetMainViewport

## 概要

本ドキュメントは、Dear ImGuiライブラリにおける`GetMainViewport`関数の機能設計書である。この関数は、アプリケーションのメインビューポート（プラットフォームウィンドウ）の情報を取得するためのユーティリティ関数である。

### 本機能の処理概要

`GetMainViewport`関数は、Dear ImGuiが描画を行う主要な表示領域（ビューポート）の情報を取得する機能を提供する。ビューポートはプラットフォームウィンドウを表現する構造体であり、位置、サイズ、フレームバッファスケール等の情報を含む。

**業務上の目的・背景**：GUIアプリケーション開発において、ウィンドウの配置やサイズ計算を正確に行うためには、描画対象となるビューポートの情報が不可欠である。特にフルスクリーンウィンドウの作成、ウィンドウの中央配置、オーバーレイ表示などの実装で、ビューポートの座標とサイズを基準にした計算が必要となる。本機能は、これらの要件を満たすための基盤となる情報取得手段を提供する。

**機能の利用シーン**：
- フルスクリーンウィンドウを作成する際の位置・サイズ設定
- ダイアログやポップアップウィンドウを画面中央に配置する計算
- オーバーレイウィンドウを画面の四隅に配置する座標計算
- メニューバーやタスクバーを除いたワークエリアの取得
- Retinaディスプレイ等の高DPI環境でのフレームバッファスケール確認

**主要な処理内容**：
1. 現在のImGuiコンテキストを取得
2. コンテキスト内のViewports配列から先頭のビューポート（メインビューポート）を返却
3. 呼び出し元にImGuiViewport構造体へのポインタを返す

**関連システム・外部連携**：プラットフォームバックエンド（Win32、GLFW、SDL等）がビューポートの初期化と更新を担当する。ビューポートの位置・サイズ情報は、バックエンドがOSから取得したウィンドウ情報に基づいて設定される。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | Fullscreen Window | 主画面 | フルスクリーンウィンドウのサイズ・位置取得 |
| 17 | Simple Overlay | 主画面 | オーバーレイ位置の計算基準 |

## 機能種別

データ取得（読み取り専用）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| なし | - | - | パラメータなし | - |

### 入力データソース

ImGuiコンテキスト（GImGui）内のViewports配列

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 戻り値 | ImGuiViewport* | メインビューポートへのポインタ。常に有効な値が返される（NULLにはならない） |

### ImGuiViewport構造体の主要メンバー

| メンバー名 | 型 | 説明 |
|-----------|-----|------|
| ID | ImGuiID | ビューポートの一意識別子 |
| Flags | ImGuiViewportFlags | ビューポートフラグ |
| Pos | ImVec2 | メインエリアの位置（スクリーン座標） |
| Size | ImVec2 | メインエリアのサイズ |
| FramebufferScale | ImVec2 | Retinaディスプレイ用のスケール値 |
| WorkPos | ImVec2 | ワークエリアの位置（メニューバー等を除く） |
| WorkSize | ImVec2 | ワークエリアのサイズ |
| PlatformHandle | void* | プラットフォーム固有のウィンドウハンドル |

### 出力先

呼び出し元への戻り値として返却

## 処理フロー

### 処理シーケンス

```
1. 現在のImGuiコンテキストを取得
   └─ グローバル変数GImGuiを参照
2. Viewports配列の先頭要素を返却
   └─ g.Viewports[0]がメインビューポート
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ImGuiコンテキスト取得]
    B --> C[Viewports配列の先頭要素を取得]
    C --> D[ImGuiViewport*を返却]
    D --> E[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | メインビューポートの一意性 | メインビューポートは常にViewports[0]に存在する | 常時 |
| BR-002 | NULL返却不可 | この関数はNULLを返すことがない | 常時 |

### 計算ロジック

特になし

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

なし

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

該当なし

## パフォーマンス要件

- O(1)の時間計算量
- メモリアロケーションなし
- インライン展開に適した軽量関数

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

特になし

## 備考

- dockingブランチでは、マルチビューポートが有効な場合に複数のビューポートが存在する可能性があるが、本関数は常にメインビューポートを返す
- 将来的にはプラットフォームモニターの表現にも拡張される可能性がある
- `io.DisplaySize`は`GetMainViewport()->Size`と同等の値を持つ

---

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

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

### 推奨読解順序

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

まず、ビューポートを表現するImGuiViewport構造体を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui.h | `imgui.h` | ImGuiViewport構造体の定義（3933-3951行目） |

**読解のコツ**: ImGuiViewportはビューポートの位置・サイズ・スケール情報を保持する。特にPos/Size（メインエリア）とWorkPos/WorkSize（ワークエリア）の違いに注目。ワークエリアはメニューバーやタスクバーを除いた領域を表す。

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

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

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

**主要処理フロー**:
1. **15687行目**: `ImGuiContext& g = *GImGui;` - 現在のImGuiコンテキストを取得
2. **15688行目**: `return g.Viewports[0];` - メインビューポートを返却

#### Step 3: ビューポート初期化処理を理解する

ビューポートがどのように初期化されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui.cpp | `imgui.cpp` | CreateContext関数内でのビューポート初期化 |
| 3-2 | imgui_internal.h | `imgui_internal.h` | ImGuiViewportPの内部構造 |

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

```
ImGui::GetMainViewport()
    │
    └─ GImGui (グローバルコンテキスト)
           │
           └─ Viewports[0] (メインビューポート)
```

### データフロー図

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

なし     ───▶ GImGui->Viewports[0]取得 ───▶ ImGuiViewport*
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui.h | `imgui.h` | ヘッダー | ImGuiViewport構造体定義、API宣言 |
| imgui.cpp | `imgui.cpp` | ソース | GetMainViewport関数実装 |
| imgui_internal.h | `imgui_internal.h` | 内部ヘッダー | ImGuiViewportP（内部拡張）定義 |
| imgui_demo.cpp | `imgui_demo.cpp` | デモ | 使用例（409行目、5437行目、9788行目等） |
