Home /Modules/user-interface/sleela_ui_font.h

sleela_ui_font.h

user-interface/include/sleela_ui_font.h · 189 line(s) · c

#ifndef SLEELA_UI_FONT_H
#define SLEELA_UI_FONT_H
/* =============================================================================
 * SleelaUI(TM) Font API -- fonts and font effects for Sleela and her UI.
 *
 * A FONT bundles a family, size, weight, slant, and spacing with a stack of
 * EFFECTS -- shadows, light, glow, an emitter, outline, relief (emboss/engrave),
 * and a gradient fill -- so a developer or agent can render rich, lit text with
 * one handle. The effects compose with the rest of the toolkit: the Draw API
 * (sleela_ui_draw.h) owns the pixels, and the RELIEF / LIGHT / EMITTER effects
 * speak the same language as the Lighting layer (sleela_ui_light.h) -- light and
 * shadow are emissions, and an EMITTER radiates from the text WITHOUT reserving
 * the glyphs as "used" (so the same text can light its neighbours yet remain
 * free to carry more effects), exactly as elsewhere in SleelaUI.
 *
 * The look is produced by the toolkit's own rasterizer over an 8-bit glyph
 * coverage mask, so a styled string is pixel-identical on Windows, macOS, and
 * Linux/Unix. Every effect has a QUALITY knob (draft .. ultra) that trades
 * sample count for smoothness, so you can "choose many quality effects".
 *
 * Colours are the usual 0xRRGGBBAA words; geometry uses SLUIRect/SLUIPoint.
 *
 * Max Rupplin -- MEARVK LLC -- 2026
 * ===========================================================================*/
#include "sleela_ui.h"
#include "sleela_ui_draw.h"

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

