Home /Modules/idea/README.md

README.md

idea/realtime/README.md · 165 line(s) · markdown

Idea System(TM) — realtime canvas (C/C++ rendering + physics)

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 split into two layers behind a single C ABI (idea_canvas.h):

LayerFile(s)DependencyBuilt & verified here?
Physics / compute coreidea_canvas_sim.cppC++20 + OpenMP✅ Yes
Render (OpenGL)idea_canvas_gl.cppGLFW + OpenGL 4.4 + a loader❌ No — see below
No-GL stubidea_canvas_gl_stub.cppnone✅ Yes
Benchmark / demoidea_canvas_bench.cppC++20 + OpenMP✅ Yes

The stack

As recommended: C++20, OpenMP, GLFW, modern OpenGL.

Build

Physics core + benchmark (anywhere; no GPU/display)

cd idea/realtime
make run        # builds libideacanvas.a + idea-canvas-bench, runs the benchmark

With the OpenGL render layer (needs GLFW + a GL loader + a display)

cd idea/realtime
cmake -S . -B build -DIDEA_CANVAS_WITH_GL=ON
cmake --build build

Provide a GL loader (glad or GLEW) as noted in CMakeLists.txt and idea_canvas_gl.cpp (include it before <GLFW/glfw3.h>).

Verified performance (this environment)

Physics core, 8 OpenMP threads, release build:

grid 128x128, 200 steps -> ~9,000 steps/s  (≈149 M vertex-updates/s)
headroom vs 120 Hz target: ~75x

Three excited points produce three spreading, slowly-decaying ripples — the colour-predictive "water" flow field the renderer draws.

CPU / GPU backend selection (auto-offload)

The VM chooses where the simulation runs and falls back to the GPU when the CPU cannot sustain 120 Hz:

The GPU backend (idea_canvas_gpu.cpp) is an offscreen, windowless GL compute path: EGL-surfaceless on a real GPU, or OSMesa (software GL in CPU/native memory) as a fallback — so it runs on a server with no display. The step is a ping-pong FBO fragment shader; glReadPixels brings the field back into the native vertex block on readback.

Cross-platform rendering (Windows 10+, macOS, Linux)

On-screen and GPU rendering use open standards only — OpenGL plus each OS's standard context binding — behind one interface (idea_canvas_ctx.h), selected at build time by OS:

PlatformStandard window + GL contextFile
Windows 10+Win32 + WGL (wglCreateContextAttribsARB, core profile)idea_canvas_ctx_wgl.cpp
macOSCocoa + CGL / NSOpenGLContext (4.1 core)idea_canvas_ctx_cgl.mm
Linux/UnixEGL (surfaceless) / GLX, OSMesa software fallbackidea_canvas_ctx_egl.cpp

No proprietary APIs (no D3D/Metal). The only hand-written glue is the minimal per-OS window/context shim, for which no cross-platform standard exists. The Windows and macOS builds compile their file via the native toolchain (build-windows.ps1 delegates to the same impl/Makefile; macOS uses the Darwin branch); the .mm/WGL files are guarded so they are inert on other OSes. idea_canvas_gpu_available() reflects whether the platform context layer can create a context.

Verified here: Linux build selects and compiles the EGL file (as the no-GL stub) and the VM runs. The Windows (WGL) and macOS (CGL) context code is written against the standard APIs but is not compiled or run in this Linux sandbox — build and run it on Windows 10+ / macOS.

Sleela built-ins: ideaCanvasSetBackendPolicy, ideaCanvasPolicy, ideaCanvasActiveBackend, ideaCanvasGpuAvailable, ideaCanvasMeasuredHz, ideaCanvasMigrate.

⚠️ What is NOT verified here

idea_canvas_gl.cpp (the GLFW/OpenGL layer) is written but not compiled or run in the Idea System sandbox: there are no GL/GLFW headers, no GPU, and no display. Treat it as reviewed-but-unverified; build and run it on a machine with a GPU + display. The physics core, the no-GL stub, the benchmark, and the ABI are all built and verified here.

When built without IDEA_CANVAS_WITH_GL, the render entry points return IDEA_CANVAS_NO_RENDERER and the physics core runs fully headless.

How the Sleela runtime loads it

The module exposes one flat extern "C" ABI (idea_canvas.h). A VM that lacks native realtime-canvas support can dlopen/LoadLibrary the built library and bind these entry points as native built-ins:

Because the physics and render layers share one ABI, a VM can use just the compute core headless, or the full windowed renderer, with the same binding.

Sleela binding: lib/idea/SLIdeaCanvas.sleela

A SLeeLa standard-library class binds this module so a runnable can drive the canvas on the native CPU directly:

SLIdeaCanvas cv = new SLIdeaCanvas();
cv.create(256, 256);                       // allocate the native vertex block
cv.setParams(0.25, 0.9, 205.0, 0.06);      // water-like flow
cv.excite(128, 128, 1.0);                  // an importance lands
if (cv.hasRenderer()) {
    cv.run(720, 480, "Idea System(TM)");   // native window: 120 Hz sim / 60 Hz present
} else {
    cv.step(cv.timestep());                // headless: advance on the native CPU
}
cv.destroy();

Each method bottoms out in an ideaCanvas* native-bridge built-in. The physics step runs on the native CPU (OpenMP across every core, SIMD per row); the optional OpenGL layer presents the same block. Where a VM links this module, the built-ins bind to the entry points below; where it does not, the render calls return NO_RENDERER and the compute core still runs.

The binding references these ABI entry points (the first two added for it): idea_canvas_set_params, idea_canvas_intensity_at, plus create, destroy, cols/rows/count, excite, step, advance, timestep, open_window, should_close, present, run, and has_renderer.