# 機能設計書 97-X11Platform

## 概要

本ドキュメントは、Avaloniaフレームワークにおける Linux X11プラットフォーム（X11Platform / AvaloniaX11Platform）機能の設計仕様を記述します。X11Platformは、Linux/Unix系OS上のX Window System環境でAvaloniaアプリケーションを実行するための基盤を提供します。

### 本機能の処理概要

AvaloniaX11Platformは、X11（X Window System）プロトコルを通じてウィンドウ管理、入力処理、レンダリングを行います。GLX/EGL/Vulkanによるハードウェアアクセラレーション、DBusメニュー統合、XInput2によるマルチタッチサポートなど、Linux環境で期待される機能を提供します。

**業務上の目的・背景**：Linuxデスクトップ環境（GNOME、KDE、XFCE等）でAvaloniaアプリケーションを動作させるため、X11プロトコルとの統合が必要です。X11Platformは、XlibやXCB経由でX Serverと通信し、ウィンドウ管理、イベント処理、グラフィックス描画を実現します。また、DBusを通じたデスクトップ統合（グローバルメニュー、通知等）もサポートします。

**機能の利用シーン**：
- LinuxデスクトップでのAvaloniaアプリケーション実行
- X11ベースのウィンドウマネージャとの統合
- GLX/EGL/Vulkanによるハードウェアアクセラレーション描画
- IME（入力メソッドエディタ）サポート
- マルチモニター環境での表示

**主要な処理内容**：
1. Xサーバーへの接続とディスプレイオープン
2. XI2（XInput2）マネージャの初期化
3. GLX/EGL/Vulkanグラフィックス初期化
4. DBusプラットフォーム設定の統合
5. IME（XIM/DBus IME）の設定

**関連システム・外部連携**：
- X11/Xlib
- GLX / EGL
- Vulkan
- DBus（メニュー、設定、通知）
- GTK（ネイティブダイアログ用）
- libinput/XInput2

**権限による制御**：X11環境変数（DISPLAY等）が正しく設定されている必要があります。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全画面共通 | 主機能 | Linux環境でのウィンドウ表示 |

## 機能種別

プラットフォーム基盤 / X11統合 / グラフィックス

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| X11PlatformOptions | X11PlatformOptions | No | プラットフォームオプション | - |
| RenderingMode | X11RenderingMode[] | No | レンダリングモード | Glx/Egl/Vulkan/Software |
| EnableIme | bool? | No | IME有効化 | 自動検出可 |
| EnableMultiTouch | bool? | No | マルチタッチ有効化 | デフォルト:true |
| UseDBusMenu | bool | No | DBusメニュー使用 | デフォルト:true |
| UseDBusFilePicker | bool | No | DBusファイルピッカー | デフォルト:true |
| WmClass | string | No | WM_CLASS設定 | - |

### 入力データソース

- 環境変数（DISPLAY、AVALONIA_IM_MODULE等）
- X11サーバー
- DBus

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IWindowImpl | X11Window | ウィンドウ実装 |
| ITrayIconImpl | XEmbedTrayIconImpl/DBusTrayIconImpl | トレイアイコン実装 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. UseX11()拡張メソッド呼び出し
   └─ AppBuilderの設定
2. XInitThreads()呼び出し
   └─ X11スレッドセーフ初期化
3. XOpenDisplay()
   └─ メインディスプレイとDeferredディスプレイの接続
4. OrphanedWindow作成
   └─ イベント処理用の非表示ウィンドウ
5. X11Info初期化
   └─ ディスプレイ情報の収集
6. XI2Manager初期化
   └─ XInput2サポートの確認
7. グラフィックス初期化
   └─ GLX/EGL/Vulkan/Softwareの選択
8. Compositor作成
   └─ new Compositor(graphics)
