# 機能設計書 18-楽曲情報表示

## 概要

本ドキュメントは、K-Shoot MANIA の選曲画面における「楽曲情報表示」機能の設計を記述する。BPM・レベル・難易度ラベルなどの楽曲メタデータを選曲画面上に表示する機能である。

### 本機能の処理概要

本機能は、`*refreshsonginfo`サブルーチンにより、選曲画面のカーソル前後8曲分の楽曲情報パネルを生成・描画する。各楽曲エントリに対して、タイトル・アーティスト・BPM・レベル・難易度アイコン・フォルダ名・メダル・プレイカウントなどの情報を含むパネル画像を動的に生成する。

**業務上の目的・背景**：楽曲の基本情報(タイトル・難易度・レベル)を一覧表示することで、プレイヤーが楽曲を素早く識別し、適切な難易度で選曲できるようにする。

**機能の利用シーン**：選曲画面で楽曲リストが表示されている間、常にカーソル前後の楽曲情報パネルが表示される。カーソル移動・難易度変更・ソート変更時に再描画される。

**主要な処理内容**：
1. 表示範囲(selnow前後8曲)の各エントリについて情報パネルを生成
2. 難易度フォールバック: 利用可能な難易度への自動切替
3. エントリ種別(フォルダ/楽曲/コース)に応じた表示形式の切替
4. タイトル文字列長に応じたフォントサイズ自動調整
5. タイトル画像(title_img)対応: テキストの代わりに画像で表示
6. 難易度アイコン・レベル数値の描画
7. メダル画像・プレイカウント数値の描画

**関連システム・外部連携**：artlet(artlet2D)ライブラリによる画像処理・テキスト描画。

**権限による制御**：なし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 3 | 曲選択画面 | 主画面 | refreshsonginfoサブルーチンによるBPM・レベル・難易度ラベルの表示 |

## 機能種別

表示処理 / 画像生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| selnow | int | Yes | 現在のカーソル位置 | 0 <= selnow < mnum |
| levnow | int | Yes | 現在の難易度レベル | 0-3 |
| minfo | int[SONG_MAX][4][5] | Yes | 曲リスト情報配列 | - |
| minfostr | string[SONG_MAX][4][13] | Yes | 曲リスト文字列配列 | - |
| sorttype | int | Yes | ソートタイプ(0:通常, 1:レベル順) | 0-1 |
| sc/gr/md/pc | int[8] | Yes | スコア/グレード/メダル/プレイカウント配列 | - |

### 入力データソース

- メモリ上の配列(minfo, minfostr): `*refreshfilelist`で生成済みの曲リストデータ
- メモリ上の配列(sc, gr, md, pc): `*refreshscore`で生成済みのスコアデータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| 画像ID 2 | image | メイン楽曲情報パネル(選択中の曲) |
| 画像ID 21-27 | image | 前後楽曲情報パネル(7枚) |

### 出力先

- 画面表示: 選曲画面の楽曲情報パネルエリア

## 処理フロー

### 処理シーケンス

```
1. *refreshsonginfo開始
   └─ 難易度フォールバック(levnow -> levmn)
2. selnow-4 から selnow+3 までの8曲をループ
   a. 各曲の難易度フォールバック(levnow -> levmn2)
   b. エントリ種別判定(minfo.j.0.0)
      ├─ 負値(フォルダ系): フォルダ名パネル描画
      ├─ 4(コース): コース情報パネル描画
      └─ 0-3(楽曲): 楽曲情報パネル描画
   c. フォルダエントリ(-1,-2,-4,-5,-6,-7,-8,-9):
      └─ テンプレート画像(ID 29/92)にフォルダ名テキスト描画
   d. コースエントリ(4):
      ├─ テンプレート画像(ID 150/151)にタイトル・メダル・プレイカウント描画
      └─ title_img対応
   e. 楽曲エントリ(0-3):
      ├─ テンプレート画像(ID 11)にタイトルテキスト描画
      ├─ タイトル文字列長に応じたフォントサイズ自動調整
      ├─ title_img対応(画像表示)
      ├─ 難易度アイコン描画(ID 4)
      ├─ レベル数値描画(ID 5)
      ├─ メダル画像描画(ID 8)
      └─ プレイカウント描画(ID 10)
3. 選択中楽曲(画像ID 2)の詳細情報パネル生成
   ├─ タイトル(大サイズ)
   ├─ アーティスト名
   ├─ BPM表示
   ├─ information(説明文)表示
   ├─ 難易度アイコン・レベル
   ├─ メダル・プレイカウント
   └─ コースの場合: IMG_MSEL_COURSETEMP生成
```

### フローチャート

