@plasius/gpu-renderer 0.2.46 → 0.2.47

package/CHANGELOG.md

@@ -23,6 +23,21 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
+## [0.2.47] - 2026-10-09
+
+- **Added**
+  - Added `createCanonicalWavefrontMeshInputs` to adapt decoded canonical model
+    geometry, material factors, and texture samples to Wavefront renderer inputs.
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
 ## [0.2.46] - 2026-09-29
 
 - Add native showcase surface drawing with filtered shadows, HDR planar water
@@ -1149,3 +1164,4 @@ All notable changes to this project will be documented in this file.
 [0.2.44]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.44
 [0.2.45]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.45
 [0.2.46]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.46
+[0.2.47]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.47

package/README.md

@@ -129,6 +129,41 @@ renderer.resize(window.innerWidth, window.innerHeight);
 renderer.start();
 ```
 
+## Canonical model ingestion
+
+`createCanonicalWavefrontMeshInputs` adapts decoded primitive geometry and image
+samples from the canonical model pipeline to the renderer's existing
+`WavefrontMeshInput` shape. It maps canonical material factors and standard
+texture bindings, preserves supported material extension data, and rejects
+missing primitive, material, or decoded texture references. It accepts triangle
+primitives; parsing, resource fetching, image decoding, and other topologies stay
+in the upstream conversion layer. Metallic-roughness and unlit workflows are
+supported; workflows without an existing Wavefront mapping fail explicitly.
+
+```js
+import { createCanonicalWavefrontMeshInputs } from "@plasius/gpu-renderer";
+
+const meshes = createCanonicalWavefrontMeshInputs({
+  document: canonicalDocument,
+  geometry: decodedPrimitives.map(({ primitiveId, positions, indices, normals, texcoords }) => ({
+    primitiveId,
+    positions,
+    indices,
+    normals,
+    texcoords,
+  })),
+  // ReadonlyMap<canonical texture id, decoded RGBA sample>
+  textures: decodedTextureSamples,
+});
+```
+
+The canonical document uses types from `@plasius/gpu-model-core`. Geometry is
+already renderer-ready, normals may be omitted to retain the renderer's existing
+fallback, and texture samples are keyed by canonical texture ID. The consuming
+surface remains responsible for evaluating the remote
+`gpu.model.conversion.enabled` flag: when disabled or rolled back, keep the
+existing rendering path active.
+
 ## Adaptive Frame Hooks
 
 `@plasius/gpu-renderer` now exposes frame lifecycle hooks so the app can pass

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,
@@ -1307,6 +1308,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");
 
@@ -14093,6 +14290,7 @@ function createRayTracingRenderPlan(options = {}) {
   bucketFeedbackGameFrameTime,
   bucketFeedbackGameViewport,
   createAnimatedSceneRenderer,
+  createCanonicalWavefrontMeshInputs,
   createDefaultWavefrontSceneObjects,
   createFeedbackGameDiagnosticSnapshot,
   createGpuRenderer,