idea_canvas.h
idea/realtime/idea_canvas.h · 253 line(s) · c
/*
* idea/realtime/idea_canvas.h -- Idea System(TM) realtime canvas: public C ABI.
*
* Idea System(TM) / Idea(TM). From Author; distributive.
*
* A native rendering + physics module the Sleela runtime can reference and
* load for the cases where a VM does not have realtime canvas support natively.
* It is deliberately split into two layers:
*
* 1. The PHYSICS / compute core (idea_canvas_sim.*): a large contiguous
* vertex block advanced by an OpenMP + SIMD decay/physics step. This
* layer has NO graphics dependency -- it is pure C/C++ and is built and
* verified anywhere a C++20 + OpenMP compiler exists.
*
* 2. The RENDER layer (idea_canvas_gl.*): a GLFW window with a persistent-
* mapped, triple-buffered OpenGL vertex buffer, so the exact memory block
* the physics core writes is drawn by the GPU with no re-upload. This
* layer requires GLFW + OpenGL at build time and is OPTIONAL.
*
* The whole module is loadable through this one C ABI (extern "C"), so a VM
* can dlopen/LoadLibrary it and bind the entry points as native built-ins.
* Build with IDEA_CANVAS_WITH_GL to include layer 2; without it, only the
* verified physics core is compiled and the render entry points return
* IDEA_CANVAS_NO_RENDERER.
*
* Hz contract (mirrors idea/idea_system.h):
* present at 60 Hz; advance the live simulation at a deterministic 120 Hz
* fixed timestep.
*/
#ifndef IDEA_CANVAS_H
#define IDEA_CANVAS_H
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
#define IDEA_CANVAS_VERSION "1.0.0"
#define IDEA_CANVAS_PRESENT_HZ 60.0
#define IDEA_CANVAS_SIM_HZ 120.0
/* Status codes returned across the ABI. */
typedef enum idea_canvas_status {
IDEA_CANVAS_OK = 0,
IDEA_CANVAS_INVALID = -1, /* bad argument / null handle */
IDEA_CANVAS_OOM = -2,
IDEA_CANVAS_NO_RENDERER = -3, /* built without GL, or no display */
IDEA_CANVAS_GL_ERROR = -4 /* GLFW / OpenGL init or runtime failure */
} idea_canvas_status;
/*
* One canvas vertex. Laid out as a flat POD so the whole array is a single
* contiguous block that maps 1:1 onto an interleaved OpenGL vertex buffer
* (position, RGBA, and the scalar fields the physics step evolves).
*
* Keep this struct tightly packed and stable: the GL vertex-attribute layout
* and the VM's binding both depend on the exact field order and offsets.
*/
typedef struct idea_vertex {
float x, y; /* position in canvas space [0,1]x[0,1] */
float r, g, b, a; /* straight-alpha colour, 0..1 */
float intensity; /* current energy; decays toward 0 each step */
float velocity; /* scalar flow speed (drives colour-predictive hue) */
} idea_vertex;
/*
* Compute backends the simulation step can run on.
* CPU: the OpenMP + SIMD physics core (always available, verified).
* GPU: an offscreen GL compute path keeping data in device/native memory
* (EGL-surfaceless on a real GPU; OSMesa software fallback). Available
* only when the module was built with IDEA_CANVAS_WITH_GL and a context
* could be created at runtime.
*/
typedef enum idea_backend {
IDEA_BACKEND_CPU = 0,
IDEA_BACKEND_GPU = 1
} idea_backend;
/*
* Backend-selection policy. AUTO lets the VM decide: it runs on the CPU and,
* if sustained throughput falls below the 120 Hz budget AND a GPU backend is
* available, it offloads to the GPU. FORCE_* pin a backend.
*/
typedef enum idea_backend_policy {
IDEA_POLICY_AUTO = 0, /* measure; offload CPU->GPU under budget */
IDEA_POLICY_FORCE_CPU = 1,
IDEA_POLICY_FORCE_GPU = 2
} idea_backend_policy;
/* Opaque handle to a realtime canvas (owns the vertex block + optional GL). */
typedef struct idea_canvas idea_canvas;
/* ---- lifecycle -------------------------------------------------------- */
/*
* Create a canvas with a `cols` x `rows` grid of vertices. Allocates the
* contiguous vertex block (cols*rows elements). Does NOT open a window.
* Returns NULL on allocation failure.
*/
idea_canvas *idea_canvas_create(int cols, int rows);
/* Destroy a canvas, release the vertex block and any GL resources. */
void idea_canvas_destroy(idea_canvas *c);
/* Grid dimensions and total vertex count. */
int idea_canvas_cols(const idea_canvas *c);
int idea_canvas_rows(const idea_canvas *c);
size_t idea_canvas_count(const idea_canvas *c);
/*
* Direct access to the contiguous vertex block (count = idea_canvas_count).
* The VM may read/write this directly between steps; it is the same memory the
* GL layer maps. Returns NULL for a null handle.
*/
idea_vertex *idea_canvas_vertices(idea_canvas *c);
const idea_vertex *idea_canvas_vertices_const(const idea_canvas *c);
/* ---- physics / compute core (OpenMP + SIMD; no graphics dep) ---------- */
/* Decay/flow parameters for the simulation step. */
typedef struct idea_sim_params {
float decay; /* per-second multiplicative decay of intensity */
float flow_gain; /* how strongly velocity feeds the colour-predictive */
float hue_base; /* base hue in degrees (205 ~ water) */
float coupling; /* neighbour coupling (diffusion of intensity) */
} idea_sim_params;
/* Sensible defaults (water-like flow field). */
idea_sim_params idea_sim_defaults(void);
/*
* Inject energy at a grid cell (e.g. where a signal "importance" lands), so a
* ripple of intensity propagates on subsequent steps.
*/
idea_canvas_status idea_canvas_excite(idea_canvas *c, int col, int row,
float amount);
/* Store the simulation parameters used by subsequent idea_canvas_step /
* idea_canvas_advance calls (so a VM can configure the flow without passing a
* struct across the bridge each step). NULL fields are ignored. */
idea_canvas_status idea_canvas_set_params(idea_canvas *c, float decay,
float flow_gain, float hue_base,
float coupling);
/* Read one vertex's current intensity (0..1), or 0 for an out-of-range cell. */
float idea_canvas_intensity_at(const idea_canvas *c, int col, int row);
/*
* Advance the simulation by ONE fixed timestep (dt seconds, normally
* 1/IDEA_CANVAS_SIM_HZ). Parallelised with OpenMP and vectorised per row;
* updates intensity decay, neighbour coupling, velocity, and the
* colour-predictive RGBA of every vertex. Safe to call with any dt > 0.
*/
idea_canvas_status idea_canvas_step(idea_canvas *c, const idea_sim_params *p,
float dt);
/*
* Drain a fixed-step accumulator: feed the real per-frame delta and run as
* many 120 Hz steps as are due (clamping a long stall). Returns the number
* of steps run. `accumulator` is owned by the caller.
*/
int idea_canvas_advance(idea_canvas *c, const idea_sim_params *p,
double frame_dt_seconds, double *accumulator);
/* Fixed simulation timestep in seconds (1 / IDEA_CANVAS_SIM_HZ). */
double idea_canvas_timestep(void);
/* ---- backend selection + auto GPU offload ----------------------------- */
/*
* Set the backend policy (default IDEA_POLICY_AUTO). Under AUTO the canvas
* starts on the CPU; idea_canvas_advance measures sustained throughput and, if
* it falls below the 120 Hz budget and a GPU backend is available, migrates
* the canvas to the GPU (keeping its vertex state). FORCE_GPU with no GPU
* available stays on CPU and reports GPU as unavailable.
*/
idea_canvas_status idea_canvas_set_policy(idea_canvas *c, idea_backend_policy p);
idea_backend_policy idea_canvas_policy(const idea_canvas *c);
/* The backend the canvas is currently simulating on. */
idea_backend idea_canvas_active_backend(const idea_canvas *c);
/* Is a GPU backend available in this build + at runtime? (1/0) */
int idea_canvas_gpu_available(void);
/*
* The measured sustained simulation rate (steps/second), a rolling average
* updated by idea_canvas_advance. 0 before enough samples. This is the
* signal the AUTO policy compares against IDEA_CANVAS_SIM_HZ.
*/
double idea_canvas_measured_hz(const idea_canvas *c);
/*
* Force a one-shot backend migration now (CPU<->GPU), copying vertex state to
* the target backend's memory. Returns IDEA_CANVAS_NO_RENDERER if the GPU is
* requested but unavailable. Normally you set a policy and let advance decide;
* this is for tests and explicit control.
*/
idea_canvas_status idea_canvas_migrate(idea_canvas *c, idea_backend target);
/* ---- render layer (GLFW + OpenGL; optional) --------------------------- */
/*
* Open a window and initialise the GL renderer: compiles the shaders and
* allocates a persistent-mapped, triple-buffered vertex buffer sized to the
* vertex block. Returns IDEA_CANVAS_NO_RENDERER if the module was built
* without IDEA_CANVAS_WITH_GL (then run headless via idea_canvas_step only).
*/
idea_canvas_status idea_canvas_open_window(idea_canvas *c, int width,
int height, const char *title);
/* True if the window has been asked to close. */
int idea_canvas_should_close(const idea_canvas *c);
/*
* Present one frame: copy the current vertex block into the next persistent-
* mapped buffer region (guarded by a fence), issue the draw call, swap, and
* poll events. Call at the present rate (60 Hz). No-op/NO_RENDERER when the
* GL layer is absent.
*/
idea_canvas_status idea_canvas_present(idea_canvas *c);
/*
* The full driving loop: open a window, then repeatedly advance the physics at
* 120 Hz fixed step and present at ~60 Hz until the window closes. A VM that
* just wants "run the canvas" calls this. NO_RENDERER if GL is absent.
*/
idea_canvas_status idea_canvas_run(idea_canvas *c, const idea_sim_params *p,
int width, int height, const char *title);
/* Was the module built with the GL render layer? (1/0) */
int idea_canvas_has_renderer(void);
/* ---- GPU compute backend hooks (implemented in idea_canvas_gpu.cpp) ----
* These are called by the core when a canvas is on IDEA_BACKEND_GPU. Without
* IDEA_CANVAS_WITH_GL they are stubs that report unavailable. Not normally
* called directly by a VM -- use the policy/migrate API above. */
int idea_canvas_gpu_init(idea_canvas *c); /* create ctx + upload; 0 ok, <0 err */
int idea_canvas_gpu_step(idea_canvas *c, const idea_sim_params *p, float dt);
int idea_canvas_gpu_readback(idea_canvas *c); /* GPU -> native vertex block */
void idea_canvas_gpu_shutdown(idea_canvas *c);
/* Human-readable status name (never NULL). */
const char *idea_canvas_status_name(idea_canvas_status s);
#ifdef __cplusplus
} /* extern "C" */
#endif
#endif /* IDEA_CANVAS_H */