# 機能設計書 98-LinuxFramebuffer

## 概要

本ドキュメントは、Avaloniaフレームワークにおける Linuxフレームバッファ（LinuxFramebuffer）機能の設計仕様を記述します。LinuxFramebufferは、X11やWaylandなどのディスプレイサーバーを使用せずに、Linuxのフレームバッファデバイス（/dev/fb0等）やDRM/KMSに直接描画することで、組み込みLinux環境やキオスク端末でAvaloniaアプリケーションを実行するための基盤を提供します。

### 本機能の処理概要

LinuxFramebufferPlatformは、ディスプレイサーバーなしでLinux上での描画を可能にします。フレームバッファデバイス（fbdev）またはDRM（Direct Rendering Manager）を出力バックエンドとして使用し、libinput/EvDevによる入力処理と組み合わせて、シングルウィンドウのフルスクリーンアプリケーションを実現します。

**業務上の目的・背景**：組み込みシステム、キオスク端末、デジタルサイネージなど、フルスクリーンで動作する専用アプリケーションでは、X11/Waylandのオーバーヘッドを避け、より軽量な環境で動作させたい場合があります。LinuxFramebufferは、このようなユースケースに対応し、最小限のシステムリソースでAvalonia UIを表示できます。また、Raspberry PiなどのSBC（シングルボードコンピュータ）での利用も想定されています。

**機能の利用シーン**：
- 組み込みLinuxシステムでのUIアプリケーション
- キオスク端末やデジタルサイネージ
- Raspberry Pi等のSBCでのフルスクリーンアプリ
- 産業用HMI（ヒューマンマシンインターフェース）
- ディスプレイサーバーなしのミニマル環境

**主要な処理内容**：
1. 出力バックエンド初期化（FbdevOutput / DrmOutput）
2. 入力バックエンド初期化（LibInput / EvDev）
3. EpollDispatcherによるイベントループ
4. EmbeddableControlRootによるUIホスティング
5. Skiaによるソフトウェア/ハードウェアレンダリング

**関連システム・外部連携**：
- Linux Framebuffer（/dev/fb*）
- DRM/KMS
- libinput
- EvDev（/dev/input/event*）
- EGL/OpenGL ES（GPU対応時）

**権限による制御**：フレームバッファデバイスと入力デバイスへのアクセス権限が必要です。通常、video/inputグループへの所属またはroot権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | シングルビュー | 主機能 | フルスクリーンでのシングルビュー表示 |

## 機能種別

プラットフォーム基盤 / 組み込み / 直接描画

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| IOutputBackend | IOutputBackend | Yes | 出力バックエンド | FbdevOutput/DrmOutput |
| IInputBackend | IInputBackend | No | 入力バックエンド | LibInputBackend/EvDevBackend |
| fbdev | string | No | フレームバッファデバイスパス | /dev/fb0等 |
| card | string | No | DRMカードパス | /dev/dri/card0等 |
| scaling | double | No | スケーリング係数 | デフォルト:1.0 |
| Fps | int | No | FPS設定 | デフォルト:60 |

### 入力データソース

- フレームバッファデバイス（/dev/fb*）
- DRMデバイス（/dev/dri/card*）
- 入力デバイス（/dev/input/event*）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| TopLevel | EmbeddableControlRoot | シングルトップレベルウィンドウ |
| ExitCode | int | アプリケーション終了コード |

### 出力先

- フレームバッファ/DRMへの直接描画

## 処理フロー

### 処理シーケンス

```
1. StartLinuxFbDev()/StartLinuxDrm()呼び出し
   └─ AppBuilderの設定
2. 出力バックエンド作成
   └─ FbdevOutput / DrmOutput
3. LinuxFramebufferPlatform.Initialize()
   └─ プラットフォーム初期化
4. LinuxFramebufferLifetime作成
   └─ ライフサイクル管理
5. 入力バックエンド初期化
   └─ LibInput / EvDev
6. EmbeddableControlRoot作成
   └─ FramebufferToplevelImpl
7. アプリケーション実行
   └─ Run(lifetime.Token)
```

