SLIdeaCanvas.sleela
lib/idea/SLIdeaCanvas.sleela · 175 line(s) · sleela
<< lib/idea/SLIdeaCanvas.sleela
SLeeLa Standard Library Definition.
Definition: Defines SLIdeaCanvas โ the SLeeLa binding of the Idea System(TM)
realtime canvas native module (idea/realtime, C ABI idea_canvas.h). It is
the seam that lets a Sleela program drive a high-performance rendering +
physics canvas ON THE NATIVE CPU for the cases where a VM does not have
realtime canvas support natively.
The module is two layers behind one native bridge:
- a physics/compute core that advances a large contiguous vertex block
with an OpenMP + SIMD decay/diffusion/colour step โ this runs on the
NATIVE CPU (every core, vectorised), not the interpreter;
- an optional OpenGL render layer (GLFW + a persistent-mapped, triple-
buffered buffer) that draws the same block with no re-upload.
Every method bottoms out in an `ideaCanvas*` built-in that crosses the
native bridge into the module. Where a VM links the module, the built-ins
are bound to its entry points; where it does not, the render calls report
that no renderer is present and the physics core still runs headless.
Hz contract (mirrors idea/idea_canvas.h): present at 60 Hz; advance the live
simulation at a deterministic 120 Hz fixed timestep.
An SLIdeaCanvas is a VM-local handle (-1 = none).
Family: idea. Native CPU rendering/physics work crosses the explicit
`ideaCanvas*` SLVM bridge into idea/realtime. >>
#sleela 2.5
material;
class SLIdeaCanvas {
< ---- 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 subject's real origin where publicly known. >>
String metaVersion = "1.0.0";
int metaId = 11094;
String metaAuthor = "Kiro Agent";
String metaDate = "2026-10-16";
String metaCopyright = "SLeeLa project";
String metaTrademark = "none";
String metaCorporation = "none";
< metaOrigin: National | <nation> | International | Galactic >
String metaOrigin = "International";
String metaBirthDate = "2026-10-14";
< metaScienceRating: maturity/robustness on a 1..10 scale >
int metaScienceRating = 9;
< metaNationalSchedule: a real, citable instrument or "none" >
String metaNationalSchedule = "none";
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; }
< ---- status ordinals (mirror idea_canvas_status) ---- >
static final int OK = 0;
static final int INVALID = -1;
static final int OOM = -2;
static final int NO_RENDERER = -3;
static final int GL_ERROR = -4;
< ---- Hz contract (mirror idea_canvas.h) ---- >
static final double PRESENT_HZ = 60.0;
static final double SIM_HZ = 120.0;
< VM-local canvas handle (-1 = none) >
int canvas;
< Create a cols x rows grid of vertices (allocates the contiguous block on >
< the native side). Does NOT open a window. Returns true on success. >
boolean create(int cols, int rows) {
canvas = ideaCanvasCreate(cols, rows);
return canvas >= 0;
}
int handle() { return canvas; }
boolean valid() { return canvas >= 0; }
void destroy() { if (canvas >= 0) { ideaCanvasDestroy(canvas); canvas = -1; } }
int cols() { if (canvas < 0) { return 0; } return ideaCanvasCols(canvas); }
int rows() { if (canvas < 0) { return 0; } return ideaCanvasRows(canvas); }
int count() { if (canvas < 0) { return 0; } return ideaCanvasCount(canvas); }
< ---- physics / compute core (runs on the native CPU) ----------------- >
< Set the water-like flow parameters: multiplicative decay per second, flow >
< gain for the colour-predictive hue, base hue (205 ~ water), and the >
< per-step neighbour diffusion coefficient (small, e.g. 0.06). >
void setParams(double decay, double flowGain, double hueBase, double coupling) {
if (canvas >= 0) { ideaCanvasSetParams(canvas, decay, flowGain, hueBase, coupling); }
}
< Inject energy at a grid cell (where a signal "importance" lands) so a >
< ripple propagates on subsequent steps. >
int excite(int col, int row, double amount) {
if (canvas < 0) { return INVALID; }
return ideaCanvasExcite(canvas, col, row, amount);
}
< Advance the simulation by ONE fixed timestep (dt seconds, normally >
< 1/SIM_HZ). Parallelised across the native CPU; returns a status ordinal. >
int step(double dt) {
if (canvas < 0) { return INVALID; }
return ideaCanvasStep(canvas, dt);
}
< Drain a fixed-step accumulator: pass the real per-frame delta and the >
< number of due 120 Hz steps are run on the native CPU. Returns the step >
< count. The accumulator is held on the native side for this canvas. >
int advance(double frameDtSeconds) {
if (canvas < 0) { return 0; }
return ideaCanvasAdvance(canvas, frameDtSeconds);
}
< The fixed simulation timestep in seconds (1 / SIM_HZ). >
double timestep() { return ideaCanvasTimestep(); }
< Read one vertex's intensity (0..1) โ e.g. to drive a SLeeLa-side readout >
< without owning the native block. >
double intensityAt(int col, int row) {
if (canvas < 0) { return 0.0; }
return ideaCanvasIntensityAt(canvas, col, row);
}
< ---- render layer (optional OpenGL; present at 60 Hz) ---------------- >
< True if the module was built with the OpenGL render layer. >
boolean hasRenderer() { return ideaCanvasHasRenderer() == 1; }
< Open a window + GL renderer sized width x height. Returns a status ordinal; >
< NO_RENDERER if the module was built without GL (then run headless via step). >
int openWindow(int width, int height, String title) {
if (canvas < 0) { return INVALID; }
return ideaCanvasOpenWindow(canvas, width, height, title);
}
< True once the window has been asked to close. >
boolean shouldClose() {
if (canvas < 0) { return true; }
return ideaCanvasShouldClose(canvas) == 1;
}
< Present one frame (copy the block to the mapped buffer, draw, swap, poll). >
< Call at the present rate (60 Hz). NO_RENDERER when the GL layer is absent. >
int present() {
if (canvas < 0) { return INVALID; }
return ideaCanvasPresent(canvas);
}
< The full native loop: open a window, then advance at 120 Hz and present at >
< ~60 Hz until the window closes. A program that just wants "run the canvas >
< on the native CPU/GPU" calls this. NO_RENDERER if GL is absent. >
int run(int width, int height, String title) {
if (canvas < 0) { return INVALID; }
return ideaCanvasRun(canvas, width, height, title);
}
}