# 機能設計書 74-スプラッシュ画面

## 概要

プレイ直前にジャケット画像・楽曲情報・HiSpeed設定を表示するスプラッシュ画面機能の設計書である。

### 本機能の処理概要

選曲後、プレイ開始前にジャケット画像のアニメーション表示、HiSpeed値の確認・変更、各種楽曲情報の表示を行うスプラッシュ画面(待機画面)を提供する。プレイヤーはこの画面でHiSpeedの微調整を行い、準備が整ったらキー入力でプレイを開始する。

**業務上の目的・背景**：プレイ開始前に楽曲のジャケット画像やBPM、HiSpeed設定値を確認できる画面を提供することで、プレイヤーが十分な準備をしてからプレイに臨めるようにする。HiSpeedの調整も可能であり、5種類のHiSpeed方式(x倍速/C値/m値/a値/オフセット値)の切替と値変更ができる。

**機能の利用シーン**：選曲画面でEnterキーを押した後、プレイ開始前に表示される。コースモード終了時やコマンドライン起動時はスキップされる。一定時間経過またはEnterキー入力(未操作時)で自動的にプレイ画面へ遷移する。

**主要な処理内容**：
1. 背景画像(bg3.jpg)のロードと選曲BGMのフェードアウト
2. ジャケット画像のアニメーション表示(拡大アニメーション付き)
3. HiSpeed値の表示と上下キー/FXキーによる値変更
4. HiSpeed方式の左右キー/FXキーによる切替
5. アナログ入力デバイスの初期化(マウス/スライダー等)
6. Enterキー離脱またはタイムアウトによるプレイ画面への遷移
7. Escキーによる選曲画面への復帰

**関連システム・外部連携**：BASS Audio Libraryによる選曲BGMのフェードアウト・SE再生、artlet2dによる画像表示。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | play_splash_screen.hspによるプレイ直前のジャケット・楽曲情報表示 |
| 1 | タイトル画面 | 参照画面 | standby.jpgキャッシュ画像によるタイトル画面背景の表示 |

## 機能種別

画面表示処理(プレイ前待機画面)

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| csongjacket | string | Yes | ジャケット画像ファイル名 | - |
| csongdir | string | Yes | 楽曲ディレクトリ | - |
| courseend | int | Yes | コース終了フラグ(1:スキップ) | 0または1 |
| cmdline_from | int | Yes | コマンドライン起動フラグ(>0:スキップ) | 0以上 |
| analoginput | int | Yes | アナログ入力方式(0-5) | 0-5 |
| hsr/hsc/hsm/hsa/hso | int | Yes | HiSpeed設定値 | 各方式固有の範囲 |
| vhstype | array | Yes | HiSpeed方式の有効/無効配列 | 各要素0または1 |
| bpm/bpml | int/array | Yes | BPM値(表示用) | 正の整数 |

### 入力データソース

選曲画面で選択された楽曲情報と、config.iniから読み込まれたHiSpeed設定値。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| hs | int | 更新されたHiSpeed値(内部計算用) |
| hsr/hsc/hsm/hsa/hso | int | 更新されたHiSpeed設定値 |
| hstypenow | int | 選択されたHiSpeed方式(0-4) |
| endfl2 | int | Escキーによる中断フラグ |

### 出力先

画面表示および、HiSpeed設定値の更新(プレイ画面へ引き継ぎ)。

## 処理フロー

### 処理シーケンス

```
1. startSplashScreen (スプラッシュ画面開始)
   ├─ 背景画像(bg3.jpg)をバッファ149にロード
   ├─ 選曲BGMフェードアウト(BASS_ChannelSlideAttribute)
   ├─ SE再生(selenterid)
   ├─ ジャケット画像読み込み(Image35)
   ├─ バッファ129にジャケットをリサイズコピー
   ├─ pl_minfoprepare (楽曲情報準備)
   ├─ アナログ入力デバイス初期化
   └─ メインループ:
       ├─ ジョイスティック状態取得
       ├─ HiSpeed値の上下変更(上下キー/BT)
       ├─ HiSpeed方式の切替(左右キー/FX)
       ├─ hs値の再計算
       ├─ 画面描画(背景、ジャケットアニメーション、HiSpeed表示)
       ├─ Enter/Esc/F11/タイムアウト判定
       └─ break条件で遷移
```

### フローチャート

