SleelaUI™ Draw API
A comprehensive, low-level 2D drawing surface for developers and agents.
Where sleela_ui.h gives you widgets,
sleela_ui_draw.h gives you the pixels —
rendered by the toolkit's own software rasterizer, so your drawing is
pixel-identical on Windows, macOS, and Linux/Unix.
It is the substrate the animated Throbber is built on, and the public API any custom visualisation uses through the Canvas View widget.
What you get
- Draw context — an owned RGBA surface at any size, single- or double-buffered.
- Pixel-level control — read/write individual pixels, a per-op blend mode, a layer opacity, a clip stack, and a raw buffer lock for direct access.
- A complete primitive set — clear, points, antialiased lines + polylines, rects, rounded rects, circles, ellipses, arcs, triangles, linear and radial gradients, text, and surface-to-surface blits.
- Buffering — draw into a back buffer and
present()it so animation never tears or flickers. - Refresh-rate control — a frame clock with a target FPS, per-frame delta time, a smoothed measured rate, a sleep hint, and a fixed-timestep accumulator for deterministic simulation.
- Predictive-colour helpers — HSV, colour lerp, and luminance for smooth, natural, flowing colour fields.
Draw context
#include "sleela_ui_draw.h"
SLUIDrawContext *dc = slui_draw_create(640, 360, SLUI_BUFFER_DOUBLE);
slui_draw_clear(dc, slui_rgb(0x0d, 0x0d, 0x0f));
slui_draw_fill_round_rect(dc, (SLUIRect){20, 20, 120, 60}, 8, slui_rgb(0x5e,0x9c,0xff));
slui_draw_line(dc, 0, 0, 640, 360, 2.0, slui_rgb(255,255,255));
slui_draw_fill_circle(dc, 320, 180, 40, slui_color_hsv(205, 0.8, 1.0, 1.0));
slui_draw_present(dc); /* publish back -> front */
/* read one pixel, or the whole image as RGBA8 */
SLUIColor p = slui_draw_get_pixel(dc, 320, 180);
uint8_t rgba[640*360*4];
slui_draw_read_rgba(dc, rgba, sizeof rgba);
slui_draw_destroy(dc);
Buffer modes
| Mode | Behaviour |
|---|---|
SLUI_BUFFER_SINGLE | Draw into and read the one surface; present() is a no-op. |
SLUI_BUFFER_DOUBLE | Draw into a back buffer; present() copies it to the front. Read-backs and widget blits see the front. Use for flicker-free animation. |
Blend modes
Set with slui_draw_set_blend; applies to every primitive and set_pixel.
| Mode | Effect |
|---|---|
SLUI_BLEND_OVER | src over dst (straight-alpha, the default) |
SLUI_BLEND_COPY | overwrite dst with src |
SLUI_BLEND_ADD | additive — light accumulation; great for glow/water crests |
SLUI_BLEND_MULTIPLY | darken |
SLUI_BLEND_SCREEN | lighten |
SLUI_BLEND_MAX | per-channel maximum |
slui_draw_set_opacity(dc, 0..1) multiplies every source alpha — a layer
opacity. slui_draw_clip_push/pop/reset constrain drawing to a rectangle.
Pixel-level control
slui_draw_set_pixel(dc, x, y, color); /* honours blend + opacity */
SLUIColor c = slui_draw_get_pixel(dc, x, y); /* front buffer, 0xRRGGBBAA */
slui_draw_blend_pixel(dc, x, y, color, 0.5); /* sub-pixel AA by hand */
int stride; /* words per row (== width) */
uint32_t *raw = slui_draw_lock(dc, &stride); /* 0xAARRGGBB words */
/* ... touch raw[y*stride + x] directly ... */
slui_draw_unlock(dc);
Primitives
void slui_draw_fill_rect / fill_round_rect / stroke_rect / stroke_round_rect(...);
void slui_draw_line(dc, x0,y0, x1,y1, thickness, color); /* AA, round-cap */
void slui_draw_polyline(dc, xy, count, thickness, color);
void slui_draw_fill_circle / stroke_circle / fill_ellipse(...);
void slui_draw_arc(dc, cx,cy, r, start_rad, sweep_rad, thickness, color);
void slui_draw_fill_triangle(dc, x0,y0, x1,y1, x2,y2, color);
void slui_draw_linear_gradient(dc, rect, axis, c0, c1);
void slui_draw_radial_gradient(dc, cx,cy, radius, inner, outer);
void slui_draw_text(dc, utf8, x, baseline, color);
void slui_draw_blit(dst, src, dx, dy, src_rect); /* ctx -> ctx */
All honour the active clip, blend mode, and layer opacity. Coordinates are device pixels; thicknesses and radii are doubles (sub-pixel).
Colour helpers
SLUIColor m = slui_color_lerp(a, b, t); /* blend, t in [0,1] */
SLUIColor h = slui_color_hsv(205, 0.8, 1.0, 1.0); /* flowing hues, h in deg */
double L = slui_color_luminance(c); /* perceptual-ish, [0,1] */
Refresh-rate control (frame clock)
SLUIFrameClock *fc = slui_frame_clock_create(60.0); /* target FPS */
while (running) {
double dt = slui_frame_clock_tick(fc); /* seconds since last */
/* deterministic fixed-step updates regardless of frame rate */
while (slui_frame_clock_fixed_step(fc, 1.0/120.0)) simulate(1.0/120.0);
draw(dc);
slui_draw_present(dc);
int ms = slui_frame_clock_sleep_hint(fc); /* idle to hit 60Hz */
if (ms > 0) host_sleep_ms(ms);
}
double shown = slui_frame_clock_measured_fps(fc); /* smoothed actual FPS */
double t = slui_frame_clock_elapsed(fc); /* animation time */
slui_frame_clock_destroy(fc);
tick() clamps a long stall so a paused window can't explode a simulation.
Driving an animation inside a window: the Canvas View
A Canvas View widget owns a double-buffered context sized to its bounds and, each frame while visible, calls your draw function then presents + blits the result into the window. The window's event loop drives the frames at the view's requested rate — you do not write a loop yourself.
static void draw(SLUIDrawContext *dc, double time_s, double dt_s, void *user) {
slui_draw_clear(dc, slui_rgb(0x0d,0x0d,0x0f));
double x = (0.5 + 0.5*sin(time_s)) * slui_draw_width(dc);
slui_draw_fill_circle(dc, x, slui_draw_height(dc)/2.0, 10,
slui_color_hsv(time_s*60, 0.8, 1.0, 1.0));
}
SLUIWidget *view = slui_canvas_view(root, 400, 80);
slui_canvas_view_set_fps(view, 60.0);
slui_canvas_view_set_draw(view, draw, NULL);
The Throbber
The Throbber is a Canvas View whose built-in draw function is a water-like flow field — see THROBBER.md for the model. It is width-adjustable, full-motion, and colour-predictive (the hue leads the flow), tuned to approach the ease of real flowing water without exceeding it.
SLUIWidget *t = slui_throbber(root, 400); /* initial width in px */
slui_widget_set_size_request(t, 0, 24); /* height (a slim seam default) */
slui_throbber_set_width(t, 520); /* adjustable any time */
slui_throbber_set_intensity(t, 0.7); /* 0 calm .. 1 vigorous */
slui_throbber_set_hue(t, 205); /* base hue (deg); 205 ~ water */
SLeeLa bindings
Every call here has a one-class-per-file SLeeLa binding under
/lib/user-interface: SLDrawContext
(the full primitive/pixel/buffer surface), SLFrameClock (refresh pacing),
SLCanvasView (the hosted draw surface), and SLThrobber (the water throbber).
— SleelaUI™ · MEARVK LLC · 2026