Picture:set
methodSet a pixel. No-op if out of bounds when applied.
handle32 methodsUI apps only
Picture
A reusable, canvas-agnostic command list created by datumhue.image.picture. Record drawing with the methods below, then replay it onto an Image with canvas:apply(picture) — the whole picture lands in one atomic pass. Record once and apply every frame; rebuild dynamic content with reset.
- Obtained from
datumhue.image.picture- Accepted by
Image:apply
The examples on this page start from:
lua
local color = datumhue.color
local image = datumhue.image.new({ width = 64, height = 64 })
image:mount({ width = 256, height = 256 })
local pic = datumhue.image.picture()Methods 32
Picture:fill
methodFill the entire buffer with a color.
In the guide: Pixel art and sprites
Picture:clear
methodPicture:clear() -> PictureClear to transparent black (all zeros). Also resets the clip rectangle.
Picture:line
methodDraw a line.
In the guide: Pixel art and sprites API conventions
Picture:circ
methodDraw a circle outline.
Picture:circfill
methodDraw a filled circle.
In the guide: Pixel art and sprites API conventions
Picture:oval
methodDraw an oval outline (bounding box).
Picture:ovalfill
methodDraw a filled oval (bounding box).
In the guide: Pixel art and sprites
Picture:rect
methodDraw a rectangle outline.
Picture:rectfill
methodDraw a filled rectangle between two corners (inclusive, in either order). Clips to bounds.
In the guide: Pixel art and sprites
Picture:rrect
methodDraw a rounded-rectangle outline.
Picture:rrectfill
methodDraw a filled rounded rectangle.
Picture:tri
methodPicture:tri(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, color: Color) -> PictureDraw a triangle outline.
Picture:trifill
methodPicture:trifill(x1: number, y1: number, x2: number, y2: number, x3: number, y3: number, color: Color) -> PictureDraw a filled triangle.
Picture:polygon
methodDraw a polygon outline from a flat point array {x1,y1, x2,y2, ...}.
Picture:polygonfill
methodDraw a filled polygon from a flat point array {x1,y1, x2,y2, ...}.
-- Points are flat x, y pairs.
pic:polygonfill({ 32, 4, 60, 56, 4, 56 }, color("#a7c080"))
image:apply(pic)Picture:arc
methodPicture:arc(cx: number, cy: number, r: number, start_angle: number, end_angle: number, color: Color) -> PictureDraw an arc outline. Angles in radians.
Picture:arcfill
methodPicture:arcfill(cx: number, cy: number, r: number, start_angle: number, end_angle: number, color: Color) -> PictureDraw a filled arc (pie slice). Angles in radians.
-- Y points down, so a growing angle turns clockwise on screen.
pic:arcfill(32, 32, 24, 0, math.pi / 2, color("#dbbc7f"))
image:apply(pic)Picture:floodfill
methodReplace all connected same-color pixels from (x,y). Bypasses camera and clip.
Picture:blur
methodPicture:blur(x: number, y: number, w: number, h: number, radius: number) -> PictureBox blur over a rectangular region.
Picture:print
methodPicture:print(text: string, x: number, y: number, color: Color) -> integerDraw text. Returns the x position after the last character (sized by the current font). Supports newlines and the active font, clip, and camera.
local x = pic:print("HP", 2, 2, color("#e67e80"))
print(x) --> 18
pic:print("42", x + 4, 2, color("#a7c080"))
image:apply(pic)In the guide: Pixel art and sprites
Picture:measure_text
methodPicture:measure_text(text: string) -> image.TextSizeSize of the text for the picture's current font. Bitmap fonts have a fixed line height (the cell height), so height depends only on the number of lines.
local size = pic:measure_text("Hello\nworld")
print(size.width, size.height) --> 40 26returns image.TextSize record 2 keys
| Key | Type | Description |
|---|---|---|
| width | integer | The widest line's advance, in pixels. |
| height | integer | Line count times the font's cell height, in pixels. |
In the guide: Pixel art and sprites
Picture:wrap
methodPicture:wrap(text: string, max_width: number) -> string[]Word-wrap the text to fit max_width pixels for the picture's current font, breaking at spaces (a word longer than the width hard-splits) and honoring embedded newlines. Print the returned lines one per row; every line's measured width fits within max_width.
local lines = pic:wrap("one two three four", 64)
print(table.concat(lines, "|")) --> one two|three|four
for i, line in ipairs(lines) do
pic:print(line, 2, 2 + (i - 1) * 13, color("#7fbbb3"))
end
image:apply(pic)In the guide: Pixel art and sprites
Picture:push
methodPicture:push() -> PictureSave the current camera offset and clip rectangle.
Picture:pop
methodPicture:pop() -> PictureRestore the camera offset and clip rectangle. No-op if the stack is empty.
Picture:translate
methodPicture:translate(dx: number, dy: number) -> PictureShift the drawing origin by (dx, dy). Additive with the current camera offset.
Picture:camera
methodPicture:camera(x?: number, y?: number) -> PictureSet the camera offset absolutely. Call with no arguments to reset to (0, 0).
In the guide: Pixel art and sprites
Picture:clip
methodPicture:clip(x?: number, y?: number, w?: number, h?: number) -> PictureSet the clipping rectangle in screen space. Call with no arguments to reset.
pic:clip(16, 16, 32, 32)
pic:circfill(32, 32, 28, color("#d699b6"))
-- No rectangle: draw anywhere again.
pic:clip()
pic:circ(32, 32, 30, color("#d699b6"))
image:apply(pic)In the guide: Pixel art and sprites
Picture:fillp
methodPicture:fillp(pattern?: number) -> PictureSet a 4x4 fill-pattern bitmask (16-bit). Call with no arguments to reset to solid.
-- A set bit leaves its pixel unfilled. Bit 0 is the top-left pixel
-- of each 4x4 tile, and the bits count along its rows.
pic:fillp(0x5a5a)
pic:rectfill(0, 0, 63, 31, color("#83c092"))
-- No pattern: solid again.
pic:fillp()
pic:rectfill(0, 32, 63, 63, color("#83c092"))
image:apply(pic)Picture:set_font
methodSet a custom bitmap font from an Atlas (cell index = ASCII code - 32). char_w overrides the per-glyph advance, defaulting to the atlas cell width. Pass nil for the atlas to reset to the built-in font.
In the guide: Pixel art and sprites
Picture:blit
methodPicture:blit(src: Image, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, blend_mode?: image.BlendMode) -> PictureCopy pixels from another Image (or the target itself) onto the canvas at apply time. blend_mode defaults to copy.
local stamp = datumhue.image.new({ width = 8, height = 8 })
local dot = datumhue.image.picture()
stamp:apply(dot:circfill(4, 4, 3, color("#e69875")))
-- Copy the stamp's 8x8 pixels to (20, 20), blending by alpha.
pic:blit(stamp, 0, 0, 8, 8, 20, 20, "alpha")
image:apply(pic)In the guide: Draw shapes and text Pixel art and sprites
Picture:reset
methodPicture:reset() -> PictureEmpty the command list so the picture can be rebuilt. Does not change the current font.
In the guide: Pixel art and sprites