Home /Modules/ballum/SLBallumScreen.sleela

SLBallumScreen.sleela

lib/ballum/SLBallumScreen.sleela · 334 line(s) · sleela

<< lib/ballum/SLBallumScreen.sleela
   SLeeLa Standard Library Definition.
   Definition: The clean, pixel-accurate Screen API for Ballum developers. >>
#sleela 2.5
material;
<< Family: ballum. SLBallumScreen is the high-level, pixel-accurate developer
   API for one bound display. Where SLBallumManager is the low-level bridge to
   the native ballum_manager_t, SLBallumScreen is the polite, ergonomic surface
   a SLeeLa developer actually integrates with: open a screen, ask what it can
   do and how big it is, then set pixels and whole-display controls with clear,
   well-named, safe methods.

   Pixel accuracy is the contract. Every placement is validated against the live
   display geometry and the advertised capability of the display BEFORE it
   reaches the device, so a write either lands exactly where asked or returns a
   precise, readable status -- it never silently clips, wraps, or no-ops.
   Coordinates use a top-left origin: x grows right in [0, width), y grows down
   in [0, height).

   Typical use:
     SLBallumScreen screen = new SLBallumScreen();
     screen.open();                           bind the primary display
     if (screen.isReady()) {
       screen.plot(10, 20, screen.rgb(255, 0, 0));   one exact red pixel
       screen.brightness(70);                 0..100 percent
       screen.warmth(3400);                   kelvin (warm)
     }
     print(screen.lastMessage());

   Result codes mirror SLBallumStatus / the native ballum_status_t: 0 ok,
   1 invalid, 2 backend-unavailable, 4 display-not-found, 5 out-of-bounds,
   7 unsupported, 100 bridge-required. >>
class SLBallumScreen {

  < the low-level bridge-boundary driver >
  SLBallumManager manager;
  < result-code text >
  SLBallumStatus status;
  < enumerate() index of the bound display, or -1 >
  int boundIndex;
  < native display id of the bound display, or -1 >
  int boundId;
  < cached width  (pixels) of the bound display >
  int w;
  < cached height (pixels) of the bound display >
  int h;
  < cached capability bitmask of the bound display >
  int caps;
  < the status of the most recent operation >
  int lastStatus;

  < ---- lifecycle ------------------------------------------------------ >

  < Prepare the Screen. Call open()/openIndex() before drawing. >
  void create() {
    manager = new SLBallumManager();
    manager.configure();
    status = new SLBallumStatus();
    boundIndex = -1;
    boundId = -1;
    w = 0;
    h = 0;
    caps = 0;
    lastStatus = SLBallumStatus.BRIDGE_REQUIRED;
  }

  < Bind the native backend handle the host VM provides. A negative handle >
  < means no display backend is available on this host. >
  boolean attach(int nativeHandle) {
    if (manager == null) { create(); }
    boolean ok = manager.bindNativeHandle(nativeHandle);
    lastStatus = manager.statusCode();
    return ok;
  }

  < open(): enumerate displays and bind the primary one (or display 0 if no >
  < display is flagged primary). Returns the result code. >
  int open() {
    return openIndex(primaryIndex());
  }

  < openIndex(index): enumerate displays and bind the one at `index`. >
  int openIndex(int index) {
    if (manager == null) { create(); }
    int st = manager.enumerate();
    lastStatus = st;
    if (st != SLBallumStatus.OK) { return st; }
    if (index < 0 || index >= manager.displays()) {
      lastStatus = SLBallumStatus.DISPLAY_NOT_FOUND;
      return lastStatus;
    }
    boundIndex = index;
    boundId = manager.displayIdAt(index);
    w = manager.displayWidthAt(index);
    h = manager.displayHeightAt(index);
    caps = manager.displayCapsAt(index);
    lastStatus = SLBallumStatus.OK;
    return lastStatus;
  }

  < A Screen is ready to draw once a display is bound. >
  boolean isReady() { return boundId >= 0; }

  < ---- discovery ------------------------------------------------------ >

  int screenCount() {
    if (manager == null) { return 0; }
    return manager.displays();
  }

  < Index of the primary display among the enumerated set, or 0 as a safe >
  < default when none is flagged. Enumerates first if needed. >
  int primaryIndex() {
    if (manager == null) { create(); }
    if (manager.displays() == 0) { manager.enumerate(); }
    int n = manager.displays();
    int i = 0;
    while (i < n) {
      if (manager.displayPrimaryAt(i)) { return i; }
      i = i + 1;
    }
    return 0;
  }

  < Geometry + identity of the bound display. >
  int width() { return w; }
  int height() { return h; }
  int displayId() { return boundId; }
  String name() {
    if (!isReady()) { return ""; }
    return manager.displayNameAt(boundIndex);
  }
  boolean isPrimary() {
    if (!isReady()) { return false; }
    return manager.displayPrimaryAt(boundIndex);
  }

