Storyboard Lua Canvas API

The Storyboard canvas API provides an interface for clients to perform their own basic drawing operations into an in-memory buffer. In order to access the drawing operations first a canvas render extension must be created and given a unique name within the application. Once a canvas render extension is created, a Lua canvas object can be accessed using the gre.get_canvas call. In this documentation the object returned from the gre.get_canvas functions will be identified as a CANVAS object. Methods associated with the CANVAS object must be invoked using the Lua colon (:) notation for example CANVAS:stroke_rect

The Lua canvas API is dependent on both the Lua plugin (libgre-plugin-lua) and the canvas render extension plugin (libgre-plugin-canvas).

CANVAS gre.get_canvas(name); 
nameThis is the name of the parameter;
 

gre.get_canvas

gre.get_canvas(name)

Get a canvas object handle by name


Returns:
        A CANVAS object that represents the canvas or nil if no canvas can be found.
                    

CANVAS:get_dimensions

CANVAS:get_dimensions()

Return the width and height of a canvas object.


Returns:
        A table containing two fields width and height
                    

function PrintCanvasSize(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    print(string.format("Canvas is %d x %d", size.width, size.height));
end

CANVAS:fill

CANVAS:fill(color)

Flood fill the entire canvas with a specific color


Parameters:
    color   An RGB color value as an integer value.
                    

-- Flood fill the canvas with a red background value
function FillWithRed(name)
    local canvas = gre.get_canvas(name)
    canvas:fill(0xff0000)
end

CANVAS:fill_rect

CANVAS:fill_rect(x1, y1, x2, y2, color)

Fill a rectangle defined by the bounding area of x1,y2 to x2,y2 with a specific color


Parameters:
    x1      The x position of the first corner
    y1      The y position of the first corner
    x2      The x position of the second corner
    y2      The y position of the second corner
    color   An RGB color value as an integer value.
                    

-- Draw three colored bars across the canvas
function FillRGB(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local rw = size.width / 3
    canvas:fill_rect(0,    0, rw,   size.height, 0xff0000)
    canvas:fill_rect(rw,   0, 2*rw, size.height, 0x00ff00)
    canvas:fill_rect(2*rw, 0, 3*rw, size.height, 0x0000ff)
end

CANVAS:fill_poly

CANVAS:fill_poly(xytable, color)

Fill the content of a polygon through the points defined in the xytable with a specific color. The polygon must be a closed simple polygon.


Parameters:
    xytable A Lua table {{x=x1,y=y1},{x=x2,y=y2}...}.  Alternatively two tables of parameters containing an
            array of points may be provided as in {x1,x2,..}, {y1,y2,..} similar to the section called “gre.poly_string”
    color   An RGB color value as an integer value.
                    

-- Fill a triangle using a polygon
function FillRedTrianglePoly(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local mid = size.width / 2

    -- Shrink the bounds to make the lines visible
    size.height = size.height - 2
    size.width = size.width - 2

    local pts = {}
    table.insert(pts, {x=2,y=2})
    table.insert(pts, {x=mid,y=size.height})
    table.insert(pts, {x=size.width,y=2})
    table.insert(pts, pts[1])               --Close the polygon
    canvas:fill_poly(pts, 0xff0000)
end

CANVAS:stroke_line

CANVAS:stroke_line(x1, y1, x2, y2, color)

Stroke a line between the points x1,y2 to x2,y2 with a specific color. The width of the line is the last value passed to CANVAS:set_line_width or 1 if no width has ever been specified.


Parameters:
    x1      The x position of the first corner
    y1      The y position of the first corner
    x2      The x position of the second corner
    y2      The y position of the second corner
    color   An RGB color value as an integer value.
                    

-- Stroke a triangle with three different colored line segments
function StrokeRGB(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local mid = size.width / 2

    -- Shrink the bounds to make the lines visible
    size.height = size.height - 2
    size.width = size.width - 2

    canvas:stroke_line(2, 2, mid, size.height, 0xff0000)
    canvas:stroke_line(mid, size.height, size.width, 2, 0x00ff00)
    canvas:stroke_line(2, 2, size.width, 2, 0x0000ff)
end

CANVAS:stroke_rect

CANVAS:stroke_rect(x1, y1, x2, y2, color)

Stroke a rectangle outline defined by the bounding area of x1,y2 to x2,y2 with a specific color. The width of the outline is the last value passed to CANVAS:set_line_width or 1 if no width has ever been specified.


Parameters:
    x1      The x position of the first corner
    y1      The y position of the first corner
    x2      The x position of the second corner
    y2      The y position of the second corner
    color   An RGB color value as an integer value.
                    

-- Draw three colored outlines across the canvas
function StrokeRGB(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local rw = size.width / 3
    canvas:stroke_rect(0,    0, rw-1,   size.height, 0xff0000)
    canvas:stroke_rect(rw,   0, 2*rw-1, size.height, 0x00ff00)
    canvas:stroke_rect(2*rw, 0, 3*rw-1, size.height, 0x0000ff)
end

CANVAS:stroke_poly

CANVAS:stroke_poly(xytable, color)

Stroke a polygon through the points defined in the xytable with a specific color. The width of the line is the last value passed to CANVAS:set_line_width or 1 if no width has ever been specified.


Parameters:
    xytable A Lua table {{x=x1,y=y1},{x=x2,y=y2}...}.  Alternatively two tables of parameters containing an
            array of points may be provided as in {x1,x2,..}, {y1,y2,..} similar to the section called “gre.poly_string”
    color   An RGB color value as an integer value.
                    

-- Stroke a triangle using a polygon
function StrokeRedTrianglePoly(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local mid = size.width / 2

    -- Shrink the bounds to make the lines visible
    size.height = size.height - 2
    size.width = size.width - 2

    local pts = {}
    table.insert(pts, {x=2,y=2})
    table.insert(pts, {x=mid,y=size.height})
    table.insert(pts, {x=size.width,y=2})
    table.insert(pts, pts[1])               --Close the polygon
    canvas:stroke_poly(pts, 0xff0000)
end

CANVAS:clear_rect

CANVAS:clear_rect(x1, y1, x2, y2)

Make transparent a rectangle defined by the bounding area of x1,y2 to x2,y2.


Parameters:
    x1      The x position of the first corner
    y1      The y position of the first corner
    x2      The x position of the second corner
    y2      The y position of the second corner
                    

-- Fill a canvas with red and poke a transparent hole in the middle of it
function MakeTransparentHole(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local hole_width = size.width / 3
    local hole_height = size.height / 3

    cavans:fill(0xff0000)
    canvas:clear_rect(hole_width, hole_height, 2*hole_width, 2*hole_height)
end

CANVAS:set_pixel

CANVAS:set_pixel(x, y, clr)

Set the pixel value at x, y to the specified color. This is equivalent to drawing a 1x1 filled rectangle.


Parameters:
    x       The x position pixel
    y       The y position pixel
    color   An RGB color value as an integer value.
                   

CANVAS:set_alpha

CANVAS:set_alpha(value)

Set the transparency level with which subsequent draw operations should be performed. The default value for alpha is 255 (fully opaque).


Parameters:
    value   An integer value from 0 (transparent) to 255 (opaque).  Values outside this range will be clamped.
                    

-- Draw three colored bars with different opacities across the canvas on
-- an orange background
function FillRGB(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local rw = size.width / 3
    canvas:fill(0xff8000)
    canvas:set_alpha(50)
    canvas:fill_rect(0,    0, rw,   size.height, 0xff0000)
    canvas:set_alpha(150)
    canvas:fill_rect(rw,   0, 2*rw, size.height, 0x00ff00)
    canvas:set_alpha(255)
    canvas:fill_rect(2*rw, 0, 3*rw, size.height, 0x0000ff)
end

CANVAS:set_line_width

CANVAS:set_line_width(value)

Set the line width in pixels that all subsequent stroke operations should use. The default value for line width is 1.


Parameters:
    value   An integer value greater than 1 indicating the pixel width.
                    

-- Draw three colored outlines width different widths across the canvas
function StrokeRGB(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local rw = size.width / 3
    canvas:set_line_width(5)
    canvas:stroke_rect(0,    0, rw-1,   size.height, 0xff0000)
    canvas:set_line_width(3)
    canvas:stroke_rect(rw,   0, 2*rw-1, size.height, 0x00ff00)
    canvas:set_line_width(1)
    canvas:stroke_rect(2*rw, 0, 3*rw-1, size.height, 0x0000ff)
end

CANVAS:draw_image

CANVAS:draw_image(name, attrs)

Draw an image within the canvas directed by the user specified properties.


Parameters:
    name    The project relative name of the image, same as used in the the section called “Image”
    attrs   A table of properties containing information about how to draw the image.  This table can
            contain the following keys:
                x   The x position of the upper left corner of the text (default 0)
                y   The y position of the upper left corner of the text (default 0)
                w   The width to scale the image to (default: natural width)
                h   The height to scale the image to (default: natural height)
                    

-- Draw an image scaled to the canvas size
function DrawImage(name)
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local attrs = {}
    attrs.w = size.width
    attrs.h = size.height
    canvas:draw_image("images/logo.png", attrs)
end

CANVAS:draw_text

CANVAS:draw_text(text, attrs)

Draw an string within the canvas directed by the user specified properties.


Parameters:
    text    The text string to display
    attrs   A table of properties containing information about how to draw the text.  This table can
            contain the following keys:
                font    The font to use to render the text (required, no default)
                x       The x position of the upper left corner of the image (default 0)
                y       The y position of the upper left corner of the image (default 0)
                size    The point size to render the text at (default 18)
                color   The color to render the text in (default black:0x00000)
                    

-- Draw a hello world string centered on the canvas
function DrawCenteredText(name)
    local msg = "Hello World"
    local canvas = gre.get_canvas(name)
    local size = canvas:get_dimensions()
    local attrs = {}
    attrs.font = "fonts/RobotoBold.ttf"
    attrs.size = 24
    local strSize = gre.get_string_size(attrs.font, attrs.size, msg, 0)
    attrs.x = (size.width - strSize.width) / 2
    attrs.y = (size.height - strSize.height) / 2
    canvas:draw_image("Hello World", attrs)
end