# 機能設計書 85-Renderer

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるレンダリング機能「Renderer」の設計仕様を記述する。IRendererインターフェースは、ビジュアルツリーの描画処理を抽象化し、複数のレンダリングバックエンド（Compositor、ImmediateRenderer等）に対応する統一的なAPIを定義する。

### 本機能の処理概要

Rendererは、Avaloniaのビジュアルツリー（Visual階層）を画面に描画するための責務を担う。ウィンドウやコントロールの視覚的表現を、プラットフォーム固有のグラフィックスAPI（Skia、Direct2D等）を通じて実際のピクセルに変換する。Compositorベースのレンダリングでは、UIスレッドとレンダリングスレッドを分離し、60FPS以上の滑らかなアニメーションを実現する。

**業務上の目的・背景**：GUIアプリケーションにおいて、ユーザーインターフェースの視覚的フィードバックは最も重要な要素である。Rendererは、レイアウト計算結果を視覚化し、ユーザーとアプリケーションの対話を可能にする。また、ダーティ領域の追跡により、不要な再描画を避けて効率的なレンダリングを実現する。

**機能の利用シーン**：ウィンドウの初期表示、コントロールの再描画、アニメーションのフレーム更新、ウィンドウリサイズ時の再レンダリング、ヒットテスト処理で利用される。

**主要な処理内容**：
1. ビジュアルのダーティマーキング（AddDirty）
2. Z順序の再計算（RecalculateChildren）
3. ウィンドウリサイズへの対応（Resized）
4. 描画領域のペイント（Paint）
5. レンダラーの開始・停止（Start/Stop）
6. ヒットテスト処理（HitTest）

**関連システム・外部連携**：RenderLoop、Compositor、IPlatformRenderInterface、Visual、DrawingContextと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 80 | ImmediateRenderer | 主画面 | 即時レンダラーのデモ。シンプルな描画 |

## 機能種別

インターフェース / レンダリングエンジン

## 入力仕様

### 入力パラメータ

**AddDirty**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| visual | Visual | Yes | ダーティマークを付けるビジュアル | - |

**Paint**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| rect | Rect | Yes | 再描画が必要な矩形領域 | - |

**Resized**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| size | Size | Yes | 新しいウィンドウサイズ | - |

### 入力データソース

ウィンドウシステム、レイアウトエンジン、コントロール更新通知

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SceneInvalidated | イベント | シーンの一部が無効化されたときに発火 |
| Diagnostics | RendererDiagnostics | 描画診断情報 |

### 出力先

プラットフォームのウィンドウサーフェス、デバッグ診断出力

## 処理フロー

### 処理シーケンス

```
1. レンダラー開始
   └─ Start()メソッドでレンダリングループに参加
   └─ RenderLoop.Addでタスクを登録

2. ビジュアル更新検知
   └─ AddDirty(visual)で変更を通知
   └─ ダーティビジュアルを内部キューに追加

3. レンダリングフレーム
   └─ RenderLoopからTick通知を受信
   └─ ダーティビジュアルを収集
   └─ シーンを構築/更新
   └─ 描画コマンドを発行

4. 描画実行
   └─ Paint(rect)で指定領域を描画
   └─ DrawingContextを通じてプラットフォームAPIを呼び出し

5. ヒットテスト
   └─ HitTest(point, root, filter)でビジュアルを検索
   └─ Z順序に従ってトップダウンで探索
```

### フローチャート