```mermaid
flowchart TD
    A[startSplashScreen] --> B{courseend==1 OR cmdline_from>0?}
    B -->|Yes| Z[ループスキップ - 即座にreturn]
    B -->|No| C[背景・SE・ジャケット初期化]
    C --> D[メインループ開始]
    D --> E[キー入力処理]
    E --> F{上下キー押下?}
    F -->|Yes| G[HiSpeed値変更]
    F -->|No| H{左右キー押下?}
    H -->|Yes| I[HiSpeed方式切替]
    H -->|No| J[画面描画]
    G --> J
    I --> J
    J --> K{Enter離脱 OR タイムアウト OR Esc?}
    K -->|Enter/タイムアウト| L[プレイ画面へ遷移]
    K -->|Esc| M[endfl2=1 - 選曲画面へ復帰]
    K -->|No| D
    L --> N[バッファ149解放]
    M --> N
    N --> O[return]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-74-01 | HiSpeed範囲 | x倍速:0.5-9.9, C/m/a/offset値:25-2000(25刻み) | HiSpeed変更時 |
| BR-74-02 | タイムアウト遷移 | 最終キー入力から1800ms経過で自動的にプレイへ遷移 | 操作あり時 |
| BR-74-03 | 未操作遷移 | 操作なしの場合、1200ms経過後にEnterキー離脱で遷移 | 操作なし時 |
| BR-74-04 | スキップ条件 | コースモード終了時(courseend=1)またはコマンドライン起動(cmdline_from>0)はスキップ | 常時 |
| BR-74-05 | ジャケットアニメーション | ジャケット画像は3000ms掛けて拡大アニメーション(sin関数で60ピクセル分減少) | 表示中 |

### 計算ロジック

- HiSpeed(x倍速): `hs = 108 * hsr / 10 / 2`
- HiSpeed(C値): `hs = 108 / 2`
- HiSpeed(m値): `hs = 108 * hsm * 1000 / maxbpm / 2`
- HiSpeed(a値): `hs = 108 * hsa * 1000 / avebpm / 2`
- HiSpeed(offset値): `hs = 108 * hso * 1000 / oftbpm / 2`
- ジャケットサイズ: `300 - 60 * sin(min(timenow, 3000) * PI/2 / 3000)` ピクセル

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

該当なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 画像読み込み失敗 | ジャケット画像ファイルが存在しない | 明示的なエラー処理はない |

### リトライ仕様

リトライ処理は実装されていない。

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

該当なし。

## パフォーマンス要件

- await 7 でフレーム間隔を約7msに制御(約143fps)
- ジャケット画像は初回のみリサイズ処理を行い、以降はバッファからコピー

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

特になし。

## 備考

- マウス入力(analoginput=2)の場合、hidem変数に基づきマウスカーソルを画面中央に移動する
- PowerMate入力(analoginput=1)の場合、onkey 1でキーイベントを有効化する
- スプラッシュ画面終了後、バッファ149は1x1サイズに縮小されてメモリを解放する(384-386行目)

---

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

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

### 推奨読解順序

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

スプラッシュ画面で使用される変数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | HiSpeed関連変数(hsr/hsc/hsm/hsa/hso)とvhstype配列の定義を確認する |

**読解のコツ**: HSP3の`getkey`命令は第2引数にキーコードを指定して状態を取得する。`gzoom`命令はバッファ間のリサイズコピーを行う。`alXxx`系関数はartlet2dプラグインの画像処理関数である。

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

スプラッシュ画面の開始関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_splash_screen.hsp | `src/scene/play/play_splash_screen.hsp` | startSplashScreen関数(1-387行目)の全体構造を理解する |

**主要処理フロー**:
1. **2行目**: `imgbufload_bg "bg3.jpg",149` - 背景画像をバッファ149にロード
2. **3行目**: `BASS_ChannelSlideAttribute selbgmid,2,0.0,50` - 選曲BGMの50msフェードアウト
3. **5-9行目**: コースモード/コマンドライン以外の場合にSE再生
4. **11-19行目**: ジャケット画像の読み込み(通常モード/コマンドラインモードで分岐)
5. **20-21行目**: バッファ129にジャケットをリサイズコピー
6. **43行目**: メインループ開始(courseend/cmdline条件でブレイク)
7. **122-169行目**: 上下キーによるHiSpeed値の変更処理
8. **170-253行目**: 左右キーによるHiSpeed方式の切替処理
9. **256-267行目**: hs値の再計算
10. **274行目**: ジャケットアニメーション(sin関数による拡大)
11. **359行目**: タイムアウト/Enter離脱/Esc判定

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

```
play_init (プレイ画面初期化)
    │
    └─ startSplashScreen
           ├─ imgbufload_bg (背景画像ロード)
           ├─ BASS_ChannelSlideAttribute (BGMフェードアウト)
           ├─ BASS_ChannelPlay (SE再生)
           ├─ alCreateImageByFile (ジャケット読み込み)
           ├─ *pl_minfoprepare (楽曲情報準備)
           ├─ *getjoystat (ジョイスティック状態取得)
           ├─ *refreshhs (HiSpeed再計算)
           └─ 描画ループ
                ├─ gcopy (背景コピー)
                ├─ gzoom (ジャケットアニメーション)
                ├─ alCopyImageToScreen (UI画像描画)
                └─ await 7 (フレーム待機)
```

### データフロー図

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

ジャケット画像       ──▶ alCreateImageByFile       ──▶ Image35 (ジャケット)
(csongjacket)             + alStretchImageToScreen       バッファ129 (リサイズ)

HiSpeed設定          ──▶ キー入力判定              ──▶ 更新されたhs値
(hsr/hsc/hsm等)           + refreshhs                    (プレイ画面へ引き継ぎ)

Enter/Esc/タイムアウト ──▶ ループ脱出判定           ──▶ endfl2 (中断フラグ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play_splash_screen.hsp | `src/scene/play/play_splash_screen.hsp` | ソース | スプラッシュ画面の主要処理(全387行) |
| kshootmania.hsp | `kshootmania.hsp` | ソース | HiSpeed関連変数・定数の定義 |
| play_key_input.hsp | `src/scene/play/play_key_input.hsp` | ソース | キー入力処理の参照 |
