@plasius/gpu-renderer 0.2.45 → 0.2.46

package/src/native-scene-shader.js

@@ -0,0 +1,178 @@
+// Raster lighting intentionally differs from the wavefront path tracer. It makes
+// no claim of global illumination or ray tracing. All colours remain linear until
+// presentation; the generated harbour materials use continuous world-space detail.
+export const nativeSceneShader = /* wgsl */ `
+struct Frame {
+  eye: vec4f, right: vec4f, up: vec4f, forward: vec4f,
+  settings: vec4f, sun: vec4f,
+  lightRight: vec4f, lightUp: vec4f, lightForward: vec4f, lightOrigin: vec4f,
+  viewport: vec4f, wakes: array<vec4f, 4>, info: vec4f,
+};
+@group(0) @binding(0) var<uniform> frame: Frame;
+@group(1) @binding(0) var shadowMap: texture_depth_2d;
+@group(1) @binding(1) var shadowSampler: sampler_comparison;
+@group(2) @binding(0) var reflectionMap: texture_2d<f32>;
+@group(2) @binding(1) var reflectionSampler: sampler;
+struct Surface {
+  @builtin(position) clip: vec4f,
+  @location(0) world: vec3f, @location(1) normal: vec3f,
+  @location(2) colour: vec3f, @location(3) material: vec3f,
+};
+fn project(p: vec3f) -> vec4f {
+  let d = p - frame.eye.xyz;
+  let z = dot(d, frame.forward.xyz);
+  return vec4f(dot(d, frame.right.xyz) / (frame.settings.x * frame.settings.y),
+    dot(d, frame.up.xyz) / frame.settings.x, (z - 0.08) * 500.0 / 499.92, z);
+}
+fn lightProject(p: vec3f) -> vec4f {
+  let d = p - frame.lightOrigin.xyz;
+  return vec4f(dot(d, frame.lightRight.xyz) / 34.0,
+    dot(d, frame.lightUp.xyz) / 34.0, dot(d, frame.lightForward.xyz) / 100.0, 1.0);
+}
+@vertex fn surfaceVertex(@location(0) p: vec3f, @location(1) n: vec3f,
+  @location(2) c: vec3f, @location(3) m: vec3f) -> Surface {
+  return Surface(project(p), p, n, c, m);
+}
+@vertex fn shadowVertex(@location(0) p: vec3f) -> @builtin(position) vec4f {
+  return lightProject(p);
+}
+@vertex fn fullscreenVertex(@builtin(vertex_index) i: u32) -> @builtin(position) vec4f {
+  let positions = array<vec2f, 3>(vec2f(-1, -1), vec2f(3, -1), vec2f(-1, 3));
+  return vec4f(positions[i], 1, 1);
+}
+fn cameraRay(pixel: vec2f) -> vec3f {
+  let uv = pixel / frame.viewport.xy * 2.0 - 1.0;
+  return normalize(frame.forward.xyz + frame.right.xyz * uv.x * frame.settings.x * frame.settings.y
+    - frame.up.xyz * uv.y * frame.settings.x);
+}
+fn display(c: vec3f) -> vec3f {
+  let x = max(c * frame.settings.w, vec3f(0));
+  let mapped = clamp((x * (2.51 * x + 0.03)) / (x * (2.43 * x + 0.59) + 0.14), vec3f(0), vec3f(1));
+  return pow(mapped, vec3f(1.0 / 2.2));
+}
+fn hash(p: vec3f) -> f32 { return fract(sin(dot(p, vec3f(127.1, 311.7, 74.7))) * 43758.5453); }
+fn noise(p: vec3f) -> f32 {
+  let i = floor(p); let f = fract(p); let u = f * f * (3.0 - 2.0 * f);
+  return mix(mix(mix(hash(i), hash(i + vec3f(1,0,0)), u.x),
+    mix(hash(i + vec3f(0,1,0)), hash(i + vec3f(1,1,0)), u.x), u.y),
+    mix(mix(hash(i + vec3f(0,0,1)), hash(i + vec3f(1,0,1)), u.x),
+    mix(hash(i + vec3f(0,1,1)), hash(i + vec3f(1,1,1)), u.x), u.y), u.z);
+}
+fn sky(ray: vec3f) -> vec3f {
+  let elevation = pow(clamp(ray.y * 0.7 + 0.16, 0.0, 1.0), 0.6);
+  var c = mix(vec3f(0.42, 0.53, 0.61), vec3f(0.07, 0.19, 0.37), elevation);
+  let sunAngle = dot(ray, frame.sun.xyz);
+  c += vec3f(1.0, 0.73, 0.43) * pow(max(sunAngle, 0.0), 64.0) * 0.35;
+  c += vec3f(4.0, 3.2, 2.1) * smoothstep(0.99965, 0.99985, sunAngle);
+  let cloudPoint = ray / max(0.12, ray.y) * 2.1 + vec3f(0, 0, 8);
+  let cloud = smoothstep(0.49, 0.77, noise(cloudPoint) * 0.65 + noise(cloudPoint * 2.1) * 0.35);
+  c = mix(c, vec3f(0.85, 0.86, 0.82), cloud * smoothstep(0.03, 0.35, ray.y) * 0.65);
+  return c;
+}
+@fragment fn skyFragment(@builtin(position) pixel: vec4f) -> @location(0) vec4f {
+  return vec4f(display(sky(cameraRay(pixel.xy))), 1);
+}
+fn visibility(p: vec3f, n: vec3f) -> f32 {
+  let q = lightProject(p + n * 0.035).xyz;
+  let uv = vec2f(q.x * 0.5 + 0.5, 0.5 - q.y * 0.5);
+  if (any(uv < vec2f(0.005)) || any(uv > vec2f(0.995)) || q.z < 0.0 || q.z > 1.0) { return 1.0; }
+  var result = 0.0;
+  for (var y = -1; y <= 1; y++) {
+    for (var x = -1; x <= 1; x++) {
+      result += textureSampleCompareLevel(shadowMap, shadowSampler, uv + vec2f(f32(x), f32(y)) / 2048.0, q.z - 0.0006);
+    }
+  }
+  return result / 9.0;
+}
+fn brdf(c: vec3f, n: vec3f, v: vec3f, roughness: f32, metal: f32) -> vec3f {
+  let l = frame.sun.xyz; let h = normalize(l + v);
+  let nl = max(dot(n,l),0.0); let nv = max(dot(n,v),0.001);
+  let nh = max(dot(n,h),0.0); let vh = max(dot(v,h),0.0);
+  let a = max(0.035, roughness * roughness); let a2 = a * a;
+  let d = a2 / max(0.00001, 3.14159265 * pow(nh * nh * (a2 - 1.0) + 1.0, 2.0));
+  let k = pow(roughness + 1.0, 2.0) / 8.0;
+  let g = (nl / (nl * (1.0-k) + k)) * (nv / (nv * (1.0-k) + k));
+  let f0 = mix(vec3f(0.04), c, metal);
+  let f = f0 + (1.0-f0) * pow(1.0-vh, 5.0);
+  return ((1.0-f) * (1.0-metal) * c / 3.14159265 + d * g * f / max(0.001, 4.0*nl*nv)) * nl;
+}
+fn fog(c: vec3f, p: vec3f) -> vec3f {
+  let amount = 1.0 - exp(-distance(frame.eye.xyz, p) * 0.0018);
+  return mix(c, vec3f(0.32, 0.44, 0.55), amount);
+}
+fn surfaceRadiance(s: Surface, front: bool) -> vec3f {
+  let facing = select(select(-1.0,1.0,front),select(1.0,-1.0,front),frame.info.y>0.5);
+  var n = normalize(s.normal) * facing;
+  let v = normalize(frame.eye.xyz - s.world);
+  var c = s.colour;
+  if (s.material.z > 2.5) {
+    let rock = smoothstep(0.45,0.68,noise(s.world*0.27));
+    c = mix(c,vec3f(0.16,0.145,0.11),rock*0.7);
+    c *= 0.75+0.45*noise(s.world*2.4);
+    n = normalize(n+vec3f(noise(s.world*4.0)-0.5,0,noise(s.world*4.0+vec3f(13))-0.5)*0.28);
+  } else if (s.material.z > 0.5 && s.material.z < 1.5) {
+    let grain = noise(s.world * vec3f(18, 3, 1.6));
+    c *= 0.82 + 0.30 * grain;
+  } else if (s.material.z > 1.5) { c *= 0.88 + 0.18 * noise(s.world * 12.0); }
+  let hemi = mix(vec3f(0.06,0.05,0.035), vec3f(0.16,0.22,0.29), n.y * 0.5 + 0.5);
+  let direct = brdf(c, n, v, s.material.x, s.material.y) * vec3f(3.0, 2.65, 2.15) * visibility(s.world, n);
+  let ambient = c * hemi * (1.0 - s.material.y * 0.7);
+  let env = sky(reflect(-v,n)) * mix(vec3f(0.04), c, s.material.y) * (1.0-s.material.x) * 0.30;
+  return fog(direct + ambient + env, s.world);
+}
+@fragment fn surfaceFragment(s: Surface, @builtin(front_facing) front: bool) -> @location(0) vec4f {
+  return vec4f(display(surfaceRadiance(s,front)),1);
+}
+fn wave(p: vec2f) -> f32 {
+  let t = frame.settings.z;
+  return sin(dot(p,vec2f(0.35,0.23))-t*0.85)*0.13
+    + sin(dot(p,vec2f(-0.61,0.42))+t*1.12)*0.065
+    + sin(dot(p,vec2f(1.2,0.83))-t*1.4)*0.025
+    + sin(dot(p,vec2f(3.1,-2.1))+t*1.8)*0.009;
+}
+struct WaterResult { @location(0) colour: vec4f, @builtin(frag_depth) depth: f32 };
+@fragment fn waterFragment(@builtin(position) pixel: vec4f) -> WaterResult {
+  let ray = cameraRay(pixel.xy);
+  if (ray.y > -0.001) { discard; }
+  var dist = (frame.viewport.z - frame.eye.y) / ray.y;
+  var p = frame.eye.xyz + ray * dist;
+  for (var i=0; i<3; i++) {
+    dist = (frame.viewport.z + wave(p.xz) - frame.eye.y) / ray.y;
+    p = frame.eye.xyz + ray * dist;
+  }
+  if (dist < 0.08 || dist > 499.0) { discard; }
+  let eps = 0.03;
+  let waveNormal = normalize(vec3f((wave(p.xz-vec2f(eps,0))-wave(p.xz+vec2f(eps,0)))/(2.0*eps),
+    1.0, (wave(p.xz-vec2f(0,eps))-wave(p.xz+vec2f(0,eps)))/(2.0*eps)));
+  let n = normalize(mix(waveNormal,vec3f(0,1,0),smoothstep(35.0,150.0,dist)));
+  let v = -ray;
+  let fresnel = 0.02 + 0.98 * pow(1.0-max(dot(n,v),0.0),5.0);
+  let uv = clamp(pixel.xy / frame.viewport.xy + n.xz * 0.018, vec2f(0.002), vec2f(0.998));
+  // Reflection target is HDR linear; tone mapping happens once after mixing.
+  let reflected = textureSampleLevel(reflectionMap, reflectionSampler, uv, 0).rgb;
+  let shadow = visibility(p, n);
+  var c = mix(vec3f(0.008,0.05,0.065) * (0.5+0.5*shadow), reflected, fresnel);
+  c += brdf(vec3f(0.01),n,v,0.14,0.0) * vec3f(2.5,2.15,1.7) * shadow;
+  var foam = 0.0;
+  for (var i=0u; i<4u; i++) {
+    if (f32(i) >= frame.info.x) { break; }
+    let w = frame.wakes[i]; let delta = p.xz - w.xy;
+    let along = dot(delta, vec2f(sin(w.z), cos(w.z)));
+    let across = abs(dot(delta,vec2f(cos(w.z),-sin(w.z))));
+    let ribbon = exp(-pow((across - max(0.0,-along)*0.28 - 0.65)*4.0,2.0));
+    foam += ribbon * (1.0-smoothstep(-1.0,0.5,along)) * exp(min(0.0,along)*0.25) * (0.4+0.6*noise(vec3f(p.x*5.0,p.z*5.0,frame.settings.z*0.5)));
+  }
+  c = mix(c,vec3f(0.48,0.61,0.62),clamp(foam*0.42,0.0,0.55));
+  let clip = project(p);
+  return WaterResult(vec4f(display(fog(c,p)),1),clip.z/clip.w);
+}
+// Keep reflection radiance linear, including sky. Reusing the lighting calculation
+// rather than sampling a screenshot avoids double tone mapping on the water.
+@fragment fn reflectionSky(@builtin(position) pixel: vec4f) -> @location(0) vec4f {
+  return vec4f(sky(cameraRay(pixel.xy)),1);
+}
+@fragment fn reflectionSurface(s: Surface, @builtin(front_facing) front: bool) -> @location(0) vec4f {
+  if (s.world.y < frame.viewport.z) { discard; }
+  return vec4f(surfaceRadiance(s,front),1);
+}
+`;

