# 機能設計書 90-Atlas レンダリングエンジン

## 概要

本ドキュメントは、Windows Terminal の Atlas レンダリングエンジンについて記述する。Atlas は DirectX ベースの高性能テキストレンダリングエンジンであり、Direct2D（D2D）バックエンドと Direct3D（D3D）バックエンドの2つのレンダリングパスを提供する。

### 本機能の処理概要

**業務上の目的・背景**：ターミナルエミュレータにおいてテキストのレンダリングは最もパフォーマンスクリティカルな処理である。Atlas エンジンは GPU アクセラレーションを活用し、高速かつ高品質なテキストレンダリングを実現する。従来の GDI レンダリングと比較して、大幅なパフォーマンス向上と視覚品質の改善を提供する。

**機能の利用シーン**：ターミナルの表示更新のたびに呼び出される。テキスト入力、スクロール、ウィンドウリサイズなどの操作で画面を再描画する際に使用される。

**主要な処理内容**：
1. IRenderEngine インターフェースの実装（StartPaint / EndPaint / Present / Invalidate 等）
2. Direct2D ファクトリおよび DirectWrite ファクトリの初期化
3. テキストのシェイピングとグリフ配置（DWriteTextAnalysis）
4. グリフアトラスへのキャッシュとテクスチャ管理
5. カーソル、選択範囲、グリッドラインのレンダリング
6. カスタムピクセルシェーダーのサポート（レトロエフェクト等）
7. 部分無効化による効率的な再描画
8. D2D / D3D バックエンドの切り替え

**関連システム・外部連携**：DirectX 11（D3D11, D2D1, DXGI）、DirectWrite、HLSL シェーダー。

**権限による制御**：GPU ハードウェアアクセラレーションが利用可能であること。ソフトウェアレンダリングへのフォールバックも対応。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | TermControl（ターミナル表示） | 主画面 | DirectXベースのテキストレンダリング |
| 25 | Rendering（レンダリング設定） | 参照画面 | Atlasレンダリングエンジン関連の設定 |

## 機能種別

描画処理 / GPU レンダリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| clusters | std::span<const Cluster> | Yes | レンダリングするテキストクラスタ | - |
| coord | til::point | Yes | セル座標 | 0以上のグリッド座標 |
| textAttributes | TextAttribute | Yes | テキスト属性（色、太字、斜体等） | - |
| cursorOptions | CursorOptions | No | カーソルの描画オプション | - |
| selections | std::span<const til::rect> | No | テキスト選択範囲 | - |
| fontInfoDesired | FontInfoDesired | Yes | フォント情報（サイズ、ファミリー等） | - |

### 入力データソース

- TextBuffer（ターミナルバッファ）からのテキストデータとテキスト属性
- RenderSettings からのカラー設定
- FontInfoDesired からのフォント設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| スワップチェーン | IDXGISwapChain | GPU レンダリング結果のフレームバッファ |
| ダーティ領域 | til::rect | 再描画された領域 |

### 出力先

- HWND に関連付けられたスワップチェーン（画面表示）

## 処理フロー

### 処理シーケンス

```
1. StartPaint() - フレームの描画開始
   └─ 設定変更があれば _handleSettingsUpdate() を実行
   └─ 無効化領域のクランプ
2. PrepareRenderInfo() - レンダリング情報の準備
3. PaintBackground() - 背景色の描画
4. PaintBufferLine() (各行に対して) - テキスト行の描画
   └─ _flushBufferLine() でバッファリングされた行をフラッシュ
   └─ _mapRegularText() / _mapBuiltinGlyphs() でグリフマッピング
5. PaintBufferGridLines() - グリッドライン（下線等）の描画
6. PaintSelection() - 選択範囲の描画
7. PaintCursor() - カーソルの描画
8. EndPaint() - フレームの描画終了
9. Present() - スワップチェーンのプレゼント
   └─ Backend::Render() でバックエンド固有のレンダリング
```

### フローチャート