### フローチャート

```mermaid
flowchart TD
    A[StartLinuxFbDev/StartLinuxDrm] --> B{出力バックエンド選択}
    B -->|fbdev| C[FbdevOutput作成]
    B -->|DRM| D[DrmOutput作成]
    C --> E[LinuxFramebufferPlatform.Initialize]
    D --> E
    E --> F{GPU対応?}
    F -->|Yes| G[IGlOutputBackend → IPlatformGraphics]
    F -->|No| H[Softwareレンダリング]
    G --> I[Compositor作成]
    H --> I
    I --> J[サービス登録]
    J --> K[LinuxFramebufferLifetime作成]
    K --> L{入力バックエンド}
    L -->|AVALONIA_USE_EVDEV=1| M[EvDevBackend]
    L -->|デフォルト| N[LibInputBackend]
    M --> O[EmbeddableControlRoot作成]
    N --> O
    O --> P[アプリケーション実行]
    P --> Q{終了シグナル?}
    Q -->|Yes| R[Shutdown]
    Q -->|No| P
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-98-01 | 入力バックエンド選択 | AVALONIA_USE_EVDEV=1でEvDev使用、それ以外はlibinput | 起動時 |
| BR-98-02 | シングルビューライフタイム | ISingleViewApplicationLifetimeを実装 | 常時 |
| BR-98-03 | フレームバッファフォーマット | FbDevOutputOptionsで指定可能 | fbdev使用時 |
| BR-98-04 | スケーリング適用 | Scalingプロパティでスケール係数設定 | 常時 |
| BR-98-05 | フォーカス管理 | シングルスコープでフォーカス管理 | 常時 |

### 計算ロジック

スケーリングは出力バックエンドのScalingプロパティで設定され、FramebufferToplevelImplで適用されます。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 権限エラー | IOException | デバイスアクセス権限なし | videoグループ/root権限 |
| デバイス未発見 | FileNotFoundException | フレームバッファ未検出 | デバイスパス確認 |

### リトライ仕様

エラー発生時のリトライは行いません。

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

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

## パフォーマンス要件

- ShouldRenderOnUIThreadオプションでシングルコア最適化
- Fpsオプションでフレームレート制御

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

- デバイスファイルへの適切なアクセス権限設定
- 入力デバイスへのアクセス制御

## 備考

組み込み環境向けの軽量プラットフォームとして設計されており、マルチウィンドウはサポートされません。

---

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

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

### 推奨読解順序

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

まず、出力バックエンドと入力バックエンドのインターフェースを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | IOutputBackend.cs | `src/Linux/Avalonia.LinuxFramebuffer/Output/IOutputBackend.cs` | 出力インターフェース |
| 1-2 | IInputBackend.cs | `src/Linux/Avalonia.LinuxFramebuffer/Input/IInputBackend.cs` | 入力インターフェース |
| 1-3 | LinuxFramebufferPlatformOptions.cs | `src/Linux/Avalonia.LinuxFramebuffer/LinuxFramebufferPlatformOptions.cs` | オプション定義 |

**読解のコツ**: IOutputBackendとIGlOutputBackendの関係、入力バックエンドの抽象化を確認してください。

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

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

**主要処理フロー**:
1. **79-87行目**: Initialize() - プラットフォーム初期化
2. **54-76行目**: Initialize(内部) - サービス登録
3. **90-175行目**: LinuxFramebufferLifetime - ライフサイクル管理
4. **154-174行目**: EnsureTopLevel - TopLevel作成

#### Step 3: 出力バックエンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | FbdevOutput.cs | `src/Linux/Avalonia.LinuxFramebuffer/Output/FbdevOutput.cs` | フレームバッファ出力 |
| 3-2 | DrmOutput.cs | `src/Linux/Avalonia.LinuxFramebuffer/Output/DrmOutput.cs` | DRM出力 |

#### Step 4: 入力バックエンドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | LibInputBackend.cs | `src/Linux/Avalonia.LinuxFramebuffer/Input/LibInput/LibInputBackend.cs` | libinput入力 |
| 4-2 | EvDevBackend.cs | `src/Linux/Avalonia.LinuxFramebuffer/Input/EvDev/EvDevBackend.cs` | EvDev入力 |

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

```
LinuxFramebufferPlatformExtensions
    │
    ├─ StartLinuxFbDev()
    │      └─ FbdevOutput作成
    │
    ├─ StartLinuxDrm()
    │      └─ DrmOutput作成
    │
    └─ StartLinuxDirect()
           └─ LinuxFramebufferPlatform.Initialize()
                  │
                  ├─ サービス登録
                  │      ├─ EpollDispatcherImpl
                  │      ├─ IRenderTimer
                  │      └─ Compositor
                  │
                  └─ LinuxFramebufferLifetime
                         ├─ EnsureTopLevel()
                         │      ├─ IInputBackend選択
                         │      ├─ FramebufferToplevelImpl
                         │      └─ EmbeddableControlRoot
                         │
                         └─ Run() / Shutdown()
