# 機能設計書 55-Echo

## 概要

本ドキュメントは、K-ShootMania（KSM）のプレイ画面におけるEchoオーディオエフェクトの設計を記述する。Echoは4分音符単位のディレイ（遅延反復）をBPMに同期させて適用するエフェクトである。

### 本機能の処理概要

EchoエフェクトはFXノートのロング区間で発動し、regawo.dllを通じて楽曲にBPM連動のディレイ効果を適用する。L/R独立の2インスタンスを持ち、トリガー切替機構により自然なエフェクト遷移を実現する。

**業務上の目的・背景**：エコー（ディレイ）は音楽制作・DJパフォーマンスにおいて基本的な空間系エフェクトであり、楽曲の余韻や反復効果を演出するために使用される。4分音符単位のBPM同期により、楽曲のリズムに合致したエコーが得られる。

**機能の利用シーン**：プレイ画面においてFXノートのロング区間でEcho（FX_EC4）が指定されている場合に発動する。feedbackLevel（フィードバック量）により残響の長さを制御できる。

**主要な処理内容**：
1. 譜面読み込み時にEchoの使用フラグ（fl_Echo）を設定
2. regawo.dllの2インスタンスをL/R用にロード
3. BPM連動のwaveLength（ディレイタイム）とfadeoutLength計算
4. echo_trigger変数による0/1トグルでインスタンス切替
5. feedbackLevel（param4）によるフィードバック量制御

**関連システム・外部連携**：BASS Audio Library経由でregawo.dllを制御する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 主画面 | regawo.dllによる4分音符単位のエコーエフェクト適用 |

## 機能種別

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

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| updatePeriod | FXDEF_LENGTH (float) | Yes | 更新周期 | 0.0以上 |
| waveLength | FXDEF_LENGTH (float) | Yes | ディレイタイム（BPM連動） | 0.0以上 |
| mix | FXDEF_RATE (float) | Yes | エフェクトミックス率 | 0.0〜1.0 |
| feedbackLevel | FXDEF_RATE (float) | Yes | フィードバック量（デフォルト0.60） | 0.0〜1.0 |
| rate | FXDEF_RATE (float) | Yes | レート（デフォルト1.00） | 0.0〜1.0 |
| updateTrigger | FXDEF_SWITCH (float) | Yes | 更新トリガー | 0.0 or 1.0 |

### 入力データソース

- KSH譜面ファイルのFXノート定義（FX_EC4=18）
- ユーザー定義エフェクト
- BPMデータ
- feffectparam2（feedbackLevel値）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 音声ストリーム | audio stream | Echo処理が適用されたオーディオ出力 |
| hFX_Echo | int[2] | L/R独立のVSTエフェクトハンドル配列 |

### 出力先

オーディオ出力デバイス

## 処理フロー

### 処理シーケンス

```
1. 譜面読み込みフェーズ
   └─ FX_EC4（定数値18）を検出し fl_Echo=1 を設定
2. VSTエフェクト初期化（applyVSTEffects）
   └─ fl_Echo=1の場合、regawo.dllを2インスタンスロード（優先度26）
   └─ 各インスタンスで mix(param1)=0, rate(param2)=1.00, ByPass(param29)=1.0 を設定
3. BPM連動処理
   └─ BPM変化時にwaveLength(param1)とfadeoutLength(param3)を再計算
   └─ waveLength: 60*4*1000/bpmfx/10/echo_now
   └─ fadeoutLength: waveLength * 1.25
4. FXノート区間切替
   └─ ON:  echo_trigger切替(0/1トグル), ByPass=0, waveLength/feedbackLevel/rate/fadeoutLength設定
   └─ OFF: ByPass(param29)=1, waveLength(param1)=0
5. L/Rインスタンス切替
   └─ echo_trigger.cntの0/1切替でparam0を設定し、アクティブインスタンスを選択
   └─ 非アクティブ側のparam5=0（rate=0）でフェードアウト
```

### フローチャート

