# 機能設計書 274-imgui_freetype

## 概要

本ドキュメントは、Dear ImGuiのFreeTypeフォントレンダラー（imgui_freetype）の機能設計について記述する。stb_truetypeに代わるフォントレンダリングバックエンドとして、FreeTypeライブラリを使用した高品質なフォント描画を提供する。

### 本機能の処理概要

FreeTypeライブラリを使用してフォントグリフをラスタライズし、Dear ImGuiのフォントアトラスに描画する機能を提供する。stb_truetype標準レンダラーの代替として、より高品質なヒンティングとレンダリングオプションを提供する。

**業務上の目的・背景**：高品質なフォントレンダリングが必要なアプリケーションにおいて、FreeTypeの豊富なヒンティングオプションとレンダリング品質を活用する。特に小さいフォントサイズでの可読性向上、カラーフォント（絵文字）のサポート、SVGフォントへの対応など、stb_truetypeでは難しい要件に対応する。

**機能の利用シーン**：プロフェッショナルなUIツール、テキストエディタ、ローカライズされたアプリケーション（特にCJKフォント）、絵文字を使用するチャットアプリケーションなどでの使用が想定される。フォント品質が重要なデスクトップアプリケーションに最適。

**主要な処理内容**：
1. FreeTypeライブラリの初期化と終了
2. フォントファイルの読み込みとFT_Face作成
3. ヒンティングフラグに基づくグリフ読み込み設定
4. グリフメトリクスの計算（Ascent、Descent等）
5. グリフのラスタライズとビットマップ生成
6. カラーグリフ、SVGグリフ（LunaSVG/PlutoSVG）のサポート

**関連システム・外部連携**：FreeTypeライブラリ（必須）、LunaSVG（オプション、SVGフォント用）、PlutoSVG（オプション、SVGフォント用）

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | Font Atlas | 主機能 | フォントアトラスの構築に使用 |

## 機能種別

フォントレンダリング / フォントローダー実装

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| FontData | void* | Yes | フォントファイルデータ | ImFontConfig経由 |
| FontDataSize | int | Yes | フォントデータサイズ | ImFontConfig経由 |
| FontNo | int | No | フォントインデックス（TTCファイル用） | デフォルト0 |
| FontLoaderFlags | unsigned int | No | ヒンティング/スタイルフラグ | ImFontConfig/ImFontAtlas経由 |
| SizePixels | float | Yes | フォントサイズ | ImFontConfig経由 |
| RasterizerDensity | float | No | ラスタライズ密度（高DPI対応） | デフォルト1.0 |

### 入力データソース

- ImFontAtlas::AddFont系関数経由で追加されるフォントデータ
- ImFontConfig構造体のフォント設定
- ImFontAtlas::FontLoaderFlagsのグローバル設定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| グリフビットマップ | RGBA32 | ラスタライズされたグリフ画像 |
| グリフメトリクス | ImFontGlyph | 位置、サイズ、アドバンス幅 |
| フォントメトリクス | float | Ascent、Descent |

### 出力先

ImFontAtlasのテクスチャ領域

## 処理フロー

### 処理シーケンス

```
1. LoaderInit: FreeTypeライブラリ初期化
   └─ FT_New_Library、FT_Add_Default_Modules
   └─ SVGフック設定（オプション）
2. FontSrcInit: フォントソース初期化
   └─ FT_New_Memory_Face、FT_Select_Charmap
   └─ ロードフラグ変換（ユーザーフラグ→FT_LOAD_*）
3. FontBakedInit: ベイクサイズ初期化
   └─ FT_New_Size、FT_Activate_Size
   └─ FT_Request_Size（サイズ設定）
   └─ メトリクス計算（Ascent/Descent）
4. FontBakedLoadGlyph: グリフ読み込み
   a. FT_Get_Char_Index（グリフインデックス取得）
   b. FT_Load_Glyph（グリフ読み込み）
   c. FT_Render_Glyph（ラスタライズ）
   d. BlitGlyph（RGBA32変換）
   e. フォントアトラスへの登録
5. FontSrcDestroy / LoaderShutdown: クリーンアップ
```

### フローチャート

