@solidrt/3d 0.0.63 → 0.0.64

package/src/scene.ts

@@ -39,7 +39,7 @@
 import { addDraw, createCubeDrawTarget, createDrawTarget, depthTexture, destroyProgram, destroyRenderPipeline, destroyTexture, removeDraw, renderTarget, setDrawBuffers, setDrawParams, setDrawRange, setDrawTextures, setTargetParams, setTargetRect, setTargetSize, setTargetTextures } from "@solidrt/core/gpu"
 import * as spatial from "flux:spatial"
 import type { BindDrawOptions, Impact as CoreImpact, NodeId, QueryFilter } from "flux:spatial"
-import type { BufferId, DrawId, FilterMode, ProgramId, RenderPipelineId, ShaderParams, TextureBindings, TextureId, WrapMode } from "@solidrt/core/gpu"
+import type { BufferId, DrawId, FilterMode, InstanceOrder, ProgramId, RenderPipelineId, ShaderParams, TextureBindings, TextureId, WrapMode } from "@solidrt/core/gpu"
 import { getOwner, onCleanup } from "@solidrt/core"
 import type { PointerEvent as ElementPointerEvent, WheelEvent as ElementWheelEvent } from "@solidrt/core"
 import { copy, mat4, transformPoint } from "./math.ts"
@@ -50,19 +50,21 @@ import { cameraParams, cameraState, ensureCamera, makeCamera, updateCamera } fro
 import type { Camera, CameraState, CameraUpdate } from "./camera.ts"
 import { makeShadowSystem } from "./scene-shadows.ts"
 import { makePointerInput } from "./scene-pointer.ts"
-import { geometryKey, geometryTopology, validateGeometry } from "./geometry.ts"
+import { geometryKey, geometryTopology, layoutKey, validateGeometry } from "./geometry.ts"
 import type { Geometry } from "./geometry.ts"
 import { acquireGeometryBuffers, releaseGeometryBuffers } from "./geometry-gpu.ts"
 import { backgroundPipeline, missingAttributes, SKYBOX_FRAGMENT } from "./material.ts"
 import { disposeResolve, makeResolve, replaceResolve, resizeResolve, setResolveBloom } from "./resolve.ts"
 import type { BloomOptions, ResolveInput, ResolveOptions, ResolveRecord } from "./resolve.ts"
-import { createEnvironmentPlaceholder, createPrefilter, bufferFormat } from "./environment.ts"
-import type { Prefilter } from "./environment.ts"
+import { checkCubeKnobs, createEnvironmentPlaceholder, createPrefilter, cubeTurn, bufferFormat, environmentParams } from "./environment.ts"
+import type { EnvironmentOptions, Prefilter } from "./environment.ts"
+
+export type { EnvironmentOptions } from "./environment.ts"
 import type { Material } from "./material.ts"
 import { activateMorph, fillTransform, freeLeaving, leaveScene, makeNode, setTransition } from "./node.ts"
 import type { SceneHooks, SceneNode, ScenePointerListener } from "./node.ts"
-import { checkInstancePairing, checkMask, instanceBinding, localBounds, publishRecords } from "./mesh.ts"
-import type { InstancedMesh, InstanceNode, Mesh } from "./mesh.ts"
+import { checkInstancePairing, checkMask, checkOrderPairing, drawCount, instanceBinding, localBounds, markLiveRecords, publishRecords } from "./mesh.ts"
+import type { InstancedMesh, InstanceNode, Mesh, MeshInstances, ResolvedInstanceOrder } from "./mesh.ts"
 import type { CastingLight, Light } from "./light.ts"
 
 const IDENTITY = mat4()
@@ -337,64 +339,12 @@ export type SkyboxOptions = {
   rotation?: number
 }
 
