zinc:3d — 3D on the CPU, and on the GPU where there is one

plugins/3d renders simple 3D scenes on the CPU, on every target that runs the 2D rasterizer, and on the GPU on macOS (see GPU renderer). The scene graph, camera and math are Zinc code (plugins/3d/index.ts); transform, lighting, clipping and rasterization are C++ (plugins/3d/native/render3d.host.cpp). plugins/three draws through zinc:3d, so it gets both. A frame is rendered into a runtime image (raster::dyn_wrap) that render() adds to the frame as an ordinary image command (like gfx.drawImage, nearest-neighbour when scaled), so 2D drawing and zinc:ui compose over it.

import { onFrame, width, height, image, drawText, font } from 'zinc:gfx';
import { Scene, Camera, Node, Material, Light, cube, render } from 'zinc:3d';

const scene = new Scene();
scene.lights.push(new Light(-0.5, -1, -0.6, 0xffffff));
const crate = new Material(0xffffff);
crate.texture = image('crate.png');                 // baked asset, or gfx.createImage() for a runtime texture
const box = scene.add(new Node(cube(1), crate));
const camera = new Camera().setPosition(0, 1.5, 4).lookAt(0, 0, 0);
let t = 0;

onFrame((dt: number) => {
  t += dt;
  box.setRotation(0, t, 0);
  const tris = render(scene, camera, 0, 0, width(), height());   // 3D view
  drawText(font('sans', 12), 8, 8, `${tris} triangles`, 0xffffff, 255, 0);  // 2D over it
});

Examples: examples/3d/cubes (textured cubes with a baked PNG and a runtime image painted with zinc:gfx, a Gouraud torus, a flat-shaded sphere, a textured floor, fps overlay) and examples/3d/model (an OBJ model with vertex colours and computed normals on a checkered floor; A toggles orthographic, B flat shading).

API

Each camera owns its render target, so split screens use one camera per view. Shading: lighting is computed per vertex (Gouraud) or per face (flat) as base × (ambient + Σ max(0, −n·L) × light); textures are modulated by it. The scene graph works in any number profile: under fx12 (PS1 profile) the world matrices are composed in Q20.12 in Zinc, then the C++ side works in float.

Rasterizer

• vertices transformed and lit once per draw (float), outcodes against 6 planes; triangles fully outside one plane are dropped, the others are clipped (Sutherland–Hodgman) against the near and far planes and a guard band of ±2 viewports;
• backface culling in screen space (doubleSided disables it);
• blending and emissive (ZN-696): a blended triangle is depth tested and writes no depth; over: (c × a + d × (255 − a)) / 255, added: d + c × a / 255, clamped, on both renderers (the GPU’s frame equals the software one on tests/data/zinc3d_glow). Opaque draws keep their code: on the GPU the emissive and blended draws use shader variants of their own;
• highlights (ZN-563.04): Blinn-Phong with three.js’s BRDF_BlinnPhong factor, specular × lightColour × n·l × (shininess/2 + 1)/4 × (n·h)^shininess added to the lit colour per vertex (per pixel on the GPU); a cube’s flat faces barely show them in software;
• scanline rasterization, top-left rule at pixel centres, edges and attributes stepped in 16.16 fixed point;
• depth: NDC z in Q30, stored in a 16- or 32-bit z-buffer;
• texturing is perspective-correct every subdiv pixels (exact u/w, v/w, 1/w at the run ends, affine inside a run): 16 is visually exact at these resolutions, larger values trade accuracy for fewer divisions;
• optional 2x2 ordered dither to RGB565 (for 16-bit panels).

Four inner loops are instantiated (textured or not × Gouraud or constant colour).

GPU renderer

plugins/3d/native/render3d.gl.cpp (ZN-563) implements the same native interface on OpenGL 3.2 core (macOS) and is written against the GLES 3 subset; it includes the software renderer, which stays the fallback and the oracle. It reproduces the software shading:

• one vertex array per mesh (position, normal, uv, colour interleaved; the software renderer builds the mesh, normals included, then its arrays are freed), one program per kind of material: unlit (three’s MeshBasicMaterial) or lit (Lambert: ambient + 4 directional lights per vertex, clamped, like the software renderer), smooth or flat (the face normal from the derivatives of the world position), textured or not (nearest texel, repeat), vertex colours or not, highlights or not (per pixel, from the world normal and the eye position); the uniforms are the model and model-view-projection matrices, the colour and the lights (once per program and frame);
• depth test, back faces culled unless double-sided, colour interpolated in screen space (noperspective) like the software spans;
• the target is a framebuffer read back into the same runtime image, presented the same way. The read is asynchronous (a pixel buffer per target, mapped one frame later: the image shows the previous frame, as gl.zincPresent does); deterministic runs read synchronously (ZINC_GL_PRESENT=sync|async chooses, as for WebGL). The shaders write blue first so that the RGBA bytes read back are the runtime’s 0x00RRGGBB words: a GL_BGRA read made the driver convert on the CPU, synchronously (2.5 ms at 800x500 on the Intel Mac);
• render() returns the triangles submitted (three.js’s renderer.info counts so), the software renderer those drawn after culling.

Not done yet: the GLES 2 path (no vertex arrays) and contexts on Linux, the Pi and the web (follow-up tasks).

Options and memory

zinc.json: "plugins": { "3d": { ... } }, or per target under targets.<id>.plugins.3d.

Memory per camera, allocated on the first render and on resize, freed by camera.dispose(): colour 4 × W × H (the runtime image) + depth 2 or 4 × W × H, with W = w / scale, H = h / scale.

Also: meshes 24 B/vertex (+8 uv, +4 colour) + 2 B/index (at most 65535 vertices per mesh), a per-vertex scratch of 37 B × the largest mesh, and a 0x00RRGGBB copy of each baked image used as a texture (4 × w × h, made on first use; runtime images are sampled in place). Buffers come from system memory (hal_alloc) first and fall back to the Zinc heap, which on ESP32 owns the largest free block; when both are full the program panics with out of memory (heap budget …).

ESP32 without PSRAM: the Zinc heap gets about 94 KiB (the largest free block after ESP-IDF, the display bands and FreeRTOS) and system memory is fragmented into blocks of ~13 KiB, so a 320x240 screen takes scale: 3 (a 106x80 view: 33 KiB colour + 17 KiB z16). scale: 2 (160x120, 112 KiB) does not fit.

Targets and performance

Measured on an Apple M1 Pro, macOS release build (-O2), average of 300 renders (render() only: clear, transform, raster; the machine was loaded by other builds, so the ranges are the spread of several runs; the 2D compositor’s scaling and presentation are not included):

GPU renderer, Intel Mac (x86_64, Intel GPU), AOT, 800x500, CPU time of a frame (animation + renderer.render, the read included), 240 frames after 60 (bench/three_many.ts, bench/qjs/three_many.mjs):

Not verified: timings on a real Pi 1 or ESP32 (no hardware), the wasm page in a browser, dithering on a physical RGB565 panel. Checked: screenshots on macOS (f64 and --profile ps1), tests/conformance/scene3d.ts (primitives, OBJ parsing, transforms and a few rendered frames; sim, macOS, f32 and fx12 profiles give the same output).

Limits and follow-ups

• lighting uses the model matrix’s 3x3 for normals (exact for rotations and uniform scale only); back faces of double-sided materials are lit with the front normal;
• no transparency, fog, mipmapping or texture filtering (nearest texel); no shadows;
• one texture per material; OBJ materials (mtllib/usemtl) are ignored;
• a PS1 build would want fixed-point transforms (GTE-style) instead of soft float.

Edit this page on GitHub ↗