# 機能設計書 115-トレース表示

## 概要

本ドキュメントは、K-Shoot MANIA譜面エディタにおけるトレース表示機能の設計を記述する。参考画像(別の譜面ファイル)のオーバーレイ表示、インポート、上下移動に対応する。

### 本機能の処理概要

別のKSH譜面ファイルを読み込み、現在編集中の譜面の背景に半透明でオーバーレイ表示する機能である。参考譜面を視覚的に確認しながら譜面制作を行うことができる。

**業務上の目的・背景**：譜面制作において、既存の譜面を参考にしながら新しい難易度の譜面を制作することがある。トレース機能により、参考譜面のノート配置パターンをオーバーレイ表示し、効率的な譜面制作を可能にする。

**機能の利用シーン**：同一楽曲の別難易度の譜面を制作する際に、元の難易度の譜面をトレースとして読み込む場面で利用される。Ctrl+Alt+Vで表示/非表示を切り替え、Ctrl+Alt+Oでファイル読み込みを行う。

**主要な処理内容**：
1. トレース表示/非表示(CMD_VIEW_TRACE): vtrace変数によるオーバーレイの表示切替
2. トレース読み込み(CMD_VIEW_TRACE_IMPORT): KSHファイルを読み込みBUF_TRACEバッファに描画
3. トレース位置初期化(CMD_VIEW_TRACE_SHIFTINIT): 表示位置を初期値(0)にリセット
4. トレース位置上移動(CMD_VIEW_TRACE_SHIFTUP): UNIT_MEASURE/editdiv単位で上に移動
5. トレース位置下移動(CMD_VIEW_TRACE_SHIFTDOWN): UNIT_MEASURE/editdiv単位で下に移動
6. トレース位置上移動(1小節)(CMD_VIEW_TRACE_SHIFTUPD): 1小節単位で上に移動
7. トレース位置下移動(1小節)(CMD_VIEW_TRACE_SHIFTDOWND): 1小節単位で下に移動

**関連システム・外部連携**：外部システムとの連携はない。KSH譜面ファイルの読み込み処理を内部で実行する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 譜面エディタ | 主画面 | 表示メニュー > トレースサブメニューからの各操作 |

## 機能種別

UI表示制御 / ファイル読み込み

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| cmd | int | Yes | トレースコマンドID | CMD_VIEW_TRACE/TRACE_IMPORT/TRACE_SHIFTINIT/SHIFTUP/SHIFTDOWN/SHIFTUPD/SHIFTDOWND |
| KSHファイル | file | No | トレース元のKSH譜面ファイル | インポート時にダイアログで選択 |

### 入力データソース

- メニュー操作(表示メニュー > トレース)
- キーボードショートカット(Ctrl+Alt+V, Ctrl+Alt+O)
- ファイルダイアログ(KSHファイル選択)

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| vtrace | int | トレース表示状態(0: 非表示、1: 表示、-1: 2倍表示中で一時無効) |
| vtracesh | int | トレース表示位置オフセット |
| BUF_TRACE | buffer | トレース描画用オフスクリーンバッファ(画像ID=11) |

### 出力先

- 描画画面(オーバーレイ表示)
- メニューのチェック状態

## 処理フロー

### 処理シーケンス

```
1. ユーザーがCtrl+Alt+Oまたはメニューでトレース読み込みを選択
   └─ CMD_VIEW_TRACE_IMPORT発行
2. ファイルダイアログでKSHファイルを選択
   └─ dialog "ksh",16 でファイル選択
3. 選択されたKSHファイルを解析
   └─ ノート・アナログ・BPM等のデータを一時配列に展開
4. BUF_TRACEバッファにトレース譜面を描画
   └─ ノート・レーザーを色分けして描画
5. vtrace=1に設定してオーバーレイ表示を有効化
   └─ 描画時にgcopy BUF_TRACEで重ね合わせ
6. ユーザーが位置調整コマンドでvtraceshを変更
   └─ SHIFTUP/DOWN: ±UNIT_MEASURE/editdiv、SHIFTUPD/DOWND: ±UNIT_MEASURE
```