```

### フローチャート

```mermaid
flowchart TD
    A[UseX11呼び出し] --> B{IME有効化?}
    B -->|Auto| C[CJKロケール判定]
    B -->|Explicit| D[指定値使用]
    C --> E{DBus IME検出?}
    E -->|Yes| F[DBus IME設定]
    E -->|No| G{XIM設定?}
    G -->|Yes| H[XIM有効化]
    G -->|No| I[IME無効]
    F --> J[XInitThreads]
    H --> J
    I --> J
    D --> J
    J --> K[XOpenDisplay]
    K --> L{Display取得成功?}
    L -->|No| M[例外スロー]
    L -->|Yes| N[OrphanedWindow作成]
    N --> O[X11Info初期化]
    O --> P[XI2Manager初期化]
    P --> Q{RenderingMode走査}
    Q -->|Glx| R[GlxPlatformGraphics]
    Q -->|Egl| S[EglPlatformGraphics]
    Q -->|Vulkan| T[VulkanSupport]
    Q -->|Software| U[null]
    R --> V[Compositor作成]
    S --> V
    T --> V
    U --> V
    V --> W[初期化完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-97-01 | IME自動検出 | zh/ja/vi/koロケールでIME自動有効化 | EnableIme未設定時 |
| BR-97-02 | レンダリング優先順位 | RenderingMode配列順序でフォールバック | 初期化時 |
| BR-97-03 | GLXブラックリスト | llvmpipe/SVGA3DはGLXから除外 | GLX初期化時 |
| BR-97-04 | トレイアイコン選択 | DBusTray優先、非アクティブ時はXEmbed | トレイ作成時 |
| BR-97-05 | セッション管理 | AVALONIA_X11_USE_SESSION_MANAGEMENTで制御 | 環境変数 |

### 計算ロジック

Z-Orderの計算はXQueryTreeで子ウィンドウ一覧を取得し、スタック順序から算出します。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| Exception-01 | Exception | XOpenDisplay失敗 | DISPLAY環境変数確認 |
| InvalidOp-01 | InvalidOperationException | RenderingMode空配列 | 少なくとも1つのモード指定 |
| InvalidOp-02 | InvalidOperationException | 全RenderingModeが失敗 | Softwareモードの追加 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- GLibMainLoopオプションでGLib統合可能
- UseRetainedFramebufferでフレームバッファ保持

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

- X11認証トークンの適切な処理
- GLXレンダラーブラックリストによる不安定ドライバの除外

## 備考

X11PlatformOptionsでGlProfiles、GlxRendererBlacklist等の詳細設定が可能です。

---

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

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

### 推奨読解順序

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

まず、X11プラットフォームオプションと情報構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | X11Platform.cs (下部) | `src/Avalonia.X11/X11Platform.cs` | X11PlatformOptionsクラス定義 |
| 1-2 | X11Info.cs | `src/Avalonia.X11/X11Info.cs` | ディスプレイ情報構造 |

**読解のコツ**: X11RenderingMode列挙型とオプションの各プロパティの意味を確認してください。

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

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

**主要処理フロー**:
1. **43-109行目**: Initialize() - プラットフォーム初期化
2. **55-56行目**: XInitThreads / XOpenDisplay
3. **63-64行目**: OrphanedWindow作成
4. **67-69行目**: X11Info / Globals / Resources初期化
5. **78-93行目**: サービス登録
6. **95-99行目**: XI2Manager初期化
7. **101-108行目**: グラフィックス初期化
8. **122-131行目**: CreateTrayIcon - DBus/XEmbedの選択

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | X11Window.cs | `src/Avalonia.X11/X11Window.cs` | ウィンドウ実装 |
| 3-2 | X11Window.Xim.cs | `src/Avalonia.X11/X11Window.Xim.cs` | XIM統合 |
| 3-3 | X11Window.Ime.cs | `src/Avalonia.X11/X11Window.Ime.cs` | IME統合 |

#### Step 4: イベント処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | X11EventDispatcher.cs | `src/Avalonia.X11/Dispatching/X11EventDispatcher.cs` | イベントディスパッチ |
| 4-2 | X11PlatformThreading.cs | `src/Avalonia.X11/Dispatching/X11PlatformThreading.cs` | スレッド処理 |

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

```
AvaloniaX11Platform
    │
    ├─ Initialize()
    │      ├─ XInitThreads()
    │      ├─ XOpenDisplay()
    │      ├─ X11Info作成
    │      ├─ XI2Manager初期化
    │      ├─ サービス登録
    │      └─ InitializeGraphics()
    │             ├─ GlxPlatformGraphics.TryCreate()
    │             ├─ EglPlatformGraphics.TryCreate()
    │             └─ VulkanSupport.TryInitialize()
    │
    ├─ CreateWindow()
    │      └─ new X11Window(this, null)
    │
    └─ CreateTrayIcon()
           ├─ DBusTrayIconImpl (優先)
           └─ XEmbedTrayIconImpl (フォールバック)
```

### データフロー図

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

X11PlatformOptions ────▶ AvaloniaX11Platform ────────▶ サービス登録
         │                      │
         │                      ├─ XOpenDisplay()
         │                      │      └─ Display/DeferredDisplay
         │                      │
         │                      ├─ X11Info
         │                      │      └─ Atoms, Extensions
         │                      │
         │                      └─ InitializeGraphics()
         │                             ├─ IPlatformGraphics
         │                             └─ Compositor

環境変数 ───────────────▶ IME設定
                              ├─ DBus IME
                              └─ XIM
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| X11Platform.cs | `src/Avalonia.X11/X11Platform.cs` | ソース | メインプラットフォーム |
| X11Window.cs | `src/Avalonia.X11/X11Window.cs` | ソース | ウィンドウ実装 |
| X11Info.cs | `src/Avalonia.X11/X11Info.cs` | ソース | ディスプレイ情報 |
| X11Atoms.cs | `src/Avalonia.X11/X11Atoms.cs` | ソース | X11アトム定義 |
| X11Globals.cs | `src/Avalonia.X11/X11Globals.cs` | ソース | グローバル設定 |
| X11Screens.cs | `src/Avalonia.X11/Screens/X11Screens.cs` | ソース | スクリーン管理 |
| X11CursorFactory.cs | `src/Avalonia.X11/X11CursorFactory.cs` | ソース | カーソル生成 |
| X11Clipboard.cs | `src/Avalonia.X11/Clipboard/X11Clipboard.cs` | ソース | クリップボード |
| XI2Manager.cs | `src/Avalonia.X11/XI2Manager.cs` | ソース | XInput2管理 |
| X11EventDispatcher.cs | `src/Avalonia.X11/Dispatching/X11EventDispatcher.cs` | ソース | イベントディスパッチ |
| X11PlatformThreading.cs | `src/Avalonia.X11/Dispatching/X11PlatformThreading.cs` | ソース | スレッド処理 |
| GlibDispatcherImpl.cs | `src/Avalonia.X11/Dispatching/GLibDispatcherImpl.cs` | ソース | GLib統合 |
| GlxPlatformFeature.cs | `src/Avalonia.X11/Glx/GlxPlatformFeature.cs` | ソース | GLXサポート |
| XEmbedTrayIconImpl.cs | `src/Avalonia.X11/XEmbedTrayIconImpl.cs` | ソース | XEmbedトレイ |
| GtkNativeFileDialogs.cs | `src/Avalonia.X11/NativeDialogs/GtkNativeFileDialogs.cs` | ソース | GTKダイアログ |
| XLib.cs | `src/Avalonia.X11/XLib.cs` | ソース | Xlib P/Invoke |
