# 機能設計書 96-IRポップアップUI

## 概要

本ドキュメントは、K-Shoot MANIAにおけるインターネットランキング(IR)のポップアップUI表示機能の設計を記述する。

### 本機能の処理概要

本機能は、IRサーバーへのスコア送信結果やIR関連の通知をリザルト画面上にポップアップとして表示する機能である。フェードイン/フェードアウトのアニメーション付きで画面右下に表示される。

**業務上の目的・背景**：プレイ後のスコア送信結果（成功/失敗/ランキング情報等）をプレイヤーに通知するため、一時的なポップアップUIが必要である。

**機能の利用シーン**：リザルト画面(SCENE_RESULT)でir_popup_initで初期化し、ir_popup_set_textでテキストを設定、ir_popup_drawで毎フレーム描画する。

**主要な処理内容**：
1. ir_popup_init: ポップアップ用画像バッファ(IMG_IR_POPUP_TEMP)の生成
2. ir_popup_set_text: テキスト内容・表示時間・エラー状態の設定
3. ir_popup_draw: フェードイン→表示→フェードアウトのアニメーション描画

**関連システム・外部連携**：IRサーバーとの通信結果を受けて表示内容が決定される。artlet2D(alXxx系関数)による画像・テキスト描画。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | リザルト画面 | 主画面 | ir_popup_init/ir_popup_set_textによるIRスコア送信結果のポップアップ表示 |

## 機能種別

UI表示 / アニメーション

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| text (ir_popup_set_text) | str | Yes | 表示テキスト。空文字の場合はリセット | なし |
| time (ir_popup_set_text) | int | Yes | 表示時間(ミリ秒) | なし |
| is_error (ir_popup_set_text) | int | Yes | エラー状態(0:通常, 1:エラー) | 0または1 |

### 入力データソース

- IRサーバーからのレスポンス内容(ir_send_scoreの結果)

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| IMG_IR_POPUP_TEMP | Image | ポップアップ用一時画像バッファ |
| popup_height | int | ポップアップの描画高さ |

### 出力先

画面右下にアニメーション付きで描画

## 処理フロー

### 処理シーケンス

```
1. ir_popup_init: 初期化
   └─ popup_startt=0, popup_endt=-10000
   └─ IMG_IR_POPUP_TEMP画像バッファ生成
2. ir_popup_set_text: テキスト設定
   └─ 空文字の場合: リセット
   └─ テキストありの場合:
     └─ popup_startt=現在時刻, popup_endt=現在時刻+time
     └─ IMG_IR_POPUP背景画像をコピー(is_errorで色分け)
     └─ テキスト描画・高さ計算
3. ir_popup_draw: 毎フレーム描画
   └─ フェードイン(200ms): 透明度0→1、左方向からスライドイン
   └─ 表示中: 透明度1.0で固定表示
   └─ フェードアウト(200ms): 透明度1→0、左方向へスライドアウト
```

### フローチャート

