Home /Modules/user-interface/slui_throbber.cpp

slui_throbber.cpp

user-interface/src/slui_throbber.cpp · 338 line(s) · c

/* =============================================================================
 * SleelaUI Throbber + CanvasView.
 *
 * CanvasView is the general animated drawing widget: it owns a double-buffered
 * SLUIDrawContext sized to its bounds and, each frame, lets a developer draw
 * callback paint into it with the comprehensive Draw API, then blits the result
 * into the window. Throbber is a CanvasView with a built-in draw callback that
 * is a WATER-LIKE FLOW FIELD.
 *
 * The flow model (why it reads as water, not a mechanical scroll):
 *
 *   * A 1-D field across the throbber's width carries a surface HEIGHT h[i] and
 *     a VELOCITY u[i]. Each step we advect height by velocity and apply a light
 *     diffusion + restoring force -- a shallow-water-style relaxation -- so
 *     disturbances propagate as travelling crests that disperse and recombine
 *     the way ripples do, instead of a rigid marquee.
 *   * Motion is integrated so the field SPEEDS UP AND SLOWS DOWN smoothly (the
 *     drive is a slow sinusoidal "amplification", bounded in its rate of
 *     change), echoing the project's existing throbber jerk-bounded feel but
 *     made fluid.
 *   * COLOUR IS PREDICTIVE: a crest is coloured by where it is ABOUT TO BE --
 *     the hue is advanced along the base hue by the local velocity, so faster
 *     water leads warmer/forward in hue and the colour arrives slightly ahead
 *     of the crest. Under strong amplification the hue spread widens (latent
 *     colour surfaces on the brightest crests) then recedes as the field calms.
 *   * WIDTH IS ADJUSTABLE: the field resamples to any pixel width while keeping
 *     the same physical wavelength feel, so a 40px and a 400px throbber look
 *     like the same water at different crops.
 *
 * It is "more natural than Water? -- no": the model is tuned to approach, not
 * exceed, the ease of real flowing water: bounded acceleration, energy that
 * only ever dissipates between impulses, and no instantaneous jumps.
 *
 * Max Rupplin -- MEARVK LLC -- 2026
 * ===========================================================================*/
#include "slui_widget.hpp"

#include "sleela_ui_draw.h"
#include "sleela_ui_light.h"
#include "slui_backend.hpp"
#include "slui_render.hpp"

#include <algorithm>
#include <cmath>
#include <vector>