### フローチャート

```mermaid
flowchart TD
    A[トレースコマンド] --> B{コマンド種別}
    B -->|表示切替| C{vzoomrate=1.0?}
    C -->|Yes| D[vtraceトグル]
    C -->|No| E[変更不可]
    B -->|インポート| F[ファイルダイアログ]
    F --> G[KSHファイル解析]
    G --> H[BUF_TRACEに描画]
    H --> I[vtrace=1]
    B -->|位置初期化| J[vtracesh=0]
    B -->|上移動| K[vtracesh+=UNIT_MEASURE/editdiv]
    B -->|下移動| L[vtracesh-=UNIT_MEASURE/editdiv]
    B -->|上移動1小節| M[vtracesh+=UNIT_MEASURE]
    B -->|下移動1小節| N[vtracesh-=UNIT_MEASURE]
    D --> O[gosub *draw]
    I --> O
    J --> O
    K --> O
    L --> O
    M --> O
    N --> O
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-115-01 | 2倍表示制限 | vzoomrate!=1.0f(2倍/0.5倍表示)時はトレース表示を有効にできない | CMD_VIEW_TRACE |
| BR-115-02 | 初期表示状態 | vtrace=1(表示)がデフォルト | エディタ起動時 |
| BR-115-03 | 移動量 | 上下移動はUNIT_MEASURE/editdivまたはUNIT_MEASURE単位 | SHIFTUP/DOWN/SHIFTUPD/DOWND |
| BR-115-04 | バッファサイズ | BUF_TRACEは41+9*2ピクセル幅、vUNIT_MEASURE*tate+1高さ | 初期化時 |
| BR-115-05 | 2倍表示連動 | 2倍表示有効時にvtrace=1→-1、解除時に-1→1に自動切替 | CMD_VIEW_2X |

### 計算ロジック

- トレース描画位置: `(tate-posnow*vtate-vyoko*vtate)*vUNIT_MEASURE+vtracesh` (2011行目)

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

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

データベース操作はない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ファイル不在 | 選択されたKSHファイルが存在しない | 処理を中断 |
| - | 空ファイル | ファイルサイズが0の場合 | 処理を中断 |

### リトライ仕様

リトライ処理はない。

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

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

## パフォーマンス要件

- トレース読み込み時にファイル解析とバッファ描画が必要で、大きな譜面では処理時間がかかる場合がある
- 表示自体はバッファのgcopyのみで高速

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

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

## 備考

- BUF_TRACEは定数11で定義されたオフスクリーンバッファ
- トレース読み込み時はdrawall=1フラグを設定して全ノートの描画を行う
- KSHファイルの解析処理はインポート時にのみ実行され、メイン描画ループとは独立

---

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

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

### 推奨読解順序

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

トレース表示に関わる変数とバッファを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | kshooteditor.hsp | `kshooteditor.hsp` | **194行目**: `#define BUF_TRACE 11` - トレースバッファID |
| 1-2 | kshooteditor.hsp | `kshooteditor.hsp` | **492行目**: `vtrace=1` - トレース表示初期値 |
| 1-3 | kshooteditor.hsp | `kshooteditor.hsp` | **125-130行目**: CMD_VIEW_TRACE~CMD_VIEW_TRACE_SHIFTDOWNDのenum定義 |
| 1-4 | kshooteditor.hsp | `kshooteditor.hsp` | **850行目**: `buffer BUF_TRACE,41+9*2,vUNIT_MEASURE*tate+1` - バッファ初期化 |

