# 機能設計書 107-Vulkan

## 概要

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

### 本機能の処理概要

Vulkan統合機能は、AvaloniaアプリケーションでVulkan APIを使用したGPUアクセラレーションレンダリングを可能にする。高パフォーマンスな3Dグラフィックスやコンピュートシェーダーの実行基盤を提供し、OpenGLを超える低レベルGPU制御を実現する。

**業務上の目的・背景**：Vulkanは、Khronos Groupが策定した次世代グラフィックスAPIであり、OpenGLと比較して低オーバーヘッドでGPUリソースを直接制御できる。ゲームエンジン、リアルタイム3Dレンダリング、GPGPUアプリケーションにおいて、OpenGLより高いパフォーマンスを発揮する。Avalonia Vulkan統合により、これらの高度なグラフィックス要件を持つアプリケーションの構築が可能になる。

**機能の利用シーン**：
- 高パフォーマンス3Dゲームやシミュレーション
- GPGPUを活用した科学計算アプリケーション
- VRコンテンツビューワー
- 動画編集やリアルタイム映像処理
- 大規模3Dモデルのレンダリング

**主要な処理内容**：
1. VulkanインスタンスとVulkanデバイスの作成・管理
2. グラフィックスキューファミリーの選択
3. KHRサーフェスを通じたウィンドウシステム統合
4. コマンドバッファプールの管理
5. フェンス・セマフォによる同期処理
6. 外部オブジェクト共有機能（メモリ共有）

**関連システム・外部連携**：
- Vulkanドライバー（GPU固有）
- VK_KHR_surface拡張
- プラットフォーム固有サーフェス拡張（VK_KHR_win32_surface等）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 111 | GpuDemo | 補助機能 | Vulkanレンダリング対応 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| VulkanInstanceCreationOptions | VulkanInstanceCreationOptions | No | インスタンス作成オプション | - |
| VulkanDeviceCreationOptions | VulkanDeviceCreationOptions | No | デバイス作成オプション | - |
| CustomSharedDevice | IVulkanDevice | No | カスタム共有デバイス | - |

### 入力データソース

- システムVulkanドライバー
- プラットフォームサーフェス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| VulkanContext | VulkanContext | Vulkanコンテキスト |
| VkDevice | VkDevice | Vulkan論理デバイスハンドル |
| VkQueue | VkQueue | グラフィックスキューハンドル |

### 出力先

- Avaloniaレンダリングパイプライン
- 画面表示

## 処理フロー

### 処理シーケンス

```
1. VulkanPlatformGraphics.TryCreate呼び出し
   └─ VulkanOptions確認
2. VulkanInstance作成
   └─ 必要な拡張のロード
3. VulkanDevice作成
   └─ 物理デバイス列挙
   └─ グラフィックスキューファミリー選択
4. VulkanContext作成
   └─ VulkanInstanceApiとVulkanDeviceApiの初期化
5. レンダーターゲット作成
   └─ KHRサーフェスを通じてウィンドウに接続
6. 描画処理
   └─ コマンドバッファ記録・サブミット
```

### フローチャート