-/**
- * The scene's environment: a cube map every `lit` material with
- * `reflectivity` mirrors (scene.setEnvironment). The same three fields
- * as a skybox, and typically the same cube - Three's `scene.environment`
- * with `environmentIntensity` and `environmentRotation`; Unity's
- * environment reflections source, Godot's reflected light from the sky.
- */
-export type EnvironmentOptions = {
-  /** A cube map (loadEnvironment's baked chain; equirectToCube for an LDR
-   * panorama; createCubeTexture with `mipmap: true` for a hand-baked
-   * sky), faces in +X, -X, +Y, -Y, +Z, -Z order, looked up like the
-   * skybox (no flip). A 2D texture id throws. */
-  cube: TextureId
-  /** Multiplier on the reflected color, >= 0; default 1. */
-  intensity?: number
-  /** Turn about world y in RADIANS (default 0), the skybox's convention:
-   * the environment turns as a node with rotation [0, r, 0] would. */
-  rotation?: number
-}
-
-// The uniform turn a rotated cube map is looked up through: the INVERSE
-// of the sky's turn, because a lookup along view direction v must find
-// the texel that sat at R(-r) v before the sky turned by +r.
-function cubeTurn(rotation: number): Mat4 {
-  let c = Math.cos(rotation)
-  let n = Math.sin(rotation)
-  // prettier-ignore
-  return [
-    c, 0, n, 0,
-    0, 1, 0, 0,
-    -n, 0, c, 0,
-    0, 0, 0, 1,
-  ]
-}
-
-function checkCubeKnobs(o: { intensity?: number; rotation?: number }, site: string): { intensity: number; rotation: number } {
-  let intensity = o.intensity ?? 1
-  let rotation = o.rotation ?? 0
-  if (!Number.isFinite(intensity) || intensity < 0) throw new Error(site + ": intensity must be a finite number >= 0, got " + intensity)
-  if (!Number.isFinite(rotation)) throw new Error(site + ": rotation must be a finite angle in radians, got " + rotation)
-  return { intensity, rotation }
-}
-
 // The entry params a skybox compiles to.
 function skyboxParams(sky: SkyboxOptions, site: string): ShaderParams {
   let k = checkCubeKnobs(sky, site)
   return { uSkyIntensity: k.intensity, uSkyRotation: cubeTurn(k.rotation) }
 }
 
-// The shared params an environment compiles to (null = off: uEnvOn 0
-// makes every reflective material's term vanish; the set ENVIRONMENT in
-// `@solidrt/3d/glsl` declares).
-function environmentParams(env: EnvironmentOptions | null): ShaderParams {
-  if (env === null) return { uEnvIntensity: 0, uEnvRotation: cubeTurn(0), uEnvOn: 0 }
-  let k = checkCubeKnobs(env, "scene.setEnvironment")
-  return { uEnvIntensity: k.intensity, uEnvRotation: cubeTurn(k.rotation), uEnvOn: 1 }
-}
-
 export type { BloomOptions, ResolveInput, ResolveOptions } from "./resolve.ts"
 
 /** The resolve's tone mapping (setToneMapping): "none" clamps, "aces" is
@@ -404,6 +354,20 @@ export type { BloomOptions, ResolveInput, ResolveOptions } from "./resolve.ts"
  * where a filmic curve shifts them. */
 export type ToneMapping = "none" | "aces" | "agx" | "neutral"
 
+/** The buffer's blend space (SceneOptions.blendSpace). "linear" is the
+ * default contract: fragments write linear light into a half-float
+ * buffer and one resolve pass applies exposure, tone mapping and the
+ * sRGB encode. "display" turns the scene display-referred, the way the
+ * web renders: fragments encode to sRGB at output (BLEND_SPACE in the
+ * shared tail), BLENDING runs on encoded values, the buffer is rgba8
+ * and IS the displayed image - no resolve pass, no HDR, and exposure,
+ * tone mapping, bloom, a custom resolve and reflection probes are all
+ * unavailable (they act on linear radiance). The one reason it exists:
+ * content authored or TRAINED against sRGB compositing - a gaussian
+ * splat capture above all - only looks right when the blend itself is
+ * sRGB; a linear blend lays a milky veil over its stacked translucents. */
+export type BlendSpace = "linear" | "display"
+
 // The uToneMapping value per mode; the RESOLVE set branches on it.
 const TONE_MAPPING_CODE: Record<ToneMapping, number> = { none: 0, aces: 1, agx: 2, neutral: 3 }
 // The core's draw queues (flux:spatial bindDraw), drawn in this order.
@@ -414,15 +378,35 @@ const QUEUE_TRANSPARENT = 3
 let drawQueue = (m: Material): number =>
   m.transparent === true ? QUEUE_TRANSPARENT : m.cutout === true ? QUEUE_CUTOUT : QUEUE_OPAQUE
 // A mesh entry's draw sink: what the core writes into it and where it
