@driftengine/assets 4.1.2 → 4.1.4

package/README.md

@@ -2,7 +2,7 @@
 
 Model readers for seven formats, and the streaming loader that uploads them.
 
-**Cost: 12.5 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 12.7 KB gzipped on top of core.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

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/index.d.ts

@@ -70,4 +70,6 @@ export type { ClusterOptions, ClusterSet } from './bake/cluster.ts';
 export { buildClusterDag } from './bake/clusterLod.ts';
 export type { ClusterDag, ClusterLevel } from './bake/clusterLod.ts';
 export { bakeObjectSdf } from './bake/sdf.ts';
+export { IMPOSTOR_GUTTER, IMPOSTOR_TILE, PROXY_BASE_CELLS, PROXY_MIN_CELLS, buildImpostor, buildProxy, frameOf, octahedralCoord, octahedralDirection, proxyResolution, rasteriseView, sampleImpostor, } from './bake/hlod.ts';
+export type { Impostor, ProxyCell, ViewFrame } from './bake/hlod.ts';
 export type { ObjectSdf } from './bake/sdf.ts';

package/dist/index.js

@@ -165,3 +165,16 @@ export { buildClusterDag } from './bake/clusterLod.js';
  * carries, and a field a consumer cannot bake is a pipeline with no input.
  */
 export { bakeObjectSdf } from './bake/sdf.js';
+/*
+ * **The third time, and the one that got furthest before anybody noticed.** `bake/hlod.ts` builds
+ * the proxies and impostors `docs/CAPABILITIES.md` lists as shipping, it is tested, it is sized and
+ * it carries the licence — and until this line its only importer in the whole repository was its
+ * own test. A consumer following "the barrel is the contract" could read the row, believe the
+ * capability, and find no way to call it.
+ *
+ * The paragraph above says a demo boundary test caught the cluster case. Nothing caught this one,
+ * because no scene tried to bake an impostor — which is what the two paragraphs above are worth
+ * together: **a module reached only by its own test is not shipped, and no gate here asks.** Found
+ * by censusing what three consumers could adopt and what they could not.
+ */
+export { IMPOSTOR_GUTTER, IMPOSTOR_TILE, PROXY_BASE_CELLS, PROXY_MIN_CELLS, buildImpostor, buildProxy, frameOf, octahedralCoord, octahedralDirection, proxyResolution, rasteriseView, sampleImpostor, } from './bake/hlod.js';

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.2",
+  "version": "4.1.4",
   "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.2",
-    "@driftengine/texture": "4.1.2"
+    "@driftengine/drft": "4.1.4",
+    "@driftengine/texture": "4.1.4"
   },
   "peerDependencies": {
-    "@driftengine/core": "4.1.2"
+    "@driftengine/core": "4.1.4"
   },
   "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/index.ts

@@ -199,4 +199,31 @@ export type { ClusterDag, ClusterLevel } from './bake/clusterLod.ts';
  * carries, and a field a consumer cannot bake is a pipeline with no input.
  */
 export { bakeObjectSdf } from './bake/sdf.ts';
+/*
+ * **The third time, and the one that got furthest before anybody noticed.** `bake/hlod.ts` builds
+ * the proxies and impostors `docs/CAPABILITIES.md` lists as shipping, it is tested, it is sized and
+ * it carries the licence — and until this line its only importer in the whole repository was its
+ * own test. A consumer following "the barrel is the contract" could read the row, believe the
+ * capability, and find no way to call it.
+ *
+ * The paragraph above says a demo boundary test caught the cluster case. Nothing caught this one,
+ * because no scene tried to bake an impostor — which is what the two paragraphs above are worth
+ * together: **a module reached only by its own test is not shipped, and no gate here asks.** Found
+ * by censusing what three consumers could adopt and what they could not.
+ */
+export {
+  IMPOSTOR_GUTTER,
+  IMPOSTOR_TILE,
+  PROXY_BASE_CELLS,
+  PROXY_MIN_CELLS,
+  buildImpostor,
+  buildProxy,
+  frameOf,
+  octahedralCoord,
+  octahedralDirection,
+  proxyResolution,
+  rasteriseView,
+  sampleImpostor,
+} from './bake/hlod.ts';
+export type { Impostor, ProxyCell, ViewFrame } from './bake/hlod.ts';
 export type { ObjectSdf } from './bake/sdf.ts';

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'),
       /*