# 機能設計書 88-SkiaPlatform

## 概要

本ドキュメントは、Avaloniaフレームワークにおける2D描画エンジン「SkiaPlatform」の設計仕様を記述する。SkiaPlatformは、SkiaSharpライブラリを使用してクロスプラットフォームの高性能2D描画を実現する、Avaloniaの主要レンダリングバックエンドである。

### 本機能の処理概要

SkiaPlatformは、Google製の2DグラフィックスライブラリSkiaのC#バインディング（SkiaSharp）をAvaloniaのレンダリングパイプラインに統合する。ジオメトリ、ビットマップ、テキスト、エフェクトなど、すべての2D描画プリミティブをSkia APIを通じてレンダリングする。GPUアクセラレーション（OpenGL、Vulkan、Metal）とソフトウェアレンダリングの両方をサポートする。

**業務上の目的・背景**：クロスプラットフォームGUIアプリケーションでは、一貫した描画品質と高いパフォーマンスが求められる。SkiaはChrome、Android、Flutter等で使用されている実績のあるライブラリであり、Avaloniaにおいても安定した描画基盤を提供する。

**機能の利用シーン**：すべてのUI要素の描画、画像処理、テキストレンダリング、ベクターグラフィックス、カスタムエフェクトで利用される。

**主要な処理内容**：
1. IPlatformRenderInterfaceの実装（PlatformRenderInterface）
2. ジオメトリの作成（楕円、矩形、パス等）
3. ビットマップの読み込み・書き込み
4. GlyphRunの作成とテキストレンダリング
5. GPUコンテキストの管理（OpenGL、Vulkan、Metal）
6. DrawingContextの提供

**関連システム・外部連携**：SkiaSharp、OpenGL/Vulkan/Metal GPU API、FontManagerImplと連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面 | 補助機能 | Skiaによる2D描画 |

## 機能種別

プラットフォーム実装 / レンダリングエンジン

## 入力仕様

### 入力パラメータ

**Initialize**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| options | SkiaOptions | No | Skia設定オプション | デフォルトで空のSkiaOptions |

**LoadBitmap**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| stream | Stream | Yes | 画像ストリーム | - |

**CreateRenderTargetBitmap**:
| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| size | PixelSize | Yes | ビットマップサイズ | Width/Height >= 1 |
| dpi | Vector | Yes | DPI設定 | - |

### 入力データソース

Avaloniaランタイムからの初期化呼び出し、描画要求

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 各種Geometry | IGeometryImpl | ジオメトリ実装 |
| Bitmap | IBitmapImpl | ビットマップ実装 |
| GlyphRun | IGlyphRunImpl | グリフラン実装 |

### 出力先

ウィンドウサーフェス、ビットマップ、レンダーターゲット

## 処理フロー

### 処理シーケンス

```
1. プラットフォーム初期化
   └─ SkiaPlatform.Initialize()を呼び出し
   └─ PlatformRenderInterfaceを作成
   └─ FontManagerImplを作成
   └─ AvaloniaLocatorにバインド

2. バックエンドコンテキスト作成
   └─ CreateBackendContext(graphicsContext)を呼び出し
   └─ GPU種別に応じたSkiaGpuを作成
   └─ SkiaContextを返却

3. ジオメトリ作成
   └─ CreateEllipseGeometry/CreateRectangleGeometry等
   └─ SKPathを内部で作成
   └─ IGeometryImplを返却

4. ビットマップ操作
   └─ LoadBitmap: SKBitmapをデコード
   └─ CreateWriteableBitmap: 書き込み可能ビットマップ
   └─ CreateRenderTargetBitmap: レンダーターゲット

5. テキストレンダリング
   └─ CreateGlyphRun: GlyphRunImplを作成
   └─ BuildGlyphRunGeometry: テキストパスを構築
```

### フローチャート

