Home/Modules/ballum

ballum

library module lib/ballum

Examples

lib/examples/ballum

6 file(s)

<img align="right" src="https://github.com/mearvk/SLeeLa/blob/master/images/debian/debian-logo.png" width="75" height="75" alt="SLeeLa">

SLeeLa Ballum™ — pixel-level display control

Status: SLeeLa-side facade + per-OS profiles over the native Ballum core. This directory is the language-facing layer for Ballum, the SLeeLa feature that gives a program pixel-level control of the native OS screen/monitor — set a pixel's color, blit a region, and adjust brightness, warmth (color temperature), and gamma — on macOS, Linux, and Windows 10+.

The actual device I/O lives in the native core at ballum/ (ballum/include/sleela_ballum/ballum_manager.h). These .sleela classes own request/state/validation semantics and honest status reporting. Like lib/wifi/, the facade is a bridge boundary: it never drives a display on its own; a host SLVM binding connects its methods to the native ballum_manager_* API. Until that binding is installed, operations return BRIDGE_REQUIRED — but every bounds, range, and capability check still runs locally, so a program fails cleanly and never asks the native layer to write an out-of-range pixel or an impossible control.

Classes

FileRole
SLPackage.sleelaPackage facade (configure/name/available).
SLBallumScreen.sleelaThe clean, pixel-accurate Screen API — the high-level surface a developer integrates with (see below).
SLBallumManager.sleelaThe low-level bridge-boundary driver: bind the native handle, enumerate, then live setPixel/setBrightness/setWarmth/setGamma through the uiBallum* VM bridge (plus request* pre-validation helpers).
SLBallumDisplay.sleelaOne connected display: id, geometry, primary flag, and the capability bitmask (supportsPerPixel/supportsBrightness/…), mirroring ballum_display_t.
SLBallumColor.sleelaAn 8-bit RGBA color with clamped channels, mirroring ballum_color_t.
SLBallumStatus.sleelaResult codes mirroring ballum_status_t, plus the SLeeLa BRIDGE_REQUIRED code and text(code).
SLBallumInput.sleelaThe touchscreen + mouse input listener — polls pointer events and synthesizes click/move/drag gestures (see below).
SLBallumPointerEvent.sleelaOne pointer event (type/x/y/button/source/contact/modifiers), mirroring ballum_pointer_event_t.

Input: touchscreen + mouse (SLBallumInput)

Ballum is not just output — SLBallumInput is a clean listener for mouse and touchscreen input over the whole screen. The native backend reports raw pointer events (mouse and touch unified as DOWN/MOVE/UP), and the listener folds them into the gestures a developer actually wants — click and drag — with a small, explicit state machine and a configurable drag threshold.

The core VM has no callbacks, so input is polled: call poll() each frame; it returns a gesture code and latches the event position/button/source for the accessors. Drain until it returns NONE.

Gesture (poll() return)Meaning
NONE (0)nothing this poll
DOWN (1)a raw press, not yet resolved to click/drag
MOVE (2)hover/move with no button held
CLICK (3)press + release at the same spot (a tap, on touch)
DRAG_BEGIN (4)movement past the threshold while pressed
DRAG_MOVE (5)continued drag movement
DRAG_END (6)release that ends a drag
SLBallumInput input = new SLBallumInput();
input.configure();
input.setDragThreshold(4);                 // pixels of slop before tap -> drag

if (input.available()) {                    // a pointer backend is present
    int g = input.poll();                   // call each frame; drain to NONE
    while (g != SLBallumInput.NONE) {
        if (g == SLBallumInput.CLICK) {
            screen.plotRgb(input.x(), input.y(), 0, 255, 0);   // paint where tapped
        } else if (g == SLBallumInput.DRAG_MOVE) {
            screen.plotRgb(input.x(), input.y(), 255, 255, 0); // trail while dragging
        }
        g = input.poll();
    }
}
MethodPurpose
configure() / setDragThreshold(px)prepare; tune the click-vs-drag threshold
available()is a pointer-input backend present on this host
poll()fold one raw event into a gesture; returns a gesture code
gesture() / gestureName(g)the last gesture and its readable name
x() / y() / button() / source() / contact() / modifiers()latched event fields
isTouch() / isMouse() / isPressed() / isDragging()state queries
pressX() / pressY()where the current press/drag started
snapshot()an SLBallumPointerEvent value object of the latched event

Platform support: the Linux (X11) backend provides live pointer input (XSelectInput + button/motion events). The macOS and Windows backends report available() == false for now — whole-screen global capture there needs a CGEventTap (macOS, with Accessibility permission) or a WH_MOUSE_LL hook (Windows), each with its own lifecycle; until wired, they fail cleanly rather than fake an input stream. Runnable demo: input-demo.sleela.

The Screen API (SLBallumScreen) — pixel accuracy, cleanly

SLBallumScreen is the surface most developers should use. It wraps the low-level SLBallumManager for one bound display and offers a small, polite, well-named API with pixel accuracy as its contract: every placement is validated against the live display geometry and the display's advertised capability before it reaches the device, so a write either lands exactly where asked or returns a precise, readable status — it never silently clips, wraps, or no-ops. Coordinates use a top-left origin: x in [0, width), y in [0, height).

