Ballum Full-Screen: Quick Start and Careful Use
Ballum is SLeeLa's pixel-accurate native-display API. These examples target the current master tree and use the logo assets already in images/.
1. Run the full-screen white splash
From the repository root:
make -C impl
./impl/build/sleela run lib/ballum/session-demo.sleela
The demo requests the primary display, paints the full surface white, loads
images/national-bitcoin-icc-logo-007.jpg, and fades the logo in. When the
session ends, it fades back to white. The first Escape enters frame mode; the
second Escape exits. Keep calling step() while in frame mode so the second
press is handled.
2. Choose the alternate logo
LOGO_FILE=images/national-bitcoin-icc-logo-006.jpg FX=fade ./impl/build/sleela run lib/ballum/session-demo.sleela
Other available effect names are printed by the runnable. Try FX=iris-in,
FX=wipe-left, or FX=dissolve. Use the repo-root working directory so
relative image paths resolve.
3. Tune the reveal
SESSION_FRAMES=48 FX=fade LOGO_FILE=images/national-bitcoin-icc-logo-007.jpg ./impl/build/sleela run lib/ballum/session-demo.sleela
A larger SESSION_FRAMES value gives a longer fade. Use the default modest
value for quick testing; the demo frame loop uses a 16 ms busy-wait cadence
because the current SLeeLa surface does not expose a sleep/yield primitive.
That cadence is simple but can consume CPU while the demo is running.
4. Minimal session API pattern
The standard library session API is in lib/ballum/SLBallumSession.sleela.
Its intended usage pattern is: call finish() after the exit loop to fade the
logo back out and restore the configured background (white by default).
SLBallumSession s = new SLBallumSession();
s.withLogoFile("images/national-bitcoin-icc-logo-007.jpg");
s.withEffect(SLBallumEffect.FADE);
s.withFadeFrames(48);
s.start();
while (s.step() != SLBallumSession.EXIT) {
// Keep polling; first Escape enters FRAME, second Escape exits.
}
s.finish(); // fade the logo back to white, then restore a clean white screen
This is an API illustration; use the runnable demo above as the verified
entry point for the current single-file sleela run workflow.
Careful-use checklist
- Run from the repository root when using relative paths.
- Save work before launching a full-screen display-control demo.
- Confirm the selected monitor and resolution before using pixel-level APIs.
- Test on a normal user desktop first; do not run as root.
- On a headless machine, expect the backend to fail closed rather than claim a display was opened.
- Check
uiBallumLogoReady()before assuming image decoding succeeded. - Keep keyboard polling in the loop and continue until
EXIT. - Avoid extremely large frame counts and avoid running multiple full-screen sessions simultaneously.
- This demo is a display/rendering example, not a cryptocurrency wallet or proof of any seizure or crime.
Assets
Validation notes
The source and paths are updated in the repository. A successful remote commit
does not itself prove the current host can open a display or decode a JPEG.
Run make -C ballum test and make -C impl all, then try the demo on a
machine with a supported graphical display. These commits have not been
validated by a live full-screen run in this session.