```mermaid
flowchart TD
    A[Start] --> B[RenderLoop登録]
    B --> C[レンダリングループ]
    C --> D{ダーティビジュアル?}
    D -->|Yes| E[シーン更新]
    D -->|No| C
    E --> F[描画コマンド生成]
    F --> G[Paint実行]
    G --> H[SceneInvalidatedイベント]
    H --> I{ポインタ移動?}
    I -->|Yes| J[HitTest]
    J --> K[ビジュアル特定]
    I -->|No| C
    K --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ダーティ伝播 | 子ビジュアルのダーティは親に伝播する | AddDirty呼び出し時 |
| BR-002 | Z順序ソート | RecalculateChildrenはZ順序に従ってソート | 子の順序変更時 |
| BR-003 | ヒットテスト順序 | ヒットテストはZ順序の逆順（前面から）で実行 | HitTest呼び出し時 |
| BR-004 | フィルタ伝播 | フィルタがfalseを返すと、そのビジュアルと子は除外 | HitTest呼び出し時 |

### 計算ロジック

該当なし（インターフェース定義）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ObjectDisposedException | 破棄後のレンダラーを使用した場合 | レンダラーの状態を確認 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- フレームレートは最低60FPSを維持
- ダーティ領域のみを再描画（インクリメンタルレンダリング）
- UIスレッドとレンダリングスレッドの分離（Compositorベース）

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

特になし

## 備考

IRendererインターフェースはPrivateApiとしてマークされており、内部使用専用。IRendererWithCompositorはCompositorプロパティを追加で公開する。

---

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

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

### 推奨読解順序

#### Step 1: インターフェース定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | インターフェース定義（9-67行目） |
| 1-2 | IHitTester.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | ヒットテストインターフェース（78-102行目） |
| 1-3 | IRendererWithCompositor.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | Compositor対応インターフェース（69-75行目） |

**読解のコツ**: IRendererは[PrivateApi]属性でマークされており、internal宣言。アプリケーションコードからは直接使用しない設計。

#### Step 2: 主要メソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | Diagnosticsプロパティ（18行目）: 診断情報 |
| 2-2 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | SceneInvalidatedイベント（27行目）: シーン無効化通知 |
| 2-3 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | AddDirty（33行目）: ダーティマーキング |
| 2-4 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | RecalculateChildren（39行目）: Z順序再計算 |
| 2-5 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | Resized（45行目）: リサイズ通知 |
| 2-6 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | Paint（51行目）: 描画実行 |
| 2-7 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | Start/Stop（56-61行目）: レンダラー制御 |

#### Step 3: ヒットテストを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | IHitTester.HitTest（94行目）: 複数ビジュアル取得 |
| 3-2 | IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | IHitTester.HitTestFirst（101行目）: 最前面ビジュアル取得 |

**注意点**: ヒットテストはIsHitTestVisibleを尊重しない低レベルAPI。InputExtensionsを使用すべき。

#### Step 4: 具体的な実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ImmediateRenderer.cs | `src/Avalonia.Base/Rendering/ImmediateRenderer.cs` | 即時レンダラー実装（シンプルな同期描画） |

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

```
IRenderer (インターフェース)
    │
    ├─ IRendererWithCompositor
    │      └─ Compositor (プロパティ)
    │
    ├─ IHitTester
    │      ├─ HitTest(Point, Visual, Func<Visual,bool>?)
    │      └─ HitTestFirst(Point, Visual, Func<Visual,bool>?)
    │
    └─ メソッド定義
           ├─ AddDirty(Visual)
           ├─ RecalculateChildren(Visual)
           ├─ Resized(Size)
           ├─ Paint(Rect)
           ├─ Start()
           ├─ Stop()
           └─ TryGetRenderInterfaceFeature(Type)
```

### データフロー図

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

ビジュアル変更 ──────────▶ AddDirty ────────────────────▶ ダーティリスト
                              │
リサイズ通知 ────────────▶ Resized ─────────────────────▶ サイズ更新
                              │
タイマーTick ────────────▶ Paint ──────────────────────▶ 描画出力
                              │                          (サーフェス)
                              ▼
                        SceneInvalidated ──────────────▶ イベント通知
                              │
ポインタ位置 ────────────▶ HitTest ─────────────────────▶ ビジュアルリスト
                        (IHitTester)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| IRenderer.cs | `src/Avalonia.Base/Rendering/IRenderer.cs` | ソース | メインインターフェース定義 |
| ImmediateRenderer.cs | `src/Avalonia.Base/Rendering/ImmediateRenderer.cs` | ソース | 即時レンダラー実装 |
| RendererDiagnostics.cs | `src/Avalonia.Base/Rendering/RendererDiagnostics.cs` | ソース | 診断情報クラス |
| SceneInvalidatedEventArgs.cs | `src/Avalonia.Base/Rendering/SceneInvalidatedEventArgs.cs` | ソース | イベント引数 |
| IRenderLoop.cs | `src/Avalonia.Base/Rendering/IRenderLoop.cs` | ソース | レンダーループインターフェース |
| IRenderLoopTask.cs | `src/Avalonia.Base/Rendering/IRenderLoopTask.cs` | ソース | レンダーループタスク |
| Visual.cs | `src/Avalonia.Base/Visual.cs` | ソース | ビジュアル基底クラス |
