graphics

General-purpose drawing, window, input and immediate-mode UI toolkit, backed by macroquad through the native module stdlib/graphics.so (Rust crate rust/graphics).

Requires: a Rust toolchain to build, and a display with OpenGL (X11 or Wayland) to run. Without one, set LYNXER_GRAPHICS_HEADLESS=1. Linux is the only supported platform. Without a display the module rasterizes on the CPU: clearBackground, drawRectangle, drawRectangleLines, drawLine, drawTriangle, drawTriangleLines, drawCircle and drawCircleLines fill a framebuffer and screenshot(path) writes it as a PNG, in the same top-left origin the drawing ops use. Text, textures, fonts, shaders, render targets and the ui* widgets need a window and stay no-ops. lynxer/examples/stdlib_graphics_raster.lynx is the CI-runnable check.

graphics is the low-level surface. The game module is a separate, game-oriented layer over the same backend (sprites, scenes, tilemaps, physics); the two do not share state and can be imported together.

global setup(){ import("graphics"); }

global onStart(){
    global.graphics.loadFont("assets/font.ttf");
}

global onUpdate(float dt){ }

global onDraw(){
    global.graphics.clearBackground(20, 20, 30, 255);
    global.graphics.drawCircle(160.0, 120.0, 40.0, 220, 80, 80);
    global.graphics.drawText("hello", 8.0, 24.0, 24.0, 255, 255, 255);
}

global main(){
    global.graphics.init("demo", 800, 600);
    global.graphics.setStartCallback("onStart");
    global.graphics.setUpdateCallback("onUpdate");
    global.graphics.setDrawCallback("onDraw");
    global.graphics.run();
}

Coordinates and units

• Screen space, origin at the top-left, +Y pointing down.
• Colours are 0..255 per channel, alpha last. The shape helpers default alpha to 255.
• rotation is in radians for the rotated-rectangle ops, textures and text, and in degrees for polygons, ellipses and arcs (macroquad's own split).
• Angles passed to setCamera2D are in degrees.

Frames and callbacks

run() opens the window and blocks, invoking the registered callbacks once per frame: start once, then update(dt) and draw(). Before draw(), the loop clears the window to the colour set with setBackground. stop() ends the loop; Ctrl-C exits with code 130.

Every op that touches the GPU context — loadTexture, loadFont, loadMaterial, renderTarget, getScreenData, screenshot, all draw* ops and immediate-mode widgets — is only valid inside a registered callback. start may load resources; update and draw may issue drawing/UI work. Outside a callback, context-dependent integer operations return -1, float operations return -1.0, and string operations return an empty string without calling macroquad. This also applies when a windowed run has not started yet. Headless CPU-rendered drawing and UI remain available outside callbacks.

Headless mode

LYNXER_GRAPHICS_HEADLESS=1 runs without a window: run() executes three frames at a fixed 1/60 timestep, drawing is a no-op, and ops that need a context return a placeholder:

Ops that need no context keep working: images built with genImage and their pixels, rgbToHsl/hslToRgb, the key-name table, the 2D camera value, and the UI value registry.

Window and frame loop

Frame timing

deltaTime() -> float, time() -> float (since run()), fps() -> int, and drawFps(x, y).

2D shapes

Colours are (r, g, b) with an optional a defaulting to 255.

Text and fonts

Pass -1 as the font handle to use the built-in font. font and scale are trailing defaults on measure* and textCenter.

Cameras

Textures, images and render targets

Handles are integers; -1 means "unavailable".

Input

Keys are named, not numeric. Names are case- and separator-insensitive: "space", "Left Shift", "f12", "kpenter", "leftcontrol". Aliases include esc, return, ctrl, shift, alt, del, pgup, pgdn and the arrow* spellings.

3D primitives

Use setCamera3D first. All take (r, g, b) with alpha defaulting to 255.

drawLine3D, drawCube, drawCubeWires, drawSphere, drawSphereWires, drawSphereEx (explicit rings/slices), drawCylinder, drawCylinderWires, drawCylinderEx (explicit side count), drawPlane, drawGrid, drawAffineParallelogram and drawAffineParallelepiped.

Materials

Immediate-mode UI

Widgets are addressed by an integer id. Values are held by the module, so they survive across frames and can be read or written from Lynxer.

macroquad's window and group take a closure, which a flat op list cannot nest, so uiWindowBegin/uiGroupBegin buffer the widgets issued until the matching *End, then replay them inside that closure. Blocks can be nested to arbitrary depth. The headless rasterizer draws nested panels too, without interaction. Widget values update when the outermost block is replayed, so read them after its uiWindowEnd/uiGroupEnd.

Randomness and colour

srand(seed), rand() -> int, genRange(low,high) -> float, genRangeInt(low,high) -> int, rgbToHsl(r,g,b) -> str (JSON [h,s,l]), hslToRgb(h,s,l) -> str (JSON [r,g,b,a]), and setAssetsFolder(path).

Notes and current limitations

• A display is mandatory for real rendering. macroquad has no offscreen backend, so anything that draws needs a window and OpenGL. Headless mode returns placeholders instead of rendering.
• No audio. macroquad's audio feature needs a crate that is not vendored; use the sound module instead.
• No native OS widgets. The ui* set is drawn by macroquad onto the canvas; there is no GTK/Qt/Tk equivalent.
• No gamepad input. macroquad 0.4.16 has no gamepad API.
• No 3D model loading. macroquad can draw generated primitives but has no model importer, and Mesh cannot be built from Lynxer.
• No window retitle, setTargetFps on the backend, or window-resize query. miniquad 0.4.11 exposes none of them; the title is set once by run() and the frame rate is capped by sleeping in the loop.
• The windowed path is not covered by CI. CI runs with LYNXER_SKIP_DISPLAY=1, which skips the graphics fixture; the build, the module-contract check and the headless fixture are what gate it there.

Rust / C ABI

The crate is lynxer_graphics under rust/graphics, a cdylib exporting lynxer_module_init_v1 and lynxer_module_attach_v1. Every op is registered with the packed signature (cdecl:int64(...), cdecl:float64(...) or cdecl:cstring(...)) because several take more than the four arguments the fixed grammar allows. See native-module-abi.

See also

• game — the game-oriented layer over the same backend.
• native-module-abi — writing a Rust backend.
• limitations — platform constraints.