Home /Modules/ui/sleela_ui_draw.h

sleela_ui_draw.h

ui/include/sleela_ui_draw.h · 225 line(s) · c

#ifndef SLEELA_UI_DRAW_H
#define SLEELA_UI_DRAW_H
/* =============================================================================
 * SleelaUI(TM) Draw API -- the comprehensive, low-level 2D drawing surface for
 * developers and agents.
 *
 * Where sleela_ui.h gives you widgets, this header gives you the PIXELS. It
 * exposes the toolkit's own software rasterizer as a stable C ABI so you can:
 *
 *   * own an off-screen pixel surface (a draw context) at any size;
 *   * draw with a complete primitive set -- clear, points, lines (AA), rects,
 *     rounded rects, circles/ellipses/arcs, polylines, triangles, gradients
 *     (linear + radial), text, and surface-to-surface blits;
 *   * work at the PIXEL LEVEL -- read and write individual pixels, choose a
 *     blend mode, lock the raw buffer for direct access, apply the clip;
 *   * control BUFFERING -- single or double buffered, with an explicit
 *     back-buffer you draw into and a present()/swap() that publishes it, so
 *     animation never tears or flickers;
 *   * pace REFRESH -- a frame clock with a target rate (FPS), per-frame delta
 *     time, an accumulator for fixed-step simulation, and a sleep hint so a
 *     render loop runs smoothly without busy-spinning.
 *
 * A draw context can be free-standing (an image you render and read back) or
 * BOUND TO A WIDGET -- the SLUICanvasView widget (see sleela_ui.h) hands its
 * per-frame surface to a developer draw callback, which is exactly how the
 * animated Throbber and any custom visualisation are built.
 *
 * All colours are the same 0xRRGGBBAA words as sleela_ui.h (SLUIColor), and all
 * geometry uses SLUIRect/SLUIPoint, so the two headers compose cleanly.
 *
 * Max Rupplin -- MEARVK LLC -- 2026
 * ===========================================================================*/
#include "sleela_ui.h"

#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/* --------------------------------------------------------------------------
 * Draw context: an owned RGBA pixel surface with an optional back buffer.
 * ------------------------------------------------------------------------- */
typedef struct SLUIDrawContext SLUIDrawContext;

typedef enum {
    SLUI_BUFFER_SINGLE = 0, /* draw and read the one surface directly       */
    SLUI_BUFFER_DOUBLE = 1  /* draw into a back buffer, present() to publish */
} SLUIBufferMode;

/* Pixel compositing mode for every primitive and set_pixel. */
typedef enum {
    SLUI_BLEND_OVER = 0,     /* src OVER dst (straight-alpha, the default)   */
    SLUI_BLEND_COPY = 1,     /* overwrite dst with src (ignores dst alpha)   */
    SLUI_BLEND_ADD = 2,      /* additive (light accumulation; great for glow)*/
    SLUI_BLEND_MULTIPLY = 3, /* multiplicative (darken)                      */
    SLUI_BLEND_SCREEN = 4,   /* screen (lighten)                             */
    SLUI_BLEND_MAX = 5       /* per-channel maximum                          */
} SLUIBlendMode;

/* Create a free-standing context of `width` x `height` device pixels. */
SLUIDrawContext *slui_draw_create(int width, int height, SLUIBufferMode mode);
void slui_draw_destroy(SLUIDrawContext *dc);

/* Resize the surface(s); contents are undefined afterward (clear to repaint). */
SLUIStatus slui_draw_resize(SLUIDrawContext *dc, int width, int height);
int slui_draw_width(const SLUIDrawContext *dc);
int slui_draw_height(const SLUIDrawContext *dc);

/* The active blend mode applied by subsequent primitives. */
void slui_draw_set_blend(SLUIDrawContext *dc, SLUIBlendMode mode);
SLUIBlendMode slui_draw_get_blend(const SLUIDrawContext *dc);

/* A global multiplier (0..1) applied to every source alpha -- a layer opacity. */
void slui_draw_set_opacity(SLUIDrawContext *dc, double opacity);

