# 機能設計書 73-Brush

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるブラシ機能（Brush）の設計仕様を記述する。Brushは、図形や背景などの塗りつぶしスタイルを定義する抽象基底クラスであり、SolidColorBrush、GradientBrush等の具象実装の共通基盤を提供する。

### 本機能の処理概要

Brushは、描画領域を塗りつぶす方法を定義するグラフィックス基盤機能である。単色塗りつぶし（SolidColorBrush）、線形グラデーション（LinearGradientBrush）、放射状グラデーション（RadialGradientBrush）など、多様な塗りつぶしパターンの共通インターフェースを提供し、Opacity（不透明度）とTransform（変換）のサポートを実現する。

**業務上の目的・背景**：UIアプリケーションにおいて、視覚的な表現力は重要な要素である。Brushシステムは、コントロールの背景、前景、境界線などあらゆる描画要素に統一的な塗りつぶしスタイルを適用可能にする。これにより、一貫性のあるビジュアルデザインと、柔軟なスタイリングオプションを実現できる。

**機能の利用シーン**：Control.Backgroundプロパティ、Control.Foregroundプロパティ、Border.Backgroundプロパティ、Shape.Fillプロパティ、Pen.Brushプロパティなど、UIのあらゆる塗りつぶし指定箇所で使用される。

**主要な処理内容**：
1. 不透明度（Opacity）の管理
2. 変換（Transform）の適用
3. 変換原点（TransformOrigin）の管理
4. 文字列からのブラシ解析（Parse）
5. コンポジター向けリソース管理

**関連システム・外部連携**：描画システム（DrawingContext）、レンダリングパイプライン（Compositor）、スタイリングシステムと連携し、すべてのUI要素の塗りつぶしを担当する。

**権限による制御**：本機能は純粋な描画機能であり、特別な権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | Acrylic | 主画面 | アクリル効果のデモでブラシを使用 |
| 82 | Brushes | 主画面 | 各種ブラシのデモ表示 |

## 機能種別

グラフィックス基盤 / 描画スタイル定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Opacity | double | No | 不透明度（0.0〜1.0） | デフォルト: 1.0 |
| Transform | ITransform? | No | ブラシに適用する変換 | null可 |
| TransformOrigin | RelativePoint | No | 変換の原点 | デフォルト: (0,0) |

### 入力データソース

- XAMLマークアップでのブラシ定義
- Brush.Parse()メソッドによる文字列解析
- プログラムによる直接インスタンス化

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IBrush | IBrush | ブラシインターフェースとしての自身 |
| ImmutableBrush | IImmutableBrush | 不変ブラシへの変換（ToImmutable） |

### 出力先

- DrawingContextへの塗りつぶしパラメータとして渡される
- Compositorシステムへのリソースとして登録

## 処理フロー

### 処理シーケンス

```
1. ブラシインスタンス生成
   └─ StyledPropertyによる初期化
2. プロパティ設定
   └─ Opacity/Transform/TransformOrigin
3. 描画時の適用
   └─ DrawingContextに渡される
   └─ Compositorでシリアライズ
4. レンダリング
   └─ GPUシェーダーで塗りつぶし実行
```

### フローチャート

