Home /Modules/ballum/ballum_manager.h

ballum_manager.h

ballum/include/sleela_ballum/ballum_manager.h · 363 line(s) · c

#ifndef SLEELA_BALLUM_MANAGER_H
#define SLEELA_BALLUM_MANAGER_H

/*
 * Ballum(TM) -- pixel-level control over the screen/monitor of the native OS.
 *
 * Ballum gives a SLeeLa program direct, bounded control of the display: set an
 * individual pixel's color, read/blit a region, and adjust whole-display
 * brightness, warmth (color temperature), and gamma. It targets macOS, Linux,
 * and Windows 10+ through one portable manager over a per-OS backend vtable,
 * exactly like wifi-common/ abstracts the radio.
 *
 * Design rules (carried from the repo's established native subsystems):
 *   - Open standards only on each OS (X11/XRANDR + DDC/CI on Linux, Core
 *     Graphics / IOKit on macOS, DXGI + the Win32 gamma ramp on Windows 10+).
 *   - Exactly one backend is compiled in per build; a graceful "unavailable"
 *     backend is always available so calls fail closed, never crash.
 *   - The manager copies results into caller/VM-owned memory and never hands
 *     out internal pointers.
 *   - Every setter is bounded and validated before it touches the device.
 *
 * This header is the single C ABI the SLeeLa bridge and the standalone tests
 * build against.
 */

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