```mermaid
flowchart TD
    A[ir_popup_init] --> B[ir_popup_set_text]
    B --> C{テキスト空?}
    C -->|Yes| D[ポップアップリセット]
    C -->|No| E[背景画像コピー + テキスト描画]
    E --> F[popup_startt/popup_endt設定]
    F --> G[ir_popup_draw: 毎フレーム]
    G --> H{startt <= now < startt+200?}
    H -->|Yes| I[フェードイン: alpha=(now-startt)/200]
    H -->|No| J{startt+200 <= now < endt?}
    J -->|Yes| K[固定表示: alpha=1.0]
    J -->|No| L{endt <= now < endt+200?}
    L -->|Yes| M[フェードアウト: alpha=(endt+200-now)/200]
    L -->|No| N[非表示: return]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-96-01 | フェードイン時間 | 200msかけて透明度0→1にフェードイン | popup_startt〜popup_startt+200 |
| BR-96-02 | フェードアウト時間 | 200msかけて透明度1→0にフェードアウト | popup_endt〜popup_endt+200 |
| BR-96-03 | スライドアニメーション | 右方向から40ピクセル分スライドイン/アウト | フェードイン/アウト時 |
| BR-96-04 | エラー色分け | is_error=0で通常背景、is_error=1でエラー背景 | ir_popup_set_text内 |
| BR-96-05 | 表示位置 | 画面右下(scrsize_w-170-dx, scrsize_h-popup_height) | ir_popup_draw内 |

### 計算ロジック

- フェードイン透明度: `(timenow - popup_startt) / 200`
- フェードアウト透明度: `(popup_endt + 200 - timenow) / 200`
- X方向オフセット: `-40 + 40 * (timenow - popup_startt) / 200` (フェードイン時)

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

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

## エラー処理

### エラーケース一覧

特になし。テキスト空文字の場合はリセット動作となる。

### リトライ仕様

特になし。

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

特になし。

## パフォーマンス要件

毎フレーム描画のため、描画処理は軽量である必要がある。

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

特になし。

## 備考

- IMG_IR_POPUPは背景画像(通常/エラーの2パターン)、IMG_IR_POPUP_TEMPはテキスト付き一時画像
- artlet2D(alXxx系関数)を使用した半透明描画

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ir.hsp | `src/ir.hsp` | popup_startt/popup_endt/popup_height変数(71-73行目) |
| 1-2 | ir.hsp | `src/ir.hsp` | IMG_IR_POPUP/IMG_IR_POPUP_TEMP画像バッファID(20-21行目のdefine) |

**読解のコツ**: alXxx系関数はartlet2Dプラグインの関数群。alCreateImageで画像バッファ生成、alCopyImageToImageで画像間コピー、alCopyImageToScreenで画面描画。

#### Step 2: 初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ir.hsp | `src/ir.hsp` | ir_popup_init(70-75行目): 初期化処理 |

**主要処理フロー**:
1. **71行目**: popup_startt=0
2. **72行目**: popup_endt=-10000（表示なし状態）
3. **74行目**: IMG_IR_POPUP_TEMPバッファ生成(200xscrsize_h)

#### Step 3: テキスト設定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ir.hsp | `src/ir.hsp` | ir_popup_set_text(77-98行目): テキスト設定と画像構築 |

**主要処理フロー**:
- **79-83行目**: テキスト空の場合のリセット処理
- **85-86行目**: popup_startt/popup_endtの設定
- **89行目**: is_errorに応じた背景画像の選択とコピー
- **94-95行目**: テキスト矩形計算でpopup_heightを決定
- **96行目**: テキスト描画

#### Step 4: 描画処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ir.hsp | `src/ir.hsp` | ir_popup_draw(100-117行目): 毎フレーム描画処理 |

**主要処理フロー**:
- **103-104行目**: フェードイン期間(0-200ms)
- **106-107行目**: 固定表示期間
- **109-111行目**: フェードアウト期間(endt〜endt+200ms)
- **115行目**: alCopyImageToScreenで画面に描画

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

```
result.hsp (リザルト画面)
    |
    +-- ir_popup_init()
    |       └── alCreateImage(IMG_IR_POPUP_TEMP)
    |
    +-- ir_send_score() → ir_popup_set_text(text, time, is_error)
    |       +── alCopyImageToImage(背景)
    |       +── alDrawText(テキスト)
    |       └── popup_height計算
    |
    └── ir_popup_draw()  ※毎フレーム
            +── alCopyModeAlpha(透明度)
            └── alCopyImageToScreen(描画)
```

### データフロー図

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

IR通信結果 ────────> ir_popup_set_text ──────> IMG_IR_POPUP_TEMP
(text, time, is_error)      |                    (テキスト付き画像)
                            v
IMG_IR_POPUP ─────> 背景画像コピー
(背景テンプレート)          |
                            v
毎フレーム ────────> ir_popup_draw ──────> 画面右下に描画
                    (フェードアニメーション)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ir.hsp | `src/ir.hsp` | ソース | IRポップアップUIの全実装 |
| result.hsp | `src/scene/result.hsp` | ソース | ir_popup_init/ir_popup_drawの呼び出し元 |
