@plasius/gpu-renderer 0.2.47 → 0.2.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-renderer",
-  "version": "0.2.47",
+  "version": "0.2.49",
   "description": "Framework-agnostic WebGPU renderer runtime for Plasius projects.",
   "type": "module",
   "sideEffects": false,
@@ -89,7 +89,7 @@
     }
   ],
   "overrides": {
-    "brace-expansion": "5.0.9",
+    "brace-expansion": "5.0.12",
     "esbuild": "^0.28.1",
     "minimatch": "^10.2.1"
   },

package/src/index.d.ts

@@ -869,6 +869,7 @@ export interface WavefrontEnvironmentMapSnapshot {
 }
 
 export interface WavefrontPathTracingComputeConfig {
+  readonly progressive: boolean;
   readonly mode: typeof rendererWavefrontComputeMode;
   readonly width: number;
   readonly height: number;
@@ -1036,6 +1037,7 @@ export interface WavefrontPathTracingMemoryEstimate {
   readonly queuePairBytes: number;
   readonly hitBytes: number;
   readonly accumulationBytes: number;
+  readonly progressiveBytes: number;
   readonly pathVertexBytes: number;
   readonly sceneObjectBytes: number;
   readonly triangleBytes: number;
@@ -1097,6 +1099,8 @@ export interface WavefrontGpuParallelismDiagnostics {
 }
 
 export interface CreateWavefrontPathTracingComputeRendererOptions {
+  /** Accumulate linear radiance between frames until camera/scene/reset changes. Default false. */
+  readonly progressive?: boolean;
   readonly canvas?: HTMLCanvasElement | string;
   readonly navigator?: Navigator | { gpu?: GPU };
   readonly document?: Document;
@@ -1160,7 +1164,8 @@ export interface WavefrontPathTracingComputeRenderer {
   readonly device: GPUDevice;
   readonly format: GPUTextureFormat | string;
   readonly config: WavefrontPathTracingComputeConfig;
-  renderOnce(): WavefrontPathTracingComputeFrameStats;
+  renderOnce(options?: { samplesPerPixel?: number }): WavefrontPathTracingComputeFrameStats;
+  resetAccumulation(): void;
   renderFrame(options?: {
     readStats?: boolean;
     readOutputProbe?: boolean;
@@ -1182,6 +1187,8 @@ export interface WavefrontPathTracingComputeRenderer {
   updateSceneObjects(sceneObjects: readonly WavefrontSceneObjectInput[]): WavefrontPathTracingComputeConfig;
   updateCamera(camera: WavefrontCameraOptions): WavefrontPathTracingComputeConfig;
   getSnapshot(): Readonly<{
+    /** Submitted samples; await GPU completion before reporting completed progress. */
+    accumulatedSamplesPerPixel: number;
     frame: number;
     width: number;
     height: number;
@@ -1607,9 +1614,34 @@ export interface RendererSnapshot {
   xrActive: boolean;
 }
 
+/** Decoded RGBA8 image, matching gpu-shared glTF material textures. */
+export interface NativeSurfaceImage {
+  width: number;
+  height: number;
+  data: Uint8Array | Uint8ClampedArray;
+}
+export interface NativeSurfaceMaterial {
+  /** sRGB colour; RGB is multiplied by each vertex's linear base-colour factor. */
+  baseColor?: NativeSurfaceImage;
+  /** Linear, OpenGL-style tangent-space normal map. */
+  normal?: NativeSurfaceImage;
+  /** Linear R occlusion, G roughness, B metalness. */
+  orm?: NativeSurfaceImage;
+  normalScale?: number;
+  /** Independent dielectric coating strength, 0–1; defaults to 0 (off). */
+  clearcoat?: number;
+  /** Coating roughness, 0–1; independent of the base map; defaults to 0. */
+  clearcoatRoughness?: number;
+  /** Linear RGBA8: R multiplies clearcoat, G multiplies clearcoatRoughness; B/A ignored. White when omitted. */
+  clearcoatMap?: NativeSurfaceImage;
+}
 /** Interleaved world-space triangles: position, normal, linear colour, roughness/metalness/detail. */
 export interface NativeSceneFrame {
   vertices: Float32Array;
+  /** Two UV components per vertex. Required when surfaces are supplied. */
+  texcoords?: Float32Array;
+  /** Contiguous triangle ranges covering all vertices, using zero-based materials. */
+  surfaces?: { firstVertex: number; vertexCount: number; materialIndex: number }[];
   camera: { eye: [number, number, number]; target: [number, number, number]; fov?: number };
   time?: number;
   water?: boolean;
@@ -1630,6 +1662,8 @@ export function createNativeSceneRenderer(options: {
   canvas: HTMLCanvasElement;
   navigator?: Navigator | { gpu?: GPU };
   maxVertices?: number;
+  /** At most 16 materials, 64 MiB decoded RGBA8 total; maps are power-of-two, up to 2048. */
+  materials?: NativeSurfaceMaterial[];
   onUnavailable?: (message: string) => void;
 }): Promise<{
   render(frame: NativeSceneFrame): NativeSceneSnapshot;
@@ -2053,3 +2087,6 @@ export const rendererWorkerProfiles: Readonly<
 export const rendererWorkerManifests: Readonly<
   Record<RendererWorkerProfileName, RendererWorkerManifest>
 >;
+
+/** Validate native materials and bounded decoded maps without GPU allocation. */
+export declare function validateNativeSurfaceMaterials(materials: NativeSurfaceMaterial[]): void;

package/src/index.js

@@ -89,3 +89,5 @@ export {
   defaultRendererClearColor,
   supportsWebGpu,
 } from "./renderer-webgpu-runtime.js";
+
+export { validateNativeMaterials as validateNativeSurfaceMaterials } from './native-surface-materials.js';

package/src/native-scene-renderer.js

@@ -1,5 +1,9 @@
 import { createGpuRenderer } from "./renderer-webgpu-runtime.js";
 import { nativeSceneShader } from "./native-scene-shader.js";
+import {
+  validateNativeMaterials,
+  createNativeMaterialTextures,
+} from "./native-surface-materials.js";
 
 const STRIDE = 12;
 const UNIFORM_BYTES = 256;
@@ -17,7 +21,7 @@ const unit = (a) => {
 const finiteVector = (a) =>
   Array.isArray(a) && a.length === 3 && a.every(Number.isFinite);
 
-function validateFrame(frame, maxVertices) {
+function validateFrame(frame, maxVertices, materialCount) {
   const { vertices, camera, time = 0 } = frame ?? {};
   if (
     !(vertices instanceof Float32Array) ||
@@ -56,6 +60,48 @@ function validateFrame(frame, maxVertices) {
       "wakes must contain at most four finite [x, z, heading] entries.",
     );
   }
+  const count = vertices.length / STRIDE;
+  if (
+    frame.texcoords !== undefined &&
+    (!(frame.texcoords instanceof Float32Array) ||
+      frame.texcoords.length !== count * 2 ||
+      !frame.texcoords.every(Number.isFinite))
+  ) {
+    throw new Error(
+      "texcoords must contain two finite coordinates per vertex.",
+    );
+  }
+  if (frame.surfaces !== undefined) {
+    if (
+      !Array.isArray(frame.surfaces) ||
+      frame.surfaces.length > 256 ||
+      !frame.texcoords
+    ) {
+      throw new Error(
+        "surfaces require texcoords and at most 256 contiguous draw ranges.",
+      );
+    }
+    let end = 0;
+    for (const range of frame.surfaces) {
+      if (
+        !range ||
+        range.firstVertex !== end ||
+        !Number.isInteger(range.vertexCount) ||
+        range.vertexCount <= 0 ||
+        range.vertexCount % 3 !== 0 ||
+        !Number.isInteger(range.materialIndex) ||
+        range.materialIndex < 0 ||
+        range.materialIndex >= materialCount
+      ) {
+        throw new Error(
+          "surface ranges must cover triangles in order and reference a valid material.",
+        );
+      }
+      end += range.vertexCount;
+    }
+    if (end !== count)
+      throw new Error("surface ranges must cover every vertex exactly once.");
+  }
   return { ...frame, time };
 }
 
@@ -106,6 +152,9 @@ function frameUniforms(frame, width, height, reflected = false) {
 /** Native raster surfaces. The caller owns simulation, animation and scheduling. */
 export async function createNativeSceneRenderer(options = {}) {
   const maxVertices = options.maxVertices ?? 300_000;
+  const materials = options.materials ?? [];
+  validateNativeMaterials(materials);
+  const materialCount = materials.length;
   if (
     !Number.isInteger(maxVertices) ||
     maxVertices < 3 ||
@@ -118,6 +167,7 @@ export async function createNativeSceneRenderer(options = {}) {
   let available = true;
   let targets = null;
   let vertexBuffer = null;
+  let uvBuffer = null;
   let vertexCapacity = 0;
   let pendingFrame = null;
   let submittedFrames = 0;
@@ -186,6 +236,63 @@ export async function createNativeSceneRenderer(options = {}) {
         { binding: 1, visibility: 2, sampler: { type: "filtering" } },
       ],
     });
+    const materialLayout = device.createBindGroupLayout({
+      entries: [
+        ...[0, 1, 2, 5].map((binding) => ({
+          binding,
+          visibility: 2,
+          texture: { sampleType: "float" },
+        })),
+        { binding: 3, visibility: 2, sampler: { type: "filtering" } },
+        {
+          binding: 4,
+          visibility: 2,
+          buffer: { type: "uniform", minBindingSize: 16 },
+        },
+      ],
+    });
+    const materialSampler = device.createSampler({
+      addressModeU: "repeat",
+      addressModeV: "repeat",
+      minFilter: "linear",
+      magFilter: "linear",
+      mipmapFilter: "linear",
+      maxAnisotropy: 4,
+    });
+    const materialGroups = createNativeMaterialTextures(
+      device,
+      materials,
+      own,
+    ).map((material) => {
+      const params = own(
+        device.createBuffer({
+          size: 16,
+          usage: 0x48,
+          label: "native.material-parameters",
+        }),
+      );
+      device.queue.writeBuffer(
+        params,
+        0,
+        new Float32Array([
+          material.normalScale,
+          material.authored ? 1 : 0,
+          material.clearcoat,
+          material.clearcoatRoughness,
+        ]),
+      );
+      return device.createBindGroup({
+        layout: materialLayout,
+        entries: [
+          { binding: 0, resource: material.baseColor },
+          { binding: 1, resource: material.normal },
+          { binding: 2, resource: material.orm },
+          { binding: 3, resource: materialSampler },
+          { binding: 4, resource: { buffer: params } },
+          { binding: 5, resource: material.clearcoatMap },
+        ],
+      });
+    });
     const uniformBuffer = own(
       device.createBuffer({
         label: "native.frame",
@@ -267,6 +374,20 @@ export async function createNativeSceneRenderer(options = {}) {
                         ? attributes.slice(0, 1)
                         : attributes,
                   },
+                  ...(vertex === "shadowVertex"
+                    ? []
+                    : [
+                        {
+                          arrayStride: 8,
+                          attributes: [
+                            {
+                              shaderLocation: 4,
+                              offset: 0,
+                              format: "float32x2",
+                            },
+                          ],
+                        },
+                      ]),
                 ],
               }
             : {}),
@@ -303,7 +424,7 @@ export async function createNativeSceneRenderer(options = {}) {
       "surfaceFragment",
       format,
       4,
-      [uniformLayout, shadowLayout],
+      [uniformLayout, shadowLayout, materialLayout],
       true,
     );
     const skyPipeline = await pipeline(
@@ -320,7 +441,7 @@ export async function createNativeSceneRenderer(options = {}) {
       "waterFragment",
       format,
       4,
-      [uniformLayout, shadowLayout, reflectionLayout],
+      [uniformLayout, shadowLayout, materialLayout, reflectionLayout],
     );
     const reflectedSurfacePipeline = await pipeline(
       "reflection-surface",
@@ -328,7 +449,7 @@ export async function createNativeSceneRenderer(options = {}) {
       "reflectionSurface",
       "rgba16float",
       1,
-      [uniformLayout, shadowLayout],
+      [uniformLayout, shadowLayout, materialLayout],
       true,
     );
     const reflectedSkyPipeline = await pipeline(
@@ -434,7 +555,20 @@ export async function createNativeSceneRenderer(options = {}) {
         if (p !== shadowPipeline) pass.setBindGroup(1, shadowGroup);
         if (vertexCount > 0) {
           pass.setVertexBuffer(0, vertexBuffer);
-          pass.draw(vertexCount);
+          if (p === shadowPipeline) {
+            pass.draw(vertexCount);
+          } else {
+            pass.setVertexBuffer(1, uvBuffer);
+            if (pendingFrame.surfaces) {
+              for (const range of pendingFrame.surfaces) {
+                pass.setBindGroup(2, materialGroups[range.materialIndex + 1]);
+                pass.draw(range.vertexCount, 1, range.firstVertex);
+              }
+            } else {
+              pass.setBindGroup(2, materialGroups[0]);
+              pass.draw(vertexCount);
+            }
+          }
         }
       };
       const shadowPass = encoder.beginRenderPass({
@@ -480,7 +614,8 @@ export async function createNativeSceneRenderer(options = {}) {
       if (pendingFrame.water !== false) {
         pass.setPipeline(waterPipeline);
         pass.setBindGroup(1, shadowGroup);
-        pass.setBindGroup(2, targets.reflectionGroup);
+        pass.setBindGroup(2, materialGroups[0]);
+        pass.setBindGroup(3, targets.reflectionGroup);
         pass.draw(3);
       }
       drawGeometry(pass, surfacePipeline, mainGroup);
@@ -491,15 +626,23 @@ export async function createNativeSceneRenderer(options = {}) {
       render(input) {
         if (destroyed) throw new Error("Native scene renderer was destroyed.");
         if (!available) throw new Error("WebGPU device was lost.");
-        pendingFrame = validateFrame(input, maxVertices);
+        pendingFrame = validateFrame(input, maxVertices, materialCount);
         const data = pendingFrame.vertices;
         ensureTargets();
         if (data.byteLength > vertexCapacity) {
           if (vertexBuffer) release(vertexBuffer);
+          if (uvBuffer) release(uvBuffer);
           vertexCapacity = Math.min(
             maxVertices * STRIDE * 4,
             Math.max(4096, 2 ** Math.ceil(Math.log2(data.byteLength))),
           );
+          uvBuffer = own(
+            device.createBuffer({
+              label: "native.surface-uvs",
+              size: Math.ceil(vertexCapacity / (STRIDE * 4)) * 8,
+              usage: 0x28,
+            }),
+          );
           vertexBuffer = own(
             device.createBuffer({
               label: "native.surface-vertices",
@@ -508,6 +651,8 @@ export async function createNativeSceneRenderer(options = {}) {
             }),
           );
         }
+        if (pendingFrame.texcoords?.byteLength)
+          device.queue.writeBuffer(uvBuffer, 0, pendingFrame.texcoords);
         vertexCount = data.length / STRIDE;
         if (data.byteLength) device.queue.writeBuffer(vertexBuffer, 0, data);
         device.queue.writeBuffer(

package/src/native-scene-shader.js

@@ -11,12 +11,18 @@ struct Frame {
 @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;
+@group(3) @binding(0) var reflectionMap: texture_2d<f32>;
+@group(3) @binding(1) var reflectionSampler: sampler;
+@group(2) @binding(0) var baseColourMap: texture_2d<f32>;
+@group(2) @binding(1) var normalMap: texture_2d<f32>;
+@group(2) @binding(2) var ormMap: texture_2d<f32>;
+@group(2) @binding(3) var materialSampler: sampler;
+@group(2) @binding(4) var<uniform> materialParameters: vec4f;
+@group(2) @binding(5) var clearcoatMap: texture_2d<f32>;
 struct Surface {
   @builtin(position) clip: vec4f,
   @location(0) world: vec3f, @location(1) normal: vec3f,
-  @location(2) colour: vec3f, @location(3) material: vec3f,
+  @location(2) colour: vec3f, @location(3) material: vec3f, @location(4) uv: vec2f,
 };
 fn project(p: vec3f) -> vec4f {
   let d = p - frame.eye.xyz;
@@ -30,8 +36,8 @@ fn lightProject(p: vec3f) -> vec4f {
     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);
+  @location(2) c: vec3f, @location(3) m: vec3f, @location(4) uv: vec2f) -> Surface {
+  return Surface(project(p), p, n, c, m, uv);
 }
 @vertex fn shadowVertex(@location(0) p: vec3f) -> @builtin(position) vec4f {
   return lightProject(p);
@@ -84,17 +90,25 @@ fn visibility(p: vec3f, n: vec3f) -> f32 {
   }
   return result / 9.0;
 }
-fn brdf(c: vec3f, n: vec3f, v: vec3f, roughness: f32, metal: f32) -> vec3f {
+// Dielectric coating is evaluated independently from the coloured substrate.
+// This returns the microfacet lobe without Fresnel, including the cosine term.
+fn specularLobe(n: vec3f, v: vec3f, roughness: f32) -> f32 {
   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 nh = max(dot(n,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));
+  return d * g / max(0.001, 4.0*nl*nv) * nl;
+}
+fn brdf(c: vec3f, n: vec3f, v: vec3f, roughness: f32, metal: f32) -> vec3f {
+  let h = normalize(frame.sun.xyz + v);
+  let nl = max(dot(n,frame.sun.xyz),0.0);
+  let vh = max(dot(v,h),0.0);
   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;
+  return (1.0-f) * (1.0-metal) * c / 3.14159265 * nl + specularLobe(n,v,roughness) * f;
 }
 fn fog(c: vec3f, p: vec3f) -> vec3f {
   let amount = 1.0 - exp(-distance(frame.eye.xyz, p) * 0.0018);
@@ -102,23 +116,58 @@ fn fog(c: vec3f, p: vec3f) -> vec3f {
 }
 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 coatNormal = normalize(s.normal) * facing;
+  var n = coatNormal;
   let v = normalize(frame.eye.xyz - s.world);
-  var c = s.colour;
-  if (s.material.z > 2.5) {
+  // Derivatives and samples must be uniform across each fragment quad.
+  // Relative degeneracy: raw derivative magnitudes shrink with model scale and
+  // zoom. An absolute tangent cutoff silently disabled normal maps in close-ups.
+  let dpScale = max(length(dpdx(s.world)), length(dpdy(s.world)));
+  let uvScale = max(length(dpdx(s.uv)), length(dpdy(s.uv)));
+  let dx = dpdx(s.world) / max(dpScale, 1e-20);
+  let dy = dpdy(s.world) / max(dpScale, 1e-20);
+  let ux = dpdx(s.uv) / max(uvScale, 1e-20);
+  let uy = dpdy(s.uv) / max(uvScale, 1e-20);
+  let determinant = ux.x * uy.y - ux.y * uy.x;
+  let tangent = dx * uy.y - dy * ux.y;
+  let bitangent = dy * ux.x - dx * uy.x;
+  let sampledNormal = textureSample(normalMap, materialSampler, s.uv).xyz * 2.0 - 1.0;
+  var c = s.colour * textureSample(baseColourMap, materialSampler, s.uv).rgb;
+  let orm = textureSample(ormMap, materialSampler, s.uv).rgb;
+  let coatSample = textureSample(clearcoatMap, materialSampler, s.uv).rg;
+  let roughness = clamp(s.material.x * orm.g, 0.04, 1.0);
+  let metalness = clamp(s.material.y * orm.b, 0.0, 1.0);
+  let orthogonalTangent = tangent - n * dot(n,tangent);
+  let orthogonalBitangent = bitangent - n * dot(n,bitangent);
+  if (dpScale > 1e-20 && uvScale > 1e-20 && abs(determinant) > 1e-6 && dot(orthogonalTangent,orthogonalTangent) > 1e-12 && dot(orthogonalBitangent,orthogonalBitangent) > 1e-12) {
+    let t = normalize(orthogonalTangent) * sign(determinant);
+    let b = normalize(orthogonalBitangent) * sign(determinant);
+    n = normalize(t * sampledNormal.x * materialParameters.x + b * sampledNormal.y * materialParameters.x + n * max(0.001,sampledNormal.z));
+  }
+  if (materialParameters.y < 0.5 && 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) {
+  } else if (materialParameters.y < 0.5 && 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); }
+  } else if (materialParameters.y < 0.5 && 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);
+  let direct = brdf(c, n, v, roughness, metalness) * vec3f(3.0, 2.65, 2.15) * visibility(s.world, n);
+  let ambient = c * hemi * (1.0 - metalness * 0.7) * orm.r;
+  let env = sky(reflect(-v,n)) * mix(vec3f(0.04), c, metalness) * (1.0-roughness) * orm.r * 0.30;
+  let baseRadiance = direct + ambient + env;
+  let coatCoverage = materialParameters.z * coatSample.r;
+  if (coatCoverage <= 0.0) { return fog(baseRadiance,s.world); }
+  // KHR_materials_clearcoat's simple Fresnel layering: varnish has its own
+  // smooth normal and roughness. Its reflection never inherits the wood colour.
+  let coatFresnel = 0.04 + 0.96 * pow(1.0-clamp(abs(dot(coatNormal,v)),0.0,1.0),5.0);
+  let coatWeight = coatCoverage * coatFresnel;
+  let coatRoughness = clamp(materialParameters.w * coatSample.g,0.04,1.0);
+  let coatDirect = vec3f(3.0,2.65,2.15) * specularLobe(coatNormal,v,coatRoughness) * visibility(s.world,coatNormal);
+  let coatEnvironment = sky(reflect(-v,coatNormal)) * (1.0-coatRoughness) * orm.r * 0.30;
+  return fog(baseRadiance * (1.0-coatWeight) + (coatDirect+coatEnvironment) * coatWeight, s.world);
 }
 @fragment fn surfaceFragment(s: Surface, @builtin(front_facing) front: bool) -> @location(0) vec4f {
   return vec4f(display(surfaceRadiance(s,front)),1);
@@ -172,7 +221,8 @@ struct WaterResult { @location(0) colour: vec4f, @builtin(frag_depth) depth: f32
   return vec4f(sky(cameraRay(pixel.xy)),1);
 }
 @fragment fn reflectionSurface(s: Surface, @builtin(front_facing) front: bool) -> @location(0) vec4f {
+  let radiance = surfaceRadiance(s,front);
   if (s.world.y < frame.viewport.z) { discard; }
-  return vec4f(surfaceRadiance(s,front),1);
+  return vec4f(radiance,1);
 }
 `;

package/src/native-surface-materials.js

@@ -0,0 +1,124 @@
+// Decoded RGBA contract matches gpu-shared's glTF loader. No network or DOM work.
+const MAX_BYTES = 64 * 1024 * 1024;
+const MAPS = ["baseColor", "normal", "orm", "clearcoatMap"];
+const defaults = {
+  baseColor: [255, 255, 255, 255],
+  normal: [128, 128, 255, 255],
+  orm: [255, 255, 255, 255],
+  clearcoatMap: [255, 255, 255, 255],
+};
+const dimension = (n) =>
+  Number.isInteger(n) && n >= 1 && n <= 2048 && (n & (n - 1)) === 0;
+
+export function validateNativeMaterials(materials) {
+  if (!Array.isArray(materials) || materials.length > 16)
+    throw new Error("materials must contain at most 16 entries.");
+  let bytes = 0;
+  for (const material of materials) {
+    if (!material || typeof material !== "object")
+      throw new Error("Each material must be an object.");
+    if (
+      !Number.isFinite(material.normalScale ?? 1) ||
+      (material.normalScale ?? 1) < 0 ||
+      (material.normalScale ?? 1) > 4
+    ) {
+      throw new Error("material normalScale must be between 0 and 4.");
+    }
+    for (const key of ["clearcoat", "clearcoatRoughness"]) {
+      const value = material[key] ?? 0;
+      if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error(`material ${key} must be between 0 and 1.`);
+      }
+    }
+    for (const key of MAPS) {
+      const map = material[key];
+      if (map === undefined) continue;
+      if (
+        !map ||
+        !dimension(map.width) ||
+        !dimension(map.height) ||
+        !(
+          map.data instanceof Uint8Array ||
+          map.data instanceof Uint8ClampedArray
+        ) ||
+        map.data.length !== map.width * map.height * 4
+      ) {
+        throw new Error(
+          `material ${key} texture must contain RGBA8 data with power-of-two dimensions between 1 and 2048.`,
+        );
+      }
+      bytes += map.data.byteLength;
+      if (bytes > MAX_BYTES)
+        throw new Error("material textures exceed the 64 MiB source budget.");
+    }
+  }
+}
+const linear = (x) => (x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4);
+const srgb = (x) =>
+  x <= 0.0031308 ? x * 12.92 : 1.055 * x ** (1 / 2.4) - 0.055;
+
+function nextMip(image, colour) {
+  const width = Math.max(1, image.width / 2),
+    height = Math.max(1, image.height / 2);
+  const data = new Uint8Array(width * height * 4);
+  for (let y = 0; y < height; y++)
+    for (let x = 0; x < width; x++)
+      for (let c = 0; c < 4; c++) {
+        let sum = 0;
+        for (let dy = 0; dy < 2; dy++)
+          for (let dx = 0; dx < 2; dx++) {
+            const offset =
+              (Math.min(image.height - 1, y * 2 + dy) * image.width +
+                Math.min(image.width - 1, x * 2 + dx)) *
+                4 +
+              c;
+            const value = image.data[offset] / 255;
+            sum += colour && c < 3 ? linear(value) : value;
+          }
+        data[(y * width + x) * 4 + c] = Math.round(
+          255 * (colour && c < 3 ? srgb(sum / 4) : sum / 4),
+        );
+      }
+  return { width, height, data };
+}
+
+export function createNativeMaterialTextures(device, materials, own) {
+  // Index zero is the backwards-compatible material; caller materials start at one.
+  return [{}, ...materials].map((material, index) => {
+    const result = {
+      normalScale: material.normal ? (material.normalScale ?? 1) : 0,
+      authored: ["baseColor", "normal", "orm"].some((key) => material[key]),
+      clearcoat: material.clearcoat ?? 0,
+      clearcoatRoughness: material.clearcoatRoughness ?? 0,
+    };
+    for (const key of MAPS) {
+      let level = material[key] ?? {
+        width: 1,
+        height: 1,
+        data: new Uint8Array(defaults[key]),
+      };
+      const mipLevelCount = 1 + Math.log2(Math.max(level.width, level.height));
+      const texture = own(
+        device.createTexture({
+          label: `native.material.${index}.${key}`,
+          size: { width: level.width, height: level.height },
+          format: key === "baseColor" ? "rgba8unorm-srgb" : "rgba8unorm",
+          mipLevelCount,
+          usage: 0x06,
+        }),
+      );
+      for (let mipLevel = 0; mipLevel < mipLevelCount; mipLevel++) {
+        device.queue.writeTexture(
+          { texture, mipLevel },
+          level.data,
+          { bytesPerRow: level.width * 4, rowsPerImage: level.height },
+          { width: level.width, height: level.height, depthOrArrayLayers: 1 },
+        );
+        if (mipLevel + 1 < mipLevelCount)
+          level = nextMip(level, key === "baseColor");
+      }
+      result[key] = texture.createView();
+    }
+    return result;
+  });
+}