# 機能設計書 17-合成スタイル

## 概要

本ドキュメントは、Ghosttyの合成スタイル機能の設計について記述する。フォントに存在しないスタイル（太字、斜体）を合成して表示する機能である。

### 本機能の処理概要

**業務上の目的・背景**：
多くのフォントは複数のスタイル（Regular、Bold、Italic、Bold Italic）を持つが、一部のフォントはRegularスタイルのみを提供している。ターミナルアプリケーションは太字や斜体のテキストを表示する必要があるため、フォントにそのスタイルが存在しない場合は合成（synthetic）スタイルを生成する必要がある。本機能は、FreeTypeの変換機能を使用して太字化や斜体化を実現する。

**機能の利用シーン**：
- 太字スタイルを持たないフォントで太字テキストを表示
- 斜体スタイルを持たないフォントで斜体テキストを表示
- Bold Italicが存在しない場合の合成
- ユーザー設定で合成を無効化

**主要な処理内容**：
1. フォントコレクションでスタイル欠如を検出
2. 設定に基づく合成可否の判定
3. syntheticBold関数による太字フェイス生成
4. syntheticItalic関数による斜体フェイス生成
5. 合成フェイスのコレクションへの追加
6. レンダリング時の合成フラグに基づく変換適用

**関連システム・外部連携**：
- FreeType（フォント変換機能）
- フォントコレクション（スタイル管理）
- 設定システム（font-synthetic-style設定）

**権限による制御**：
特になし。設定で各スタイルの合成を個別に無効化可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | メインターミナルウィンドウ | 主画面 | 合成スタイルテキストの表示 |

## 機能種別

フォント処理 / スタイル変換

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| synthetic_config | FontSyntheticStyle | Yes | 合成スタイル設定 | 有効な設定 |
| entry | *Entry | Yes | 元となるフォントエントリ | ロード済みフェイス |
| opts | Options | Yes | フェイスオプション | 有効なオプション |

### 入力データソース

- 設定ファイル（font-synthetic-style設定）
- フォントコレクションのエントリ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| face | Face | 合成スタイルが適用されたフォントフェイス |
| synthetic.italic | bool | 合成斜体フラグ |
| synthetic.bold | bool | 合成太字フラグ |

### 出力先

フォントコレクション（italic/bold/bold_italicスロット）

## 処理フロー

### 処理シーケンス

```
1. スタイル欠如検出
   └─ regularのみ存在し、bold/italicが空の場合を検出
2. 設定確認
   └─ synthetic_configで合成が有効かチェック
3. 合成フェイス生成
   └─ syntheticBold/syntheticItalicを呼び出し
4. フラグ設定
   └─ face.synthetic.bold/italicをtrueに設定
5. コレクションへ追加
   └─ 対応するスタイルのリストに追加
6. レンダリング時変換
   └─ FreeTypeのembolden/obliqueを適用
```

### フローチャート

```mermaid
flowchart TD
    A[コレクション構築] --> B{italicスタイルあり?}
    B -->|Yes| C[そのまま使用]
    B -->|No| D{synthetic italic有効?}
    D -->|No| E[警告ログ]
    D -->|Yes| F[syntheticItalic生成]
    F --> G[コレクションに追加]

    A --> H{boldスタイルあり?}
    H -->|Yes| I[そのまま使用]
    H -->|No| J{synthetic bold有効?}
    J -->|No| K[警告ログ]
    J -->|Yes| L[syntheticBold生成]
    L --> M[コレクションに追加]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Bold Italic優先順位 | bold+italicからの合成、italic+boldからの合成の順で試行 | bold_italicが欠如 |
| BR-02 | バックエンド依存 | 合成機能はFreeTypeバックエンドでのみ利用可能 | FreeType使用時 |
| BR-03 | 個別無効化 | italic, bold, bold-italicを個別に無効化可能 | 設定時 |

### 計算ロジック

- 合成斜体: FreeTypeの `oblique` 変換（12度の傾斜）
- 合成太字: FreeTypeの `embolden` 変換（ストローク太さの増加）

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| SyntheticBoldUnavailable | 未対応 | バックエンドが合成太字未サポート | スタイルなしで継続 |
| SyntheticItalicUnavailable | 未対応 | バックエンドが合成斜体未サポート | スタイルなしで継続 |

### リトライ仕様

リトライなし。エラー時は該当スタイルを使用しない。

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

該当なし

## パフォーマンス要件

- 合成フェイス生成は初回ロード時のみ
- レンダリング時の変換はGPUではなくCPUで実行
- 合成スタイルは元のフォントキャッシュを共有

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

特になし

## 備考

- CoreTextバックエンドでは別の実装が必要
- 一部フォントでは合成結果が美しくない場合がある

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | freetype.zig | `src/font/face/freetype.zig` | Face構造体のsyntheticフィールド（56-59行目） |
| 1-2 | Config.zig | `src/config/Config.zig` | FontSyntheticStyle設定構造体 |

**読解のコツ**: Face.syntheticはpacked structでitalicとboldフラグを持つ。この値がtrueの場合、レンダリング時に変換が適用される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Collection.zig | `src/font/Collection.zig` | synthetic_configフィールド（323行目） |
| 2-2 | Collection.zig | `src/font/Collection.zig` | italicスタイル合成ロジック（374-397行目） |
| 2-3 | Collection.zig | `src/font/Collection.zig` | boldスタイル合成ロジック（404-421行目） |

**主要処理フロー**:
1. **374-380行目**: italicスタイルが空かつ設定で有効かをチェック
2. **386-397行目**: syntheticItalicを呼び出し、成功すればリストに追加
3. **404-421行目**: boldスタイルについて同様の処理

#### Step 3: 合成フェイス生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Collection.zig | `src/font/Collection.zig` | syntheticBold関数（469-492行目） |
| 3-2 | Collection.zig | `src/font/Collection.zig` | syntheticItalic関数（494-512行目） |

**主要処理フロー**:
- **469-471行目**: バックエンドがsyntheticBoldをサポートしているかチェック
- **483行目**: Face.syntheticBoldを呼び出して新しいフェイスを生成
- **508行目**: Face.syntheticItalicを呼び出して新しいフェイスを生成

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

```
Collection初期化
    │
    ├─ [italicスタイル欠如時]
    │      └─ syntheticItalic()
    │             └─ Face.syntheticItalic()
    │                    └─ synthetic.italic = true設定
    │
    └─ [boldスタイル欠如時]
           └─ syntheticBold()
                  └─ Face.syntheticBold()
                         └─ synthetic.bold = true設定

レンダリング時
    │
    └─ [synthetic.italic/bold == true]
           └─ FreeType変換適用
```

### データフロー図

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

Regular Face ──────▶ syntheticItalic() ────▶ Italic Face
        │                                      (synthetic.italic=true)
        │
        └──────────▶ syntheticBold() ──────▶ Bold Face
                                               (synthetic.bold=true)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Collection.zig | `src/font/Collection.zig` | ソース | 合成スタイル管理 |
| freetype.zig | `src/font/face/freetype.zig` | ソース | FreeType合成実装 |
| coretext.zig | `src/font/face/coretext.zig` | ソース | CoreText合成実装 |
| Config.zig | `src/config/Config.zig` | ソース | 合成スタイル設定定義 |
