@driftengine/assets 4.1.1 → 4.1.3

package/dist/drftLoader.js

@@ -950,20 +950,37 @@ export function isRawCodec(codec) {
  * the view would keep the whole file alive for as long as the image does.
  */
 /**
- * How every image a model carries is decoded: **straight alpha, and no colour conversion.**
+ * How every image a model carries is decoded: **premultiplied, and no colour conversion.**
  *
- * `createImageBitmap` premultiplies unless told not to, and the upload into a straight-alpha
- * texture then divides back out. A texel with no alpha comes back with no colour, so a cutout or an
- * emblem loses the colour its author padded past its edge, and filtering pulls black into the edge;
- * a partly transparent one comes back rounded to a coarser step. Colour management rewrites a normal
- * or ORM map, whose values are not colours at all, and glTF — which these assets are baked from —
- * says an image's own colour metadata is ignored. `render/imageTexels.ts` asks for the same two.
+ * **Straight alpha was tried in 4.0.0 and it is what this reverts.** The argument for it was that
+ * `createImageBitmap` premultiplies by default, so a texel with no alpha comes back with no colour
+ * and a cutout or an emblem loses the colour its author padded past its edge. That reasoning is
+ * sound about the pixels and wrong about the content: an imported material's albedo routinely
+ * carries arbitrary bytes under its fully transparent texels, and premultiplying was what kept
+ * them out of the frame.
  *
- * What it gives up: an albedo authored in a wide-gamut space with a profile saying so is read as
- * sRGB. The baker is where that conversion belongs, and it has no colour management either.
+ * **What it cost, reported and then reproduced.** A car came through with its interior, grille,
+ * mirrors and lamps as hard black and white shards. Held frames of one scene in the showroom, on
+ * one machine, at one frame: a model with 41 images drew clean and two with 64 and 65 drew shards,
+ * on **both** backends, with the old container and the new one alike — the count only decides how
+ * likely a model is to carry a masked texture at all. Restoring this one option drew the car
+ * correctly again.
+ *
+ * **Why an opaque material sees it.** Nothing discards on an opaque draw, so the shader takes
+ * `texel.rgb` whatever the alpha beside it says. Premultiplied, the bytes under a mask arrive as
+ * black and disappear into a dark surface; straight, they arrive as whatever the exporter left
+ * there. A material that genuinely means to cut out says so with its own alpha reference, which is
+ * what `kn5.ts`'s `alphaReference` now reads correctly.
+ *
+ * **What would make this wrong:** content authored *for* straight alpha, whose colour under a mask
+ * is meaningful and wanted — a decal atlas relying on the padding. Nothing measured here is that,
+ * and the day one arrives it wants the option per material rather than per engine.
+ *
+ * `colorSpaceConversion` stays off: a normal or ORM map holds values that are not colours, and
+ * glTF says an image's own colour metadata is ignored.
  */
 const AS_AUTHORED = {
-    premultiplyAlpha: 'none',
+    premultiplyAlpha: 'premultiply',
     colorSpaceConversion: 'none',
 };
 async function decodeImage(texture, longestSide) {

package/dist/kn5.js

@@ -311,6 +311,25 @@ export function readKn5Nodes(header) {
  * this stays only for the warning, which is the thing a name genuinely can answer: a shader
  * nobody here has seen is still geometry somebody wants.
  */
+/**
+ * What a tested material's alpha reference actually is, where it states zero or states none.
+ *
+ * **Zero means the shader's own threshold, not "discard nothing".** A material that says it is
+ * alpha tested has already said that something is meant to be discarded, so a reference of zero
+ * cannot be read literally without contradicting the flag beside it. Assetto Corsa's `*AT*` shaders
+ * carry a built-in reference and a material overrides it by stating one; stating zero is how a
+ * material says it is not overriding anything.
+ *
+ * **A half, because that is the convention those shaders were authored against**, and because the
+ * masks in question are two-valued: a grille's hole and a seat's stitching are cut out of a texture
+ * whose alpha is 0 or 255, so any threshold strictly inside the range separates them identically.
+ * What would make this wrong is a material whose mask is a soft gradient, which wants blending
+ * rather than a test and says so with `alphaBlendMode`.
+ */
+const DEFAULT_ALPHA_REFERENCE = 0.5;
+function alphaReference(stated) {
+    return stated > 0 ? stated : DEFAULT_ALPHA_REFERENCE;
+}
 const KNOWN_SHADERS = new Set([
     'ksPerPixelAlpha',
     'ksWindscreen',
@@ -441,7 +460,7 @@ export function kn5ToMeshes(buffer) {
              * rather than on evidence — stated plainly for the same reason the bone block is read past
              * rather than interpreted. What the change fixes is not this line but the one above it.
              */
-            cutout: material.alphaTested ? property('ksAlphaRef', 0) : 0,
+            cutout: material.alphaTested ? alphaReference(property('ksAlphaRef', 0)) : 0,
             albedo: bind(material, 'txDiffuse'),
             normalMap: bind(material, 'txNormal'),
             /*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/assets",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "description": "Model readers and the streaming loader for the .drft container",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,11 +27,11 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.1.1",
-    "@driftengine/texture": "4.1.1"
+    "@driftengine/drft": "4.1.3",
+    "@driftengine/texture": "4.1.3"
   },
   "peerDependencies": {
-    "@driftengine/core": "4.1.1"
+    "@driftengine/core": "4.1.3"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/drftLoader.ts

@@ -1162,20 +1162,37 @@ export function isRawCodec(codec: number): boolean {
  * the view would keep the whole file alive for as long as the image does.
  */
 /**
- * How every image a model carries is decoded: **straight alpha, and no colour conversion.**
+ * How every image a model carries is decoded: **premultiplied, and no colour conversion.**
  *
- * `createImageBitmap` premultiplies unless told not to, and the upload into a straight-alpha
- * texture then divides back out. A texel with no alpha comes back with no colour, so a cutout or an
- * emblem loses the colour its author padded past its edge, and filtering pulls black into the edge;
- * a partly transparent one comes back rounded to a coarser step. Colour management rewrites a normal
- * or ORM map, whose values are not colours at all, and glTF — which these assets are baked from —
- * says an image's own colour metadata is ignored. `render/imageTexels.ts` asks for the same two.
+ * **Straight alpha was tried in 4.0.0 and it is what this reverts.** The argument for it was that
+ * `createImageBitmap` premultiplies by default, so a texel with no alpha comes back with no colour
+ * and a cutout or an emblem loses the colour its author padded past its edge. That reasoning is
+ * sound about the pixels and wrong about the content: an imported material's albedo routinely
+ * carries arbitrary bytes under its fully transparent texels, and premultiplying was what kept
+ * them out of the frame.
  *
- * What it gives up: an albedo authored in a wide-gamut space with a profile saying so is read as
- * sRGB. The baker is where that conversion belongs, and it has no colour management either.
+ * **What it cost, reported and then reproduced.** A car came through with its interior, grille,
+ * mirrors and lamps as hard black and white shards. Held frames of one scene in the showroom, on
+ * one machine, at one frame: a model with 41 images drew clean and two with 64 and 65 drew shards,
+ * on **both** backends, with the old container and the new one alike — the count only decides how
+ * likely a model is to carry a masked texture at all. Restoring this one option drew the car
+ * correctly again.
+ *
+ * **Why an opaque material sees it.** Nothing discards on an opaque draw, so the shader takes
+ * `texel.rgb` whatever the alpha beside it says. Premultiplied, the bytes under a mask arrive as
+ * black and disappear into a dark surface; straight, they arrive as whatever the exporter left
+ * there. A material that genuinely means to cut out says so with its own alpha reference, which is
+ * what `kn5.ts`'s `alphaReference` now reads correctly.
+ *
+ * **What would make this wrong:** content authored *for* straight alpha, whose colour under a mask
+ * is meaningful and wanted — a decal atlas relying on the padding. Nothing measured here is that,
+ * and the day one arrives it wants the option per material rather than per engine.
+ *
+ * `colorSpaceConversion` stays off: a normal or ORM map holds values that are not colours, and
+ * glTF says an image's own colour metadata is ignored.
  */
 const AS_AUTHORED = {
-  premultiplyAlpha: 'none',
+  premultiplyAlpha: 'premultiply',
   colorSpaceConversion: 'none',
 } as const satisfies ImageBitmapOptions;
 

package/src/kn5.ts

@@ -430,6 +430,27 @@ export function readKn5Nodes(header: Kn5Header): { nodes: Kn5Node[]; meshes: Kn5
  * this stays only for the warning, which is the thing a name genuinely can answer: a shader
  * nobody here has seen is still geometry somebody wants.
  */
+/**
+ * What a tested material's alpha reference actually is, where it states zero or states none.
+ *
+ * **Zero means the shader's own threshold, not "discard nothing".** A material that says it is
+ * alpha tested has already said that something is meant to be discarded, so a reference of zero
+ * cannot be read literally without contradicting the flag beside it. Assetto Corsa's `*AT*` shaders
+ * carry a built-in reference and a material overrides it by stating one; stating zero is how a
+ * material says it is not overriding anything.
+ *
+ * **A half, because that is the convention those shaders were authored against**, and because the
+ * masks in question are two-valued: a grille's hole and a seat's stitching are cut out of a texture
+ * whose alpha is 0 or 255, so any threshold strictly inside the range separates them identically.
+ * What would make this wrong is a material whose mask is a soft gradient, which wants blending
+ * rather than a test and says so with `alphaBlendMode`.
+ */
+const DEFAULT_ALPHA_REFERENCE = 0.5;
+
+function alphaReference(stated: number): number {
+  return stated > 0 ? stated : DEFAULT_ALPHA_REFERENCE;
+}
+
 const KNOWN_SHADERS = new Set([
   'ksPerPixelAlpha',
   'ksWindscreen',
@@ -591,7 +612,7 @@ export function kn5ToMeshes(buffer: ArrayBuffer): Kn5Import {
        * rather than on evidence — stated plainly for the same reason the bone block is read past
        * rather than interpreted. What the change fixes is not this line but the one above it.
        */
-      cutout: material.alphaTested ? property('ksAlphaRef', 0) : 0,
+      cutout: material.alphaTested ? alphaReference(property('ksAlphaRef', 0)) : 0,
       albedo: bind(material, 'txDiffuse'),
       normalMap: bind(material, 'txNormal'),
       /*