# 機能設計書 79-背景透過

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける背景透過（Background Opacity）機能の設計について記載する。この機能により、ターミナルウィンドウの背景を半透明にし、背後のコンテンツを透かして表示することができる。

### 本機能の処理概要

**業務上の目的・背景**：
背景透過は、デスクトップの美観向上やマルチタスク時の視認性向上を目的とした機能である。ユーザーはターミナル越しに背後のウィンドウやデスクトップの壁紙を確認でき、コンテキストを維持しながら作業を行える。また、背景ぼかし（blur）と組み合わせることで、より洗練された視覚効果を実現できる。

**機能の利用シーン**：
- デスクトップの壁紙やウィジェットを透かして表示したい場合
- 複数ウィンドウを重ねて作業する際の視認性向上
- 美観重視のデスクトップ環境でのカスタマイズ
- 背景ぼかしと組み合わせたガラス効果の実現

**主要な処理内容**：
1. `background-opacity`設定値の読み込み
2. レンダラーでの背景アルファ値の適用
3. セル背景色への透過度適用（`background-opacity-cells`設定時）
4. 背景ぼかし効果との連携（`background-blur`設定時）

**関連システム・外部連携**：
- macOS: ウィンドウコンポジター / Glass Effect API（macOS 26.0+）
- Linux/GTK: Waylandコンポジター / KWin blur
- レンダラー（Metal / OpenGL）: シェーダーでのアルファ合成

**権限による制御**：
- 特に権限制御は不要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | 背景透過の表示 |

## 機能種別

表示設定 / レンダリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| background-opacity | f64 | No | 背景不透明度（0.0-1.0） | 範囲外はクランプ |
| background-opacity-cells | bool | No | セル背景にも透過適用 | true/false |
| background-blur | BackgroundBlur | No | 背景ぼかし設定 | false/true/整数/macos-glass-* |

### 入力データソース

- 設定ファイル（`~/.config/ghostty/config`等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| bg_color[3] | u8 | 背景色アルファ値（0-255） |
| レンダリング結果 | - | 半透明背景のターミナル表示 |

### 出力先

- ターミナルウィンドウの背景レイヤー

## 処理フロー

### 処理シーケンス

```
1. 設定読み込み
   └─ Config.zig から background-opacity 値を取得
2. DerivedConfig への設定
   └─ レンダラー用に値を変換・クランプ
3. レンダラー初期化時
   └─ bg_color[3] にアルファ値を設定
4. フレーム描画時
   └─ 背景色をアルファ付きでレンダリング
5. セル描画時（background-opacity-cells有効時）
   └─ 各セルの背景色にも透過度を適用
```

### フローチャート