```mermaid
flowchart TD
    A[StartPaint] --> B{設定変更?}
    B -->|Yes| C[_handleSettingsUpdate]
    B -->|No| D[無効化領域クランプ]
    C --> D
    D --> E[PrepareRenderInfo]
    E --> F[PaintBackground]
    F --> G[PaintBufferLine - 各行]
    G --> H[PaintBufferGridLines]
    H --> I[PaintSelection]
    I --> J[PaintCursor]
    J --> K[EndPaint]
    K --> L[Present]
    L --> M[Backend::Render]
    M --> N[SwapChain Present]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-90-01 | 部分無効化 | 変更された行のみ再描画する（_api.invalidatedRows） | 常時 |
| BR-90-02 | バックエンド選択 | D3D バックエンドがデフォルト。ソフトウェアレンダリング時は D2D にフォールバック | 初期化時 |
| BR-90-03 | グリフアトラス | レンダリング済みグリフをテクスチャアトラスにキャッシュし再利用 | テキスト描画時 |
| BR-90-04 | カスタムシェーダー | PixelShaderPath が設定されている場合、カスタム HLSL シェーダーを適用 | レトロエフェクト等の使用時 |
| BR-90-05 | フレームレート制限 | DXGI_SWAP_CHAIN_FLAG_FRAME_LATENCY_WAITABLE_OBJECT でディスプレイリフレッシュレートに同期 | 通常モード |

### 計算ロジック

- セル座標からピクセル座標への変換：pixel = cell * cellSize
- 色の事前乗算アルファ変換：u32ColorPremultiply() / colorFromU32Premultiply()

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| HRESULT | D3D デバイスロスト | GPU ドライバの更新やハードウェアエラー | デバイスの再作成 |
| HRESULT | DXGI エラー | スワップチェーンの作成/プレゼント失敗 | ソフトウェアレンダリングにフォールバック |
| ATLAS_ENGINE_ERROR_MAC_TYPE | macType エラー | Mac Type フォントフック検出時 | 警告コールバック |

### リトライ仕様

D3D デバイスロスト時はデバイスを再作成して描画をリトライ。

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

該当なし。

## パフォーマンス要件

- 60fps 以上のレンダリングパフォーマンスを目標
- 部分無効化による不要な再描画の回避
- グリフアトラスキャッシュによるテキストシェイピングコストの削減
- Present() はバックグラウンドスレッドから呼び出される

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

- カスタムシェーダーはユーザーが指定した HLSL ファイルから読み込まれる。

## 備考

- _api フィールド：IRenderEngine API（Invalidate等）からアクセスされるデータ。スレッドセーフではない
- _r フィールド：Present() メソッドからアクセスされるデータ。API メソッドからのアクセスは禁止
- _p フィールド：両方からアクセス可能な共有データ

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | common.h | `src/renderer/atlas/common.h` | vec2, vec4, rect テンプレート型の定義。ATLAS_FLAG_OPS / ATLAS_POD_OPS マクロ。GraphicsAPI enum の定義 |
| 1-2 | Backend.h | `src/renderer/atlas/Backend.h` | IBackend インターフェース（ReleaseResources / Render / RequiresContinuousRedraw）。各種デバッグフラグ（ATLAS_DEBUG_*）の定義 |

**読解のコツ**: Atlas エンジンは _api / _r / _p の3つのデータドメインを持つ。_api はメインスレッド、_r はレンダリングスレッドからアクセスされ、並行アクセスの同期に注意が必要。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AtlasEngine.h | `src/renderer/atlas/AtlasEngine.h` | AtlasEngine クラス定義（16-100行目）。IRenderEngine の実装と独自の setter/getter |

**主要処理フロー**:
1. **19行目**: コンストラクタ - D2D/DWrite ファクトリの初期化
2. **25-58行目**: IRenderEngine インターフェースの実装メソッド一覧
3. **66-79行目**: Atlas 固有の setter（SetAntialiasingMode / SetPixelShaderPath / SetSoftwareRendering 等）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AtlasEngine.cpp | `src/renderer/atlas/AtlasEngine.cpp` | StartPaint（58行目）→ PaintBufferLine → EndPaint → Present のメインレンダリングループ |
| 3-2 | AtlasEngine.api.cpp | `src/renderer/atlas/AtlasEngine.api.cpp` | Invalidate* メソッド群（46行目以降）。API スレッドからのデータ更新 |

**主要処理フロー**:
- **35-52行目** (AtlasEngine.cpp): コンストラクタで D2D ファクトリ、DWrite ファクトリ、テキストアナライザを初期化
- **58-100行目** (AtlasEngine.cpp): StartPaint() - 設定変更チェック、無効化領域のクランプ
- **46-54行目** (AtlasEngine.api.cpp): Invalidate() - 無効化行の更新

#### Step 4: バックエンド実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | BackendD3D.h | `src/renderer/atlas/BackendD3D.h` | D3D11 バックエンド。VSConstBuffer / PSConstBuffer / CustomConstBuffer の定義。ShadingType enum |
| 4-2 | BackendD2D.h | `src/renderer/atlas/BackendD2D.h` | D2D フォールバックバックエンド |

**主要処理フロー**:
- BackendD3D: GPU シェーダーを使用した高速レンダリング。グリフアトラスのテクスチャ管理
- BackendD2D: ソフトウェアレンダリングフォールバック。Direct2D の描画コマンドを直接使用

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

```
IRenderEngine (インターフェース)
    │
    └─ AtlasEngine (AtlasEngine.h)
           │
           ├─ StartPaint / EndPaint (AtlasEngine.cpp)
           │      └─ _handleSettingsUpdate
           │
           ├─ PaintBufferLine (AtlasEngine.cpp)
           │      ├─ _flushBufferLine
           │      ├─ _mapRegularText → DWriteTextAnalysis
           │      └─ _mapBuiltinGlyphs → BuiltinGlyphs
           │
           ├─ PaintCursor / PaintSelection (AtlasEngine.cpp)
           │
           ├─ Present (AtlasEngine.cpp)
           │      └─ IBackend::Render
           │             ├─ BackendD3D::Render (BackendD3D.cpp)
           │             │      └─ HLSL シェーダー実行
           │             │
           │             └─ BackendD2D::Render (BackendD2D.cpp)
           │                    └─ Direct2D 描画コマンド
           │
           └─ Invalidate* (AtlasEngine.api.cpp)
                  └─ 無効化領域の管理
