# 機能設計書 114-表示設定

## 概要

本ドキュメントは、K-Shoot MANIA譜面エディタにおける表示設定機能の設計を記述する。2倍表示/X軸ズーム/1行あたり小節数変更/線の明るさ調整/アナログ詳細表示の各表示設定機能を提供する。

### 本機能の処理概要

譜面エディタの表示方法を制御し、制作者の好みや作業内容に応じて譜面の見え方を変更する機能群である。

**業務上の目的・背景**：譜面制作において、ノートの密集具合や配置パターンに応じて異なる表示スケールが必要となる。密集した箇所では拡大表示、全体像の確認時には縮小表示が求められるため、柔軟な表示制御を提供する。

**機能の利用シーン**：細かいノート配置時に2倍表示やX軸ズームで拡大する場面、全体構成を確認するために1行あたりの小節数を増やす場面、グリッド線を見やすくする場面、レーザーオブジェクトの配置精度を調整する場面で利用される。

**主要な処理内容**：
1. 2倍表示(CMD_VIEW_2X): ノート間隔を2倍に拡大(vzoomrate=2.0f)またはCtrl押下で0.5倍に縮小
2. X軸ズーム(CMD_VIEW_ZOOMX): 横方向を拡大表示(vzoomx=1)
3. 1行あたり小節数変更(CMD_VIEW_BARPERROW_2~5): 2/3/4/5小節から選択(vtate変数)
4. 線の明るさ(CMD_VIEW_LINEBRIGHT): グリッド線の色を明るくする(linebright=1)
5. アナログ詳細表示(CMD_TOOL_ANALOGDETAIL0~2): LASERオブジェクトの配置精度を標準/詳細/最詳細の3段階で制御

**関連システム・外部連携**：外部システムとの連携はない。

**権限による制御**：権限による制御はない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主画面 | 表示メニュー/ツールメニューからの各表示設定変更 |

## 機能種別

UI表示制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cmd | int | Yes | 表示設定コマンドID | CMD_VIEW_2X/ZOOMX/BARPERROW_*/LINEBRIGHT/CMD_TOOL_ANALOGDETAIL* |

### 入力データソース

- メニュー操作(表示メニュー/ツールメニュー)
- キーボードショートカット

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| vzoomrate | double | 縦方向ズーム倍率(0.5/1.0/2.0) |
| vzoomx | int | X軸ズームフラグ(0: 通常、1: 拡大) |
| vtate | int | 1行あたりの小節数(2/3/4/5) |
| linebright | int | 線の明るさフラグ(0: 通常、1: 明るい) |
| analogdetail | int | アナログ詳細レベル(0: 標準、1: 詳細、2: 最詳細) |

### 出力先

- エディタ内部変数(上記変数群)
- メニューのチェック状態
- 描画画面(表示変更として反映)

## 処理フロー

### 処理シーケンス

```
1. ユーザーが表示メニューまたはショートカットで設定を変更
   └─ 対応するCMDコマンドが発行される
2. コマンドハンドラで対応する変数を更新
   └─ vzoomrate/vzoomx/vtate/linebright/analogdetailの値変更
3. メニューのチェック状態を更新
   └─ CheckMenuItemで状態反映
4. 必要に応じてウィンドウサイズを変更
   └─ vtate変更時はscreenサイズ再計算
5. gosub *drawで描画を更新
   └─ 新しい表示設定で再描画
```

### フローチャート

