# 機能設計書 79-GradientBrush

## 概要

本ドキュメントは、Avaloniaフレームワークにおけるグラデーションブラシ機能（GradientBrush）の設計仕様を記述する。GradientBrushは、複数の色を滑らかに遷移させて塗りつぶすブラシの抽象基底クラスであり、LinearGradientBrush（線形）とRadialGradientBrush（放射状）の共通機能を提供する。

### 本機能の処理概要

GradientBrushは、グラデーション停止点（GradientStop）のコレクションを管理し、色の遷移パターンを定義する。SpreadMethod（グラデーションの端での繰り返し方法）を設定可能で、Pad（端の色で塗りつぶし）、Reflect（反転繰り返し）、Repeat（同じパターン繰り返し）の3種類をサポートする。

**業務上の目的・背景**：単色では表現できない視覚的な深みや立体感をUIに与えることができる。ボタンのハイライト、背景の装飾、進捗バーの表現など、多様な場面でグラデーションは使用され、プロフェッショナルなUI外観を実現する。

**機能の利用シーン**：Control.Backgroundへのグラデーション設定、ボタンやパネルの装飾、データビジュアライゼーション、カスタムコントロールの描画など。

**主要な処理内容**：
1. グラデーション停止点（GradientStops）の管理
2. 拡散方法（SpreadMethod）の管理
3. 停止点変更の監視と通知
4. Compositorへのシリアライズ
5. 不変ブラシへの変換（ToImmutable）

**関連システム・外部連携**：DrawingContext、Compositor、SolidColorBrushと同様の描画システムと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 82 | Brushes | 補助機能 | グラデーションブラシのデモ |

## 機能種別

グラフィックス基盤 / グラデーション描画

## 入力仕様

### 入力パラメータ（GradientBrush共通）

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SpreadMethod | GradientSpreadMethod | No | 端での繰り返し方法 | デフォルト: Pad |
| GradientStops | GradientStops | No | 色の停止点コレクション | 自動初期化 |

### LinearGradientBrush追加パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| StartPoint | RelativePoint | No | 開始点 | デフォルト: TopLeft |
| EndPoint | RelativePoint | No | 終了点 | デフォルト: BottomRight |

### RadialGradientBrush追加パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Center | RelativePoint | No | 中心点 | デフォルト: Center |
| GradientOrigin | RelativePoint | No | グラデーション原点 | デフォルト: Center |
| RadiusX | RelativeScalar | No | X方向半径 | デフォルト: 0.5 |
| RadiusY | RelativeScalar | No | Y方向半径 | デフォルト: 0.5 |

### GradientSpreadMethod列挙値

| 値 | 説明 |
|---|------|
| Pad | 端の色でそのまま塗りつぶす |
| Reflect | グラデーションを反転して繰り返す |
| Repeat | 同じグラデーションパターンを繰り返す |

### 入力データソース

- XAMLマークアップでのグラデーション定義
- プログラムによる直接インスタンス化

## 出力仕様

### 出力データ

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

### 出力先

- DrawingContextへの塗りつぶしパラメータ
- Control.Background等のブラシプロパティ

## 処理フロー

### 処理シーケンス

```
1. GradientBrush生成
   └─ GradientStopsの初期化
2. GradientStops設定
   └─ 停止点の追加/変更
3. 変更監視
   └─ CollectionChanged/PropertyChanged購読
4. Compositorシリアライズ
   └─ SpreadMethod、各停止点をシリアライズ
5. レンダリング
   └─ GPUシェーダーでグラデーション描画
```

### フローチャート

