# 機能設計書 96-NativePlatform

## 概要

本ドキュメントは、Avaloniaフレームワークにおける macOSネイティブプラットフォーム（NativePlatform / AvaloniaNativePlatform）機能の設計仕様を記述します。NativePlatformは、macOS上でAvaloniaアプリケーションを実行するための基盤を提供し、Cocoa APIを通じてウィンドウ管理、入力処理、レンダリングなどのネイティブ機能を統合します。

### 本機能の処理概要

AvaloniaNativePlatformは、AvaloniaフレームワークがmacOS上で動作するために必要なプラットフォーム抽象化レイヤーを実装します。libAvaloniaNativeネイティブライブラリと連携し、IWindowingPlatformインターフェースを実装して、ウィンドウ作成、クリップボード、カーソル、入力デバイス、画面情報などの各種プラットフォームサービスを提供します。

**業務上の目的・背景**：AvaloniaはクロスプラットフォームフレームワークとしてmacOSのネイティブな外観と動作を提供する必要があります。NativePlatformは、Cocoa/AppKitフレームワークとの橋渡しを行い、macOSのメニューバー、ドック統合、ネイティブダイアログ、Metal/OpenGLレンダリングなどのmacOS固有機能をサポートします。これにより、macOSユーザーに期待されるUXを提供できます。

**機能の利用シーン**：
- macOSデスクトップアプリケーションのAvalonia実行基盤
- macOSネイティブメニューバーの表示
- ドックアイコンとドックメニューの管理
- Metal/OpenGLによるGPUレンダリング
- macOS固有のキーボードショートカット対応

**主要な処理内容**：
1. libAvaloniaNativeライブラリの読み込みと初期化
2. IAvaloniaNativeFactory経由でのネイティブオブジェクト生成
3. macOSメニューバーとドックメニューのエクスポート
4. OpenGL/Metal レンダリングコンテキストの管理
5. macOS固有のホットキー設定
6. ストレージプロバイダ（ファイルダイアログ）の提供

**関連システム・外部連携**：
- libAvaloniaNative（Objective-C++ネイティブライブラリ）
- Cocoa / AppKit フレームワーク
- Metal / OpenGL
- macOS Storage API

**権限による制御**：AppSandbox環境での動作に対応し、ファイルアクセス権限やネットワーク権限はmacOSの権限システムに従います。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 63 | Native Embed | 主機能 | ネイティブコントロール埋め込みのデモ |
| 105 | Embedding | 主機能 | 埋め込みのテスト |

## 機能種別

プラットフォーム基盤 / ネイティブ統合 / Cocoa連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| AvaloniaNativePlatformOptions | AvaloniaNativePlatformOptions | No | プラットフォームオプション | - |
| MacOSPlatformOptions | MacOSPlatformOptions | No | macOS固有オプション | - |
| RenderingMode | AvaloniaNativeRenderingMode[] | No | レンダリングモード | OpenGl/Metal/Software |
| AvaloniaNativeLibraryPath | string | No | ネイティブライブラリパス | ファイル存在確認 |
| AppSandboxEnabled | bool | No | App Sandbox有効化 | - |

### 入力データソース

- アプリケーション設定（AvaloniaLocator経由）
- libAvaloniaNativeネイティブライブラリ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IWindowImpl | WindowImpl | ウィンドウ実装 |
| ITrayIconImpl | TrayIconImpl | トレイアイコン実装（メニューバー） |
| ITopLevelImpl | EmbeddableTopLevelImpl | 埋め込みトップレベル |

### 出力先

- AvaloniaLocator経由でのサービス登録
- macOSウィンドウシステム

## 処理フロー

### 処理シーケンス

```
1. UseAvaloniaNative()拡張メソッド呼び出し
   └─ AppBuilderの設定
2. ネイティブライブラリロード
   └─ CreateAvaloniaNative() P/Invoke
3. IAvaloniaNativeFactoryプロキシ作成
   └─ MicroComRuntime.CreateProxyFor
4. ファクトリ初期化
   └─ factory.Initialize(callbacks)
5. macOS固有設定
   └─ SetShowInDock, SetDisableSetProcessName等
6. サービス登録
   └─ AvaloniaLocatorへの各種サービスバインド
7. グラフィックス初期化
   └─ OpenGL/Metal/Softwareの選択
8. Compositor作成
   └─ new Compositor(platformGraphics, true)
```

