# 機能設計書 82-フルスクリーン・ウィンドウ設定

## 概要

本ドキュメントは、K-ShootManiaにおけるフルスクリーン/ウィンドウモード切替、ウィンドウサイズ選択、フルスクリーン解像度選択の設定機能の設計を記述する。オプション設定画面のページ0(画面設定)に含まれる項目である。

### 本機能の処理概要

**業務上の目的・背景**：K-ShootManiaはさまざまなモニタ解像度を持つPC環境で動作する音楽ゲームであり、プレイヤーの環境に適した表示モードの選択が必要である。フルスクリーンモードはレイテンシの低減と没入感の向上に寄与し、ウィンドウモードは他アプリケーションとの並行利用を可能にする。ウィンドウサイズとフルスクリーン解像度の多段階選択により、多様なハードウェア環境への対応を実現する。

**機能の利用シーン**：オプション設定画面（pagenow=0）でselnow=0(フルスクリーン切替)、selnow=1(ウィンドウサイズ)、selnow=2(フルスクリーン解像度)を選択し、左右キーで値を変更する。設定変更後Escキーで画面を閉じると、config.iniに保存され、解像度変更が即座に反映される。

**主要な処理内容**：
1. fullscr変数による0(ウィンドウ)/1(フルスクリーン)の切替
2. windowsize配列によるウィンドウモード時の解像度選択（320x240〜1280x1024の10段階）
3. fullscrsize配列によるフルスクリーンモード時の解像度選択（640x480〜1920x1200の10段階）
4. 設定値のconfig.iniへの保存
5. 設定変更時の画面モード切替(chgdisp/screen/bgscr)とテクスチャキャッシュのクリア・再生成

**関連システム・外部連携**：HSP3ランタイム(screen/bgscr/chgdisp命令)、Windows API(ディスプレイモード変更)

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | オプション設定画面 | 主画面 | fullscr変数によるフルスクリーン/ウィンドウ切替、windowsize/fullscrsizeの解像度選択 |
| 1 | タイトル画面 | 遷移先画面 | Escキー押下でSCENE_TITLEへ遷移、設定変更時のimgrefresh=1 |

## 機能種別

設定変更 / 画面制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| fullscr | int | Yes | フルスクリーンフラグ(0:ウィンドウ/1:フルスクリーン) | 0 or 1 |
| windowsize | int配列[2] | Yes | ウィンドウサイズ [幅,高さ] | プリセット値のみ |
| fullscrsize | int配列[2] | Yes | フルスクリーン解像度 [幅,高さ] | プリセット値のみ |

### 入力データソース

- オプション設定画面上の左右キー操作
- config.iniからの初期値読み込み

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| fullscr | int | フルスクリーンフラグ |
| windowsize | int配列 | ウィンドウサイズ [幅,高さ] |
| fullscrsize | int配列 | フルスクリーン解像度 [幅,高さ] |
| scrsize_w | int | 実効画面幅 |
| scrsize_h | int | 実効画面高さ |

### 出力先

- config.ini（fullscr, windowsize, fullscrsize設定値）
- 画面表示モード（即座に反映）

## 処理フロー

### 処理シーケンス

```
1. 値変更操作（左右キー）
   ├─ selnow=0: fullscr切替（0⇔1）
   ├─ selnow=1: windowsizeの段階的変更
   └─ selnow=2: fullscrsizeの段階的変更
2. 表示更新
   └─ 現在値をテキスト表示（例: "1280x720", "WINDOW", "FULL SCREEN"）
3. Esc押下時の保存・反映
   ├─ *saveconfig呼び出しでconfig.iniに保存
   └─ 解像度変更検出時
       ├─ フルスクリーン: chgdisp 1 + bgscr
       ├─ ウィンドウ: screen命令
       ├─ テクスチャキャッシュ削除・再生成
       └─ imgrefresh=1設定
```

### フローチャート

