Canvas¶
The Canvas class enables rendering low-level geometric shapes, managing
clipping regions, manipulating offscreen render targets, and configuring screen
color tones.
Synopsis¶
Static Methods¶
Canvas.clear()Canvas.draw_line(x1, y1, x2, y2[, options])Canvas.fill_circle(cx, cy, radius[, options])Canvas.fill_polygon(points[, options])Canvas.fill_rect(rect[, options])Canvas.height()Canvas.pop_clip()Canvas.pop_render_target()Canvas.push_clip(x, y, w, h)Canvas.push_render_target(img)Canvas.set_tone(r, g, b[, window])Canvas.size()Canvas.stroke_circle(cx, cy, radius[, options])Canvas.stroke_polygon(points[, options])Canvas.stroke_rect(rect[, options])Canvas.width()
Static Methods¶
Canvas.clear()¶
Clears the current render target to transparent black {r=0, g=0, b=0, a=0}.
Canvas.draw_line(x1, y1, x2, y2[, options])¶
Draws a line segment between two coordinates.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
x1 |
float |
Yes | The starting X coordinate. |
y1 |
float |
Yes | The starting Y coordinate. |
x2 |
float |
Yes | The ending X coordinate. |
y2 |
float |
Yes | The ending Y coordinate. |
options |
table |
No | Advanced drawing modifiers. |
Draw Line Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
color |
table |
{ r=255, g=255, b=255, a=255 } |
RGB tint color with optional alpha transparency. |
thickness |
float |
1.0 |
Thickness of the line segment. |
Canvas.fill_circle(cx, cy, radius[, options])¶
Draws a filled circle.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
cx |
float |
Yes | The center X coordinate. |
cy |
float |
Yes | The center Y coordinate. |
radius |
float |
Yes | The radius of the circle outline. |
options |
table |
No | Advanced drawing modifiers. |
Fill Circle Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
color |
table |
{ r=255, g=255, b=255, a=255 } |
RGB tint color with optional alpha transparency. |
Canvas.fill_polygon(points[, options])¶
Draws a filled polygon.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
points |
float[] |
Yes | A flat array of coordinates arranged as [x1, y1, x2, y2, x3, y3, ...]. Must contain a minimum of 3 points (6 values). |
options |
table |
No | Advanced drawing modifiers. |
Fill Polygon Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
color |
table |
{ r=255, g=255, b=255, a=255 } |
RGB tint color with optional alpha transparency. |
Canvas.fill_rect(rect[, options])¶
Draws a filled rectangle.
Can also be called as Canvas.fill_rect(x, y, w, h[, options]).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
rect |
table | instance |
Yes | A rectangle definition in { x, y, w, h } format. |
x |
float |
Yes | The X coordinate of the target rectangle. |
y |
float |
Yes | The Y coordinate of the target rectangle. |
w |
float |
Yes | The width of the target rectangle. |
h |
float |
Yes | The height of the target rectangle. |
options |
table |
No | Advanced drawing modifiers. |
Fill Rect Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
color |
table |
{ r=255, g=255, b=255, a=255 } |
RGB tint color with optional alpha transparency. |
Canvas.height()¶
Gets the height of the current canvas in pixels.
- Returns:
int: The canvas height.
Canvas.pop_clip()¶
Removes the most recently pushed clipping rectangle.
Canvas.pop_render_target()¶
Restores drawing operations to the previous canvas by popping the current
offscreen Image off the stack.
Canvas.push_clip(x, y, w, h)¶
Pushes a clipping rectangle that restricts all subsequent drawing operations to its specified boundaries.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
x |
int |
Yes | The X coordinate of the clipping region. |
y |
int |
Yes | The Y coordinate of the clipping region. |
w |
int |
Yes | The width of the clipping region. |
h |
int |
Yes | The height of the clipping region. |
Canvas.push_render_target(img)¶
Redirects all subsequent drawing operations onto an offscreen Image.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
img |
Image |
Yes | A valid Image class instance created as a render target. |
Canvas.set_tone(r, g, b[, window])¶
Multiplies every rendered pixel color by an (r, g, b) factor.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
r |
float |
Yes | Red tone multiplier. |
g |
float |
Yes | Green tone multiplier. |
b |
float |
Yes | Blue tone multiplier. |
window |
int |
No | Identifier targeting a specific window instead of the active one. |
Canvas.size()¶
Gets canvas size as a table.
- Returns:
table
Size Table¶
| Field | Type | Description |
|---|---|---|
width |
int |
The canvas width. |
height |
int |
The canvas height. |
Canvas.stroke_circle(cx, cy, radius[, options])¶
Draws a stroked circle.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
cx |
float |
Yes | The center X coordinate. |
cy |
float |
Yes | The center Y coordinate. |
radius |
float |
Yes | The radius of the circle outline. |
options |
table |
No | Advanced drawing modifiers. |
Stroke Circle Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
color |
table |
{ r=255, g=255, b=255, a=255 } |
RGB tint color with optional alpha transparency. |
thickness |
float |
1.0 |
Thickness of the stroke. |
Canvas.stroke_polygon(points[, options])¶
Draws a stroked polygon.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
points |
float[] |
Yes | A flat array of coordinates arranged as [x1, y1, x2, y2, x3, y3, ...]. Must contain a minimum of 3 points (6 values). |
options |
table |
No | Advanced drawing modifiers. |
Stroke Polygon Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
color |
table |
{ r=255, g=255, b=255, a=255 } |
RGB tint color with optional alpha transparency. |
thickness |
float |
1.0 |
Thickness of the stroke. |
Canvas.stroke_rect(rect[, options])¶
Draws a stroked rectangle.
Can also be called as Canvas.stroke_rect(x, y, w, h[, options]).
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
rect |
table | instance |
Yes | A rectangle definition in { x, y, w, h } format. |
x |
float |
Yes | The X coordinate of the target rectangle outline (if rect is omitted). |
y |
float |
Yes | The Y coordinate of the target rectangle outline (if rect is omitted). |
w |
float |
Yes | The width of the target rectangle outline (if rect is omitted). |
h |
float |
Yes | The height of the target rectangle outline (if rect is omitted). |
options |
table |
No | Advanced drawing modifiers. |
Stroke Rect Options Table¶
| Field | Type | Default | Description |
|---|---|---|---|
color |
table |
{ r=255, g=255, b=255, a=255 } |
RGB tint color with optional alpha transparency. |
thickness |
float |
1.0 |
Thickness of the stroke. |
Canvas.width()¶
Gets the width of the current active canvas in pixels.
- Returns:
int: The canvas width.
Examples¶
// Draw a single thick red line across the screen
Canvas.draw_line(10, 10, 150, 150, {
color = { r = 255, g = 0, b = 0, a = 255 },
thickness = 3.0
})
// Unify coordinates inside a bounding geometry table
local boundaryRect = { x = 40, y = 40, w = 200, h = 100 }
Canvas.fill_rect(boundaryRect, { color = { r = 0, g = 0, b = 255, a = 255 } })
// Define a safe rendering clipping viewport boundary region
Canvas.push_clip(50, 50, 100, 100)
// Attempt to render a circle; sections extending past the clip box bounds are dropped
Canvas.fill_circle(50, 50, 60, { color = { r = 0, g = 255, b = 0, a = 255 } })
// Pop out the clipping mask constraint to restore full workspace painting context
Canvas.pop_clip()