# 通知設計書 31-RendererWarning

## 概要

本ドキュメントは、Windows Terminal におけるレンダラー警告通知（RendererWarning）の設計仕様を記述する。RendererWarning は、レンダリングエンジン（AtlasEngine）が描画処理中にエラーや警告を検出した際に発火するイベントであり、シェーダーファイルの欠落、シェーダーコンパイル失敗、フォント未検出などの問題をユーザーに通知する。

### 本通知の処理概要

RendererWarning は、レンダリングエンジンが描画処理の過程で問題を検出した場合に、HRESULT エラーコードとパラメータ情報を含む警告イベントを発火する通知機構である。

**業務上の目的・背景**：ターミナルアプリケーションの描画はユーザー体験の根幹であり、シェーダーファイルの欠落やフォントの未検出、シェーダーコンパイルエラーなど、レンダリングに関わる問題が発生した場合にユーザーへ速やかに通知する必要がある。この通知により、ユーザーは問題の原因を特定し、設定の修正やファイルの復元などの対処を行うことができる。

**通知の送信タイミング**：AtlasEngine の描画処理中に警告が検出された時点で発火する。具体的には、ピクセルシェーダーファイルが見つからない場合（ERROR_FILE_NOT_FOUND / ERROR_PATH_NOT_FOUND）、シェーダーのコンパイルに失敗した場合（D2DERR_SHADER_COMPILE_FAILED）、指定フォントが見つからない場合（DWRITE_E_NOFONT）、MacType 互換性エラー（ATLAS_ENGINE_ERROR_MAC_TYPE）、その他の HRESULT エラーが発生した場合に送信される。

**通知の受信者**：ControlCore が RendererWarning イベントを発火し、TermControl の _RendererWarning ハンドラーが受信する。最終的には RaiseNotice イベントを通じて、UI 上のダイアログとしてユーザーに表示される。

**通知内容の概要**：HRESULT エラーコードと、関連するパラメータ（シェーダーファイルパスやフォント名など）を含むエラーメッセージ。HRESULT に応じてローカライズされたメッセージ文字列に変換される。

**期待されるアクション**：ユーザーはエラーメッセージの内容に基づき、設定ファイルのシェーダーパス修正、不足しているフォントのインストール、またはシェーダーファイルの修正・復元を行う。

## 通知種別

アプリ内通知（WinRT イベント経由でダイアログ表示）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（UIスレッドへのディスパッチ） |
| 優先度 | 高（レンダリング障害に関わるため） |
| リトライ | なし（イベント発火は1回、ただしレンダラー自体がリトライ後に警告を発する） |

### 送信先決定ロジック

レンダリングエンジン（AtlasEngine）が警告コールバックを呼び出し、ControlCore の `_rendererWarning` メソッドを経由して RendererWarning イベントが発火される。TermControl がこのイベントをサブスクライブしており、UIスレッド上で RaiseNotice イベントに変換してユーザーに表示する。

## 通知テンプレート

### メール通知の場合

該当なし（アプリ内通知のため）

### 本文テンプレート