#ifdef __cplusplus
extern "C" {
#endif

/* ---- limits -------------------------------------------------------------- */

#define BALLUM_MAX_DISPLAYS        16u
#define BALLUM_DISPLAY_NAME_BYTES  64u
#define BALLUM_BACKEND_NAME_BYTES  32u

/* Percent controls (brightness) are 0..100. */
#define BALLUM_BRIGHTNESS_MIN      0
#define BALLUM_BRIGHTNESS_MAX      100

/* Color temperature / warmth, in kelvin. 6500K is the neutral D65 white point;
 * lower is warmer (toward amber), higher is cooler (toward blue). */
#define BALLUM_WARMTH_MIN_KELVIN   1000u
#define BALLUM_WARMTH_NEUTRAL_K    6500u
#define BALLUM_WARMTH_MAX_KELVIN   10000u

/* Gamma is a fixed-point value scaled by 100 (so 2.20 gamma == 220). */
#define BALLUM_GAMMA_SCALE         100u
#define BALLUM_GAMMA_MIN           10u    /* 0.10 */
#define BALLUM_GAMMA_MAX           1000u  /* 10.00 */

/* ---- status -------------------------------------------------------------- */

typedef enum {
    BALLUM_STATUS_OK = 0,
    BALLUM_STATUS_INVALID_ARGUMENT,
    BALLUM_STATUS_BACKEND_UNAVAILABLE,
    BALLUM_STATUS_BACKEND_ERROR,
    BALLUM_STATUS_DISPLAY_NOT_FOUND,
    BALLUM_STATUS_OUT_OF_BOUNDS,         /* pixel/region outside the display   */
    BALLUM_STATUS_BUFFER_TOO_SMALL,
    BALLUM_STATUS_UNSUPPORTED,           /* backend lacks this capability       */
    BALLUM_STATUS_PERMISSION_DENIED,     /* OS refused the display operation    */
    BALLUM_STATUS_NOT_INITIALIZED
} ballum_status_t;

/* Capability flags a backend advertises per display. A SLeeLa program checks
 * these before enabling a control, so a missing capability fails cleanly
 * instead of silently doing nothing. */
typedef enum {
    BALLUM_CAP_NONE              = 0,
    BALLUM_CAP_PER_PIXEL         = 1 << 0, /* set/get individual pixels         */
    BALLUM_CAP_REGION_BLIT       = 1 << 1, /* blit a rectangle of pixels        */
    BALLUM_CAP_BRIGHTNESS        = 1 << 2, /* whole-display brightness          */
    BALLUM_CAP_COLOR_TEMPERATURE = 1 << 3, /* warmth / color temperature        */
    BALLUM_CAP_GAMMA             = 1 << 4, /* gamma ramp                        */
    BALLUM_CAP_POINTER_INPUT     = 1 << 5, /* mouse/touch pointer events        */
    BALLUM_CAP_TOUCH_INPUT       = 1 << 6, /* multi-touch is reported           */
    BALLUM_CAP_FULLSCREEN_SURFACE = 1 << 7 /* claim a fullscreen framebuffer    */
} ballum_capability_t;

/* ---- pointer input ------------------------------------------------------- */

/* Raw pointer event kinds the backend reports. Mouse and touch are unified: a
 * touch contact maps to DOWN/MOVE/UP with source BALLUM_POINTER_TOUCH. Higher
 * gestures (click, drag) are synthesized above this layer, not reported here. */
typedef enum {
    BALLUM_EVENT_NONE = 0,
    BALLUM_EVENT_POINTER_DOWN,   /* button pressed / finger touched down */
    BALLUM_EVENT_POINTER_MOVE,   /* pointer/finger moved                 */
    BALLUM_EVENT_POINTER_UP      /* button released / finger lifted      */
} ballum_event_type_t;

/* Backend-neutral key codes a session acts on. The set is intentionally small:
 * a Ballum session's one hard control is ESC (exit). Per-OS backends map their
 * native keysyms (X11 keysym, Win32 VK, macOS key code) onto these. Printable
 * ASCII may be reported as its own code (e.g. 'a'); 0 means no key. */
typedef enum {
    BALLUM_KEY_NONE  = 0,
    BALLUM_KEY_ESC   = 27,  /* ASCII ESC -- exit a full-screen session        */
    BALLUM_KEY_ENTER = 13,
    BALLUM_KEY_SPACE = 32
} ballum_key_t;

/* Which physical button, matching the SLUI pointer-button vocabulary. For a
 * touch contact the button is reported as LEFT. */
typedef enum {
    BALLUM_BUTTON_NONE = 0,
    BALLUM_BUTTON_LEFT = 1,
    BALLUM_BUTTON_MIDDLE = 2,
    BALLUM_BUTTON_RIGHT = 3
} ballum_pointer_button_t;

/* Where the event came from. */
typedef enum {
    BALLUM_POINTER_MOUSE = 0,
    BALLUM_POINTER_TOUCH = 1
} ballum_pointer_source_t;

/* Modifier bitmask, matching SLUI_MOD_*. */
enum {
    BALLUM_MOD_SHIFT = 1u << 0,
    BALLUM_MOD_CTRL  = 1u << 1,
    BALLUM_MOD_ALT   = 1u << 2,
    BALLUM_MOD_SUPER = 1u << 3
};

/* One raw pointer event in display pixel coordinates (top-left origin). */
typedef struct {
    ballum_event_type_t     type;
    uint32_t                display_id;   /* display the event occurred on   */
    int32_t                 x;            /* pixel x (may be <0 if off-edge)  */
    int32_t                 y;            /* pixel y                          */
    ballum_pointer_button_t button;       /* for DOWN/UP; LEFT for touch      */
    ballum_pointer_source_t source;       /* mouse or touch                   */
    uint32_t                contact_id;   /* touch contact id (0 for mouse)   */
    uint32_t                modifiers;    /* BALLUM_MOD_* bitmask             */
} ballum_pointer_event_t;

/* ---- value types --------------------------------------------------------- */

/* A single pixel: 8-bit RGBA, straight (non-premultiplied) alpha. */
typedef struct {
    uint8_t r;
    uint8_t g;
    uint8_t b;
    uint8_t a;
} ballum_color_t;

/* A pixel coordinate on a display (top-left origin). */
typedef struct {
    uint32_t x;
    uint32_t y;
} ballum_point_t;

/* A rectangle of pixels. */
typedef struct {
    uint32_t x;
    uint32_t y;
    uint32_t width;
    uint32_t height;
} ballum_rect_t;

/* Static description of one connected display. */
typedef struct {
    uint32_t id;                                /* backend-stable display id    */
    char     name[BALLUM_DISPLAY_NAME_BYTES];   /* human-readable, NUL-terminated */
    uint32_t width;                             /* pixels                        */
    uint32_t height;                            /* pixels                        */
    uint32_t refresh_mhz;                       /* refresh rate in milli-Hz      */
    int      is_primary;                        /* 1 if the primary display      */
    uint32_t capabilities;                      /* OR of ballum_capability_t     */
} ballum_display_t;

/* ---- backend vtable ------------------------------------------------------ */

/*
 * One backend is compiled in per build (per-OS). The portable manager calls
 * through this vtable; any entry may be NULL, in which case the manager returns
 * BALLUM_STATUS_UNSUPPORTED for that operation rather than dereferencing NULL.
 */
typedef struct ballum_backend {
    const char *name;

    /* Enumerate displays into `out` (capacity entries); sets *out_count. */
    ballum_status_t (*enumerate)(void *context, ballum_display_t *out,
                                 size_t capacity, size_t *out_count);

    /* Per-pixel. */
    ballum_status_t (*set_pixel)(void *context, uint32_t display_id,
                                 ballum_point_t at, ballum_color_t color);
    ballum_status_t (*get_pixel)(void *context, uint32_t display_id,
                                 ballum_point_t at, ballum_color_t *out);

    /* Blit a tightly-packed RGBA buffer of rect.width*rect.height pixels. */
    ballum_status_t (*blit_region)(void *context, uint32_t display_id,
                                   ballum_rect_t rect, const ballum_color_t *pixels,
                                   size_t pixel_count);

    /* Whole-display controls. brightness is 0..100; warmth is kelvin;
     * gamma is scaled by BALLUM_GAMMA_SCALE. */
    ballum_status_t (*set_brightness)(void *context, uint32_t display_id, int percent);
    ballum_status_t (*set_warmth)(void *context, uint32_t display_id, uint32_t kelvin);
    ballum_status_t (*set_gamma)(void *context, uint32_t display_id, uint32_t gamma_scaled);

    /* Poll one pending pointer (mouse/touch) event without blocking. Writes the
     * event through `out` and returns BALLUM_STATUS_OK when one was dequeued, or
     * BALLUM_STATUS_UNSUPPORTED when the backend has no input queue. When no
     * event is pending it returns BALLUM_STATUS_OK with out->type ==
     * BALLUM_EVENT_NONE. May be NULL (input not provided). */
    ballum_status_t (*poll_event)(void *context, ballum_pointer_event_t *out);

    /* Poll one pending key event without blocking. Writes the key through `out`
     * and returns BALLUM_STATUS_OK when one was dequeued; *out == BALLUM_KEY_NONE
     * means no key was pending. Returns BALLUM_STATUS_UNSUPPORTED when the
     * backend has no keyboard queue. May be NULL (keyboard not provided), in
     * which case the manager reports no keys -- fail closed, never a false key.
     * Key codes are the backend-neutral ballum_key_t set (ESC is the one a
     * session needs to exit); per-OS backends map their native keysyms onto it. */
    ballum_status_t (*poll_key)(void *context, int *out);

    /* ---- Fullscreen surface (the World-Class per-pixel path) -------------
     * These three turn Ballum from "draw on the live desktop (transient,
     * compositor may overpaint)" into TOTAL per-pixel control: the backend
     * creates an override-redirect, always-on-top fullscreen surface backed by
     * an in-memory RGBA framebuffer, so the program owns every pixel and the
     * window manager cannot paint over it.
     *
     * claim_surface : create and map the fullscreen surface for `display_id`.
     *                 While a surface is claimed, set_pixel/get_pixel/blit
     *                 operate on its framebuffer (O(1) / memcpy -- no X calls),
     *                 and `present` pushes the whole framebuffer to the screen
     *                 in ONE XPutImage (MIT-SHM when available), not per-pixel.
     * present       : push the framebuffer to the surface in one shot.
     * release_surface: unmap and destroy the surface; drawing reverts to the
     *                 live-desktop fallback (if the backend offers one).
     *
     * Any of these may be NULL: the manager then reports
     * BALLUM_STATUS_UNSUPPORTED and BALLUM_CAP_FULLSCREEN_SURFACE is absent. */
    ballum_status_t (*claim_surface)(void *context, uint32_t display_id);
    ballum_status_t (*present)(void *context, uint32_t display_id);
    ballum_status_t (*release_surface)(void *context, uint32_t display_id);
} ballum_backend_t;

/* The backend compiled in for this build (never NULL; may be the unavailable
 * backend when no OS backend is selected). */
const ballum_backend_t *ballum_backend_default(void);

/* 1 if the compiled-in backend is a real OS backend, 0 if it is the
 * unavailable fallback. */
int ballum_backend_supported(void);

/* ---- manager ------------------------------------------------------------- */

typedef struct ballum_manager {
    const ballum_backend_t *backend;
    void                   *backend_context;
    ballum_display_t        displays[BALLUM_MAX_DISPLAYS];
    size_t                  display_count;
    uint64_t                enumerate_generation;
    int                     initialized;
} ballum_manager_t;

/* Initialize a manager over a backend (NULL selects ballum_backend_default()). */
ballum_status_t ballum_manager_init(ballum_manager_t *manager,
                                    const ballum_backend_t *backend,
                                    void *backend_context);

/* Refresh the manager's display list; fills `out` (capacity entries) and
 * *out_count with the enumerated displays, copied into caller memory. */
ballum_status_t ballum_manager_enumerate(ballum_manager_t *manager,
                                         ballum_display_t *out, size_t capacity,
                                         size_t *out_count);

/* Copy the cached description of display `id` into `out`. */
ballum_status_t ballum_manager_describe(const ballum_manager_t *manager,
                                        uint32_t id, ballum_display_t *out);

/* Does display `id` advertise capability `cap`? 1 yes, 0 no, <0 on bad args. */
int ballum_manager_has_capability(const ballum_manager_t *manager,
                                   uint32_t id, ballum_capability_t cap);

/* Pixel control (validated against the cached display bounds + capability). */
ballum_status_t ballum_manager_set_pixel(ballum_manager_t *manager, uint32_t id,
                                         ballum_point_t at, ballum_color_t color);
ballum_status_t ballum_manager_get_pixel(ballum_manager_t *manager, uint32_t id,
                                         ballum_point_t at, ballum_color_t *out);
ballum_status_t ballum_manager_blit_region(ballum_manager_t *manager, uint32_t id,
                                           ballum_rect_t rect,
                                           const ballum_color_t *pixels,
                                           size_t pixel_count);

/* ---- fullscreen surface (total per-pixel control) ------------------------ */

/* Claim an override-redirect, always-on-top fullscreen surface over display
 * `id`, backed by an in-memory RGBA framebuffer the program owns. While
 * claimed, set_pixel/get_pixel/blit operate on the framebuffer (fast, no
 * per-pixel device calls) and ballum_manager_present() pushes it to the screen
 * in one shot. Validated against the display's BALLUM_CAP_FULLSCREEN_SURFACE
 * capability. Returns BALLUM_STATUS_UNSUPPORTED when the backend cannot. */
ballum_status_t ballum_manager_claim_surface(ballum_manager_t *manager, uint32_t id);

/* Present the framebuffer of a claimed surface to the screen (one XPutImage on
 * X11, SHM when available). */
ballum_status_t ballum_manager_present(ballum_manager_t *manager, uint32_t id);

/* Release a claimed surface; drawing reverts to the backend's live-desktop
 * fallback, if any. */
ballum_status_t ballum_manager_release_surface(ballum_manager_t *manager, uint32_t id);

/* Does display `id` advertise a claimable fullscreen surface? 1/0/<0. */
int ballum_manager_has_surface(const ballum_manager_t *manager, uint32_t id);

/* Whole-display controls (validated against the documented ranges). */
ballum_status_t ballum_manager_set_brightness(ballum_manager_t *manager, uint32_t id,
                                              int percent);
ballum_status_t ballum_manager_set_warmth(ballum_manager_t *manager, uint32_t id,
                                          uint32_t kelvin);
ballum_status_t ballum_manager_set_gamma(ballum_manager_t *manager, uint32_t id,
                                         uint32_t gamma_scaled);

/* ---- pointer input ------------------------------------------------------- */

/* Poll one pending pointer (mouse/touch) event, non-blocking. On success *out
 * is filled; out->type == BALLUM_EVENT_NONE means no event was pending. Returns
 * BALLUM_STATUS_UNSUPPORTED when the backend provides no input queue. */
ballum_status_t ballum_manager_poll_event(ballum_manager_t *manager,
                                          ballum_pointer_event_t *out);

/* Does the backend provide pointer input at all? 1 yes, 0 no, <0 on bad args. */
int ballum_manager_has_input(const ballum_manager_t *manager);

/* ---- keyboard input ------------------------------------------------------ */

/* Poll one pending key, non-blocking. On success *out holds a ballum_key_t
 * (0 == BALLUM_KEY_NONE means nothing pending). Returns BALLUM_STATUS_UNSUPPORTED
 * when the backend has no keyboard queue. Fails closed: a backend without a
 * poll_key reports no keys rather than a false one. */
ballum_status_t ballum_manager_poll_key(ballum_manager_t *manager, int *out);

/* Does the backend provide keyboard input at all? 1 yes, 0 no, <0 on bad args. */
int ballum_manager_has_keyboard(const ballum_manager_t *manager);

/* ---- helpers ------------------------------------------------------------- */

const char *ballum_status_name(ballum_status_t status);
const char *ballum_event_type_name(ballum_event_type_t type);
ballum_color_t ballum_color_rgb(uint8_t r, uint8_t g, uint8_t b);
ballum_color_t ballum_color_rgba(uint8_t r, uint8_t g, uint8_t b, uint8_t a);

/* Clamp helpers used by both the manager and backends. */
int      ballum_clamp_brightness(int percent);
uint32_t ballum_clamp_warmth(uint32_t kelvin);
uint32_t ballum_clamp_gamma(uint32_t gamma_scaled);

#ifdef __cplusplus
}
#endif

#endif /* SLEELA_BALLUM_MANAGER_H */