Home /Modules/ui/sleela_ui_mood.h

sleela_ui_mood.h

ui/include/sleela_ui_mood.h · 213 line(s) · c

#ifndef SLEELA_UI_MOOD_H
#define SLEELA_UI_MOOD_H
/* =============================================================================
 * SleelaUI(TM) Mood, Wash, Calculus-8 & millimetre light placement.
 *
 * This layer gives the Lighting system (sleela_ui_light.h) three things the
 * design calls for:
 *
 *   1. MILLIMETRE PRECISION. A light/dark/shadow emitter can be placed in real
 *      millimetres relative to the text's font-paint location: a HEIGHT the
 *      light shines down from, plus left/right and up/down offsets. The mm are
 *      resolved to the toolkit's device pixels through a DPI, so the same light
 *      sits at the same physical place on any display. Height, left, right, up
 *      and down are all supported.
 *
 *   2. CALCULUS-8 with 100 DIFFERENTIABLES. A light carries 100 control points
 *      ("differentiables"). A careful 8-stage calculus evaluates them -- eight
 *      smooth, analytically-differentiable basis stages -- and maps the inputs
 *      directly into a MOOD. Because every stage is differentiable, nudging an
 *      input moves the mood smoothly (no jumps), and the API returns both the
 *      value and its derivative so an adjuster can follow the slope.
 *
 *   3. MOODS from EXCELLENT WASHES. A mood is a named, adjustable state whose
 *      colour comes from an Excellent Wash: a soft, multi-stop graded colour
 *      field. Light colours are known and adjustable; the wash is how a mood
 *      paints the light. A mood also carries a NATURAL TANOR -- a soft,
 *      portrait-quality ambient glow for "lightless bulbs" (light-of-effect with
 *      no hard source) -- which has its own REFRESH on the light pattern and a
 *      gentle "a little left" bias in its freshing pattern.
 *
 * Everything composes with the existing SLUILight / SLUILightScene: you build a
 * light, place it in mm, give it a mood (wash + tanor + a calculus), and add it
 * to a scene as a source or an emitter exactly as before.
 *
 * Max Rupplin -- MEARVK LLC -- 2026
 * ===========================================================================*/
#include "sleela_ui.h"
#include "sleela_ui_light.h"

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

