` you can restyle.
```js
const stats = new StatsOverlay(engine);
engine.run(scene, camera, { frame: (alpha, clock) => stats.update(clock.realDelta) });
```
Notes: `pipelines` should stop climbing once loading is done. If it keeps rising, shaders are compiling mid-frame.
### `overlay.update(dt)` → `void`
Adds `dt` seconds and refreshes the text once `interval` has passed. Call once per frame.
### `overlay.destroy()` → `void`
Removes the box from the page.
## Benchmark
Opt-in timing. It lives in its own module, never imported by the engine, and until it attaches the
renderer's profiling hook costs a null check.
```js
import { Benchmark } from 'winding-engine/bench.js';
```
### `new Benchmark(engine)`
A benchmark for one engine. It records every CPU phase of a frame, every GPU pass where the device
has timestamp queries, and the wall time.
### `benchmark.run(scene, camera, options)` → `Promise
`
Renders `frames` frames, one at a time, and reports on them. It waits for the GPU after every
frame, which is what makes the wall time mean something; it measures a frame, not the throughput of
a pipelined loop.
| Option | Default | Meaning |
|---|---|---|
| `frames` | `300` | frames to record |
| `warmup` | `30` | frames rendered first and not recorded: the first frames compile pipelines and grow buffers |
| `update` | `null` | `update(i)`, run untimed before each frame, to move the camera or animate the scene |
Returns: a report, as [`benchmark.report()`](#benchmark-report) describes.
```js
const report = await new Benchmark(engine).run(scene, camera, { frames: 300 });
console.log(Benchmark.format(report));
```
### `benchmark.start()` and `benchmark.stop()`
Record every frame the engine renders, however it's driven — your own loop or `engine.run` --
between the two. Starting again while running starts the recording over. `stop()` puts GPU timing
back as it was before the first `start()`.
### `benchmark.report()` → `report`
Everything recorded so far, summarised, as plain data safe to `JSON.stringify`:
```js
{ frames,
cpu: [{ name, mean, median, p95, max, share }], // in frame order; they sum to the frame
gpu: [{ name, mean, share }] | null, // null without timestamp queries
wall: { mean, median, p95, max } | null } // null unless from run()
```
Times are milliseconds. `share` is the fraction of the frame the phase or pass took.
### `Benchmark.format(report)` → `string`
A report as a table to print, ending with what the frame is bound by: CPU, GPU, or waiting for the
display.
## Environment and HDR
### `new Environment(gpu, options)` → `Environment`
A baked lighting environment: diffuse ambient light, reflections, and the background. Baked once, from a procedural sky or from an equirectangular HDR map. Most code gets one from [`engine.loadEnvironment`](#engine-loadenvironment) or uses `engine.environment`; construct one directly for a custom sky.
| Option | Default | Meaning |
|---|---|---|
| `size` | `128`; with a map, the power of two at or below map width / 4 | Edge of the sky cube and reflection cube, in texels. A power of two. |
| `irradianceSize` | `32` | Edge of the diffuse-light cube. A power of two. |
| `prefilterMips` | `6` | Roughness levels for reflections, capped by the cube's mip count. |
| `label` | `'env'` | GPU label prefix. |
| `sky` | the default sky | Procedural sky settings, merged over the defaults below. Ignored when `map` is given. |
| `map` | `null` | An equirectangular panorama, `{ width, height, data }` with `data` as linear RGB floats, as [`parseHDR`](#parsehdr) returns. Its centre faces +X and its top row is straight up. |
`sky` fields (all colours linear):
| Field | Default | Meaning |
|---|---|---|
| `ground` | `[0.10, 0.09, 0.08]` | Colour below the horizon. |
| `horizon` | `[0.62, 0.66, 0.74]` | Colour at the horizon. |
| `zenith` | `[0.16, 0.30, 0.60]` | Colour straight up. |
| `sun` | `[0.35, 0.55, 0.45]` | Direction toward the sun disc (normalised for you). |
| `sunColor` | `[1.0, 0.93, 0.80]` | Colour of the disc and its glow. |
| `sunIntensity` | `60` | Brightness of the disc. `0` removes it. |
| `glow` | `0.5` | Brightness of the halo around the disc. `0` removes it. |
Properties: `size` (cube edge), `prefilterMips`, `sky` (the merged settings). Method: `destroy()`.
Throws: `'Environment: map needs width, height and width * height * 3 floats of RGB'`; `RangeError` `'Environment: a WxH map is past this device's N'`; `RangeError` `'Environment: size N is past this device's M'`.
```js
import { Environment } from 'winding-engine';
const dusk = new Environment(engine.gpu, {
sky: { zenith: [0.05, 0.08, 0.2], sun: [0.9, 0.1, 0], sunIntensity: 30 },
});
const scene = engine.createScene({ environment: dusk });
```
Notes: the sky lights the scene only through ambient light and reflections; its sun disc casts no shadow. For sunlight and shadows, add a directional light shining along the opposite of `sun`. Settings are read once at bake time; changing `sky` afterwards does nothing. An environment belongs to the engine whose `gpu` made it. Free it with [`engine.unload`](#engine-unload) once no scene uses it.
### `parseHDR(bytes, { maxDimension })` → `{ width, height, data }`
Decodes a Radiance `.hdr` (RGBE) file to linear RGB floats, top row first. [`engine.loadEnvironment`](#engine-loadenvironment) calls it for you; use it directly to inspect or edit a map before building an [`Environment`](#environment).
`bytes` is the file, as a `Uint8Array` or an `ArrayBuffer`.
| Option | Default | Meaning |
|---|---|---|
| `maxDimension` | `Infinity` | Refuse a map wider or taller than this before decoding it. Pass `engine.gpu.limits.maxTextureDimension2D`. |
Returns: `{ width, height, data }`, with `data` a `Float32Array` of 3 floats a pixel. Any `EXPOSURE=` header is divided out.
Throws: `'hdr: not a Radiance file…'`; `'hdr: the header never ends'`; `'hdr: FORMAT=… is not supported; only 32-bit_rle_rgbe is'`; `'hdr: EXPOSURE=… is not a positive number'`; `'hdr: only -Y h +X w and +Y h +X w orientations are supported'`; `'hdr: a WxH image has no pixels'`; `'hdr: a WxH map is past this device's N'`; `'hdr: the pixel data ends early'`; `'hdr: a run is longer than its scanline'`; `'hdr: a repeat with no pixel before it'`.
```js
const bytes = new Uint8Array(await (await fetch('sky.hdr')).arrayBuffer());
const map = parseHDR(bytes, { maxDimension: engine.gpu.limits.maxTextureDimension2D });
const sky = new Environment(engine.gpu, { map, size: 256 });
```
## Colour helpers
3D colours in Winding are linear light. Colour pickers, hex codes and CSS values are sRGB. These convert sRGB to linear for 3D. 2D colours (anything seen through a `Camera2D`) are already sRGB and need no conversion. Alpha is never converted.
A light's colour may exceed 1: convert the colour, then multiply by the brightness you want.
### `srgbToLinear(c)` → `number`
One channel, sRGB (0–1) to linear.
```js
srgbToLinear(0.5); // 0.214
```
### `linearToSrgb(c)` → `number`
One channel, linear back to sRGB (0–1).
```js
linearToSrgb(0.214); // 0.5
```
### `colorFromHex(hex)` → `[r, g, b, a]`
A hex colour as linear RGBA. Takes 3, 4, 6 or 8 digits, with or without `#`. Alpha is `1` when not given.
Throws: `'colorFromHex: "" is not a 3, 4, 6 or 8 digit hex colour'`, for a number as well: `0xff0000` is written `'#ff0000'`.
```js
colorFromHex('#e03a2f'); // [0.745, 0.042, 0.028, 1]
colorFromHex('#e03a2f80'); // alpha 0.502
```
### `colorFromBytes(r, g, b, a)` → `[r, g, b, a]`
0–255 sRGB channels, as a colour picker gives them, as linear RGBA. `a` defaults to `255`.
```js
const sun = colorFromBytes(255, 240, 220).slice(0, 3).map((c) => c * 3);
```
Notes: returns a plain array, so it survives `JSON.stringify`.
## Math
Exported from `'winding-engine'`. Plain functions over typed arrays. Every function that produces a vector, quaternion or matrix writes into `out` first and returns it. Passing the same array as `out` and an input is safe. Only the `*Create` functions allocate.
### vec3
A vec3 is a `Float32Array(3)` (any array of 3 numbers works as input).
| Function | What it does |
|---|---|
| `vec3Create(x = 0, y = 0, z = 0)` | A new `Float32Array(3)`. Allocates. |
| `vec3Set(out, x, y, z)` | Sets `out` to `x, y, z`. |
| `vec3Copy(out, a)` | Copies `a` into `out`. |
| `vec3Add(out, a, b)` | `a + b`. |
| `vec3Sub(out, a, b)` | `a - b`. |
| `vec3Mul(out, a, b)` | Component-wise `a * b`. |
| `vec3Scale(out, a, s)` | `a * s`. |
| `vec3ScaleAndAdd(out, a, b, s)` | `a + b * s`. |
| `vec3Negate(out, a)` | `-a`. |
| `vec3Dot(a, b)` | The dot product. Returns a number. |
| `vec3Cross(out, a, b)` | The cross product `a × b`. |
| `vec3LengthSq(a)` | Squared length. Cheaper than `vec3Length` for comparisons. |
| `hypot3(x, y, z)` | `sqrt(x² + y² + z²)`: a faster `Math.hypot` for three numbers. |
| `vec3Length(a)` | Length. |
| `vec3DistanceSq(a, b)` | Squared distance between two points. |
| `vec3Normalize(out, a)` | Unit length. A zero vector gives zero, not NaN. |
| `vec3Lerp(out, a, b, t)` | Linear blend: `a` at 0, `b` at 1. |
| `vec3Min(out, a, b)` | Component-wise minimum. |
| `vec3Max(out, a, b)` | Component-wise maximum. |
| `vec3TransformMat4(out, a, m)` | Transforms a point (w = 1), with perspective divide. |
| `vec3TransformMat4Dir(out, a, m)` | Transforms a direction (w = 0): no translation. |
| `vec3TransformQuat(out, a, q)` | Rotates by a quaternion. |
### quat
A quaternion is a `Float32Array(4)`, `[x, y, z, w]`.
| Function | What it does |
|---|---|
| `quatCreate()` | A new identity quaternion. Allocates. |
| `quatIdentity(out)` | Sets `out` to the identity. |
| `quatCopy(out, a)` | Copies `a` into `out`. |
| `quatSetAxisAngle(out, axis, rad)` | A turn of `rad` radians about a unit `axis`, right-hand rule. |
| `quatMultiply(out, a, b)` | `a * b`: `b` applies first, then `a`. |
| `quatDot(a, b)` | The 4D dot product. Returns a number. |
| `quatConjugate(out, a)` | The conjugate: the inverse, for a unit quaternion. |
| `quatNormalize(out, a)` | Unit length. A zero quaternion gives the identity. |
| `quatFromEuler(out, yaw, pitch, roll)` | From radians, YXZ order: roll about Z, then pitch about X, then yaw about Y. There is no inverse. |
| `quatFromMat4(out, m, mOff = 0)` | The rotation of a matrix's upper 3×3, which must have no scale. |
| `quatSlerp(out, a, b, t)` | Spherical blend at constant angular speed, the short way round. |
| `quatFromTo(out, from, to)` | The shortest turn taking unit vector `from` onto unit vector `to`. |
| `quatLookAlong(out, direction, up = [0, 1, 0])` | Points -Z along `direction` with +Y as upright as it can be. `direction` need not be unit length. |
### mat4
A matrix is a column-major `Float32Array(16)`. The optional `*Off` arguments address a matrix or vector inside a larger array.
| Function | What it does |
|---|---|
| `mat4Create()` | A new identity matrix. Allocates. |
| `mat4Identity(out)` | Sets `out` to the identity. |
| `mat4Copy(out, a, outOff = 0, aOff = 0)` | Copies `a` into `out`. |
| `mat4GetTranslation(out, m)` | Writes `m`'s translation into vec3 `out`. |
| `mat4Multiply(out, a, b, outOff = 0, aOff = 0, bOff = 0)` | `a * b`: applied to a vector, `b` happens first. |
| `mat4MultiplyAffine(out, a, b, outOff = 0, aOff = 0, bOff = 0)` | `a * b` for matrices whose bottom row is `0, 0, 0, 1` (translation, rotation, scale). Faster; wrong for projections. |
| `mat4FromQuatPosScale(out, q, pos, scale, outOff = 0, qOff = 0, posOff = 0, scaleOff = 0)` | Builds translation × rotation × scale. |
| `mat4Invert(out, a)` | The inverse. Returns `null`, leaving `out` untouched, if the determinant is exactly zero. |
| `mat4LookAt(out, eye, center, up)` | A right-handed view matrix looking from `eye` toward `center`, down its -Z. |
| `mat4NormalMatrix(out, m, outOff = 0, mOff = 0)` | The inverse transpose of the upper 3×3, written as a WGSL `mat3x3` (3 columns padded to 4 floats). Returns `false` for a singular matrix, else `true`. |
| `mat4Decompose(outPos, outRot, outScale, m, mOff = 0)` | Splits into translation, rotation and scale. Shear is lost. Returns `false`, leaving the outputs untouched, if an axis has zero scale. |
| `mat4OrthographicReverseZ(out, left, right, bottom, top, near, far)` | An orthographic projection for WebGPU, reverse-Z: `near` maps to depth 1, `far` to 0. |
| `mat4PerspectiveReverseZInfinite(out, fovYRadians, aspect, near)` | A perspective projection for WebGPU, reverse-Z with no far plane. Use with `depthCompare: 'greater'` and a depth clear of 0. |
### aabb
A box is a pair of vec3s, `min` and `max`. An empty box has `min` at `+Infinity` and `max` at `-Infinity`.
| Function | What it does |
|---|---|
| `aabbTransform(outMin, outMax, min, max, m, mOff = 0, outOff = 0, inOff = 0)` | The smallest axis-aligned box holding the box transformed by `m`. An empty box stays empty. Returns nothing. |
| `aabbBoundingSphere(outCenter, min, max)` | Writes the box's centre into `outCenter` and returns the radius of the sphere around it. |
| `aabbUnion(min, max, otherMin, otherMax)` | Grows `min`/`max` in place to hold the other box. Returns nothing. |
| `aabbSetEmpty(min, max)` | Makes the box empty. Returns nothing. |
| `aabbRayDistance(min, max, origin, direction, boundsOff = 0)` | Distance along a ray to where it enters the box: `0` if the origin is inside, `-1` for a miss. Does not check the ray is finite. |
| `rayTriangleDistance(origin, direction, positions, a, b, c)` | Distance along a ray to a triangle, from either side, or `-1` for a miss. `a`, `b`, `c` index flat xyz `positions`, so pass `index * 3`. The distance is in units of `direction`'s length. |
## Renamed in 1.0
Names that changed in 1.0, for code written against 0.x. A renamed option, and each of the four properties with an entry here, throws saying what it is called now; a renamed method is simply gone, and calling it says it is not a function.
| Was | Is |
|---|---|
| `engine.run({ scene, camera, update, frame, overlay })` | [`engine.run(scene, camera, { update, frame, hud })`](#engine-run) |
| `overlay` (in `run` and `renderFrame`) | `hud` |
| `engine.stats.overlay2D`, `overlay2DWritten` | [`hudSprites`, `hudSpritesWritten`](#engine-stats) |
| a sprite's `rotation` | [`angle`](#scene-addsprite) |
| `addReflectionProbe`, `setReflectionProbe`, `reflectionProbeOf`, `engine.captureReflectionProbes` | [`addProbe`](#scene-addprobe), [`setProbe`](#scene-setprobe), [`probeOf`](#scene-probeof), [`engine.captureProbes`](#engine-captureprobes) |
| a probe's `min` and `max`; its `blend` | `position` and `size`; `fade` |
| `play({ add })` | [`play({ join })`](#node-play) |
| `scene.advanceAnimations(dt)`, `scene.advanceParticles(dt)` | [`scene.advance(dt)`](#scene-advance) |
| `node.setRotationAxisAngle`, `node.setRotationEuler`, `node.getWorldPosition` | [`setAxisAngle`](#node-setaxisangle), [`setEuler`](#node-seteuler), [`worldPosition`](#node-worldposition) |
| `node.setLight(changes)` | [`scene.setLight(node, changes)`](#scene-setlight) |
| `scene.playerFor(node)` | [`node.animation`](#node-animation) |
| text's `anchor`; Camera2D's `anchor` | `pivot`, from the top-left |
| an emitter's `size: [birth, death]` | `size` and `sizeEnd` |
### `engine.rhi`
Now [`engine.gpu`](#engine-gpu). Reading or assigning `engine.rhi` throws `'engine.rhi is now engine.gpu'`.
### `camera.rotation` (Camera2D)
Now [`camera.angle`](#camera2d-angle). Reading or assigning it throws.
### `engine.renderer.drawSkybox`
Now [`engine.renderer.skybox`](#renderer-skybox). Reading or assigning it throws.
### `engine.renderer.post.requestedLevels`
Now [`engine.renderer.post.levels`](#post-levels); what the last frame drew is `post.levelsDrawn`. Reading or assigning it throws.