@plasius/gpu-renderer 0.2.46 → 0.2.48

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   bucketFeedbackGameFrameTime: () => bucketFeedbackGameFrameTime,
   bucketFeedbackGameViewport: () => bucketFeedbackGameViewport,
   createAnimatedSceneRenderer: () => createAnimatedSceneRenderer,
+  createCanonicalWavefrontMeshInputs: () => createCanonicalWavefrontMeshInputs,
   createDefaultWavefrontSceneObjects: () => createDefaultWavefrontSceneObjects,
   createFeedbackGameDiagnosticSnapshot: () => createFeedbackGameDiagnosticSnapshot,
   createGpuRenderer: () => createGpuRenderer,
@@ -86,6 +87,7 @@ __export(index_exports, {
   supportsWebGpu: () => supportsWebGpu,
   traceWavefrontReferenceTriangles: () => traceWavefrontReferenceTriangles,
   transitionMediumStack: () => transitionMediumStack,
+  validateNativeSurfaceMaterials: () => validateNativeMaterials,
   wavefrontMaterialKinds: () => wavefrontMaterialKinds,
   wavefrontPathTracingComputeLimits: () => wavefrontPathTracingComputeLimits,
   wavefrontSceneObjectKinds: () => wavefrontSceneObjectKinds
@@ -650,12 +652,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;
@@ -669,8 +677,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);
@@ -723,17 +731,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);
@@ -741,23 +757,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);
@@ -811,12 +862,114 @@ 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);
 }
 `
 );
 
+// src/native-surface-materials.js
+var MAX_BYTES = 64 * 1024 * 1024;
+var MAPS = ["baseColor", "normal", "orm", "clearcoatMap"];
+var defaults = {
+  baseColor: [255, 255, 255, 255],
+  normal: [128, 128, 255, 255],
+  orm: [255, 255, 255, 255],
+  clearcoatMap: [255, 255, 255, 255]
+};
+var dimension = (n) => Number.isInteger(n) && n >= 1 && n <= 2048 && (n & n - 1) === 0;
+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 === void 0) 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.");
+    }
+  }
+}
+var linear = (x) => x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+var srgb = (x) => x <= 31308e-7 ? 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 };
+}
+function createNativeMaterialTextures(device, materials, own) {
+  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: 6
+        })
+      );
+      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;
+  });
+}
+
 // src/native-scene-renderer.js
 var STRIDE = 12;
 var UNIFORM_BYTES = 256;
@@ -832,7 +985,7 @@ var unit = (a) => {
   return a.map((v) => v / length);
 };
 var 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) || vertices.length % (STRIDE * 3) !== 0 || vertices.length > maxVertices * STRIDE || !vertices.every(Number.isFinite)) {
     throw new Error(
@@ -854,6 +1007,30 @@ function validateFrame(frame, maxVertices) {
       "wakes must contain at most four finite [x, z, heading] entries."
     );
   }
+  const count = vertices.length / STRIDE;
+  if (frame.texcoords !== void 0 && (!(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 !== void 0) {
+    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 };
 }
 function frameUniforms(frame, width, height, reflected = false) {
@@ -901,6 +1078,9 @@ function frameUniforms(frame, width, height, reflected = false) {
 }
 async function createNativeSceneRenderer(options = {}) {
   const maxVertices = options.maxVertices ?? 3e5;
+  const materials = options.materials ?? [];
+  validateNativeMaterials(materials);
+  const materialCount = materials.length;
   if (!Number.isInteger(maxVertices) || maxVertices < 3 || maxVertices > 6e5) {
     throw new Error("maxVertices must be an integer between 3 and 600000.");
   }
@@ -909,6 +1089,7 @@ 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;
@@ -1015,7 +1196,20 @@ async function createNativeSceneRenderer(options = {}) {
         if (p !== shadowPipeline) pass2.setBindGroup(1, shadowGroup);
         if (vertexCount > 0) {
           pass2.setVertexBuffer(0, vertexBuffer);
-          pass2.draw(vertexCount);
+          if (p === shadowPipeline) {
+            pass2.draw(vertexCount);
+          } else {
+            pass2.setVertexBuffer(1, uvBuffer);
+            if (pendingFrame.surfaces) {
+              for (const range of pendingFrame.surfaces) {
+                pass2.setBindGroup(2, materialGroups[range.materialIndex + 1]);
+                pass2.draw(range.vertexCount, 1, range.firstVertex);
+              }
+            } else {
+              pass2.setBindGroup(2, materialGroups[0]);
+              pass2.draw(vertexCount);
+            }
+          }
         }
       };
       const shadowPass = encoder.beginRenderPass({
@@ -1061,7 +1255,8 @@ 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);
@@ -1111,6 +1306,63 @@ 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: 72,
+          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",
@@ -1175,7 +1427,19 @@ async function createNativeSceneRenderer(options = {}) {
             {
               arrayStride: STRIDE * 4,
               attributes: vertex === "shadowVertex" ? attributes.slice(0, 1) : attributes
-            }
+            },
+            ...vertex === "shadowVertex" ? [] : [
+              {
+                arrayStride: 8,
+                attributes: [
+                  {
+                    shaderLocation: 4,
+                    offset: 0,
+                    format: "float32x2"
+                  }
+                ]
+              }
+            ]
           ]
         } : {}
       },
@@ -1209,7 +1473,7 @@ async function createNativeSceneRenderer(options = {}) {
       "surfaceFragment",
       format,
       4,
-      [uniformLayout, shadowLayout],
+      [uniformLayout, shadowLayout, materialLayout],
       true
     );
     const skyPipeline = await pipeline(
@@ -1226,7 +1490,7 @@ async function createNativeSceneRenderer(options = {}) {
       "waterFragment",
       format,
       4,
-      [uniformLayout, shadowLayout, reflectionLayout]
+      [uniformLayout, shadowLayout, materialLayout, reflectionLayout]
     );
     const reflectedSurfacePipeline = await pipeline(
       "reflection-surface",
@@ -1234,7 +1498,7 @@ async function createNativeSceneRenderer(options = {}) {
       "reflectionSurface",
       "rgba16float",
       1,
-      [uniformLayout, shadowLayout],
+      [uniformLayout, shadowLayout, materialLayout],
       true
     );
     const reflectedSkyPipeline = await pipeline(
@@ -1249,15 +1513,23 @@ 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: 40
+            })
+          );
           vertexBuffer = own(
             device.createBuffer({
               label: "native.surface-vertices",
@@ -1266,6 +1538,8 @@ 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(
@@ -1307,6 +1581,202 @@ async function createNativeSceneRenderer(options = {}) {
   }
 }
 
+// src/canonical-wavefront-meshes.js
+var STANDARD_TEXTURE_BINDINGS = Object.freeze([
+  ["baseColor", "baseColorTexture"],
+  ["metallicRoughness", "metallicRoughnessTexture"],
+  ["normal", "normalTexture"],
+  ["occlusion", "occlusionTexture"],
+  ["emissive", "emissiveTexture"]
+]);
+var EXTENSION_TEXTURE_BINDINGS = Object.freeze([
+  ["clearcoat", "clearcoat", "clearcoatTexture"],
+  ["clearcoatRoughness", "clearcoat", "clearcoatRoughnessTexture"],
+  ["clearcoatNormal", "clearcoat", "clearcoatNormalTexture"],
+  ["transmission", "transmission", "transmissionTexture"],
+  ["sheenColor", "sheen", "sheenColorTexture"],
+  ["sheenRoughness", "sheen", "sheenRoughnessTexture"]
+]);
+function requireArray(value, label) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`${label} must be an array.`);
+  }
+  return value;
+}
+function requireMap(value, label) {
+  if (!value || typeof value !== "object" || typeof value.get !== "function") {
+    throw new TypeError(`${label} must provide a ReadonlyMap-compatible get method.`);
+  }
+  return value;
+}
+function textureSample(binding, textures, label, extra = {}) {
+  if (binding === void 0 || binding === null) {
+    return void 0;
+  }
+  const sample = textures.get(binding.textureId);
+  if (!sample) {
+    throw new Error(`Missing decoded texture sample ${binding.textureId} for ${label}.`);
+  }
+  const width = Number(sample.width);
+  const height = Number(sample.height);
+  const data = sample.data;
+  const dataLength = data && typeof data.length === "number" ? data.length : -1;
+  if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+    throw new TypeError(`Decoded texture sample ${binding.textureId} has invalid dimensions.`);
+  }
+  if (width > 4096 || height > 4096 || width * height > 4096 * 4096) {
+    throw new RangeError(`Decoded texture sample ${binding.textureId} exceeds the 4096-pixel resource limit.`);
+  }
+  if (!(Array.isArray(data) || ArrayBuffer.isView(data)) || dataLength < width * height * 4) {
+    throw new TypeError(`Decoded texture sample ${binding.textureId} must contain width \xD7 height \xD7 4 RGBA values.`);
+  }
+  return Object.freeze({
+    ...sample,
+    ...binding.texCoordSet === void 0 ? {} : { texCoord: binding.texCoordSet },
+    ...extra
+  });
+}
+function cloneMaterialExtensions(material, textures) {
+  const extensions = { ...material.extensions ?? {} };
+  if (material.workflow === "unlit") {
+    const unlitKey = "KHR_materials_unlit";
+    const unlitValue = extensions[unlitKey] ?? extensions.unlit ?? {};
+    if (typeof unlitValue !== "object" || unlitValue === null || Array.isArray(unlitValue)) {
+      throw new TypeError(`Canonical material extension ${unlitKey} must be an object.`);
+    }
+    extensions[unlitKey] = { ...unlitValue, enabled: true };
+  }
+  for (const [bindingName, extensionName, textureKey] of EXTENSION_TEXTURE_BINDINGS) {
+    const binding = material.textures?.[bindingName];
+    if (!binding) {
+      continue;
+    }
+    const extensionKey = `KHR_materials_${extensionName}`;
+    const extensionValue = extensions[extensionKey] ?? extensions[extensionName] ?? {};
+    if (typeof extensionValue !== "object" || extensionValue === null || Array.isArray(extensionValue)) {
+      throw new TypeError(`Canonical material extension ${extensionKey} must be an object.`);
+    }
+    extensions[extensionKey] = {
+      ...extensionValue,
+      [textureKey]: textureSample(binding, textures, `${extensionKey}.${textureKey}`)
+    };
+  }
+  return extensions;
+}
+function mapMaterial(material, materialRefId, textures) {
+  if (!material) {
+    return { materialRefId };
+  }
+  if (material.alphaMode === "mask") {
+    throw new Error("Canonical alphaMode mask is unsupported by WavefrontMeshInput.");
+  }
+  if (material.workflow !== "metallic-roughness" && material.workflow !== "unlit") {
+    throw new Error(`Unsupported canonical material workflow: ${material.workflow}.`);
+  }
+  const mapped = {
+    materialRefId,
+    ...material.alphaMode === "blend" ? { materialKind: "transparent" } : {},
+    baseColor: material.baseColorFactor,
+    emission: material.emissiveFactor ? [...material.emissiveFactor, 1] : [0, 0, 0, 1],
+    roughness: material.roughnessFactor,
+    metallic: material.metallicFactor,
+    opacity: material.alphaMode === "opaque" ? 1 : material.baseColorFactor?.[3],
+    clearcoat: material.clearcoatFactor,
+    clearcoatRoughness: material.clearcoatRoughnessFactor,
+    transmission: material.transmissionFactor,
+    sheenColor: material.sheenColorFactor,
+    extensions: cloneMaterialExtensions(material, textures)
+  };
+  for (const [bindingName, inputName] of STANDARD_TEXTURE_BINDINGS) {
+    const binding = material.textures?.[bindingName];
+    if (!binding) {
+      continue;
+    }
+    const extra = bindingName === "normal" && material.normalScale !== void 0 ? { scale: material.normalScale } : bindingName === "occlusion" && material.occlusionStrength !== void 0 ? { strength: material.occlusionStrength } : {};
+    mapped[inputName] = textureSample(binding, textures, inputName, extra);
+  }
+  return mapped;
+}
+function createCanonicalWavefrontMeshInputs({ document, geometry, textures = /* @__PURE__ */ new Map() } = {}) {
+  if (!document || typeof document !== "object") {
+    throw new TypeError("Canonical model document is required.");
+  }
+  const meshes = requireArray(document.meshes, "Canonical model meshes");
+  const materials = requireArray(document.materials, "Canonical model materials");
+  const geometryInputs = requireArray(geometry, "Renderer-ready geometry");
+  const textureSamples = requireMap(textures, "Decoded texture samples");
+  const geometryByPrimitiveId = /* @__PURE__ */ new Map();
+  for (const entry of geometryInputs) {
+    if (!entry || typeof entry.primitiveId !== "string" || entry.primitiveId.length === 0) {
+      throw new TypeError("Renderer-ready geometry requires a non-empty primitiveId.");
+    }
+    if (geometryByPrimitiveId.has(entry.primitiveId)) {
+      throw new Error(`Duplicate renderer-ready geometry for primitive ${entry.primitiveId}.`);
+    }
+    geometryByPrimitiveId.set(entry.primitiveId, entry);
+  }
+  const materialsById = /* @__PURE__ */ new Map();
+  const materialRefIds = /* @__PURE__ */ new Map();
+  materials.forEach((material, index) => {
+    if (!material || typeof material.id !== "string" || material.id.length === 0) {
+      throw new TypeError("Canonical materials require a non-empty id.");
+    }
+    if (materialsById.has(material.id)) {
+      throw new Error(`Duplicate canonical material ${material.id}.`);
+    }
+    materialsById.set(material.id, material);
+    materialRefIds.set(material.id, index + 1);
+  });
+  const output = [];
+  const consumedPrimitiveIds = /* @__PURE__ */ new Set();
+  const canonicalPrimitiveIds = /* @__PURE__ */ new Set();
+  for (const mesh of meshes) {
+    if (!mesh || typeof mesh.id !== "string") {
+      throw new TypeError("Canonical meshes require a string id.");
+    }
+    for (const primitive of requireArray(mesh.primitives, `Primitives for mesh ${mesh.id}`)) {
+      if (!primitive || typeof primitive.id !== "string" || primitive.id.length === 0) {
+        throw new TypeError(`Canonical mesh ${mesh.id} contains a primitive without an id.`);
+      }
+      if (canonicalPrimitiveIds.has(primitive.id)) {
+        throw new Error(`Duplicate canonical primitive ${primitive.id}.`);
+      }
+      canonicalPrimitiveIds.add(primitive.id);
+      if (primitive.topology !== "triangles") {
+        throw new Error(`Unsupported canonical primitive topology: ${primitive.topology}.`);
+      }
+      const source = geometryByPrimitiveId.get(primitive.id);
+      if (!source) {
+        throw new Error(`Missing renderer-ready geometry for primitive ${primitive.id}.`);
+      }
+      consumedPrimitiveIds.add(primitive.id);
+      let material = null;
+      let materialRefId = 0;
+      if (primitive.materialId !== void 0) {
+        material = materialsById.get(primitive.materialId);
+        if (!material) {
+          throw new Error(`Missing canonical material ${primitive.materialId} for primitive ${primitive.id}.`);
+        }
+        materialRefId = materialRefIds.get(primitive.materialId);
+      }
+      output.push(Object.freeze({
+        id: output.length + 1,
+        positions: source.positions,
+        ...source.indices === void 0 ? {} : { indices: source.indices },
+        ...source.normals === void 0 ? {} : { normals: source.normals },
+        ...(source.texcoords ?? source.uvs) === void 0 ? {} : { uvs: source.texcoords ?? source.uvs },
+        ...mapMaterial(material, materialRefId, textureSamples)
+      }));
+    }
+  }
+  for (const primitiveId of geometryByPrimitiveId.keys()) {
+    if (!consumedPrimitiveIds.has(primitiveId)) {
+      throw new Error(`Renderer-ready geometry references unknown primitive ${primitiveId}.`);
+    }
+  }
+  return Object.freeze(output);
+}
+
 // src/animated-scene-renderer.js
 var import_gpu_camera = require("@plasius/gpu-camera");
 
@@ -3750,8 +4220,8 @@ function hashUint32(value) {
   x = ((x >>> 16 ^ x) >>> 0) * 73244475 >>> 0;
   return (x >>> 16 ^ x) >>> 0;
 }
-function mixSeed(pixelId, sampleId, bounce, frameIndex, dimension) {
-  let x = (pixelId >>> 0) * 747796405 ^ (sampleId >>> 0) * 2891336453 ^ (bounce >>> 0) * 277803737 ^ (frameIndex >>> 0) * 1442695041 ^ (dimension >>> 0) * 1597334677;
+function mixSeed(pixelId, sampleId, bounce, frameIndex, dimension2) {
+  let x = (pixelId >>> 0) * 747796405 ^ (sampleId >>> 0) * 2891336453 ^ (bounce >>> 0) * 277803737 ^ (frameIndex >>> 0) * 1442695041 ^ (dimension2 >>> 0) * 1597334677;
   x >>>= 0;
   x ^= x >>> 16;
   x = x * 2146121005 >>> 0;
@@ -9630,25 +10100,25 @@ function toWgslConstName(name) {
   return `SAMPLE_DIM_${name.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}`;
 }
 var usedDimensions = /* @__PURE__ */ new Set();
-for (const [, dimension] of sampleDimensionEntries) {
-  if (usedDimensions.has(dimension)) {
-    throw new Error(`Duplicate wavefront sample dimension ${dimension}.`);
+for (const [, dimension2] of sampleDimensionEntries) {
+  if (usedDimensions.has(dimension2)) {
+    throw new Error(`Duplicate wavefront sample dimension ${dimension2}.`);
   }
-  usedDimensions.add(dimension);
+  usedDimensions.add(dimension2);
 }
 var WAVEFRONT_SAMPLE_DIMENSIONS = Object.freeze(
   Object.fromEntries(sampleDimensionEntries)
 );
 function listWavefrontSampleDimensions() {
   return sampleDimensionEntries.map(
-    ([name, dimension]) => Object.freeze({
+    ([name, dimension2]) => Object.freeze({
       name,
-      dimension,
+      dimension: dimension2,
       wgslName: toWgslConstName(name)
     })
   );
 }
-var WAVEFRONT_SAMPLE_DIMENSIONS_WGSL = listWavefrontSampleDimensions().map(({ wgslName, dimension }) => `const ${wgslName}: u32 = ${dimension}u;`).join("\n");
+var WAVEFRONT_SAMPLE_DIMENSIONS_WGSL = listWavefrontSampleDimensions().map(({ wgslName, dimension: dimension2 }) => `const ${wgslName}: u32 = ${dimension2}u;`).join("\n");
 function fract(value) {
   return value - Math.floor(value);
 }
@@ -9661,19 +10131,19 @@ function radicalInverseVdc2(value) {
   bits = ((bits & 16711935) << 8 | (bits & 4278255360) >>> 8) >>> 0;
   return bits / 4294967296;
 }
-function sampleWavefrontDimension1D(pixelId, sampleId, bounce, frameIndex, dimension) {
-  return random01FromSeed(mixSeed(pixelId, sampleId, bounce, frameIndex, dimension));
+function sampleWavefrontDimension1D(pixelId, sampleId, bounce, frameIndex, dimension2) {
+  return random01FromSeed(mixSeed(pixelId, sampleId, bounce, frameIndex, dimension2));
 }
-function sampleWavefrontDimension2D(pixelId, sampleId, bounce, frameIndex, dimension, strataCount) {
+function sampleWavefrontDimension2D(pixelId, sampleId, bounce, frameIndex, dimension2, strataCount) {
   const strata = Math.max(1, Number.isFinite(strataCount) ? Math.trunc(strataCount) : 1);
   const jitter = sampleWavefrontDimension1D(
     pixelId,
     sampleId,
     bounce,
     frameIndex,
-    dimension
+    dimension2
   );
-  const scramble = hashUint32(mixSeed(pixelId, sampleId, bounce, frameIndex, dimension));
+  const scramble = hashUint32(mixSeed(pixelId, sampleId, bounce, frameIndex, dimension2));
   const stratified = fract(((sampleId >>> 0) % strata + jitter) / strata);
   const lowDiscrepancy = fract(radicalInverseVdc2(sampleId >>> 0 ^ scramble) + jitter);
   return Object.freeze([stratified, lowDiscrepancy]);
@@ -14093,6 +14563,7 @@ function createRayTracingRenderPlan(options = {}) {
   bucketFeedbackGameFrameTime,
   bucketFeedbackGameViewport,
   createAnimatedSceneRenderer,
+  createCanonicalWavefrontMeshInputs,
   createDefaultWavefrontSceneObjects,
   createFeedbackGameDiagnosticSnapshot,
   createGpuRenderer,
@@ -14151,6 +14622,7 @@ function createRayTracingRenderPlan(options = {}) {
   supportsWebGpu,
   traceWavefrontReferenceTriangles,
   transitionMediumStack,
+  validateNativeSurfaceMaterials,
   wavefrontMaterialKinds,
   wavefrontPathTracingComputeLimits,
   wavefrontSceneObjectKinds