ゲーム画面の表示画角制御 (ビューポート)¶
SDL3 ビルドのエンジンでは、外側ウインドウ ( surface ) の中に内側ゲーム画面を 任意のサイズ・位置・倍率で配置し、周囲の余白を背景色や壁紙画像で埋めることが できます。ゲーム本来の解像度を保ったままウインドウサイズに合わせてレターボックス 表示・整数倍拡大・センタリングなどを行いたいときに使います。
内部構造の詳細は src/core 側のガイドを参照:
対応ビルド
この機能は SDL ビルド ( __GENERIC__ ) でのみ 利用できます。3 つの
DrawDevice ( SDLDrawDevice / SDLOGL /
OGLDrawDevice ) すべてで動作します。
WINVER ビルドでは API が登録されず、従来の zoom ロック動作のままです。
概念モデル¶
[外側 surface] = Window.innerWidth / innerHeight = OS ウインドウ client
│ ビューポート設定 (fit / zoom / align / offset)
▼
[内側ゲーム] = primaryLayer のサイズ (TJS から setSize で指定)
- 外側 surface … Window.innerWidth / Window.innerHeight。Elements UI オーバレイもこの座標系です。
- 内側ゲーム … primaryLayer のサイズ。
primaryLayer.setSize(w, h)で決まり、 Window.setInnerSize とは独立です。 - 両者を一致させれば従来どおり全面等倍。異なるサイズにすると、設定に従って ゲームが surface 内へ配置され、余白が生じます。
マウス座標は配置に応じて自動的にゲーム論理座標へ補正されるため、どの fit/zoom でも 入力は正しくゲーム内部へ届きます。
fit 方式¶
| 値 | 動作 |
|---|---|
"contain" |
アスペクト維持で収まる最大 ( レターボックス )。既定 |
"cover" |
アスペクト維持で埋める最小 ( はみ出しは clip ) |
"fill" |
アスペクト無視で surface 全面へ引き伸ばし |
"none" |
原寸 ( 倍率 1.0 ) |
"integer" |
収まる範囲で最大の整数倍 ( 最低 1 倍、ドット等倍維持 ) |
"custom" |
Window.viewportZoom の倍率を使用 |
TJS API¶
Window クラスに以下のメンバーが追加されています。
プロパティ¶
| メンバー | 説明 |
|---|---|
| viewportFit | フィット方式 ( 文字列 )。既定 "contain" |
| viewportZoom | "custom" 時の倍率。既定 1.0 |
| viewportAlignX | 水平配置 0=左 / 0.5=中央 / 1=右 |
| viewportAlignY | 垂直配置 0=上 / 0.5=中央 / 1=下 |
| viewportOffsetX | 水平オフセット ( px ) |
| viewportOffsetY | 垂直オフセット ( px ) |
| viewportBgColor | 余白の背景色 0xRRGGBB |
メソッド¶
| メンバー | 説明 |
|---|---|
| setViewport(fit [,zoom [,alignX [,alignY [,offsetX [,offsetY]]]]]) | 配置をまとめて設定 |
| setViewportWallpaper(image [,fit [,alignX [,alignY]]]) | 余白の壁紙画像を設定 |
| clearViewportWallpaper() | 壁紙を解除 |
壁紙の image にはストレージ名 ( 文字列 ) のほか、Layer /
Bitmap オブジェクトを直接渡すこともできます ( 参照保持されます )。
使用例¶
var win = new Window();
win.setInnerSize(1280, 720); // 外側ウインドウ
var lay = new Layer(win, null); // primaryLayer
lay.setSize(640, 400); // 内側ゲーム解像度
win.add(lay);
win.viewportBgColor = 0xff203060; // 余白の色
win.viewportFit = "integer"; // 整数倍 (640x400 → 1280x800 は不可なので 1 倍)
// または 180% センタリング:
win.setViewport("custom", 1.8);
// 余白に壁紙 (ストレージ名でもオブジェクトでも可):
win.setViewportWallpaper("bg_pattern.png", "cover");
// win.setViewportWallpaper(myBitmap, "cover"); // Layer / Bitmap を直接渡す