```

### データフロー図

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

TextBuffer ────────▶ PaintBufferLine               スワップチェーン
(テキストデータ)         │                          (画面表示)
                        ▼
TextAttribute ───▶ UpdateDrawingBrushes
(色・属性)               │
                        ▼
FontInfo ────────▶ DWriteTextAnalysis ──▶ グリフアトラス
(フォント設定)       (テキストシェイピング)   (テクスチャキャッシュ)
                                                │
                                                ▼
                                        Backend::Render
                                          (D3D / D2D)
                                                │
                                                ▼
                                        IDXGISwapChain
                                          ::Present
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AtlasEngine.h | `src/renderer/atlas/AtlasEngine.h` | ヘッダ | AtlasEngine クラス定義 |
| AtlasEngine.cpp | `src/renderer/atlas/AtlasEngine.cpp` | ソース | メインレンダリングループ（StartPaint / Present） |
| AtlasEngine.api.cpp | `src/renderer/atlas/AtlasEngine.api.cpp` | ソース | IRenderEngine API 実装（Invalidate* 等） |
| AtlasEngine.r.cpp | `src/renderer/atlas/AtlasEngine.r.cpp` | ソース | レンダリングスレッド側の処理 |
| common.h | `src/renderer/atlas/common.h` | ヘッダ | 共通型定義（vec2, vec4, rect） |
| Backend.h | `src/renderer/atlas/Backend.h` | ヘッダ | IBackend インターフェースとデバッグフラグ |
| BackendD3D.h | `src/renderer/atlas/BackendD3D.h` | ヘッダ | D3D11 バックエンド定義 |
| BackendD3D.cpp | `src/renderer/atlas/BackendD3D.cpp` | ソース | D3D11 バックエンド実装 |
| BackendD2D.h | `src/renderer/atlas/BackendD2D.h` | ヘッダ | D2D フォールバックバックエンド定義 |
| BackendD2D.cpp | `src/renderer/atlas/BackendD2D.cpp` | ソース | D2D フォールバックバックエンド実装 |
| DWriteTextAnalysis.h | `src/renderer/atlas/DWriteTextAnalysis.h` | ヘッダ | DirectWrite テキスト解析 |
| DWriteTextAnalysis.cpp | `src/renderer/atlas/DWriteTextAnalysis.cpp` | ソース | テキストシェイピング実装 |
| BuiltinGlyphs.h | `src/renderer/atlas/BuiltinGlyphs.h` | ヘッダ | ビルトイングリフ定義 |
| BuiltinGlyphs.cpp | `src/renderer/atlas/BuiltinGlyphs.cpp` | ソース | ビルトイングリフ描画 |
| shader_ps.hlsl | `src/renderer/atlas/shader_ps.hlsl` | シェーダー | ピクセルシェーダー |
| shader_vs.hlsl | `src/renderer/atlas/shader_vs.hlsl` | シェーダー | 頂点シェーダー |
| custom_shader_ps.hlsl | `src/renderer/atlas/custom_shader_ps.hlsl` | シェーダー | カスタムピクセルシェーダーテンプレート |
| shader_common.hlsl | `src/renderer/atlas/shader_common.hlsl` | シェーダー | シェーダー共通定義 |
| dwrite.h | `src/renderer/atlas/dwrite.h` | ヘッダ | DirectWrite ヘルパー |
| dwrite.cpp | `src/renderer/atlas/dwrite.cpp` | ソース | DirectWrite ヘルパー実装 |
| wic.h | `src/renderer/atlas/wic.h` | ヘッダ | WIC（画像処理）ヘルパー |
| wic.cpp | `src/renderer/atlas/wic.cpp` | ソース | WIC ヘルパー実装 |