package/src/renderer-webgpu-runtime.js

@@ -260,6 +260,7 @@ export async function createGpuRenderer(options = {}) {
     cancelAnimationFrame = globalThis.cancelAnimationFrame?.bind(globalThis),
     frameIdFactory,
     onFrameStart,
+    encodeFrame,
     onBeforeEncode,
     onAfterSubmit,
     onFrameComplete,
@@ -337,26 +338,30 @@ export async function createGpuRenderer(options = {}) {
     });
     const view = texture.createView();
 
-    const pass = encoder.beginRenderPass(createRenderPassDescriptor(view, clear));
-
-    if (typeof onBeforeEncode === "function") {
-      onBeforeEncode({
-        frame,
-        frameNumber,
-        frameId,
-        frameTimeMs,
-        timestamp,
-        device,
-        context,
-        encoder,
-        pass,
-        canvas: targetCanvas,
-        xrActive,
-      });
-    }
+    if (typeof encodeFrame === "function") {
+      encodeFrame({ device, context, encoder, view, canvas: targetCanvas, timestamp });
+    } else {
+      const pass = encoder.beginRenderPass(createRenderPassDescriptor(view, clear));
+
+      if (typeof onBeforeEncode === "function") {
+        onBeforeEncode({
+          frame,
+          frameNumber,
+          frameId,
+          frameTimeMs,
+          timestamp,
+          device,
+          context,
+          encoder,
+          pass,
+          canvas: targetCanvas,
+          xrActive,
+        });
+      }
 
-    if (typeof pass.end === "function") {
-      pass.end();
+      if (typeof pass.end === "function") {
+        pass.end();
+      }
     }
 
     const commandBuffer = encoder.finish();

package/src/wavefront-adaptive-byte-constants.js

@@ -0,0 +1,28 @@
+// Generated from final adaptive WGSL by @plasius/gpu-shader; checked by tests.
+// Source SHA-256: 2d2782a19c480564ae5bde52123e2dc8de4db3fcab818e26cc7ad743c6934821
+export const ADAPTIVE_DISPATCH_ARGUMENTS_ALIGNMENT = 4;
+export const ADAPTIVE_DISPATCH_ARGUMENTS_BYTE_SIZE = 12;
+export const ADAPTIVE_DISPATCH_ARGUMENTS_MINIMUM_BYTE_SIZE = 12;
+export const ADAPTIVE_DISPATCH_ARGUMENTS_X_OFFSET = 0;
+export const ADAPTIVE_DISPATCH_ARGUMENTS_Y_OFFSET = 4;
+export const ADAPTIVE_DISPATCH_ARGUMENTS_Z_OFFSET = 8;
+export const ADAPTIVE_FIRST_HIT_DISTANCE_ALIGNMENT = 4;
+export const ADAPTIVE_FIRST_HIT_DISTANCE_BYTE_SIZE = 4;
+export const ADAPTIVE_FIRST_HIT_DISTANCE_MINIMUM_BYTE_SIZE = 4;
+export const ADAPTIVE_FIRST_HIT_DISTANCE_DISTANCE_OFFSET = 0;
+export const ADAPTIVE_HISTORY_WORD_ALIGNMENT = 4;
+export const ADAPTIVE_HISTORY_WORD_BYTE_SIZE = 4;
+export const ADAPTIVE_HISTORY_WORD_MINIMUM_BYTE_SIZE = 4;
+export const ADAPTIVE_HISTORY_WORD_MASK_OFFSET = 0;
+export const ADAPTIVE_NORMAL_MATERIAL_RISK_ALIGNMENT = 4;
+export const ADAPTIVE_NORMAL_MATERIAL_RISK_BYTE_SIZE = 4;
+export const ADAPTIVE_NORMAL_MATERIAL_RISK_MINIMUM_BYTE_SIZE = 4;
+export const ADAPTIVE_NORMAL_MATERIAL_RISK_WORD_OFFSET = 0;
+export const ADAPTIVE_PIXEL_STATE_ALIGNMENT = 4;
+export const ADAPTIVE_PIXEL_STATE_BYTE_SIZE = 4;
+export const ADAPTIVE_PIXEL_STATE_MINIMUM_BYTE_SIZE = 4;
+export const ADAPTIVE_PIXEL_STATE_WORD_OFFSET = 0;
+export const ADAPTIVE_WORKLIST_ENTRY_ALIGNMENT = 4;
+export const ADAPTIVE_WORKLIST_ENTRY_BYTE_SIZE = 4;
+export const ADAPTIVE_WORKLIST_ENTRY_MINIMUM_BYTE_SIZE = 4;
+export const ADAPTIVE_WORKLIST_ENTRY_LOCAL_PIXEL_ID_OFFSET = 0;

package/src/wavefront-adaptive-metadata.js

@@ -0,0 +1,185 @@
+import {
+  ADAPTIVE_COUNT_BITS, ADAPTIVE_COUNT_MASK, ADAPTIVE_FLAG_SHIFT,
+  ADAPTIVE_MAX_FLAGS, ADAPTIVE_MAX_SAMPLES,
+} from "./wavefront-adaptive-shader.js";
+import {
+  ADAPTIVE_PIXEL_STATE_BYTE_SIZE, ADAPTIVE_FIRST_HIT_DISTANCE_BYTE_SIZE,
+  ADAPTIVE_NORMAL_MATERIAL_RISK_BYTE_SIZE, ADAPTIVE_WORKLIST_ENTRY_BYTE_SIZE,
+  ADAPTIVE_HISTORY_WORD_BYTE_SIZE, ADAPTIVE_DISPATCH_ARGUMENTS_BYTE_SIZE,
+} from "./wavefront-adaptive-byte-constants.js";
+
+export const DEFAULT_ADAPTIVE_ALLOCATION_CAP_BYTES = 128 * 1024 ** 2;
+const MAX_TILE_PIXELS = 16384;
+const U32_MAX = 0xffffffff;
+
+function integer(name, value, minimum, maximum) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new RangeError(`${name} must be an integer in ${minimum}..${maximum}.`);
+  }
+  return value;
+}
+
+export function packAdaptivePixelState({ requested, completed = 0, flags = 0 }) {
+  integer("requested", requested, 0, ADAPTIVE_MAX_SAMPLES);
+  integer("completed", completed, 0, requested);
+  integer("flags", flags, 0, ADAPTIVE_MAX_FLAGS);
+  return (requested | (completed << ADAPTIVE_COUNT_BITS) | (flags << ADAPTIVE_FLAG_SHIFT)) >>> 0;
+}
+
+export function unpackAdaptivePixelState(word) {
+  integer("packed adaptive word", word, 0, U32_MAX);
+  const state = {
+    requested: word & ADAPTIVE_COUNT_MASK,
+    completed: (word >>> ADAPTIVE_COUNT_BITS) & ADAPTIVE_COUNT_MASK,
+    flags: word >>> ADAPTIVE_FLAG_SHIFT,
+  };
+  // Do not silently accept unused nine-bit values or impossible completion.
+  packAdaptivePixelState(state);
+  return Object.freeze(state);
+}
+
+function refuse(plan, reason) {
+  return Object.freeze({ ...plan, enabled: false, reason });
+}
+
+function admitDevice(plan, limits) {
+  if (!plan.enabled) return plan;
+  const maxBufferSize = limits?.maxBufferSize;
+  const maxBindingSize = limits?.maxStorageBufferBindingSize;
+  if (![maxBufferSize, maxBindingSize].every((value) => Number.isSafeInteger(value) && value > 0)) {
+    return refuse(plan, "adaptive-device-limits-unavailable");
+  }
+  if (plan.buffers.some(({ size }) => size > maxBufferSize || size > maxBindingSize)) {
+    return refuse(plan, "adaptive-device-buffer-limit");
+  }
+  return plan;
+}
+
+export function planAdaptiveResources(options = {}, limits) {
+  const bytes = {
+    pixelState: 0, firstHitDistance: 0, normalMaterialRisk: 0,
+    worklist: 0, dispatch: 0, history: 0, total: 0,
+  };
+  if (options.enabled !== true) {
+    return Object.freeze({ enabled: false, reason: "adaptive-disabled",
+      bytes: Object.freeze(bytes), buffers: Object.freeze([]) });
+  }
+  for (const key of ["firstHitDistance", "normalMaterialRisk", "history"]) {
+    if (options[key] !== undefined && typeof options[key] !== "boolean") {
+      throw new TypeError(`${key} must be a boolean.`);
+    }
+  }
+  const width = integer("width", options.width, 1, U32_MAX);
+  const height = integer("height", options.height, 1, U32_MAX);
+  const pixelCount = integer("pixelCount", width * height, 1, U32_MAX);
+  const tilePixelCapacity = integer("tilePixelCapacity",
+    options.tilePixelCapacity === undefined ? MAX_TILE_PIXELS : options.tilePixelCapacity, 1, MAX_TILE_PIXELS);
+  const cap = integer("maximumAllocationBytes", options.maximumAllocationBytes === undefined
+    ? DEFAULT_ADAPTIVE_ALLOCATION_CAP_BYTES : options.maximumAllocationBytes, 1, Number.MAX_SAFE_INTEGER);
+  bytes.pixelState = pixelCount * ADAPTIVE_PIXEL_STATE_BYTE_SIZE;
+  bytes.firstHitDistance = options.firstHitDistance === true ? pixelCount * ADAPTIVE_FIRST_HIT_DISTANCE_BYTE_SIZE : 0;
+  bytes.normalMaterialRisk = options.normalMaterialRisk === true ? pixelCount * ADAPTIVE_NORMAL_MATERIAL_RISK_BYTE_SIZE : 0;
+  bytes.worklist = tilePixelCapacity * ADAPTIVE_WORKLIST_ENTRY_BYTE_SIZE;
+  bytes.dispatch = ADAPTIVE_DISPATCH_ARGUMENTS_BYTE_SIZE;
+  bytes.history = options.history === true ? 2 * Math.ceil(pixelCount / 32) * ADAPTIVE_HISTORY_WORD_BYTE_SIZE : 0;
+  bytes.total = Object.values(bytes).reduce((sum, value) => sum + value, 0);
+  const buffers = ["pixelState", "firstHitDistance", "normalMaterialRisk", "worklist", "dispatch"]
+    .filter((key) => bytes[key] > 0)
+    .map((key) => Object.freeze({ key, size: bytes[key], indirect: key === "dispatch" }));
+  if (bytes.history) {
+    for (const key of ["previousHistory", "currentHistory"]) {
+      buffers.push(Object.freeze({ key, size: bytes.history / 2, indirect: false }));
+    }
+  }
+  const plan = Object.freeze({ enabled: true, reason: null, pixelCount, tilePixelCapacity,
+    maximumAllocationBytes: cap, bytes: Object.freeze(bytes), buffers: Object.freeze(buffers) });
+  if (bytes.total > cap) return refuse(plan, "adaptive-allocation-cap");
+  return limits === undefined ? plan : admitDevice(plan, limits);
+}
+
+export function createAdaptiveResourceOwner(device, usage, options = {}) {
+  // Snapshot configuration now; a caller cannot expand the allocation while it is pending.
+  let plan = planAdaptiveResources(options);
+  let disposed = false;
+  let pending = null;
+  let result = null;
+  let allocatedBytes = 0;
+  const buffers = new Map();
+
+  function cleanup() {
+    for (const buffer of buffers.values()) buffer.destroy();
+    buffers.clear();
+    allocatedBytes = 0;
+  }
+
+  function disabled(reason) {
+    result = Object.freeze({ status: "disabled", reason, buffers: Object.freeze({}), allocatedBytes: 0 });
+    return result;
+  }
+
+  async function allocate() {
+    if (disposed) return disabled("adaptive-disposed");
+    if (!plan.enabled) return disabled(plan.reason);
+    plan = admitDevice(plan, device?.limits);
+    if (!plan.enabled) return disabled(plan.reason);
+    if (typeof device.pushErrorScope !== "function" || typeof device.popErrorScope !== "function") {
+      return disabled("adaptive-error-scopes-unavailable");
+    }
+    let scopeCount = 0;
+    let failed = false;
+    try {
+      for (const key of ["STORAGE", "COPY_DST", "INDIRECT"]) integer(`GPUBufferUsage.${key}`, usage?.[key], 1, U32_MAX);
+      device.pushErrorScope("out-of-memory");
+      scopeCount += 1;
+      device.pushErrorScope("validation");
+      scopeCount += 1;
+      for (const descriptor of plan.buffers) {
+        const buffer = device.createBuffer({
+          label: `wavefront-adaptive-${descriptor.key}`,
+          size: descriptor.size,
+          usage: usage.STORAGE | usage.COPY_DST | (descriptor.indirect ? usage.INDIRECT : 0),
+        });
+        buffers.set(descriptor.key, buffer);
+        allocatedBytes += descriptor.size;
+      }
+    } catch {
+      failed = true;
+    }
+    // Pop both scopes synchronously before awaiting: scopes are a device-wide stack.
+    const completions = [];
+    while (scopeCount > 0) {
+      scopeCount -= 1;
+      try { completions.push(Promise.resolve(device.popErrorScope())); }
+      catch { failed = true; }
+    }
+    const errors = await Promise.allSettled(completions);
+    failed ||= errors.some((entry) => entry.status === "rejected" || entry.value !== null);
+    if (failed || disposed) {
+      cleanup();
+      return disabled(disposed ? "adaptive-disposed" : "adaptive-allocation-failed");
+    }
+    result = Object.freeze({ status: "ready", reason: null,
+      buffers: Object.freeze(Object.fromEntries(buffers)), allocatedBytes });
+    return result;
+  }
+
+  function acquire() {
+    if (disposed && !pending) return Promise.resolve(disabled("adaptive-disposed"));
+    if (result) return Promise.resolve(result);
+    // No automatic retry after allocation failure: the caller owns recovery.
+    pending ??= allocate().finally(() => { pending = null; });
+    return pending;
+  }
+
+  return Object.freeze({
+    acquire,
+    snapshot: () => Object.freeze({ plan, allocatedBytes, disposed,
+      status: disposed ? "disposed" : result?.status ?? "unallocated",
+      reason: disposed ? "adaptive-disposed" : result?.reason ?? plan.reason }),
+    destroy() {
+      if (disposed) return;
+      disposed = true;
+      cleanup();
+    },
+  });
+}

