Canvas

The canvas module is a wrapper around the HTML5 canvas and allows to draw on top of the rendering. It needs to be initialized with create() first in the init() function.

Reference

canvas.clear()

Clear the canvas.

canvas.getWidth()

Returns the width of the canvas in pixels.

canvas.getHeight()

Returns the height of the canvas in pixels.

canvas.setLineWidth(w)

Sets the width of lines in the canvas.

Parameters:

w (number) – the width to set the lines to.

canvas.setLineCap(cap)

Sets the type of endings applied to the ends of a line.

Parameters:

cap (str) – the type of corner to create on a line. One of “butt”, “round”, “square”.

canvas.setLineJoin(join)

Sets the type of corner created when two lines meet.

Parameters:

join (str) – the type of connection to create between two lines. One of “bevel”, “round”, or “miter”.

canvas.setMiterLimit(limit)

Sets the maximum miter length. Miter length is the distance between the inner corner and the outer corner of the join.

Parameters:

limit (number) – the maximum miter length. When the miter length exceeds this value, the corner is trimmed.

canvas.setStrokeColor(r, g, b, a)

Sets the color of the stroke (outline) for shapes drawn on the canvas.

Parameters:

  • r (number) – red channel value

  • g (number) – green channel value

  • b (number) – blue channel value

  • a (number) – alpha channel value

canvas.setFillColor(r, g, b, a)

Sets the color that is used to fill in shapes and text when they are drawn on the canvas.

Parameters:

  • r (number) – red channel value

  • g (number) – green channel value

  • b (number) – blue channel value

  • a (number) – alpha channel value

canvas.setShadowColor(r, g, b, a)

Sets the color to use for shadows.

Parameters:

  • r (number) – red channel value

  • g (number) – green channel value

  • b (number) – blue channel value

  • a (number) – alpha channel value

canvas.setShadowBlurLevel(level)

Sets the blur level for shadows.

Parameters:

level (number) – the level of blur to be applied to shadows (in pixels).

canvas.setShadowOffset(x, y)

Sets the blur level for shadows.

Parameters:

  • x (number) – the vertical offset of the shadow in pixels.

  • y (number) – the horizontal offset of the shadow in pixels.

canvas.beginPath()

Begins a new path.

canvas.closePath()

Close the current path by connecting the last and first point in the path, creating a loop.

canvas.isPointInPath(x, y)

Determines if the specified point is in the current path.

Parameters:

  • x (number) – x-coordinate of the point to check.

  • y (number) – y-coordinate of the point to check.

Returns:

indicating if the point is in the path or not.

Return type:

boolean

canvas.clip()

Sets the clipping path to the current drawing path.

canvas.stroke()

Draws the outline of a shape or path using the current stroke style, line width and styles.

canvas.fill()

Fills a shape or path with the current fill style.

canvas.moveTo(x, y)

Moves the current drawing position to the specified coordinates.

Parameters:

  • x (number) – x-coordinate of the new current drawing position.

  • y (number) – y-coordinate of the new current drawing position.

canvas.lineTo(x, y)

Draws a straight line from the current position to the specified coordinates.

Parameters:

  • x (number) – the x-coordinate to draw the line to.

  • y (number) – the y-coordinate to draw the line to.

canvas.setCompositeOperation(operation)

Sets the type of compositing operation to apply when drawing new shapes.

“source-over”, “source-in”, “source-out”, “source-atop”, “destination-over”, “destination-in”, “destination-out”, “destination-atop”, “lighter”, “copy”, “xor”.

Parameters:

operation (str) – the compositing operation to use, possible values are:

canvas.setGlobalAlpha(value)

Sets the transparency value that is applied to all rendering operations.

Parameters:

value (number) – a value between 0.0 (fully transparent) and 1.0 (fully opaque).

canvas.pathRect(x, y, w, h)

Creates a rectangle path which is only drawn after calling stroke() or fill().

Parameters:

  • x (number) – x-coordinate of the rectangle upper-left corner.

  • y (number) – y-coordinate of the rectangle upper-left corner.

  • w (number) – width of the rectangle.

  • h (number) – height of the rectangle.

canvas.strokeRect(x, y, w, h)

