# 機能設計書 81-背景ぼかし

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける背景ぼかし（Background Blur）機能の設計仕様を記載する。

### 本機能の処理概要

背景ぼかし機能は、ターミナルウィンドウの背景に対してブラーエフェクト（ぼかし効果）を適用し、背後のウィンドウやデスクトップをぼかして表示する視覚的効果を提供する機能である。

**業務上の目的・背景**：
ターミナルの背景透過（background-opacity）機能と組み合わせることで、ユーザーは背後のコンテンツを完全に見えなくすることなく、ターミナルの可読性を維持しながら視覚的に美しいデスクトップ環境を構築できる。特にプレゼンテーションや画面共有時に、プロフェッショナルな外観を提供する。

**機能の利用シーン**：
- 半透明のターミナルウィンドウを使用する際に、背後のコンテンツがテキストの可読性を妨げないようにする場合
- デスクトップの美観を重視するユーザーが、モダンなガラス風の外観を求める場合
- macOS 26.0以降でネイティブのガラスエフェクトを使用したい場合

**主要な処理内容**：
1. 設定ファイルから`background-blur`の値を読み取る
2. プラットフォーム固有のブラーAPIを呼び出す（macOS: CoreAnimation、Linux/Wayland: KDE Blur Manager）
3. レンダラーに対してブラー状態を通知する
4. ウィンドウコンポジターと連携してブラーエフェクトを適用する

**関連システム・外部連携**：
- macOS: CoreAnimationフレームワーク、NSWindow API
- Linux/Wayland: org.kde.kwin.blur Wayland Protocol
- Linux/X11: KDE Plasma Blur Protocol

**権限による制御**：
特に権限による制御はない。設定値に基づいてすべてのユーザーが利用可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | 背景ぼかしエフェクトの表示対象 |
| 2 | クイックターミナル | 主画面 | 背景ぼかしエフェクトの表示対象 |

## 機能種別

表示処理 / 視覚効果

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| background-blur | BackgroundBlur | No | ブラーの有効/無効およびぼかし強度 | false, true, macos-glass-regular, macos-glass-clear, または0-255の整数 |

### 入力データソース

設定ファイル（`~/.config/ghostty/config`等）から読み込む。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ブラーエフェクト | 視覚効果 | ウィンドウ背景に適用されるぼかし効果 |

### 出力先

ウィンドウコンポジター（macOS: WindowServer、Linux: KWin等）

## 処理フロー

### 処理シーケンス

```
1. 設定値の読み取り
   └─ Config.zigでbackground-blurの値をパース
2. プラットフォーム判定
   └─ macOS/Linux(Wayland)/Linux(X11)を判定
3. ブラーマネージャーの初期化
   └─ macOS: ghostty_set_window_background_blur APIを呼び出し
   └─ Linux: KDE Blur Managerプロトコルをバインド
4. ウィンドウへのブラー適用
   └─ 各プラットフォーム固有のAPIでブラーを設定
```

### フローチャート

