# 機能設計書 87-Compositor

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるコンポジション管理機能「Compositor」の設計仕様を記述する。Compositorクラスは、UIスレッドとレンダリングスレッド間の通信を管理し、GPUアクセラレーション描画を含む高度なコンポジション処理を実現する。

### 本機能の処理概要

Compositorは、Avaloniaの最新レンダリングアーキテクチャの中核を担うクラスである。UIスレッドで作成されたCompositionObject（ビジュアル、ブラシ、アニメーション等）の変更を収集し、バッチとしてレンダリングスレッド（ServerCompositor）に送信する。これにより、UIスレッドの応答性を維持しながら、滑らかな60FPS以上の描画を実現する。

**業務上の目的・背景**：現代のGUIアプリケーションでは、複雑なアニメーションやエフェクトを滑らかに表示する必要がある。Compositorは、変更の差分を効率的にシリアライズし、レンダリングスレッドに非同期で送信することで、UIスレッドのブロックを最小化する。GPUアクセラレーションとの統合により、ハードウェア支援の高性能描画が可能となる。

**機能の利用シーン**：ウィンドウの描画、アニメーションの実行、ビジュアルエフェクトの適用、GPUリソースの管理で利用される。

**主要な処理内容**：
1. CompositionObjectの変更追跡とシリアライズ
2. バッチのコミットとレンダリングスレッドへの送信
3. ServerCompositorとの通信管理
4. CompositionVisualやアニメーションの作成
5. GPU機能の問い合わせ（TryGetRenderInterfaceFeature）
6. GPU相互運用（TryGetCompositionGpuInterop）

**関連システム・外部連携**：RenderLoop、ServerCompositor、CompositionObject、IPlatformGraphics、MediaContextと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面 | 補助機能 | コンポジションエンジン |

## 機能種別

サービス / ファクトリ / 通信管理

## 入力仕様

### 入力パラメータ

**コンストラクタ**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| gpu | IPlatformGraphics? | No | GPUバックエンド | nullでソフトウェアレンダリング |
| useUiThreadForSynchronousCommits | bool | No | 同期コミットにUIスレッドを使用 | デフォルトfalse |

**RequestCompositionUpdate**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| action | Action | Yes | コミット前に実行するコールバック | - |

### 入力データソース

CompositionObjectからの変更通知、MediaContextからのスケジュール要求

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| CompositionBatch | CompositionBatch | コミットされたバッチ情報 |

### 出力先

ServerCompositor（レンダリングスレッド）

## 処理フロー

### 処理シーケンス

```
1. Compositor初期化
   └─ コンストラクタでRenderLoop、GPU、Dispatcherを設定
   └─ ServerCompositorを作成
   └─ BatchStreamPoolを初期化

2. CompositionObjectの変更
   └─ RegisterForSerializationで変更を登録
   └─ _objectSerializationQueueに追加
   └─ RequestCommitAsyncを呼び出し

3. コミット要求
   └─ RequestCommitAsync/_triggerCommitRequestedを通じてスケジュール
   └─ _nextCommitバッチを作成
   └─ 前のバッチ完了後に実行

4. コミット実行
   └─ Commitメソッドでバッチを構築
   └─ _invokeBeforeCommitのコールバックを実行
   └─ BatchStreamWriterで変更をシリアライズ
   └─ ServerCompositor.EnqueueBatchで送信

5. バッチ処理完了
   └─ CompositionBatch.Processedタスクが完了
   └─ AfterCommitイベントを発火
```

### フローチャート

```mermaid
flowchart TD
    A[CompositionObject変更] --> B[RegisterForSerialization]
    B --> C[RequestCommitAsync]
    C --> D{前のバッチ処理中?}
    D -->|Yes| E[完了待ち]
    D -->|No| F[_triggerCommitRequested]
    E --> F
    F --> G[Commit]
    G --> H[_invokeBeforeCommit実行]
    H --> I[BatchStreamWriter作成]
    I --> J[変更シリアライズ]
    J --> K[ServerCompositor.EnqueueBatch]
    K --> L[CompositionBatch返却]
    L --> M[AfterCommit発火]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | UIスレッド検証 | コミット操作はUIスレッドからのみ実行可能 | Commit呼び出し時 |
| BR-002 | 順序保証 | バッチは順序通りに処理される | 複数コミット時 |
| BR-003 | 遅延コミット | RequestCompositionUpdateは次のコミット前に実行 | レイアウト後の更新 |
| BR-004 | Dispose管理 | DisposeOnNextBatchで次のバッチでオブジェクトを破棄 | CompositionObject破棄時 |

### 計算ロジック

該当なし

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | CreateCompositionVisualSnapshotで異なるCompositorのビジュアルを使用 | 同じCompositorを使用 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- バッチストリームのメモリプール再利用
- NonPumpingLockHelperでメッセージポンプを停止しないロック
- 変更の差分のみをシリアライズ

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

特になし

## 備考

TryGetDefaultCompositor()で、プラットフォームのデフォルトCompositorを取得できる。ただし、すべてのプラットフォームで利用可能とは限らない。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Compositor.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.cs` | フィールド定義（25-41行目）: _server, _nextCommit, _batchObjectPool等 |
| 1-2 | CompositionBatch.cs | `src/Avalonia.Base/Rendering/Composition/CompositionBatch.cs` | バッチクラス定義 |
| 1-3 | BatchStream.cs | `src/Avalonia.Base/Rendering/Composition/Transport/BatchStream.cs` | シリアライズストリーム |