Draw a rectangle outline using the current stroke style.

Parameters:

  • x (number) – x-coordinate of the rectangle upper-left corner.

  • y (number) – y-coordinate of the rectangle upper-left corner.

  • w (number) – width of the rectangle.

  • h (number) – height of the rectangle.

canvas.fillRect(x, y, w, h)

Draw a rectangle with a filled interior using the current fill style,

Parameters:

  • x (number) – x-coordinate of the rectangle upper-left corner.

  • y (number) – y-coordinate of the rectangle upper-left corner.

  • w (number) – width of the rectangle.

  • h (number) – height of the rectangle.

canvas.clearRect(x, y, w, h)

Clears the specified rectangle by setting its pixels to transparent.

Parameters:

  • x (number) – x-coordinate of the rectangle upper-left corner.

  • y (number) – y-coordinate of the rectangle upper-left corner.

  • w (number) – width of the rectangle.

  • h (number) – height of the rectangle.

canvas.circle(x, y, r)

Draws a circle with given parameters. Must be followed by stroke() or fill().

Parameters:

  • x (number) – x-coordinates of the center of the circle.

  • y (number) – y-coordinates of the center of the circle.

  • r (number) – the radius of the circle

canvas.arc(x, y, r, startAngle, endAngle, anticlockwise)

Draws an arc with given parameters. Must be followed by stroke() or fill().

Parameters:

  • x (number) – x-coordinates of the center of the circle.

  • y (number) – y-coordinates of the center of the circle.

  • r (number) – the radius of the circle.

  • startAngle (number) – the starting angle in radians.

  • endAngle (number) – the ending angle, in radians.

  • anticlockwise (boolean) – a flag which specifies whether the drawing should be counterclockwise or clockwise.

canvas.quadraticCurve(cpx, cpy, x, y)

Adds a quadratic Bézier curve to the path with given control point and end point.

Parameters:

  • cpx (number) – x-coordinate of the control point.

  • cpy (number) – y-coordinate of the control point.

  • x (number) – x-coordinate of the end point.

  • y (number) – y-coordinate of the end point.

canvas.bezierCurve(cp1x, cp1y, cp2x, cp2y, x, y)

Draws a bezier curve from the current position to the specified point, using the specified control points.

Parameters:

  • cp1x (number) – x-coordinate of the first control point.

  • cp1y (number) – y-coordinate of the first control point.

  • cp2x (number) – x-coordinate of the second control point.

  • cp2y (number) – y-coordinate of the second control point.

  • x (number) – x-coordinate of the end point.

  • y (number) – y-coordinate of the end point.

canvas.setGradientActive(gradient)

Sets a gradient object to active.

Parameters:

gradient (Gradient) – a gradient object

canvas.colorStop(gradient, offset, r, g, b, a)

Adds a new stop, defined by an offset and a color, to a gradient object.

Parameters:

  • gradient (Gradient) – a gradient object

  • offset (number) – a value between 0.0 and 1.0 where the new color stop is positioned.

  • r (number) – red channel value

  • g (number) – green channel value

  • b (number) – blue channel value

  • a (number) – alpha channel value

canvas.createLinearGradient(x1, y1, x2, y2)

Creates a linear gradient object.

Parameters:

  • x1 (number) – the x-coordinate of the start point of the gradient

  • y1 (number) – the y-coordinate of the start point of the gradient

  • x2 (number) – the x-coordinate of the end point of the gradient

  • y2 (number) – the y-coordinate of the end point of the gradient

Returns:

a new gradient object

Return type:

Gradient

canvas.createRadialGradient(x1, y1, r1, x2, y2, r2)

Creates a radial gradient object.

Parameters:

  • x1 (number) – x-coordinate of the start circle

  • y1 (number) – y-coordinate of the start circle

  • r1 (number) – radius of the start circle

  • x2 (number) – x-coordinate of the end circle

  • y2 (number) – y-coordinate of the end circle

  • r2 (number) – radius of the end circle

Returns:

a new gradient object

Return type:

Gradient

canvas.setFont(font)

Sets a font style.

Parameters:

font (str) – The font style to be set, in the format of ‘font-style font-size font-family’. Example: ‘italic 20px Arial’.

