reze-engine 0.56.10 → 0.56.12

package/src/shaders/lights.ts

@@ -10,21 +10,26 @@ import { SCENE_TAP_STUB } from "./scene-tap"
 // renderer that bolted a second key light onto a toon shader has shipped. A
 // light here brightens; it does not restate the shading.
 //
-// So there are no per-light shadows, no area lights and no clustering. At this
-// count a flat loop in the fragment shader is cheaper than anything that would
-// avoid it, and the cap is what keeps that true.
+// So there are no per-light shadows, no area lights and no clustering. The loop
+// runs over the lights a scene HAS, not over the cap, so a scene with four pays
+// for four; the cap only bounds the buffer and the worst case.
 //
 // LAYOUT. A 4-float header (count, then padding that keeps the records
-// vec4-aligned), then MAX_LIGHTS records of 8 floats:
+// vec4-aligned), then MAX_LIGHTS records of 16 floats — four vec4s:
 //
-//   [0..2] position, world space      [3] radius
+//   [0..2] position, world space               [3] radius
 //   [4..6] colour PREMULTIPLIED by intensity   [7] type
+//   [8..10] aim, unit, pointing away from the light   [11] cos of the outer angle
+//   [12] cos of the inner angle                [13..15] spare
 //
 // Colour carries intensity because nothing reads them apart: every use is the
 // product, and storing two numbers that are only ever multiplied is two numbers
-// that can disagree. `type` is reserved — every light is a point light today
-// and the loop does not branch on it, so it is honest padding rather than a
-// switch with one case.
+// that can disagree.
+//
+// A POINT LIGHT IS A SPOT WITH NO CONE, and that is how the loop stays
+// branchless: it stores aim (0,0,0) and both cosines at -1, which makes the
+// cone term below saturate to exactly 1. `type` says which a light is for
+// anyone reading the buffer; the shading never asks.
 
 import { castDistanceStub } from "./passes/cast-distance"
 import { audioApi } from "./audio-api"
@@ -37,14 +42,25 @@ import { idApi } from "./id-api"
  *  vec4-aligned, which is what lets a future pass read them as vec4s. */
 export const LIGHT_HEADER = 4
 /** Floats per light — see the layout above. */
-export const LIGHT_STRIDE = 8
+export const LIGHT_STRIDE = 16
 /**
- * The cap, and it is a real one: the loop below runs per fragment, so this is
- * the number that decides whether lights are free or a cost. Sixteen is the
- * bounded middle tier the design settled on — enough for a stage rig, far below
- * the point where clustering would start to pay for itself.
+ * The cap. The loop below runs per fragment over the lights a scene HAS, so
+ * this bounds the worst case rather than the ordinary one, and the buffer is
+ * storage rather than uniform — 128 records is 8 KiB, which costs nothing to
+ * declare and is paid for only by the scenes that fill it.
+ *
+ * Sized against the work, not against a round number: a Unity stage arrives
+ * with a lamp per fixture. One rip of a resort brought thirty-three, a lit
+ * interior brings a hundred or more, and the ceilings of sixteen and then
+ * forty-eight each cut a real scene in half. Past this the extras are dropped.
+ *
+ * What it does NOT buy: a scene that genuinely lights a fragment from a hundred
+ * lamps pays for a hundred iterations of the loop. The distance test below
+ * rejects most of them in a few instructions, which is what makes a rig of this
+ * size affordable at all; clustering is what replaces the linear walk when a
+ * scene wants every one of them close enough to matter.
  */
-export const MAX_LIGHTS = 16
+export const MAX_LIGHTS = 128
 /** Floats in the whole buffer. */
 export const LIGHTS_FLOATS = LIGHT_HEADER + MAX_LIGHTS * LIGHT_STRIDE
 