**読解のコツ**: CompositorはUIスレッド側、ServerCompositorはレンダリングスレッド側の対になるクラス。

#### Step 2: コンストラクタを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Compositor.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.cs` | 公開コンストラクタ（70-73行目） |
| 2-2 | Compositor.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.cs` | 内部コンストラクタ（80-95行目） |

**主要処理フロー**:
1. **86-87行目**: RenderLoopとDispatcherを設定
2. **89-90行目**: BatchStreamPoolを作成
3. **91行目**: ServerCompositorを作成
4. **92行目**: CommitRequestedコールバックを設定
5. **94行目**: DefaultEasingを初期化

#### Step 3: コミット要求を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Compositor.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.cs` | RequestCommitAsync（101行目） |
| 3-2 | Compositor.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.cs` | RequestCompositionBatchCommitAsync（107-124行目） |

**主要処理フロー**:
- **109行目**: UIスレッドを検証
- **112-121行目**: 前のバッチの完了を待ってからコミットをスケジュール

#### Step 4: コミット処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Compositor.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.cs` | Commit（126-138行目）: コミットエントリポイント |
| 4-2 | Compositor.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.cs` | CommitCore（140-214行目）: コア処理 |

**主要処理フロー**:
- **147-149行目**: _invokeBeforeCommitコールバックを実行
- **151-166行目**: BatchStreamWriterで変更をシリアライズ
- **168-175行目**: Disposeオブジェクトを処理
- **196-197行目**: ServerCompositor.EnqueueBatchで送信

#### Step 5: ファクトリメソッドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Compositor.Factories.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.Factories.cs` | CreateXXXメソッド群 |

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

```
Compositor
    │
    ├─ Constructor
    │      ├─ BatchStreamMemoryPool
    │      ├─ BatchStreamObjectPool
    │      └─ ServerCompositor
    │
    ├─ RequestCommitAsync
    │      └─ RequestCompositionBatchCommitAsync
    │             └─ _triggerCommitRequested (MediaContext.CommitRequested)
    │
    ├─ Commit
    │      └─ CommitCore
    │             ├─ _invokeBeforeCommit ループ
    │             ├─ BatchStreamWriter
    │             ├─ ICompositorSerializable.SerializeChanges
    │             └─ ServerCompositor.EnqueueBatch
    │
    ├─ RegisterForSerialization
    │      └─ _objectSerializationQueue/HashSet
    │
    ├─ CreateXXX (ファクトリ)
    │      ├─ CreateContainerVisual
    │      ├─ CreateSolidColorVisual
    │      ├─ CreateCustomVisual
    │      └─ CreateImplicitAnimation
    │
    └─ TryGetRenderInterfaceFeature
           └─ GetRenderInterfacePublicFeatures
                  └─ Server.RT_GetRenderInterfaceFeatures
```

### データフロー図

```
[UIスレッド]                              [レンダリングスレッド]

CompositionObject変更
        │
        ▼
RegisterForSerialization
        │
        ▼
_objectSerializationQueue ──────────▶ BatchStreamWriter
        │                                    │
        ▼                                    ▼
RequestCommitAsync                    CompositionBatch
        │                                    │
        ▼                                    ▼
Commit ─────────────────────────────▶ ServerCompositor
        │                             EnqueueBatch
        ▼                                    │
AfterCommit ◀──────────────────────── Processed (完了通知)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Compositor.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.cs` | ソース | メインクラス（UIスレッド側） |
| Compositor.Factories.cs | `src/Avalonia.Base/Rendering/Composition/Compositor.Factories.cs` | ソース | ファクトリメソッド |
| ServerCompositor.cs | `src/Avalonia.Base/Rendering/Composition/Server/ServerCompositor.cs` | ソース | レンダリングスレッド側 |
| CompositionBatch.cs | `src/Avalonia.Base/Rendering/Composition/CompositionBatch.cs` | ソース | バッチ情報 |
| BatchStream.cs | `src/Avalonia.Base/Rendering/Composition/Transport/BatchStream.cs` | ソース | シリアライズストリーム |
| CompositionObject.cs | `src/Avalonia.Base/Rendering/Composition/CompositionObject.cs` | ソース | 基底オブジェクト |
| CompositionVisual.cs | `src/Avalonia.Base/Rendering/Composition/CompositionVisual.cs` | ソース | コンポジションビジュアル |
| CompositionTarget.cs | `src/Avalonia.Base/Rendering/Composition/CompositionTarget.cs` | ソース | レンダーターゲット |
| CompositionOptions.cs | `src/Avalonia.Base/Rendering/Composition/CompositionOptions.cs` | ソース | オプション設定 |
