# 機能設計書 80-背景画像

## 概要

本ドキュメントは、Ghosttyターミナルエミュレータにおける背景画像機能の設計について記載する。この機能により、ターミナルウィンドウの背景にPNGまたはJPEG画像を表示し、カスタマイズされた視覚的な作業環境を実現できる。

### 本機能の処理概要

**業務上の目的・背景**：
背景画像機能は、ターミナルをパーソナライズし、より魅力的な作業環境を提供する。企業ロゴ、壁紙、アートワークなどを背景として設定することで、ユーザーは自分好みの端末環境を構築できる。また、背景透過機能と組み合わせることで、より洗練された視覚効果を実現できる。

**機能の利用シーン**：
- デスクトップのカスタマイズ・パーソナライズ
- 企業ブランディングのためのロゴ表示
- 動機付けや美観向上のためのアートワーク表示
- 透過背景と組み合わせたグラデーション効果

**主要な処理内容**：
1. `background-image`設定から画像パスを取得
2. PNG/JPEG画像のロードとデコード
3. レンダラーへのテクスチャ転送
4. 背景画像の位置、フィット、繰り返し設定の適用
5. `background-opacity`との連携

**関連システム・外部連携**：
- wuffs: PNG/JPEGデコーダーライブラリ
- Metal / OpenGL: GPUテクスチャ管理
- ファイルシステム: 画像ファイルの読み込み

**権限による制御**：
- 特に権限制御は不要（ファイルシステムアクセス権のみ）

## 関連画面

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

## 機能種別

表示設定 / レンダリング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| background-image | ?Path | No | 画像ファイルパス | PNG/JPEG形式 |
| background-image-opacity | f32 | No | 画像不透明度（デフォルト1.0） | 0.0以上 |
| background-image-position | BackgroundImagePosition | No | 画像位置（デフォルトcenter） | enum値 |
| background-image-fit | BackgroundImageFit | No | フィット方法（デフォルトcontain） | enum値 |
| background-image-repeat | bool | No | 繰り返し表示（デフォルトfalse） | true/false |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 背景テクスチャ | GPU Texture | デコードされた画像データ |
| レンダリング結果 | - | 背景画像付きのターミナル表示 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 設定読み込み
   └─ Config.zig から background-image パスを取得
2. 画像ファイル読み込み
   └─ ファイルシステムから画像データを取得
3. 画像デコード
   └─ wuffsライブラリでPNG/JPEGをデコード
4. テクスチャ生成
   └─ GPU用テクスチャとしてアップロード
5. フレーム描画時
   └─ 位置、フィット、繰り返し設定に従って描画
```

### フローチャート

```mermaid
flowchart TD
    A[設定ファイル読み込み] --> B{background-image設定あり?}
    B -->|No| C[背景画像なしで描画]
    B -->|Yes| D[画像ファイル読み込み]
    D --> E{読み込み成功?}
    E -->|No| F[エラーログ / 背景画像なし]
    E -->|Yes| G[wuffsでデコード]
    G --> H{デコード成功?}
    H -->|No| F
    H -->|Yes| I[GPUテクスチャ生成]
    I --> J[位置・フィット設定適用]
    J --> K[背景描画]
    K --> L{繰り返し設定?}
    L -->|Yes| M[タイル描画]
    L -->|No| N[単一描画]
    M --> O[レンダリング完了]
    N --> O
    C --> O
    F --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-80-1 | 対応形式 | PNG/JPEG形式のみ対応 | 常時 |
| BR-80-2 | ターミナル単位 | 背景画像はサーフェス単位で設定 | 常時 |
| BR-80-3 | VRAMデュプリケーション | 現時点で画像はターミナルごとにVRAMに複製 | 常時 |
| BR-80-4 | 透過度連携 | 画像透過度はbackground-opacityと相対的 | 常時 |
| BR-80-5 | 位置指定 | 9種類の位置から選択可能 | 常時 |

### 計算ロジック

画像最終透過度:
```
final_opacity = background_image_opacity * background_opacity
```

