Home /Modules/idea/idea_canvas.h

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 */