/* Clip subsequent drawing to a rectangle; push/pop nest; reset clears all. */
void slui_draw_clip_push(SLUIDrawContext *dc, SLUIRect r);
void slui_draw_clip_pop(SLUIDrawContext *dc);
void slui_draw_clip_reset(SLUIDrawContext *dc);

/* --------------------------------------------------------------------------
 * Buffering. In SLUI_BUFFER_DOUBLE mode you draw into the back buffer and call
 * present() to copy it to the front; read-backs and widget blits see the front.
 * In SLUI_BUFFER_SINGLE mode present() is a no-op. clear() wipes the active
 * (draw) buffer to a solid colour.
 * ------------------------------------------------------------------------- */
void slui_draw_clear(SLUIDrawContext *dc, SLUIColor color);
void slui_draw_present(SLUIDrawContext *dc); /* publish back -> front         */

/* --------------------------------------------------------------------------
 * Pixel-level control.
 * ------------------------------------------------------------------------- */
/* Set/get one pixel. set honours the active blend mode and opacity; get reads
 * the front buffer and returns straight-alpha 0xRRGGBBAA (0 if out of range). */
void slui_draw_set_pixel(SLUIDrawContext *dc, int x, int y, SLUIColor color);
SLUIColor slui_draw_get_pixel(const SLUIDrawContext *dc, int x, int y);

/* Blend one pixel with explicit coverage [0..1] (sub-pixel AA by hand). */
void slui_draw_blend_pixel(SLUIDrawContext *dc, int x, int y, SLUIColor color,
                           double coverage);

/* Lock the raw back-buffer words for direct read/write. The layout is tightly
 * packed 0xAARRGGBB, `*stride_words` words per row (== width). Call unlock when
 * done; the pointer is invalidated by resize/destroy. Returns NULL on error. */
uint32_t *slui_draw_lock(SLUIDrawContext *dc, int *stride_words);
void slui_draw_unlock(SLUIDrawContext *dc);

/* Copy the front buffer out as tightly-packed RGBA8 (4 bytes/pixel, top-down),
 * for screenshots, encoders, or tests. `cap` is the byte capacity of `out`;
 * returns the number of bytes the full image needs (write happens if it fits). */
size_t slui_draw_read_rgba(const SLUIDrawContext *dc, uint8_t *out, size_t cap);

/* --------------------------------------------------------------------------
 * Primitives. All honour the clip, blend mode, and layer opacity. Coordinates
 * are device pixels; thickness and radii are in pixels (doubles for sub-pixel).
 * ------------------------------------------------------------------------- */
void slui_draw_fill_rect(SLUIDrawContext *dc, SLUIRect r, SLUIColor color);
void slui_draw_fill_round_rect(SLUIDrawContext *dc, SLUIRect r, double radius,
                               SLUIColor color);
void slui_draw_stroke_rect(SLUIDrawContext *dc, SLUIRect r, double thickness,
                           SLUIColor color);
void slui_draw_stroke_round_rect(SLUIDrawContext *dc, SLUIRect r, double radius,
                                 double thickness, SLUIColor color);

/* Antialiased line of a given thickness (round-capped). */
void slui_draw_line(SLUIDrawContext *dc, double x0, double y0, double x1,
                    double y1, double thickness, SLUIColor color);
/* A connected polyline through `count` points (2 ints each: x,y). */
void slui_draw_polyline(SLUIDrawContext *dc, const int *xy, int count,
                        double thickness, SLUIColor color);

void slui_draw_fill_circle(SLUIDrawContext *dc, double cx, double cy,
                           double radius, SLUIColor color);
void slui_draw_stroke_circle(SLUIDrawContext *dc, double cx, double cy,
                             double radius, double thickness, SLUIColor color);
void slui_draw_fill_ellipse(SLUIDrawContext *dc, double cx, double cy, double rx,
                            double ry, SLUIColor color);
/* An arc (stroked) from `start_rad` sweeping `sweep_rad` radians, 0 = +x axis. */
void slui_draw_arc(SLUIDrawContext *dc, double cx, double cy, double radius,
                   double start_rad, double sweep_rad, double thickness,
                   SLUIColor color);

