# 機能設計書 10-OpenGLレンダラー

## 概要

本ドキュメントは、GhosttyターミナルエミュレータにおけるLinux向けのOpenGLを使用したGPUレンダリング「OpenGLレンダラー」機能の設計を記述する。

### 本機能の処理概要

OpenGLレンダラーは、OpenGL 4.3以降を使用して端末画面をGPU描画する。GTKアプリケーションとの統合、sRGBフレームバッファによる正確な色再現、カスタムシェーダーサポートを提供する。Metalと異なりシングルバッファリングで動作し、OpenGLの同期的なフレーム完了を活用する。

**業務上の目的・背景**：Linux環境において高性能なGPUレンダリングを実現するために、広くサポートされているOpenGLを使用する。OpenGL 4.3以降の機能を活用することで、効率的なテキストレンダリングとカスタムシェーダーによる視覚効果が可能となる。

**機能の利用シーン**：
- Linux/GTK環境での端末表示
- 大量のテキスト出力を高速に表示する場面
- カスタムシェーダーで視覚効果を適用する場面

**主要な処理内容**：
1. OpenGLコンテキストの初期化とバージョン確認
2. GLADによる関数ポインタロード
3. シェーダーのコンパイルとパイプライン構築
4. セルグリッドの効率的な描画
5. sRGBフレームバッファによるリニアアルファブレンディング
6. フレームバッファオブジェクト（FBO）へのオフスクリーンレンダリング

**関連システム・外部連携**：
- GTK/GLib
- OpenGL 4.3+
- GLSL シェーダー
- カスタムシェーダー（Shadertoy形式）

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | Linux向けOpenGLを使用したGPUレンダリング |

## 機能種別

レンダリング / GPU処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| config | Config | Yes | レンダリング設定 | - |

### 入力データソース

- Terminal/Screen構造体からのセルデータ
- フォントアトラスからのグリフテクスチャ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| rendered_frame | Framebuffer | 描画されたフレーム |

### 出力先

- GTKウィンドウ

## 処理フロー

### 処理シーケンス

```
1. OpenGL初期化
   └─ GLADで関数ポインタロード
   └─ バージョン確認（4.3以上）
   └─ デバッグ出力有効化
   └─ sRGBフレームバッファ有効化

2. シェーダー初期化
   └─ initShaders()でGLSLコンパイル
   └─ プログラムリンク

3. フレーム描画
   └─ FBOへレンダリング
   └─ デフォルトフレームバッファにblit
   └─ present()でスワップ

4. リソース管理
   └─ バッファ/テクスチャの作成
   └─ sRGBAまたはRGBA内部フォーマット
```

### フローチャート

```mermaid
flowchart TD
    A[OpenGL.init] --> B[GLADロード]
    B --> C{バージョン >= 4.3?}
    C -->|Yes| D[デバッグ出力有効化]
    C -->|No| E[エラー: バージョン不足]
    D --> F[sRGBフレームバッファ有効化]

    G[drawFrame] --> H[FBOへレンダリング]
    H --> I[デフォルトFBへblit]
    I --> J[present]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | シングルバッファ | swap_chain_count=1で同期描画 | 常時 |
| BR-002 | 最小バージョン | OpenGL 4.3以上を要求 | 初期化時 |
| BR-003 | sRGBフレームバッファ | GL_FRAMEBUFFER_SRGBを有効化 | リニアブレンディング時 |
| BR-004 | GTKメインスレッド | GTKはスレッドセーフでないためメインスレッドで描画 | GTK環境時 |

### 計算ロジック

- ビューポートサイズ: glGetIntegerv(GL_VIEWPORT)から取得

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| E-001 | バージョン不足 | OpenGL 4.3未満 | エラーログ出力、終了 |
| E-002 | シェーダーコンパイル失敗 | 不正なシェーダーコード | エラーログ出力 |

### リトライ仕様

リトライ機構は使用しない。

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

トランザクション処理は使用しない。

## パフォーマンス要件

- フレームレート: 60fps以上
- 同期描画のためvsyncに依存

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

特になし。

## 備考

- GTKはスレッドセーフでないため、レンダリングはメインスレッドで実行

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | OpenGL.zig | `src/renderer/OpenGL.zig` | OpenGL構造体、フィールド定義 |
| 1-2 | opengl/Target.zig | `src/renderer/opengl/Target.zig` | レンダーターゲット（FBO） |

**読解のコツ**: `OpenGL`構造体はalloc、blending、last_targetを持つ。Metalと比較してシンプルな構造。

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | OpenGL.zig | `src/renderer/OpenGL.zig` | init()関数 |
| 2-2 | OpenGL.zig | `src/renderer/OpenGL.zig` | prepareContext()関数 |
| 2-3 | OpenGL.zig | `src/renderer/OpenGL.zig` | surfaceInit()関数 |

**主要処理フロー**:
- **51-56行目**: `init()` - allocとblending設定
- **133-159行目**: `prepareContext()` - GLADロード、バージョン確認、デバッグ/sRGB有効化
- **162-178行目**: `surfaceInit()` - サーフェス初期化

#### Step 3: 描画処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | OpenGL.zig | `src/renderer/OpenGL.zig` | drawFrameStart/End |
| 3-2 | OpenGL.zig | `src/renderer/OpenGL.zig` | present()関数 |

**主要処理フロー**:
- **255-257行目**: `drawFrameStart()` - 何もしない（Metalと違いAutoreleasePool不要）
- **262-264行目**: `drawFrameEnd()` - 何もしない
- **298-300行目以降**: `present()` - FBOをデフォルトFBにblit

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

```
OpenGL
    |
    +-- init()
    |      +-- alloc/blending設定
    |
    +-- surfaceInit()
    |      +-- prepareContext()
    |             +-- gl.glad.load()
    |             +-- バージョン確認
    |             +-- GL_DEBUG_OUTPUT有効化
    |             +-- GL_FRAMEBUFFER_SRGB有効化
    |
    +-- initShaders()
    |      +-- shaders.Shaders.init()
    |
    +-- initTarget()
    |      +-- Target.init()
    |
    +-- present()
           +-- glBlitFramebuffer()
```

### データフロー図

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

セルデータ ──────────> Buffer更新
                           |
                           v
フォントアトラス ─────> RenderPass (FBO)
                           |
                           v
                    glBlitFramebuffer ───> デフォルトFB
                           |
                           v
                    GTKウィンドウ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| OpenGL.zig | `src/renderer/OpenGL.zig` | ソース | OpenGLレンダラーのメインロジック |
| opengl/Target.zig | `src/renderer/opengl/Target.zig` | ソース | フレームバッファオブジェクト |
| opengl/Frame.zig | `src/renderer/opengl/Frame.zig` | ソース | フレーム管理 |
| opengl/Pipeline.zig | `src/renderer/opengl/Pipeline.zig` | ソース | シェーダープログラム |
| opengl/shaders.zig | `src/renderer/opengl/shaders.zig` | ソース | シェーダー管理 |
| opengl/buffer.zig | `src/renderer/opengl/buffer.zig` | ソース | バッファ管理 |
| opengl/Texture.zig | `src/renderer/opengl/Texture.zig` | ソース | テクスチャ管理 |