```
HRESULT 別のメッセージテンプレート:

ERROR_FILE_NOT_FOUND / ERROR_PATH_NOT_FOUND:
  "PixelShaderNotFound" リソース文字列 + パラメータ（ファイルパス）

D2DERR_SHADER_COMPILE_FAILED:
  "PixelShaderCompileFailed" リソース文字列 + パラメータ（ファイルパス）

DWRITE_E_NOFONT:
  "RendererErrorFontNotFound" リソース文字列 + パラメータ（フォント名）

ATLAS_ENGINE_ERROR_MAC_TYPE:
  "RendererErrorMacType" リソース文字列

その他:
  "RendererErrorOther" リソース文字列 + HRESULT値 + システムメッセージ + パラメータ
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| Result (HRESULT) | レンダリングエラーの HRESULT コード | AtlasEngine 警告コールバック | Yes |
| Parameter (hstring) | エラーに関連するパラメータ（ファイルパス、フォント名等） | AtlasEngine 警告コールバック | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| レンダリング処理 | AtlasEngine 描画時の警告検出 | HRESULT がエラーコードである場合 | シェーダーファイル読み込み失敗、コンパイル失敗、フォント未検出等 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| コントロール破棄済み | TermControl が既に破棄されている場合、コルーチン内の weak_ref チェックで処理がスキップされる |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[AtlasEngine 描画処理中に警告検出] --> B[SetWarningCallback 経由で _rendererWarning 呼び出し]
    B --> C[RendererWarningArgs 生成<br/>HRESULT + Parameter]
    C --> D[ControlCore.RendererWarning イベント発火]
    D --> E[TermControl._RendererWarning ハンドラー受信]
    E --> F[UIスレッドへディスパッチ<br/>co_await resume_foreground]
    F --> G{HRESULT 判定}
    G -->|FILE_NOT_FOUND| H1[PixelShaderNotFound メッセージ生成]
    G -->|SHADER_COMPILE_FAILED| H2[PixelShaderCompileFailed メッセージ生成]
    G -->|DWRITE_E_NOFONT| H3[RendererErrorFontNotFound メッセージ生成]
    G -->|MAC_TYPE| H4[RendererErrorMacType メッセージ生成]
    G -->|その他| H5[RendererErrorOther + FormatMessage メッセージ生成]
    H1 --> I[NoticeEventArgs 生成<br/>Level=Warning]
    H2 --> I
    H3 --> I
    H4 --> I
    H5 --> I
    I --> J[RaiseNotice イベント発火]
    J --> K[ユーザーにダイアログ表示]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（インメモリイベント処理のみ）

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| コントロール破棄 | UIスレッドディスパッチ時にコントロールが既に破棄されている | weak_ref チェックで co_return により処理を中断 |
| FormatMessage 失敗 | 不明な HRESULT に対して FormatMessageW がメッセージを返さない場合 | 空メッセージとして扱い、HRESULT 値のみ表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（イベント通知としてのリトライはない） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし（レンダリング警告発生頻度に依存） |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（レンダリングエラー発生時に即座に通知）

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

- パラメータにはファイルパスが含まれる可能性があるが、ローカルユーザーに対する表示のみであり、外部送信は行わない
- FormatMessageW を使用するため、システムメッセージにはローカルの言語設定が反映される

## 備考

- RendererWarning イベントは ControlCore.idl で UIスレッドから呼び出されるイベントとしてコメントされている
- TermControl のコンストラクタで、Enable より先にこのコールバックが設定される（初回描画の警告を見逃さないため）
- 最初のレンダラー障害時は自動的に D2D + WARP へフォールバックされ（RendererEnteredErrorState）、その後の障害で RendererWarning が発火する

---

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

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

### 推奨読解順序

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

まず、RendererWarningArgs の構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | EventArgs.idl | `src/cascadia/TerminalControl/EventArgs.idl` | RendererWarningArgs の IDL 定義（行98-102）。HRESULT Result と String Parameter の2プロパティ |
| 1-2 | EventArgs.h | `src/cascadia/TerminalControl/EventArgs.h` | RendererWarningArgs の C++ 実装（行148-159）。コンストラクタで HRESULT と hstring を受け取る |

**読解のコツ**: WinRT の IDL 定義がインターフェースの公開仕様を定め、.h ファイルがその実装を提供する。`WINRT_PROPERTY` マクロはプロパティのバッキングフィールドとアクセサを自動生成する。

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

AtlasEngine が警告を検出し、コールバックを通じて ControlCore に通知する起点を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | AtlasEngine の SetWarningCallback 設定（行382-384）。ラムダ経由で _rendererWarning を呼び出す |
| 2-2 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | _rendererWarning メソッド（行1945-1948）。RendererWarningArgs を生成し RendererWarning イベントを raise |

**主要処理フロー**:
1. **行382-384**: AtlasEngine に警告コールバックを設定
2. **行1945-1948**: コールバック受信、RendererWarningArgs 生成、イベント発火

#### Step 3: TermControl での受信と変換処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | _RendererWarning ハンドラー（行1306-1355）。HRESULT に応じたメッセージ文字列の生成と RaiseNotice イベントへの変換 |
| 3-2 | TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | イベント登録（行301）。_revokers.RendererWarning にサブスクリプションを設定 |

**主要処理フロー**:
- **行301**: RendererWarning イベントのサブスクライブ（コンストラクタ内）
- **行1306-1315**: UIスレッドへのディスパッチと weak_ref チェック
- **行1323-1352**: HRESULT に基づく switch 文でメッセージ文字列を生成
- **行1354-1355**: NoticeEventArgs を生成し RaiseNotice イベントを発火

#### Step 4: イベント宣言を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | RendererWarning イベント宣言（行209）。UIスレッドから呼ばれるイベントグループに属する |
| 4-2 | ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | til::typed_event 宣言（行287）。RendererWarningArgs を型引数に持つ |

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

```
AtlasEngine (描画処理中に警告検出)
    |
    +-- SetWarningCallback (ラムダ)
           |
           +-- ControlCore::_rendererWarning(HRESULT hr, zwstring_view parameter)
                  |
                  +-- RendererWarning.raise(*this, RendererWarningArgs)
                         |
                         +-- TermControl::_RendererWarning(sender, args)
                                |
                                +-- co_await resume_foreground (UIスレッド)
                                |
                                +-- switch(hr) でメッセージ生成
                                |
                                +-- RaiseNotice.raise(NoticeEventArgs{Warning, message})
```

### データフロー図

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

AtlasEngine                     ControlCore                          TermControl / UI
HRESULT + parameter ------->  _rendererWarning() -------->  _RendererWarning()
                               RendererWarningArgs生成        HRESULT解析 + メッセージ生成
                               イベント発火                     RaiseNotice イベント
                                                                  -> ダイアログ表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| EventArgs.idl | `src/cascadia/TerminalControl/EventArgs.idl` | IDL定義 | RendererWarningArgs の WinRT インターフェース定義 |
| EventArgs.h | `src/cascadia/TerminalControl/EventArgs.h` | ソース | RendererWarningArgs の C++ 実装 |
| EventArgs.cpp | `src/cascadia/TerminalControl/EventArgs.cpp` | ソース | WinRT 生成コードのインクルード |
| ControlCore.idl | `src/cascadia/TerminalControl/ControlCore.idl` | IDL定義 | RendererWarning イベントの宣言 |
| ControlCore.h | `src/cascadia/TerminalControl/ControlCore.h` | ソース | RendererWarning イベントの til::typed_event 宣言と _rendererWarning メソッド宣言 |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | 警告コールバック設定と _rendererWarning 実装 |
| TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | ソース | _RendererWarning ハンドラー宣言と Revoker 定義 |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | _RendererWarning ハンドラー実装（HRESULT 解析とメッセージ生成） |