SLBallumScreen screen = new SLBallumScreen();
screen.create();
screen.attach(nativeHandle);     // host VM provides the backend handle
screen.open();                   // enumerate + bind the primary display

if (screen.isReady() && screen.canPlotPixels()) {
    screen.plotRgb(10, 20, 255, 0, 0);          // one exact red pixel
    screen.fillRect(0, 0, 32, 32, screen.rgb(0, 128, 255));
    int packed = screen.sample(10, 20);         // read back: 0xAARRGGBB
}
if (screen.canSetBrightness()) { screen.brightness(70); }   // 0..100 %
if (screen.canSetWarmth())     { screen.warmth(3400); }     // kelvin (warm)
if (screen.canSetGamma())      { screen.gammaPoint(2, 20); }// gamma 2.20
print(screen.lastMessage());                                // readable status
MethodPurpose
create() / attach(handle) / open() / openIndex(i)prepare, bind the native handle, enumerate + bind a display
isReady() / width() / height() / name() / displayId() / isPrimary()readiness + geometry/identity of the bound display
screenCount() / primaryIndex()discovery across displays
canPlotPixels() / canSetBrightness() / canSetWarmth() / canSetGamma()capability gates to check before enabling a control
inBounds(x, y)the accuracy gate every placement passes
rgb(r,g,b) / rgba(r,g,b,a)build a color at the call site
plot(x,y,color) / plotRgb(x,y,r,g,b)set exactly one pixel
sample(x,y)read a pixel back as packed 0xAARRGGBB (verify accuracy)
fillRect(x,y,w,h,color)fill an exact rectangle, pixel by pixel
brightness(%) / warmth(kelvin) / gamma(scaled) / gammaPoint(whole,hundredths)whole-display controls
statusCode() / ok() / lastMessage()precise, readable result of the last op

Runnable demo: screen-demo.sleela.

Per-OS profile classes (the lib/antivirus profile pattern) under platforms/<Brand>/<OS>/:

FileOSBackend
platforms/GNU/Linux/SLLinuxBallumProfile.sleelaLinuxx11-xrandr
platforms/Apple/macOS/SLMacOSBallumProfile.sleelamacOSmacos-coregraphics
platforms/Microsoft/Windows/SLWindowsBallumProfile.sleelaWindows 10+windows-gdi

Each profile exposes the backend name and per-OS capability facts (supportsColorTemperature(), supportsDdcBacklight(), …), so the SLeeLa layer can reason about OS differences without touching the device.

The flow

bindNativeHandle(h)                       → BRIDGE_READY (or BACKEND_UNAVAILABLE)
acceptEnumerateResult(status, count)      → ENUMERATED; displays() known
display.supportsBrightness()              → gate the control in the UI
mgr.requestBrightness(display, 70)        → OK (bridge dispatches) or UNSUPPORTED
mgr.statusText()                          → human-readable status

Result codes

Mirror ballum_status_t (see SLBallumStatus):

CodeMeaning
0 OKok
1 INVALID_ARGUMENTbad arguments
2 BACKEND_UNAVAILABLEno backend on this host
3 BACKEND_ERRORthe OS display call failed
4 DISPLAY_NOT_FOUNDunknown display id
5 OUT_OF_BOUNDSpixel/region outside the display
6 BUFFER_TOO_SMALLenumerate buffer too small
7 UNSUPPORTEDdisplay/backend lacks this capability
8 PERMISSION_DENIEDOS refused the operation
9 NOT_INITIALIZEDmanager not initialized
100 BRIDGE_REQUIREDnative bridge not installed (SLeeLa-side)

Ranges (mirror ballum_manager.h)

SLBallumManager exposes clampBrightness/clampWarmth/clampGamma mirroring the native ballum_clamp_* helpers.

Relationship to the native tree

Implementation boundary

These classes manage, classify, validate, and report. Real pixel/brightness/ warmth/gamma control requires the native ballum/ backend plus a host VM bridge. Without the bridge, operations report BRIDGE_REQUIRED; with a backend that lacks a capability, they report UNSUPPORTED — never a false success.

Examples and Tutorial Series

The package now includes a progressive learning path:

Start with examples/05-headless-safe.sleela and examples/01-screen-inspection.sleela before trying operations that visibly change a display. The examples are source additions; compilation and runtime behavior still need to be verified with the project's actual SLeeLa toolchain and target OS.

Full-Screen White Splash and Logo Fade

For a ready-to-run, full-screen white display with the repository logo fading in, see Ballum Full-Screen Tutorial. From the repository root:

make -C impl
./impl/build/sleela run lib/ballum/session-demo.sleela

The default splash uses logo 007; select logo 006 with:

LOGO_FILE=images/national-bitcoin-icc-logo-006.jpg FX=fade ./impl/build/sleela run lib/ballum/session-demo.sleela

The runnable paints a white background, fades the logo in, handles Escape, then fades the logo out and restores white. The reusable SLBallumSession API now provides finish() for the same graceful fade-out; call it after the step() loop. Relative asset paths assume the repository root is the working directory. These are source-level examples; validate the build and display backend on your machine before relying on live display control.

Files 37