# 機能設計書 52-Phaser

## 概要

本ドキュメントは、K-ShootMania（KSM）のプレイ画面におけるPhaserオーディオエフェクトの設計を記述する。Phaserは位相をずらした信号を原音にミックスすることで、うねりのあるサウンドを生成するモジュレーション系エフェクトである。

### 本機能の処理概要

PhaserエフェクトはFXノートのロング区間で発動し、phas.dllを通じてオーディオストリームにリアルタイムでフェイザー処理を適用する。BPM連動の周期制御により、楽曲のテンポに同期したうねりを生成する。

**業務上の目的・背景**：音楽ゲームにおいてフェイザー効果は楽曲の空間的広がりやサイケデリックな演出を提供するために必要不可欠なエフェクトである。譜面制作者がFXノート区間に指定することで、楽曲のテンポに同期した位相変調効果を付与できる。

**機能の利用シーン**：プレイ画面においてFXノートのロング区間でPhaserが指定されている場合、エフェクトが適用される。BPM変化に追従して周期（period）が自動調整される。

**主要な処理内容**：
1. 譜面読み込み時にPhaserエフェクトの使用フラグ（fl_Phas）を設定
2. VSTプラグインとしてphas.dllをオーディオストリームにロード
3. 9つのパラメータ（period, stage, loFreq, hiFreq, Q, stereoWidth, mix, hiCutGain, feedback）を初期化
4. BPM変化に応じたperiodの自動調整（2拍周期）
5. FXノート区間のON/OFFに連動したmix値とfeedback値の切替

**関連システム・外部連携**：BASS Audio Library（bass.dll）のVSTプラグインホスティング機能（bass_vst.dll）を通じてphas.dllを制御する。

**権限による制御**：特になし。譜面データに基づいて自動的に適用される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | phas.dllによるフェイザーエフェクト適用 |

## 機能種別

リアルタイム音声処理（VSTエフェクト適用）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| period | FXDEF_LENGTH (float) | Yes | LFO周期（BPM連動、デフォルト0.50=2拍） | 0.0以上 |
| stage | FXDEF_INT (int) | Yes | フェイザーステージ数（デフォルト6） | 0〜12 |
| loFreq | FXDEF_FREQ (float) | Yes | 低域周波数（デフォルト1500Hz） | 0〜22050Hz |
| hiFreq | FXDEF_FREQ (float) | Yes | 高域周波数（デフォルト20000Hz） | 0〜22050Hz |
| Q | FXDEF_FLOAT (float) | Yes | レゾナンス（デフォルト0.707） | 0〜50.0 |
| stereoWidth | FXDEF_RATE (float) | Yes | ステレオ幅（デフォルト0.75） | 0.0〜1.0 |
| mix | FXDEF_RATE (float) | Yes | エフェクトミックス率 | 0.0〜1.0 |
| hiCutGain | FXDEF_NEGDB (float) | Yes | ハイカットゲイン（デフォルト8dB） | 0〜20.0 |
| feedback | FXDEF_RATE (float) | Yes | フィードバック量（デフォルト0.35） | 0.0〜1.0 |

### 入力データソース

- KSH譜面ファイルのFXノート定義
- ユーザー定義エフェクト（#define_fx / #define_filter）
- BPMデータ（bpml配列）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 音声ストリーム | audio stream | Phaser処理が適用されたオーディオ出力 |
| hFX_Phas | int | VSTエフェクトハンドル |

### 出力先

オーディオ出力デバイス（BASS Audio Libraryのオーディオストリーム経由）

## 処理フロー

### 処理シーケンス

```
1. 譜面読み込みフェーズ（play_chart_load.hsp）
   └─ FXノート定義からFX_PHAS（定数値15）を検出し fl_Phas=1 を設定
2. VSTエフェクト初期化フェーズ（applyVSTEffects）
   └─ fl_Phas=1の場合、BASS_VST_ChannelSetDSP でphas.dllをロード（優先度16）
   └─ period=0.25, stage=0.0, loFreq=1500/22050, hiFreq=20000/22050 等を設定
3. BPM連動処理（processAudioEffects）
   └─ BPM変化時にperiodを再計算: 60*2*1000/bpmfx/10
4. FXノート区間切替処理
   └─ ON:  mix=0.50, feedback=0.50 を設定
   └─ OFF: mix=0.0, feedback=0.0 にリセット
```

### フローチャート