### フローチャート

```mermaid
flowchart TD
    A[UseAvaloniaNative呼び出し] --> B{ライブラリパス指定?}
    B -->|Yes| C[カスタムパスからロード]
    B -->|No| D[CreateAvaloniaNative P/Invoke]
    C --> E[ファクトリプロキシ作成]
    D --> E
    E --> F[MacOptionsの設定]
    F --> G[GCHandleDeallocator登録]
    G --> H[ディスパッチャ初期化]
    H --> I[サービス登録]
    I --> J{レンダリングモード走査}
    J -->|OpenGl| K[AvaloniaNativeGlPlatformGraphics]
    J -->|Metal| L[MetalPlatformGraphics]
    J -->|Software| M[nullを使用]
    K --> N[Compositor作成]
    L --> N
    M --> N
    N --> O[メニューエクスポーター設定]
    O --> P[初期化完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-96-01 | レンダリング優先順位 | RenderingMode配列の順序で試行 | 初期化時 |
| BR-96-02 | ホットキー設定 | Commandキー(⌘)をメイン修飾キーとして設定 | 常時 |
| BR-96-03 | キージェスチャ記号 | macOS記号（⌘⇧⌃⌥）を使用 | キー表示時 |
| BR-96-04 | Dockアイコン表示 | ShowInDockオプションで制御 | macOS起動時 |
| BR-96-05 | AppDelegate無効化 | DisableAvaloniaAppDelegateで制御可能 | 特殊な統合時 |

### 計算ロジック

特になし。

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

### 操作別データベース影響一覧

本機能はデータベース操作を伴いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidOp-01 | InvalidOperationException | CreateAvaloniaNativeエクスポート未発見 | ライブラリパス確認 |
| NotImpl-01 | NotImplementedException | CreateEmbeddableWindow非対応 | EmbeddableTopLevelを使用 |

### リトライ仕様

レンダリングモードは優先度順にフォールバックします。

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

本機能はUI基盤のため、トランザクション管理は不要です。

## パフォーマンス要件

- Metalを優先してGPUアクセラレーション
- ネイティブレンダータイマーによる効率的な描画

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

- App Sandbox対応
- ファイルアクセス権限の適切な処理
- GCHandle解放のコールバック登録

## 備考

ProcessExitイベントでファクトリのDisposeを呼び出し、ネイティブリソースを解放します。

---

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

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

### 推奨読解順序

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

まず、ネイティブファクトリインターフェースと設定を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AvaloniaNativePlatformExtensions.cs | `src/Avalonia.Native/AvaloniaNativePlatformExtensions.cs` | プラットフォームオプション |
| 1-2 | IAvaloniaNativeFactory | Native Interop | ネイティブファクトリインターフェース |

**読解のコツ**: MicroCom.Runtimeによるネイティブ相互運用パターンを理解してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AvaloniaNativePlatform.cs | `src/Avalonia.Native/AvaloniaNativePlatform.cs` | メインプラットフォームクラス |

**主要処理フロー**:
1. **25-26行目**: CreateAvaloniaNative P/Invoke宣言
2. **31-42行目**: Initialize(IntPtr) - ファクトリプロキシ作成
3. **46-62行目**: Initialize(options) - オプション付き初期化
4. **95-192行目**: DoInitialize - 詳細初期化処理
5. **117-133行目**: サービス登録
6. **135-141行目**: ホットキー設定
7. **143-149行目**: キージェスチャフォーマット設定
8. **151-181行目**: グラフィックス初期化
9. **200-207行目**: CreateWindow - ウィンドウ生成

#### Step 3: ウィンドウ実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | WindowImpl.cs | `src/Avalonia.Native/WindowImpl.cs` | ウィンドウ実装 |
| 3-2 | WindowImplBase.cs | `src/Avalonia.Native/WindowImplBase.cs` | ウィンドウ基底クラス |
| 3-3 | TopLevelImpl.cs | `src/Avalonia.Native/TopLevelImpl.cs` | トップレベル実装 |

#### Step 4: メニュー統合を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | AvaloniaNativeMenuExporter.cs | `src/Avalonia.Native/AvaloniaNativeMenuExporter.cs` | メニューエクスポート |
| 4-2 | MacOSNativeMenuCommands.cs | `src/Avalonia.Native/MacOSNativeMenuCommands.cs` | ネイティブコマンド |

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

```
AvaloniaNativePlatform
    │
    ├─ Initialize()
    │      ├─ CreateAvaloniaNative() [P/Invoke]
    │      ├─ MicroComRuntime.CreateProxyFor<IAvaloniaNativeFactory>
    │      └─ DoInitialize()
    │             ├─ factory.Initialize()
    │             ├─ サービス登録
    │             └─ グラフィックス初期化
    │
    ├─ CreateWindow()
    │      └─ new WindowImpl(factory, options)
    │
    ├─ CreateTrayIcon()
    │      └─ new TrayIconImpl(factory)
    │
    └─ SetupApplicationMenuExporter()
           └─ new AvaloniaNativeMenuExporter(factory)