```mermaid
flowchart TD
    A[GradientBrush生成] --> B[GradientStops初期化]
    B --> C[停止点追加]
    C --> D{停止点変更?}
    D -->|Yes| E[CollectionChanged通知]
    D -->|No| F{プロパティ変更?}
    E --> G[RegisterForSerialization]
    F -->|Yes| H[PropertyChanged通知]
    F -->|No| I[描画使用]
    H --> G
    G --> I
    I --> J[Compositorシリアライズ]
    J --> K[GPUレンダリング]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-79-01 | 停止点ソート | GradientStopsはOffsetでソートされるべき | 描画時 |
| BR-79-02 | デフォルト拡散 | SpreadMethodのデフォルトはPad | 常時 |
| BR-79-03 | 変更追跡 | 停止点の追加/削除/変更はすべて追跡される | 常時 |

### 計算ロジック

線形グラデーション補間:
```
t = (position - StartPoint) / (EndPoint - StartPoint)
color = InterpolateColors(GradientStops, t)
```

放射状グラデーション補間:
```
distance = Distance(position, Center) / Radius
color = InterpolateColors(GradientStops, distance)
```

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | 特別なエラーケースなし | - |

### リトライ仕様

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

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

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

## パフォーマンス要件

- GradientStopsの変更監視は効率的に実装
- Compositorシリアライズは変更時のみ実行
- GPUシェーダーによる高速なグラデーション描画

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

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

## 備考

- GradientBrushはBrushを継承しており、Opacity、Transform、TransformOriginも使用可能
- [Content]属性によりGradientStopsはXAMLの既定コンテンツ
- IMutableBrushを実装しており、変更可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | GradientBrush.cs | `src/Avalonia.Base/Media/GradientBrush.cs` | グラデーション基底クラス |

**主要処理フロー**:
- **24-25行目**: SpreadMethodPropertyの定義
- **30-31行目**: GradientStopsPropertyの定義
- **40-43行目**: コンストラクタでGradientStops初期化
- **52-58行目**: GradientStopsプロパティ（[Content]属性）
- **64-83行目**: OnPropertyChanged（コレクション変更監視）
- **95-103行目**: SerializeChanges（Compositorへのシリアライズ）

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

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

**主要処理フロー**:
- **LinearGradientBrush 17-20行目**: StartPointProperty（デフォルト: TopLeft）
- **LinearGradientBrush 25-28行目**: EndPointProperty（デフォルト: BottomRight）
- **RadialGradientBrush 18-21行目**: CenterProperty（デフォルト: Center）
- **RadialGradientBrush 26-29行目**: GradientOriginProperty
- **RadialGradientBrush 34-43行目**: RadiusX/RadiusYProperty

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

```
Brush (abstract)
    │
    └─ GradientBrush (abstract)
           │   ├─ SpreadMethod
           │   └─ GradientStops
           │
           ├─ LinearGradientBrush
           │      ├─ StartPoint
           │      └─ EndPoint
           │
           └─ RadialGradientBrush
                  ├─ Center
                  ├─ GradientOrigin
                  ├─ RadiusX
                  └─ RadiusY
```

### データフロー図

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

GradientStops ───▶ GradientBrush ───▶ DrawingContext
    │                    │                    │
    │              色補間計算                  ▼
    │                    │              GPUシェーダー
    ▼                    │                    │
[GradientStop]           │                    ▼
  ├─ Offset        シリアライズ            画面表示
  └─ Color              │
                        ▼
                   Compositor
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| GradientBrush.cs | `src/Avalonia.Base/Media/GradientBrush.cs` | ソース | グラデーション基底 |
| LinearGradientBrush.cs | `src/Avalonia.Base/Media/LinearGradientBrush.cs` | ソース | 線形グラデーション |
| RadialGradientBrush.cs | `src/Avalonia.Base/Media/RadialGradientBrush.cs` | ソース | 放射状グラデーション |
| GradientStop.cs | `src/Avalonia.Base/Media/GradientStop.cs` | ソース | 停止点定義 |
| GradientStops.cs | `src/Avalonia.Base/Media/GradientStops.cs` | ソース | 停止点コレクション |
| GradientSpreadMethod.cs | `src/Avalonia.Base/Media/GradientSpreadMethod.cs` | ソース | 拡散方法列挙 |
| ImmutableLinearGradientBrush.cs | `src/Avalonia.Base/Media/Immutable/ImmutableLinearGradientBrush.cs` | ソース | 不変線形グラデーション |
| ImmutableRadialGradientBrush.cs | `src/Avalonia.Base/Media/Immutable/ImmutableRadialGradientBrush.cs` | ソース | 不変放射状グラデーション |
| ImmutableGradientStop.cs | `src/Avalonia.Base/Media/Immutable/ImmutableGradientStop.cs` | ソース | 不変停止点 |
| Brush.cs | `src/Avalonia.Base/Media/Brush.cs` | ソース | ブラシ基底 |