```

### データフロー図

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

IOutputBackend ────────▶ LinuxFramebufferPlatform ───▶ 画面描画
         │                      │
         │                      ├─ FramebufferToplevelImpl
         │                      │      └─ 描画処理
         │                      │
         │                      └─ EmbeddableControlRoot
         │                             └─ UI表示

IInputBackend ─────────▶ 入力イベント処理
         │                      │
         ├─ LibInputBackend     ├─ ポインター入力
         └─ EvDevBackend        └─ キーボード入力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| LinuxFramebufferPlatform.cs | `src/Linux/Avalonia.LinuxFramebuffer/LinuxFramebufferPlatform.cs` | ソース | メインプラットフォーム |
| LinuxFramebufferPlatformOptions.cs | `src/Linux/Avalonia.LinuxFramebuffer/LinuxFramebufferPlatformOptions.cs` | ソース | オプション |
| FramebufferToplevelImpl.cs | `src/Linux/Avalonia.LinuxFramebuffer/FramebufferToplevelImpl.cs` | ソース | トップレベル実装 |
| EpollDispatcherImpl.cs | `src/Linux/Avalonia.LinuxFramebuffer/EpollDispatcherImpl.cs` | ソース | イベントループ |
| IOutputBackend.cs | `src/Linux/Avalonia.LinuxFramebuffer/Output/IOutputBackend.cs` | ソース | 出力インターフェース |
| FbdevOutput.cs | `src/Linux/Avalonia.LinuxFramebuffer/Output/FbdevOutput.cs` | ソース | fbdev出力 |
| DrmOutput.cs | `src/Linux/Avalonia.LinuxFramebuffer/Output/DrmOutput.cs` | ソース | DRM出力 |
| IInputBackend.cs | `src/Linux/Avalonia.LinuxFramebuffer/Input/IInputBackend.cs` | ソース | 入力インターフェース |
| LibInputBackend.cs | `src/Linux/Avalonia.LinuxFramebuffer/Input/LibInput/LibInputBackend.cs` | ソース | libinput入力 |
| EvDevBackend.cs | `src/Linux/Avalonia.LinuxFramebuffer/Input/EvDev/EvDevBackend.cs` | ソース | EvDev入力 |
| DrmBindings.cs | `src/Linux/Avalonia.LinuxFramebuffer/Output/DrmBindings.cs` | ソース | DRM P/Invoke |
| NativeUnsafeMethods.cs | `src/Linux/Avalonia.LinuxFramebuffer/NativeUnsafeMethods.cs` | ソース | ネイティブメソッド |
