@plasius/gpu-renderer 0.2.54 → 0.2.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-renderer",
-  "version": "0.2.54",
+  "version": "0.2.56",
   "description": "Framework-agnostic WebGPU renderer runtime for Plasius projects.",
   "type": "module",
   "sideEffects": false,

package/src/canonical-wavefront-meshes.js

@@ -84,14 +84,6 @@ function textureSample(binding, textures, label, 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) {
@@ -118,12 +110,18 @@ function mapMaterial(material, materialRefId, textures) {
   if (material.alphaMode === "mask") {
     throw new Error("Canonical alphaMode mask is unsupported by WavefrontMeshInput.");
   }
-  if (material.workflow !== "metallic-roughness" && material.workflow !== "unlit") {
+  if (material.workflow === "unlit"
+    || Object.hasOwn(material.extensions ?? {}, "KHR_materials_unlit")
+    || Object.hasOwn(material.extensions ?? {}, "unlit")) {
+    throw new Error("Canonical unlit materials are unsupported by WavefrontMeshInput; retain an unlit-capable rendering path.");
+  }
+  if (material.workflow !== "metallic-roughness") {
     throw new Error(`Unsupported canonical material workflow: ${material.workflow}.`);
   }
 
   const mapped = {
     materialRefId,
+    alphaMode: material.alphaMode,
     ...(material.alphaMode === "blend" ? { materialKind: "transparent" } : {}),
     baseColor: material.baseColorFactor,
     emission: material.emissiveFactor
@@ -131,7 +129,8 @@ function mapMaterial(material, materialRefId, textures) {
       : [0, 0, 0, 1],
     roughness: material.roughnessFactor,
     metallic: material.metallicFactor,
-    opacity: material.alphaMode === "opaque" ? 1 : material.baseColorFactor?.[3],
+    // The authored factor remains in baseColor.a; do not multiply it twice.
+    opacity: 1,
     clearcoat: material.clearcoatFactor,
     clearcoatRoughness: material.clearcoatRoughnessFactor,
     transmission: material.transmissionFactor,
@@ -158,6 +157,8 @@ function mapMaterial(material, materialRefId, textures) {
 /**
  * Maps decoded canonical mesh primitives into the renderer's existing Wavefront
  * input contract. Geometry and image decoding remain upstream responsibilities.
+ * Referenced unlit workflows or extension markers are rejected until an explicit
+ * unlit shading path exists; callers must retain an unlit-capable rendering path.
  */
 export function createCanonicalWavefrontMeshInputs({ document, geometry, textures = new Map() } = {}) {
   if (!document || typeof document !== "object") {

package/src/index.d.ts

@@ -522,6 +522,9 @@ export interface WavefrontSceneObject {
 }
 
 export interface WavefrontMeshInput {
+  /** Opaque ignores factor/texture alpha. Blend defaults opacity to one.
+   * Omitted preserves legacy factor × opacity × texture alpha semantics. */
+  readonly alphaMode?: "opaque" | "blend";
   readonly id?: number;
   readonly positions: readonly number[] | Float32Array;
   readonly indices?: readonly number[] | Uint16Array | Uint32Array;
@@ -749,6 +752,7 @@ export interface WavefrontGpuMeshSource {
       readonly roughness: number;
       readonly metallic: number;
       readonly opacity: number;
+      readonly alphaMode?: "opaque" | "blend";
       readonly ior: number;
       readonly sheen: number;
       readonly sheenTint: number;
@@ -1416,6 +1420,7 @@ export function normalizeWavefrontMesh(
   roughness: number;
   metallic: number;
   opacity: number;
+  alphaMode?: "opaque" | "blend";
   ior: number;
   sheen: number;
   sheenTint: number;

package/src/wavefront-mesh-sources.js

@@ -121,7 +121,7 @@ function createMeshTriangleRecords(meshes, gpuMaterialSource = null) {
             clampUnit(mesh.normalTexture?.scale ?? mesh.normalTexture?.strength ?? 1),
             clampUnit(mesh.occlusionTexture?.strength ?? 1),
             clampUnit(mesh.emissiveTexture?.strength ?? 1),
-            0,
+            mesh.alphaMode === "opaque" ? 1 : 0,
           ]),
           extensionTextures: Object.freeze(
             Object.fromEntries(
@@ -499,7 +499,7 @@ export function createWavefrontGpuMaterialSource(meshes = []) {
       clampUnit(mesh.normalTexture?.scale ?? mesh.normalTexture?.strength ?? 1),
       clampUnit(mesh.occlusionTexture?.strength ?? 1),
       clampUnit(mesh.emissiveTexture?.strength ?? 1),
-      0,
+      mesh.alphaMode === "opaque" ? 1 : 0,
     ]);
   });
 
@@ -705,7 +705,7 @@ export function createWavefrontGpuMeshSource(meshes = [], gpuMaterialSourceInput
       clampUnit(mesh.normalTexture?.scale ?? mesh.normalTexture?.strength ?? 1),
       clampUnit(mesh.occlusionTexture?.strength ?? 1),
       clampUnit(mesh.emissiveTexture?.strength ?? 1),
-      0,
+      mesh.alphaMode === "opaque" ? 1 : 0,
     ]);
 
     vertexCursor += meshVertexCount;

package/src/wavefront-scene-normalizers.js

@@ -193,6 +193,10 @@ export function createDefaultWavefrontSceneObjects() {
 }
 
 export function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
+  const alphaMode = input.alphaMode;
+  if (alphaMode !== undefined && alphaMode !== "opaque" && alphaMode !== "blend") {
+    throw new TypeError("mesh alphaMode must be opaque or blend.");
+  }
   const positions = input.positions;
   const positionLength = getArrayLikeLength(positions);
   if (positionLength < 9 || positionLength % 3 !== 0) {
@@ -236,7 +240,11 @@ export function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
     input.emission ?? input.emissive ?? input.material?.emission ?? input.material?.emissive,
     [0, 0, 0, 1]
   );
-  const opacity = clamp(readFiniteNumber("opacity", input.opacity ?? input.material?.opacity, color[3] ?? 1), 0, 1);
+  const opacity = alphaMode === "opaque" ? 1 : clamp(
+    readFiniteNumber("opacity", input.opacity ?? input.material?.opacity, alphaMode === "blend" ? 1 : color[3] ?? 1),
+    0,
+    1
+  );
   const transmission = clamp(
     readFiniteNumber("transmission", input.transmission ?? input.material?.transmission, materialExtensions.transmission),
     0,
@@ -280,6 +288,7 @@ export function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
       0
     ),
     medium,
+    alphaMode,
     color: Object.freeze(color),
     emission: Object.freeze(emission),
     roughness: clamp(readFiniteNumber("roughness", input.roughness ?? input.material?.roughness, 0.72), 0, 1),

package/src/wavefront-shader-materials.js

@@ -67,7 +67,7 @@ fn sample_surface_material(
   let baseColorTexel = sample_atlas(baseColorAtlasTexture, triangle.baseColorAtlas, uv);
   let baseColor = vec4<f32>(
     clamp(triangle.color.rgb * srgb_to_linear_vec3(baseColorTexel.rgb), vec3<f32>(0.0), vec3<f32>(1.0)),
-    clamp(triangle.color.a * baseColorTexel.a, 0.0, 1.0)
+    select(clamp(triangle.color.a * baseColorTexel.a, 0.0, 1.0), 1.0, triangle.textureSettings.w > 0.5)
   );
   let metallicRoughnessTexel = sample_atlas(
     metallicRoughnessAtlasTexture,