Home /Modules/ballum/TUTORIAL.md

TUTORIAL.md

lib/ballum/TUTORIAL.md · 90 line(s) · markdown

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.

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

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.