@woosh/meep-engine 3.14.0 → 3.14.2

package/src/shade/renderer/texture/texture_write_to_gpu.js

@@ -4,7 +4,8 @@ import { to_half_float_uint16 } from "../../../core/binary/to_half_float_uint16.
 import { BinaryDataType } from "../../../core/binary/type/BinaryDataType.js";
 import { dataTypeByteSize } from "../../../core/binary/type/DataTypeByteSizes.js";
 import { array_copy } from "../../../core/collection/array/array_copy.js";
-import { ColorSpace } from "./ColorSpace.js";
+import { AlphaMode } from "./source/AlphaMode.js";
+import { texture_write_level } from "./texture_write_level.js";
 import { gpu_texture_format_channel_count } from "./format/gpu_texture_format_channel_count.js";
 
 /**
@@ -82,13 +83,22 @@ function premultiply_rgba_in_place(data, data_type) {
 }
 
 /**
+ * Bring loose pixels into the shape the texture's format expects, then hand them to
+ * {@link texture_write_level}.
+ *
+ * Padding and premultiplication happen *before* the write rather than inside it, which is what keeps
+ * the primitive a primitive: it takes texels that are already correct, and a payload that arrived
+ * correct (a {@link ShadeTexelData}) skips this function entirely rather than threading a "nothing
+ * to do" flag through it.
+ *
+ * A single-level path by construction — a `Sampler2D` or an `ArrayBuffer` is one level of pixels, and
+ * any others are generated.
  *
  * @param {ShadeImage} image
  * @param {ArrayBuffer} source_data
  * @param {GPUQueue} queue
  * @param {GPUTexture} texture
  * @param {boolean} premultiplyAlpha
- * @param copySize
  */
 function texture_write_raw(
     image,
@@ -101,10 +111,6 @@ function texture_write_raw(
     const source_channel_count = image.channel_count;
     const source_bytes_per_element = dataTypeByteSize(image.data_type);
 
-    const bytes_per_pixel = source_channel_count * source_bytes_per_element;
-
-    let bytesPerRow = bytes_per_pixel * image.width;
-
     let upload_data = source_data;
 
     if (source_channel_count === 3) {
@@ -143,9 +149,6 @@ function texture_write_raw(
             );
         }
 
-        //
-        bytesPerRow = source_bytes_per_element * image.width * 4;
-
         // alpha is 1 everywhere, premultiplication is the identity
 
     } else if (premultiplyAlpha && source_channel_count === 4) {
@@ -156,46 +159,41 @@ function texture_write_raw(
         premultiply_rgba_in_place(upload_data, image.data_type);
     }
 
-    const dataLayout = {
-        offset: 0,
-        bytesPerRow: bytesPerRow
-    };
-
-    if(image.depth > 1){
-        dataLayout.rowsPerImage = image.height;
-    }
-
-    queue.writeTexture(
-        {
-            texture: texture,
-            mipLevel: 0,
-            origin: {
-                x: 0, y: 0, z: 0
-            },
-        },
-        upload_data,
-        dataLayout,
-        [image.width, image.height, image.depth]
-    )
-
+    /*
+     Row stride is no longer computed here. It comes from the texture's format, which is the only
+     thing that knows how wide a row of blocks is — and which, for the padded case above, correctly
+     reports the four channels the texture has rather than the three the image had.
+    */
+    texture_write_level(queue, texture, 0, upload_data);
 }
 
 /**
+ * Upload an image's texels into a texture.
+ *
+ * `level_count` says how many of the image's levels to write, from the base up, and is required
+ * rather than defaulted: the one caller that wants fewer than all of them — {@link TextureManager},
+ * about to run the mip generator — is the caller least able to have that decision made for it.
+ * Uploading levels the generator is about to overwrite is bytes across the bus for nothing.
  *
  * @param {ShadeImage} image
  * @param {GPUTexture} texture
  * @param {GPUQueue} queue
+ * @param {number} level_count how many levels to write; `image.level_count` for all of them
  */
 export function texture_write_to_gpu(
     image,
     texture,
-    queue
+    queue,
+    level_count
 ) {
 
     assert.defined(image, 'image');
     assert.defined(texture, 'texture');
     assert.defined(queue, 'queue');
 
+    assert.isNonNegativeInteger(level_count, 'level_count');
+    assert.greaterThan(level_count, 0, 'level_count');
+
     assert.equal(image.isShadeImage, true, "image.isShadeImage !== true");
 
     const source = image.source;
@@ -210,11 +208,38 @@ export function texture_write_to_gpu(
         depthOrArrayLayers: texture.depthOrArrayLayers,
     };
 
-    /**
-     * see https://www.realtimerendering.com/blog/gpus-prefer-premultiplication/
-     * @type {boolean}
-     */
-    const premultiplyAlpha = image.color_space !== ColorSpace.None;
+    /*
+     Asked of the image rather than re-derived here. `AlphaMode.Straight` is what `color_space !==
+     None` used to mean inline, so this is the same decision — but it is now one the image can be
+     told, which is how a payload that arrived already premultiplied (an encoder's output) says so.
+    */
+    const premultiplyAlpha = image.alpha_mode === AlphaMode.Straight;
+
+    if (source.isShadeTexelData === true) {
+        /*
+         Already in the texture's format, already laid out in rows of blocks. Nothing to pad, nothing
+         to premultiply — an encoder did both, or there was nothing to do — so the levels go straight
+         down.
+
+         A level may be absent: a streaming payload declares its whole chain up front and fills it in
+         coarsest-first, so "not here yet" is an ordinary state rather than a gap to complain about.
+        */
+        const levels = source.levels;
+
+        const upload_count = Math.min(level_count, levels.length);
+
+        for (let level = 0; level < upload_count; level++) {
+            const bytes = levels[level];
+
+            if (bytes === undefined) {
+                continue;
+            }
+
+            texture_write_level(queue, texture, level, bytes);
+        }
+
+        return;
+    }
 
     if (source.isSampler2D) {
 

package/src/shade/renderer/texture/virtual/source/VTSourceImage.d.ts

@@ -13,6 +13,14 @@
  *
  * Layers are the standard group order: [albedo, normal, orm]. Pass
  * `undefined` for layers the material doesn't have — they're masked out.
+ *
+ * **Uncompressed sources only, structurally.** Page borders are resolved here at
+ * runtime by blitting from neighbouring content, and for block-compressed data
+ * that is impossible: the border and the page interior share blocks at the seam,
+ * and re-encoding a block at runtime is machinery the engine does not have. A
+ * compressed stack has to come from a source whose tiles were produced with their
+ * borders already inside them — {@link VTSourceTiled} — which is also what
+ * {@link VTPhysicalCache#upload} means by "border already baked in".
  */
 export class VTSourceImage {
     /**

package/src/shade/renderer/texture/virtual/source/VTSourceImage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VTSourceImage.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/texture/virtual/source/VTSourceImage.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH;IAyBI;;;;;;OAMG;IACH;QAJ+E,MAAM,EAA1E,CAAC,WAAW,GAAC,gBAAgB,GAAC,eAAe,GAAC,SAAS,CAAC,EAAE;QAExC,IAAI,GAAtB,OAAO;OAajB;IAzCD;;OAEG;IACH,YAFU,MAAM,CAED;IAwCf,6BA2CC;IAED;;;;;;;OAOG;IACH,eANW,MAAM,KACN,MAAM,KACN,MAAM,UACN,WAAW,GACT,QAAQ,CAAC,WAAW,GAAC,SAAS,CAAC,EAAE,CAAC,CAuF9C;IAED,gBAEC;;CACJ"}
+{"version":3,"file":"VTSourceImage.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/texture/virtual/source/VTSourceImage.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAyBI;;;;;;OAMG;IACH;QAJ+E,MAAM,EAA1E,CAAC,WAAW,GAAC,gBAAgB,GAAC,eAAe,GAAC,SAAS,CAAC,EAAE;QAExC,IAAI,GAAtB,OAAO;OAajB;IAzCD;;OAEG;IACH,YAFU,MAAM,CAED;IAwCf,6BA2CC;IAED;;;;;;;OAOG;IACH,eANW,MAAM,KACN,MAAM,KACN,MAAM,UACN,WAAW,GACT,QAAQ,CAAC,WAAW,GAAC,SAAS,CAAC,EAAE,CAAC,CAuF9C;IAED,gBAEC;;CACJ"}

package/src/shade/renderer/texture/virtual/source/VTSourceImage.js

@@ -15,6 +15,14 @@ import { assert } from "../../../../../core/assert.js";
  *
  * Layers are the standard group order: [albedo, normal, orm]. Pass
  * `undefined` for layers the material doesn't have — they're masked out.
+ *
+ * **Uncompressed sources only, structurally.** Page borders are resolved here at
+ * runtime by blitting from neighbouring content, and for block-compressed data
+ * that is impossible: the border and the page interior share blocks at the seam,
+ * and re-encoding a block at runtime is machinery the engine does not have. A
+ * compressed stack has to come from a source whose tiles were produced with their
+ * borders already inside them — {@link VTSourceTiled} — which is also what
+ * {@link VTPhysicalCache#upload} means by "border already baked in".
  */
 export class VTSourceImage {
 

package/src/shade/util/texture_mip_extent.d.ts

@@ -0,0 +1,49 @@
+/**
+ * One dimension of a texture at `level`.
+ *
+ * Halving, floored at 1 — a 1024-wide texture is still 1 texel wide at level 10 and at level 20.
+ * Trivial, and re-derived in enough places that getting it wrong is a real event rather than a
+ * hypothetical one.
+ *
+ * @param {number} size texels, at the base level
+ * @param {number} level
+ * @returns {number} texels, at `level`
+ */
+export function texture_mip_size(size: number, level: number): number;
+/**
+ * The extent of a texture at `level`.
+ *
+ * **Only a 3D texture's depth halves.** The third component of an array texture is a layer count,
+ * and every layer carries every mip — so it does not shrink with the others. That single distinction
+ * is the reason this exists as a named thing: written out by hand it reads as an obvious `>> level`
+ * on all three components, and that mistake under-reported a six-layer cube map's memory by close to
+ * half and would have uploaded its levels at the wrong extent.
+ *
+ * @param {number} width texels, at the base level
+ * @param {number} height texels, at the base level
+ * @param {number} depth_or_layers depth for a 3D texture, layer count otherwise
+ * @param {GPUTextureDimension|string} dimension
+ * @param {number} level
+ * @returns {number[]} `[width, height, depthOrArrayLayers]` at `level`, in the shape
+ * `GPUExtent3D` takes
+ */
+export function texture_mip_extent(width: number, height: number, depth_or_layers: number, dimension: GPUTextureDimension | string, level: number): number[];
+/**
+ * The number of levels in a texture's full mip chain.
+ *
+ * The count that {@link texture_mip_extent} implies: the chain runs until every halving axis has
+ * reached 1, so it is as long as the longest axis that halves. **Only a 3D texture's depth halves**
+ * — the same distinction, one derivative up. Written as `max(width, height)` it silently truncates
+ * every volume deeper than it is wide: a 4x4x16 has five levels and that reading gives three, while
+ * `texture_mip_extent` will happily report the extent of all five.
+ *
+ * A zero-sized texture has no levels. Any other size has at least one, which is what the `+ 1` is.
+ *
+ * @param {number} width texels, at the base level
+ * @param {number} height texels, at the base level
+ * @param {number} depth_or_layers depth for a 3D texture, layer count otherwise
+ * @param {GPUTextureDimension|string} dimension
+ * @returns {number}
+ */
+export function texture_mip_level_count(width: number, height: number, depth_or_layers: number, dimension: GPUTextureDimension | string): number;
+//# sourceMappingURL=texture_mip_extent.d.ts.map

package/src/shade/util/texture_mip_extent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"texture_mip_extent.d.ts","sourceRoot":"","sources":["../../../../src/shade/util/texture_mip_extent.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,uCAJW,MAAM,SACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,0CARW,MAAM,UACN,MAAM,mBACN,MAAM,aACN,sBAAoB,MAAM,SAC1B,MAAM,GACJ,MAAM,EAAE,CAYpB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,+CANW,MAAM,UACN,MAAM,mBACN,MAAM,aACN,sBAAoB,MAAM,GACxB,MAAM,CA0BlB"}

package/src/shade/util/texture_mip_extent.js

@@ -0,0 +1,87 @@
+import { assert } from "../../core/assert.js";
+
+/**
+ * One dimension of a texture at `level`.
+ *
+ * Halving, floored at 1 — a 1024-wide texture is still 1 texel wide at level 10 and at level 20.
+ * Trivial, and re-derived in enough places that getting it wrong is a real event rather than a
+ * hypothetical one.
+ *
+ * @param {number} size texels, at the base level
+ * @param {number} level
+ * @returns {number} texels, at `level`
+ */
+export function texture_mip_size(size, level) {
+    return Math.max(size >> level, 1);
+}
+
+/**
+ * The extent of a texture at `level`.
+ *
+ * **Only a 3D texture's depth halves.** The third component of an array texture is a layer count,
+ * and every layer carries every mip — so it does not shrink with the others. That single distinction
+ * is the reason this exists as a named thing: written out by hand it reads as an obvious `>> level`
+ * on all three components, and that mistake under-reported a six-layer cube map's memory by close to
+ * half and would have uploaded its levels at the wrong extent.
+ *
+ * @param {number} width texels, at the base level
+ * @param {number} height texels, at the base level
+ * @param {number} depth_or_layers depth for a 3D texture, layer count otherwise
+ * @param {GPUTextureDimension|string} dimension
+ * @param {number} level
+ * @returns {number[]} `[width, height, depthOrArrayLayers]` at `level`, in the shape
+ * `GPUExtent3D` takes
+ */
+export function texture_mip_extent(width, height, depth_or_layers, dimension, level) {
+    assert.isString(dimension, 'dimension');
+    assert.isNonNegativeInteger(level, 'level');
+
+    return [
+        texture_mip_size(width, level),
+        texture_mip_size(height, level),
+        dimension === "3d" ? texture_mip_size(depth_or_layers, level) : depth_or_layers,
+    ];
+}
+
+/**
+ * The number of levels in a texture's full mip chain.
+ *
+ * The count that {@link texture_mip_extent} implies: the chain runs until every halving axis has
+ * reached 1, so it is as long as the longest axis that halves. **Only a 3D texture's depth halves**
+ * — the same distinction, one derivative up. Written as `max(width, height)` it silently truncates
+ * every volume deeper than it is wide: a 4x4x16 has five levels and that reading gives three, while
+ * `texture_mip_extent` will happily report the extent of all five.
+ *
+ * A zero-sized texture has no levels. Any other size has at least one, which is what the `+ 1` is.
+ *
+ * @param {number} width texels, at the base level
+ * @param {number} height texels, at the base level
+ * @param {number} depth_or_layers depth for a 3D texture, layer count otherwise
+ * @param {GPUTextureDimension|string} dimension
+ * @returns {number}
+ */
+export function texture_mip_level_count(width, height, depth_or_layers, dimension) {
+    assert.isString(dimension, 'dimension');
+
+    assert.isNumber(width, 'width');
+    assert.isNumber(height, 'height');
+    assert.isNumber(depth_or_layers, 'depth_or_layers');
+
+    assert.notNaN(width, 'width');
+    assert.notNaN(height, 'height');
+    assert.notNaN(depth_or_layers, 'depth_or_layers');
+
+    assert.greaterThanOrEqual(width, 0, 'width');
+    assert.greaterThanOrEqual(height, 0, 'height');
+    assert.greaterThanOrEqual(depth_or_layers, 0, 'depth_or_layers');
+
+    const longest = dimension === "3d"
+        ? Math.max(width, height, depth_or_layers)
+        : Math.max(width, height);
+
+    if (longest === 0) {
+        return 0;
+    }
+
+    return Math.floor(Math.log2(longest)) + 1;
+}

package/src/avif/native/isobmff/ByteCursor.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ByteCursor.d.ts","sourceRoot":"","sources":["../../../../../src/avif/native/isobmff/ByteCursor.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH;IACI;;OAEG;IACH,MAFU,QAAQ,CAEN;IAEZ;;OAEG;IACH,OAFU,UAAU,CAEP;IAEb;;;OAGG;IACH,UAFU,MAAM,CAEH;IAEb;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;;;;OAKG;IACH,aALW,WAAW,GAAC,UAAU,gBACtB,MAAM,gBACN,MAAM,GACJ,UAAU,CAmBtB;IAED;;;;;OAKG;IACH,wBAJW,MAAM,eACN,MAAM,GACJ,UAAU,CAetB;IAED;;OAEG;IACH,wBAEC;IAED;;;OAGG;IACH,eAHW,MAAM,QACN,MAAM,QAMhB;IAED;;OAEG;IACH,MAFa,MAAM,CAMlB;IAED;;OAEG;IACH,OAFa,MAAM,CAUlB;IAED;;OAEG;IACH,OAFa,MAAM,CAWlB;IAED;;OAEG;IACH,OAFa,MAAM,CAUlB;IAED;;OAEG;IACH,OAFa,MAAM,CAUlB;IAED;;OAEG;IACH,OAFa,MAAM,CAUlB;IAED;;;;;;;OAOG;IACH,OAFa,MAAM,CAelB;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,CAoBlB;IAED;;;OAGG;IACH,UAFa,MAAM,CAUlB;IAED;;;;OAIG;IACH,eAFa,MAAM,CAgBlB;IAED;;;;OAIG;IACH,mBAHW,MAAM,GACJ,UAAU,CAUtB;IAED;;OAEG;IACH,YAFW,MAAM,QAMhB;IAED;;OAEG;IACH,eAFW,MAAM,QAQhB;CACJ"}

package/src/engine/asset/loaders/image/codec/Codec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Codec.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/codec/Codec.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH;IACI;;;;OAIG;IACH,aAHW,UAAU,GACR,QAAQ,CAAC,CAAC,CAKtB;IAED;;;;OAIG;IACH,WAHW,UAAU,GACT,QAAQ,OAAO,CAAC,CAI3B;CACJ"}

package/src/engine/asset/loaders/image/codec/CodecWithFallback.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"CodecWithFallback.d.ts","sourceRoot":"","sources":["../../../../../../../src/engine/asset/loaders/image/codec/CodecWithFallback.js"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH;IAOI;;;OAGG;IACH,uBAFW,MAAM,CAAC,CAAC,EAclB;IAtBD;;;OAGG;IACH,UAFU,MAAM,CAAC,CAAC,EAAE,CAEP;IAgCb,kCAeC;IAED,8BAuCC;;CACJ;sBAtGqB,YAAY"}

package/src/shade/util/compute_max_mip_count.d.ts

@@ -1,8 +0,0 @@
-/**
- * Maximum mip count for given texture dimensions
- * @param {number} width
- * @param {number} height
- * @returns {number}
- */
-export function compute_max_mip_count(width: number, height: number): number;
-//# sourceMappingURL=compute_max_mip_count.d.ts.map

package/src/shade/util/compute_max_mip_count.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"compute_max_mip_count.d.ts","sourceRoot":"","sources":["../../../../src/shade/util/compute_max_mip_count.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,6CAJW,MAAM,UACN,MAAM,GACJ,MAAM,CAoBlB"}

package/src/shade/util/compute_max_mip_count.js

@@ -1,27 +0,0 @@
-import { assert } from "../../core/assert.js";
-
-/**
- * Maximum mip count for given texture dimensions
- * @param {number} width
- * @param {number} height
- * @returns {number}
- */
-export function compute_max_mip_count(width, height) {
-    assert.isNumber(width, 'width');
-    assert.isNumber(height, 'height');
-
-    assert.notNaN(width, "width");
-    assert.notNaN(height, "height");
-
-    assert.greaterThanOrEqual(width, 0);
-    assert.greaterThanOrEqual(height, 0);
-
-    // the +1 is to indicate that there's always at least 1 level
-    const max_size = Math.max(width, height);
-
-    if (max_size === 0) {
-        return 0;
-    }
-
-    return Math.floor(Math.log2(max_size)) + 1;
-}