Image¶
The Image class enables loading images from files and rendering them onto the
screen.
Synopsis¶
Constructors¶
Static Methods¶
Static Members¶
Image.BatchRecordSizeImage.BatchFieldCountImage.BatchCompactRecordSizeImage.BatchCompactFieldCountImage.BatchFlagFlipXImage.BatchFlagFlipYImage.BlendAddImage.BlendDestinationOutImage.BlendMultiplyImage.BlendNormalImage.BlendPremultiplied
Instance Methods¶
image.draw(x, y[, options])image.draw_quad(tl, tr, br, bl[, options])image.draw_batch(data[, count])image.draw_batch_compact(data[, count, origin_x, origin_y])image.height()image.hit_test(x, y)image.size()image.width()
Constructors¶
Image(path)¶
Loads an image from given path.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string |
Yes | The path of the image to load. |
Static Methods¶
Image.create(width, height)¶
Creates a completely blank, mutable RGBA image of the specified dimensions.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
width |
int |
Yes | Width of the image. |
height |
int |
Yes | Height of the image. |
Image.create_render_target(width, height)¶
Creates a blank RGBA image that is capable of being targeted for custom runtime drawing operations.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
width |
int |
Yes | Width of the image. |
height |
int |
Yes | Height of the image. |
Static Members¶
Image.BatchRecordSize¶
- Type:
int
The size in bytes of a single standard batch record.
Image.BatchFieldCount¶
- Type:
int
The total number of float fields in a standard batch record.
Image.BatchCompactRecordSize¶
- Type:
int
The size in bytes of a single compact batch record.
Image.BatchCompactFieldCount¶
- Type:
int
The total number of float fields in a compact batch record.
Image.BatchFlagFlipX¶
- Type:
int
Bitmask flag used to toggle horizontal flipping inside batch flag fields.
Image.BatchFlagFlipY¶
- Type:
int
Bitmask flag used to toggle vertical flipping inside batch flag fields.
Image.BlendAdd¶
- Type:
int
Additive blending mode, useful for lighting or particle effects.
Image.BlendDestinationOut¶
- Type:
int
Destination-out blending mode, typically used for masking out elements.
Image.BlendMultiply¶
- Type:
int
Multiplies the source colors with the destination colors.
Image.BlendNormal¶
- Type:
int
Standard alpha blending (Default).
Image.BlendPremultiplied¶
- Type:
int
Blending mode designed for assets utilizing premultiplied alpha channels.
Instance Methods¶
image.draw(x, y[, options])¶
Render the image at given coordinates with specified options.
Draw Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
src |
table |
null |
Source rectangle within the image { x, y, w, h } format. Defaults to the entire image. |
size |
table |
null |
Target destination size in { w, h } format. Overrides separate width/height properties. |
w | width |
float |
Original Width | Explicit target width for scaling. |
h | height |
float |
Original Height | Explicit target height for scaling. |
scale |
float|table |
1.0 |
Scale factors formatted as either a single float (uniform scale) or a table in { x, y } format. |
angle |
float |
0.0 |
Rotation angle specified in degrees. |
origin |
table |
null |
Anchor origin point for rotation/scaling in { x, y } format. Defaults to top-left (0,0), or the image center if centered is true. |
centered |
bool |
false |
When set to true (and origin isn't explicitly defined), it centers the draw origin point automatically based on final dimensions. |
color |
Color | string | int | array | table |
null |
Tint color. See Color Formats. |
alpha |
float |
1.0 |
Opacity from 0.0 (invisible) to 1.0 (opaque). |
blend |
int |
Image.BlendNormal |
The blend mode to use. |
flip_x |
bool |
false |
Flips the rendered asset horizontally if true. |
flip_y |
bool |
false |
Flips the rendered asset vertically if true. |
image.draw_quad(tl, tr, br, bl[, options])¶
Render the image mapped to an arbitrary quadrilateral defined by four corner points, supporting perspective warps and distorted field projections.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
tl |
table |
Yes | Top-Left destination corner in { x, y } format. |
tr |
table |
Yes | Top-Right destination corner in { x, y } format. |
br |
table |
Yes | Bottom-Right destination corner in { x, y } format. |
bl |
table |
Yes | Bottom-Left destination corner in { x, y } format. |
options |
table |
No | Optional drawing parameters table. |
Quad Draw Options Table¶
Supports all fields from the standard Draw Options Table plus the following mesh subdivision settings:
| Field | Type | Default | Description |
|---|---|---|---|
cols |
int |
1 |
Number of horizontal subdivisions for the mesh grid. |
rows |
int |
1 |
Number of vertical subdivisions for the mesh grid. |
subdivisions |
int |
null |
Sets both cols and rows to the same value for a uniform grid if specified. |
image.draw_batch(data[, count])¶
Render multiple instances of the image in a single high-performance batch call.
data can be passed as either an array or a blob.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
data |
array | blob |
Yes | Raw buffer containing packed batch records. |
count |
int |
No | Optional maximum number of records to process. Defaults to the total available records. |
Batch Record Layout¶
| Index | Field | Description |
|---|---|---|
| 0 | x |
Target X coordinate |
| 1 | y |
Target Y coordinate |
| 2 | src_x |
Source rectangle X |
| 3 | src_y |
Source rectangle Y |
| 4 | src_w |
Source rectangle Width |
| 5 | src_h |
Source rectangle Height |
| 6 | width |
Target width |
| 7 | height |
Target height |
| 8 | scale_x |
Horizontal scale factor |
| 9 | scale_y |
Vertical scale factor |
| 10 | angle |
Rotation angle in degrees |
| 11 | origin_x |
Origin anchor X |
| 12 | origin_y |
Origin anchor Y |
| 13 | r |
Red tint channel (0-255) |
| 14 | g |
Green tint channel (0-255) |
| 15 | b |
Blue tint channel (0-255) |
| 16 | a |
Alpha/Opacity channel (0-255) |
| 17 | flags |
Bitmask flags (blend mode in bits 0–3, flip_x in bit 4, flip_y in bit 5) |
image.draw_batch_compact(data[, count, origin_x, origin_y])¶
Render multiple instances of the image using an optimized, lightweight layout.
data can be passed as either an array or a blob.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
data |
array | blob |
Yes | Raw buffer containing packed compact batch records. |
count |
int |
No | Optional maximum number of records to process. Defaults to the total available records. |
origin_x |
float |
No | Optional default origin anchor X coordinate. Defaults to 0.0. |
origin_y |
float |
No | Optional default origin anchor Y coordinate. Defaults to 0.0. |
Compact Batch Record Layout¶
| Index | Field | Description |
|---|---|---|
| 0 | x |
Target X coordinate |
| 1 | y |
Target Y coordinate |
| 2 | angle |
Rotation angle in degrees |
| 3 | scale |
Uniform scale factor (applied to both scale X and Y) |
| 4 | rgb_color |
24-bit RGB packed into uint32 (0xRRGGBB) |
| 5 | flags |
Bitmask flags (blend mode in bits 0–3, flip_x in bit 4, flip_y in bit 5, and alpha opacity in bits 8–15) |
image.height()¶
Get the image height.
- Returns:
int: The image height.
image.hit_test(x, y)¶
Perform a hit test against the image's alpha channel at given coordinates.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
x |
int |
Yes | X coordinate. |
y |
int |
Yes | Y coordinate. |
- Returns:
bool:trueif the image's pixel at (x, y) has non-zero alpha.falseotherwise.
image.size()¶
Get image size as a table.
- Returns:
table
Size Table¶
| Field | Type | Description |
|---|---|---|
width |
int |
The image width. |
height |
int |
The image height. |
image.width()¶
Get the image width.
- Returns:
int: The image width.
Examples¶
// Load an image
local acorn = Image("res://assets/Images/acorn.png")
// In draw():
acorn.draw(10, 10) // Normal
acorn.draw(50, 10, {angle = 45}) // Rotated
acorn.draw(100, 10, {scale = 2.0}) // Scaled
acorn.draw(10, 50, {flipped_x = true}) // Flipped
Additional example code available here.