# 画面設計書 4-Composition

## 概要

本ドキュメントは、ControlCatalogアプリケーションのCompositionページ（CompositionPage）の画面設計を定義します。

### 本画面の処理概要

このCompositionページは、Avalonia UIのCompositionアニメーション機能をデモンストレーションするページです。暗黙的アニメーション（ImplicitAnimations）、キーフレームベースのアニメーション、およびカスタムビジュアル描画の3つのタブで構成されています。

**業務上の目的・背景**：本画面は、Avalonia UIフレームワークのCompositionレイヤーを使用したGPUアクセラレーション描画とアニメーションの実装方法を示すデモです。CompositorAPIを使用することで、UIスレッドをブロックせずにスムーズなアニメーションを実現できます。開発者がハイパフォーマンスなアニメーションを実装する際の参考となります。

**画面へのアクセス方法**：MainViewのHamburgerMenuから「Composition」タブを選択してアクセスします。MainView.xamlの19-21行目で定義されています。

**主要な操作・処理内容**：
1. Implicit animationsタブ：色付きボーダーのグリッドをリサイズすると、各要素が滑らかにアニメーションして再配置
2. Animationタブ：色が変化し、スケールがアニメーションするSolidColorVisualを表示。Thread.Sleep(10000)ボタンでUIスレッドブロックテスト
3. Customタブ：楕円がアニメーションするカスタムビジュアルを表示。Start/Stopボタンでアニメーション制御、Precise dirty rectsオプションで描画最適化

**画面遷移**：
- 遷移元：MainView（HamburgerMenu）
- 遷移先：なし（コンテンツページ）

**権限による表示制御**：本アプリケーションはデモ用のため、特別な権限制御は実装されていません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 87 | Compositor | 主機能 | Compositionアニメーションのデモ。GPUアクセラレーション描画 |
| 68 | Animation | 補助機能 | キーフレームベースのアニメーション表示 |

## 画面種別

デモページ / サンプル

## URL/ルーティング

デスクトップアプリケーションのため、URLルーティングは該当なし。HamburgerMenuのTabItemとしてアクセス。

## 入出力項目

| 項目名 | 入力/出力 | データ型 | 説明 | バインディング |
|--------|----------|----------|------|---------------|
| PreciseDirtyRectsCheckbox | 入力 | bool | 精密なダーティレクト更新を使用するか | IsCheckedChanged |
| Items | 出力 | List<CompositionPageColorItem> | 色付きアイテムリスト | ItemsSource |

## 表示項目

| 項目名 | 表示位置 | データ型 | 説明 |
|--------|----------|----------|------|
| TabControl | メイン | TabControl | 3タブ構成 |
| ItemsControl | Implicit animationsタブ | ItemsControl | 色付きボーダーグリッド |
| GridSplitter | Implicit animationsタブ | GridSplitter | リサイズ用スプリッター |
| SolidVisualHost | Animationタブ | Control | SolidColorVisualのホスト |
| CustomVisualHost | Customタブ | Control | カスタムビジュアルのホスト |

## イベント仕様

### 1-ButtonThreadSleep

**トリガー**: Thread.Sleep(10000)ボタンクリック

**処理内容**:
1. Thread.Sleep(10000)を呼び出しUIスレッドを10秒間ブロック
2. Compositionアニメーションはブロックされずに継続することをデモ

**コード参照**: CompositionPage.axaml.cs 316-319行目

### 2-ButtonStartCustomVisual

**トリガー**: Startボタンクリック（Customタブ）

**処理内容**:
1. CustomVisualHandler.StartMessageを送信
2. カスタムビジュアルのアニメーションを開始

**コード参照**: CompositionPage.axaml.cs 321-324行目

### 3-ButtonStopCustomVisual

**トリガー**: Stopボタンクリック（Customタブ）

**処理内容**:
1. CustomVisualHandler.StopMessageを送信
2. カスタムビジュアルのアニメーションを停止

**コード参照**: CompositionPage.axaml.cs 326-329行目

### 4-PreciseDirtyRectsCheckboxCustomVisualChanged

**トリガー**: Precise dirty rectsチェックボックス変更

**処理内容**:
1. チェック状態に応じてUsePreciseDirtyRectsまたはUseNonPreciseDirtyRectsメッセージを送信
2. 描画更新領域の最適化方式を切り替え

**コード参照**: CompositionPage.axaml.cs 331-336行目

### 5-SetEnableAnimations（添付プロパティ）

**トリガー**: EnableAnimations添付プロパティがtrueに設定されたとき

**処理内容**:
1. ImplicitAnimationCollectionを作成・設定
2. Offset変更時のアニメーションを適用

**コード参照**: CompositionPage.axaml.cs 119-137行目

