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(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()
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(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(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(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(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(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(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(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(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(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(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(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(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_text("Hello World", attrs)
end