```mermaid
flowchart TD
    A[SkiaPlatform.Initialize] --> B[PlatformRenderInterface作成]
    B --> C[FontManagerImpl作成]
    C --> D[AvaloniaLocatorにバインド]
    D --> E{GPUコンテキスト?}
    E -->|OpenGL| F[GlSkiaGpu]
    E -->|Vulkan| G[VulkanSkiaGpu]
    E -->|Metal| H[SkiaMetalGpu]
    E -->|null| I[ソフトウェアレンダリング]
    F --> J[SkiaContext作成]
    G --> J
    H --> J
    I --> J
    J --> K[描画準備完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトDPI | DefaultDpi = (96.0, 96.0) | 初期化時 |
| BR-002 | ビットマップサイズ制限 | Width/Heightは1以上 | CreateRenderTargetBitmap時 |
| BR-003 | サポートピクセルフォーマット | Rgb565, Bgra8888, Rgba8888をサポート | ビットマップ作成時 |
| BR-004 | デフォルトアルファフォーマット | Premul（事前乗算アルファ） | ビットマップ作成時 |

### 計算ロジック

**デフォルトピクセルフォーマット**:
```csharp
DefaultPixelFormat = SKImageInfo.PlatformColorType.ToPixelFormat()
```

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ArgumentException | CreateRenderTargetBitmapでWidth/Height < 1の場合 | 1以上の値を指定 |
| - | ArgumentException | CreateBackendContextでサポートされないGPUコンテキスト | 対応GPUを使用 |
| - | Exception | ResizeBitmapでImmutableBitmap以外のソース | 正しいビットマップ型を使用 |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

- MaxGpuResourceSizeBytesでGPUリソースサイズを制限可能
- SKPaintCacheでペイントオブジェクトを再利用
- SKTextBlobBuilderCacheでテキストブロブを再利用

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

特になし

## 備考

SkiaSharpは、NativeAOTやトリミングに対応しており、小さなバイナリサイズを実現できる。

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SkiaPlatform.cs | `src/Skia/Avalonia.Skia/SkiaPlatform.cs` | Initialize（13-25行目）: 初期化処理 |

**主要処理フロー**:
1. **15行目**: デフォルトオプションでオーバーロードを呼び出し
2. **20行目**: PlatformRenderInterfaceを作成
3. **22-24行目**: AvaloniaLocatorにバインド

#### Step 2: PlatformRenderInterfaceを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | クラス定義（20-214行目） |
| 2-2 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | CreateBackendContext（31-44行目）: GPUコンテキスト作成 |

**主要処理フロー**:
- **33-34行目**: nullの場合、ソフトウェアレンダリング
- **35-36行目**: ISkiaGpuならそのまま使用
- **37-38行目**: IGlContextならGlSkiaGpuを作成
- **39-40行目**: IMetalDeviceならSkiaMetalGpuを作成
- **41-42行目**: IVulkanPlatformGraphicsContextならVulkanSkiaGpuを作成

#### Step 3: ジオメトリ作成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | CreateEllipseGeometry（60行目） |
| 3-2 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | CreateLineGeometry（62行目） |
| 3-3 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | CreateRectangleGeometry（64行目） |
| 3-4 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | CreateStreamGeometry（68行目） |

#### Step 4: ビットマップ操作を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | LoadBitmap（116-128行目） |
| 4-2 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | CreateRenderTargetBitmap（187-200行目） |
| 4-3 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | CreateWriteableBitmap（203-206行目） |

#### Step 5: GlyphRun処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | BuildGlyphRunGeometry（82-113行目）: グリフパス構築 |
| 5-2 | PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | CreateGlyphRun（208-212行目）: GlyphRunImpl作成 |

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

```
SkiaPlatform
    │
    └─ Initialize(SkiaOptions)
           ├─ new PlatformRenderInterface(maxGpuResourceSizeBytes)
           └─ AvaloniaLocator.Bind

PlatformRenderInterface
    │
    ├─ CreateBackendContext(IPlatformGraphicsContext?)
    │      ├─ new SkiaContext(null) [ソフトウェア]
    │      ├─ new GlSkiaGpu(gl) [OpenGL]
    │      ├─ new SkiaMetalGpu(metal) [Metal]
    │      └─ new VulkanSkiaGpu(vulkan) [Vulkan]
    │
    ├─ CreateXXXGeometry
    │      ├─ EllipseGeometryImpl
    │      ├─ LineGeometryImpl
    │      ├─ RectangleGeometryImpl
    │      ├─ StreamGeometryImpl
    │      ├─ GeometryGroupImpl
    │      └─ CombinedGeometryImpl
    │
    ├─ LoadBitmap / CreateXXXBitmap
    │      ├─ ImmutableBitmap
    │      ├─ WriteableBitmapImpl
    │      └─ RenderTargetBitmapImpl
    │
    └─ CreateGlyphRun / BuildGlyphRunGeometry
           └─ GlyphRunImpl
```

### データフロー図

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

SkiaOptions ─────────────▶ SkiaPlatform.Initialize ──▶ AvaloniaLocator登録
                                │
                                ▼
GPUコンテキスト ─────────▶ CreateBackendContext ─────▶ SkiaContext
                                │
                                ▼
描画パラメータ ──────────▶ CreateXXXGeometry ─────────▶ IGeometryImpl
                                │
                                ▼
画像データ ──────────────▶ LoadBitmap ────────────────▶ IBitmapImpl
                                │
                                ▼
グリフ情報 ──────────────▶ CreateGlyphRun ─────────────▶ IGlyphRunImpl
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| SkiaPlatform.cs | `src/Skia/Avalonia.Skia/SkiaPlatform.cs` | ソース | 初期化エントリーポイント |
| PlatformRenderInterface.cs | `src/Skia/Avalonia.Skia/PlatformRenderInterface.cs` | ソース | レンダーインターフェース実装 |
| SkiaOptions.cs | `src/Skia/Avalonia.Skia/SkiaOptions.cs` | ソース | 設定オプション |
| DrawingContextImpl.cs | `src/Skia/Avalonia.Skia/DrawingContextImpl.cs` | ソース | 描画コンテキスト |
| FontManagerImpl.cs | `src/Skia/Avalonia.Skia/FontManagerImpl.cs` | ソース | フォント管理 |
| GlyphRunImpl.cs | `src/Skia/Avalonia.Skia/GlyphRunImpl.cs` | ソース | グリフラン実装 |
| ImmutableBitmap.cs | `src/Skia/Avalonia.Skia/ImmutableBitmap.cs` | ソース | 不変ビットマップ |
| WriteableBitmapImpl.cs | `src/Skia/Avalonia.Skia/WriteableBitmapImpl.cs` | ソース | 書き込み可能ビットマップ |
| RenderTargetBitmapImpl.cs | `src/Skia/Avalonia.Skia/RenderTargetBitmapImpl.cs` | ソース | レンダーターゲット |
| GlSkiaGpu.cs | `src/Skia/Avalonia.Skia/Gpu/OpenGl/GlSkiaGpu.cs` | ソース | OpenGL GPU |
| VulkanSkiaGpu.cs | `src/Skia/Avalonia.Skia/Gpu/Vulkan/VulkanSkiaGpu.cs` | ソース | Vulkan GPU |
| SkiaMetalGpu.cs | `src/Skia/Avalonia.Skia/Gpu/Metal/SkiaMetalGpu.cs` | ソース | Metal GPU |
