Home /Modules/ui/DRAW-API.md

DRAW-API.md

ui/DRAW-API.md · 175 line(s) · markdown

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

#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

ModeBehaviour
SLUI_BUFFER_SINGLEDraw into and read the one surface; present() is a no-op.
SLUI_BUFFER_DOUBLEDraw 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.

ModeEffect
SLUI_BLEND_OVERsrc over dst (straight-alpha, the default)
SLUI_BLEND_COPYoverwrite dst with src
SLUI_BLEND_ADDadditive — light accumulation; great for glow/water crests
SLUI_BLEND_MULTIPLYdarken
SLUI_BLEND_SCREENlighten
SLUI_BLEND_MAXper-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