Ballum examples — what to learn here
Ballum is SLeeLa's display/frame layer. These examples teach the arithmetic of a frame: how a rectangle of pixels is described, how content is fitted inside it, and how a renderer decides which parts to repaint. They are calculation-only — no native display backend is opened, so they run anywhere and always print the same numbers.
Read them in order; each adds one idea.
The three cases
| Level | File | The one new idea |
|---|---|---|
| Basic | BASIC-frame-metrics.sleela | A frame is width × height: pixel count and aspect ratio. |
| Moderate | MODERATE-fit-and-letterbox.sleela | Fit a source inside a frame keeping aspect ratio, then center it (letterbox / pillarbox). |
| Advanced | ADVANCED-dirty-rects.sleela | Track changed regions ("dirty rectangles"), union them, and measure frame coverage. |
The original CLASSIC-display-frame.sleela is the
shortest starter.
What we want you to take away
- A display is numbers before it is pixels. Every decision a renderer makes — how big, where, how much to repaint — is arithmetic you can do and verify without a screen. That is what these examples show.
- Aspect-ratio fitting is a "smaller of two ratios" rule. The moderate
example scales by
min(frameW/srcW, frameH/srcH)so the whole source fits, then splits the leftover space into equal margins. Whichever axis has margin tells you letterbox vs pillarbox. - Real renderers repaint only what changed. The advanced example models dirty rectangles and unions them into one bounding box, then compares its area to the whole frame. This is why a well-written UI does not redraw the entire screen on every keystroke.
Practical notes for SLeeLa 1.7
- No math intrinsics. There is no
sqrt/abs/rounding function. Use the operators+ - * / %, and promote todouble(e.g.width * 1.0) when you want a fractional result instead of integer division. (int)does not truncate here. At this language level an(int)cast on a double does not drop the fractional part, so the moderate example keeps fitted sizes as doubles and leaves pixel rounding to the backend. When you want an integer-ish percentage, scale first (the advanced example reports coverage in per-mille using integer math:unionArea * 1000 / frameArea).- Object arrays follow the standard idiom: a static-field array, elements
built in typed locals and stored back, and read via typed locals. See
ADVANCED-dirty-rects.sleela.
Run them
sleela check lib/examples/ballum/BASIC-frame-metrics.sleela
sleela run lib/examples/ballum/MODERATE-fit-and-letterbox.sleela
Output is deterministic. The moderate example reports a 1280×1024 source pillarboxed into a 1920×1080 frame with 285-pixel side margins; the advanced example reports a union rectangle covering 375 per-mille of the frame.