Home /Examples/lib/examples/ballum/LEARNING-NOTES.md

LEARNING-NOTES.md

lib/examples/ballum/LEARNING-NOTES.md · 60 line(s) · markdown

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

LevelFileThe one new idea
BasicBASIC-frame-metrics.sleelaA frame is width × height: pixel count and aspect ratio.
ModerateMODERATE-fit-and-letterbox.sleelaFit a source inside a frame keeping aspect ratio, then center it (letterbox / pillarbox).
AdvancedADVANCED-dirty-rects.sleelaTrack 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

  1. 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.
  2. 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.
  3. 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

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.