Skip to content

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

Static Methods

Canvas.clear()

Clears the current render target to transparent black.

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 Color | string | int | array | table "white" Draw color. See Color Formats.
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 Color | string | int | array | table "white" Draw color. See Color Formats.

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 Color | string | int | array | table "white" Draw color. See Color Formats.

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 Color | string | int | array | table "white" Draw color. See Color Formats.

Canvas.fill_round_rect(rect, r[, options])

Draws a filled rectangle with rounded corners.

Can also be called as Canvas.fill_round_rect(x, y, w, h, r[, 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.
r float Yes The radius of the corners.
options table No Advanced drawing modifiers.

Fill Round Rect Options Table

Field Type Default Description
color Color | string | int | array | table "white" Draw color. See Color Formats.

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 Color | string | int | array | table "white" Draw color. See Color Formats.
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 Color | string | int | array | table "white" Draw color. See Color Formats.
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 Color | string | int | array | table "white" Draw color. See Color Formats.
thickness float 1.0 Thickness of the stroke.

Canvas.stroke_round_rect(rect, r[, options])

Draws a stroked rectangle with rounded corners.

Can also be called as Canvas.stroke_round_rect(x, y, w, h, r[, 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).
r float Yes The radius of the corners.
options table No Advanced drawing modifiers.

Stroke Round Rect Options Table

Field Type Default Description
color Color | string | int | array | table "white" Draw color. See Color Formats.
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 = "#FF0000", 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 = Color.Blue })

Canvas.fill_circle(100, 100, 40, { color = Color.Lime })

Canvas.fill_circle(200, 100, 40, { color = Color.from_hsv(hue, 1.0, 1.0) })

Canvas.fill_round_rect({x=10, y=10, w=100, h=50}, 8)
Canvas.fill_round_rect(10, 10, 100, 50, 8, { color = Color.Blue })

// 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 = "#00FF00" })

// Pop out the clipping mask constraint to restore full workspace painting context
Canvas.pop_clip()

Additional example code available here.