package/src/wavefront-adaptive-shader.js

@@ -0,0 +1,28 @@
+// Bit semantics are shared by CPU packing and final assembled WGSL.
+export const ADAPTIVE_COUNT_BITS = 9;
+export const ADAPTIVE_COUNT_MASK = (1 << ADAPTIVE_COUNT_BITS) - 1;
+export const ADAPTIVE_FLAG_SHIFT = ADAPTIVE_COUNT_BITS * 2;
+export const ADAPTIVE_MAX_FLAGS = 2 ** (32 - ADAPTIVE_FLAG_SHIFT) - 1;
+export const ADAPTIVE_MAX_SAMPLES = 256;
+
+export const ADAPTIVE_METADATA_WGSL = `
+const ADAPTIVE_COUNT_MASK: u32 = ${ADAPTIVE_COUNT_MASK}u;
+const ADAPTIVE_COMPLETED_SHIFT: u32 = ${ADAPTIVE_COUNT_BITS}u;
+
+struct AdaptivePixelState { word: u32, };
+struct AdaptivePixelStates { records: array<AdaptivePixelState>, };
+struct AdaptiveFirstHitDistance { distance: f32, };
+struct AdaptiveNormalMaterialRisk { word: u32, };
+struct AdaptiveWorklistEntry { localPixelId: u32, };
+struct AdaptiveHistoryWord { mask: u32, };
+struct AdaptiveDispatchArguments { x: u32, y: u32, z: u32, };
+
+@group(0) @binding(0) var<storage, read_write> pixels: AdaptivePixelStates;
+
+@compute @workgroup_size(64)
+fn reset_adaptive_counts(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= arrayLength(&pixels.records)) { return; }
+  // Budgets were selected before contributing samples. Preserve them and flags.
+  pixels.records[id.x].word &= ~(ADAPTIVE_COUNT_MASK << ADAPTIVE_COMPLETED_SHIFT);
+}
+`;