# 機能設計書 86-Vsync設定

## 概要

本ドキュメントは、K-ShootManiaにおけるVsync(垂直同期)有効/無効の切替機能の設計を記述する。オプション設定画面のページ0(画面設定)のselnow=9として提供される。

### 本機能の処理概要

**業務上の目的・背景**：音楽ゲームではフレームレートの安定性が判定精度に直結する。Vsyncを有効にすると画面のティアリング（画面の断裂）を防止できるが、入力遅延が増加する可能性がある。逆にVsyncを無効にするとフレームレートが不安定になる場合があるが、入力遅延を最小化できる。プレイヤーの環境と好みに応じた選択を可能にする設定項目である。

**機能の利用シーン**：オプション設定画面のページ0でselnow=9を選択し、左右キーでVsyncの有効/無効を切り替える。

**主要な処理内容**：
1. vsync変数の0(無効)/1(有効)の切替
2. config.iniへのvsync値の保存
3. プレイ画面でのmod_d3d9vsync.hspによるD3D9 Vsync同期制御への反映

**関連システム・外部連携**：Direct3D9(mod_d3d9vsync.hsp)

**権限による制御**：特になし。全プレイヤーが変更可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | オプション設定画面 | 主画面 | vsync変数によるVsync有効(1)/無効(0)の切替 |

## 機能種別

設定変更 / グラフィックス制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| vsync | int | Yes | Vsyncフラグ(0:無効/1:有効) | 0 or 1 |

### 入力データソース

- オプション設定画面上の左右キー操作
- config.iniのvsync設定値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| vsync | int | Vsyncフラグ(0:無効/1:有効) |

### 出力先

- config.ini（vsync設定値）
- D3D9レンダリングパイプライン（プレイ時に参照）

## 処理フロー

### 処理シーケンス

```
1. 左キー押下時（pagenow=0, selnow=9）
   └─ vsync = 0 (無効)
2. 右キー押下時
   └─ vsync = 1 (有効)
3. 表示
   ├─ vsync=0: lang.3.14 (無効)
   └─ vsync=1: lang.3.15 (有効)
4. Esc押下時
   └─ *saveconfigでconfig.iniに保存
```

### フローチャート

```mermaid
flowchart TD
    A[selnow=9選択] --> B{左右キー?}
    B -->|左| C[vsync = 0]
    B -->|右| D[vsync = 1]
    C --> E[表示更新]
    D --> E
    E --> F{Esc押下?}
    F -->|No| B
    F -->|Yes| G[config.ini保存]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-86-01 | Vsync二値制御 | 左キーで0(無効)、右キーで1(有効)の直接代入 | 左右キー操作時 |
| BR-86-02 | デフォルト値 | vsync=0(無効) | 初回起動時 |
| BR-86-03 | プレイ時適用 | vsync値はプレイ画面でmod_d3d9vsync.hsp経由でD3D9に適用 | ゲームプレイ開始時 |

### 計算ロジック

特になし。二値のトグル操作。

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

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

### 操作別データベース影響一覧

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定保存 | config.ini | WRITE | vsync値の保存 |

## エラー処理

### エラーケース一覧

特になし。

### リトライ仕様

なし。

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

config.iniへの保存は*saveconfigサブルーチンによる一括書き込み。

## パフォーマンス要件

Vsync有効時はモニタのリフレッシュレートにフレームレートが同期される。無効時はフレームレートの上限が解放される。

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

特になし。

## 備考

- Vsync制御にはmod_d3d9vsync.hsp（サードパーティモジュール）が使用される
- Vsyncの効果はフルスクリーンモードでより顕著に現れる
- デフォルトは無効(vsync=0)

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | **343行目**: vsync=0のデフォルト値、**168行目**: mod_d3d9vsync.hspのインクルード |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | option.hsp | `src/scene/option.hsp` | **254-256行目**: 左キーでvsync=0、**405-407行目**: 右キーでvsync=1 |

**主要処理フロー**:
1. **254行目**: `vsync=0` - 左キーで無効化
2. **405行目**: `vsync=1` - 右キーで有効化
3. **575-580行目**: 表示処理（lang.3.14/lang.3.15）

#### Step 3: config保存を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshootmania.hsp | `kshootmania.hsp` | **639-640行目**: config.ini読み込み、**1479-1480行目**: config保存 |

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

```
on_update_option (option.hsp:1)
    │
    ├─ 左右キー処理 (selnow=9)
    │      └─ vsync = 0 or 1
    │
    ├─ 表示処理 (pagenow=0)
    │      └─ *drawconfigitem (有効/無効ラベル)
    │
    └─ Esc押下時
           └─ *saveconfig → config.ini保存

プレイ画面参照:
mod_d3d9vsync.hsp ──> vsync変数を参照してD3D9 Vsync制御
```

### データフロー図

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

左右キー操作        ───> vsync変更(0 or 1)         ───> 画面表示更新

config.ini          ───> vsync読み込み              ───> vsync設定
(起動時)                  (639-640行目)

vsync値             ───> mod_d3d9vsync.hsp          ───> D3D9 Vsync制御
(プレイ時)

Escキー押下         ───> *saveconfig               ───> config.ini更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| option.hsp | `src/scene/option.hsp` | ソース | Vsync設定の操作処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | 変数初期化・config読み込み・保存 |
| mod_d3d9vsync.hsp | `third_party/mod_d3d9vsync.hsp` | サードパーティ | D3D9 Vsync同期制御モジュール |
| config.ini | `config.ini` | 設定 | vsync設定値の保存 |