```mermaid
flowchart TD
    A[ブラシ生成] --> B{Parse文字列?}
    B -->|Yes| C[KnownColors検索]
    C --> D{既知の色?}
    D -->|Yes| E[キャッシュされたブラシを返す]
    D -->|No| F[Color.TryParse]
    F --> G{解析成功?}
    G -->|Yes| H[ImmutableSolidColorBrush生成]
    G -->|No| I[FormatException]
    B -->|No| J[プロパティ設定]
    J --> K[Compositor登録]
    K --> L[描画時使用]
    E --> L
    H --> L
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-73-01 | デフォルト不透明度 | Opacityのデフォルト値は1.0（完全不透明） | 常時 |
| BR-73-02 | 既知色の最適化 | 既知の色名はキャッシュされたブラシを返す | Brush.Parse時 |
| BR-73-03 | 変換の適用順序 | TransformOriginを中心にTransformが適用される | Transform設定時 |

### 計算ロジック

最終的な不透明度 = Brush.Opacity × 描画コンテキストの不透明度

変換行列の適用:
```
result = Translate(-TransformOrigin) × Transform × Translate(TransformOrigin)
```

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FormatException | 解析エラー | Parse()で無効なブラシ文字列 | 有効な色名または16進数カラーコードを指定 |
| ArgumentNullException | 引数エラー | Parse()にnullを渡した場合 | nullでない文字列を指定 |

### リトライ仕様

本機能にリトライ仕様は存在しない。

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

本機能にトランザクション管理は存在しない。

## パフォーマンス要件

- 既知の色名はキャッシュされたブラシインスタンスを返す（メモリ最適化）
- Immutableブラシは共有可能で効率的
- Compositorへのシリアライズは変更時のみ実行

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

本機能は描画処理のみを担当するため、特別なセキュリティ考慮事項は存在しない。

## 備考

- BrushはAnimatableを継承しており、アニメーション対応
- TypeConverterにより、XAMLで直接色名や16進数カラーコードを指定可能
- ICompositionRenderResourceを実装し、GPUアクセラレーション対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IBrush.cs | `src/Avalonia.Base/Media/IBrush.cs` | ブラシの基本契約 |
| 1-2 | IImmutableBrush.cs | `src/Avalonia.Base/Media/Immutable/IImmutableBrush.cs` | 不変ブラシの契約 |

**読解のコツ**: IBrushはOpacity、Transform、TransformOriginを定義する最小限のインターフェース。

#### Step 2: 基底クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Brush.cs | `src/Avalonia.Base/Media/Brush.cs` | ブラシ抽象基底クラス |

**主要処理フロー**:
- **21-22行目**: OpacityPropertyの定義（デフォルト1.0）
- **27-28行目**: TransformPropertyの定義
- **33-34行目**: TransformOriginPropertyの定義
- **68-89行目**: Parseメソッドによる文字列解析
- **91-99行目**: プロパティ変更時のCompositor通知
- **112-128行目**: Compositorリソース管理

#### Step 3: 具象実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SolidColorBrush.cs | `src/Avalonia.Base/Media/SolidColorBrush.cs` | 単色ブラシ |
| 3-2 | GradientBrush.cs | `src/Avalonia.Base/Media/GradientBrush.cs` | グラデーション基底 |
| 3-3 | LinearGradientBrush.cs | `src/Avalonia.Base/Media/LinearGradientBrush.cs` | 線形グラデーション |
| 3-4 | RadialGradientBrush.cs | `src/Avalonia.Base/Media/RadialGradientBrush.cs` | 放射状グラデーション |

**主要処理フロー**:
- **SolidColorBrush 18-19行目**: ColorPropertyの定義
- **SolidColorBrush 82-85行目**: ToImmutableの実装
- **GradientBrush 24-31行目**: GradientStopsPropertyの定義
- **LinearGradientBrush 17-28行目**: StartPoint/EndPointの定義

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

```
Brush (abstract)
    │
    ├─ SolidColorBrush
    │      └─ Color プロパティ
    │
    └─ GradientBrush (abstract)
           │
           ├─ LinearGradientBrush
           │      └─ StartPoint / EndPoint
           │
           └─ RadialGradientBrush
                  └─ Center / GradientOrigin / RadiusX / RadiusY
```

### データフロー図

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

文字列 "Red" ───▶ Brush.Parse() ───▶ ImmutableSolidColorBrush(Red)
                       │
文字列 "#FF0000" ───▶  │
                       │
              KnownColors検索
              または
              Color.TryParse()
                       │
                       ▼
              DrawingContext ───▶ GPUレンダリング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Brush.cs | `src/Avalonia.Base/Media/Brush.cs` | ソース | ブラシ抽象基底クラス |
| IBrush.cs | `src/Avalonia.Base/Media/IBrush.cs` | ソース | ブラシインターフェース |
| SolidColorBrush.cs | `src/Avalonia.Base/Media/SolidColorBrush.cs` | ソース | 単色ブラシ |
| GradientBrush.cs | `src/Avalonia.Base/Media/GradientBrush.cs` | ソース | グラデーション基底 |
| LinearGradientBrush.cs | `src/Avalonia.Base/Media/LinearGradientBrush.cs` | ソース | 線形グラデーション |
| RadialGradientBrush.cs | `src/Avalonia.Base/Media/RadialGradientBrush.cs` | ソース | 放射状グラデーション |
| ImmutableSolidColorBrush.cs | `src/Avalonia.Base/Media/Immutable/ImmutableSolidColorBrush.cs` | ソース | 不変単色ブラシ |
| BrushConverter.cs | `src/Avalonia.Base/Media/BrushConverter.cs` | ソース | 型変換 |
| KnownColors.cs | `src/Avalonia.Base/Media/KnownColors.cs` | ソース | 既知色定義 |
| Animatable.cs | `src/Avalonia.Base/Animation/Animatable.cs` | ソース | アニメーション基底 |