```mermaid
flowchart TD
    A[*refreshsonginfo開始] --> B[難易度フォールバック]
    B --> C[8曲ループ開始]
    C --> D{エントリ種別?}
    D -->|フォルダ| E[フォルダ名パネル描画]
    D -->|コース| F[コース情報パネル描画]
    D -->|楽曲| G[楽曲情報パネル描画]
    E --> H[フォントサイズ調整・テキスト描画]
    F --> I[タイトル・メダル・プレイカウント描画]
    G --> J[タイトル・難易度・レベル・メダル描画]
    H --> K[次の曲へ]
    I --> K
    J --> K
    K --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-18-1 | フォントサイズ自動調整 | タイトル文字数に応じて11-17pxの間でフォントサイズを自動調整 | タイトルテキスト描画時 |
| BR-18-2 | title_img優先 | title_imgパラメータが存在する場合はテキストの代わりに画像を表示 | 楽曲/コースエントリ表示時 |
| BR-18-3 | フォルダ表示形式 | フォルダ名に">>"(下位)または"<<"(上位)の矢印を付加 | フォルダエントリ表示時 |
| BR-18-4 | 難易度フォールバック | 現在の難易度が利用不可の場合、3->2->1->0の順でフォールバック | 常時 |
| BR-18-5 | レベル順ソート対応 | sorttype=1の場合は楽曲固有の難易度でスコア表示 | レベル順ソート時 |

### 計算ロジック

フォントサイズ自動調整:
```
文字数50超: 11px
文字数40超: 12px
文字数34超: 13px
文字数26超: 15px
それ以外:   17px
```

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

本機能ではデータベース操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | title_img不在 | タイトル画像ファイルが存在しない場合 | テキスト表示にフォールバック |

### リトライ仕様

なし。

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

なし。

## パフォーマンス要件

- 8枚の情報パネル画像を毎回再生成するため、描画コストが発生
- alDrawText_CalcRect_によるテキストサイズ計算が各パネルで実行される

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

特になし。

## 備考

- minfostr配列のインデックス: .0=フォルダパス, .1=レベル, .3=ジャケットパス, .5=ファイル名, .6=information, .8=タイトル, .10=title_img, .11=artist_img, .12=アイコンパス
- エントリ種別値: -1:フォルダ, -2:戻る, -3:区切り, -4:All, -5:All戻る, -6:Favorite, -7:Favorite戻る, -8:Courses, -9:Courses戻る, 0-3:楽曲(難易度), 4:コース

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | select.hsp | `src/scene/select.hsp` | minfostr配列の13要素の意味(0:パス, 1:レベル, 3:ジャケット, 5:ファイル名, 6:information, 8:タイトル, 10:title_img, 11:artist_img, 12:アイコン) |
| 1-2 | select.hsp | `src/scene/select.hsp` | minfo配列の種別値(-9〜-1, 0-4)の意味 |

**読解のコツ**: alDrawTextは指定領域にテキストを描画する関数。第6引数が水平配置(0:左, 1:中央)、第7引数が垂直配置。

#### Step 2: *refreshsonginfo を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | select.hsp | `src/scene/select.hsp` | 4057-4839行目の*refreshsonginfoサブルーチン |

**主要処理フロー**:
1. **4057-4096行目**: 難易度フォールバック(levnow -> levmn)
2. **4097-4103行目**: 表示範囲ループ(selnow-4 〜 selnow+3)
3. **4147-4231行目**: サブパネル描画(フォルダ/コース/楽曲の種別分岐)
4. **4232-4519行目**: メインパネル(選択中楽曲)の詳細描画
5. **4252-4256行目**: フォントサイズ自動調整ロジック
6. **4521-4523行目**: メダル画像描画
7. **4524-4529行目**: プレイカウント描画

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

```
*refreshsonginfo (4057行目)
    |
    +-- 難易度フォールバック (4057-4096行目)
    +-- 8曲ループ (4097行目)
    |       |
    |       +-- [フォルダエントリ] (4148-4178行目)
    |       |       +-- alCopyImageToImage(テンプレートコピー)
    |       |       +-- alDrawText(フォルダ名)
    |       |
    |       +-- [コースエントリ] (4179-4231行目)
    |       |       +-- alCopyImageToImage(テンプレートコピー)
    |       |       +-- alDrawText/alCreateImageByFile(タイトル/title_img)
    |       |       +-- alCopyImageToImage(メダル)
    |       |       +-- alStretchImageToImage(プレイカウント)
    |       |
    |       +-- [楽曲エントリ] (4232-4519行目)
    |               +-- alCopyImageToImage(テンプレートコピー)
    |               +-- alDrawText/alCreateImageByFile(タイトル/title_img)
    |               +-- alStretchImageToImage(難易度アイコン)
    |               +-- alStretchImageToImage(レベル)
    |               +-- alCopyImageToImage(メダル)
    |               +-- alStretchImageToImage(プレイカウント)
    |
    +-- [コース詳細] (4530-4676行目, minfo.*.0.0=4の場合)
            +-- .kcoファイル読み込み・IMG_MSEL_COURSETEMP生成
```

### データフロー図

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

minfo/minfostr配列 ----------> エントリ種別判定 -----------> 画像テンプレート選択
                                    |
sc/gr/md/pc配列 --------------> スコア/メダル取得 ---------> メダル/グレード画像
                                    |
minfostr.*.levmn.8(タイトル) -> フォントサイズ調整 ---------> 画像ID 2,21-27
minfostr.*.levmn.10(title_img) -> 画像読み込み ------------->    (情報パネル)
                                    |
テンプレート画像(ID 4,5,8,10,11) -> 合成描画 ------------->  選曲画面表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| select.hsp | `src/scene/select.hsp` | ソース | *refreshsonginfoサブルーチンによる楽曲情報パネル生成・描画 |
| テンプレート画像 | (メモリ上) | リソース | 画像ID 4(難易度), 5(レベル), 8(メダル), 10(数字), 11(楽曲パネル背景) |
