@driftengine/core 4.8.6 → 4.9.0

package/CHANGELOG.json

@@ -1,4 +1,136 @@
 [
+  {
+    "version": "4.9.0",
+    "date": "2026-10-07",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "`screenSpaceReflections`: every opaque lit surface reflects the frame by its own material, the probe's share swapped for what a ray finds, softened by roughness and left to the probes past a ceiling.",
+        "text": "A renderer built with `screenSpaceReflections` reflects the frame in every opaque lit surface by that surface's own material, where `ReflectiveSurface` reflects it by a box's. The lit stage leaves, per pixel, how much of the environment it showed and the tint a reflection lands with; the screen-space trace gains a material mode that marches every such pixel against the frame's depth and swaps the probe's share for what it finds. The swap is exact because the lit stage's blend is a mix: the frame holds the environment times the tint times the weight, and a found reflection belongs there with the same tint and weight, so nothing else in the pixel moves. A rougher surface shows a softer reflection, blurred by its roughness, and past `maxRoughness` it keeps the probes' reflection alone. One floor mesh with one ORM map therefore mirrors the figures standing on its glossy panels and barely shows them on its matte ones. What a surface reflects is what the lit stage already reflected: a metal by its metalness, a dielectric where `setSurfaceReflectivity` or its material asks. `true` takes `DEFAULT_FRAME_REFLECTIONS`; a `FrameReflections` sets the ceiling, the march and the blur. WebGPU writes the two maps by replaying the opaque lit draws without their lamps, since a second attachment on the frame's pass would bind every pipeline in it; WebGL2 writes them beside the colour, enabled around the opaque lit draws alone and behind a lit switch, so a renderer without the option carries nothing for it. It needs `screenEffects`, `hdrScene` and one sample, and says so once where it has none. On `demo/dev/frameReflections.html` the trace moves 30,138 floor pixels and none above them, a ceiling below every stripe matches the frame without the trace to the pixel, and the two backends differ by 41 pixels."
+      },
+      {
+        "kind": "added",
+        "short": "`setSurfaceOverlay` lays a rim of light, a dissolve with a glowing edge and wrinkle normals by six region weights over a draw's materials, its images regions of one atlas.",
+        "text": "`renderer.setSurfaceOverlay(overlay)` lays something over the surfaces of the draws that follow, beyond their materials, so one character's whole set of materials changes together while another's does not; per draw, reset by `bindMeshPass`. A `rim` glows along the silhouette: an edge `(1 - N·V)^falloff` leaning toward normals that face up, raised to a contrast, times a noise laid in screen space and scrolled on the environment's `surfaceTime`, a slow pulse and a mask in the mesh's uv, added to emission and not gated on the night. A `dissolve` cuts the surface away where a noise in its uv falls under a threshold, with a glowing band at the edge and a colour laid through the same noise. A `wrinkle` blends a second normal map into the surface's by six region weights read through two masks. Every image is a region of one atlas (`OverlayRegion`), read in the slot the frame's refraction copy takes, which an opaque surface never reads; a draw that refracts keeps its refraction and reads none of the overlay's images, and says so once. A lit switch, off until an overlay is set. WebGL2 carries the overlay's fifteen uniform vectors where its device has room and refuses it in words where it does not, as on a 256-vector part at the eight-light budget, and reads a compressed atlas as none. On `demo/dev/surfaceOverlay.html` every control moves only the object it names, and the two backends agree to the pixel."
+      },
+      {
+        "kind": "added",
+        "short": "`outputTransform: 'filmic'` and `setFilmicCurve`: a film curve shaped by five numbers that holds mid grey at mid grey, applied by the composite.",
+        "text": "`outputTransform: 'filmic'` is a film curve in the ACEScg working space: a straight segment through mid grey meeting a soft toe below and a shoulder above, shaped by a slope, a toe, a shoulder and two clips, with the ACES reference's glow and red modifier around it. `setFilmicCurve` sets the numbers and a renderer starts with `DEFAULT_FILMIC_CURVE`; a curve that runs backwards or divides by zero is clamped and said once rather than refused. 0.18 of scene light comes out at 0.18, where `'aces'` gives about 0.11: 118 of 255 on both backends, and every one of sixteen grey and colour patches agrees with a consumer's own transcription of the reference. It is the composite's, so it needs `screenEffects` and `hdrScene`; without them every pass grades with `'aces'` and the renderer says so once. Bound to DriftScript as `drift/render.filmic`."
+      },
+      {
+        "kind": "added",
+        "short": "`highDynamicRange` draws to a display's own range on WebGPU, `displayRange` says which range the frame went out in, and `setDisplayLuminance` lets highlights reach the display's peak.",
+        "text": "`highDynamicRange: true` asks for a canvas whose highlights run past paper white as far as the display can show. It is had where the renderer is on WebGPU, the frame keeps its light past white (`screenEffects` and `hdrScene`) and the display reports a high range: the canvas is configured `rgba16float` with extended tone mapping and read back to confirm it. `renderer.displayRange` says which range the frame goes out in, `'high'` or `'standard'`, and `displayRangeReason` says why; WebGL2 draws into an eight-bit canvas and always answers `'standard'`. `setDisplayLuminance(paperWhite, peak)` gives the ratio highlights may reach: paper white stays where it was and so does everything below it, the filmic shoulder rolls off toward the peak, and a colour grade colours a highlight without clipping it back to white. On a standard display it changes nothing. A host without a browser display query answers it with `createRenderer`'s `highDynamicRangeDisplay`."
+      },
+      {
+        "kind": "added",
+        "short": "`setCameraMotionBlur(scale, maxShare)` blurs each drawn object by its own motion under DriftTR on WebGPU: a mover smears while the still stage behind it stays sharp.",
+        "text": "Camera motion blur now reads each pixel's motion from the reconstruction's motion target, so a mover with a previous placement or pose smears along its own path while the stage standing still behind it does not, and `setCameraMotionBlur` takes a maximum as a share of the frame. On `demo/dev/objectBlur.html` a box crossing a still camera's view smears 8 pixels, 1 with the blur off, 5 capped. It is WebGPU's under DriftTR alone, since that is where per-object motion is kept; WebGL2, and WebGPU without reconstruction, blur by the camera's motion alone and say so once when given a mover."
+      },
+      {
+        "kind": "added",
+        "short": "`setChromaticAberration(intensity, start)` pulls the colour channels apart toward the frame's edges past a start radius, at three wavelengths, on both backends.",
+        "text": "`setChromaticAberration(intensity, start)` is a lens fringe in the composite: the three channels sampled apart toward the frame's edges, scaled by their wavelengths, from a start radius outward, so the middle of the frame is untouched. Held until changed; 0 is none. On `demo/dev/toneCurve.html?fringe=` it moves 13,480 pixels, none inside the start, and the two backends agree. It needs `screenEffects`, and says so once."
+      },
+      {
+        "kind": "added",
+        "short": "`Atmosphere.fogStart` keeps the exponential fog's first metres clear, integrated along each ray's own path in the lit stage and the GPU-driven pipeline alike.",
+        "text": "`Atmosphere.fogStart` holds the exponential height fog off for its first metres: the medium begins where the ray has travelled that far, integrated along the ray's own path, so a stage reads clear up close and hazes with distance as a fog start does in a scene authored elsewhere. 0, or absent, is the fog as before. On `demo/dev/fogStart.html` the measured columns match values worked by hand on both backends, and the GPU-driven pipeline's fog takes it too."
+      },
+      {
+        "kind": "added",
+        "short": "A registered pass reads the frame: `reads: ['colorSnapshot']` hands it the colour drawn so far as `sceneColor`, beside the depth's `sceneDepth`, on both backends.",
+        "text": "A pass that declares `reads: ['depthSnapshot']` is handed the frame's depth as `sceneDepth` — in the `PrepareContext` on WebGPU, an `r32float` texture, and in the `PassContext` on WebGL2 — and one that declares `reads: ['colorSnapshot']` the colour with everything drawn before it as `sceneColor`, copied afresh at each such pass's draw. A distortion samples the scene behind it with it; a full-screen pass drawn last reads the whole frame and writes over it in scene light, before the tone curve. Under DriftTR the pass runs after the upscale over a copy of the reconstructed frame. On `demo/dev/framePass.html` a pass inverting the frame reads the same values on both backends, with multisampling too."
+      },
+      {
+        "kind": "changed",
+        "short": "The worker factories are at declared subpaths, `@driftengine/assets/bcWorkers` and `@driftengine/physics/workers`, where a bundler and Node can both find them.",
+        "text": "`spawnBcWorker` and the physics island pool's `createIslandPool` were reached by a path into a package's `src`, which a published package's `exports` does not have to allow and a strict resolver refuses. Each now has a subpath of its own in its package's `exports`, `@driftengine/assets/bcWorkers` and `@driftengine/physics/workers`, built to `dist` like the barrels, and the messages that name them say so. The barrels still do not reach them, which is what keeps a worker out of a game that never names one."
+      },
+      {
+        "kind": "fixed",
+        "short": "A scene capture or a probe bake inside a frame no longer turns that frame black on WebGPU, nor switches off its skin spread, nor steps the temporal jitter twice.",
+        "text": "Three defects at the boundary a capture or a probe bake opens in the middle of a frame. On WebGPU, `captureScene` and `bakeProbe` saved the open pass before flushing the frame graph, which opens the frame's pass, so a capture after any draw restored the wrong pass and the frame came out black. On both backends, the latch that spreads skin once a frame was set before the check that refuses a mirror, a probe or a capture, so a blended draw inside a capture switched the frame's skin spread off. And the temporal history stepped its jitter each time the camera was bound rather than once a frame, so a frame that bound it twice drew two frames' jitter. Each has a test, and `scripts/capture-check.mjs` captures at the start of a frame, among its draws and at its end, against controls taken the same way."
+      },
+      {
+        "kind": "fixed",
+        "short": "WebGPU asks a device for the textures and samplers the environment probe's widest lit variant really binds, sixteen and twelve, counted from the generated bindings.",
+        "text": "The check that decides whether a device can build the environment probe's permutation compared its limits against seven sampled textures and four samplers, typed when the probe was added. The widest lit variant had since grown to sixteen and twelve with the material maps, glass, the fixture atlas and DriftLight, so a device under those would have been admitted to a permutation it cannot bind. The counts now come from the generated bindings, a shared sampler counted once."
+      }
+    ]
+  },
+  {
+    "version": "4.8.7",
+    "date": "2026-10-06",
+    "entries": [
+      {
+        "kind": "changed",
+        "short": "A lightmap page is 8 bytes a texel, half what it was: the irradiance is an rgb9e5 word the lit stage decodes and filters, and a bake that arrives packed uploads where it lies.",
+        "text": "`createLightmap` stored a page as two half-float layers, 16 bytes a texel, so a stage of 49 pages and 21.8 million texels took 348 MB on the device. The irradiance is now one rgb9e5 word a texel, three 9-bit mantissas over a shared 5-bit exponent in the layout of `EXT_texture_shared_exponent` and WebGPU's `rgb9e5ufloat`, beside the direction's four bytes, in two `rgba8` layers that the lit stage decodes and filters itself: 8 bytes a texel, 174 MB for the same stage. `LightmapPage.irradiance` takes a `Uint32Array` of packed words as a bake hands them over, uploaded where they lie with no float array in between, as well as floats, which are packed once at upload. What it gives up is precision in a texel's smaller channels, which share the largest one's exponent, and anything past 65,408; light has neither to lose. On `demo/dev/lightmap.html` a page of one value is still 0 pixels from the same ambient raised by `setAmbientSH`, and the room is within one level of 4.8.6's on both backends."
+      },
+      {
+        "kind": "changed",
+        "short": "The BC decode worker is behind its own specifier, so a game importing `@driftengine/assets` no longer has it in its build: name `spawnBcWorker` as `DrftLoader`'s `bcWorker` to decode in it.",
+        "text": "`DrftLoader` decoded a BC texture the device cannot take as blocks in a worker it built with `new Worker(new URL('./bcWorker.ts', import.meta.url))` inside the package's barrel, and a bundler writes that worker out at transform time, before tree-shaking, so every game importing anything from `@driftengine/assets` carried the BC decoder's chunk from 4.8.4 on, whether or not it loaded a BC texture. The gate that asserts no barrel names a worker bundled each barrel against the built packages and skipped one that would not bundle, so it saw this one only when another test's `npm pack` had built them first, which is how it passed three releases. The factory is now `spawnBcWorker` at `@driftengine/assets/src/bcWorkers.ts`, as the physics island pool is, and a loader takes it as `bcWorker`; without it BC textures decode on the main thread and the loader says so once, naming the option. The gate bundles from source now. Every scene and page in this repository that loads a model names the worker."
+      },
+      {
+        "kind": "added",
+        "short": "`PointLightSource.falloffExponent` lights by `(1 - (d/R)^2)^n` with no distance term, Unreal's falloff for a light without inverse square, in both arms and on water, DriftLight and DriftRay.",
+        "text": "A point or spot light may name its own falloff: `(1 - (d/R)^2)^n` with `R` its radius and `n` the exponent, and no inverse square, which is how Unreal lights a light that does not use inverse-square falloff. A rig authored there keeps its shape: a fill meant to light a whole hall across a hundred metres does, where the frame's falloff had it gone a few metres out. 0, or absent, is the frame's falloff as before. The selection carries it in `PointLightBuffer.falloffExponents` and the environment in `lightFalloffExponents`; the fixed arm reads it in the third lane of the cone uniform, which a two-float array already paid a whole row for, so the eight-light build spends no uniform row on it, and the froxel table's record grows to six texels. Water, DriftLight's volume and DriftRay's bounce fall off by it too, so a light lands the same way on every surface it reaches. On `demo/dev/clustered.html` one light drawn by the fixed arm and by the table is 0 pixels apart on both backends, and an exponent of 8 moves 42,123 pixels against none."
+      },
+      {
+        "kind": "added",
+        "short": "`AreaLightSource.barnDoorAngle` and `barnDoorLength` hang barn doors on a rectangle: each fragment is lit by the part the doors leave in view, its highlight included, in both arms.",
+        "text": "A rectangle may carry barn doors, a flap hinged at each edge standing `barnDoorAngle` degrees from its normal and `barnDoorLength` metres long, 20 cm when absent, as Unreal's rect lights do. At 90 they fold flat and hide nothing; smaller narrows the light to the opening they leave. Each fragment shades the part of the rectangle no door's tip hides, one axis at a time, so the form factor and the integrated highlight both come from that smaller rectangle, in the fixed arm, which reads the doors in the size uniform's two spare lanes, and in the froxel table's record. Each door is taken as endless along its hinge, so where two meet the corner they hide is square rather than mitred, and a shadowed rectangle's map is still baked from its whole face. Measured from straight above a 1.2 by 0.5 m panel 1.2 m over a floor with 20 degree, 30 cm doors: nothing changes within the 1.04 by 0.69 m box the door tips leave whole, nothing is lit past 4.94 and 2.32 m where they hide all of it, the fixed and clustered arms are 0 pixels apart, and doors at 90 degrees are 0 pixels from none, on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`SurfaceMaterial.physicalSpecular` shades a lamp's and the sun's highlight as GGX's own `pi D Vis F N.L` with the specular attribute as F0, on the standard, lightmap and anisotropic models.",
+        "text": "The engine's highlight is a look control: it peaks at the specular attribute times one however rough the surface, so strength and width are set apart. A material with `physicalSpecular: true` takes GGX's own term instead, `pi * D * Vis * F * N.L` with Smith's height-correlated masking, as Unreal shades and as this engine's skin and eye already did. Its peak is `1 / (4 alpha^2)` of the light head-on, so a polished surface's highlight is several times the look's and a rough one's lower and wider; the specular attribute is read as the reflectance at normal incidence, Unreal's `0.08 * Specular`, and Fresnel brightens every surface toward grazing rather than a metal alone. Lamps, widened by their size as before, and the sun take it, on the standard, lightmap and anisotropic models; a rectangle's highlight was already the lobe integrated over it with that F0. The code is a lit switch, compiled into the lit programs the first time a material asks, so a scene that never does carries none of it. Measured with a lamp and an eye mirrored about a floor at roughness 0.5, where the term works out by hand to 4.4376: the physical highlight at 1/4.4377 of the light reads the look's middle pixel to within a level on both backends, from a lamp and from the sun, and the anisotropic model's physical lobe at strength 0 is the standard one to within a level everywhere."
+      },
+      {
+        "kind": "added",
+        "short": "`ReflectiveSurface.fresnel` reads `strength` as the surface's reflectance head-on and weighs each pixel by the split-sum BRDF at its view and `roughness`, so a reflection follows the camera.",
+        "text": "A screen-space reflection's `strength` was one share over its box, so a floor reflected as much underfoot as toward the horizon and a consumer re-matched the share to its camera's angle each frame. With `fresnel: true` the strength is the surface's reflectance head-on and each pixel returns `F0 * A + B` of what its ray finds, the split-sum environment BRDF at its own view and the box's `roughness`: Karis's fit, now one GLSL text that the lit stage and the reflection pass both include. The pass reads no material, so the reflectance and roughness are the box's, and nothing occludes the reflection where the lit stage's ambient occlusion would. Off by default, the one share as before. Measured on `demo/dev/ssr.html`: at a reflectance of 1 and roughness 0 it is 0 pixels from a strength of 1, as the fit says, and at a pixel whose view works out by hand to N.V 0.344, reflectance 0.04 matches the constant strength the fit gives there, 0.153, to within a level on both backends."
+      },
+      {
+        "kind": "added",
+        "short": "`MeshInstances.uvRegions` gives each instance its own cell of its texture, so mesh particles on different flipbook frames, or props on different tiles of an atlas, are one draw.",
+        "text": "Four floats an instance, `[scaleU, scaleV, offsetU, offsetV]`, applied to the mesh's texture coordinates before the material's own scale and offset, in the lit, depth and motion stages alike, so a cutout instance's shadow is cut by its own cell. They ride the bottom row of the instance's matrix, which a placement made of a turn, a scale and a move leaves at `[0, 0, 0, 1]` and which every stage drawing an instance now rebuilds as that, so they cost no attribute and no byte; an instanced placement must be affine, as every placement of a solid object is. Absent, every instance wears the whole texture, and a culled copy carries the cells into a target that has the array. On `demo/dev/instanceCells.html` eight cards each on their own cell of a strip, in one instanced draw, are 0 pixels from eight single draws with the cell in their materials, opaque and blended, on both backends; the published scenes and the instanced shadow, cull and opacity pages are 0 pixels from 4.8.6 on WebGPU."
+      },
+      {
+        "kind": "added",
+        "short": "`createSceneCapture` and `captureScene` draw the world from a camera of your own into a texture any material shows, a stadium screen's emissive or a monitor's, on both backends.",
+        "text": "`createSceneCapture(width, height)` makes a texture the scene can be drawn into, and `captureScene(capture, camera, clearColor, draw)` draws it: the callback is handed the camera, its matrices shaped to the capture, and submits the world exactly as it would to the screen. The texture then goes wherever an image goes, as a material's `emissive` for a screen in the world showing what another camera sees, a monitor or a security feed. It holds radiance, as a reflection probe does: the output transform and exposure are held off for the pass, at the world's colour format and sample count, half floats under `hdrScene`, so the frame grades the screen once with everything around it. It is the probe bake's arrangement and the mesh pass alone: the sky, water and particles are in it only if the callback draws them, nothing after the world runs on it, it has no mip chain, and the frame's camera, jitter, motion, refraction copy and skin spread are left alone while it draws. WebGL2 draws a capture's rows flipped, as it does a probe face's, so it reads as an image does. A second camera's view shown on a quad filling the frame is 0 pixels from that view drawn directly, single-sampled on both backends and at four samples on WebGPU, where WebGL2's multisampled capture is WebGPU's to the pixel; and a frame with a capture in it is 0 pixels from the frame without one outside the screen."
+      },
+      {
+        "kind": "added",
+        "short": "`drawDeviceParticles` draws a particle pool's material from a buffer your own compute shader wrote, where it lies, with nothing read back. WebGPU only; WebGL2 says so once.",
+        "text": "A simulation can run entirely on the device: a compute shader of the consumer's own, registered with `registerCompute`, writes its particles into a buffer of its own, and `drawDeviceParticles(batch, { buffer, count }, camera, env, time)` draws the pool's material, blend, flipbook, fades and fog from that buffer in place of the one the pool uploads into. Each particle is `DEVICE_PARTICLE_FLOATS`, sixteen floats in a `ParticleInstances`' order, and the buffer needs `VERTEX` usage beside `STORAGE`; a slot of half-width 0 draws nothing, so a fixed-size buffer can hold fewer live particles than it has room for, and a count past what the buffer holds is cut to it. The particles are not sorted. WebGL2 has no compute stage, so there it says so once and draws nothing. On `demo/dev/spriteParticles.html` sixteen sprites written by a compute shader are 0 pixels from the same sixteen uploaded, soft edges included."
+      },
+      {
+        "kind": "fixed",
+        "short": "A skin's `radius` is how far its light travels, as documented: the profile is at two fifths of it, so screen-space skin no longer smears a face seen up close over tens of pixels.",
+        "text": "`skinModel`'s `radius` was documented as how far light travels beneath the surface before it leaves, and was handed to Burley's profile as its distance `d` itself. That profile carries light 2.5 `d` on average and the blur's taps reach 9 `d`, so light travelled two and a half times as far as the model said, and `skinScattering: 'screen-space'` spread a face at arm's length over sixty pixels: a nose, lips and brows washed into one blur. The profile is now at `radius / 2.5` in both paths, the screen-space blur and the lit stage's pre-integrated fit, transmission and penumbra, so the two still agree. Measured first rather than assumed: on a step of light at 0.75 m and 800 by 600, the blur matched the profile's own masses at the old distance exactly, edges at the predicted taps, so the kernel was right and the distance was not; it now reaches 26 pixels where it reached 65, on both backends. A skin authored against the old meaning and looking right keeps its look with its `radius` raised by 2.5."
+      },
+      {
+        "kind": "fixed",
+        "short": "The anisotropic model on a mesh with neither tangents nor texture coordinates drew black, a direction normalised from zero; it takes a direction in the surface now.",
+        "text": "A brushed surface takes its direction from the tangent frame, and a mesh carrying neither tangents nor coordinates gives a frame of zeros, which normalised to a NaN and drew the whole surface black. It takes a direction in the surface's plane instead, across the world's up, so the highlight is stretched somewhere. Measured on a floor with no coordinates: the anisotropic model at strength 0 draws the standard highlight to within a level on both backends, where it drew nothing."
+      },
+      {
+        "kind": "fixed",
+        "short": "Arcs stay finite under multisampling: an edge pixel shaded off the quad took the filament's side coordinate past one and its powers to NaN, which bloom spread into a white disc.",
+        "text": "A multisampled target shades a pixel on a quad's edge at its centre, which can lie outside the quad. There an arc's side coordinate ran past one, the filament's `across` went negative, and `pow` of a negative number is NaN on both backends: one dark speck, which bloom then spread into a white disc the size of its blur around every arc. `across` is clamped before its powers. Found by a scene drawing short arcs at four samples."
+      },
+      {
+        "kind": "note",
+        "short": "The lit stage carries the falloff exponent and barn doors in every permutation: 2.8 to 6.4% more instructions on RADV at a phone's viewport, and the same registers.",
+        "text": "What every lit pipeline now compiles was measured on RADV with a phone's viewport, against 4.8.6: the fixed-arm lit pixel shader is 5,778 instructions where it was 5,618 on WebGPU and 5,171 where it was 4,989 on WebGL2, both still 96 registers; the clustered one is 6,831 where it was 6,507 and 6,313 where it was 5,934, still 120 and 108. Registers set how many fragments a phone's GPU keeps in flight, and they did not move. The physical highlight is a lit switch and costs nothing until a material asks for it. Core's gzipped size is 828.1 KB, 29.0 KB over 4.8.6, almost all of it the generated WGSL, whose sixteen lit permutations each carry the new light loop."
+      }
+    ]
+  },
   {
     "version": "4.8.6",
     "date": "2026-10-05",

package/README.md

@@ -6,7 +6,7 @@ carries the loop, the renderer, cameras, input, the scene graph, geometry, text
 and the whole of [`@driftengine/physics`](https://driftengine.dev/docs/simulation/rigid-bodies),
 which it re-exports. The rest of the engine is separate packages you add when you need them.
 
-**Cost: 777.5 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
+**Cost: 858.8 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`,
 which fails the build if the figure drifts by more than 3%.
 
 The manual is at **[driftengine.dev/docs](https://driftengine.dev/docs)**, with an example running

package/dist/index.d.ts

@@ -145,6 +145,8 @@ export { placeCascade } from './render/gi/globalField.ts';
 export type { ReflectionOptions, ReflectiveSample } from './render/gi/reflection.ts';
 export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.ts';
 export type { ColourGradeLut } from './render/colourGrade.ts';
+export { DEFAULT_FILMIC_CURVE } from './render/filmicCurve.ts';
+export type { FilmicCurve } from './render/filmicCurve.ts';
 /**
  * How bloom answers past its threshold — a ramp in place of the subtraction, and a tint for each
  * of the pyramid's `BLOOM_LEVELS` octaves — the third argument of `setBloom`.
@@ -157,6 +159,9 @@ export type { BoltHandle, CausticsHandle, ClothBindingHandle, ClothParticlesHand
 export type { ClothBindingData } from './render/clothBindingData.ts';
 export { anisotropicModel, eyeModel, hairModel, lightmapModel, skinModel, } from './render/surfaceModel.ts';
 export type { AnisotropicModel, EyeModel, HairModel, LightmapModel, SkinModel, SurfaceModel, SurfaceModelKind, } from './render/surfaceModel.ts';
+export { DEFAULT_FRAME_REFLECTIONS } from './render/frameReflections.ts';
+export type { FrameReflections } from './render/frameReflections.ts';
+export type { OverlayRegion, SurfaceDissolve, SurfaceOverlay, SurfaceRim, SurfaceWrinkle, } from './render/surfaceOverlay.ts';
 export { WHOLE_PAGE } from './render/lightmap.ts';
 export type { LightmapPage, LightmapRegion } from './render/lightmap.ts';
 export { createSkinnedCloth } from './render/skinnedClothRun.ts';
@@ -367,8 +372,8 @@ export { seaStateForAgitation, seaStateForWind } from './render/seaState.ts';
 export type { SeaState } from './render/seaState.ts';
 export { InstancedMesh, createInstanceData, writeInstance } from './render/instancedMesh.ts';
 export { createMeshInstances, packInstances, INSTANCE_FLOATS, INSTANCE_STRIDE, } from './render/instances.ts';
-export { ParticlePool } from './render/particlePool.ts';
-export type { ParticlePoolOptions, ParticleInstances } from './render/particlePool.ts';
+export { ParticlePool, DEVICE_PARTICLE_FLOATS } from './render/particlePool.ts';
+export type { DeviceParticles, ParticlePoolOptions, ParticleInstances, } from './render/particlePool.ts';
 export { ParticleBatch } from './render/particleBatch.ts';
 export type { ParticleBatchOptions, ParticleBlend, ParticleFacing, } from './render/particleBatch.ts';
 export { PARTICLE_MOTE_FRAG, PARTICLE_SMOKE_FRAG, PARTICLE_SPARK_FRAG, PARTICLE_VERT, } from './render/shaders/particle.ts';

package/dist/index.js

@@ -209,6 +209,7 @@ export { placeCascade } from './render/gi/globalField.js';
  * take the identity, bend it, hand it back — and because it is what the placeholder is.
  */
 export { GRADE_PLACEHOLDER_SIZE, MAX_GRADE_SIZE, identityGradeLut } from './render/colourGrade.js';
+export { DEFAULT_FILMIC_CURVE } from './render/filmicCurve.js';
 /**
  * How bloom answers past its threshold — a ramp in place of the subtraction, and a tint for each
  * of the pyramid's `BLOOM_LEVELS` octaves — the third argument of `setBloom`.
@@ -221,6 +222,12 @@ export { probeDevice } from './render/backend/probe.js';
  * its own, compiled the first time a draw asks.
  */
 export { anisotropicModel, eyeModel, hairModel, lightmapModel, skinModel, } from './render/surfaceModel.js';
+/*
+ * What a draw lays over its surface beyond its material — a rim of light, a dissolve, wrinkle
+ * normals by region — set per draw with `setSurfaceOverlay`, its images regions of one atlas.
+ */
+/* Every opaque lit surface reflecting the frame by its own material: `screenSpaceReflections`. */
+export { DEFAULT_FRAME_REFLECTIONS } from './render/frameReflections.js';
 /*
  * A baked lightmap: the page a consumer decoded, which `createLightmap` uploads as a lightmapped
  * material's `modelMap`, and the region of it a material or an instance reads.
@@ -474,7 +481,7 @@ export { InstancedMesh, createInstanceData, writeInstance } from './render/insta
  * pitches and rolls and a yaw cannot say so.
  */
 export { createMeshInstances, packInstances, INSTANCE_FLOATS, INSTANCE_STRIDE, } from './render/instances.js';
-export { ParticlePool } from './render/particlePool.js';
+export { ParticlePool, DEVICE_PARTICLE_FLOATS } from './render/particlePool.js';
 export { ParticleBatch } from './render/particleBatch.js';
 export { PARTICLE_MOTE_FRAG, PARTICLE_SMOKE_FRAG, PARTICLE_SPARK_FRAG, PARTICLE_VERT, } from './render/shaders/particle.js';
 export { BoltPool } from './render/boltPool.js';

package/dist/render/anisotropicLobe.d.ts

@@ -5,3 +5,13 @@ export declare function anisotropicAlphas(roughness: number, strength: number, o
  * are `th`, `bh` and `nh`. 1 at the mirror direction.
  */
 export declare function anisotropicLobe(th: number, bh: number, nh: number, alphaT: number, alphaB: number): number;
+/** Three components in the lobe's frame: along the direction, across it, along the normal. */
+export type FrameVector = readonly [number, number, number];
+/**
+ * The physical form of the same lobe, `π · D · Vis · N·L`, for a surface whose highlight is GGX's
+ * own (`SurfaceMaterial.physicalSpecular`): the stretched distribution normalised as a BRDF's, and
+ * Smith's height-correlated masking stretched with it (Heitz 2014, as Filament writes it), Fresnel
+ * left to the caller. The half vector, the light and the view are each in the lobe's frame. At
+ * strength 0 it is isotropic GGX, the term skin's and the eye's highlights are.
+ */
+export declare function anisotropicPhysicalLobe(half: FrameVector, light: FrameVector, view: FrameVector, alphaT: number, alphaB: number): number;

package/dist/render/anisotropicLobe.js

@@ -31,3 +31,22 @@ export function anisotropicLobe(th, bh, nh, alphaT, alphaB) {
     const d = x * x + y * y + nh * nh;
     return 1 / Math.max(d * d, 1e-8);
 }
+/**
+ * The physical form of the same lobe, `π · D · Vis · N·L`, for a surface whose highlight is GGX's
+ * own (`SurfaceMaterial.physicalSpecular`): the stretched distribution normalised as a BRDF's, and
+ * Smith's height-correlated masking stretched with it (Heitz 2014, as Filament writes it), Fresnel
+ * left to the caller. The half vector, the light and the view are each in the lobe's frame. At
+ * strength 0 it is isotropic GGX, the term skin's and the eye's highlights are.
+ */
+export function anisotropicPhysicalLobe(half, light, view, alphaT, alphaB) {
+    const x = half[0] / alphaT;
+    const y = half[1] / alphaB;
+    const d = x * x + y * y + half[2] * half[2];
+    const distribution = 1 / (Math.PI * alphaT * alphaB * d * d);
+    const ndl = light[2];
+    const ndv = view[2];
+    const lambdaView = ndl * Math.hypot(alphaT * view[0], alphaB * view[1], ndv);
+    const lambdaLight = ndv * Math.hypot(alphaT * light[0], alphaB * light[1], ndl);
+    const visibility = 0.5 / Math.max(lambdaView + lambdaLight, 1e-5);
+    return Math.PI * distribution * visibility * ndl;
+}

package/dist/render/areaLights.d.ts

@@ -95,6 +95,22 @@ export interface AreaLightSource {
      * of a scene unit, and never inside the rectangle itself. Unreal's `AttenuationRadius`, in metres.
      */
     range?: number;
+    /**
+     * Barn doors: a flap hinged at each of the rectangle's four edges, standing this many degrees from
+     * its normal. 90, or absent, folds them flat and they hide nothing; smaller closes them, so the
+     * light narrows to the opening they leave — a rectangle at 50° throws a beam rather than filling
+     * its hemisphere. Unreal's `BarnDoorAngle`, whose default of 88° is nearly flat.
+     *
+     * What a fragment sees past the doors is the part of the rectangle no door's tip hides, one axis
+     * at a time, and the rectangle then shades as that smaller rectangle, its highlight included.
+     * Its shadow map is still baked from the whole rectangle's centre. **What it gives up**: each
+     * door is taken as endless along its hinge, so the two axes clip apart and the corner where two
+     * doors meet hides a square rather than the mitre two real flaps make. One-sided: a two-sided
+     * rectangle's back face has none.
+     */
+    barnDoorAngle?: number;
+    /** The barn doors' length in metres. Absent, 0.2: Unreal's default of 20 cm. */
+    barnDoorLength?: number;
 }
 /** The irradiance a derived `range` ends at, in scene units. See `AreaLightSource.range`. */
 export declare const AREA_RANGE_CUTOFF = 0.001;
@@ -109,8 +125,27 @@ export interface AreaLightBuffer {
     readonly twoSided: Float32Array;
     /** One a rectangle: how far its light reaches. See `AreaLightSource.range`. */
     readonly ranges?: Float32Array;
+    /**
+     * Two a rectangle: the cosine of its barn doors' angle from its normal, then their length in
+     * metres — 0 and 0 for none. See `AreaLightSource.barnDoorAngle`.
+     */
+    readonly barnDoors?: Float32Array;
 }
 export declare function createAreaLightBuffer(capacity?: number): AreaLightBuffer;
+/** Unreal's default barn door length, in metres. See `AreaLightSource.barnDoorLength`. */
+export declare const DEFAULT_BARN_DOOR_LENGTH = 0.2;
+/**
+ * A rectangle's barn doors as the shader reads them, into `out[at]` and `out[at + 1]`: the cosine of
+ * their angle and their length. An angle not between 0 and 90 degrees, or a length not above zero,
+ * is no doors at all, written as 0 and 0 — which the shader reads as "nothing hidden".
+ */
+export declare function barnDoorsOf(light: AreaLightSource, out: Float32Array, at: number): void;
+/**
+ * The fixed arm's half extents and barn doors, four a rectangle as `uAreaLightSize` holds them: the
+ * two half extents, then the doors' cosine and length. Into a target the binder owns, for the first
+ * `MAX_AREA_LIGHTS` alone, which are all the fixed arm reads.
+ */
+export declare function packAreaSizesAndDoors(lights: AreaLightBuffer, out: Float32Array): void;
 /**
  * How far a rectangle's light reaches when it names no range: where its irradiance on its own axis,
  * `L · A / d²` for a rectangle of radiance `L` and area `A` seen from far, falls to

package/dist/render/areaLights.js

@@ -20,8 +20,41 @@ export function createAreaLightBuffer(capacity = MAX_AREA_LIGHTS) {
         sizes: new Float32Array(capacity * 2),
         twoSided: new Float32Array(capacity),
         ranges: new Float32Array(capacity),
+        barnDoors: new Float32Array(capacity * 2),
     };
 }
+/** Unreal's default barn door length, in metres. See `AreaLightSource.barnDoorLength`. */
+export const DEFAULT_BARN_DOOR_LENGTH = 0.2;
+/**
+ * A rectangle's barn doors as the shader reads them, into `out[at]` and `out[at + 1]`: the cosine of
+ * their angle and their length. An angle not between 0 and 90 degrees, or a length not above zero,
+ * is no doors at all, written as 0 and 0 — which the shader reads as "nothing hidden".
+ */
+export function barnDoorsOf(light, out, at) {
+    const angle = light.barnDoorAngle;
+    const length = light.barnDoorLength ?? DEFAULT_BARN_DOOR_LENGTH;
+    if (angle === undefined || !(angle >= 0 && angle < 90) || !(length > 0)) {
+        out[at] = 0;
+        out[at + 1] = 0;
+        return;
+    }
+    out[at] = Math.cos((angle * Math.PI) / 180);
+    out[at + 1] = length;
+}
+/**
+ * The fixed arm's half extents and barn doors, four a rectangle as `uAreaLightSize` holds them: the
+ * two half extents, then the doors' cosine and length. Into a target the binder owns, for the first
+ * `MAX_AREA_LIGHTS` alone, which are all the fixed arm reads.
+ */
+export function packAreaSizesAndDoors(lights, out) {
+    const doors = lights.barnDoors;
+    for (let a = 0; a < MAX_AREA_LIGHTS; a++) {
+        out[a * 4] = lights.sizes[a * 2] ?? 0;
+        out[a * 4 + 1] = lights.sizes[a * 2 + 1] ?? 0;
+        out[a * 4 + 2] = doors?.[a * 2] ?? 0;
+        out[a * 4 + 3] = doors?.[a * 2 + 1] ?? 0;
+    }
+}
 /**
  * How far a rectangle's light reaches when it names no range: where its irradiance on its own axis,
  * `L · A / d²` for a rectangle of radiance `L` and area `A` seen from far, falls to
@@ -106,6 +139,8 @@ export function selectAreaLights(lights, out) {
                     ? light.range
                     : areaRange(light.r, light.g, light.b, light.halfWidth, light.halfHeight);
         }
+        if (out.barnDoors !== undefined)
+            barnDoorsOf(light, out.barnDoors, slot * 2);
     }
     return out;
 }

package/dist/render/atmosphere.d.ts

@@ -45,6 +45,19 @@ export interface Atmosphere {
     /** Linear mode only: where haze begins, and where it is total. */
     fogNear?: number;
     fogFar?: number;
+    /**
+     * The medium only: how far along the view ray it begins, in metres. Absent or 0 is at the
+     * camera, as every world before it was drawn.
+     *
+     * The air nearer than this is perfectly clear, and what lies beyond is fogged by the air past
+     * this point alone — so a faint, bright haze can lie over a distant crowd while the figures a
+     * few metres from the camera stay sharp, which no density can do when the medium starts at the
+     * eye: there it veils the whole frame, lifting the shadows and draining the colour before it
+     * reaches anything far enough to want it. Unlike `linear`'s `fogNear`, nothing past it is a
+     * ramp: it is the same extinction, integrated from further out. **What it gives up** is the air
+     * between the camera and the start, which a real medium has; that is the point of it.
+     */
+    fogStart?: number;
     underwater: UnderwaterAtmosphere | null;
 }
 /**

package/dist/render/atmosphere.js

@@ -46,7 +46,15 @@ export function resolveAtmosphere(atmosphere, cameraY, underwaterEnabled, out) {
     out.fogHeightFalloff = atmosphere.fogHeightFalloff;
     out.fogEyeY = cameraY;
     out.fogMode = atmosphere.fogMode === 'linear' ? 1 : 0;
-    out.fogNear = atmosphere.fogNear ?? 0;
+    /*
+     * **One slot, two meanings, and never both**: the ramp's near distance in linear mode, and in
+     * the medium where it begins (`fogStart`), which the medium never read before — so a world that
+     * left a `fogNear` on an exponential fog starts nothing, and draws exactly as it did.
+     */
+    out.fogNear =
+        atmosphere.fogMode === 'linear'
+            ? (atmosphere.fogNear ?? 0)
+            : Math.max(0, Number.isFinite(atmosphere.fogStart) ? (atmosphere.fogStart ?? 0) : 0);
     out.fogFar = atmosphere.fogFar ?? 1;
     /*
      * The air medium stands in when nothing is submerged. The shaders multiply by the factor

package/dist/render/backend/api.d.ts

@@ -1,13 +1,16 @@
 import type { Bounds } from '../../math/bounds.ts';
 import type { Vec3 } from '../../math/color.ts';
+import type { Camera } from '../camera.ts';
 import type { ReadonlyMat4 } from 'gl-matrix';
 import type { MeshData } from '../mesh.ts';
 import type { ProbeBakeOptions } from '../reflectionProbe.ts';
 import type { Renderer, TranslucentMeshOptions } from './webgl2/renderer.ts';
 import type { InstancedOptions, MeshInstances } from '../instances.ts';
 import type { SurfaceMaterial } from '../surfaceTexture.ts';
+import type { SurfaceOverlay } from '../surfaceOverlay.ts';
 import type { SurfaceSource } from '../compressedSource.ts';
 import type { LightmapPage } from '../lightmap.ts';
+import type { DeviceParticles } from '../particlePool.ts';
 import type { ClothBindingData } from '../clothBindingData.ts';
 import type { TextStyle } from '../textLayout.ts';
 import type { SdfFont } from '../sdfFont.ts';
@@ -187,7 +190,7 @@ export interface MeshOptions {
 }
 export type RendererApi = Omit<{
     [K in keyof Renderer]: Renderer[K];
-}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
+}, 'gpuTimer' | 'createMesh' | 'createMeshIncremental' | 'updateMesh' | 'drawMesh' | 'disposeMesh' | 'drawTranslucentMesh' | 'drawLightVolume' | 'drawFilm' | 'createScatter' | 'drawScatter' | 'uploadScatter' | 'disposeScatter' | 'createInstanced' | 'uploadInstanced' | 'drawInstanced' | 'drawTranslucentInstanced' | 'disposeInstanced' | 'createWater' | 'drawWater' | 'disposeWater' | 'createPlumes' | 'drawPlumes' | 'disposePlumes' | 'setPlumeScale' | 'createCaustics' | 'drawCaustics' | 'disposeCaustics' | 'createParticles' | 'drawParticles' | 'drawDeviceParticles' | 'disposeParticles' | 'createWindStreaks' | 'drawWindStreaks' | 'disposeWindStreaks' | 'createFlock' | 'drawFlock' | 'disposeFlock' | 'createBolts' | 'drawBolts' | 'disposeBolts' | 'createLines' | 'drawLines' | 'disposeLines' | 'createText' | 'setText' | 'setPlate' | 'drawText' | 'textWidth' | 'disposeText' | 'createSdfText' | 'setSdfText' | 'drawSdfText' | 'disposeSdfText' | 'createSurfaceTexture' | 'createSurfaceTextureArray' | 'createLightmap' | 'createSceneCapture' | 'captureScene' | 'updateSurfaceTexture' | 'disposeSurfaceTexture' | 'setSurfaceTexture' | 'setMaterial' | 'setSurfaceOverlay' | 'createClothBinding' | 'createClothParticles' | 'updateClothParticles' | 'setCloth' | 'disposeClothBinding' | 'disposeClothParticles'> & {
     /**
      * A mesh's cloth binding: which simulation triangle each of its vertices follows, where on it and
      * by how much (`ClothBindingData`). The mesh must be skinned — a binding blends each vertex
@@ -211,6 +214,13 @@ export type RendererApi = Omit<{
     setCloth(binding: ClothBindingHandle | null, particles?: ClothParticlesHandle | null): void;
     disposeClothBinding(binding: ClothBindingHandle): void;
     disposeClothParticles(particles: ClothParticlesHandle): void;
+    /**
+     * What the following draws lay over their surfaces beyond their materials — a rim of light, a
+     * dissolve with a glowing edge, wrinkle normals by region — or null for none, which every pass
+     * starts with. Per draw, so one character's whole set of materials changes together. Its images
+     * are regions of one atlas (`SurfaceOverlay.maps`). See `surfaceOverlay.ts`.
+     */
+    setSurfaceOverlay(overlay: SurfaceOverlay | null): void;
     /**
      * Upload a caller's image, or a BC image's blocks with their stored chain where
      * `compressedFormats` has the format. See `SurfaceTextureHandle` for the boundary this guards.
@@ -232,12 +242,33 @@ export type RendererApi = Omit<{
     createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: Parameters<Renderer['createSurfaceTexture']>[1]): SurfaceTextureHandle;
     /**
      * A baked lightmap page on the device, as the texture a `lightmapModel` material takes for its
-     * `modelMap`: two layers of half floats, the irradiance and the direction, filtered linearly and
-     * clamped at its edges, with no mip chain. Disposed as any texture is, with
+     * `modelMap`: two layers of four bytes a texel, the irradiance as an rgb9e5 word and the
+     * direction, which the lit stage decodes and filters itself, clamped at the page's edges, with no
+     * mip chain. A page whose irradiance arrives packed uploads where it lies. Disposed as any texture is, with
      * `disposeSurfaceTexture`; `updateSurfaceTexture` refuses it, as it refuses any array. See
      * `lightmap.ts` for what a surface does with it.
      */
     createLightmap(page: LightmapPage): SurfaceTextureHandle;
+    /**
+     * A texture the scene can be drawn into from a camera of the caller's (`captureScene`), which a
+     * material then shows like any image — most often as its `emissive`, for a screen in the world
+     * showing what a camera elsewhere sees. `width` and `height` in pixels, 1 to 4096. It holds
+     * radiance, at the colour format a probe takes: half floats under `hdrScene`, bytes otherwise.
+     * Disposed as any texture is; `updateSurfaceTexture` refuses it. See `sceneCapture.ts`.
+     */
+    createSceneCapture(width: number, height: number): SurfaceTextureHandle;
+    /**
+     * Draw the scene into a capture from `camera`, at the moment a caller says, usually once a frame
+     * before the frame's own world. `draw` is handed the camera, its matrices updated for the
+     * capture's shape, and submits the scene exactly as it would to the screen — `bindMeshPass`,
+     * `drawMesh` and the rest; `bindMeshPass` the frame's own camera again afterwards. The output
+     * transform is held off, so a screen showing it is graded once, with the frame.
+     *
+     * **The mesh pass alone**, as a probe bake is: what a scene draws after its world is in the
+     * capture only if `draw` draws it, and no temporal resolve or effect after the world runs on it.
+     * Returns whether it drew: false for a texture that is not a capture.
+     */
+    captureScene(capture: SurfaceTextureHandle, camera: Camera, clearColor: Vec3, draw: (camera: Camera) => void): boolean;
     /**
      * Replace a texture's pixels, keeping the GPU object and its sampler state.
      *
@@ -444,6 +475,13 @@ export type RendererApi = Omit<{
     }): ParticleHandle;
     /** Draw a pool's live particles, after the opaque scene. */
     drawParticles(batch: ParticleHandle, data: Parameters<Renderer['drawParticles']>[1], camera: Parameters<Renderer['drawParticles']>[2], env: Parameters<Renderer['drawParticles']>[3], timeSeconds: number): void;
+    /**
+     * Draw a pool's particles from a buffer a caller's own compute wrote (`registerCompute`), where
+     * they lie: the pool's material, blend, flipbook and fades, its instance stream the caller's
+     * buffer. WebGPU only; WebGL2 says so once and draws nothing. Not sorted. See `DeviceParticles`
+     * for the layout.
+     */
+    drawDeviceParticles(batch: ParticleHandle, particles: DeviceParticles, camera: Parameters<Renderer['drawParticles']>[2], env: Parameters<Renderer['drawParticles']>[3], timeSeconds: number): void;
     /** Release a particle pool. */
     disposeParticles(batch: ParticleHandle): void;
     /** Draw a wet film over geometry, using a handle as the surface it lies on. */

package/dist/render/backend/createRenderer.d.ts

@@ -132,6 +132,12 @@ export interface CreateRendererOptions {
      * badge is looked at on a deployed build.
      */
     readonly splash?: boolean | SplashOptions;
+    /**
+     * Whether the display shows a high dynamic range, asked only where `highDynamicRange` was. The
+     * browser's `(dynamic-range: high)` query by default; a host with no DOM, or one that knows
+     * better about its own display, answers instead. See `displayRange.ts`.
+     */
+    readonly highDynamicRangeDisplay?: () => boolean;
 }
 /** What was built, and which path built it. */
 export interface CreatedRenderer {

package/dist/render/backend/createRenderer.js

@@ -4,6 +4,7 @@ import { BACKEND_TIMEOUT_MS, forcedBackend, selectBackend } from './select.js';
 import { TIMED_OUT, withDeadline } from './deadline.js';
 import { mountSplash } from '../../ui/splash.js';
 import { gpuDrivenRefusal, gpuDrivenSupported } from '../gpudriven/pipeline.js';
+import { browserHighDynamicRange, chooseDisplayRange } from '../displayRange.js';
 /**
  * What a caller who says nothing gets.
  *
@@ -177,7 +178,9 @@ export async function createRenderer(canvas, quality = {}, options = {}) {
                 const { createGpuSurface } = await import('./webgpu/device.js');
                 const { WebGPURenderer } = await import('./webgpu/renderer.js');
                 stage = 'creating the surface';
-                const surface = createGpuSurface(canvas, device);
+                const profile = resolveRenderQuality(qualityFor('webgpu'));
+                const surface = createGpuSurface(canvas, device, chooseDisplayRange(profile.highDynamicRange, profile.screenEffects && profile.hdrScene, profile.highDynamicRange &&
+                    (options.highDynamicRangeDisplay ?? browserHighDynamicRange)()));
                 stage = 'constructing the renderer';
                 return { surface, WebGPURenderer };
             })();