playdate.graphics.imagetable
- スプライトアニメーションのコマをまとめる
- 連番画像を一括で読む
- 1枚のスプライトシートを格子状に分割して扱う
- タイル画像群として使う
重要なのは、中身は 1 枚画像ではなく「画像の集合」ということです。また、Playdate の image table は
1始まり です。つまり最初の画像は 0 ではなく 1 となります。
生成
new(count, cellsWide, cellSize)
空の image table を生成します。これはファイルから直接読むのではなく、あとから
で中身を入れる前提の生成方法です。
| カテゴリ |
名前 |
型 |
省略 |
説明 |
| 引数 |
count |
integer |
x |
この imagetable に入る画像数です。
たとえば 8 コマのアニメーションなら 8 です |
| cellsWide? |
integer |
o |
テーブルを ''x, y'' の2次元位置で扱うための横セル数です。
これを設定しておくと、後で ''getImage(x, y)'' のような格子座標ベースのアクセスがしやすくなります。
たとえば
・ ''count = 16&br()・cellsWide = 4''
なら、4列 × 4行 のようなテーブルとして解釈できます |
| cellSize? |
integer |
o |
これは少し技術的な引数で、load() を使う場合の画像確保サイズに関係する値です。
通常の利用ではあまり意識しないこともありますが、意味としては
・後で:load(path) する予定
・そのときの画像セルの確保サイズを先に決める
という用途です |
| 戻り値 |
- |
_ImageTable |
- |
生成した新しいplaydate.graphics.imagetable オブジェクト |
この形式は、すでに空のテーブルを作っておき、
- 必要に応じて中身を差し替えたい
- メモリ再確保を減らしたい
- 1枚ずつ setImage() で埋めたい
というケースに向いています。
new(path)
local tbl, err = gfx.imagetable.new("frames")
ファイルから
image table を読み込んで生成します。
アニメーションコマやタイル画像群をまとめて読むときに使えます。
| カテゴリ |
名前 |
型 |
説明 |
| 引数 |
path |
string |
読み込む画像テーブルのパスです (※) |
| 戻り値 |
- |
imagetable? |
読み込み成功時のイメージテーブル。エラーの場合はnilとなります |
| - |
err? |
読み込み失敗時のエラー文字列。
例えばpath にファイルが存在しないときには "エラー文字列" を返します |
(※) 引数のpathについて
以下に対応しています。
- 1. matrix image table
- たとえば
frames-table-16-16.png
- のようなファイルがある場合、これは
- 1枚の画像の中に16x16 のセルで画像が並んでいる形式です。
- このとき呼び方は
local tbl = gfx.imagetable.new("frames")
- です。
- つまり"frames-table-16-16.png" を直接書くのでなく、ベース名だけでよい形です。
- 2. sequential image table
- たとえば
frames-table-1.png
frames-table-2.png
frames-table-3.png
- のような連番画像群でも、同じく
local tbl = gfx.imagetable.new("frames")
- で読めます。
- 3. animated GIF
- アニメーションGIFの読み込みにも対応しています。その場合、GIF の各フレームが連続したビットマップ列として読み込まれます。
- ただし「GIF の timing data は無視」されます。GIF 自体に「1フレーム何ms表示するか」が埋まっていても、imagetable 側ではそれは保持せず、単なるフレーム列として扱います。
読み込み
playdate.graphics.imagetable:load(path)
既存のimagetable オブジェクトに、新しい画像テーブルを読み込む関数です。
重要なのは、
という点です。
| カテゴリ |
名前 |
型 |
説明 |
| 引数 |
path |
string |
読み込む画像テーブルのパスです |
| 戻り値 |
success |
boolean |
成功ならtrue、失敗ならfalse |
| err? |
string |
失敗時のみエラー文字列が返ります |
- 制約
- といった制約があります。
- ここでいうdimensions は文脈上、各セル画像の寸法を指すと考えるのが自然です。
- つまり、最初に16x16 セルのテーブルとして確保したなら、後で読み込むものも同じセルサイズである必要があります。
- 使いどころ
- これは特に、
- 同じサイズのアニメセットを差し替える
- メモリ再利用したい
- 実行中にフレーム群を切り替えたい
- ときに有用です。
- new(path) との違い
- です。
画像・描画
imagetable:drawImage(n, x, y, flip)
指定した番号の画像を、その場で直接描画します。
以下の記述を簡潔に呼び出すものです。
-- 画像を取得.
local img = imagetable:getImage(n)
if img then
-- 描画
img:draw(x, y, flip)
end
| カテゴリ |
名前 |
型 |
省略 |
説明 |
| 引数 |
n |
integer |
x |
描画する画像のインデックス。1始まりとなります |
| x |
integer |
x |
描画先の X 座標 |
| y |
integer |
x |
描画先の Y 座標 |
| flip? |
integer or string |
o |
画像の反転方法 →flip |
| 戻り値 |
なし (nil) |
imagetable:__index(n)
これは、
imagetable[n]
と書いたときに呼ばれるものです。意味としては
imagetable[n] == imagetable:getImage(n)
です。
| カテゴリ |
名前 |
型 |
説明 |
| 引数 |
n |
integer |
画像のインデックスで「1始まり」です |
| 戻り値 |
- |
_Image? |
対応するplaydate.graphics.image を返します。
範囲外ならnil になりえます |
これは「関数」として直接呼ぶというより、次の糖衣構文を可能にするためのものです。
local frame = imagetable[1]
つまり、
local frame = imagetable:getImage(1)
の短縮形です。
- 注意点
- Lua 配列感覚で書けますが、Playdate のimagetable は "1" 始まりなので、"imagetable[0]" は通常無効です。
imagetable:getImage(n)
n 番目の画像を取得します。
| カテゴリ |
名前 |
型 |
説明 |
| 引数 |
n |
integer |
取得したい画像の番号です。
左から右、上から下の順で数えます。
matrix 形式の場合も内部的な順序は
・左上
・その右
・さらに右
・行が終わったら次の行の左端
です |
| 戻り値 |
- |
_Image? |
playdate.graphics.image を返します。範囲外ならnil です |
imagetable:getImage(x, y)
セル座標で画像を取得します。
| カテゴリ |
名前 |
型 |
説明 |
| 引数 |
x |
integer |
列位置で「1始まり」です |
| y |
integer |
行位置で「1始まり」 です |
| 戻り値 |
- |
_Image? |
指定セルの画像を返します。
範囲外ならnil です |
これは、元画像が「格子状のシート」であり、さらにimagetable 側がその格子情報を持っているときに便利です。
たとえば 4 列 × 4 行のシートで、
local img = table:getImage(2, 3)
なら、2列3行目の画像を取るイメージです。
- getImage(n) との違い
- です。
- アニメーション用途ならn 版のほうが扱いやすく、タイルマップ的に扱うなら ''(x, y)'' 版のほうが自然です。
imagetable:setImage(n, image)
指定したスロットに画像を設定します。
| カテゴリ |
名前 |
型 |
説明 |
| 引数 |
n |
integer |
設定先の番号です。1始まり です |
| image |
_Image |
設定するplaydate.graphics.image です |
| 戻り値 |
なし (nil) |
ニュアンスとしては、画像データを丸ごと複製するというより、そのimage のデータを参照する形でセットするものです。
- 「そのスロットに image を入れる」
- 「ただし完全なディープコピーではない可能性が高い」
という理解がよいです。
- 1枚ずつ動的に構築した image を詰める
- 既存画像からテーブルを組み立てる
ときに使います。
local tbl = gfx.imagetable.new(3)
tbl:setImage(1, img1)
tbl:setImage(2, img2)
tbl:setImage(3, img3)
数・サイズの取得
imagetable:__len()
#imagetable と書いたときに呼ばれます。
意味としては
#imagetable == imagetable:getLength()
です。
| カテゴリ |
名前 |
型 |
説明 |
| 戻り値 |
- |
integer |
画像数を返します |
Lua の配列っぽく扱えるため、ループに便利です。
for i = 1, #imagetable do
local img = imagetable[i]
end
imagetable:getLength()
image table に入っている画像数を返します。
全フレーム走査や、アニメーションの終端判定に便利です。
以下の記述はどちらも同じ値となります。
local n = imagetable:getLength()
local n2 = #imagetable
imagetable:getSize()
image table の格子サイズを返します。
「横に何セルあるか」「縦に何セルあるか」を取得できます。
これは各画像のピクセルサイズではありません
| カテゴリ |
名前 |
型 |
説明 |
| 戻り値 |
cellsWide |
integer |
横のセル数 |
| cellsHigh |
integer |
縦のセル数 |
4列×2行の image table なら
-- w == 4
-- h == 2
local w, h = imagetable:getSize()
''getImage(x, y)'' と組み合わせて、全セルを走査したいときに便利です。
local cellsWide, cellsHigh = imagetable:getSize()
for y = 1, cellsHigh do
for x = 1, cellsWide do
local img = imagetable:getImage(x, y)
end
end
実務上の注意点
- 1. 0始まりではない
- Playdate のimagetable は 1始まり です。
- ここを C/C++ や一般的な配列感覚で 0 始まりにすると壊れやすいです。
- 2. getSize() は画像ピクセルサイズではない
- これは誤解しやすいです。
- imagetable:getSize() → セル数 ''(cellsWide, cellsHigh)''
- image:getSize() → 1枚画像のピクセルサイズ ''(width, height)''
- です。
- 3. load() は差し替え用途
- load() は単なる別名コンストラクタではなく、既存インスタンスの再利用寄りです。
- 新規ロード目的ならnew(path) のほうが自然です。
- 4. setImage() は「参照を張る」説明
- 画像をコピーするというより参照関係を作る説明になっています。
- そのため、メモリ共有や元画像の扱いを意識したほうがよい場面があります。
関連ページ
最終更新：2026年04月30日 08:06