```mermaid
flowchart TD
    A[表示設定コマンド] --> B{コマンド種別}
    B -->|2倍表示| C{Ctrl押下?}
    C -->|Yes| D[vzoomrate=0.5f]
    C -->|No| E[vzoomrate=2.0f]
    D --> F[描画更新]
    E --> F
    B -->|X軸ズーム| G[vzoomxトグル]
    G --> F
    B -->|小節数変更| H[vtate=N, screen再計算]
    H --> F
    B -->|線の明るさ| I[linebrightトグル]
    I --> F
    B -->|アナログ詳細| J[analogdetail=0/1/2]
    J --> F
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-114-01 | デフォルト小節数 | vtateのデフォルト値は3 | エディタ起動時 |
| BR-114-02 | 2倍表示切替 | トグル動作。ONの場合vzoomrate=2.0f、OFFの場合1.0f | CMD_VIEW_2X |
| BR-114-03 | Ctrl+2倍表示 | Ctrl押下時は0.5倍(縮小)になる | CMD_VIEW_2X+Ctrl |
| BR-114-04 | トレース制限 | 2倍/0.5倍表示時はトレース表示が無効化される | vzoomrate!=1.0f |
| BR-114-05 | 画面リサイズ | vtate変更時にウィンドウ高さが再計算される | CMD_VIEW_BARPERROW_* |
| BR-114-06 | config.ini保存 | vzoomx/linebright/vtate設定はconfig.iniに保存される | エディタ終了時 |
| BR-114-07 | アナログ排他選択 | アナログ詳細は3段階から1つのみ選択可能 | CMD_TOOL_ANALOGDETAIL* |

### 計算ロジック

- ウィンドウ高さ: `64 + vtate * vUNIT_MEASURE + SIZE_TOOLBAR_H` (650行目)
- 描画位置変換: `vzoom(value) = int(vzoomrate * value)` (241行目)

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

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

データベース操作はない。設定値はconfig.iniファイルに永続化される。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | エラーが発生する条件はない |

### リトライ仕様

リトライ処理はない。

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

トランザクション管理はない。

## パフォーマンス要件

- 表示設定変更は即座に描画に反映される必要がある
- vtate変更時はウィンドウリサイズとツールバー再作成が必要

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

セキュリティに関する考慮事項はない。

## 備考

- vUNIT_MEASURE=192(表示上の1小節あたりのピクセル数基準)
- vzoomrate関数はvzoom(value)として定義され、表示座標変換に広く使用される
- アナログ詳細表示はCtrl+Shiftの同時押しで一時的に最詳細モードに切り替えられる(analogdetail2マクロ)

---

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

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

### 推奨読解順序

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

表示設定に関わる変数群を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshooteditor.hsp | `kshooteditor.hsp` | **483行目**: `vtate=3` - デフォルト小節数 |
| 1-2 | kshooteditor.hsp | `kshooteditor.hsp` | **487行目**: `linebright=0` - 線の明るさ初期値 |
| 1-3 | kshooteditor.hsp | `kshooteditor.hsp` | **489-491行目**: vzoomrate/vzoomx初期値 |
| 1-4 | kshooteditor.hsp | `kshooteditor.hsp` | **493行目**: `vUNIT_MEASURE=192` - 表示単位 |
| 1-5 | kshooteditor.hsp | `kshooteditor.hsp` | **241行目**: `vzoom`関数定義 |

**読解のコツ**: vzoomrateはdouble型で倍率を保持し、vzoom関数で座標変換に使用される。vtateは1行に表示する小節数を意味する。

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

コマンド定義とメニュー登録を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | **117-124行目**: CMD_VIEW_*のenum定義 |
| 2-2 | kshooteditor.hsp | `kshooteditor.hsp` | **150-152行目**: CMD_TOOL_ANALOGDETAIL*のenum定義 |
| 2-3 | kshooteditor.hsp | `kshooteditor.hsp` | **714-726行目**: 表示メニュー項目追加 |
| 2-4 | kshooteditor.hsp | `kshooteditor.hsp` | **760-762行目**: アナログ詳細メニュー項目追加 |

#### Step 3: コマンドハンドラ処理を理解する

各表示設定コマンドの処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshooteditor.hsp | `kshooteditor.hsp` | **7018-7035行目**: CMD_VIEW_2X処理(vzoomrate切替) |
| 3-2 | kshooteditor.hsp | `kshooteditor.hsp` | **7040-7048行目**: CMD_VIEW_ZOOMX処理 |
| 3-3 | kshooteditor.hsp | `kshooteditor.hsp` | **7049-7084行目**: CMD_VIEW_BARPERROW_2~5処理 |
| 3-4 | kshooteditor.hsp | `kshooteditor.hsp` | **7085-7093行目**: CMD_VIEW_LINEBRIGHT処理 |
| 3-5 | kshooteditor.hsp | `kshooteditor.hsp` | **6948-6962行目**: CMD_TOOL_ANALOGDETAIL0~2処理 |

**主要処理フロー**:
- **7022-7025行目**: `if(ctrl_key=1): vzoomrate=0.5f / else: vzoomrate=2.0f` - 2倍/0.5倍切替
- **7028行目**: `if(vtrace=1):vtrace=-1` - 2倍表示時のトレース無効化
- **7050行目**: `vtate=2` → 7052行目: `screen 0,1194,64+vtate*vUNIT_MEASURE+SIZE_TOOLBAR_H` - ウィンドウリサイズ
- **7087-7088行目**: linebrightトグルとCheckMenuItem更新

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

```
*OnCommand (2191行目)
    |
    +-- CMD_VIEW_2X (7018行目)
    |       +-- Ctrl判定 → vzoomrate=0.5f/2.0f
    |       +-- posnow再計算
    |       +-- vtrace無効化
    |       +-- ツールバー更新
    |       +-- gosub *draw
    |
    +-- CMD_VIEW_ZOOMX (7040行目)
    |       +-- vzoomxトグル
    |       +-- gosub *draw
    |
    +-- CMD_VIEW_BARPERROW_2~5 (7049-7084行目)
    |       +-- vtate設定
    |       +-- screen (ウィンドウリサイズ)
    |       +-- gosub *refreshtitle
    |       +-- gosub *draw
    |       +-- gosub *createtoolbar
    |
    +-- CMD_VIEW_LINEBRIGHT (7085行目)
    |       +-- linebrightトグル
    |       +-- gosub *draw
    |
    +-- CMD_TOOL_ANALOGDETAIL0~2 (6948-6962行目)
            +-- analogdetail = 0/1/2
            +-- CheckMenuItem排他更新
```

### データフロー図

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

メニュー選択 --------+
ショートカットキー ---+--> 表示変数更新 -----------------> 描画画面更新
                          +-- vzoomrate (2倍表示)          ウィンドウサイズ変更
                          +-- vzoomx (X軸ズーム)           メニューチェック状態
                          +-- vtate (小節数)               config.ini保存
                          +-- linebright (線の明るさ)
                          +-- analogdetail (アナログ精度)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | エディタ本体。表示設定のコマンド定義・ハンドリング・描画反映を含む |