namespace slui {

/* ---- CanvasView --------------------------------------------------------- */
CanvasView::CanvasView(int min_w, int min_h)
    : Widget(WidgetKind::CanvasView), req_w_(min_w), req_h_(min_h) {}

CanvasView::~CanvasView() {
    if (ctx_) slui_draw_destroy(ctx_);
}

SLUISize CanvasView::measure(const PaintContext&) {
    return SLUISize{req_w_ + margin_.left + margin_.right,
                    req_h_ + margin_.top + margin_.bottom};
}

void CanvasView::apply_light() {
    if (!light_scene_ || !ctx_) return;
    SLUIMaterial m{};
    m.profile = static_cast<SLUIReliefProfile>(light_profile_);
    m.depth = light_depth_;
    m.gloss = light_gloss_;
    m.occlusion = light_occlusion_;
    m.edge_px = light_edge_;
    SLUIRect full{0, 0, ctx_w_, ctx_h_};
    slui_light_apply_relief(ctx_,
                            full,
                            /*radius=*/0.0, m,
                            static_cast<const SLUILightScene*>(light_scene_));
}

void CanvasView::ensure_context(int w, int h) {
    if (w < 1) w = 1;
    if (h < 1) h = 1;
    if (!ctx_) {
        ctx_ = slui_draw_create(w, h, SLUI_BUFFER_DOUBLE);
        ctx_w_ = w;
        ctx_h_ = h;
    } else if (ctx_w_ != w || ctx_h_ != h) {
        slui_draw_resize(ctx_, w, h);
        ctx_w_ = w;
        ctx_h_ = h;
    }
}

void CanvasView::paint(PaintContext& ctx) {
    Rect c = content();
    if (c.empty()) return;
    ensure_context(c.w, c.h);
    if (draw_fn_ && ctx_) {
        draw_fn_(ctx_, time_, last_dt_, draw_user_);
        apply_light(); /* light + relieve the whole view, if a scene is set */
        slui_draw_present(ctx_);
        /* Blit the context's front buffer into the window canvas. */
        const int stride = ctx_w_;
        /* read directly from the draw context's published pixels */
        uint32_t* px = slui_draw_lock(ctx_, nullptr);
        if (px) {
            /* lock returns the DRAW target; we want the FRONT (published) one.
             * Instead read via get_pixel through the public API blit path by
             * compositing word-for-word here using the ABI read. */
            slui_draw_unlock(ctx_);
        }
        /* Composite the published surface pixel-for-pixel into the window. */
        for (int y = 0; y < c.h; ++y) {
            for (int x = 0; x < c.w; ++x) {
                SLUIColor word = slui_draw_get_pixel(ctx_, x, y);
                Color k = Color::from_abi(word);
                if (k.a == 0) continue;
                ctx.canvas->blend(c.x + x, c.y + y, k, 1.0);
            }
        }
        (void)stride;
    }
}

/* ---- Throbber water field ----------------------------------------------- */
namespace {

/* Per-throbber flow state, owned via the draw user pointer. */
struct WaterField {
    int cells = 0;             /* resolution across the width               */
    std::vector<double> h;     /* surface height (relative, ~[-1,1])        */
    std::vector<double> u;     /* horizontal velocity                       */
    std::vector<double> hue_lead; /* smoothed predictive hue offset / cell  */
    double drive_phase = 0.0;  /* slow amplification oscillator phase       */
    double amp = 0.6;          /* current amplification [0..1]              */
    double amp_vel = 0.0;      /* its bounded rate of change                */
    double spawn_accum = 0.0;  /* impulse accumulator                       */
    double base_hue = 205.0;
    double intensity = 0.6;
    uint32_t rng = 0x1234567u;

    double rand01() {
        /* xorshift -> [0,1) */
        rng ^= rng << 13;
        rng ^= rng >> 17;
        rng ^= rng << 5;
        return (rng & 0xFFFFFF) / static_cast<double>(0x1000000);
    }