**読解のコツ**: vtraceは0/1/-1の3状態をとる。-1は2倍表示中に一時的に無効化された状態を表す。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | kshooteditor.hsp | `kshooteditor.hsp` | **703-712行目**: トレースサブメニュー項目追加 |
| 2-2 | kshooteditor.hsp | `kshooteditor.hsp` | **719行目**: 表示メニューへのトレースサブメニュー追加 |
| 2-3 | kshooteditor.hsp | `kshooteditor.hsp` | **9843-9847行目**: Ctrl+Alt+V/Oショートカット |

**主要処理フロー**:
1. **703行目**: トレースサブメニュー作成(newmenu)
2. **704行目**: トレース表示切替メニュー(CMD_VIEW_TRACE)
3. **706行目**: トレース読み込みメニュー(CMD_VIEW_TRACE_IMPORT)
4. **708-712行目**: トレース位置調整メニュー5種

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

各トレースコマンドの処理を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | kshooteditor.hsp | `kshooteditor.hsp` | **7094-7104行目**: CMD_VIEW_TRACE処理(表示切替) |
| 3-2 | kshooteditor.hsp | `kshooteditor.hsp` | **7105-7328行目**: CMD_VIEW_TRACE_IMPORT処理(ファイル読み込み・描画) |
| 3-3 | kshooteditor.hsp | `kshooteditor.hsp` | **8330-8343行目**: CMD_VIEW_TRACE_SHIFT*処理(位置調整) |
| 3-4 | kshooteditor.hsp | `kshooteditor.hsp` | **2008-2011行目**: 描画時のトレースオーバーレイ処理 |

**主要処理フロー**:
- **7096-7101行目**: vtrace=0/1のトグルとCheckMenuItem更新
- **7106行目**: `drawall=1` - トレースインポート時に全描画モードを設定
- **7112行目**: `dialog "ksh",16` - KSHファイル選択ダイアログ
- **7119-7138行目**: 一時配列の初期化(t_note, t_analog等)
- **8322行目**: `vtracesh=0` - インポート完了時の位置リセット
- **2008-2011行目**: `if((vtrace=1)&(vzoomrate=1.0f))` → gcopy BUF_TRACEで描画

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

```
*OnCommand (2191行目)
    |
    +-- CMD_VIEW_TRACE (7094行目)
    |       +-- vtraceトグル (0/1)
    |       +-- CheckMenuItem更新
    |       +-- gosub *draw
    |
    +-- CMD_VIEW_TRACE_IMPORT (7105行目)
    |       +-- dialog (ファイル選択)
    |       +-- KSHファイル解析
    |       +-- buffer BUF_TRACE (バッファ再作成)
    |       +-- ノート・レーザー描画
    |       +-- vtrace=1, vtracesh=0
    |
    +-- CMD_VIEW_TRACE_SHIFTINIT (8330行目) → vtracesh=0
    +-- CMD_VIEW_TRACE_SHIFTUP (8333行目) → vtracesh+=UNIT_MEASURE/editdiv
    +-- CMD_VIEW_TRACE_SHIFTDOWN (8336行目) → vtracesh-=UNIT_MEASURE/editdiv
    +-- CMD_VIEW_TRACE_SHIFTUPD (8339行目) → vtracesh+=UNIT_MEASURE
    +-- CMD_VIEW_TRACE_SHIFTDOWND (8342行目) → vtracesh-=UNIT_MEASURE

*draw (描画処理)
    +-- if vtrace=1 かつ vzoomrate=1.0f
            +-- gcopy BUF_TRACE (オーバーレイ描画)
```

### データフロー図

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

KSHファイル ---------+--> KSH解析 → BUF_TRACE描画 ------> オフスクリーンバッファ
位置調整コマンド ----+--> vtracesh更新 ------------------> 表示位置変更
表示切替コマンド ----+--> vtraceトグル ------------------> オーバーレイ表示/非表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| kshooteditor.hsp | `kshooteditor.hsp` | ソース | エディタ本体。トレースのコマンド定義・インポート・描画処理を含む |
| (トレース元KSHファイル) | ユーザー選択 | 入力データ | トレース表示対象の参考譜面ファイル |
