# 機能設計書 11-WebGLレンダラー

## 概要

本ドキュメントは、GhosttyのWebGL レンダラー機能の設計について記述する。WebGLレンダラーは、WebAssembly(WASM)向けのブラウザベースレンダリングを提供し、Ghosttyをウェブブラウザ上で動作させるための基盤技術である。

### 本機能の処理概要

**業務上の目的・背景**：
Ghosttyをウェブブラウザ上で動作させることで、プラットフォームに依存しないターミナルエミュレータとしての利用が可能となる。WebGLレンダラーは、ブラウザのWebGL APIを活用してGPUアクセラレーションによる高性能なレンダリングを実現し、デスクトップアプリケーションと同等のユーザーエクスペリエンスを提供することを目的とする。

**機能の利用シーン**：
- ウェブブラウザ経由でのターミナルアクセス
- WebAssemblyを利用したクロスプラットフォームターミナル環境
- ブラウザベースのIDE・開発環境への組み込み
- リモートターミナルサービスのフロントエンド

**主要な処理内容**：
1. WebGL APIを使用したGPUベースのテキストレンダリング
2. フォントアトラスからのグリフテクスチャ取得と描画
3. シェーダープログラムによる文字・背景の描画
4. 端末セルグリッドの効率的な描画バッファ管理
5. カスタムシェーダーサポート（Shadertoyスタイル）

**関連システム・外部連携**：
- ブラウザWebGL API
- WebAssembly(WASM)ランタイム
- フォントアトラス（テクスチャキャッシュ）
- シェーダーシステム

**権限による制御**：
ブラウザのWebGL利用許可が必要。セキュリティコンテキストに応じたアクセス制御が適用される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | WebGLキャンバスへの端末画面レンダリング |

## 機能種別

レンダリング処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| size | u32 | Yes | アトラスサイズ | 2のべき乗 |
| format | Format | Yes | テクスチャフォーマット | grayscale/bgr/bgra |
| cells | CellContents | Yes | レンダリングするセル情報 | 有効なセルデータ |
| uniforms | Uniforms | Yes | シェーダーユニフォーム | 適切な値範囲 |

### 入力データソース

- ターミナル状態（Terminal.RenderState）
- フォントグリッド（font.SharedGrid）
- 設定（DerivedConfig）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Canvas | HTMLCanvasElement | レンダリング結果のCanvas要素 |
| Health | Health | フレームのレンダリング状態 |

### 出力先

ブラウザのWebGLキャンバス（Canvas要素）

## 処理フロー

### 処理シーケンス

```
1. フレーム開始
   └─ スワップチェーンから次のフレームを取得
2. セルデータ準備
   └─ ターミナル状態からレンダリング用セルを構築
3. バッファ更新
   └─ 頂点バッファ・テクスチャを更新
4. レンダリングパス実行
   └─ シェーダーを使用してセルを描画
5. カスタムシェーダー適用（オプション）
   └─ Shadertoyスタイルのポストエフェクト
6. フレーム完了
   └─ スワップチェーンにフレームをリリース
```

### フローチャート

```mermaid
flowchart TD
    A[フレーム開始] --> B[ターミナル状態取得]
    B --> C[セルデータ構築]
    C --> D[バッファ更新]
    D --> E[メインレンダリングパス]
    E --> F{カスタムシェーダー?}
    F -->|Yes| G[カスタムシェーダー適用]
    F -->|No| H[フレーム完了]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | ダブルバッファリング | フレームのちらつきを防ぐためスワップチェーンを使用 | 常時 |
| BR-02 | アトラスキャッシュ | グリフは一度ラスタライズされるとアトラスにキャッシュ | グリフ描画時 |
| BR-03 | 遅延初期化 | WebGLコンテキストはキャンバス表示時に初期化 | 初回描画時 |

### 計算ロジック

テクスチャ座標計算：
- アトラス内のグリフ位置 = (region.x, region.y) / atlas.size
- グリフサイズ = (region.width, region.height) / atlas.size

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

該当なし（レンダリングはメモリ上で完結）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| WebGLError | 初期化エラー | WebGLコンテキスト取得失敗 | フォールバック通知 |
| AtlasFull | リソース不足 | アトラスに空きがない | アトラス拡張 |
| ShaderCompile | コンパイルエラー | シェーダーコンパイル失敗 | エラーログ出力 |

### リトライ仕様

アトラス満杯時は自動的にアトラスサイズを拡張してリトライ

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

該当なし

## パフォーマンス要件

- 60FPS以上のフレームレート維持
- セル数に対して線形的なレンダリング時間
- GPUメモリ効率的な利用（アトラスキャッシュ）

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

- WebGLコンテキストはブラウザのセキュリティポリシーに従う
- クロスオリジンテクスチャ読み込み制限
- シェーダーコードのサニタイズ

## 備考

- WebGLレンダラーはWASMビルド時のみ有効
- デスクトップ版ではMetal（macOS）またはOpenGL（Linux）を使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Atlas.zig | `src/font/Atlas.zig` | グリフテクスチャの管理構造、Region型、Format enum |
| 1-2 | generic.zig | `src/renderer/generic.zig` | SwapChain、FrameState、DerivedConfigの構造 |

**読解のコツ**: Atlas.zigの`Format` enumと`Region` structを先に理解すると、テクスチャ座標の計算ロジックが理解しやすい。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | WebGL.zig | `src/renderer/WebGL.zig` | WebGLレンダラーのメイン実装 |

**主要処理フロー**:
1. **1-3行目**: WebGLレンダラーの構造体定義とimport

#### Step 3: レンダリングパイプラインを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | generic.zig | `src/renderer/generic.zig` | 汎用レンダラーのフレーム処理 |

**主要処理フロー**:
- **81-95行目**: Renderer関数によるGraphicsAPI抽象化
- **239-300行目**: SwapChain構造体のダブルバッファリング実装

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

```
Renderer(WebGL)
    │
    ├─ SwapChain.nextFrame()
    │      └─ FrameState取得
    │
    ├─ rebuildCells()
    │      └─ terminal.RenderStateから変換
    │
    ├─ RenderPass.execute()
    │      └─ シェーダープログラム実行
    │
    └─ SwapChain.releaseFrame()
```

### データフロー図

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

Terminal.RenderState ───▶ rebuildCells() ───▶ CellContents
                                │
                                ▼
font.SharedGrid ─────────▶ グリフ解決 ───────▶ Atlas Region
                                │
                                ▼
CellContents + Atlas ────▶ RenderPass ──────▶ WebGL Canvas
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| WebGL.zig | `src/renderer/WebGL.zig` | ソース | WebGLレンダラー本体 |
| generic.zig | `src/renderer/generic.zig` | ソース | 汎用レンダラー基盤 |
| Atlas.zig | `src/font/Atlas.zig` | ソース | テクスチャアトラス管理 |
| cell.zig | `src/renderer/cell.zig` | ソース | セルレンダリング |
| shadertoy.zig | `src/renderer/shadertoy.zig` | ソース | カスタムシェーダー処理 |
| backend.zig | `src/renderer/backend.zig` | ソース | バックエンド選択 |