    void ensure(int width_px) {
        /* ~1 cell per 3 px keeps the wavelength natural at any width. */
        int want = std::max(16, width_px / 3);
        if (want != cells) {
            std::vector<double> nh(want, 0.0), nu(want, 0.0), nl(want, 0.0);
            /* resample existing field so a width change keeps the water */
            for (int i = 0; i < want; ++i) {
                if (cells > 0) {
                    double s = i * (cells - 1) / static_cast<double>(want - 1 > 0 ? want - 1 : 1);
                    int si = static_cast<int>(s);
                    double f = s - si;
                    int sj = std::min(si + 1, cells - 1);
                    nh[i] = h[si] * (1 - f) + h[sj] * f;
                    nu[i] = u[si] * (1 - f) + u[sj] * f;
                    nl[i] = hue_lead[si] * (1 - f) + hue_lead[sj] * f;
                }
            }
            h.swap(nh);
            u.swap(nu);
            hue_lead.swap(nl);
            cells = want;
        }
    }
};

/* Step the shallow-water-like field forward by dt seconds. */
void step_field(WaterField& w, double dt) {
    int n = w.cells;
    if (n < 4) return;
    /* Clamp dt for stability; sub-step if the frame was long. */
    double remaining = std::min(dt, 0.1);
    const double sub = 1.0 / 240.0;
    while (remaining > 1e-6) {
        double s = std::min(sub, remaining);
        remaining -= s;

        /* Slow amplification drive: a bounded 2nd-order oscillator so the whole
         * field eases faster and slower (speeds up / slows down smoothly). */
        w.drive_phase += s * (0.25 + 0.9 * w.intensity);
        double target = 0.5 + 0.5 * std::sin(w.drive_phase);
        double accel = (target - w.amp) * 6.0 - w.amp_vel * 2.5;
        /* bound the jerk by capping |accel| */
        accel = std::clamp(accel, -4.0, 4.0);
        w.amp_vel += accel * s;
        w.amp += w.amp_vel * s;
        w.amp = std::clamp(w.amp, 0.0, 1.0);

        /* Occasional impulses feed the water, mostly from the left (flow is
         * mainly left->right). Rate scales with intensity + amplification. */
        w.spawn_accum += s * (2.0 + 10.0 * w.intensity) * (0.3 + w.amp);
        while (w.spawn_accum > 1.0) {
            w.spawn_accum -= 1.0;
            int at = (w.rand01() < 0.7)
                         ? static_cast<int>(w.rand01() * n * 0.35) /* left-biased */
                         : static_cast<int>(w.rand01() * n);
            at = std::clamp(at, 1, n - 2);
            double push = (0.4 + 0.6 * w.amp) * (0.6 + 0.8 * w.rand01());
            w.h[at] += push;
            w.u[at] += push * 1.2; /* give it rightward momentum */
        }

        /* Shallow-water update: height advected by velocity gradient, velocity
         * driven by height gradient (a wave equation) plus mild damping. */
        const double c2 = 0.9;   /* wave speed^2 (controls wavelength)       */
        const double visc = 0.6; /* viscosity -> ripples disperse like water */
        const double damp = 0.25;
        const double drift = 0.8 + 1.6 * w.intensity; /* mean rightward flow */
        std::vector<double> nh(w.h), nu(w.u);
        for (int i = 1; i < n - 1; ++i) {
            double dhdx = (w.h[i + 1] - w.h[i - 1]) * 0.5;
            double dudx = (w.u[i + 1] - w.u[i - 1]) * 0.5;
            /* velocity follows -g * dh/dx, with a steady rightward drift */
            nu[i] = w.u[i] + s * (-c2 * dhdx * 4.0) - s * damp * w.u[i];
            nu[i] += s * drift * (target - 0.5) * 0.4;
            /* height follows -d(h*u)/dx ~ -(u*dh/dx + h*du/dx) */
            nh[i] = w.h[i] - s * (w.u[i] * dhdx + w.h[i] * dudx) * 2.0;
            /* viscosity: blend toward the local average (ripple dispersion) */
            double avg = (w.h[i - 1] + w.h[i + 1]) * 0.5;
            nh[i] += s * visc * (avg - w.h[i]);
            nh[i] *= (1.0 - s * damp * 0.5); /* energy only dissipates */
        }
        /* soft reflective-ish boundaries */
        nh[0] = nh[1] * 0.6;
        nh[n - 1] = nh[n - 2] * 0.6;
        nu[0] = nu[1];
        nu[n - 1] = nu[n - 2];
        w.h.swap(nh);
        w.u.swap(nu);

        /* Predictive hue: lead the base hue by the local velocity so colour
         * arrives slightly ahead of the crest; smooth it so it flows. */
        for (int i = 0; i < n; ++i) {
            double lead = w.u[i] * (30.0 + 60.0 * w.amp); /* degrees ahead */
            w.hue_lead[i] += (lead - w.hue_lead[i]) * std::min(1.0, s * 12.0);
        }
    }
}

/* The Throbber's internal draw callback: step the water, then paint it. */
void throbber_draw(SLUIDrawContext* dc, double /*time_s*/, double dt_s,
                   void* user) {
    WaterField& w = *static_cast<WaterField*>(user);
    int W = slui_draw_width(dc), H = slui_draw_height(dc);
    w.ensure(W);
    step_field(w, dt_s > 0 ? dt_s : 1.0 / 60.0);

    /* At rest the strip is the warm chrome floor (0.8x of Sleela's #2B1608
     * base); crests light up over it. */
    slui_draw_clear(dc, slui_rgb(0x22, 0x12, 0x06));

    int n = w.cells;
    /* Draw additively so overlapping crests accumulate light like water. */
    slui_draw_set_blend(dc, SLUI_BLEND_ADD);
    for (int x = 0; x < W; ++x) {
        /* sample the field at this column */
        double fx = n > 1 ? x * (n - 1) / static_cast<double>(W - 1 > 0 ? W - 1 : 1) : 0.0;
        int i = static_cast<int>(fx);
        double f = fx - i;
        int j = std::min(i + 1, n - 1);
        double height = w.h[i] * (1 - f) + w.h[j] * f;
        double vel = w.u[i] * (1 - f) + w.u[j] * f;
        double lead = w.hue_lead[i] * (1 - f) + w.hue_lead[j] * f;

        /* crest brightness: positive height glows; gate by amplification */
        double crest = std::max(0.0, height);
        double bright = std::clamp(crest * (0.5 + 0.9 * w.amp), 0.0, 1.0);
        if (bright <= 0.01) continue;

        /* Predictive colour: base hue + velocity-led offset; saturation and
         * spread grow with amplification (latent colour surfaces on strong
         * crests), receding as the field calms. */
        double hue = w.base_hue + lead + vel * 20.0;
        double sat = std::clamp(0.25 + 0.55 * w.amp + std::fabs(vel) * 0.3, 0.0, 1.0);
        double val = std::clamp(0.45 + 0.55 * bright, 0.0, 1.0);
        SLUIColor top = slui_color_hsv(hue, sat, val, 1.0);

        /* The crest fills from the bottom up by its height; a thin bright cap
         * sits at the waterline so the surface reads as a moving sheet. */
        int fill_h = static_cast<int>(std::clamp(bright, 0.0, 1.0) * H + 0.5);
        if (fill_h < 1) fill_h = 1;
        int y0 = H - fill_h;
        /* body: dimmer tint beneath the waterline */
        SLUIColor body = slui_color_hsv(hue, sat * 0.8, val * 0.5, 1.0);
        for (int y = y0; y < H; ++y) {
            double ty = (y - y0) / static_cast<double>(fill_h);
            SLUIColor cc = slui_color_lerp(top, body, ty);
            slui_draw_blend_pixel(dc, x, y, cc, 0.5 + 0.5 * bright);
        }
        /* bright waterline cap */
        slui_draw_blend_pixel(dc, x, y0, top, bright);
        if (y0 - 1 >= 0)
            slui_draw_blend_pixel(dc, x, y0 - 1, top, bright * 0.4);
    }
    slui_draw_set_blend(dc, SLUI_BLEND_OVER);
}

} // namespace

Throbber::Throbber(int width_px) : CanvasView(width_px, 6) {
    kind_ = WidgetKind::Throbber;
    req_w_ = std::max(8, width_px);
    req_h_ = 6; /* a slim seam by default; grows with size_request */
    auto* field = new WaterField();
    field->base_hue = hue_;
    field->intensity = intensity_;
    set_draw_fn(&throbber_draw, field); /* draw_user_ owns the field */
}

Throbber::~Throbber() {
    delete static_cast<WaterField*>(draw_user_);
    draw_user_ = nullptr;
}

void Throbber::set_width_px(int wpx) {
    req_w_ = std::max(8, wpx);
    invalidate();
}

void Throbber::set_intensity(double v) {
    intensity_ = std::clamp(v, 0.0, 1.0);
    if (draw_user_) static_cast<WaterField*>(draw_user_)->intensity = intensity_;
    invalidate();
}

void Throbber::set_hue(double degrees) {
    hue_ = degrees;
    if (draw_user_) static_cast<WaterField*>(draw_user_)->base_hue = hue_;
    invalidate();
}

} // namespace slui