# 機能設計書 45-バッファ長制御

## 概要

本ドキュメントは、K-ShootMania におけるオーディオバッファ長と更新周期の制御機能の設計を記述する。BASS Audio Library のバッファ長（bufferlength）と更新周期（updateperiod）をconfig.iniの設定値に基づいて制御し、音声のレイテンシ調整を行う機能である。

### 本機能の処理概要

**業務上の目的・背景**：音楽ゲームではオーディオのレイテンシ（遅延）がプレイ体験に直接影響する。バッファ長を短くすればレイテンシは小さくなるが、音切れのリスクが増す。更新周期を短くすればタイミング精度が上がるが、CPU負荷が増大する。プレイヤーの環境に合わせて最適なバッファ設定を提供するために本機能が必要である。

**機能の利用シーン**：アプリケーション起動時のBASSエンジン初期化において設定される。また、プレイ画面の一時停止からの再開時にupdateperiodが再設定される。さらに、バッファ長はレーザーエフェクトの遅延補正（laserdelay0）の計算にも使用される。

**主要な処理内容**：
1. config.iniから`#bufferlength:`と`#updateperiod:`の設定値を読み込む
2. デフォルト値としてbufferlength=200、updateperiod=100を設定する
3. BASS_Init実行後にBASS_SetConfigでバッファ長と更新周期を設定する
4. BASS_SetConfig(0, bufferlength)でバッファ長を設定
5. BASS_SetConfig(1, updateperiod)で更新周期を設定
6. BASS_SetConfig(24, 2)でフロートDSP処理を設定
7. レーザーエフェクト遅延補正値の計算: laserdelay0 = bufferlength - soundfx_delay - GLOBAL_SOUNDFX_DELAY

**関連システム・外部連携**：BASS Audio Library（bass.dll）のBASS_SetConfig API

**権限による制御**：特になし。config.iniで設定可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | ゲームプレイ画面 | 参照画面 | BASS_SetConfigによるバッファ長・更新周期の制御 |

## 機能種別

システム設定処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| bufferlength | 整数 | Yes | オーディオバッファ長（ms） | 最小値6（max関数で保証） |
| updateperiod | 整数 | Yes | 更新周期（ms） | 最小値5（max関数で保証） |

### 入力データソース

- config.ini: `#bufferlength:`パラメータ（デフォルト200ms）
- config.ini: `#updateperiod:`パラメータ（デフォルト100ms）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| BASS_CONFIG_BUFFER (0) | 整数 | BASSエンジンのバッファ長設定値 |
| BASS_CONFIG_UPDATEPERIOD (1) | 整数 | BASSエンジンの更新周期設定値 |
| laserdelay0 | 整数 | レーザーエフェクト遅延補正値（ms） |

### 出力先

- BASSオーディオエンジンの内部設定

## 処理フロー

### 処理シーケンス

```
1. デフォルト値設定
   └─ bufferlength=200, updateperiod=100
2. config.ini読み込み
   └─ #bufferlength:, #updateperiod: からユーザー設定値を取得
3. バリデーション
   └─ bufferlength=max(int(値),6), updateperiod=max(int(値),5)
4. BASSエンジン初期化
   └─ BASS_Init(-1, 44100, 0, hwnd)
5. バッファ設定適用
   └─ BASS_SetConfig(1, updateperiod) // 更新周期
   └─ BASS_SetConfig(0, bufferlength) // バッファ長
   └─ BASS_SetConfig(24, 2)           // フロートDSP
6. レーザー遅延補正値計算
   └─ laserdelay0 = bufferlength - soundfx_delay - GLOBAL_SOUNDFX_DELAY
7. プレイ画面遷移時の追加設定
   └─ BASS_SetConfig(4, 10000), BASS_SetConfig(5, 10000) // ネットストリームバッファ
```

### フローチャート