```mermaid
flowchart TD
    A[設定読み込み] --> B{background-blur値の確認}
    B -->|false| C[ブラー無効]
    B -->|true| D[デフォルト強度20でブラー有効]
    B -->|数値| E[指定強度でブラー有効]
    B -->|macos-glass-*| F[macOSガラスエフェクト]
    D --> G{プラットフォーム判定}
    E --> G
    F --> G
    G -->|macOS| H[CoreAnimation API呼び出し]
    G -->|Linux Wayland| I[KDE Blur Manager Protocol]
    G -->|Linux X11| J[X11 Blur Protocol]
    H --> K[終了]
    I --> K
    J --> K
    C --> K
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-81-01 | 透過前提条件 | background-opacityが1未満の場合のみブラーが視覚的に有効 | 常時 |
| BR-81-02 | macOSガラス値の変換 | macOS以外でmacos-glass-*を指定した場合はtrue扱い | Linux使用時 |
| BR-81-03 | KDE Plasma制限 | KDE Plasmaではブラー強度は無視され、システム設定が適用される | KDE Plasma環境 |

### 計算ロジック

- `true`指定時: 強度20（デフォルト）
- `false`指定時: 強度0（無効）
- 数値指定時: 0-255の範囲でクランプ

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

本機能はデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 警告 | 非対応デスクトップ環境 | ログ出力のみ、機能は無効化 |
| - | 警告 | Waylandプロトコル未サポート | ログ出力、ブラーなしで継続 |

### リトライ仕様

リトライは行わない。サポートされていない環境ではブラーなしで動作を継続する。

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

該当なし。

## パフォーマンス要件

- ブラーエフェクトはGPUコンポジターで処理されるため、CPU負荷は最小限
- 高いブラー強度はGPU負荷を増加させる可能性がある

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

- 背景ぼかしにより、背後のウィンドウの内容が完全に隠れるわけではない
- 機密情報を含むウィンドウが背後にある場合は注意が必要

## 備考

- Linux環境では、KDE Plasma以外のデスクトップ環境はサードパーティプラグインが必要
- macOS 26.0以降では`macos-glass-regular`と`macos-glass-clear`でネイティブガラスエフェクトが利用可能

---

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

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

### 推奨読解順序

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

まず、ブラー設定の型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.zig | `src/config/Config.zig` | BackgroundBlur union型の定義（9447-9467行目付近） |

**読解のコツ**: `BackgroundBlur`はunion(enum)型で、false/true/macos-glass-regular/macos-glass-clear/radiusの5つの状態を持つ。

**主要処理フロー**:
- **9448-9453行目**: BackgroundBlur union型の定義（false, true, macos-glass-regular, macos-glass-clear, radius）
- **9455-9467行目**: parseCLI関数でCLI引数をパース

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

設定の読み込みと適用のエントリーポイント。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Config.zig | `src/config/Config.zig` | `@"background-blur"`フィールド（1059行目） |

**主要処理フロー**:
- **1019-1059行目**: background-blur設定のドキュメントと定義

#### Step 3: プラットフォーム固有実装を理解する

Wayland環境でのブラー実装。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | wayland.zig | `src/apprt/gtk/winproto/wayland.zig` | KDE Blur Managerの初期化 |

**主要処理フロー**:
- **28行目**: kde_blur_manager Waylandプロトコルのオプショナルポインタ
- **82-84行目**: Waylandレジストリからブラーマネージャーをバインド

#### Step 4: macOS固有実装を理解する

macOSでのブラー実装。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | embedded.zig | `src/apprt/embedded.zig` | ghostty_set_window_background_blur関数 |
| 4-2 | Ghostty.Config.swift | `macos/Sources/Ghostty/Ghostty.Config.swift` | backgroundBlurプロパティ（481-486行目） |

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

```
Config.zig (設定読み込み)
    │
    ├─ BackgroundBlur.parseCLI() (値のパース)
    │
    ├─ [macOS]
    │      └─ ghostty_set_window_background_blur()
    │             └─ Ghostty.Config.swift#backgroundBlur
    │
    └─ [Linux/Wayland]
           └─ wayland.zig
                  └─ kde_blur_manager (org.kde.kwin.blur)
```

### データフロー図

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

設定ファイル ───▶ Config.zig ───▶ BackgroundBlur値
                      │
                      ▼
              プラットフォーム判定
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
    [macOS]      [Wayland]       [X11]
        │             │             │
        ▼             ▼             ▼
CoreAnimation   KDE Blur       KDE Blur
    API         Manager        Protocol
        │             │             │
        └─────────────┴─────────────┘
                      │
                      ▼
              ウィンドウコンポジター
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Config.zig | `src/config/Config.zig` | ソース | 設定の定義とパース |
| wayland.zig | `src/apprt/gtk/winproto/wayland.zig` | ソース | Waylandブラープロトコル |
| x11.zig | `src/apprt/gtk/winproto/x11.zig` | ソース | X11ブラープロトコル |
| embedded.zig | `src/apprt/embedded.zig` | ソース | libghostty API |
| Ghostty.Config.swift | `macos/Sources/Ghostty/Ghostty.Config.swift` | ソース | macOS設定アクセサ |
| generic.zig | `src/renderer/generic.zig` | ソース | レンダラーでのブラー状態管理 |
| ghostty.h | `include/ghostty.h` | ヘッダー | C API定義 |