canvas.setTextAlign(align)

Sets the current text alignment

Parameters:

align (str) – The new text alignment to be set. One of ‘start’, ‘end’, ‘left’, ‘right’, or ‘center’.

canvas.setTextBaseline(baseline)

Sets the text baseline used when drawing text.

Parameters:

baseline (str) – The text baseline to set. One of ‘alphabetic’, ‘top’, ‘hanging’, ‘middle’, ‘ideographic’, or ‘bottom’.

canvas.measureTextWidth(text)

Measures the width of the specified text in pixels.

Parameters:

text (str) – The text to measure.

canvas.fillText(text, x, y)

Draws and fills a given text string at the specified coordinates.

Parameters:

  • text (str) – The text string to be drawn and filled.

  • x (number) – The x-coordinate where the text will be drawn.

  • y (number) – The y-coordinate where the text will be drawn.

canvas.strokeText(text, x, y)

Draws the outline of the given text at the specified coordinates.

Parameters:

  • text (str) – The text string to be drawn.

  • x (number) – The x-coordinate where the text will be drawn.

  • y (number) – The y-coordinate where the text will be drawn.

canvas.scale(x, y)

Scales the canvas by the specified amount.

Parameters:

  • x (number) – amount to scale in x-axis.

  • y (number) – amount to scale in y-axis.

canvas.rotate(a)

Rotates the canvas by the specified angle.

Parameters:

a (number) – angle in radians to rotate the canvas.

canvas.translate(x, y)

Translates the canvas by the specified amount.

Parameters:

  • x (number) – amount to translate in x-axis.

  • y (number) – amount to translate in y-axis.

canvas.transform(horizontal_scale, horizontal_skew, vertical_skew, vertical_scale, horizontal_translation, vertical_translation)

Applies a 2D transformation matrix to the canvas.

Parameters:

  • horizontal_scale (number) – The amount to scale horizontally.

  • horizontal_skew (number) – The amount of horizontal skew.

  • vertical_skew (number) – The amount of vertical skew.

  • vertical_scale (number) – The amount to scale vertically.

  • horizontal_translation (number) – The amount of horizontal translation.

  • vertical_translation (number) – The amount of vertical translation.

canvas.resetAndSetTransform(horizontal_scale, horizontal_skew, vertical_skew, vertical_scale, horizontal_translation, vertical_translation)

Resets the current canvas transform to the identity matrix and then invokes the transform() function with the given parameters.

Parameters:

  • horizontal_scale (number) – The amount to scale horizontally.

  • horizontal_skew (number) – The amount of horizontal skew.

  • vertical_skew (number) – The amount of vertical skew.

  • vertical_scale (number) – The amount to scale vertically.

  • horizontal_translation (number) – The amount of horizontal translation.

  • vertical_translation (number) – The amount of vertical translation.

canvas.resetTransform()

Reset the transformation matrix to the identity matrix.

canvas.saveState()

Pushes the current canvas state to a stack to a a stack so that you can restore it.

This can be useful for performing multiple transformations or styles on the canvas, and then restoring it to its original state. The canvas state in fact includes current transformation matrix stroke and fill styles, shadow styles, and other attributes. To restore the canvas state you call the restoreState() function.

canvas.restoreState()

Pops the the most recently saved canvas from the saved state stack and restores it.

class canvas.Gradient

A class to internally link gradient objects from the Lua environment to Lumino codebase.

A Gradient object can be create using createLinearGradient or createRadialGradient

Examples

Draw a house
    local Canvas = require 'engine/canvas'

    Canvas.setLineWidth(10)
    Canvas.strokeRect(75, 140, 150, 110)
    Canvas.fillRect(130, 190, 40, 60)
    Canvas.beginPath()
    Canvas.moveTo(50, 140)
    Canvas.lineTo(150, 60)
    Canvas.lineTo(250, 140)
    Canvas.closePath()
    Canvas.stroke()
Draw a curve
    local Canvas = require 'engine/canvas'

    Canvas.beginPath();
    Canvas.moveTo(300, 100);
    Canvas.quadraticCurve(250, 350, 500, 120);
    -- or you can create a bezierCurve
    Canvas.bezierCurve(100, 200, 300, 200, 300, 120);
    Canvas.stroke();
    Canvas.closePath();