```mermaid
flowchart TD
    A[アプリ起動] --> B[デフォルト値設定 buffer=200, period=100]
    B --> C[config.ini読み込み]
    C --> D{#bufferlength存在?}
    D -->|Yes| E[bufferlength=max val,6]
    D -->|No| F[デフォルト200を使用]
    C --> G{#updateperiod存在?}
    G -->|Yes| H[updateperiod=max val,5]
    G -->|No| I[デフォルト100を使用]
    E --> J[BASS_Init]
    F --> J
    H --> J
    I --> J
    J --> K[BASS_SetConfig 1,updateperiod]
    K --> L[BASS_SetConfig 0,bufferlength]
    L --> M[BASS_SetConfig 24,2]
    M --> N[laserdelay0計算]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-45-01 | バッファ長最小値 | bufferlengthは最小6ms | config.ini読み込み時 |
| BR-45-02 | 更新周期最小値 | updateperiodは最小5ms | config.ini読み込み時 |
| BR-45-03 | デフォルト値 | bufferlength=200ms, updateperiod=100ms | config.iniに設定がない場合 |
| BR-45-04 | 遅延補正計算 | laserdelay0 = bufferlength - soundfx_delay - GLOBAL_SOUNDFX_DELAY | プレイ画面初期化時 |

### 計算ロジック

- レーザー遅延補正: `laserdelay0_orig = bufferlength - soundfx_delay - GLOBAL_SOUNDFX_DELAY`
- BASS_SetConfig定数: 0=BASS_CONFIG_BUFFER, 1=BASS_CONFIG_UPDATEPERIOD, 24=BASS_CONFIG_FLOATDSP

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定値下限 | bufferlength < 6 | max関数で6に補正 |
| - | 設定値下限 | updateperiod < 5 | max関数で5に補正 |

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

- bufferlengthを小さくするほどレイテンシが低減するが、音切れリスクが増大する
- updateperiodを小さくするほどタイミング精度が向上するが、CPU負荷が増大する
- エフェクト処理のトリガー判定にupdateperiod/5を閾値として使用（play_audio_effects.hsp 438行目、820行目、897行目）

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

特になし。

## 備考

- BASSエンジンの初期化パラメータ: サンプルレート44100Hz、デバイスID=-1（デフォルトデバイス）
- BASS_SetConfig(4, 10000) と BASS_SetConfig(5, 10000) はネットストリームバッファ設定で、プレイ画面遷移前に設定される
- 一時停止再開時にもBASS_SetConfig(1, updateperiod)が再設定される（play_key_input.hsp 145行目）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | bass.as | `src/bass.as` | BASS_SetConfig関数の宣言（36行目）。int,intの2引数で、第1引数が設定ID、第2引数が設定値 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshootmania.hsp | `kshootmania.hsp` | デフォルト値設定とconfig.ini読み込み |

**主要処理フロー**:
1. **397-398行目**: `bufferlength=200`, `updateperiod=100` でデフォルト値設定
2. **663-667行目**: config.iniから`#bufferlength:`と`#updateperiod:`を読み込み、max関数でバリデーション
3. **771行目**: `BASS_Init -1,44100,0,hwnd` でBASSエンジン初期化
4. **774-776行目**: `BASS_SetConfig 1,updateperiod`, `BASS_SetConfig 0,bufferlength`, `BASS_SetConfig 24,2`

#### Step 3: レーザー遅延補正を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | laserdelay0の計算 |

**主要処理フロー**:
- **41行目**: `laserdelay0_orig = bufferlength - soundfx_delay - GLOBAL_SOUNDFX_DELAY`

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

```
kshootmania.hsp (アプリ起動)
    |
    +-- bufferlength=200, updateperiod=100 (デフォルト値)
    +-- config.ini読み込み -> bufferlength, updateperiod上書き
    +-- BASS_Init(-1, 44100, 0, hwnd)
    +-- BASS_SetConfig(1, updateperiod)
    +-- BASS_SetConfig(0, bufferlength)
    +-- BASS_SetConfig(24, 2)
    |
    +-- プレイ画面遷移時
            +-- BASS_SetConfig(4, 10000)
            +-- BASS_SetConfig(5, 10000)
            |
            +-- play_game_logic.hsp
                    +-- laserdelay0 = bufferlength - soundfx_delay - GLOBAL_SOUNDFX_DELAY
```

### データフロー図

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

config.ini                  設定値読み込み                   BASSエンジン設定
  #bufferlength:200 ----->  max(val, 6) ------+
  #updateperiod:100 ----->  max(val, 5) ------+--> BASS_SetConfig
                                               |
                                               +--> laserdelay0計算
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshootmania.hsp | `kshootmania.hsp` | ソース | デフォルト値設定、config.ini読み込み、BASS初期化、BASS_SetConfig呼び出し |
| play_game_logic.hsp | `src/scene/play/play_game_logic.hsp` | ソース | laserdelay0_origの計算 |
| play_key_input.hsp | `src/scene/play/play_key_input.hsp` | ソース | 一時停止再開時のupdateperiod再設定 |
| play_audio_effects.hsp | `src/scene/play/play_audio_effects.hsp` | ソース | updateperiod/5をエフェクト処理閾値として使用 |
| bass.as | `src/bass.as` | ソース | BASS_SetConfig APIバインディング |
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | エディタ側でも同様のバッファ設定を使用 |