#ifdef __cplusplus
extern "C" {
#endif

/* --------------------------------------------------------------------------
 * Weight, slant, and global rendering quality.
 * ------------------------------------------------------------------------- */
typedef enum {
    SLUI_FONT_THIN = 100,
    SLUI_FONT_LIGHT = 300,
    SLUI_FONT_REGULAR = 400,
    SLUI_FONT_MEDIUM = 500,
    SLUI_FONT_SEMIBOLD = 600,
    SLUI_FONT_BOLD = 700,
    SLUI_FONT_BLACK = 900
} SLUIFontWeight;

typedef enum {
    SLUI_SLANT_UPRIGHT = 0,
    SLUI_SLANT_ITALIC = 1,  /* a true italic face if present                 */
    SLUI_SLANT_OBLIQUE = 2  /* a synthetic shear when no italic face exists  */
} SLUIFontSlant;

/* Quality trades samples for smoothness. It governs shadow/glow blur taps,
 * outline/relief angular samples, and whether coverage is super-sampled.
 * "Choose many quality effects" -> pick ULTRA for the richest result. */
typedef enum {
    SLUI_QUALITY_DRAFT = 0,  /* cheapest: hard shadows, few taps             */
    SLUI_QUALITY_LOW = 1,
    SLUI_QUALITY_MEDIUM = 2, /* a sensible default                           */
    SLUI_QUALITY_HIGH = 3,
    SLUI_QUALITY_ULTRA = 4   /* the most samples / smoothest edges           */
} SLUIFontQuality;

/* --------------------------------------------------------------------------
 * Effects. A font carries an ordered stack; they are drawn back-to-front
 * (shadows under the glyph, glyph fill, then light/glow/outline on top), so the
 * stack order you add them in is the visual layering.
 * ------------------------------------------------------------------------- */
typedef enum {
    SLUI_FX_DROP_SHADOW = 0,  /* an offset, blurred, dark copy behind         */
    SLUI_FX_INNER_SHADOW = 1, /* shadow inside the glyph (a pressed-in look)  */
    SLUI_FX_GLOW = 2,         /* a soft coloured halo around the glyph        */
    SLUI_FX_LIGHT = 3,        /* a directional sheen lighting the glyph face  */
    SLUI_FX_EMITTER = 4,      /* the text radiates light into the scene       */
    SLUI_FX_OUTLINE = 5,      /* a stroked edge of a chosen width + colour    */
    SLUI_FX_RELIEF = 6,       /* emboss/engrave the glyph (lighting normals)  */
    SLUI_FX_GRADIENT_FILL = 7 /* fill the glyph with a vertical gradient      */
} SLUIFontEffectType;

/* Relief direction for SLUI_FX_RELIEF (mirrors the Lighting relief idea). */
typedef enum {
    SLUI_FONT_EMBOSSED = 0, /* the text stands OFF the surface               */
    SLUI_FONT_ENGRAVED = 1  /* the text is pressed INTO the surface          */
} SLUIFontRelief;

/* One effect. Only the fields relevant to `type` are read; use the builder
 * helpers below so you never have to fill the whole struct. */
typedef struct {
    SLUIFontEffectType type;
    SLUIColor color;    /* shadow/glow/light/outline/emitter colour           */
    SLUIColor color2;   /* second colour (gradient bottom)                    */
    double dx, dy;      /* shadow offset (px) / light+emitter direction       */
    double blur;        /* shadow/glow softness radius (px)                   */
    double size;        /* outline width / relief depth / emitter radius (px) */
    double intensity;   /* 0..N strength (glow/light/emitter/relief)          */
    double opacity;     /* 0..1 effect opacity                                */
    int relief;         /* SLUIFontRelief for SLUI_FX_RELIEF                  */
    int reserved_anchor;/* EMITTER: -1 => reserve nothing (an emitter);       */
                        /*          >=0 => bind as a SOURCE on that anchor     */
} SLUIFontEffect;

/* Effect builders (fill a sensible default, then tweak the returned struct). */
SLUIFontEffect slui_fx_drop_shadow(double dx, double dy, double blur,
                                   SLUIColor color);
SLUIFontEffect slui_fx_inner_shadow(double dx, double dy, double blur,
                                    SLUIColor color);
SLUIFontEffect slui_fx_glow(double radius, double intensity, SLUIColor color);
SLUIFontEffect slui_fx_light(double dx, double dy, double intensity,
                             SLUIColor color);
/* An emitter: the text radiates light into a scene. anchor<0 keeps it a pure
 * emitter (reserves nothing); anchor>=0 binds it as a light SOURCE on that
 * anchor when applied to a light scene. */
SLUIFontEffect slui_fx_emitter(double radius, double intensity, SLUIColor color,
                               int anchor);
SLUIFontEffect slui_fx_outline(double width, SLUIColor color);
SLUIFontEffect slui_fx_relief(SLUIFontRelief relief, double depth,
                              double intensity);
SLUIFontEffect slui_fx_gradient_fill(SLUIColor top, SLUIColor bottom);

/* --------------------------------------------------------------------------
 * Font handle.
 * ------------------------------------------------------------------------- */
typedef struct SLUIFont SLUIFont;

/* Create a font. `family` may be a real face name or "system"/"mono". */
SLUIFont *slui_font_create(const char *family, double size_pt);
void slui_font_destroy(SLUIFont *font);
SLUIFont *slui_font_clone(const SLUIFont *font); /* copy incl. effect stack   */

/* Face attributes. */
void slui_font_set_family(SLUIFont *font, const char *family);
void slui_font_set_size(SLUIFont *font, double size_pt);
void slui_font_set_weight(SLUIFont *font, SLUIFontWeight weight);
void slui_font_set_slant(SLUIFont *font, SLUIFontSlant slant);
void slui_font_set_letter_spacing(SLUIFont *font, double px);
void slui_font_set_line_height(SLUIFont *font, double multiple); /* x em      */
void slui_font_set_quality(SLUIFont *font, SLUIFontQuality quality);

double slui_font_size(const SLUIFont *font);
SLUIFontQuality slui_font_quality(const SLUIFont *font);

/* Effect stack. Effects render back-to-front in the order added. */
void slui_font_add_effect(SLUIFont *font, SLUIFontEffect effect);
void slui_font_clear_effects(SLUIFont *font);
int slui_font_effect_count(const SLUIFont *font);

/* --------------------------------------------------------------------------
 * Measuring and drawing.
 * ------------------------------------------------------------------------- */
/* Advance width of `utf8` in this font (letter spacing included), in pixels. */
double slui_font_measure(SLUIFont *font, const char *utf8);
/* Ascent / descent / line height (px) for the current face + size. */
double slui_font_ascent(SLUIFont *font);
double slui_font_descent(SLUIFont *font);
double slui_font_line_height(SLUIFont *font);

/* Draw `utf8` into `dc` with the full effect stack, pen origin at (x, baseline)
 * and the base fill colour `color` (a GRADIENT_FILL effect overrides it). */
void slui_font_draw(SLUIDrawContext *dc, SLUIFont *font, const char *utf8, int x,
                    int baseline, SLUIColor color);

/* Draw into a rect with horizontal alignment (0 start, 1 center, 2 end) and
 * vertical centering -- the usual label path. */
void slui_font_draw_in(SLUIDrawContext *dc, SLUIFont *font, const char *utf8,
                       SLUIRect area, int halign, SLUIColor color);

/* If the font carries an EMITTER effect, register that emission into `scene`
 * for the text drawn at (x, baseline). A pure emitter (anchor<0) adds an
 * emitter that reserves nothing; an anchored one adds a light source reserving
 * its anchor. Returns the light index, SLUI_ERR_* , or 1 if the font has no
 * emitter effect. The scene type is the opaque SLUILightScene from
 * sleela_ui_light.h (passed as void* to keep this header independent). */
int slui_font_emit_into_scene(SLUIFont *font, void *light_scene, int x,
                              int baseline, const char *utf8);

/* --------------------------------------------------------------------------
 * Widget integration. Give any text widget a styled font so its label renders
 * with the font's effects. The widget borrows the font (host keeps ownership);
 * pass NULL to revert to the theme's plain text.
 * ------------------------------------------------------------------------- */
void slui_widget_set_font(SLUIWidget *widget, SLUIFont *font);

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

#endif /* SLEELA_UI_FONT_H */