Create and apply gradients
    local Canvas = require 'engine/canvas'

    local gradient1 = Canvas.createLinearGradient(0, 0, 50, 0)
    Canvas.colorStop(gradient1, 0, 255, 0, 0, 0)
    Canvas.colorStop(gradient1, 1, 0, 0, 255, 0.5)
    Canvas.setGradientActive(gradient1)
    Canvas.fillRect(0, 0, 75, 75);

    local gradient2 = Canvas.createLinearGradient(0, 0, 0, 50)
    Canvas.colorStop(gradient2, 0, 255, 0, 0, 0)
    Canvas.colorStop(gradient2, 0.3, 128, 128, 0, 0.5)
    Canvas.colorStop(gradient2, 0.65, 0, 0, 0, 0.5)
    Canvas.colorStop(gradient2, 1, 0, 0, 255, 0.5)
    Canvas.setGradientActive(gradient2)
    Canvas.fillRect(75, 0, 75, 75);

    local gradient3 = Canvas.createRadialGradient(85, 88, 5, 88, 90, 69)
    Canvas.colorStop(gradient3, 0, 128, 128, 0, 0.5)
    Canvas.colorStop(gradient3, 1, 128, 128, 0, 0.5)
    Canvas.setGradientActive(gradient3)
    Canvas.circle(250, 100, 60);
    Canvas.fill()
Apply a transformation to the Canvas and restore to previous state
    local Canvas = require 'engine/canvas'

    local screenWidth = Canvas.getWidth()
    local screenHeight = Canvas.getHeight()


    Canvas.setFillColor(255, 0, 0, 1)
    Canvas.setFont("italic 12px Arial")

    Canvas.saveState()
    Canvas.setFillColor(0, 255, 0, 1)
    Canvas.setFont("20px Arial")
    -- Canvas.moveTo(5, 350)
    Canvas.rotate(0.25)
    Canvas.fillText("Rotated state", screenWidth/2, screenHeight/2)

    -- Restoring a state will also restore fill/stroke color
    -- and all transformation to the canvas
    Canvas.restoreState()
    Canvas.fillText("Original state restored!", screenWidth/2, screenHeight/2)
Composite Operation
    local Canvas = require 'engine/canvas'

    Canvas.setFillColor(255, 0, 0, 0.4)
    Canvas.fillRect(20, 20, 75, 50)
    Canvas.setCompositeOperation("source-over")
    Canvas.setFillColor(255, 0, 0, 1)
    Canvas.fillRect(50, 50, 75, 50)

    Canvas.setFillColor(255, 0, 0, 1)
    Canvas.fillRect(150, 20, 75, 50)
    Canvas.setCompositeOperation("destination-over")
    Canvas.setFillColor(0, 0, 255, 1)
    Canvas.fillRect(180, 50, 75, 50)
Set and show shadows
    local Canvas = require 'engine/canvas'

    Canvas.setFillColor(255, 0, 0, 0.4)

    Canvas.setShadowColor(0, 255, 0, 1)
    Canvas.setShadowBlurLevel(10)
    Canvas.setShadowOffset(25, 10)

    Canvas.fillRect(50, 50, 100, 100);
Clip a shape
    local Canvas = require 'engine/canvas'

    Canvas.beginPath()
    Canvas.pathRect(50, 20, 200, 120);
    Canvas.stroke();
    Canvas.clip();
    Canvas.setFillColor(255, 0, 0, 1)
    Canvas.fillRect(0, 0, 150, 100);
Display different line joins, line caps and miter limit
    local Canvas = require 'engine/canvas'

    local screenWidth = Canvas.getWidth()
    local screenHeight = Canvas.getHeight()

    Canvas.setLineJoin("miter")
    Canvas.setMiterLimit(5)
    Canvas.setLineCap("square")

    Canvas.beginPath()
    Canvas.setLineWidth(50)
    Canvas.moveTo(50, 80);
    Canvas.lineTo(screenWidth/2, screenHeight/2)
    Canvas.lineTo(50, screenHeight-80)
    Canvas.stroke()