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; }
}