```

### データフロー図

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

AvaloniaNativePlatformOptions
         │
         ├─▶ AvaloniaNativePlatform ──────────▶ サービス登録
         │          │
         │          ├─ IAvaloniaNativeFactory
         │          │      └─ ネイティブオブジェクト生成
         │          │
         │          └─ RenderingMode選択
         │                 ├─ OpenGl → AvaloniaNativeGlPlatformGraphics
         │                 ├─ Metal → MetalPlatformGraphics
         │                 └─ Software → null

MacOSPlatformOptions ──▶ MacOptions設定
                              ├─ ShowInDock
                              ├─ DisableAvaloniaAppDelegate
                              └─ DisableSetProcessName
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AvaloniaNativePlatform.cs | `src/Avalonia.Native/AvaloniaNativePlatform.cs` | ソース | メインプラットフォームクラス |
| AvaloniaNativePlatformExtensions.cs | `src/Avalonia.Native/AvaloniaNativePlatformExtensions.cs` | ソース | 拡張メソッド |
| WindowImpl.cs | `src/Avalonia.Native/WindowImpl.cs` | ソース | ウィンドウ実装 |
| WindowImplBase.cs | `src/Avalonia.Native/WindowImplBase.cs` | ソース | ウィンドウ基底 |
| TopLevelImpl.cs | `src/Avalonia.Native/TopLevelImpl.cs` | ソース | トップレベル |
| PopupImpl.cs | `src/Avalonia.Native/PopupImpl.cs` | ソース | ポップアップ |
| ClipboardImpl.cs | `src/Avalonia.Native/ClipboardImpl.cs` | ソース | クリップボード |
| ScreenImpl.cs | `src/Avalonia.Native/ScreenImpl.cs` | ソース | スクリーン情報 |
| TrayIconImpl.cs | `src/Avalonia.Native/TrayIconImpl.cs` | ソース | トレイアイコン |
| Cursor.cs | `src/Avalonia.Native/Cursor.cs` | ソース | カーソル |
| DispatcherImpl.cs | `src/Avalonia.Native/DispatcherImpl.cs` | ソース | ディスパッチャ |
| Metal.cs | `src/Avalonia.Native/Metal.cs` | ソース | Metalグラフィックス |
| AvaloniaNativeGlPlatformGraphics.cs | `src/Avalonia.Native/AvaloniaNativeGlPlatformGraphics.cs` | ソース | OpenGLグラフィックス |
| AvaloniaNativeMenuExporter.cs | `src/Avalonia.Native/AvaloniaNativeMenuExporter.cs` | ソース | メニューエクスポート |
| MacOSNativeMenuCommands.cs | `src/Avalonia.Native/MacOSNativeMenuCommands.cs` | ソース | ネイティブコマンド |
| StorageProviderImpl.cs | `src/Avalonia.Native/StorageProviderImpl.cs` | ソース | ストレージプロバイダ |
| AvaloniaNativeDragSource.cs | `src/Avalonia.Native/AvaloniaNativeDragSource.cs` | ソース | ドラッグソース |
| MacOSActivatableLifetime.cs | `src/Avalonia.Native/MacOSActivatableLifetime.cs` | ソース | アクティベーション管理 |
| NativePlatformSettings.cs | `src/Avalonia.Native/NativePlatformSettings.cs` | ソース | プラットフォーム設定 |
