playdate.geometry.rect
playdate.geometry.rectは 軸に平行な矩形 を表す型で、回転していない普通の長方形です。
基本的には「x, y, width, height」の4値で表され、通常、x, y は左上座標で、width, height は大きさです。Playdate の rect は、当たり判定、描画範囲、UI領域、画像の部分領域など、かなり広く使います。
- playdate.geometry.rect
- 1. 生成・高速関数
- playdate.geometry.rect.new(x, y, width, height)
- playdate.geometry.rect.fast_intersection(x1, y1, w1, h1, x2, y2, w2, h2)
- playdate.geometry.rect.fast_union(x1, y1, w1, h1, x2, y2, w2, h2)
- 2. 位置・中心
- 3. 点や矩形を含むか
- 4. コピー・同一性・空判定
- 5. 位置移動
- 6. サイズ変更・余白調整
- 7. 重なり・交差・結合
- 8. 反転
- 9. 変換・展開
- 資料
- 関連ページ
1. 生成・高速関数
playdate.geometry.rect.new(x, y, width, height)
新しい playdate.geometry.rect を生成します。
local r = playdate.geometry.rect.new(10, 20, 50, 30)
上記コードは
の矩形を生成しています。
playdate.geometry.rect.fast_intersection(x1, y1, w1, h1, x2, y2, w2, h2)
2つの矩形の共通部分を、rect オブジェクトではなく4つの数値で返します。
- 返り値
- 交差していなければ (0, 0, 0, 0) が返ります。
- 重要ポイント
- これは intersection() より 約3倍速い と stub.lua にあります。
- その代わり、
- rect オブジェクトを作らない
- 引数も戻り値も数値だけ
- です。
- 向いている用途
- 毎フレーム大量に矩形交差を調べる
- 内部ループ
- パフォーマンス優先の処理
- 使いどころ
- たとえばタイルマップや多数の dirty rect を処理する場面です。
playdate.geometry.rect.fast_union(x1, y1, w1, h1, x2, y2, w2, h2)
2つの矩形を両方含む最小の矩形を、数値4つで返します。
- 返り値
- union() との違い
- union() は rect を返す
- fast_union() は数値で返す
- fast_union() の方が高速
- 向いている用途
- 再描画領域の統合
- 複数変更領域を1つにまとめる
- パフォーマンス重視の矩形統合
2. 位置・中心
rect:centerPoint()
矩形の中心点を playdate.geometry.point として返します。
local c = r:centerPoint()
- 用途
- UI要素の中央配置
- 中心基準での回転・スケール
- 矩形の重心的な参照点が欲しいとき
- 注意
- これは「幅・高さの半分の位置」を返すだけで、矩形の形を変えるわけではありません。
3. 点や矩形を含むか
rect:containsPoint(p) / rect:containsPoint(x, y)
指定した点が、その rect の中に入っているかを返します。
返り値は boolean です。
if r:containsPoint(100, 50) then
...
end
または
local p = playdate.geometry.point.new(100, 50)
if r:containsPoint(p) then
...
end
- 向いている用途
- マウスやカーソルが矩形内にあるか
- ボタンのホバー判定
- クリック範囲判定
- 点ベースの当たり判定
一番単純な hit test です。
rect:containsRect(r2) / rect:containsRect(x, y, width, height)
別の矩形が、完全にこの rect の中に入っているかを返します。
- intersects() との違い
- containsRect() は 全部入っているか
- intersects() は 一部でも重なっているか
- 向いている用途
- カメラ範囲内に完全に収まっているか
- 子要素が親領域からはみ出していないか
- 当たり判定用の許容範囲チェック
- 注意
- 一部だけ重なるケースでは false です。
4. コピー・同一性・空判定
rect:copy()
rect のコピーを新しく返します。
用途としては、元の rect を壊さずに加工したいときに使います。
たとえば
local padded = r:copy()
padded:inset(-4, -4)
のようにできます。
rect:isEqual(r2)
x, y, width, height がすべて一致しているかを返します。
- 向いている用途
- 前フレームと同じ領域か比較
- レイアウト変更が必要か判定
- キャッシュ無効化条件の判定
- 注意
- 「同じオブジェクトか」ではなく、値が同じかです。
rect:isEmpty()
幅または高さが 0 の矩形かを返します。
- 用途
- 無効な領域かどうか
- 交差結果が実質空か
- 描画する意味があるか
- 注意
- stub.lua では「zero width or height」とあります。
- つまり、どちらかが 0 なら空扱いです。
5. 位置移動
rect:offset(dx, dy)
rect 自体をその場で移動します。
のイメージです。
これは 破壊的変更 です。元の rect が変わります。
- 向いている用途
- 手元の rect を直接更新したい
- フレームごとに移動させる
- 一時コピーではなく本体を動かしたい
rect:offsetBy(dx, dy)
位置だけずらした新しい rect を返します。
local moved = r:offsetBy(5, -2)
- offset() との違い
- offset() は元を変更
- offsetBy() は新しい rect を返す
関数型っぽく安全に使いたいときはこちらが便利です。
6. サイズ変更・余白調整
rect:inset(dx, dy)
rect をその場で内側に縮める、または負値なら外側に広げます。
- 左右から縮める場合は dx に正の値を指定
- 上下から縮める場合は dy に正の値を指定
つまり概念的には
- x += dx
- y += dy
- width -= dx - 2
- height -= dy - 2
に近いです。
- 重要
- これは 破壊的変更 です。
- 向いている用途
- padding を引く
- ボーダー内側領域を作る
- 当たり判定を少し小さくする
- 負の値を指定するとどうなるか
- dx や dy に負を入れると、外側へ膨らみます。
rect:insetBy(dx, dy)
内側に詰めた新しい rect を返します。
中心は元の rect と同じです。
- inset() との違い
- inset() は元を変える
- insetBy() は新しい rect を返す
- 向いている用途
- UI の inner rect を作る
- 元の外枠を残したまま中身領域を出す
- 元データを安全に保ちたい
7. 重なり・交差・結合
rect:intersects(r2)
2つの rect が少しでも重なっているかを返します。
- 向いている用途
- 当たり判定の第一段階
- 表示領域に入っているか
- dirty rect の重なり判定
- containsRect() との違い
- intersects() は一部でも重なれば true
- containsRect() は完全内包のみ true
rect:intersection(r2)
2つの rect の重なっている部分を表す新しい rect を返します。
- 向いている用途
- 実際に描画すべき範囲を求める
- クリップ結果の計算
- 当たり領域の共通部分取得
- intersects() との違い
- intersects() は yes/no
- intersection() は「どこが重なっているか」まで返す
- 注意
- 重なりがなければ空の rect 的な結果になります。
- 使用前に isEmpty() で確認した方が安全です。
rect:union(r2)
2つの rect を両方含む、最小の外接矩形を返します。
- 向いている用途
- 再描画領域の統合
- 複数UI変更箇所をひとまとめにする
- 2つの領域をまとめて扱う
「重なり部分」ではなく、「両方全部を覆う大きい箱」です。
8. 反転
rect:flipRelativeToRect(r2, flip)
rect r2 の中心を基準に、呼び出し元 rect を反転させます。
flip は次のいずれかです。
- playdate.geometry.kUnflipped
- playdate.geometry.kFlippedX
- playdate.geometry.kFlippedY
- playdate.geometry.kFlippedXY
- 何をするか
- たとえば X 反転なら、r2 の中心に対して左右対称の位置へ移します。
- Y 反転なら上下対称です。
- 向いている用途
- 左右対称レイアウト
- UI のミラー配置
- 反転時の当たり判定位置調整
- ある基準矩形の反対側に対応位置を求める
- 注意
- これはかなり幾何的な関数で、単なる width の符号反転ではありません。
- 位置関係を基準矩形の中心に対して反転します。
9. 変換・展開
rect:toPolygon()
rect を playdate.geometry.polygon に変換して返します。
- 向いている用途
- polygon API を使いたい
- 矩形を頂点列として扱いたい
- ほかの図形処理へ渡したい
- 使い道
- rect は簡単ですが、polygon 側でしか受けられない API もあります。
- その橋渡しとして使います。
rect:unpack()
rect の内容を
として個別の値で返します。
local x, y, w, h = r:unpack()
- 向いている用途
- 数値4つを要求する API に渡す
- デバッグ表示
- 既存コードとの接続
要素の分解と変数への代入が1行でできるため、かなり便利な関数です。
資料
破壊的変更と非破壊の対応表
以下の関数はrect自身の値を書き換えます。
- offset(dx, dy)
- inset(dx, dy)
- flipRelativeToRect(r2, flip)
それに対して、以下の関数は新しいrectオブジェクトを戻り値として返すため、非破壊関数と言えます。
- offsetBy(dx, dy)
- insetBy(dx, dy)
- copy()
- intersection(r2)
- union(r2)
- toPolygon()
Playdate の geometry 系は "～By" が非破壊と覚えるとかなり整理しやすいです。
特によく使う関数
使用頻度が高いのはだいたいこのあたりです。
- rect.new()
- rect:containsPoint()
- rect:intersects()
- rect:intersection()
- rect:union()
- rect:offsetBy()
- rect:insetBy()
- rect:unpack()
- rect:centerPoint()
- rect:isEmpty()
使い分けの感覚
- 当たり判定したい
- yes/no だけなら intersects()
- 重なった範囲も欲しいなら intersection()
- 内側余白を作りたい
- 元を変えてよければ inset()
- 元を残したければ insetBy()
- 位置をずらしたい
- 元を動かすなら offset()
- 新しい rect が欲しいなら offsetBy()
- 完全に中に入っているか見たい
- 点が中か見たい
関連ページ
最終更新：2026年04月19日 01:13