## データベース更新仕様

### 操作別データベース影響一覧

本画面はデータベースを使用しません。

## メッセージ仕様

| メッセージID | 種別 | 内容 | 表示条件 |
|-------------|------|------|----------|
| N/A | - | - | - |

本画面では特別なメッセージ表示は行われません。

## 例外処理

| 例外種別 | 発生条件 | 対処 |
|----------|----------|------|
| - | - | - |

本画面では特別な例外処理は実装されていません。

## 備考

- 48種類のカラーアイテムがImplicit animationsタブに表示
- SolidColorVisualは色（赤→青→緑）とスケールの2つのアニメーションを同時実行
- カスタムビジュアルは20個の楕円が波形パターンでアニメーション
- Precise dirty rectsオプションは描画パフォーマンス最適化のデモ
- Thread.Sleep()はCompositionアニメーションがUIスレッドとは独立していることを示す

---

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

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

### 推奨読解順序

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

まず、色情報を保持するデータクラスを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | CompositionPage.axaml.cs | `samples/ControlCatalog/Pages/CompositionPage.axaml.cs` | CompositionPageColorItemクラス（339-357行目） |

**読解のコツ**: CompositionPageColorItemはColor、ColorBrush、ColorHexValueの3プロパティを持つシンプルなデータクラスです。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | CompositionPage.axaml | `samples/ControlCatalog/Pages/CompositionPage.axaml` | TabControlの3タブ構造 |
| 2-2 | CompositionPage.axaml.cs | `samples/ControlCatalog/Pages/CompositionPage.axaml.cs` | コンストラクタとOnAttachedToVisualTree |

**主要処理フロー**:
1. **24-29行目（C#）**: コンストラクタでビジュアルホストにアニメーション設定
2. **31-35行目（C#）**: OnAttachedToVisualTreeでカラーアイテムを設定
3. **37-91行目（C#）**: CreateColorItemsで48色のリストを生成

#### Step 3: Compositionアニメーションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | CompositionPage.axaml.cs | `samples/ControlCatalog/Pages/CompositionPage.axaml.cs` | EnsureImplicitAnimations（93-117行目） |
| 3-2 | CompositionPage.axaml.cs | `samples/ControlCatalog/Pages/CompositionPage.axaml.cs` | AttachAnimatedSolidVisual（139-187行目） |
| 3-3 | CompositionPage.axaml.cs | `samples/ControlCatalog/Pages/CompositionPage.axaml.cs` | AttachCustomVisual（189-216行目） |

**主要処理フロー**:
- **93-117行目**: ImplicitAnimationCollectionの作成（オフセットと回転のアニメーション）
- **139-187行目**: SolidColorVisualの色とスケールアニメーション
- **218-314行目**: CustomVisualHandlerクラス（楕円アニメーション描画）

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

```
CompositionPage（コンストラクタ）
    │
    ├─ InitializeComponent()
    │
    ├─ AttachAnimatedSolidVisual(SolidVisualHost)
    │      └─ CompositionSolidColorVisual作成
    │             ├─ Color KeyFrameAnimation（Red→Blue→Green）
    │             ├─ Scale KeyFrameAnimation
    │             └─ CenterPoint ExpressionAnimation
    │
    └─ AttachCustomVisual(CustomVisualHost)
           └─ CompositionCustomVisual作成
                  └─ CustomVisualHandler
                         ├─ OnRender（楕円描画）
                         ├─ OnMessage（Start/Stop/DirtyRects）
                         └─ OnAnimationFrameUpdate（フレーム更新）

OnAttachedToVisualTree
    └─ Items.ItemsSource = CreateColorItems()
           └─ 48色のCompositionPageColorItemリスト

SetEnableAnimations（添付プロパティ）
    └─ EnsureImplicitAnimations()
           └─ ImplicitAnimationCollection設定
```

### データフロー図

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

ユーザー操作 ───────▶ CompositionPage ───────▶ 画面表示
  │                        │
  ├─ GridSplitterドラッグ ▶ Offset変更 ──────▶ 暗黙的アニメーション
  │                        │
  ├─ Start/Stopボタン ───▶ SendHandlerMessage ▶ カスタムビジュアル
  │                        │
  ├─ Precise dirty rects ▶ DirtyRects設定 ──▶ 描画最適化
  │                        │
  └─ Thread.Sleepボタン ─▶ UIスレッドブロック ▶ アニメーション継続
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CompositionPage.axaml | `samples/ControlCatalog/Pages/CompositionPage.axaml` | XAML | UI定義（3タブ構成） |
| CompositionPage.axaml.cs | `samples/ControlCatalog/Pages/CompositionPage.axaml.cs` | ソース | Compositionアニメーション実装 |