```mermaid
flowchart TD
    A[LoaderInit] --> B[FT_New_Library]
    B --> C[FT_Add_Default_Modules]
    C --> D{SVGサポート?}
    D -->|Yes| E[SVGフック設定]
    D -->|No| F[FontSrcInit]
    E --> F
    F --> G[FT_New_Memory_Face]
    G --> H[ロードフラグ変換]
    H --> I[FontBakedInit]
    I --> J[FT_New_Size]
    J --> K[FT_Request_Size]
    K --> L[メトリクス計算]
    L --> M[FontBakedLoadGlyph]
    M --> N[FT_Get_Char_Index]
    N --> O{グリフ存在?}
    O -->|No| P[false返却]
    O -->|Yes| Q[FT_Load_Glyph]
    Q --> R{Bold/Oblique?}
    R -->|Yes| S[FT_GlyphSlot_Embolden/Oblique]
    R -->|No| T[FT_Render_Glyph]
    S --> T
    T --> U[BlitGlyph - RGBA32変換]
    U --> V[フォントアトラス登録]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-274-01 | ヒンティングモード | LightHinting/MonoHinting/NoHintingを選択可能 | FontLoaderFlags設定時 |
| BR-274-02 | スタイル合成 | Bold/Obliqueを人工的に生成可能 | FontLoaderFlags設定時 |
| BR-274-03 | カラーグリフ | LoadColorフラグでカラー絵文字サポート | FT 2.10+必要 |
| BR-274-04 | SVGサポート | PlutoSVG/LunaSVGでSVGフォント対応 | FT 2.12+必要 |

### 計算ロジック

- グリフオフセット: `X0/Y0 = bitmap_left/top + font_offset + ascent`
- スケール: `scale = 1.0f / (rasterizer_density * extra_size_scale)`
- FT座標変換: `FT_CEIL(X) = ((X + 63) & -64) / 64`

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

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FT_Err_* | FreeTypeエラー | FT_New_Memory_Face失敗 | false返却 |
| - | アサーション | SVGグリフでSVGサポート無効 | プリプロセッサ定義追加 |
| - | アサーション | テクスチャパック失敗 | メモリ/サイズ確認 |

### リトライ仕様

リトライ処理なし。エラー時はfalse返却。

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

該当なし

## パフォーマンス要件

- グリフはオンデマンドでラスタライズ
- FT_Sizeを再利用してサイズ切り替えを高速化
- メモリアロケータのカスタマイズ可能

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

- フォントファイルはFreeTypeライブラリで解析
- カスタムメモリアロケータを設定可能

## 備考

- `#define IMGUI_ENABLE_FREETYPE` で自動有効化
- オーバーサンプリング（OversampleH/V）は未サポート（ヒンティングで代替）
- ガンマ補正は別途sRGB変換が必要

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | imgui_freetype.h | `misc/freetype/imgui_freetype.h` | ローダーフラグ定義（29-54行目） |
| 1-2 | imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | Data構造体（145-150行目）、FontSrcData構造体（153-166行目）、FontSrcBakedData構造体（169-173行目） |

**読解のコツ**: 3階層のデータ構造（Atlas→FontSrc→FontBaked）を理解することが重要。

#### Step 2: ローダーフラグを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | imgui_freetype.h | `misc/freetype/imgui_freetype.h` | ImGuiFreeTypeLoaderFlags_列挙（29-40行目） |
| 2-2 | imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | フラグ変換ロジック（186-204行目） |

**主要フラグ**:
- **NoHinting**: FT_LOAD_NO_HINTING
- **LightHinting**: FT_LOAD_TARGET_LIGHT
- **MonoHinting**: FT_LOAD_TARGET_MONO
- **Bold**: FT_GlyphSlot_Embolden
- **Oblique**: FT_GlyphSlot_Oblique
- **LoadColor**: FT_LOAD_COLOR

#### Step 3: ライブラリ初期化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | LoaderInit関数（343-381行目） |
| 3-2 | imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | メモリアロケータ関数（310-341行目） |

**主要処理フロー**:
- **349-352行目**: カスタムメモリマネージャー設定
- **355-360行目**: FT_New_Library、FT_Add_Default_Modules
- **365-375行目**: SVGフック設定（LunaSVG/PlutoSVG）

