Basalt2/docs/guides/canvas.md

Canvas Plugin Guide

The Canvas plugin allows you to draw various shapes and text on your elements. It provides a simple yet powerful way to create custom graphics.

Basic Usage

First, you need to get the canvas object:

local main = basalt.createFrame()
local canvas = main:getCanvas()

Drawing Functions

Lines

Draw a line from point (x1,y1) to (x2,y2):

canvas:line(1, 1, 10, 10, "*", colors.red, colors.black) -- Draws a red line

Rectangles

Create rectangles with specified dimensions:

canvas:rect(5, 5, 10, 5, "#", colors.blue, colors.white) -- Creates a blue rectangle

Ellipses

Draw ellipses/circles:

canvas:ellipse(10, 10, 5, 3, "@", colors.green, colors.black) -- Creates an ellipse

Text

Write text at specific coordinates:

canvas:text(1, 1, "Hello World!", colors.yellow, colors.black)

Color Management

Background Colors

Set background color at specific coordinates:

canvas:bg(1, 1, colors.blue)

Foreground Colors

Set foreground color at specific coordinates:

canvas:fg(1, 1, colors.white)

Render Types

The canvas plugin supports two different render types that control when the canvas commands are executed:

Setting the Render Type

canvas:setType(type)

Parameters:

• type: String, either "pre" or "post"
  • "pre": Commands are executed before the main object rendering (default)
  • "post": Commands are executed after the main object rendering

Example:

-- Create a canvas that renders after the main object
local canvas = main:addCanvas()
canvas:setType("post")

-- Add commands that will now execute after main rendering
canvas:addCommand(function()
    canvas:drawText(1, 1, "Overlay Text")
end)

-- or
canvas:line(1, 1, 10, 10, " ", colors.red, colors.green)

Note: Changing the render type affects all subsequent commands added to the canvas. You can have multiple canvas objects with different render types on the same base object.

Canvas Commands

Canvas commands allow you to create custom drawing operations using low-level drawing functions. Available commands are:

• textFg - Set text foreground color
• textBg - Set text background color
• drawText - Draw text
• drawFg - Draw foreground colors
• drawBg - Draw background colors
• blit - Draw text with foreground and background colors
• multiBlit - Draw multiple blit operations

Adding Commands

-- Example of proper command usage
canvas:addCommand(function()
    -- Draw red text on black background
    canvas:drawText(1, 1, "Hello")
    canvas:drawFg(1, 1, colors.red)
    canvas:drawBg(1, 1, colors.black)
    
    -- Or use blit for more efficient drawing
    canvas:blit(1, 2, "Hello", "fffff", "00000") -- white on black
end)

Advanced Blit Example

The multiBlit function allows you to render text efficiently in a rectangular area:

canvas:addCommand(function()
    -- Parameters: x, y, width, height, text, fg, bg
    canvas:multiBlit(1, 1, 5, 3, 
        "HelloWorld!Hello", -- text (width * height characters)
        "ffffffffff", -- fg colors (width * height characters)
        "0000000000"  -- bg colors (width * height characters)
    )
end)

Note: Do not use drawing functions like line, rect, or ellipse inside commands as this will cause render queue issues. Use the low-level drawing functions instead.