```mermaid
flowchart TD
    A[オプション画面 pagenow=0] --> B{selnow?}
    B -->|0| C[fullscr: 0⇔1切替]
    B -->|1| D[windowsize: 段階的変更]
    B -->|2| E[fullscrsize: 段階的変更]
    C --> F[表示更新]
    D --> F
    E --> F
    F --> G{Esc押下?}
    G -->|No| B
    G -->|Yes| H[*saveconfig呼び出し]
    H --> I{解像度変更あり?}
    I -->|No| J[SCENE_TITLEへ遷移]
    I -->|Yes| K[画面モード切替]
    K --> L[キャッシュ削除・再生成]
    L --> M[imgrefresh=1]
    M --> J
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-82-01 | fullscr範囲制限 | min(fullscr+1,1)とmax(fullscr-1,0)で0-1に制限 | 左右キー操作時 |
| BR-82-02 | ウィンドウサイズプリセット | 320x240/480x320/480x360/512x384/580x435/640x480/800x600/1024x768/1280x720/1280x1024の10段階 | selnow=1操作時 |
| BR-82-03 | フルスクリーンサイズプリセット | 640x480/800x600/1024x600/1024x768/1280x720/1280x800/1280x1024/1366x768/1920x1080/1920x1200の10段階 | selnow=2操作時 |
| BR-82-04 | 解像度変更検出 | fullscr変更、scrsize_w/scrsize_h変更、lowquality変更のいずれかで画面再構築 | Esc押下時 |
| BR-82-05 | キャッシュクリア | 解像度変更時にcache/ディレクトリ配下のファイルを全削除・再作成 | 解像度変更検出時 |

### 計算ロジック

ウィンドウサイズの段階遷移は、現在の幅・高さの比較演算で次のプリセットに遷移する。右キーで大きい解像度へ、左キーで小さい解像度へ移動する。

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

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

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

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 設定保存 | config.ini | READ/WRITE | fullscr, windowsize, fullscrsize値の保存 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | キャッシュディレクトリ作成失敗 | ファイルシステムエラー | whileループで100ms間隔リトライ |

### リトライ仕様

キャッシュディレクトリ(cache/)の作成はwhileループで繰り返しリトライされる（option.hsp内ではなくkshootmania.hsp内のEsc処理で実行）。

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

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

## パフォーマンス要件

- 解像度変更時にテクスチャキャッシュの全削除・再生成が発生するため、一時的な処理遅延が生じる
- blackout 500による500msフェードアウト演出

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

特になし。

## 備考

- fullscrpとlowqualitypに変更前の値を保持し、Esc押下時に変更有無を判定する
- 画面モード切替後はタイトル画面に遷移し、テクスチャの再読み込み(imgrefresh=1)が行われる
- デフォルト値: fullscr=0(ウィンドウ), windowsize=640x480, fullscrsize=1280x720

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshootmania.hsp | `kshootmania.hsp` | **223-225行目**: fullscrsize初期化、**283行目**: lowquality初期化 |

**読解のコツ**: fullscr, windowsize, fullscrsizeはグローバル変数で、config.ini読み込み時に上書きされる。dim宣言なしのため型は暗黙的にint。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | option.hsp | `src/scene/option.hsp` | **1行目**: on_update_option関数定義、**493行目以降**: pagenow=0の描画処理 |

**主要処理フロー**:
1. **188-212行目**: 左キー押下時のウィンドウサイズ段階的縮小
2. **213-234行目**: 左キー押下時のフルスクリーンサイズ段階的縮小
3. **340-363行目**: 右キー押下時のウィンドウサイズ段階的拡大
4. **364-385行目**: 右キー押下時のフルスクリーンサイズ段階的拡大
5. **499-500行目**: fullscr値の表示（WINDOW/FULL SCREEN）
6. **505行目**: ウィンドウサイズの表示

#### Step 3: Esc押下時の保存・画面切替を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | option.hsp | `src/scene/option.hsp` | **1061-1158行目**: Esc押下時の保存と画面モード切替処理 |

**主要処理フロー**:
- **1081行目**: *saveconfig呼び出し
- **1089行目**: 解像度変更検出条件
- **1090-1094行目**: フルスクリーンモード切替(chgdisp 1, bgscr)
- **1096-1099行目**: ウィンドウモード切替(chgdisp 1復帰, screen)
- **1101行目**: *refreshgetsize呼び出し（サイズ計算関数の更新）
- **1102行目**: imgrefresh=1設定
- **1103-1157行目**: キャッシュディレクトリの削除と再作成

#### Step 4: config.ini保存処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | kshootmania.hsp | `kshootmania.hsp` | **1299-1500行目**: *saveconfigサブルーチン |

**主要処理フロー**:
- **1306行目**: fullscr設定の検出
- **1307行目**: windowsize設定の検出
- **1308行目**: fullscrsize設定の検出
- **1372-1377行目**: fullscr, windowsize, fullscrsizeの書き込み

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

```
on_update_option (option.hsp:1)
    │
    ├─ 値変更処理 (左右キー)
    │      ├─ fullscr切替 (188-190行目, 340-341行目)
    │      ├─ windowsize変更 (192-212行目, 343-363行目)
    │      └─ fullscrsize変更 (214-234行目, 365-385行目)
    │
    ├─ 表示処理 (pagenow=0)
    │      └─ *drawconfigitem (1200-1207行目)
    │
    └─ Esc押下時処理 (1061-1158行目)
           ├─ *saveconfig (kshootmania.hsp:1299)
           │      └─ notesave "config.ini"
           ├─ chgdisp / bgscr / screen (画面モード切替)
           ├─ *refreshgetsize
           ├─ キャッシュ削除・再作成
           └─ blackout 500 (フェードアウト)
```

### データフロー図

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

左右キー操作        ───> fullscr/windowsize/       ───> 画面表示更新
                         fullscrsize変更

config.ini          ───> 初期値読み込み            ───> グローバル変数設定
(起動時)                  (488-499行目)

Escキー押下         ───> *saveconfig               ───> config.ini更新
                         画面モード切替                  画面解像度変更
                         キャッシュ再構築                テクスチャ再読み込み
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| option.hsp | `src/scene/option.hsp` | ソース | オプション設定画面のメイン処理 |
| kshootmania.hsp | `kshootmania.hsp` | ソース | 変数初期化・config.ini読み込み・保存処理 |
| config.ini | `config.ini` | 設定 | ゲーム設定ファイル |
| bg.jpg | `imgs/bg.jpg` | リソース | オプション画面背景画像 |
| config_item.gif | `imgs/config_item.gif` | リソース | 設定項目表示画像 |
| config_item_0.gif | `imgs/config_item_0.gif` | リソース | ページ0設定項目ラベル画像 |
| config_item_cur.gif | `imgs/config_item_cur.gif` | リソース | 選択カーソル画像 |