  < Capability queries a developer checks before enabling a control. These read >
  < the advertised capability bitmask of the bound display (ballum_capability_t: >
  < 1 per-pixel, 2 blit, 4 brightness, 8 warmth, 16 gamma). >
  boolean capHas(int bit) { return (caps / bit) % 2 == 1; }
  boolean canPlotPixels() { return capHas(1); }
  boolean canSetBrightness() { return capHas(4); }
  boolean canSetWarmth() { return capHas(8); }
  boolean canSetGamma() { return capHas(16); }
  < 128 == BALLUM_CAP_FULLSCREEN_SURFACE: a claimable, owned fullscreen frame. >
  boolean canFullScreen() { return capHas(128); }

  < ---- fullscreen surface: total, owned, fast per-pixel control -------- >
  < Claim an override-redirect fullscreen surface over the bound display. The >
  < window manager/compositor leaves every pixel to this program, so drawing >
  < is total (not overpainted). While claimed, plot()/fillRect() write to an >
  < in-memory framebuffer with no per-pixel device round-trips; call present() >
  < to push the whole frame to the screen in one native image transfer >
  < (MIT-SHM when the server supports it). Call releaseFullScreen() to give the >
  < screen back. Returns the result code (also in lastStatus). >
  int claimFullScreen() {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return lastStatus; }
    if (!canFullScreen()) { lastStatus = SLBallumStatus.UNSUPPORTED; return lastStatus; }
    lastStatus = manager.claimSurface(boundId);
    return lastStatus;
  }

  < Push the claimed framebuffer to the screen in one shot. Call after a batch >
  < of plot()/fillRect() writes to make them visible. >
  int present() {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return lastStatus; }
    lastStatus = manager.present(boundId);
    return lastStatus;
  }

  < Release a claimed fullscreen surface; drawing reverts to the live desktop. >
  int releaseFullScreen() {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return lastStatus; }
    lastStatus = manager.releaseSurface(boundId);
    return lastStatus;
  }

  < ---- pixel accuracy helpers ----------------------------------------- >

  < Is (x, y) an exact, in-range pixel on the bound display? This is the >
  < accuracy gate every placement passes through. >
  boolean inBounds(int x, int y) {
    return isReady() && x >= 0 && y >= 0 && x < w && y < h;
  }

  < Build a color without needing to name SLBallumColor at the call site. >
  SLBallumColor rgb(int r, int g, int b) {
    SLBallumColor c = new SLBallumColor();
    c.setRgb(r, g, b);
    return c;
  }
  SLBallumColor rgba(int r, int g, int b, int a) {
    SLBallumColor c = new SLBallumColor();
    c.setRgba(r, g, b, a);
    return c;
  }

  < ---- pixel control (the core of the API) ---------------------------- >

  < plot(x, y, color): set exactly one pixel. Validates readiness, capability, >
  < and bounds before the write, so the pixel lands precisely or a clear status >
  < is returned. Returns the result code (also in lastStatus). >
  int plot(int x, int y, SLBallumColor color) {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return lastStatus; }
    if (color == null) { lastStatus = SLBallumStatus.INVALID_ARGUMENT; return lastStatus; }
    if (!canPlotPixels()) { lastStatus = SLBallumStatus.UNSUPPORTED; return lastStatus; }
    if (!inBounds(x, y)) { lastStatus = SLBallumStatus.OUT_OF_BOUNDS; return lastStatus; }
    lastStatus = manager.setPixel(boundId, x, y, color);
    return lastStatus;
  }

  < plotRgb: the common case, one call, no color object at the call site. >
  int plotRgb(int x, int y, int r, int g, int b) {
    return plot(x, y, rgb(r, g, b));
  }

  < sample(x, y): read a pixel back, returned packed as 0xAARRGGBB, or -1 if the >
  < read is out of bounds / unsupported. Lets a developer verify accuracy. >
  int sample(int x, int y) {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return -1; }
    if (!canPlotPixels()) { lastStatus = SLBallumStatus.UNSUPPORTED; return -1; }
    if (!inBounds(x, y)) { lastStatus = SLBallumStatus.OUT_OF_BOUNDS; return -1; }
    int packed = manager.getPixelPacked(boundId, x, y);
    lastStatus = packed >= 0 ? SLBallumStatus.OK : SLBallumStatus.BACKEND_ERROR;
    return packed;
  }

  < fillRect(x, y, rectW, rectH, color): set every pixel in an exact rectangle, >
  < one accurate plot at a time. The rectangle must lie fully inside the >
  < display; otherwise OUT_OF_BOUNDS is returned and nothing is drawn. Returns >
  < the result code; stops and reports the first non-OK pixel. >
  int fillRect(int x, int y, int rectW, int rectH, SLBallumColor color) {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return lastStatus; }
    if (color == null || rectW <= 0 || rectH <= 0) { lastStatus = SLBallumStatus.INVALID_ARGUMENT; return lastStatus; }
    if (!canPlotPixels()) { lastStatus = SLBallumStatus.UNSUPPORTED; return lastStatus; }
    if (x < 0 || y < 0 || x + rectW > w || y + rectH > h) {
      lastStatus = SLBallumStatus.OUT_OF_BOUNDS;
      return lastStatus;
    }
    int row = 0;
    while (row < rectH) {
      int col = 0;
      while (col < rectW) {
        int st = manager.setPixel(boundId, x + col, y + row, color);
        if (st != SLBallumStatus.OK) { lastStatus = st; return st; }
        col = col + 1;
      }
      row = row + 1;
    }
    lastStatus = SLBallumStatus.OK;
    return lastStatus;
  }

  < ---- whole-display controls ----------------------------------------- >
  < Each checks the capability, then delegates to the manager (which clamps to >
  < the documented range and dispatches to native). >

  < brightness(percent): 0..100. >
  int brightness(int percent) {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return lastStatus; }
    if (!canSetBrightness()) { lastStatus = SLBallumStatus.UNSUPPORTED; return lastStatus; }
    lastStatus = manager.setBrightness(boundId, percent);
    return lastStatus;
  }

  < warmth(kelvin): color temperature, 1000..10000K (6500 neutral; lower warmer). >
  int warmth(int kelvin) {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return lastStatus; }
    if (!canSetWarmth()) { lastStatus = SLBallumStatus.UNSUPPORTED; return lastStatus; }
    lastStatus = manager.setWarmth(boundId, kelvin);
    return lastStatus;
  }

  < gamma(gammaScaled): gamma encoded x100 (2.20 gamma == 220), 10..1000. >
  int gamma(int gammaScaled) {
    if (!isReady()) { lastStatus = SLBallumStatus.BRIDGE_REQUIRED; return lastStatus; }
    if (!canSetGamma()) { lastStatus = SLBallumStatus.UNSUPPORTED; return lastStatus; }
    lastStatus = manager.setGamma(boundId, gammaScaled);
    return lastStatus;
  }

  < gammaPoint(whole, hundredths): convenience for gamma(2, 20) == 2.20 gamma. >
  int gammaPoint(int whole, int hundredths) {
    return gamma(whole * 100 + hundredths);
  }

  < ---- status --------------------------------------------------------- >

  int statusCode() { return lastStatus; }
  boolean ok() { return lastStatus == SLBallumStatus.OK; }
  String lastMessage() { return status.text(lastStatus); }

  < ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
  < Eleven catalogued attributes with getter/setter pairs, so a GUI, loader, >
  < or catalog can read and (where appropriate) override this record. >
  < Values are faithful to the real origin of the subject where publicly known. >
  String metaVersion = "1.0.0";
  int metaId = 11517;
  String metaAuthor = "SLeeLa Project";
  String metaDate = "2026-10-23";
  String metaCopyright = "SLeeLa standard library";
  String metaTrademark = "Ballum";
  String metaCorporation = "SLeeLa Project";
  String metaOrigin = "International";
  String metaBirthDate = "2026";
  < maturity/robustness on a 1..10 scale >
  int metaScienceRating = 9;
  String metaNationalSchedule = "SLeeLa Ballum Screen API (lib/ballum)";

  String getMetaVersion() { return metaVersion; }
  void setMetaVersion(String v) { metaVersion = v; }
  int getMetaId() { return metaId; }
  void setMetaId(int v) { metaId = v; }
  String getAuthor() { return metaAuthor; }
  void setAuthor(String v) { metaAuthor = v; }
  String getDate() { return metaDate; }
  void setDate(String v) { metaDate = v; }
  String getCopyright() { return metaCopyright; }
  void setCopyright(String v) { metaCopyright = v; }
  String getTrademark() { return metaTrademark; }
  void setTrademark(String v) { metaTrademark = v; }
  String getCorporation() { return metaCorporation; }
  void setCorporation(String v) { metaCorporation = v; }
  String getOrigin() { return metaOrigin; }
  void setOrigin(String v) { metaOrigin = v; }
  String getBirthDate() { return metaBirthDate; }
  void setBirthDate(String v) { metaBirthDate = v; }
  int getScienceRating() { return metaScienceRating; }
  void setScienceRating(int v) { metaScienceRating = v; }
  String getNationalSchedule() { return metaNationalSchedule; }
  void setNationalSchedule(String v) { metaNationalSchedule = v; }
}