# rustraight 機能辞典
rustraight が公開している全 public API を、カテゴリ別に列挙した辞典です。
- **ライブラリ利用者向け**: 関数シグネチャと説明を引く辞典として使えます。
- **開発者向け**: 各項目に動作確認の**状態**と**確認方法**を持たせています。未確認の項目から順に `examples/` 配下へ確認用サンプルを作り、確認が取れたら状態を ✅ に更新していく運用を想定しています。
> ソース: `src/*.rs` の `pub` 宣言と doc comment を基準に作成（2026-07 時点、v0.5.2）。`pub(crate)` 以下の内部実装（`registry.rs` / `util.rs` / `window/geometry.rs` など）は利用者から呼べないため対象外です。
## 凡例
| ⬜ | 未確認 |
| ✅ | 動作確認済み |
| 目視 | 画面に描かれた結果を見て確認する |
| 目視+操作 | キー/マウス/パッド操作をしながら画面の反応で確認する |
| 耳 | 音声出力を聞いて確認する |
| ログ | コンソール出力（デバッグビルド）を見て確認する |
| 自動テスト可 | ウィンドウ/GPU/デバイス無しで `cargo test` により検証できる（要ウィンドウ系より優先して着手しやすい） |
## 目次
1. [初期化 / ウィンドウ](#1-初期化--ウィンドウ)
2. [画像・スプライト](#2-画像スプライト)
3. [図形描画](#3-図形描画)
4. [ブレンド / マスク](#4-ブレンド--マスク)
5. [サブスクリーン](#5-サブスクリーン)
6. [入力 - キーボード](#6-入力---キーボード)
7. [入力 - マウス](#7-入力---マウス)
8. [入力 - ゲームパッド](#8-入力---ゲームパッド)
9. [サウンド](#9-サウンド)
10. [テキスト](#10-テキスト)
11. [オーバーレイウィンドウ](#11-オーバーレイウィンドウ)
12. [デバッグログ](#12-デバッグログ)
13. [乱数](#13-乱数)
---
## 1. 初期化 / ウィンドウ
**確認用サンプル:** `examples/01_window.rs` (`cargo run --example 01_window`)
| ✅ | `init(config: WindowConfig)` | Win32 ウィンドウ・wgpu デバイスを構築し初期化する。以降の全 API はこの呼び出し後にのみ使える | 目視 |
| ✅ | `advance_frame() -> bool` | 1フレーム進める（入力確定→GPU描画→メッセージ処理）。ウィンドウが閉じられると `false` | 目視+操作 |
| ✅ | `delta_time() -> f32` | 前フレームからの経過秒数 | 目視（表示して確認） |
| ✅ | `elapsed_time() -> f64` | 起動からの累計経過秒数 | 目視（表示して確認） |
| ✅ | `set_window_position(x: i32, y: i32)` | ウィンドウの画面上の位置を移動する | 目視 |
| ✅ | `window_position() -> (i32, i32)` | ウィンドウの画面上の位置を取得する | 目視（表示して確認） |
| ✅ | `set_window_size(w: i32, h: i32)` | ウィンドウのクライアント領域サイズを変更する | 目視 |
| ✅ | `window_size() -> (i32, i32)` | ウィンドウのクライアント領域サイズを取得する | 目視（表示して確認） |
| ✅ | `set_screen_size(w: i32, h: i32)` | 仮想解像度（描画座標系）を変更する | 目視 |
| ✅ | `screen_size() -> (i32, i32)` | 仮想解像度を取得する | 目視（表示して確認） |
| ✅ | `show_cursor(visible: bool)` | マウスカーソルの表示/非表示を切り替える | 目視 |
| ✅ | `MAIN_SCREEN: u32 = 0` | メインウィンドウを示す描画ターゲット定数 | draw_* 系と合わせて確認 |
### 型: `WindowConfig`
`init()` に渡す設定。`..Default::default()` で未指定項目を埋められる。
| `title` | `String` | `"Window"` | ウィンドウタイトル |
| `width` / `height` | `i32` | `800` / `600` | ウィンドウサイズ |
| `screen_width` / `screen_height` | `i32` | `800` / `600` | 仮想解像度（省略時は width/height） |
| `resizable` | `bool` | `true` | リサイズ可否 |
| `vsync` | `bool` | `true` | 垂直同期 |
| `decorations` | `bool` | `true` | タイトルバー等の装飾 |
| `transparent` | `bool` | `false` | ウィンドウ背景の透過（DX12 DirectComposition） |
| `topmost` | `bool` | `false` | 常に最前面表示 |
| `font_path` | `Option<String>` | `None` | デフォルトフォントファイルパス（`None` ならシステムフォント） |
| `font_size` | `u32` | `16` | デフォルトフォントサイズ |
| `overlay_enabled` | `bool` | `false` | オーバーレイウィンドウを有効化 |
各フィールドは組み合わせが多いため、`transparent` / `topmost` / `resizable` / `decorations` / `vsync` は個別に ON/OFF したサンプルで確認するのが効率的です。
---
## 2. 画像・スプライト
**確認用サンプル:** `examples/03_sprites.rs` (`cargo run --example 03_sprites`)
要アセット: `検証素材/images/{sprite.png, spritesheet.png, photo.jpg}`(準備済み)
| ✅ | `load_image(path: &str) -> u32` | 画像ファイル（WIC 経由: PNG/JPEG/BMP/TIFF/GIF/WebP等）を読み込みハンドルを返す。失敗時は代替スプライト（8x8マゼンタ）を返す | 目視（正常系・失敗系の両方） |
| ✅ | `load_div_image(path: &str, count: usize, tile_w: i32, tile_h: i32) -> Vec<u32>` | スプライトシートをタイル単位で分割ロードする。タイル数より `count` が多い場合は代替スプライトで埋める | 目視 |
| ⬜ | `free_image(handle: u32)` | 指定ハンドルの画像を解放する | 解放後の再描画で消えることを目視 |
| ⬜ | `free_all_images()` | 全画像を解放する | 同上 |
| ⬜ | `image_size(handle: u32) -> (i32, i32)` | スプライト/サブスクリーンのサイズを取得する（無効ハンドルは `(0,0)`） | 目視（表示して確認） |
| ✅ | `draw_image(target: u32, x: i32, y: i32, handle: u32)` | 等倍・無回転でスプライトを描画する | 目視 |
| ✅ | `draw_image_ex(target: u32, x: i32, y: i32, handle: u32, params: DrawImageParams)` | 拡大縮小・回転・反転・アルファ指定つきで描画する | 目視 |
### 型: `DrawImageParams`
`draw_image_ex` / `overlay_draw_image_ex` に渡す拡張パラメータ。
| `scale_x` / `scale_y` | `f32` | `1.0` | 拡大率 |
| `rotation` | `f32` | `0.0` | 回転角（度数法） |
| `alpha` | `f32` | `1.0` | 不透明度 (0.0〜1.0) |
| `flip_x` / `flip_y` | `bool` | `false` | 反転 |
各フィールドを単独で振ったサンプル（スケールのみ、回転のみ…）を1画面に並べると一度に確認できます。
---
## 3. 図形描画
**確認用サンプル:** `examples/02_shapes.rs` (`cargo run --example 02_shapes`)
| ✅ | `draw_fill(target: u32, color: Color)` | ターゲット全体を単色で塗りつぶす | 目視 |
| ⬜ | `draw_pixel(target: u32, x: i32, y: i32, color: Color)` | 1ピクセルを描画する | 目視（拡大して確認） |
| ✅ | `draw_line(target: u32, x1, y1, x2, y2: i32, color: Color)` | 直線を描画する | 目視 |
| ✅ | `draw_rectangle(target: u32, x, y, w, h: i32, color: Color, filled: bool)` | 矩形を描画する（塗り/枠線） | 目視（両方の filled 値） |
| ✅ | `draw_circle(target: u32, cx, cy, radius: i32, color: Color, filled: bool)` | 円を描画する（塗り/枠線） | 目視（両方の filled 値） |
| ✅ | `draw_triangle(target: u32, x1,y1,x2,y2,x3,y3: i32, color: Color, filled: bool)` | 三角形を描画する（塗り/枠線） | 目視（両方の filled 値） |
| ✅ | `clear(target: u32)` | 描画コマンドキューをクリアする | 目視 |
### 型: `Color`
`r, g, b, a: u8` の RGBA カラー。
| `Color::rgb(r, g, b) -> Color` | 不透明色を作る（`a=255`） | **自動テスト可**（各フィールド値の検証） |
| `Color::rgba(r, g, b, a) -> Color` | アルファ指定で色を作る | **自動テスト可** |
| `Color::WHITE/BLACK/RED/GREEN/BLUE/YELLOW/CYAN/MAGENTA` | 定義済み定数 | **自動テスト可**（値が期待通りか） |
`Color` はウィンドウ非依存の純粋なデータ型のため、ここだけは `cargo test` で他項目より先に自動検証できます。
---
## 4. ブレンド / マスク
**確認用サンプル:** `examples/04_blend_mask.rs` (`cargo run --example 04_blend_mask`)
要アセット: `検証素材/images/{sprite.png, mask.png}`(準備済み)
| ⬜ | `set_blend(blend: BlendMode)` | 以後の `draw_image`/`draw_image_ex` の合成モードを設定する | 目視（重ね描きで確認） |
| ✅ | `set_mask(x: i32, y: i32, handle: u32)` | 以後の画像描画にマスク（アルファ形状マスク）を適用する | 目視 |
| ⬜ | `reset_mask()` | マスクを解除する | 目視 |
### 型: `BlendMode`
`Normal`（既定） / `Add`（加算） / `Mul`（乗算） の3種。3つを同一シーンで並べて比較すると確認しやすい。
---
## 5. サブスクリーン
**確認用サンプル:** `examples/05_subscreen.rs` (`cargo run --example 05_subscreen`)
要アセット: `検証素材/images/sprite.png`(準備済み)
| ✅ | `create_screen(w: i32, h: i32) -> u32` | オフスクリーンのレンダーターゲットを作成し、スプライトとしても使える画像ハンドルを返す | 目視（サブスクリーンへ描画→メインへ貼り付け） |
サブスクリーンは他の全 `draw_*` の `target` 引数として使えるため、単体では動作確認にならず「サブスクリーンに図形/スプライト/テキストを描いてメインに貼る」一連の流れで確認する必要があります。
---
## 6. 入力 - キーボード
**確認用サンプル:** `examples/06_keyboard.rs` (`cargo run --example 06_keyboard`)
| ✅ | `is_pressed(key: KeyCode) -> bool` | 指定キーが押されている間 `true` | 目視+操作 |
| ✅ | `is_just_pressed(key: KeyCode) -> bool` | 押した瞬間だけ `true` | 目視+操作 |
| ✅ | `is_released(key: KeyCode) -> bool` | 離した瞬間だけ `true` | 目視+操作 |
### 型: `KeyCode`
約95種類のキーを表す enum（アルファベット26 / 数字10 / テンキー16 / ファンクションF1-F24 / カーソル・ナビゲーション10 / 修飾キー8 / 編集キー6 / 記号11 など）。1つずつ個別に確認するのは非効率なので、**「押されたキーの名前を画面にログ表示する」1本のサンプル**で全キーを横断的に確認するのが効率的です（キーボードにある物理キーだけ実際に押せる点に注意）。
---
## 7. 入力 - マウス
**確認用サンプル:** `examples/07_mouse.rs` (`cargo run --example 07_mouse`)
| ✅ | `mouse_position() -> (i32, i32)` | 現在のカーソル座標（仮想スクリーン座標） | 目視 |
| ✅ | `mouse_delta() -> (i32, i32)` | 前フレームからの移動量 | 目視+操作 |
| ✅ | `is_mouse_pressed(btn: MouseButton) -> bool` | 押している間 `true` | 目視+操作 |
| ✅ | `is_mouse_just_pressed(btn: MouseButton) -> bool` | 押した瞬間だけ `true` | 目視+操作 |
| ✅ | `is_mouse_released(btn: MouseButton) -> bool` | 離した瞬間だけ `true` | 目視+操作 |
| ✅ | `mouse_wheel() -> i32` | ホイール回転量（上=正、1ノッチ=120） | 目視+操作 |
`MouseButton`: `Left` / `Right` / `Middle` の3種。
---
## 8. 入力 - ゲームパッド
**確認用サンプル:** `examples/08_gamepad.rs` (`cargo run --example 08_gamepad`)
| ⬜ | `is_pad_pressed(pad_id: usize, btn: PadButton) -> bool` | 押している間 `true` | 目視+操作（実機コントローラー必須） |
| ⬜ | `is_pad_just_pressed(pad_id: usize, btn: PadButton) -> bool` | 押した瞬間だけ `true` | 目視+操作 |
| ⬜ | `is_pad_released(pad_id: usize, btn: PadButton) -> bool` | 離した瞬間だけ `true` | 目視+操作 |
| ⬜ | `pad_axis(pad_id: usize, axis: PadAxis) -> f32` | 指定軸の値 (-1.0〜1.0) | 目視+操作 |
| ⬜ | `is_pad_connected(pad_id: usize) -> bool` | 接続中かどうか | 目視（抜き差しして確認） |
| ⬜ | `pad_count() -> usize` | 接続中のコントローラー数 | 目視（抜き差しして確認） |
`PadButton`（16種）: `South/East/West/North`, `LBumper/RBumper`, `LTrigger/RTrigger`, `Select/Start`, `LThumb/RThumb`, `DPadUp/Down/Left/Right`。
`PadAxis`（6種）: `LeftStickX/Y`, `RightStickX/Y`, `LeftTrigger/RightTrigger`。
内部で **XInput**（Xbox系）と **DirectInput**（それ以外のUSBコントローラー）の2バックエンドを使い分けているため、可能であれば両方のタイプのコントローラーで確認するのが望ましい（DirectInput は300フレームごとに新規デバイスを再列挙する仕様があるため、抜き差し後すぐには反映されない場合がある点に留意）。
---
## 9. サウンド
**確認用サンプル:** `examples/10_sound.rs` (`cargo run --example 10_sound`)
要アセット: `検証素材/sounds/{se_16bit.wav, se_8bit.wav, bgm.ogg}`(準備済み。`se.wav`は32bit float形式で非対応フォーマットの失敗ハンドリング確認用)
| ✅ | `load_sound(path: &str) -> u32` | WAV(PCM 8/16-bit) または OGG Vorbis を読み込む。失敗時は `0` | 耳＋ログ（失敗系はログ確認） |
| ✅ | `play_sound(handle: u32, looping: bool)` | 再生する（`looping=true` でループ）。再生中に呼ぶと最初から再生し直す | 耳 |
| ✅ | `stop_sound(handle: u32)` | 再生を停止する | 耳 |
| ✅ | `set_volume(handle: u32, volume: f32)` | 音量を設定する (0.0〜1.0) | 耳 |
| ✅ | `free_sound(handle: u32)` | 音声データを解放する（再生中なら停止してから） | 耳（解放後に再生されないこと） |
| ✅ | `free_all_sounds()` | 全音声を解放する | 同上 |
対応フォーマットが2系統（WAV 8bit / WAV 16bit / OGG Vorbis）あるため、各フォーマットのファイルを最低1つずつ用意して確認する必要があります。
---
## 10. テキスト
**確認用サンプル:** `examples/09_text.rs` (`cargo run --example 09_text`)
要アセット: `検証素材/fonts/{Mamelon-3.5-Hi-Regular.otf, YDWaosagi.otf}`(準備済み)
| ✅ | `load_font(path: &str, size: u32) -> u32` | TTF/OTF/TTC フォントを読み込む。失敗時は `0` | **自動テスト可**（読み込み成功/失敗の戻り値検証） |
| ✅ | `get_text_width(text: &str, font_id: u32) -> i32` | 描画時の幅（ピクセル）を返す | **自動テスト可**（既知フォント+文字列での戻り値検証） |
| ✅ | `draw_text(target: u32, x: i32, y: i32, text: impl AsRef<str>, color: Color)` | デフォルトフォントで描画する | 目視 |
| ✅ | `draw_text_ex(target: u32, x: i32, y: i32, text: impl AsRef<str>, color: Color, font: u32)` | 指定フォントで描画する | 目視 |
| ✅ | `set_font_file(path: &str)` | デフォルトフォントファイルを変更する（次回描画時に再ロード） | 目視 |
| ✅ | `set_font_size(size: u32)` | デフォルトフォントサイズを変更する（次回描画時に再ロード） | 目視 |
`load_font` / `get_text_width` は Win32 ウィンドウや GPU を必要とせず、フォントファイルさえあれば `cargo test` から直接呼べます（`init()` 不要）。テキスト系の中では最も自動化しやすい項目です。
日本語など複数バイト文字、同一（文字列+フォント+色）の組み合わせのテクスチャキャッシュ（240フレーム未使用で自動削除）についても、専用サンプルで確認すると良いでしょう。
---
## 11. オーバーレイウィンドウ
`WindowConfig.overlay_enabled = true` で有効化する、メインウィンドウ外（全画面）にも描画できる透過ウィンドウ。
**確認用サンプル:** `examples/11_overlay.rs` (`cargo run --example 11_overlay`)
要アセット: `検証素材/images/sprite.png`(準備済み)
| ✅ | `overlay_visible(visible: bool)` | オーバーレイの表示/非表示を切り替える | 目視 |
| ⬜ | `overlay_draw_image(x: i32, y: i32, handle: u32)` | スプライトをオーバーレイに描画する | 目視 |
| ⬜ | `overlay_draw_image_ex(x, y: i32, handle: u32, params: DrawImageParams)` | 拡張パラメータ付きで描画する | 目視 |
| ✅ | `overlay_draw_text(x, y: i32, text: impl AsRef<str>, color: Color)` | テキストをオーバーレイに描画する | 目視 |
| ⬜ | `overlay_blend_set(blend: BlendMode)` | オーバーレイのブレンドモードを設定する | 目視 |
| ✅ | `overlay_clear()` | オーバーレイの描画キューをクリアする | 目視 |
`draw_*` でメインウィンドウ外の座標に描画すると自動的にオーバーレイへフォールバックする仕様があるため、「意図的なオーバーレイ描画」と「フォールバックによる描画」の両方を分けて確認するのが望ましい。
---
## 12. デバッグログ
デバッグビルドのみ標準エラーに出力されるマクロ。リリースビルドでは出力コードごと除去される。
専用サンプルは無し。`03_sprites` / `09_text` / `10_sound` の意図的な失敗ケース（存在しないパス等）で `log_warn!` の出力を確認できる。
| ✅ | `log_info!(...)` | `[情報]` 接頭辞で出力 | ログ（`cargo run` と `cargo run --release` の両方で出ない/出ることを確認） |
| ✅ | `log_warn!(...)` | `[警告]` 接頭辞で出力 | ログ |
| ✅ | `log_error!(...)` | `[エラー]` 接頭辞で出力 | ログ |
---
## 13. 乱数
外部クレート（`rand` 等）に依存しない、`std` のみで実装した擬似乱数生成器（xorshift64*）。
**確認用サンプル:** `examples/12_rng.rs` (`cargo run --example 12_rng`)
| ✅ | `rand_range(min: i32, max: i32) -> i32` | `min..=max` の一様乱数を返す | 自動テスト可 |
| ✅ | `rand_f32() -> f32` | `0.0..1.0` の一様乱数を返す | 自動テスト可 |
| ✅ | `seed_rng(seed: u64)` | 乱数生成器のシードを明示的に設定する（テスト・リプレイの再現用） | 自動テスト可 |
---
## 推奨確認順（目安）
1. **初期化/ウィンドウ + 図形描画** — 他の全カテゴリの土台。ここが動かないと以降を目視確認できない
2. **画像・スプライト + ブレンド/マスク + サブスクリーン** — 描画系の主要機能
3. **入力（キーボード/マウス/ゲームパッド）** — 操作を伴うため単独サンプルで確認
4. **テキスト** — `load_font`/`get_text_width` は自動テスト化を先に済ませ、描画系のみ目視で残す
5. **サウンド** — 音声ファイル用意が必要なため後回しでも可
6. **オーバーレイウィンドウ + デバッグログ** — 他機能に依存する/優先度が低いため最後
このドキュメントの ⬜/✅ を更新しながら進めれば、README の「特徴」一覧とも1対1で対応が取れます。
## 現在の進捗（2026-07時点）
`examples/` に全13カテゴリ中12カテゴリ分のサンプルを作成済み（デバッグログのみ専用サンプル無し）。
各サンプルは自動起動テストにより「アセットの読み込みエラーが出ない／意図した失敗ケースだけ警告が出る」ことは確認済みだが、
描画結果の見た目や音声の聞こえ方といった**目視・耳による最終確認はまだ行われていない**。上記表の ⬜ は実際に実行して確認した後に ✅ へ更新すること。
| 1 | `01_window.rs` | ✅ コンパイル確認済み |
| 2 | `03_sprites.rs` | ✅ 実行確認済み（アセット読み込み正常、意図した失敗ケースのみ警告） |
| 3 | `02_shapes.rs` | ✅ コンパイル確認済み |
| 4 | `04_blend_mask.rs` | ✅ 実行確認済み（警告無し） |
| 5 | `05_subscreen.rs` | ✅ 実行確認済み（警告無し） |
| 6 | `06_keyboard.rs` | ✅ コンパイル確認済み |
| 7 | `07_mouse.rs` | ✅ コンパイル確認済み |
| 8 | `08_gamepad.rs` | ✅ コンパイル確認済み |
| 9 | `10_sound.rs` | ✅ 実行確認済み（アセット読み込み正常、se.wavのみ意図通り失敗） |
| 10 | `09_text.rs` | ✅ 実行確認済み（アセット読み込み正常、意図した失敗ケースのみ警告） |
| 11 | `11_overlay.rs` | ✅ 実行確認済み（警告無し） |
| 12 | `12_rng.rs` | ⬜ 未確認 |