-// sorts, from the material the entry draws with.
-let drawBinding = (material: Material, mesh: Mesh, inst: { count: number } | null): BindDrawOptions => ({
+// sorts, from the material the entry draws with. `orderFeed` (the scene
+// entry of a position-ordered population) has the core steer the entry's
+// record order from the target's view.
+let drawBinding = (material: Material, mesh: Mesh, inst: MeshInstances | null, orderFeed = false): BindDrawOptions => ({
   normal: material.normalMatrix === true,
-  count: inst !== null ? inst.count : 1,
+  count: inst !== null ? drawCount(inst) : 1,
   fade: material.lodFade === true,
   queue: drawQueue(material),
   renderOrder: mesh.renderOrder,
+  orderFeed,
 })
 
+// The engine's instanceOrder for the scene entry of an ordered mesh: the
+// key stream resolved to its pipeline buffer index (the geometry's
+// buffers precede the instance buffers, and the material's declaration
+// order is the pipeline's), the float offsets resolved at creation, and
+// for a position key a seed direction the core-side feed (bindDraw
+// orderFeed) replaces at the first flush.
+const ORDER_SEED_DIRECTION: [number, number, number] = [0, 0, 1]
+let entryInstanceOrder = (order: ResolvedInstanceOrder, material: Material, geometryBuffers: number): InstanceOrder => {
+  let at = (material.instanceBuffers ?? []).findIndex(b => layoutKey(b.attributes) === order.key)
+  if (at < 0) throw new Error("Mesh material declares no instance buffer with the mesh's instanceOrder key layout (" + order.key + ")")
+  let buffer = geometryBuffers + at
+  let indices = order.indices !== null ? { indices: order.indices } : {}
+  return order.position
+    ? { position: order.floats, direction: ORDER_SEED_DIRECTION, descending: order.descending, buffer, retain: order.retain, ...indices }
+    : { field: order.floats, descending: order.descending, buffer }
+}
+
 /** The RESOLVE set's params for a resolve pass of your own (an app-owned
  * atlas tiled views render into, resolved through `resolveFragment` from
  * `/glsl`): `uToneMapping` and `uExposure` as the scene's setToneMapping
@@ -455,6 +439,12 @@ export type SceneOptions = {
   toneMapping?: ToneMapping
   /** Output exposure, default 1; see setExposure. */
   exposure?: number
+  /** The buffer's blend space, default "linear"; fixed at creation. See
+   * BlendSpace: "display" blends sRGB-encoded values in an rgba8 buffer
+   * that is itself the displayed image (`texture` is the buffer, there
+   * is no resolve), and rejects resolve, bloom, toneMapping, exposure
+   * and reflection probes. */
+  blendSpace?: BlendSpace
   /** LOD quality knob, default 1: every measured projected size is
    * multiplied by it before the level select, so below 1 the groups hand
    * over to their far levels sooner (Unity's lodBias). Live via
@@ -693,12 +683,15 @@ const PROBE_SIZE = 128
 const PROBE_FOV = 90
 export type Scene = {
   /** The scene's output: an ordinary texture id (`<texture src>`) - the
-   * resolve of the buffer, encoded display pixels. */
+   * resolve of the buffer, encoded display pixels. In a blendSpace
+   * "display" scene there is no resolve and this IS the buffer. */
   texture: TextureId
-  /** The scene's BUFFER: the target the meshes draw into, premultiplied
-   * linear light (half float where the device renders it, see
-   * bufferFormat), sampler-only - the input of a radiance-reading pass (a
-   * bloom chain) whose result a custom resolve adds back in. */
+  /** The scene's BUFFER: the target the meshes draw into, sampler-only.
+   * Premultiplied linear light in a linear scene (half float where the
+   * device renders it, see bufferFormat) - the input of a
+   * radiance-reading pass (a bloom chain) whose result a custom resolve
+   * adds back in. In a blendSpace "display" scene it holds encoded
+   * display pixels and equals `texture`. */
   hdrTexture: TextureId
   /** The buffer's depth as a sampler-only texture id when created with
    * `depth: "texture"`, else null. */
@@ -719,8 +712,9 @@ export type Scene = {
   size(): { width: number; height: number }
   /**
    * Scene-wide uniforms: merge app-owned names into the target's SHARED
-   * params, beside the standard uViewProj/uCamPos/uCamRight/uCamUp the
-   * camera writes. One write per frame however many meshes read the name
+   * params, beside the standard uViewProj/uCamPos/uCamRight/uCamUp/
+   * uViewport (the target's pixel size) the camera writes. One write per
+   * frame however many meshes read the name
    * (a clock, a sun direction, fog) - the per-mesh channel is
    * setMeshParams. Merge semantics, no unset; a material that does not
    * declare a name simply skips it. Frame-rate-safe like setTransform.
@@ -1062,10 +1056,15 @@ function meshRange(mesh: Mesh): { firstIndex: number; indexCount: number } {
 // discard everything).
 const LOD_SOLID = [1, 1]
 
-function entrySeed(material: Material, params: ShaderParams | null): ShaderParams {
+function entrySeed(material: Material, params: ShaderParams | null, layers: number): ShaderParams {
   let seed: ShaderParams = { uModel: IDENTITY }
   if (material.normalMatrix) seed.uNormal = IDENTITY
   if (material.lodFade) seed.uLodFade = LOD_SOLID
+  // The mesh's layer membership, which lightVector masks lights against;
+  // `| 0` because GLSL ES ints are signed 32-bit (all bits = -1). An
+  // unwritten int uniform reads 0 - no light at all - so a lit entry is
+  // always seeded.
+  if (material.layered) seed.uLayers = layers | 0
   return { ...seed, ...material.params, ...params }
 }
 
@@ -1122,10 +1121,16 @@ function entryTextures(material: Material, mesh: Mesh, morph: MorphEntry | null)
   return textures
 }
 
-// A buffer's clear color: the sRGB option decoded to premultiplied linear
-// light, what the buffer holds and the resolve tone maps.
-function bufferClear(color: [number, number, number, number] | undefined): [number, number, number, number] | undefined {
+// A buffer's clear color: the sRGB option decoded to premultiplied
+// linear light in a linear scene (what the buffer holds and the resolve
+// tone maps); a display-space buffer holds encoded pixels, so the sRGB
+// components premultiply as they are.
+function bufferClear(color: [number, number, number, number] | undefined, display: boolean): [number, number, number, number] | undefined {
   if (color === undefined) return undefined
+  if (display) {
+    let a = color[3]
+    return [color[0] * a, color[1] * a, color[2] * a, a]
+  }
   let c = premultipliedColor(color)
   return [c[0]!, c[1]!, c[2]!, c[3]!]
 }
@@ -1145,19 +1150,34 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   // scene cannot see must not darken it).
   let sceneMask = checkMask(opts?.layers ?? 1, "createScene")
   let label = opts?.label ?? "scene"
+  let blendSpace = opts?.blendSpace ?? "linear"
+  if (blendSpace !== "linear" && blendSpace !== "display") {
+    throw new Error('createScene: expected blendSpace "linear" or "display", got ' + blendSpace)
+  }
+  let display = blendSpace === "display"
+  if (display) {
+    // Display space is LDR and has no resolve stage: everything that
+    // acts on linear radiance past the fragment is off the table.
+    for (let name of ["resolve", "bloom", "toneMapping", "exposure"] as const) {
+      if (opts?.[name] !== undefined) throw new Error(`createScene: ${name} does not compose with blendSpace "display" (the buffer holds encoded display pixels; there is no resolve stage)`)
+    }
+  }
   // `texture` is the scene's BUFFER throughout this file: the draw target
   // every entry, sink, sort and param write names. The handle's `texture`
-  // is its resolve (below), the displayable id.
+  // is its resolve (below); a display-space scene has no resolve and the
+  // buffer is itself the displayable id.
   let texture = createDrawTarget(width, height, null, {
     depth: depthMode,
-    format: bufferFormat(),
-    clearColor: bufferClear(opts?.clearColor),
+    format: display ? "rgba8" : bufferFormat(),
+    clearColor: bufferClear(opts?.clearColor, display),
     samples: opts?.samples,
+    filter: display ? opts?.filter : undefined,
+    wrap: display ? opts?.wrap : undefined,
     label,
     autoFree: false,
   })
   spatial.setDrawSort(texture, true)
-  let resolve = makeResolve(texture, width, height, opts?.resolve, { filter: opts?.filter, wrap: opts?.wrap }, label)
+  let resolve = display ? null : makeResolve(texture, width, height, opts?.resolve, { filter: opts?.filter, wrap: opts?.wrap }, label)
   let disposed = false
   let scheduled = false
 
@@ -1265,6 +1285,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let bias: number[] = []
     let normalBias: number[] = []
     let radius: number[] = []
+    // Layer masks cross to GLSL as signed 32-bit ints (all bits = -1,
+    // the no-hemisphere default; the shader only ANDs the bit pattern).
+    let masks: number[] = []
+    let hemiMask = -1
     let count = 0
     for (let light of lights) {
       if (light.type === "hemisphere") {
@@ -1273,6 +1297,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         let g = linearColor(light.ground)
         sky = [s[0]! * k, s[1]! * k, s[2]! * k]
         ground = [g[0]! * k, g[1]! * k, g[2]! * k]
+        hemiMask = light.layers | 0
         continue
       }
       // A light past the cap is not lit (sync reports the set once): its
@@ -1305,6 +1330,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       bias.push(light.shadow.bias)
       normalBias.push(light.shadow.normalBias)
       radius.push(light.shadow.radius)
+      masks.push(light.layers | 0)
       count++
     }
     for (let i = count; i < MAX_LIGHTS; i++) {
@@ -1314,6 +1340,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       bias.push(0)
       normalBias.push(0)
       radius.push(1)
+      masks.push(0)
     }
     // The shadow set rides with the lights. Per casting light i: its
     // map slots as uShadowFirst[i] + uShadowCount[i] (0 = a receiving
@@ -1340,10 +1367,12 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let params: ShaderParams = {
       uHemiSky: sky,
       uHemiGround: ground,
+      uHemiMask: hemiMask,
       uLightCount: count,
       uLightType: types,
       uLightColor: colors,
       uLightParams: coneFalloff,
+      uLightMask: masks,
       uShadowFirst: first,
       uShadowCount: counts,
       uShadowBias: bias,
@@ -1484,8 +1513,12 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
      * m.castShadow). Re-evaluated per mesh by _setCast; also picks the
      * caster's own shadow material variant over the depth override. */
     shadowFilter: ((mesh: Mesh) => boolean) | null
+    /** The casting light a SHADOW view renders for (null otherwise):
+     * its `layers` compose the view's mask with the scene's, so a mesh
+     * the light cannot see casts nothing into its map. */
+    shadowLight: CastingLight | null
     /** Layer mask: the view draws the meshes whose `layers` intersect
-     * it. A shadow view's follows the scene's. */
+     * it. A shadow view's is the scene's masked by its light's layers. */
     mask: number
     /** Names the view set itself (view.setParams, the fog option): the
      * scene's fan-out skips them so a view override survives scene-wide
@@ -1524,6 +1557,21 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   // environment (the faces, or the chain prefiltered from them): it
   // samples the placeholder instead of itself.
   let ownsEnvironment = (t: TextureId) => environment !== null && views.some(v => v.texture === t && v.probeCube === environment)
+  // A mesh's own environment on one entry (Mesh.environment, applied
+  // where the material reflects - Material.env): the same uEnv* names
+  // the scene writes per target, written per entry, and the entry's
+  // beat the target's (specific beats general). `probeCube` guards a
+  // probe against sampling its own cube through an override - the
+  // black placeholder stands in, writeLights' target-level rule at
+  // entry grain (the engine rejects the same-pass feedback outright).
+  let envOverride = (mesh: Mesh, material: Material, probeCube: TextureId | null): { params: ShaderParams; cube: TextureId | null } | null => {
+    if (mesh.environment === undefined || material.env !== true) return null
+    let e = mesh.environment
+    return {
+      params: environmentParams(e, "setEnvironment"),
+      cube: e === null ? null : probeCube !== null && probeCube === e.cube ? envPlaceholder : e.cube,
+    }
+  }
   // The mesh's entry in the scene's OWN target - what mesh._entry is.
   // Created when the scene mask admits the mesh, dropped when it stops:
   // the same lifecycle a view entry has, so `_buffers` (not `_entry`) is
@@ -1539,18 +1587,32 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     // mismatch branch in sync() turns it on in the same pass that writes
     // uModel.
     let morph = morphEntry(mesh.material, mesh)
-    mesh._entry = addDraw(texture, mesh.material.pipeline(mesh.geometry, geometryTopology(mesh.geometry)), entrySeed(mesh.material, morph === null ? mesh._params : { ...morph.params, ...mesh._params }), {
+    let env = envOverride(mesh, mesh.material, null)
+    let params = morph === null ? mesh._params : { ...morph.params, ...mesh._params }
+    if (env !== null) params = { ...env.params, ...params }
+    let textures = entryTextures(mesh.material, mesh, morph)
+    if (env !== null && env.cube !== null) textures = { ...textures, uEnv: env.cube }
+    // The scene entry is the ONE ordered entry of an ordered population
+    // (one buffer holds one order): views bind the same buffers and draw
+    // them in the order the scene's camera decides.
+    let order = inst?.order ?? null
+    mesh._entry = addDraw(texture, mesh.material.pipeline(mesh.geometry, geometryTopology(mesh.geometry)), entrySeed(mesh.material, params, mesh.layers), {
       buffers: [...bufs.buffers, ...(inst !== null ? instanceBinding(mesh.material, inst) : [])],
       indexBuffer: bufs.index,
       indexFormat: bufs.indexFormat,
       ...meshRange(mesh),
-      textures: entryTextures(mesh.material, mesh, morph),
+      textures,
       instanceCount: 0,
+      ...(order !== null ? { instanceOrder: entryInstanceOrder(order, mesh.material, bufs.buffers.length) } : {}),
       label: drawLabel(mesh),
     })
     // The core turns the entry on (with the world matrix) at the next
     // flush, and off again whenever the node or an ancestor hides.
-    spatial.bindDraw(mesh._node!, texture, mesh._entry, drawBinding(mesh.material, mesh, inst))
+    spatial.bindDraw(mesh._node!, texture, mesh._entry, drawBinding(mesh.material, mesh, inst, order !== null && order.position))
+    // An ordered population republishes whole with its fresh entry: the
+    // engine-side order registry was just (re)built empty, and only a
+    // full publish seeds the gathered buffer and the retained copy.
+    if (order !== null) markLiveRecords(mesh)
   }
   let detachScene = (mesh: Mesh) => {
     if (mesh._entry === null) return
@@ -1591,12 +1653,18 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let bufs = mesh._buffers!
     let morph = morphEntry(material, mesh)
     let params = v.override !== null ? (morph === null ? null : morph.params) : morph === null ? mesh._params : { ...morph.params, ...mesh._params }
-    let entry = addDraw(v.texture, material.pipeline(mesh.geometry, geometryTopology(mesh.geometry)), entrySeed(material, params), {
+    // The mesh's own environment rides its own material only (an
+    // override view follows its target, like mesh._params).
+    let env = v.override === null ? envOverride(mesh, material, v.probeCube) : null
+    if (env !== null) params = { ...env.params, ...params }
+    let textures = entryTextures(material, mesh, morph)
+    if (env !== null && env.cube !== null) textures = { ...textures, uEnv: env.cube }
+    let entry = addDraw(v.texture, material.pipeline(mesh.geometry, geometryTopology(mesh.geometry)), entrySeed(material, params, mesh.layers), {
       buffers: [...bufs.buffers, ...(inst !== null ? instanceBinding(material, inst) : [])],
       indexBuffer: bufs.index,
       indexFormat: bufs.indexFormat,
       ...meshRange(mesh),
-      textures: entryTextures(material, mesh, morph),
+      textures,
       instanceCount: 0,
       label: drawLabel(mesh),
     })
@@ -1642,7 +1710,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       updateCamera(cam, { position, target: [position[0] + d[0], position[1] + d[1], position[2] + d[2]], up: PROBE_FACE_UP[face] })
       ensureCamera(cam, size, size)
       cam.pending = false
-      setTargetParams(target, cameraParams(cam))
+      setTargetParams(target, cameraParams(cam, size, size))
       perFace?.(face)
       if (chain && face < last) renderTarget(target, face, 0)
       else renderTarget(target, face)
@@ -1654,11 +1722,14 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   // entry per mesh the filter admits.
   let makeView = (
     vopts: ViewOptions,
-    shadowFilter: ((mesh: Mesh) => boolean) | null,
+    shadowLight: CastingLight | null,
     cube: number | null = null,
     mipmap = false,
     sky = false,
   ): ViewRecord => {
+    // Non-null shadowLight makes this a SHADOW view: the light's map
+    // tile, drawing the casters its layers admit.
+    let shadowFilter = shadowLight === null ? null : (m: Mesh) => m.castShadow
     let override = vopts.overrideMaterial ?? null
     if (override !== null) {
       for (let mesh of meshes) if (mesh._instances === null) checkLayout(override, mesh.geometry, "View override material")
@@ -1666,6 +1737,12 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let tiled = vopts.into !== undefined
     if (tiled && vopts.resolve !== undefined) throw new Error("createView: a tiled view (into) has no resolve of its own - resolve the atlas")
     if (tiled && vopts.bloom !== undefined) throw new Error("createView: a tiled view (into) has no resolve to bloom on - resolve the atlas")
+    if (display) {
+      // The views of a display-space scene are display-referred like it:
+      // no resolve of their own, and nothing that would act past one.
+      if (vopts.resolve !== undefined) throw new Error('createView: resolve does not compose with blendSpace "display" (the view buffer is the displayed image)')
+      if (vopts.bloom !== undefined) throw new Error('createView: bloom does not compose with blendSpace "display" (there is no resolve stage)')
+    }
     let viewLabel = vopts.label ?? label + (cube !== null ? "-probe" : "-view")
     let buffer =
       cube !== null
@@ -1675,15 +1752,17 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
             // solid angle: a generated chain, refreshed per face render.
             mipmap,
             format: bufferFormat(),
-            clearColor: bufferClear(vopts.clearColor),
+            clearColor: bufferClear(vopts.clearColor, display),
             label: viewLabel,
             autoFree: false,
           })
         : createDrawTarget(vopts.width, vopts.height, null, {
             depth: tiled ? undefined : (vopts.depth ?? true),
-            format: tiled ? undefined : bufferFormat(),
-            clearColor: bufferClear(vopts.clearColor),
+            format: tiled ? undefined : display ? "rgba8" : bufferFormat(),
+            clearColor: bufferClear(vopts.clearColor, display),
             samples: vopts.samples,
+            filter: display ? vopts.filter : undefined,
+            wrap: display ? vopts.wrap : undefined,
             label: viewLabel,
             autoFree: false,
             into: vopts.into,
@@ -1701,8 +1780,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       texture: buffer,
       // A shadow view is depth only, a probe's faces are read as a cube,
       // a tile is the atlas's: none of them displays, so none resolves.
+      // A display-space view's buffer is the displayed image itself.
       resolve:
-        cube === null && shadowFilter === null && !tiled
+        cube === null && shadowFilter === null && !tiled && !display
           ? makeResolve(buffer, vopts.width, vopts.height, vopts.resolve, { filter: vopts.filter, wrap: vopts.wrap }, viewLabel)
           : null,
       ownBloom: vopts.bloom !== undefined,
@@ -1713,7 +1793,8 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       skipped: new Set(),
       skippedReported: false,
       shadowFilter,
-      mask: shadowFilter !== null ? sceneMask : checkMask(vopts.layers ?? 1, "createView"),
+      shadowLight,
+      mask: shadowLight !== null ? (sceneMask & shadowLight.layers) >>> 0 : checkMask(vopts.layers ?? 1, "createView"),
       ownNames: new Set(),
       camera: makeCamera(),
       entries: new Map(),
@@ -1815,7 +1896,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     let cameraMoved = camera.pending
     if (camera.pending) {
       camera.pending = false
-      setTargetParams(texture, cameraParams(camera))
+      setTargetParams(texture, cameraParams(camera, width, height))
       setView(texture, camera)
     }
     shadowSys.placeCameras(cameraMoved)
@@ -1823,7 +1904,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       ensureCamera(v.camera, v.width, v.height)
       if (v.camera.pending) {
         v.camera.pending = false
-        setTargetParams(v.texture, cameraParams(v.camera))
+        setTargetParams(v.texture, cameraParams(v.camera, v.width, v.height))
         setView(v.texture, v.camera)
         if (v.shadowFilter !== null) shadowSys.markMatricesDirty()
       }
@@ -1900,7 +1981,9 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     _setLayers(mesh) {
       if (mesh._buffers === null || disposed) return
       if (mesh._node !== null) spatial.setLayers(mesh._node, mesh.layers)
-      if (mesh._instances !== null) {
+      // An instanced mesh's instance nodes follow its mask; a record mesh
+      // has none.
+      if (mesh._instances !== null && mesh._instances.nodes !== null) {
         for (let n of instanceGroup(mesh as InstancedMesh)) spatial.setLayers(n, mesh.layers)
       }
       if ((mesh.layers & sceneMask) !== 0) attachScene(mesh)
@@ -1909,12 +1992,34 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         if ((mesh.layers & v.mask) !== 0) attachView(v, mesh)
         else detachView(v, mesh)
       }
+      // The surviving lit entries follow the membership too (uLayers, the
+      // mask lightVector tests; a fresh attach above was seeded with it).
+      let layered: ShaderParams = { uLayers: mesh.layers | 0 }
+      if (mesh._entry !== null && mesh.material.layered === true) setDrawParams(texture, mesh._entry, layered)
+      for (let v of views) {
+        let entry = v.entries.get(mesh)
+        if (entry !== undefined && viewMaterial(v, mesh).layered === true) setDrawParams(v.texture, entry, layered)
+      }
       hooks._schedule()
     },
     _lightChanged() {
       lightsDirty = true
       hooks._schedule()
     },
+    _lightLayersChanged(light) {
+      if (disposed || light.type === "hemisphere") return
+      // The light's shadow views re-filter their casters by the new mask;
+      // the tiles and cameras stay (the uniform rewrite is _lightChanged's).
+      for (let v of views) {
+        if (v.shadowLight !== light) continue
+        v.mask = (sceneMask & light.layers) >>> 0
+        for (let mesh of meshes) {
+          if ((mesh.layers & v.mask) !== 0) attachView(v, mesh)
+          else detachView(v, mesh)
+        }
+      }
+      hooks._schedule()
+    },
     _attach(mesh) {
       if (disposed) return
       validateGeometry(mesh.geometry)
@@ -1939,6 +2044,10 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         )
       }
       if (inst !== null) checkInstancePairing(mesh.material, inst, "Mesh material")
+      // An ordered population's key stream must be among the entry's
+      // buffers, whatever material the mesh wears now - errors here, at
+      // add(), like the pairing above.
+      if (inst !== null) checkOrderPairing(mesh.material, inst, "Mesh material")
       // An anchored population's records are relative to the anchor, so
       // it must be an ancestor (the core's contract: an anchor move then
       // restages every record); anything else binds records that never
@@ -2075,7 +2184,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       // The core composes the count with the visibility switch: a hidden
       // entry stays at 0 and the unhide restores the new count.
       if (mesh._buffers !== null && mesh._node !== null && !disposed && mesh._instances !== null) {
-        spatial.setDrawCount(mesh._node, mesh._instances.count)
+        spatial.setDrawCount(mesh._node, drawCount(mesh._instances))
       }
     },
     _setBuffer(mesh) {
@@ -2194,7 +2303,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   }
 
   let scene: Scene = {
-    texture: resolve.target,
+    texture: resolve === null ? texture : resolve.target,
     hdrTexture: texture,
     depthTexture: depthMode === "texture" ? depthTexture(texture) : null,
     root,
@@ -2208,7 +2317,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       width = w
       height = h
       setTargetSize(texture, w, h)
-      resizeResolve(resolve, w, h)
+      if (resolve !== null) resizeResolve(resolve, w, h)
       camera.dirty = true
       hooks._schedule()
     },
@@ -2217,7 +2326,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       if (disposed) return
       Object.assign(sceneParams, params)
       setTargetParams(texture, params)
-      setTargetParams(resolve.target, params)
+      if (resolve !== null) setTargetParams(resolve.target, params)
       for (let v of views) {
         // A view's own names (view.setParams, its fog) win over the
         // scene-wide fan-out.
@@ -2251,13 +2360,13 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
         if ((mesh.layers & mask) !== 0) attachScene(mesh)
         else detachScene(mesh)
       }
-      // Shadow views follow the scene's mask: what the scene cannot see
-      // must not darken it.
+      // Shadow views follow the scene's mask (what the scene cannot see
+      // must not darken it), narrowed by their light's own layers.
       for (let v of views) {
-        if (v.shadowFilter === null) continue
-        v.mask = mask
+        if (v.shadowLight === null) continue
+        v.mask = (mask & v.shadowLight.layers) >>> 0
         for (let mesh of meshes) {
-          if ((mesh.layers & mask) !== 0) attachView(v, mesh)
+          if ((mesh.layers & v.mask) !== 0) attachView(v, mesh)
           else detachView(v, mesh)
         }
       }
@@ -2292,7 +2401,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     },
     setEnvironment(env) {
       if (disposed) return
-      let params = environmentParams(env)
+      let params = environmentParams(env, "scene.setEnvironment")
       environment = env === null ? null : env.cube
       let cube = environment ?? envPlaceholder
       // A probe's own faces never sample the probe (see writeLights).
@@ -2300,21 +2409,25 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       scene.setParams(params)
     },
     setToneMapping(mode) {
+      if (resolve === null) throw new Error('scene.setToneMapping: a blendSpace "display" scene has no resolve stage to tone map in')
       let code = TONE_MAPPING_CODE[mode]
       if (code === undefined) throw new Error('scene.setToneMapping: expected "none", "aces", "agx" or "neutral", got ' + mode)
       scene.setParams({ uToneMapping: code })
     },
     setExposure(exposure) {
+      if (resolve === null) throw new Error('scene.setExposure: a blendSpace "display" scene has no resolve stage to expose in')
       if (!Number.isFinite(exposure) || exposure < 0) throw new Error("scene.setExposure: expected a finite number >= 0, got " + exposure)
       scene.setParams({ uExposure: exposure })
     },
     setResolve(r) {
       if (disposed) return
+      if (resolve === null) throw new Error('scene.setResolve: a blendSpace "display" scene has no resolve stage')
       replaceResolve(resolve, texture, r)
       hooks._schedule()
     },
     setBloom(bloom) {
       if (disposed) return
+      if (resolve === null) throw new Error('scene.setBloom: a blendSpace "display" scene has no resolve stage to bloom on')
       sceneBloom = bloom
       setResolveBloom(resolve, texture, width, height, bloom)
       for (let v of views) if (v.resolve !== null && !v.ownBloom) setResolveBloom(v.resolve, v.texture, v.width, v.height, bloom)
@@ -2525,6 +2638,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
     },
     createReflectionProbe(popts) {
       if (disposed) throw new Error("createReflectionProbe: the scene is disposed")
+      if (display) throw new Error('createReflectionProbe: a blendSpace "display" scene renders encoded pixels, which a probe would then sample as linear radiance')
       let { cube, setPosition, update, dispose } = makeProbe(popts, checkMask(popts.layers ?? 1, "createReflectionProbe"))
       return { cube, setPosition, update, dispose }
     },
@@ -2559,7 +2673,7 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
       // Drain the zeroed direction slots the teardown queued while the
       // targets still exist; afterwards their groups are gone.
       spatial.flush()
-      disposeResolve(resolve)
+      if (resolve !== null) disposeResolve(resolve)
       destroyTexture(texture)
       for (let v of views.slice()) disposeView(v)
       shadowSys.dispose()
@@ -2646,10 +2760,17 @@ export function createScene(width: number, height: number, opts?: SceneOptions):
   scene.setParams({ uFogColor: [0, 0, 0], uFogNear: 0, uFogInv: 0, uFogDensity: 0, uFogHeight: 0, uFogHeightFalloff: 0 })
   // Likewise the environment set starts at "none" (uEnvOn 0), so a
   // reflective material has coverage before setEnvironment.
-  scene.setParams(environmentParams(null))
+  scene.setParams(environmentParams(null, "scene.setEnvironment"))
   // And the resolve at its defaults (exposure 1, no tone mapping).
   scene.setParams({ uExposure: 1, uToneMapping: TONE_MAPPING_CODE.none })
   if (opts?.fog !== undefined) scene.setFog(opts.fog)
+  // The one shader-visible trace of the mode: stock fragments (and any
+  // custom one composing BLEND_SPACE) branch on it; views inherit it
+  // through the scene-params seed. Every scene writes it, 0 included: a
+  // program is shared across scenes and its uniform keeps the last
+  // drawn value, so a linear scene must overwrite what a display-space
+  // one left behind.
+  scene.setParams({ uBlendSpace: display ? 1 : 0 })
   if (opts?.toneMapping !== undefined) scene.setToneMapping(opts.toneMapping)
   if (opts?.exposure !== undefined) scene.setExposure(opts.exposure)
   if (opts?.bloom !== undefined) scene.setBloom(opts.bloom)