# 機能設計書 108-Metal

## 概要

本ドキュメントは、Avalonia UIフレームワークにおけるMetal統合機能の機能設計書である。macOS/iOS環境でのMetalレンダリング対応を提供する。

### 本機能の処理概要

Metal統合機能は、Apple製プラットフォーム（macOS、iOS、tvOS）でMetalグラフィックスAPIを使用したGPUアクセラレーションレンダリングを可能にする。Appleデバイス特有のGPU最適化を活用し、高パフォーマンスなグラフィックス描画を実現する。

**業務上の目的・背景**：MetalはAppleが開発した低レベルグラフィックスAPIであり、OpenGLに代わるAppleプラットフォームの主要グラフィックスAPIである。macOSでのOpenGL非推奨化に伴い、Metal対応はAppleプラットフォームでの最適なパフォーマンスを得るために必須となっている。Avalonia Metal統合により、macOS/iOSアプリケーションでネイティブに近いパフォーマンスを実現する。

**機能の利用シーン**：
- macOS向け高パフォーマンスグラフィックスアプリケーション
- iOS/iPadOSゲームやビジュアライゼーション
- Apple Silicon Mac向け最適化アプリケーション
- ProMotion対応ディスプレイでの高フレームレートアプリケーション
- macOS/iOS向け動画編集・画像処理アプリケーション

**主要な処理内容**：
1. Metalデバイスの取得と管理
2. コマンドキューの作成
3. レンダーターゲットサーフェスの管理
4. Metalテクスチャを通じた描画出力
5. Skiaとの統合（SkiaSharp Metal backend）

**関連システム・外部連携**：
- Metal Framework（Apple）
- Skia（SkiaSharp Metal backend）
- CAMetalLayer

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | Metalレンダリング | 主機能 | macOS/iOS Metalレンダリング対応 |

## 機能種別

GPUレンダリング / グラフィックスAPI統合

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Device | IntPtr | Yes | Metalデバイスハンドル | 有効なポインタ |
| CommandQueue | IntPtr | Yes | コマンドキューハンドル | 有効なポインタ |

### 入力データソース

- システムMetalドライバー
- CAMetalLayerサーフェス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IMetalDevice | IMetalDevice | Metalデバイスコンテキスト |
| Texture | IntPtr | 描画先Metalテクスチャ |

### 出力先

- CAMetalLayerサーフェス
- 画面表示

## 処理フロー

### 処理シーケンス

```
1. IMetalDevice取得
   └─ システムデフォルトMetalデバイス
2. コマンドキュー作成
   └─ Device.CommandQueue
3. IMetalPlatformSurface取得
   └─ プラットフォーム固有サーフェス
4. レンダーターゲット作成
   └─ CreateMetalRenderTarget
5. レンダリングセッション開始
   └─ BeginRendering
6. テクスチャ描画
   └─ Texture/Size/Scaling情報を使用
7. セッション終了
   └─ Disposeでコミット
```

### フローチャート

```mermaid
flowchart TD
    A[IMetalDevice取得] --> B[CommandQueue取得]
    B --> C[IMetalPlatformSurface取得]
    C --> D[CreateMetalRenderTarget]
    D --> E[BeginRendering]
    E --> F[Texture取得]
    F --> G[Metal描画コマンド]
    G --> H[Dispose/コミット]
    H --> I{次フレーム?}
    I -->|Yes| E
    I -->|No| J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-108-1 | Y軸反転 | IsYFlipped=trueの場合は座標系を反転 | レンダリング時 |
| BR-108-2 | スケーリング | Retinaディスプレイ等のスケーリング係数を適用 | 高DPIディスプレイ |
| BR-108-3 | デバイス管理 | IPlatformGraphicsContextを実装しコンテキスト管理 | 常時 |

### 計算ロジック

特になし。

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| METAL_NOT_AVAILABLE | Exception | Metal非対応デバイス | ソフトウェアレンダリングへフォールバック |
| DEVICE_LOST | - | デバイスロスト | 再初期化 |

### リトライ仕様

デバイスロスト時は再初期化を試行。

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

トランザクションなし。

## パフォーマンス要件

- Apple Silicon向け最適化
- ProMotionディスプレイ（120Hz）対応
- 効率的なテクスチャ管理

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

- Metalドライバーのセキュリティに依存
- シェーダーコードの検証はアプリケーション責任

## 備考

- macOS 10.11以降、iOS 8以降が必要
- PrivateApi属性付きのため内部実装
- SkiaSharpのMetal backendと統合

---

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

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

### 推奨読解順序

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

Metalインターフェースの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IMetalDevice.cs | `src/Avalonia.Metal/IMetalDevice.cs` | IMetalDevice、IMetalPlatformSurface、関連インターフェース定義 |

**読解のコツ**: すべてのインターフェースにPrivateApi属性が付与されており、内部実装専用であることを示している。

#### Step 2: インターフェース詳細を理解する

各インターフェースの役割を理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | IMetalDevice.cs | `src/Avalonia.Metal/IMetalDevice.cs` | IMetalDevice（9-13行目）、IPlatformGraphicsContext継承 |

**主要処理フロー**:
- **9-13行目**: IMetalDeviceはDevice（IntPtr）とCommandQueue（IntPtr）を公開
- **15-19行目**: IMetalPlatformSurfaceはレンダーターゲット作成メソッドを定義
- **21-25行目**: IMetalPlatformSurfaceRenderTargetはBeginRenderingメソッドを提供
- **27-34行目**: IMetalPlatformSurfaceRenderingSessionはTexture、Size、Scaling、IsYFlippedを公開

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

```
IMetalDevice
    │
    ├─ Device (IntPtr) - MTLDeviceハンドル
    │
    └─ CommandQueue (IntPtr) - MTLCommandQueueハンドル

IMetalPlatformSurface
    │
    └─ CreateMetalRenderTarget(IMetalDevice)
           │
           └─ IMetalPlatformSurfaceRenderTarget

IMetalPlatformSurfaceRenderTarget
    │
    └─ BeginRendering()
           │
           └─ IMetalPlatformSurfaceRenderingSession
                  │
                  ├─ Texture (IntPtr) - MTLTextureハンドル
                  ├─ Size (PixelSize) - テクスチャサイズ
                  ├─ Scaling (double) - スケーリング係数
                  └─ IsYFlipped (bool) - Y軸反転フラグ
```

### データフロー図

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

システムMetal ────────▶ IMetalDevice取得 ─────────────▶ Device/CommandQueue
デバイス                      │
                             ▼
CAMetalLayer ─────────▶ IMetalPlatformSurface ────────▶ RenderTarget
                             │
                             ▼
レンダリング要求 ─────▶ BeginRendering ───────────────▶ RenderingSession
                             │                              │
                             ▼                              ▼
                        Metal描画 ────────────────────▶ Texture描画
                             │
                             ▼
                        Dispose/コミット ─────────────▶ 画面表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| IMetalDevice.cs | `src/Avalonia.Metal/IMetalDevice.cs` | ソース | インターフェース定義 |
| IMetalExternalObjectsFeature.cs | `src/Avalonia.Metal/IMetalExternalObjectsFeature.cs` | ソース | 外部オブジェクト共有インターフェース |

**注意**: Metal統合の実際の実装はAvalonia.Native（macOS）やAvalonia.iOS等のプラットフォーム固有プロジェクトに存在する。Avalonia.Metalプロジェクトはインターフェース定義のみを提供している。
