Home /Modules/ballum/README.md

README.md

lib/ballum/tutorials/README.md · 39 line(s) · markdown

Ballum Tutorials

A practical, progressive guide to Ballum, the SLeeLa display and pointer-input package. The series moves from understanding the architecture to safe display discovery, bounded pixel operations, optional display controls, input polling, testing, and native integration.

Lessons

  1. What Ballum Does — architecture, responsibilities, and the difference between a model and real hardware I/O.
  2. Discover Displays — enumeration, display IDs, geometry, capability masks, and multi-display assumptions.
  3. Pixels and Bounds — coordinate rules, validation, safe writes, and failure handling.
  4. Display Controls — brightness, color warmth, gamma, capability checks, and restoring settings.
  5. Mouse and Touch Input — polling, event interpretation, bounded loops, and platform constraints.
  6. Status Codes and Testing — error diagnosis, negative tests, headless execution, and a repeatable test matrix.
  7. The Native Bridge — request flow, backend selection, platform support, and integration review.

Suggested learning path

Prerequisites

Examples

The examples directory contains small, focused programs. Start with headless-safe and screen inspection, then continue to pixel writes, controls, and input polling. Check each example's comments and the package README before running it.

Core principle: capability is discovered, not assumed

Ballum has several distinct layers: SLeeLa API shape, VM bridge availability, native backend availability, per-display capability, operating-system permission, and successful execution. A positive result at one layer does not guarantee success at the next.

The SLeeLa model/demo files can teach API shape and validation. Only programs wired through the real uiBallum* VM bridge to a functioning native backend can perform actual display I/O. A headless or unsupported host should report that fact rather than simulate success.

See the Ballum package README for the current API, status codes, and platform notes.