```mermaid
flowchart TD
    A[譜面読み込み] --> B{FX_PHAS定義あり?}
    B -->|Yes| C[fl_Phas=1を設定]
    B -->|No| D[Phaser未使用]
    C --> E[applyVSTEffects: phas.dllロード]
    E --> F[processAudioEffects: 毎フレーム処理]
    F --> G{BPM変化?}
    G -->|Yes| H[period再計算]
    G -->|No| I{FXノート区間変化?}
    H --> I
    I -->|ON| J[mix=0.50, feedback=0.50]
    I -->|OFF| K[mix=0.0, feedback=0.0]
    J --> F
    K --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-52-1 | BPM連動周期 | BPM変化時にperiodを `60*2*1000/bpmfx/10` で再計算 | bpmfx != bpmfxp |
| BR-52-2 | エフェクト排他制御 | L/R独立でPhaserを割り当て、両方がPhaserでない場合のみOFF処理 | feffectp.cnt=FX_PHAS かつ feffectnow.(1-cnt)!=FX_PHAS |
| BR-52-3 | ON時パラメータ設定 | mix(param8)=0.50, feedback(param5)=0.50 | feffectnow.cnt=FX_PHAS |
| BR-52-4 | OFF時パラメータリセット | stage(param1)=0.0, feedback(param8)=0 | feffectp.cnt=FX_PHAS OFF |

### 計算ロジック

- **BPM連動period**: `maxf(minf(60.0*2*1000/bpmfx/10, 1.0), 0.0)`
- **周波数正規化**: `loFreq/22050.0`, `hiFreq/22050.0`
- **Q値正規化**: `Q/50.0`
- **hiCutGain正規化**: `hiCutGain/20.0`

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

本機能はデータベースを使用しない。すべてインメモリ処理である。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DLLロード失敗 | phas.dllが存在しない場合 | エフェクト未適用で続行 |

### リトライ仕様

リトライ処理は行わない。

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

不要。リアルタイムオーディオ処理のためフレーム単位で処理される。

## パフォーマンス要件

- VSTエフェクト優先度: 16
- オーディオバッファ更新周期内に処理完了が必要

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

外部DLL（phas.dll）の読み込みに関するDLL改竄リスク。

## 備考

- Phaser DLL識別名: "phas.dll"
- エフェクト定数値: FX_PHAS = 15, FXDEF_FXTYPE_PHAS = 5
- パラメータ数: 9（他のエフェクトより多い）
- VSTパラメータマッピング: param0=period, param1=stage, param2=loFreq, param3=hiFreq, param4=Q, param5=feedback, param6=stereoWidth, param7=hiCutGain, param8=mix

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | fxdef.hsp | `src/audio/fxdef.hsp` | Phaserの定数定義とパラメータテーブル（9パラメータ） |

**読解のコツ**: Phaserは9パラメータと多いため、fxdef_prmno配列（VSTパラメータ番号へのマッピング）を理解することが重要。param0がperiod、param8がmixなど、VSTプラグイン側のパラメータ番号との対応を把握する。

- **18行目**: `#define FX_PHAS 15` - FXノート用定数
- **41行目**: `#define FXDEF_FXTYPE_PHAS 5` - エフェクトタイプ
- **124-134行目**: Phaserパラメータテーブル全体

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | fl_Phasフラグ設定 |

**主要処理フロー**:
1. **919行目**: `fl_Phas=0` - 初期化
2. **1146-1147行目**: `fx.fxnum.2=FX_PHAS` 設定時に `fl_Phas=1`
3. **1888行目**: 組み込みエフェクト定義でもfl_Phas=1を設定

#### Step 3: VSTエフェクト初期化

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | phas.dllのロードとパラメータ初期化 |

**主要処理フロー**:
- **262-273行目**: fl_Phas=1の場合にphas.dllをロードし、period/stage/loFreq/hiFreq/Q/stereoWidth/mix/hiCutGain/feedbackを初期設定

#### Step 4: BPM連動とリアルタイム処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | BPM変化時のperiod再計算とON/OFF切替 |

**主要処理フロー**:
- **403行目**: BPM変化時のperiod再計算 `60.0*2*1000/bpmfx/10`
- **592-595行目**: OFF時にstage=0, feedback=0 へリセット
- **694-696行目**: ON時にmix=0.50, feedback=0.50 を設定

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

```
play_init
    |
    +-- loadKSHChartFile -> fl_Phas=1
    |
    +-- applyVSTEffects
    |       +-- BASS_VST_ChannelSetDSP(phas.dll) -> hFX_Phas
    |       +-- 9パラメータ初期設定
    |
    +-- play_update -> processAudioEffects
            +-- BPM変化検出 -> period再計算
            +-- FXノート区間切替
                    +-- ON:  mix=0.50, feedback=0.50
                    +-- OFF: stage=0, feedback=0
```

### データフロー図

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

KSH譜面ファイル ---------> 譜面解析(fl_Phas設定) --------> エフェクトフラグ
BPMデータ ---------------> BPM連動period計算 ------------> VSTパラメータ更新
FXノート区間 ------------> processAudioEffects -----------> phas.dll
音楽ストリーム ---------> BASS Audio Library --------------> スピーカー出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| fxdef.hsp | `src/audio/fxdef.hsp` | ソース | Phaserパラメータ定義（9パラメータ） |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | VSTエフェクト初期化・リアルタイム処理 |
| play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | ソース | 譜面読み込みとfl_Phasフラグ設定 |
| phas.dll | `lib/phas.dll` | 外部DLL | Phaser VSTプラグイン本体 |
| bass_vst.dll | - | 外部DLL | BASS VSTプラグインホスティング |
