🎨 Canvas

The Canvas widget provides a transparent drawing surface where you can render custom shapes, lines, and pixel data at runtime. While most Artok widgets are pre-defined, the Canvas allows for low-level graphical manipulation, making it ideal for custom gauges, drawing apps, or dynamic masking.

---

⚙️ Properties (Props)

The Canvas configuration is defined by the CanvasWidget interface. Unlike other widgets, its primary requirement is memory allocation for the drawing buffer.

Property	Type	Description
Buffer Size	number	The amount of RAM (in bytes) allocated for the canvas pixel data.
X / Y	number	The coordinate position on the screen.
Width / Height	number	The resolution of the drawing area.

---

🛠 Drawing Principles

The Canvas acts as a layer where pixels are manipulated directly. Because it uses a dedicated buffer, you should keep the following in mind:

• Memory Usage: The memory required is calculated as Width × Height × (Bits Per Pixel / 8). For example, a 100x100 canvas at 16-bit depth requires roughly 20KB of RAM.
• Redrawing: Changes to the canvas are not visible until the blur or fill commands are completed and the widget is invalidated (refreshed).
• Layering: You can draw standard primitives (rectangles, circles, text) onto the Canvas using the Lua API.

---

⚡ Runtime API (Lua)

The Canvas is almost entirely controlled via Logic and Events scripts.

-- Fill the entire canvas with a background color
canvas_main:fill_bg(0x222222, 255) -- Dark gray, full opacity

-- Draw a custom rectangle
local rect_draw = {
    x = 10, y = 10, 
    w = 50, h = 50,
    color = 0x00FF00,
    radius = 5
}
canvas_main:draw_rect(rect_draw)

-- Draw a single pixel
canvas_main:set_px(25, 25, 0xFFFFFF)

---

PRO FEATURE

The Canvas widget consumes significant internal RAM compared to other widgets. On hardware with limited memory (like bare-metal RISC-V or small ESP32 projects), use the Canvas sparingly and keep the dimensions as small as possible.

---

🚀 Next Steps

• Static Image — Use this if your graphic doesn't need to change pixel-by-pixel at runtime.
• Line — A lighter alternative for drawing simple vector paths.
• BPP Settings — Learn how bit depth affects your canvas memory calculations.