```mermaid
flowchart TD
    A[譜面読み込み] --> B{FX_EC4定義あり?}
    B -->|Yes| C[fl_Echo=1を設定]
    B -->|No| D[Echo未使用]
    C --> E[regawo.dll x2インスタンスロード]
    E --> F[processAudioEffects]
    F --> G{BPM変化?}
    G -->|Yes| H[waveLength/fadeoutLength再計算]
    G -->|No| I{FXノート区間変化?}
    H --> I
    I -->|ON| J[echo_triggerトグル, パラメータ設定]
    I -->|OFF| K[ByPass=1, waveLength=0]
    J --> F
    K --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-55-1 | デュアルインスタンス | L/R独立で2つのregawo.dllインスタンスを持つ | fl_Echo=1 |
| BR-55-2 | トリガートグル | echo_trigger.cntを0/1で切替えてparam0に設定 | feffectnow.cnt=FX_EC4 |
| BR-55-3 | BPM連動 | waveLength=60*4*1000/bpmfx/10/echo_now, fadeoutLength=waveLength*1.25 | BPM変化時 |
| BR-55-4 | feedbackLevel | feffectparam2/100でfeedbackLevelを設定 | FX_EC4 ON時 |
| BR-55-5 | インスタンス排他 | ON側のparam5=1.0(rate), OFF側のparam5=0.0 | エフェクト切替時 |

### 計算ロジック

- **waveLength**: `60.0*4.0*1000.0/bpmfx/10.0/feffectparam.cnt`
- **fadeoutLength**: `waveLength * 1.25`
- **feedbackLevel**: `double(feffectparam2.cnt)/100`

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

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

不要。

## パフォーマンス要件

- VSTエフェクト優先度: 26（最高優先度）
- 2インスタンス構成

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

外部DLL（regawo.dll）の読み込みリスク。

## 備考

- Echo DLL: "regawo.dll"（Retrigger/Gate/Wobbleと共用）
- エフェクト定数値: FX_EC4 = 18, FXDEF_FXTYPE_ECHO = 8
- echo_trigger変数による0/1トグル方式でクロスフェード的なエフェクト遷移を実現
- param3（fadeoutLength）はwaveLengthの1.25倍に設定される

---

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

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

### 推奨読解順序

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

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

- **21行目**: `#define FX_EC4 18` - 4分音符エコー定数
- **44行目**: `#define FXDEF_FXTYPE_ECHO 8` - エフェクトタイプ
- **172-182行目**: Echoパラメータテーブル（updatePeriod, waveLength, mix, feedbackLevel, rate, updateTrigger）

**読解のコツ**: Echoはregawo.dllを使用するが、Retrigger/Gate/Wobbleとは独立したパラメータセットを持つ。linkprm=2はwaveLengthパラメータとのリンクを示す。

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

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

- **218-227行目**: hFX_Echo配列初期化、fl_Echo=1でregawo.dllを2インスタンスロード、mix=0/rate=1.00/ByPass=1.0で初期設定

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | BPM連動とトリガートグル |

- **414-419行目**: BPM変化時のwaveLengthとfadeoutLength再計算
- **647-654行目**: OFF時のByPass=1とwaveLength=0リセット
- **729-738行目**: ON時のecho_triggerトグル、waveLength/fadeoutLength/feedbackLevel/rate設定

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

```
play_init
    |
    +-- loadKSHChartFile -> fl_Echo=1
    |
    +-- applyVSTEffects
    |       +-- BASS_VST_ChannelSetDSP(regawo.dll) x2 -> hFX_Echo[0], hFX_Echo[1]
    |       +-- mix=0, rate=1.00, ByPass=1.0 初期設定
    |
    +-- processAudioEffects
            +-- BPM変化 -> waveLength再計算
            +-- FXノート切替
                    +-- ON:  echo_triggerトグル, waveLength/feedbackLevel設定
                    +-- OFF: ByPass=1, waveLength=0
```

### データフロー図

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

FXノート(FX_EC4) --------> processAudioEffects -----------> hFX_Echo[0] (L)
BPMデータ ---------------> waveLength計算 ----------------> hFX_Echo[1] (R)
feffectparam2 -----------> feedbackLevel計算 -------------> regawo.dll
echo_trigger ------------> 0/1トグル --------------------->   |
音楽ストリーム ---------> BASS Audio Library --------------> スピーカー出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| fxdef.hsp | `src/audio/fxdef.hsp` | ソース | Echoパラメータ定義 |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | VSTエフェクト制御 |
| play_chart_load.hsp | `src/scene/play/play_chart_load.hsp` | ソース | 譜面読み込みとフラグ設定 |
| regawo.dll | `lib/regawo.dll` | 外部DLL | Echo/Retrigger/Gate/Wobble共用VSTプラグイン |