#### Step 4: グリフ読み込みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | FontBakedLoadGlyph関数（475-559行目） |
| 4-2 | imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | LoadGlyph関数（218-257行目） |
| 4-3 | imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | BlitGlyph関数（259-307行目） |

**主要処理フロー**:
- **478-480行目**: FT_Get_Char_Indexでグリフインデックス取得
- **482-488行目**: FT_Activate_Size（サイズ切り替え）
- **490-492行目**: グリフ読み込み
- **508-512行目**: FT_Render_Glyph
- **537行目**: BlitGlyph呼び出し
- **556行目**: ImFontAtlasBakedSetFontGlyphBitmap

#### Step 5: ビットマップ変換を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | BlitGlyph関数（259-307行目） |

**主要処理フロー**:
- **269-274行目**: FT_PIXEL_MODE_GRAY（グレースケール→RGBA32）
- **276-288行目**: FT_PIXEL_MODE_MONO（1bit→RGBA32）
- **291-302行目**: FT_PIXEL_MODE_BGRA（カラー絵文字、プリマルチプライドアルファ変換）

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

```
ImGuiFreeType::GetFontLoader
    └─ ImFontLoader構造体を返す

ImGui_ImplFreeType_LoaderInit (atlas)
    ├─ IM_NEW(ImGui_ImplFreeType_Data)
    ├─ FT_New_Library
    ├─ FT_Add_Default_Modules
    └─ FT_Property_Set (SVGフック設定)

ImGui_ImplFreeType_FontSrcInit (atlas, src)
    ├─ IM_NEW(ImGui_ImplFreeType_FontSrcData)
    └─ InitFont
           ├─ FT_New_Memory_Face
           ├─ FT_Select_Charmap
           └─ ロードフラグ変換

ImGui_ImplFreeType_FontBakedInit (atlas, src, baked, loader_data)
    ├─ FT_New_Size
    ├─ FT_Activate_Size
    └─ FT_Request_Size

ImGui_ImplFreeType_FontBakedLoadGlyph (atlas, src, baked, loader_data, codepoint, out_glyph, out_advance_x)
    ├─ FT_Get_Char_Index
    ├─ ImGui_ImplFreeType_LoadGlyph
    │      ├─ FT_Load_Glyph
    │      ├─ FT_GlyphSlot_Embolden (オプション)
    │      └─ FT_GlyphSlot_Oblique (オプション)
    ├─ FT_Render_Glyph
    ├─ ImGui_ImplFreeType_BlitGlyph
    │      └─ ピクセル形式変換
    ├─ ImFontAtlasPackAddRect
    └─ ImFontAtlasBakedSetFontGlyphBitmap
```

### データフロー図

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

FontData ────────────▶ FT_New_Memory_Face ──────▶ FT_Face
  │                                                  │
  └─ FontConfig           ┌──────────────────────────┘
       │                  │
       ▼                  ▼
  FontLoaderFlags    FT_Load_Glyph ──────────▶ FT_GlyphSlot
       │                  │                         │
       └─ FT_LOAD_*       │                         ▼
           フラグ          │                    FT_Render_Glyph
                          │                         │
                          │                         ▼
                          │                    FT_Bitmap
                          │                         │
                          │                         ▼
                          │                    BlitGlyph
                          │                         │
                          │                         ▼
                          └────────────────▶ RGBA32ピクセル
                                                    │
                                                    ▼
                                           ImFontAtlas テクスチャ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| imgui_freetype.h | `misc/freetype/imgui_freetype.h` | ヘッダー | 公開API、フラグ定義 |
| imgui_freetype.cpp | `misc/freetype/imgui_freetype.cpp` | ソース | FreeTypeローダー実装 |
| imgui.h | `imgui.h` | ヘッダー | ImGui コアAPI |
| imgui_internal.h | `imgui_internal.h` | ヘッダー | 内部API（フォントアトラス構築） |
| ft2build.h | (外部ライブラリ) | ヘッダー | FreeType API |
| lunasvg.h | (外部ライブラリ、オプション) | ヘッダー | LunaSVG API |
| plutosvg.h | (外部ライブラリ、オプション) | ヘッダー | PlutoSVG API |
