@plasius/gpu-renderer 0.2.54 → 0.2.55

package/CHANGELOG.md

@@ -23,6 +23,20 @@ All notable changes to this project will be documented in this file.
 - **Security**
   - (placeholder)
 
+## [0.2.55] - 2026-10-24
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - Preserve canonical blend alpha exactly once and ignore factor/texture alpha for opaque materials through CPU/GPU packing and material sampling; retain legacy Wavefront alpha composition when mode is omitted.
+
+- **Security**
+  - (placeholder)
+
 ## [0.2.54] - 2026-10-21
 
 - **Added**
@@ -1300,3 +1314,4 @@ All notable changes to this project will be documented in this file.
 [0.2.52]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.52
 [0.2.53]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.53
 [0.2.54]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.54
+[0.2.55]: https://github.com/Plasius-LTD/gpu-renderer/releases/tag/v0.2.55

package/README.md

@@ -74,6 +74,10 @@ The canonical adapter maps the core 0.5 material texture slots; it currently
 accepts UV0 and identity texture transforms. Other selections/transforms fail
 explicitly so authored appearance is not silently changed. See the
 [canonical integration contract](docs/guides/integration.md#canonical-model-ingestion).
+Canonical blend materials multiply authored factor alpha by texture alpha once;
+opaque materials ignore both alpha channels. Direct `WavefrontMeshInput` callers
+can select `alphaMode: "opaque" | "blend"`; omitting it preserves legacy opacity
+composition. Alpha masks remain unsupported by the canonical adapter.
 For an interactive model viewer with loading, integrity checks, camera gestures
 and quality controls, use the shared package's `model-inspection` entry.
 

package/dist/index.cjs

@@ -1691,12 +1691,14 @@ function mapMaterial(material, materialRefId, textures) {
   }
   const mapped = {
     materialRefId,
+    alphaMode: material.alphaMode,
     ...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],
+    // The authored factor remains in baseColor.a; do not multiply it twice.
+    opacity: 1,
     clearcoat: material.clearcoatFactor,
     clearcoatRoughness: material.clearcoatRoughnessFactor,
     transmission: material.transmissionFactor,
@@ -8377,7 +8379,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,
@@ -9361,6 +9363,10 @@ function createDefaultWavefrontSceneObjects() {
   ]);
 }
 function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
+  const alphaMode = input.alphaMode;
+  if (alphaMode !== void 0 && 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) {
@@ -9390,7 +9396,11 @@ function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
     input.emission ?? input.emissive ?? input.material?.emission ?? input.material?.emissive,
     [0, 0, 0, 1]
   );
-  const opacity = clamp2(readFiniteNumber("opacity", input.opacity ?? input.material?.opacity, color[3] ?? 1), 0, 1);
+  const opacity = alphaMode === "opaque" ? 1 : clamp2(
+    readFiniteNumber("opacity", input.opacity ?? input.material?.opacity, alphaMode === "blend" ? 1 : color[3] ?? 1),
+    0,
+    1
+  );
   const transmission = clamp2(
     readFiniteNumber("transmission", input.transmission ?? input.material?.transmission, materialExtensions.transmission),
     0,
@@ -9422,6 +9432,7 @@ function normalizeWavefrontMesh(input = {}, meshIndex = 0) {
       0
     ),
     medium,
+    alphaMode,
     color: Object.freeze(color),
     emission: Object.freeze(emission),
     roughness: clamp2(readFiniteNumber("roughness", input.roughness ?? input.material?.roughness, 0.72), 0, 1),
@@ -9573,7 +9584,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(
@@ -9916,7 +9927,7 @@ 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
     ]);
   });
   return Object.freeze({
@@ -10101,7 +10112,7 @@ function createWavefrontGpuMeshSource(meshes = [], gpuMaterialSourceInput = 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
     ]);
     vertexCursor += meshVertexCount;
     indexCursor += mesh.indices.length;