#ifdef __cplusplus
extern "C" {
#endif

/* --------------------------------------------------------------------------
 * Millimetre placement.
 * ------------------------------------------------------------------------- */
/* A light position in millimetres relative to a reference point (the text's
 * font-paint origin). +right / +down / +height-above-the-plane. left and up are
 * negative right/down. `height_mm` is how far above the surface the light sits
 * (it "shines down" from there). */
typedef struct {
    double right_mm;  /* +right, -left                                        */
    double down_mm;   /* +down, -up                                           */
    double height_mm; /* above the plane the light shines down from           */
} SLUIMm;

/* Convenience builders. */
SLUIMm slui_mm(double right_mm, double down_mm, double height_mm);
SLUIMm slui_mm_left(double mm, double height_mm);  /* shift left by mm        */
SLUIMm slui_mm_right(double mm, double height_mm);
SLUIMm slui_mm_up(double mm, double height_mm);
SLUIMm slui_mm_down(double mm, double height_mm);

/* Convert millimetres to device pixels at `dpi` (dots per inch; 96 is the UI
 * default). 1 inch = 25.4 mm. */
double slui_mm_to_px(double mm, double dpi);

/* Place `light` at `mm` relative to the font-paint origin (ref_x, ref_y) in
 * device pixels, at `dpi`. Sets the light's x/y (the ground point directly
 * under it) and z (the height it shines down from), so a point light at
 * height_mm genuinely grazes the text from that elevation, offset left/right
 * and up/down by the mm. Returns the modified light (also writes through the
 * pointer if non-NULL). */
SLUILight slui_light_place_mm(SLUILight *light, double ref_x, double ref_y,
                              SLUIMm mm, double dpi);

/* --------------------------------------------------------------------------
 * Excellent Wash: a soft, multi-stop graded colour field that paints a mood.
 * Up to 8 stops (position 0..1 -> colour); the wash is sampled smoothly
 * (smoothstep between stops) so it reads as a gentle wash, not hard bands.
 * ------------------------------------------------------------------------- */
#define SLUI_WASH_MAX_STOPS 8

typedef struct {
    int count;
    double pos[SLUI_WASH_MAX_STOPS];     /* ascending in [0,1]                */
    SLUIColor color[SLUI_WASH_MAX_STOPS];
    double softness;                     /* 0..1 extra blur between stops     */
} SLUIWash;

SLUIWash slui_wash_begin(void);
/* Add a stop; returns the wash by value so calls can chain through a variable.
 * Stops may be added out of order; sampling sorts by position. */
SLUIWash slui_wash_stop(SLUIWash wash, double position, SLUIColor color);
/* Two- and three-stop shortcuts for the common washes. */
SLUIWash slui_wash_linear(SLUIColor a, SLUIColor b);
SLUIWash slui_wash_triad(SLUIColor a, SLUIColor b, SLUIColor c);
/* Sample the wash at t in [0,1] -> colour (smoothstep-interpolated). */
SLUIColor slui_wash_sample(const SLUIWash *wash, double t);

/* --------------------------------------------------------------------------
 * Natural Tanor: a soft portrait-quality ambient glow for "lightless bulbs"
 * -- a light-of-effect with no hard source. It has its own refresh on the light
 * pattern and a gentle leftward ("a little left") bias in the freshing pattern.
 * ------------------------------------------------------------------------- */
typedef struct {
    double warmth;        /* 0 cool .. 1 warm -- the glow's temperament       */
    double diffusion;     /* 0..1 how soft/portrait the falloff is            */
    double refresh_hz;    /* how often the pattern freshens (Hz); 0 = static  */
    double left_bias;     /* 0..1 "a little left" drift of the pattern        */
    double depth;         /* 0..1 how deep the lightless glow reaches         */
    SLUIColor tone;       /* the tanor's base tone                            */
} SLUITanor;

/* A sensible portrait tanor (warm, soft, gently refreshing, a little left). */
SLUITanor slui_tanor_default(void);

/* --------------------------------------------------------------------------
 * Calculus-8: 100 differentiables evaluated through 8 careful stages into a
 * mood scalar. The 100 inputs are an owned vector; each is a "differentiable"
 * the host can nudge. The 8 stages are smooth basis functions (polynomial,
 * trigonometric, logistic, gaussian, ...) summed with learned-feel weights, so
 * the mapping inputs -> mood is continuous and differentiable everywhere.
 * ------------------------------------------------------------------------- */
#define SLUI_CALC8_INPUTS 100
#define SLUI_CALC8_STAGES 8

typedef struct SLUICalculus8 SLUICalculus8;

SLUICalculus8 *slui_calc8_create(void);
void slui_calc8_destroy(SLUICalculus8 *c);

/* Set/get one of the 100 differentiable inputs (index 0..99), each in [0,1].
 * Out-of-range indices are ignored / return 0. */
void slui_calc8_set(SLUICalculus8 *c, int index, double value);
double slui_calc8_get(const SLUICalculus8 *c, int index);
/* Set all 100 inputs from an array (any count up to 100). */
void slui_calc8_set_all(SLUICalculus8 *c, const double *values, int count);

/* Evaluate the calculus: returns the mood scalar in [0,1]. If `derivative` is
 * non-NULL it receives d(mood)/d(input) for input `wrt_index` (the slope along
 * that differentiable), so an adjuster can follow the gradient into a mood. */
double slui_calc8_eval(const SLUICalculus8 *c, int wrt_index,
                       double *derivative);

/* The per-stage contributions (SLUI_CALC8_STAGES values) for inspection, so a
 * tool can see how the eight stages shaped the mood. Writes up to `cap`. */
int slui_calc8_stages(const SLUICalculus8 *c, double *out, int cap);

/* --------------------------------------------------------------------------
 * Mood: a named, adjustable state = a wash + a tanor + a calculus. Applying a
 * mood to a light sets its colour (sampled from the wash at the calculus's mood
 * scalar) and folds the tanor's warmth/depth into the light, so "inputs ->
 * direct moods" is one call.
 * ------------------------------------------------------------------------- */
typedef enum {
    SLUI_MOOD_CALM = 0,
    SLUI_MOOD_WARM = 1,
    SLUI_MOOD_COOL = 2,
    SLUI_MOOD_VIVID = 3,
    SLUI_MOOD_SOMBER = 4,
    SLUI_MOOD_TENDER = 5,
    SLUI_MOOD_RADIANT = 6,
    SLUI_MOOD_CUSTOM = 7
} SLUIMoodKind;

typedef struct SLUIMood SLUIMood;

/* Create a mood. A built-in kind pre-fills a tasteful wash + tanor; CUSTOM
 * starts empty for the host to set. */
SLUIMood *slui_mood_create(SLUIMoodKind kind);
void slui_mood_destroy(SLUIMood *mood);

void slui_mood_set_wash(SLUIMood *mood, SLUIWash wash);
void slui_mood_set_tanor(SLUIMood *mood, SLUITanor tanor);
/* The mood borrows the calculus (host keeps ownership); its eval drives where
 * the wash is sampled. Pass NULL to use a fixed midpoint. */
void slui_mood_set_calculus(SLUIMood *mood, const SLUICalculus8 *calc);

SLUIWash slui_mood_wash(const SLUIMood *mood);
SLUITanor slui_mood_tanor(const SLUIMood *mood);

/* The mood's current colour: the wash sampled at the calculus's mood scalar
 * (advanced by `time_s` through the tanor's refresh + left bias so a lightless
 * bulb's glow freshens over time). */
SLUIColor slui_mood_color(const SLUIMood *mood, double time_s);

/* Apply the mood to a light: set the light's colour from the mood (at time_s)
 * and fold the tanor's depth into the light's intensity/softness so the light
 * carries the mood's portrait quality. */
void slui_light_apply_mood(SLUILight *light, const SLUIMood *mood,
                           double time_s);

/* --------------------------------------------------------------------------
 * Convenience: build a mm-placed, mood-coloured light for text in one call.
 * The light shines down on text painted at (font_x, font_baseline) from
 * `mm` away, coloured by `mood` at `time_s`. role/polarity choose light vs
 * shadow and source vs emitter.
 * ------------------------------------------------------------------------- */
SLUILight slui_light_for_text(double font_x, double font_baseline, SLUIMm mm,
                              double dpi, const SLUIMood *mood, double time_s,
                              SLUILightRole role, SLUIPolarity polarity,
                              double reach_px, double intensity);

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

#endif /* SLEELA_UI_MOOD_H */