```mermaid
flowchart TD
    A[VulkanPlatformGraphics.TryCreate] --> B{CustomSharedDevice?}
    B -->|Yes| C[CustomSharedDeviceFactory作成]
    B -->|No| D[VulkanInstance.Create]
    D --> E[VulkanDevice.Create]
    E --> F{作成成功?}
    F -->|No| G[エラーログ出力]
    F -->|Yes| H[DefaultDeviceFactory作成]
    C --> I[VulkanPlatformGraphics作成]
    H --> I
    I --> J[CreateContext]
    J --> K[VulkanContext作成]
    K --> L[VulkanInstanceApi初期化]
    L --> M[VulkanDeviceApi初期化]
    M --> N[CreateRenderTarget]
    N --> O[VulkanKhrRenderTarget作成]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-107-1 | デバイス選択 | 最初の適切な物理デバイスを選択 | 複数GPU環境 |
| BR-107-2 | 拡張確認 | 外部オブジェクト共有には特定の拡張が必要 | メモリ共有時 |
| BR-107-3 | ロスト状態 | IsLost=trueの場合はコンテキスト再作成 | デバイスロスト時 |
| BR-107-4 | 共有デバイス | UsesSharedContext=trueの場合はデバイスを共有 | カスタムデバイス使用時 |

### 計算ロジック

特になし。

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

データベース操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| VK_INIT_FAIL | VulkanException | Vulkan初期化失敗 | ドライバー/ハードウェア確認 |
| SURFACE_NOT_FOUND | VulkanException | 適切なサーフェスが見つからない | プラットフォームサポート確認 |
| DEVICE_LOST | - | デバイスロスト | 再初期化 |

### リトライ仕様

デバイスロスト時はコンテキスト再作成を試行。

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

トランザクションなし。

## パフォーマンス要件

- 低オーバーヘッドGPU制御
- マルチスレッドコマンドバッファ記録
- 明示的な同期によるGPU/CPU並列処理

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

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

## 備考

- Vulkan 1.0以上をサポート
- 外部オブジェクト共有にはVK_KHR_external_memory等の拡張が必要

---

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

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

### 推奨読解順序

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

Vulkanオプションとコンテキストの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | VulkanOptions.cs | `src/Avalonia.Vulkan/VulkanOptions.cs` | VulkanOptions定義、インスタンス/デバイス作成オプション |
| 1-2 | VulkanContext.cs | `src/Avalonia.Vulkan/VulkanContext.cs` | VulkanContext実装、IVulkanPlatformGraphicsContext |

**読解のコツ**: VulkanContextはDeviceHandle、PhysicalDeviceHandle、InstanceHandle、MainQueueHandleなどの低レベルハンドルを公開。

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

プラットフォームグラフィックスの初期化を理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | VulkanPlatformGraphics.cs | `src/Avalonia.Vulkan/VulkanPlatformGraphics.cs` | TryCreate（77-100行目）でインスタンス/デバイス作成 |

**主要処理フロー**:
- **77-80行目**: CustomSharedDevice使用時は専用ファクトリー
- **82-92行目**: VulkanInstance.CreateとVulkanDevice.Create
- **18-19行目**: CreateContext()でVulkanContext作成

#### Step 3: デバイス作成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | VulkanDevice.cs | `src/Avalonia.Vulkan/Interop/VulkanDevice.cs` | デバイス管理 |
| 3-2 | VulkanDevice.Create.cs | `src/Avalonia.Vulkan/Interop/VulkanDevice.Create.cs` | デバイス作成ロジック |

#### Step 4: レンダーターゲットを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | VulkanKhrSurfaceRenderTarget.cs | `src/Avalonia.Vulkan/VulkanKhrSurfaceRenderTarget.cs` | KHRサーフェスレンダーターゲット |

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

```
VulkanPlatformGraphics.TryCreate
    │
    ├─ VulkanInstance.Create
    │      └─ Vulkan拡張のロード
    │
    ├─ VulkanDevice.Create
    │      ├─ 物理デバイス列挙
    │      ├─ キューファミリー選択
    │      └─ 論理デバイス作成
    │
    └─ VulkanPlatformGraphics (constructor)
           │
           └─ CreateContext
                  └─ VulkanContext (constructor)
                         │
                         ├─ VulkanInstanceApi作成
                         ├─ VulkanDeviceApi作成
                         └─ VulkanExternalObjectsFeature作成（拡張対応時）

VulkanContext.CreateRenderTarget
    │
    └─ VulkanKhrRenderTarget作成
           └─ IVulkanKhrSurfacePlatformSurface使用
```

### データフロー図

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

VulkanOptions ─────────▶ VulkanPlatformGraphics.TryCreate ─▶ VulkanContext
                               │
                               ▼
Vulkanドライバー ─────▶ VulkanInstance/Device ───────────▶ VkDevice
                               │                              VkQueue
                               ▼
プラットフォーム ─────▶ VulkanKhrRenderTarget ────────────▶ 画面表示
サーフェス
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| VulkanPlatformGraphics.cs | `src/Avalonia.Vulkan/VulkanPlatformGraphics.cs` | ソース | プラットフォームグラフィックス |
| VulkanContext.cs | `src/Avalonia.Vulkan/VulkanContext.cs` | ソース | Vulkanコンテキスト |
| VulkanOptions.cs | `src/Avalonia.Vulkan/VulkanOptions.cs` | ソース | オプション定義 |
| IVulkanDevice.cs | `src/Avalonia.Vulkan/IVulkanDevice.cs` | ソース | デバイスインターフェース |
| VulkanDevice.cs | `src/Avalonia.Vulkan/Interop/VulkanDevice.cs` | ソース | デバイス実装 |
| VulkanInstance.cs | `src/Avalonia.Vulkan/Interop/VulkanInstance.cs` | ソース | インスタンス実装 |
| VulkanCommandBuffer.cs | `src/Avalonia.Vulkan/Interop/VulkanCommandBuffer.cs` | ソース | コマンドバッファ |
| VulkanImage.cs | `src/Avalonia.Vulkan/Interop/VulkanImage.cs` | ソース | イメージ管理 |
| VulkanKhrSurfaceRenderTarget.cs | `src/Avalonia.Vulkan/VulkanKhrSurfaceRenderTarget.cs` | ソース | レンダーターゲット |
| VulkanExternalObjectsFeature.cs | `src/Avalonia.Vulkan/VulkanExternalObjectsFeature.cs` | ソース | 外部オブジェクト共有 |