```mermaid
flowchart TD
    A[設定ファイル読み込み] --> B[background-opacity 取得]
    B --> C[値のクランプ 0.0-1.0]
    C --> D[DerivedConfig.background_opacity に設定]
    D --> E[レンダラー初期化]
    E --> F[bg_color アルファ値計算]
    F --> G{macOS Glass Effect?}
    G -->|Yes| H[アルファ値を0に設定]
    G -->|No| I[計算値を使用]
    H --> J[フレーム描画]
    I --> J
    J --> K{background-opacity-cells?}
    K -->|Yes| L[セル背景にも透過適用]
    K -->|No| M[セル背景は不透明]
    L --> N[レンダリング完了]
    M --> N
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-79-1 | 値クランプ | 0.0未満は0.0に、1.0超は1.0にクランプ | 常時 |
| BR-79-2 | デフォルト完全不透明 | デフォルト値は1.0（完全不透明） | 設定なし時 |
| BR-79-3 | macOSフルスクリーン無効 | macOSネイティブフルスクリーン時は透過無効 | macOS |
| BR-79-4 | Glass Effect優先 | macOS Glass Effect使用時はアルファ0 | macOS 26.0+ |
| BR-79-5 | セル背景分離 | デフォルトでセル背景は不透明 | 常時 |

### 計算ロジック

```
bg_color_alpha = round(background_opacity * 255.0)
```

セル背景（background-opacity-cells = true時）:
```
cell_bg_alpha = round(default_alpha * background_opacity)
```

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | コンポジター非対応 | デスクトップ環境が透過非対応 | 完全不透明として動作 |

### リトライ仕様

リトライは行わない。

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

該当なし

## パフォーマンス要件

- 透過レンダリングはGPUで処理されるため、CPU負荷は最小
- 背景ぼかしと組み合わせた場合はGPU負荷が増加

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

- 背景透過により後ろのウィンドウ内容が見える可能性
- 機密情報を扱う場合は不透明度1.0を推奨

## 備考

- macOSでは設定変更にGhosttyの再起動が必要
- Linux KDE Plasmaでは個別のぼかし強度設定は無視される（システム全体設定を使用）
- toggle_background_opacityアクションで完全不透明との切り替えが可能

---

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

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

### 推奨読解順序

#### Step 1: 設定定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.zig | `src/config/Config.zig` | background-opacity設定（1001行目） |
| 1-2 | Config.zig | `src/config/Config.zig` | background-opacity-cells設定（1017行目） |
| 1-3 | Config.zig | `src/config/Config.zig` | background-blur設定（1059行目） |

**読解のコツ**: `f64`型で0.0-1.0の範囲。デフォルト1.0（完全不透明）。

#### Step 2: レンダラーでの使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | generic.zig | `src/renderer/generic.zig` | DerivedConfig構造体（548-549行目） |
| 2-2 | generic.zig | `src/renderer/generic.zig` | 設定値の変換（608-609行目） |
| 2-3 | generic.zig | `src/renderer/generic.zig` | bg_colorアルファ設定（735行目） |

**主要処理フロー**:
1. **608-609行目**: `@max(0, @min(1, config.@"background-opacity"))` でクランプ
2. **735行目**: `@intFromFloat(@round(options.config.background_opacity * 255.0))` でアルファ値計算

#### Step 3: セル背景への適用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | generic.zig | `src/renderer/generic.zig` | セル背景アルファ処理（2898-2901行目） |

**主要処理フロー**:
- **2898行目**: `if (self.config.background_opacity_cells and bg_style != null)` でチェック
- **2899-2900行目**: デフォルトアルファに`background_opacity`を乗算

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

```
Config.zig (設定読み込み)
    │
    ├─ background-opacity: f64
    ├─ background-opacity-cells: bool
    └─ background-blur: BackgroundBlur
           │
           └─ DerivedConfig (generic.zig)
                  │
                  ├─ background_opacity: f64 (クランプ済み)
                  └─ background_opacity_cells: bool
                         │
                         └─ Renderer 初期化
                                │
                                ├─ bg_color[3] = round(opacity * 255)
                                │
                                └─ フレーム描画
                                       │
                                       ├─ 背景描画 (bg_color使用)
                                       │
                                       └─ セル描画
                                              │
                                              └─ [cells有効時] セル背景にも適用
```

### データフロー図

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

設定ファイル ───▶ Config.@"background-opacity"
                        │
                        ▼
                 クランプ [0.0, 1.0]
                        │
                        ▼
               DerivedConfig.background_opacity
                        │
                        ▼
               アルファ値計算 (× 255)
                        │
                        ▼
                    bg_color[3]
                        │
              ┌─────────┴─────────┐
              │                   │
         背景描画            セル描画
              │                   │
              ▼                   ▼
         透過背景        [cells有効時] 透過セル背景
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Config.zig | `src/config/Config.zig` | ソース | background-opacity等の設定定義 |
| generic.zig | `src/renderer/generic.zig` | ソース | レンダラーでの透過処理 |
| embedded.zig | `src/apprt/embedded.zig` | ソース | libghosttyでの透過設定 |
| window.zig | `src/apprt/gtk/class/window.zig` | ソース | GTKウィンドウの透過設定 |
| BaseTerminalController.swift | `macos/Sources/Features/Terminal/BaseTerminalController.swift` | ソース | macOSウィンドウの透過設定 |
| Ghostty.Config.swift | `macos/Sources/Ghostty/Ghostty.Config.swift` | ソース | macOS設定ラッパー |