@@ -210,6 +226,19 @@ fn lightEmitMain(@builtin(global_invocation_id) gid: vec3u) {
   _rzLightsOut[b + 4u] = c.x;
   _rzLightsOut[b + 5u] = c.y;
   _rzLightsOut[b + 6u] = c.z;
+  // An effect emits POINT lights: RzLight carries no aim, and widening it would
+  // fail to compile every emitter already written against it. The rest of the
+  // record is written anyway — these slots are reused frame to frame, and a spot
+  // the document placed here last frame would otherwise keep its cone.
+  _rzLightsOut[b + 7u] = 0.0;
+  _rzLightsOut[b + 8u] = 0.0;
+  _rzLightsOut[b + 9u] = 0.0;
+  _rzLightsOut[b + 10u] = 0.0;
+  _rzLightsOut[b + 11u] = -1.0;
+  _rzLightsOut[b + 12u] = -1.0;
+  _rzLightsOut[b + 13u] = 0.0;
+  _rzLightsOut[b + 14u] = 0.0;
+  _rzLightsOut[b + 15u] = 0.0;
 }
 `
 }
@@ -240,6 +269,19 @@ fn rzLightColor(i: u32) -> vec3f {
   return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
 }
 
+/** Where light i points, away from itself. The zero vector for a point light. */
+fn rzLightAim(i: u32) -> vec3f {
+  let b = ${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u + 8u;
+  return vec3f(_rzLights[b], _rzLights[b + 1u], _rzLights[b + 2u]);
+}
+
+/** The cosines a spot fades between: x its outer edge, y its inner one. A point
+ *  light stores (-1, -1), which saturates the cone term to 1. */
+fn rzLightCone(i: u32) -> vec2f {
+  let b = ${LIGHT_HEADER}u + i * ${LIGHT_STRIDE}u + 11u;
+  return vec2f(_rzLights[b], _rzLights[b + 1u]);
+}
+
 /**
  * Every positional light's contribution at a surface point, as light — not as a
  * finished colour. Multiply by whatever the surface's albedo is.
@@ -269,14 +311,25 @@ fn rzLightsDiffuse(p: vec3f, n: vec3f) -> vec3f {
   for (var i = 0u; i < count; i = i + 1u) {
     let d = rzLightPos(i) - p;
     let dist = length(d);
+    // Out of reach before anything else is computed. The falloff is already
+    // exactly zero at the radius, so this changes no pixel — it is what keeps a
+    // stage rig's far lamps off the bill at every fragment they do not light.
+    if (dist >= rzLightRadius(i)) { continue; }
+    let toLight = d / max(dist, 1e-4);
     // Facing the light, and nothing behind it. No wrap or half-lambert: this
     // layer adds light, and a wrapped term would lift the shadow side, which is
     // the ramp's business and not this one's.
-    let ndl = max(dot(n, d / max(dist, 1e-4)), 0.0);
+    let ndl = max(dot(n, toLight), 0.0);
     if (ndl <= 0.0) { continue; }
     let t = clamp(dist / max(rzLightRadius(i), 1e-4), 0.0, 1.0);
     let falloff = 1.0 - t * t;
-    acc = acc + rzLightColor(i) * (ndl * falloff * falloff);
+    // How far inside the cone this point sits: 1 within the inner angle, 0 past
+    // the outer one, squared for the same soft edge the falloff has. A point
+    // light's (-1, -1) divides by the floor and clamps to 1, so it pays one
+    // dot product and no branch.
+    let cone = rzLightCone(i);
+    let aim = clamp((dot(-toLight, rzLightAim(i)) - cone.x) / max(cone.y - cone.x, 1e-4), 0.0, 1.0);
+    acc = acc + rzLightColor(i) * (ndl * falloff * falloff * aim * aim);
   }
   return acc;
 }

package/src/shaders/materials/common.ts

@@ -31,7 +31,16 @@ struct CameraUniforms {
   view: mat4x4f,
   projection: mat4x4f,
   viewPos: vec3f,
-  _padding: f32,
+  /** Render-target height in device pixels. */
+  viewportHeight: f32,
+  /** The scene clock in seconds — what the time node reads. Paused with the
+   *  transport and stepped exactly by an export, so an animated material lands
+   *  in the file where it stood on screen. (No backticks in here: this WGSL
+   *  lives in a template literal and one would end it.) */
+  time: f32,
+  // NOTHING AFTER THIS. A trailing vec3f aligns to 16 and pushes the struct to
+  // 176 bytes against a 160-byte buffer, which fails validation on every
+  // pipeline at once; ending on the f32 rounds the struct to exactly 160.
 };
 
 struct Light {
@@ -127,6 +136,13 @@ struct LightVP { viewProj: array<mat4x4f, ${SHADOW_CASCADES.length}>, };
 // keeps its shadows when the crisp near volume ends. Binding 7: 6 is the
 // positional lights, 9 the BRDF LUT.
 @group(0) @binding(7) var shadowMapFar: texture_depth_2d;
+// The world's own sky, for a surface that REFLECTS it rather than merely being
+// lit by it. Equirect, in the same layout and the same linear radiance the
+// composite draws the dome from, and mipped — a rough surface reads a coarser
+// level, which is what a prefiltered environment is for. A scene with no HDRI
+// has the 1x1 fallback bound here; rzWorldSpecular checks the SH flag and
+// answers with the flat ambient instead, so nothing samples the placeholder.
+@group(0) @binding(8) var worldEnvTexture: texture_2d<f32>;
 // binding(9) brdfLut is declared inside NODES_WGSL (nodes.ts).
 @group(1) @binding(0) var<storage, read> skinMats: array<mat4x4f>;
 @group(2) @binding(0) var diffuseTexture: texture_2d<f32>;

package/src/shaders/materials/nodes.ts

@@ -290,6 +290,47 @@ fn point_world_to_camera(p: vec3f) -> vec3f { return (camera.view * vec4f(p, 1.0
 // One function per slot because WGSL has no texture arrays-of-bindings here; the
 // slot is topology, exactly like a Math node's operation.
 
+/**
+ * The world's radiance arriving from a direction — what a reflection sees.
+ *
+ * The engine's ambient is irradiance: the SH fit of the sky integrated over a
+ * hemisphere, evaluated along the NORMAL. That is the right answer for diffuse
+ * light and the wrong one for a mirror, which needs radiance along the
+ * REFLECTION vector and needs it sharp. A stage ripped from a game asks for
+ * this on nearly every surface — it is what a Unity material's DEFAULT_REFLECTION
+ * keyword means — 
+ * and so does every metal the app has ever drawn.
+ *
+ * ROUGHNESS PICKS A MIP, which is the cheap prefilter: the chain is built by
+ * successive halving at upload, so a level is a box average of the sky over a
+ * widening solid angle. A cosine-lobe convolution would be more correct; the
+ * visible difference is confined to the middle of the roughness range, and the
+ * chain costs one downsample per level instead of a render pass per level.
+ *
+ * Without an HDRI there is nothing to reflect but the flat world colour, which
+ * is what the ambient already is — so the two agree and a scene without a sky
+ * texture sees no change at all.
+ */
+fn rzWorldSpecular(dir: vec3f, roughness: f32) -> vec3f {
+  // A SKY TEXTURE, or the best the scene has. The flag is 2 when an HDRI is
+  // installed, 1 when the world is a gradient fitted to the same harmonics,
+  // and 0 when it is one flat colour — and in the last two cases the ambient
+  // already answers by direction, which is a blurred sky and exactly what a
+  // world without a picture can honestly reflect.
+  if (light.sh[0].w < 1.5) { return rzWorldAmbient(normalize(dir)); }
+  let d = normalize(dir);
+  // The composite's own convention, restated: LH world with +Z forward, which
+  // is what makes a reflection line up with the dome the viewer can see.
+  let u = 0.5 + atan2(d.x, d.z) * 0.15915494309;
+  let v = 0.5 - asin(clamp(d.y, -1.0, 1.0)) * 0.31830988618;
+  let levels = f32(textureNumLevels(worldEnvTexture) - 1u);
+  // sqrt, not linear: mip n covers roughly twice the angle of n-1, so a linear
+  // ramp spends most of its travel in the blurry end and a mirror-to-satin
+  // sweep happens entirely in the first tenth of the dial.
+  let lod = clamp(sqrt(clamp(roughness, 0.0, 1.0)) * levels, 0.0, levels);
+  return textureSampleLevel(worldEnvTexture, diffuseSampler, vec2f(u, v), lod).rgb * light.ambientColor.w;
+}
+
 fn group_tex0(uv: vec2f) -> vec4f { return textureSample(groupTexture0, diffuseSampler, uv); }
 fn group_tex1(uv: vec2f) -> vec4f { return textureSample(groupTexture1, diffuseSampler, uv); }
 fn group_tex2(uv: vec2f) -> vec4f { return textureSample(groupTexture2, diffuseSampler, uv); }