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 | File | Role | | --- | --- | | `SLPackage.sleela` | Package facade (`configure`/`name`/`available`). | | `SLBallumScreen.sleela` | **The clean, pixel-accurate Screen API** — the high-level surface a developer integrates with (see below). | | `SLBallumManager.sleela` | The 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.sleela` | One connected display: id, geometry, primary flag, and the capability bitmask (`supportsPerPixel`/`supportsBrightness`/…), mirroring `ballum_display_t`. | | `SLBallumColor.sleela` | An 8-bit RGBA color with clamped channels, mirroring `ballum_color_t`. | | `SLBallumStatus.sleela` | Result codes mirroring `ballum_status_t`, plus the SLeeLa `BRIDGE_REQUIRED` code and `text(code)`. | | `SLBallumInput.sleela` | **The touchscreen + mouse input listener** — polls pointer events and synthesizes click/move/drag gestures (see below). | | `SLBallumPointerEvent.sleela` | One 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 | ```java 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(); } } ``` | Method | Purpose | | --- | --- | | `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)`. ```java 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 ``` | Method | Purpose | | --- | --- | | `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///`: | File | OS | Backend | | --- | --- | --- | | `platforms/GNU/Linux/SLLinuxBallumProfile.sleela` | Linux | `x11-xrandr` | | `platforms/Apple/macOS/SLMacOSBallumProfile.sleela` | macOS | `macos-coregraphics` | | `platforms/Microsoft/Windows/SLWindowsBallumProfile.sleela` | Windows 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`): | Code | Meaning | | --- | --- | | `0` OK | ok | | `1` INVALID_ARGUMENT | bad arguments | | `2` BACKEND_UNAVAILABLE | no backend on this host | | `3` BACKEND_ERROR | the OS display call failed | | `4` DISPLAY_NOT_FOUND | unknown display id | | `5` OUT_OF_BOUNDS | pixel/region outside the display | | `6` BUFFER_TOO_SMALL | enumerate buffer too small | | `7` UNSUPPORTED | display/backend lacks this capability | | `8` PERMISSION_DENIED | OS refused the operation | | `9` NOT_INITIALIZED | manager not initialized | | `100` BRIDGE_REQUIRED | native bridge not installed (SLeeLa-side) | ## Ranges (mirror `ballum_manager.h`) - **Brightness**: `0..100` percent. - **Warmth**: `1000..10000` kelvin (6500 = neutral D65). - **Gamma**: encoded ×100, `10..1000` (i.e. `0.10..10.00`). - **Color**: RGBA, each channel `0..255`. `SLBallumManager` exposes `clampBrightness`/`clampWarmth`/`clampGamma` mirroring the native `ballum_clamp_*` helpers. ## Relationship to the native tree - Native manager + per-OS backends: `ballum/` (`ballum/include/sleela_ballum/ballum_manager.h`, `ballum/src/*`). - VM bridge: `impl/core/ballum_vm_bridge.c` and `impl/core/ballum_vm_bridge.h` expose the `uiBallum*` boundary used by the live demos. Verify that the bridge is included in the particular runtime build before expecting device I/O. ## 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: - **[Examples](examples/README.md)** — five focused SLeeLa programs covering display inspection, safe pixel writes, capability-gated display controls, bounded pointer polling, and headless-safe behavior. - **[Tutorials](tutorials/README.md)** — seven lessons covering architecture, display enumeration, coordinate safety, display controls, pointer input, status/testing, and the native bridge. 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](TUTORIAL.md)**. From the repository root: ```sh make -C impl ./impl/build/sleela run lib/ballum/session-demo.sleela ``` The default splash uses [logo 007](../../images/national-bitcoin-icc-logo-007.jpg); select [logo 006](../../images/national-bitcoin-icc-logo-006.jpg) with: ```sh 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.