フィット計算（contain）:
```
scale = min(window_width / image_width, window_height / image_height)
```

フィット計算（cover）:
```
scale = max(window_width / image_width, window_height / image_height)
```

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル不在 | 指定パスに画像がない | エラーログ、背景画像なしで続行 |
| - | 形式不正 | PNG/JPEG以外の形式 | エラーログ、背景画像なしで続行 |
| - | デコード失敗 | 破損した画像ファイル | エラーログ、背景画像なしで続行 |
| - | VRAM不足 | 大きすぎる画像 | エラーログ、背景画像なしで続行 |

### リトライ仕様

リトライは行わない。設定リロード時に再試行可能。

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

該当なし

## パフォーマンス要件

- 画像ロードは初期化時に1回のみ
- 大きな画像はVRAM使用量に注意
- 複数ターミナルで同じ画像を使用してもVRAMは共有されない（将来改善予定）

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

- 画像ファイルはユーザー指定のパスから読み込み
- 悪意のある画像ファイルによる脆弱性はwuffsライブラリに依存

## 備考

- 現在は静止画のみ対応（GIF、動画は非対応）
- 複数ターミナル（スプリット）では画像が繰り返される
- 画像共有は将来のバージョンで対応予定

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.zig | `src/config/Config.zig` | background-image設定（615行目） |
| 1-2 | Config.zig | `src/config/Config.zig` | background-image-opacity（636行目） |
| 1-3 | Config.zig | `src/config/Config.zig` | background-image-position（654行目） |
| 1-4 | Config.zig | `src/config/Config.zig` | background-image-fit（684行目） |
| 1-5 | Config.zig | `src/config/Config.zig` | background-image-repeat（695行目） |

**読解のコツ**: 設定は5つの項目で構成。Path型は設定パス解決を行う特殊型。

#### Step 2: 画像処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | image.zig | `src/renderer/image.zig` | 画像読み込みとデコード処理 |
| 2-2 | generic.zig | `src/renderer/generic.zig` | レンダラーでの画像テクスチャ管理 |

**主要処理フロー**:
- wuffsライブラリを使用したPNG/JPEGデコード
- テクスチャ生成とGPUアップロード

#### Step 3: レンダリング処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | generic.zig | `src/renderer/generic.zig` | 背景画像の描画処理 |

**主要処理フロー**:
- 位置、フィット、繰り返し設定の適用
- 透過度との合成

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

```
Config.zig (設定読み込み)
    │
    ├─ background-image: ?Path
    ├─ background-image-opacity: f32
    ├─ background-image-position: BackgroundImagePosition
    ├─ background-image-fit: BackgroundImageFit
    └─ background-image-repeat: bool
           │
           └─ Renderer 初期化
                  │
                  ├─ image.zig (画像ロード)
                  │      │
                  │      └─ wuffs (PNG/JPEGデコード)
                  │
                  └─ テクスチャ生成
                         │
                         └─ フレーム描画
                                │
                                ├─ 位置計算
                                ├─ フィット計算
                                ├─ 透過度適用
                                └─ [repeat] タイル描画
```

### データフロー図

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

設定ファイル ───▶ background-image パス
                        │
                        ▼
              ファイルシステム読み込み
                        │
                        ▼
               wuffs デコーダー
                        │
                        ▼
              GPU テクスチャ生成
                        │
                        ▼
              フレーム描画時
                        │
          ┌─────────────┼─────────────┐
          │             │             │
     位置計算      フィット計算    透過度計算
          │             │             │
          └─────────────┴─────────────┘
                        │
                        ▼
              背景画像レンダリング
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Config.zig | `src/config/Config.zig` | ソース | 背景画像関連設定定義 |
| generic.zig | `src/renderer/generic.zig` | ソース | レンダラーでの画像処理 |
| image.zig | `src/renderer/image.zig` | ソース | 画像ロード・デコード |
| path.zig | `src/config/path.zig` | ソース | Path型定義 |
