Home /Modules/ballum/07-native-bridge.md

07-native-bridge.md

lib/ballum/tutorials/07-native-bridge.md · 75 line(s) · markdown

Lesson 7 — The Native Bridge and Platform Limits

The SLeeLa facade is not itself an operating-system display driver. The native core lives under the repository's ballum/ tree, while impl/core/ballum_vm_bridge.* provides the VM-facing bridge. A source-level method can only perform real device I/O if the running VM has the bridge implementation linked and the selected native backend can perform the requested operation.

Trace one request end to end

  1. A SLeeLa program enumerates displays and checks the target's capabilities.
  2. The program calls the appropriate uiBallum* function.
  3. The VM resolves that function to the Ballum bridge implementation.
  4. The bridge validates and converts the VM arguments into the native API's expected types.
  5. The native manager checks initialization, display identity, ranges, and operation support.
  6. The selected platform backend attempts the operating-system operation.
  7. The status travels back through the bridge to the SLeeLa caller.

This path is useful when debugging. If a SLeeLa method compiles but the runtime reports that a bridge is required, the issue may be the runtime build or registration path rather than the native display driver. If the bridge is reached but the backend is unavailable, investigate backend selection and platform support. If a backend call returns permission denied, follow the operating system's documented permission process.

Platform support must be verified in source

The native specification currently describes Linux x11-xrandr, macOS CoreGraphics, and Windows 10+ GDI display backends. These names indicate intended implementation paths, not identical feature parity. The package README also documents current limitations for pointer capture. Always verify the actual backend files, build configuration, runtime selection, and tests for the commit being evaluated.

A backend may support display enumeration but not a particular control. It may compile on a platform but not be selected in the current runtime. It may be selected but fail at runtime because the host is headless, the display is inaccessible, or permission is denied. Report these cases separately.

Integration checklist

Build and registration

Native boundary

Platform behavior

Evidence

Model demonstrations versus real I/O

The aggregate lib/ballum/ballum.sleela contains model/demo behavior, including a simulated handle path. That can be useful for teaching class shape or state transitions, but it must not be used as proof that a physical display changed. Similarly, a sample that prints a success-like message without checking the bridge's returned status is not a valid integration test.

A strong test makes the result falsifiable: it checks the real status, confirms the selected display and capability, and reports failure when the native operation fails. For display controls, observe the visible change where safe and restore the original setting. For pixel operations, use a minimal, bounded test on a known display. For input, confirm the host supports capture and avoid collecting more data than needed.

Practice: follow the status

Choose one example and trace its operation from the SLeeLa call to the bridge function and native backend. Write down:

If any link in that chain cannot be found or tested, document it as an integration gap rather than assuming it works.

Final checkpoint: distinguish the presence of API classes, the presence of bridge symbols, the availability of a platform backend, and demonstrated success on real hardware.