/* A filled triangle (flat-shaded). */
void slui_draw_fill_triangle(SLUIDrawContext *dc, double x0, double y0,
                             double x1, double y1, double x2, double y2,
                             SLUIColor color);

/* Gradients filling a rect. Linear interpolates c0->c1 along the axis; radial
 * interpolates centre->edge within the rect's inscribed radius. */
void slui_draw_linear_gradient(SLUIDrawContext *dc, SLUIRect r,
                               SLUIOrientation axis, SLUIColor c0, SLUIColor c1);
void slui_draw_radial_gradient(SLUIDrawContext *dc, double cx, double cy,
                               double radius, SLUIColor inner, SLUIColor outer);

/* Text, using the window/application font the host last selected (or a default
 * system face). Draws left-to-right from the baseline at (x, baseline). */
void slui_draw_text(SLUIDrawContext *dc, const char *utf8, int x, int baseline,
                    SLUIColor color);

/* Blit another context's front buffer at (dx, dy) with the active blend/opacity.
 * `src_rect` may be NULL to copy the whole source. */
void slui_draw_blit(SLUIDrawContext *dst, const SLUIDrawContext *src, int dx,
                    int dy, const SLUIRect *src_rect);

/* --------------------------------------------------------------------------
 * Colour helpers for predictive / generative drawing. These are pure value
 * utilities (no context needed) that make smooth, natural colour fields easy.
 * ------------------------------------------------------------------------- */
/* Linear blend of two colours, t in [0,1]. */
SLUIColor slui_color_lerp(SLUIColor a, SLUIColor b, double t);
/* HSV -> packed colour. h in [0,360), s,v,a in [0,1]. Ideal for flowing hues. */
SLUIColor slui_color_hsv(double h, double s, double v, double a);
/* A perceptual-ish luminance of a colour in [0,1]. */
double slui_color_luminance(SLUIColor c);

/* --------------------------------------------------------------------------
 * Frame clock: refresh-rate control for a render loop.
 *
 * Typical loop:
 *     SLUIFrameClock *fc = slui_frame_clock_create(60.0);
 *     while (running) {
 *         double dt = slui_frame_clock_tick(fc);   // seconds since last tick
 *         update(dt);
 *         draw(dc);
 *         slui_draw_present(dc);
 *         int ms = slui_frame_clock_sleep_hint(fc);// how long to idle for 60Hz
 *         if (ms > 0) host_sleep_ms(ms);
 *     }
 * ------------------------------------------------------------------------- */
typedef struct SLUIFrameClock SLUIFrameClock;

SLUIFrameClock *slui_frame_clock_create(double target_fps);
void slui_frame_clock_destroy(SLUIFrameClock *fc);

/* Set/get the target refresh rate in frames per second (0 = unthrottled). */
void slui_frame_clock_set_fps(SLUIFrameClock *fc, double target_fps);
double slui_frame_clock_get_fps(const SLUIFrameClock *fc);

/* Advance the clock one frame; returns the delta time in seconds since the
 * previous tick (clamped to a sane max so a stall can't explode a simulation). */
double slui_frame_clock_tick(SLUIFrameClock *fc);

/* Seconds since the clock was created (monotonic animation time). */
double slui_frame_clock_elapsed(const SLUIFrameClock *fc);

/* The measured, smoothed frames-per-second actually being achieved. */
double slui_frame_clock_measured_fps(const SLUIFrameClock *fc);

/* Milliseconds the caller should idle to hit the target rate (0 if behind). */
int slui_frame_clock_sleep_hint(const SLUIFrameClock *fc);

/* Fixed-timestep helper: accumulate real time and drain it in `step` chunks so
 * physics/field updates stay deterministic regardless of frame rate. Call tick
 * first, then repeatedly call this until it returns 0, running one fixed step
 * each time it returns 1. */
int slui_frame_clock_fixed_step(SLUIFrameClock *fc, double step);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* SLEELA_UI_DRAW_H */