# 機能設計書 49-Flanger

## 概要

本ドキュメントは、K-ShootMania のプレイ画面におけるFlanger（フランジャー）エフェクト機能の設計を記述する。flan.dllを使用し、FXロングノート押下中にフランジャーエフェクトを楽曲にリアルタイムで適用する機能である。

### 本機能の処理概要

**業務上の目的・背景**：Flangerは原音に対して僅かに遅延させたコピーを混合し、遅延時間を周期的に変化させることで「ジェット機のような」うねり効果を生み出すエフェクトである。FXロングノートに割り当てられ、プレイヤーのFXボタン操作と連動した音響演出を提供する。

**機能の利用シーン**：プレイ画面でFXロングノートにFlangerエフェクト（FX_FLAN）が割り当てられている場合、ノート押下中にflan.dllのVSTプラグインとしてフランジャーエフェクトが適用される。

**主要な処理内容**：
1. applyVSTEffects関数でfl_Flan=1の場合、flan.dllをVSTプラグインとしてロード
2. 初期パラメータ設定: パラメータ0=0.25（周期）、パラメータ1=30/44100（最小ディレイ）、パラメータ2=45/44100（最大ディレイ）、パラメータ3=0.60（フィードバック）、パラメータ4=0.0（ステレオオフセット）、パラメータ5=0.75（ミックス量）、パラメータ6=0.0（ByPass状態）
3. BPM変化時にパラメータ0を`2*60*4*1000/bpmfx/10`で再計算
4. FXエフェクト開始時: パラメータ6=0.80でエフェクト有効化
5. FXエフェクト終了時: パラメータ6=0.0でエフェクト無効化

**関連システム・外部連携**：flan.dll（VSTプラグイン）、BASS Audio Library、bass_vst.dll

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

## 関連画面

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

## 機能種別

リアルタイムオーディオエフェクト処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fl_Flan | 整数 | Yes | Flangerエフェクト使用フラグ | 0または1 |
| feffectnow | 整数配列 | Yes | L/R各レーザーの現在FXエフェクトID | FX_FLAN |
| bpmfx | 整数 | Yes | 現在のBPM*1000 | 正の整数 |

### 入力データソース

- 譜面ファイル（.ksh）のFXロングノート定義

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| hFX_Flan | 整数 | FlangerのVSTハンドル |

### 出力先

- BASSオーディオエンジンのVSTエフェクトチェーン

## 処理フロー

### 処理シーケンス

```
1. VSTプラグインロード（applyVSTEffects）
   └─ hFX_Flan = BASS_VST_ChannelSetDSP(mid.0, flan.dll, 0, 15)
   └─ パラメータ初期設定: 0=0.25, 1=30/44100, 2=45/44100, 3=0.60, 4=0.0, 5=0.75, 6=0.0
2. BPM変化時の周期更新
   └─ パラメータ0 = maxf(minf(2*60*4*1000/bpmfx/10, 1.0), 0.0)
3. FXエフェクト開始
   └─ feffectnow.cnt = FX_FLAN の場合: パラメータ6 = 0.80
4. FXエフェクト終了
   └─ feffectp.cnt = FX_FLAN かつ feffectnow.(1-cnt) != FX_FLAN の場合: パラメータ6 = 0.0
```

### フローチャート

```mermaid
flowchart TD
    A[applyVSTEffects: flan.dllロード priority=15] --> B[初期パラメータ設定]
    B --> C[毎フレーム: processAudioEffects]
    C --> D{BPM変化?}
    D -->|Yes| E[パラメータ0周期更新]
    D -->|No| F{feffectnow変化?}
    E --> F
    F -->|FX_FLAN開始| G[パラメータ6=0.80]
    F -->|FX_FLAN終了| H[パラメータ6=0.0]
    F -->|変化なし| I[次フレームへ]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-49-01 | 周期計算 | period = 2*60*4*1000/bpmfx/10 (BPM連動) | BPM変化時 |
| BR-49-02 | VSTプライオリティ | Flangerのプライオリティは15 | applyVSTEffects |
| BR-49-03 | ミックス量制御 | パラメータ6で0.0(OFF)〜0.80(ON)を切替 | FXエフェクトON/OFF時 |
| BR-49-04 | L/R独立制御 | 両方のレーザーがFlangerでない場合のみ無効化 | feffectnow.(1-cnt)!=FX_FLANの条件 |

### 計算ロジック

- Flanger周期（パラメータ0）: `maxf(minf(2.0 * 60.0 * 4 * 1000 / bpmfx / 10, 1.0), 0.0)`
- ディレイ範囲: 30/44100 〜 45/44100 サンプル（約0.68ms 〜 1.02ms）

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

本機能ではデータベース操作は発生しない。

## エラー処理

BASS_VST_SetParam_Rはエラー時に最大5回リトライする。

### リトライ仕様

BASS_VST_SetParam_R内で最大5回リトライ。

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

該当なし。

## パフォーマンス要件

- VSTプラグインのDSP処理が音切れを起こさないこと

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

特になし。

## 備考

- flan.dllはFlanger専用のVSTプラグインである
- パラメータ6はflan.dllのミックス量制御パラメータで、0.0で完全バイパス、0.80で80%のウェット信号をミックスする
- Flangerの周期はBPMに連動し、2小節分の長さとなる

---

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

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

### 推奨読解順序

#### Step 1: VSTプラグインロードを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | applyVSTEffects関数内のFlanger初期化（274-283行目） |

**主要処理フロー**:
- **275行目**: `hFX_Flan=BASS_VST_ChannelSetDSP(mid.0,dir_default+"\\lib\\flan.dll",0,15)` でVSTロード
- **276-282行目**: 7つのパラメータ（0-6）の初期値設定

#### Step 2: BPM連動更新を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | BPM変化時処理（402行目） |

**主要処理フロー**:
- **402行目**: `BASS_VST_SetParam_R hFX_Flan,0,maxf(minf(2.0f*60.0f*4*1000/bpmfx/10,1.0f),0.0f)` でBPM連動周期更新

#### Step 3: FXエフェクト切替を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | Flanger ON/OFF処理（596-599行目, 698-700行目） |

**主要処理フロー**:
- **596-598行目**: Flanger終了時: `BASS_VST_SetParam_R hFX_Flan,6,0`
- **698-700行目**: Flanger開始時: `BASS_VST_SetParam_R hFX_Flan,6,0.80f`

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

```
start_play
    +-- applyVSTEffects
    |       +-- BASS_VST_ChannelSetDSP(flan.dll, priority=15) -> hFX_Flan
    |       +-- パラメータ0-6初期設定
    |
    +-- on_update_play (毎フレーム)
            +-- processAudioEffects
                    +-- BPM変化: パラメータ0再計算
                    +-- feffectnow変化: パラメータ6 ON/OFF
```

### データフロー図

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

譜面FXロングノート          feffectnow判定                   flan.dll VSTパラメータ
  FX_FLAN ----------------> ON/OFF切替                       パラメータ0(周期)
                                                             パラメータ6(ミックス量)
BPM値                       周期計算
  bpmfx ------------------>  2*60*4*1000/bpmfx/10
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | applyVSTEffects, processAudioEffects |
| bass_vst.as | `src/bass_vst.as` | ソース | BASS_VST_ChannelSetDSP, BASS_VST_SetParam_R APIバインディング |
| flan.dll | `lib/flan.dll` | DLL | Flanger VSTプラグイン |
