playdate.graphics.image
playdate.graphics.image は、画像を生成したり加工する機能を持っています。
- playdate.graphics.image
- 1. 生成・読み込み
- 2. 画像描画
- image:draw(x, y, flip?, sourceRect?) / image:draw(point, flip?, sourceRect?)
- image:drawAnchored(x, y, ax, ay, flip?)
- image:drawCentered(x, y, flip?)
- image:drawIgnoringOffset(x, y, flip?) / image:drawIgnoringOffset(point, flip?)
- image:drawScaled(x, y, scale, yscale?)
- image:drawRotated(x, y, angle, scale?, yscale?)
- image:drawWithTransform(xform, x, y)
- image:drawTiled(x, y, width, height, flip?) / image:drawTiled(rect, flip?)
- image:drawFaded(x, y, alpha, ditherType)
- image:drawBlurred(x, y, radius, numPasses, ditherType, flip?, xPhase?, yPhase?)
- image:drawSampled(x, y, width, height, centerx, centery, dxx, dyx, dxy, dyy, dx, dy, z, tiltAngle, tile)
- 3. 加工して新しい image を返す関数
- image:copy()
- image:blurredImage(radius, numPasses, ditherType, padEdges?, xPhase?, yPhase?)
- image:fadedImage(alpha, ditherType)
- image:blendWithImage(image, alpha, ditherType)
- image:invertedImage()
- image:rotatedImage(angle, scale?, yscale?)
- image:scaledImage(scale, yscale?)
- image:transformedImage(xform)
- image:vcrPauseFilterImage()
- 4. マスク関連
- 5. 状態変更
- 6. 情報取得・サンプリング
- 資料
- 関連ページ
1. 生成・読み込み
new(path)
ファイルから画像を読み込んで、新しい image オブジェクトを返します。
- 挙動
- path で指定した画像ファイルをロードします
- ファイルが見つからない場合は nil, err を返します
- path に拡張子がなくても、SDK 側の規則に従って解決されます
- 向いている用途
- 普通の画像ロード
- UIパーツ、キャラ画像、背景画像の読み込み
- 起動時ロード
- 注意
- 読み込み失敗時は nil になり得るので、実運用では戻り値チェックが必要です
-- 画像データ "images/player" を読み込んで生成.
local img, err = gfx.image.new("images/player")
if not img then
print(err) -- エラーであればログ出力.
end
new(width, height, bgcolor?)
指定サイズの空画像を新規作成します。
- 引数
- width, height: 画像サイズ
- bgcolor: 初期色。省略時は kColorClear
- 挙動
- 向いている用途
- オフスクリーン描画
- キャッシュ画像生成
- 動的UI生成
- 合成用の一時バッファ
-- 画像を生成.
local img = gfx.image.new(64, 64, gfx.kColorClear)
-- Render Targetを画像に変更.
gfx.pushContext(img)
gfx.fillCircleAtPoint(32, 32, 20)
-- Render Targetをもとに戻す.
gfx.popContext()
image:load(path)
既存の image オブジェクトに対して、別の画像データを読み込み直します。
- 戻り値
- 挙動
- 既存の image の中身を差し替えます
- 追加メモリを確保せず再利用する前提です
- 読み込む画像は元の image と同じ寸法である必要があります
- 向いている用途
- メモリ節約
- 同サイズ画像の差し替え
- 使い回しバッファ更新
- 注意
- サイズが違うと失敗します
- 画像インスタンス自体を維持したい場合に便利です
2. 画像描画
image:draw(x, y, flip?, sourceRect?) / image:draw(point, flip?, sourceRect?)
最も基本の描画関数です。
画像の左上を (x, y) に置いて描きます。
引数の説明は以下の通り。
| 引数名 |
概要 |
パラメータ |
説明 |
| flip |
反転描画の設定 |
playdate.graphics.kImageUnflipped |
反転なし (デフォルト値) |
| playdate.graphics.kImageFlippedX |
X軸で反転 ( "flipX" でも指定可能) |
| playdate.graphics.kImageFlippedY |
Y軸で反転 ("flipY" でも指定可能) |
| playdate.graphics.kImageFlippedXY |
XY軸で反転 '("flipXY" でも指定可能) |
| sourceRect |
矩形切り出し描画 |
playdate.geometry.rect |
画像全体ではなく、一部分だけ切り出して描画します |
image:drawAnchored(x, y, ax, ay, flip?)
画像内の任意の基準点が (x, y) に来るように描きます。
- 引数：基準点(ax, ay)
- 0.0 ～ 1.0 の比率で指定します。
- (0.0, 0.0) = 左上
- (0.5, 0.5) = 中央
- (1.0, 1.0) = 右下
- 向いている用途
- 中心基準で置きたい
- 足元基準でキャラを地面に立たせたい
- 回転や位置合わせの基準統一
image:drawCentered(x, y, flip?)
画像の中心が (x, y) に来るように描きます。
- 向いている用途
- アイコン中央配置
- 弾やマーカーの中心配置
- UI要素の中央配置
- 備考
- drawAnchored(x, y, 0.5, 0.5, flip) の簡易版と思ってよいです。
image:drawIgnoringOffset(x, y, flip?) / image:drawIgnoringOffset(point, flip?)
現在の setDrawOffset() を無視して描画します。
- 向いている用途
- カメラが動いても固定したいHUD
- 画面隅のUI
- デバッグ表示
- スクリーン固定のカーソルや枠
ワールド描画とUI描画を分ける時に便利です。
image:drawScaled(x, y, scale, yscale?)
画像の左上を基準に拡大縮小して描きます。
- 引数
- scale: X方向の拡大率
- yscale: Y方向。省略時は scale と同じ
- 向いている用途
Playdate は 1bit なので、拡縮は滑らかというよりピクセル変形として見る方が自然です。
image:drawRotated(x, y, angle, scale?, yscale?)
画像を中心基準で回転して描きます。
- 挙動
- (x, y) が画像中心
- angle は時計回りの度数法
- scale, yscale で同時に拡縮可
- 向いている用途
- クランク連動回転
- 矢印やポインタ
- ロゴ演出
- 回転オブジェクト
- 注意
- 毎フレーム多用すると負荷はそれなりにあります。
image:drawWithTransform(xform, x, y)
- 挙動
- xform による変換をかけた状態で
- (x, y) を中心基準に描く
- 向いている用途
image:drawTiled(x, y, width, height, flip?) / image:drawTiled(rect, flip?)
画像をタイル状に敷き詰めて描きます。
- 向いている用途
- 背景パターン
- 壁紙
- 小さな模様の敷き詰め
- UIの繰り返しテクスチャ
小さいパターン画像を大きな領域に繰り返し表示できます。
image:drawFaded(x, y, alpha, ditherType)
画像を擬似半透明で描きます。
- 挙動
- alpha は 0.0 ～ 1.0
- 本当のアルファブレンドではなく、ディザリングで透明感を表現します
- 引数：ditherType
- stub.lua では、blurredImage() に列挙されているディザ方式を使います。代表的には:
- kDitherTypeNone
- kDitherTypeDiagonalLine
- kDitherTypeVerticalLine
- kDitherTypeHorizontalLine
- kDitherTypeScreen
- kDitherTypeBayer2x2
- kDitherTypeBayer4x4
- kDitherTypeBayer8x8
- kDitherTypeFloydSteinberg
- kDitherTypeBurkes
- kDitherTypeAtkinson
- 向いている用途
- フェードイン・フェードアウト
- ゴースト表示
- 選択中の薄表示
- UIの無効状態
image:drawBlurred(x, y, radius, numPasses, ditherType, flip?, xPhase?, yPhase?)
画像をその場でぼかして描画します。
- 挙動
- 元画像をグレースケール的にぼかし
- それを 1bit にディザして描きます
- 引数の意味
- radius: ぼかし半径
- numPasses: パス数。増えるほど Gaussian blur に近づく
- ditherType: 1bit に戻すときの方式
- flip: 反転描画
- xPhase, yPhase: 一部ディザ方式の見え方をずらす
- 向いている用途
- 残像
- シャドウ風表現
- 後景化
- UIの非アクティブ感
これは生成済み blurred image を draw するのではなく、リアルタイム計算となるため、
CPUコストには注意です。
image:drawSampled(x, y, width, height, centerx, centery, dxx, dyx, dxy, dyy, dx, dy, z, tiltAngle, tile)
画像を傾いた平面に貼ったように描きます。
- 対象矩形を塗る
- 座標変換は affine transform ベース
- z が低いほど遠近感が誇張される
- tiltAngle は X軸まわりの傾き
- tile でタイル繰り返し可
向いている用途としては、
といった表現が可能です。
3. 加工して新しい image を返す関数
image:copy()
まったく同じ内容の image を複製して返します。
- 向いている用途
- 元を壊さず加工したい
- 派生画像を作りたい
- マスクや反転を別個に扱いたい
image:blurredImage(radius, numPasses, ditherType, padEdges?, xPhase?, yPhase?)
ぼかした新しい image を返します。
- drawBlurred() との違い
- drawBlurred() はその場描画
- blurredImage() は加工済み image を作る
- 引数: padEdges
- ぼかし半径分の余白を確保するかどうかです。
- false だと端が切れ気味になり得ます。
- 向いている用途
- 起動時にぼかし版を生成してキャッシュ
- 毎フレーム計算したくないぼかし画像
- エフェクトの事前生成
image:fadedImage(alpha, ditherType)
フェード済みの新しい image を返します。
- 挙動
- alpha に応じて擬似半透明化
- 既存マスクがある場合はそれも乗算的に効く
- 向いている用途
- 複数段階の薄表示画像の事前生成
- 毎フレーム drawFaded() したくないケース
image:blendWithImage(image, alpha, ditherType)
2枚の image をブレンドした新しい image を返します。
- 挙動
- 呼び出し元 image の重みが alpha
- 相手 image の重みが 1 - alpha
- 結果を 1bit ディザで返す
- 向いている用途
- 2コマの中間状態
- 疑似クロスフェード
- パターン同士の混合
- Playdateらしいポイント
- フルカラーの普通のアルファ合成ではなく、最終的に1bitに落とす点が重要です。
image:invertedImage()
白黒を反転した新しい image を返します。
- 向いている用途
- 選択強調
- 点滅反転
- UI反転版
- 当たり判定デバッグ用の見た目変化
image:rotatedImage(angle, scale?, yscale?)
回転・拡縮した新しい image を返します。
- 挙動
- 時計回りの度数法
- 180度の倍数以外ではサイズが変わり得ます
- 向いている用途
- 事前回転キャッシュ
- 毎フレーム回転描画を避けたい場合
- ローテーションアニメのプリベイク
image:scaledImage(scale, yscale?)
拡縮した新しい image を返します。
- 向いている用途
- サイズ違いバリエーション生成
- UIアイコンの事前拡大版
- 演出用の派生画像
image:transformedImage(xform)
アフィン変換を適用した新しい image を返します。
- 向いている用途
- draw 時ではなく asset 側に変換結果を持ちたい
- 複雑変形のキャッシュ
- 変形画像の使い回し
image:vcrPauseFilterImage()
VCR 一時停止風のノイズっぽい崩れ効果をかけた image を返します。
- 向いている用途
- レトロ映像演出
- 壊れた画面表現
- トランジション
- Playdateらしいローファイ演出
- 位置づけ
- かなりエフェクト寄りの特殊関数です。
4. マスク関連
image:addMask(opaque?)
画像にマスクがまだ無ければ追加します。
- 挙動
- opaque == true または省略: 全面白マスク → 全面不透明
- opaque == false: 全面黒マスク → 全面透明
- 向いている用途
- これから透明領域を管理したい場合の初期化
- clear image に後からマスクを持たせたいとき
image:clearMask(opaque?)
既存マスクの中身を初期化します。
- 挙動
- opaque が true なら全面不透明
- false なら全面透明
- マスクが無い場合は効果なし
- addMask() との違い
- addMask() は「マスクが無ければ追加」
- clearMask() は「既存マスクの内容を塗り直す」
image:getMaskImage()
マスクがあれば、そのマスク image を返します。
無ければ nil。
- 注意点
- 戻り値の mask image は元画像のマスクデータを参照しています。
- つまり、その mask image に描くと元画像のマスク自体が変わります。
- 向いている用途
- マスクを直接編集
- 透明領域の動的更新
- 既存画像の一部分だけ表示管理
image:hasMask()
マスクを持っているかを返します。
- 向いている用途
image:removeMask()
マスクを削除します。
- 向いている用途
- 不透明画像に戻したい
- マスク管理をやめたい
- メモリや状態を単純化したい
image:setMaskImage(maskImage)
指定 image のコピーをマスクとして設定します。
- 挙動
- マスク用 image を外から与える
- そのコピーが使われる
- 向いている用途
- 別画像から透明形状だけ流用
- 事前生成した mask の適用
- パターン透過表現
5. 状態変更
image:setInverted(flag)
この image を描くとき、色反転状態で扱うかどうかを設定します。
- 挙動
- true なら描画時に白黒反転
- ステンシルとして使う場合は意味が逆転し、黒で描ける/白で抜ける関係が反転します
- 向いている用途
- 画像自体はそのままに、描画時だけ反転
- 選択状態表示
- 点滅演出
- invertedImage() との違い
- setInverted(true) は状態変更
- invertedImage() は新規画像生成
image:clear(color)
image の内容をクリアします。
- 挙動
- kColorWhite: 全面白
- kColorBlack: 全面黒
- kColorClear: 透明
- マスクとの関係が重要
- stub.lua の説明では:
- 黒 or 白で clear すると、マスクがあれば全面不透明
- kColorClear で clear すると、マスクが無ければマスクが追加される
Playdate の image は、透明を扱うときにマスクの存在がかなり重要です。
そのため clear(kColorClear) は単なる塗りつぶしではなく、透明画像化の意味も持ちます。
6. 情報取得・サンプリング
image:getSize()
画像の (width, height) を返します。
- 向いている用途
- 中央配置
- 当たり判定サイズ計算
- タイル敷き詰めサイズ確認
image:sample(x, y)
画像の (x, y) の色を返します。
- 戻り値
- playdate.graphics.kColorWhite
- playdate.graphics.kColorBlack
- playdate.graphics.kColorClear
- 向いている用途
- ピクセル単位の判定
- 画像内容の参照
- 特定ピクセルが透明かどうか確認
- 注意点
- 左上が (0, 0) です。
資料
実際によく使うもの
頻度が高いのはだいたいこのあたりです。
- image.new(path)
- image.new(w, h, bgcolor)
- image:draw()
- image:drawCentered()
- image:getSize()
- image:copy()
- image:scaledImage()
- image:rotatedImage()
- image:clear()
- image:setMaskImage()
- image:getMaskImage()
設計思想の概要
playdate.graphics.image は、
- 普通の画像ロード
- オフスクリーン描画先
- 透明マスク付きビットマップ
- 加工済み派生画像の生成元
を兼ねています。
なので、Playdate では image を単なる「絵」ではなく、描画対象でもあり、描画先でもあり、加工パイプラインの中間データでもあると見ると理解しやすいです。
関連ページ
最終更新：2026年05月03日 07:41
