@woosh/meep-engine 2.42.7 → 2.43.0

package/engine/graphics/texture/atlas/CachingTextureAtlas.js

@@ -1,13 +1,30 @@
-import { Cache } from "../../../../core/cache/Cache.js";
 import { AbstractTextureAtlas } from "./AbstractTextureAtlas.js";
-import { invokeObjectHash } from "../../../../core/model/object/invokeObjectHash.js";
+
+class PatchRecord {
+    constructor() {
+        /**
+         *
+         * @type {AtlasPatch|null}
+         */
+        this.patch = null;
+
+        /**
+         * When was the patch last used
+         * @type {number}
+         */
+        this.last_use_time = 0;
+    }
+}
 
 /**
- * 4Mb
- * @type {number}
+ * Adding and removing elements to atlas can be costly. It can trigger repack, it may require splatting or cleaning.
+ * This abstraction allows us to bypass that most of the time by caching unused patches and just reusing them in the future
+ * if they are requested again.
+ *
+ * The caching strategy here is a little unusual. The texture atlas has a certain size, and the cache will use as much of
+ * the atlas space as it can. Meaning that if there is not much unused space - the cache will be very small
+ * And if only a small part of the atlas is area is used by "live" patches, the cache can be quite large
  */
-const DEFAULT_CACHE_SIZE = 4194304;
-
 export class CachingTextureAtlas extends AbstractTextureAtlas {
     /**
      *
@@ -15,23 +32,16 @@ export class CachingTextureAtlas extends AbstractTextureAtlas {
      * @param {number} cache_size
      */
     constructor({
-                    atlas,
-                    cache_size = DEFAULT_CACHE_SIZE
+                    atlas
                 }) {
         super();
 
         /**
          *
-         * @type {Cache<Sampler2D, AtlasPatch>}
+         * @type {PatchRecord[]}
          * @private
          */
-        this.__cached_patches = new Cache({
-            maxWeight: cache_size,
-            keyHashFunction: invokeObjectHash,
-            keyWeigher(sampler) {
-                return sampler.computeByteSize();
-            }
-        });
+        this.__cached_patches = [];
 
         /**
          *
@@ -40,17 +50,156 @@ export class CachingTextureAtlas extends AbstractTextureAtlas {
          */
         this.__atals = atlas;
 
-        this.__cached_patches.onEvicted.add(this.__handle_cache_eviction, this);
+    }
+
+    /**
+     * Finds an entry in the cache to evict
+     * @returns {number}
+     * @private
+     */
+    __find_eviction_target() {
+        let best_date = Infinity;
+        let best_node = -1;
+
+        const records = this.__cached_patches;
+        const n = records.length;
+
+        for (let i = 0; i < n; i++) {
+            const record = records[i];
+
+            const date = record.last_use_time;
+
+            if (date < best_date) {
+                best_node = i;
+                best_date = date;
+            }
+
+        }
+
+        return best_node;
+    }
+
+    /**
+     * Finds an entry in the cache that could be replaced with an incoming element
+     * @private
+     * @returns {number}
+     * @param {number} width
+     * @param {number} height
+     */
+    __find_replacement_target(width, height) {
+        // find the smallest element in area that is least recently used in cache
+        let best_area = Infinity;
+        let best_date = Infinity;
+
+        let best_node = -1;
+
+        const records = this.__cached_patches;
+        const n = records.length;
+        for (let i = 0; i < n; i++) {
+            const record = records[i];
+
+            const packing = record.patch.packing;
+
+            const w = packing.x1 - packing.x0;
+            const h = packing.y1 - packing.y0;
+
+            if (w < width || h < height) {
+                // too small
+                continue;
+            }
+
+            const area = w * h;
+
+            if (area > best_area) {
+                // prefer smaller patches to evict, as they are cheaper to pull back later on
+                continue;
+            }
+
+            const date = record.last_use_time;
+
+            if (date >= best_date) {
+                // prefer patches that have been in cache the longest (the oldest records)
+                continue;
+            }
+
+            // found a better candidate, update
+
+            best_area = area;
+            best_date = date;
+
+            best_node = i;
+        }
+
+        return best_node;
+    }
+
+    /**
+     * Will evict specified element from cache
+     * @private
+     * @param {number} index
+     */
+    __evict(index) {
+        const records = this.__cached_patches;
+        const record = records[index];
+
+        records.splice(index, 1);
+        this.__atals.remove(record.patch);
+    }
+
+    /**
+     * Evict all cached elements, purging the cache
+     * @private
+     */
+    __evict_all() {
+        for (let i = this.__cached_patches.length - 1; i > 0; i--) {
+            this.__evict(i);
+        }
+    }
+
+    /**
+     * Free up space in cache to accommodate certain area
+     * @private
+     * @param {number} width
+     * @param {number} height
+     * @returns {boolean} true if enough space was freed up to fit specified area, false otherwise
+     */
+    __evict_for(width, height) {
+        if (this.__cached_patches.length <= 0) {
+            // nothing to evict
+            return false;
+        }
+
+        const target = this.__find_replacement_target(width, height);
+
+        if (target) {
+            // evicted just one element
+            this.__evict(target);
+            return true;
+        }
+
+        while (!this.__atals.can_pack(width, height)) {
+            const victim = this.__find_eviction_target();
+
+            if (victim === -1) {
+                return false;
+            }
+
+            this.__evict(victim);
+        }
+
+        return true;
     }
 
     update() {
         try {
             this.__atals.update();
         } catch (e) {
-            if (this.__cached_patches.size() > 0) {
+            // failed to perform update
+
+            if (this.__cached_patches.length > 0) {
 
                 // has some caches patches, lets drop them
-                this.__cached_patches.clear();
+                this.__evict_all();
 
                 // try to update again
                 this.__atals.update();
@@ -78,40 +227,56 @@ export class CachingTextureAtlas extends AbstractTextureAtlas {
         return this.__atals.sampler;
     }
 
-    /**
-     *
-     * @param {Sampler2D} sampler
-     * @param {AtlasPatch} patch
-     * @private
-     */
-    __handle_cache_eviction(sampler, patch) {
-        this.__atals.remove(patch);
-    }
-
     reset() {
-        this.__cached_patches.drop();
+        this.__cached_patches.splice(i, this.__cached_patches.length);
         this.__atals.reset();
     }
 
     /**
      *
      * @param {Sampler2D} sampler
-     * @returns {AtlasPatch}
+     * @returns {number}
+     * @private
      */
-    add(sampler) {
-        const existing_patch = this.__cached_patches.get(sampler);
+    __find_cache_record_index(sampler) {
+        const records = this.__cached_patches;
+        const n = records.length;
+        for (let i = 0; i < n; i++) {
+            if (records[i].patch.sampler === sampler) {
+                return i;
+            }
+        }
+
+        return -1;
+    }
+
+    add(sampler, padding = 4) {
+        const existing_patch_index = this.__find_cache_record_index(sampler);
+
+        const records = this.__cached_patches;
 
-        if (existing_patch !== null) {
+        if (existing_patch_index !== -1) {
             // cache hit
 
+            const record = records[existing_patch_index];
+
             // remove from cache
-            this.__cached_patches.remove(sampler);
+            records.splice(existing_patch_index, 1);
 
             // return patch
-            return existing_patch;
+            return record.patch;
+        }
+
+        const w = sampler.width + padding * 2;
+        const h = sampler.height + padding * 2;
+
+        if (records.length > 0 && !this.__atals.can_pack(w, h)) {
+            // new element will not fit, lets try to evict some cache to try and accommodate it
+            // note that eviction will purge the entire cache in case that this patch doesn't fit
+            this.__evict_for(w, h);
         }
 
-        return this.__atals.add(sampler);
+        return this.__atals.add(sampler, padding);
     }
 
     /**
@@ -126,7 +291,12 @@ export class CachingTextureAtlas extends AbstractTextureAtlas {
         }
 
         // push to cache, let eviction logic handle the rest
-        this.__cached_patches.put(patch.sampler, patch);
+        const record = new PatchRecord();
+
+        record.last_use_time = performance.now();
+        record.patch = patch;
+
+        this.__cached_patches.push(record);
 
         return true;
     }

package/engine/graphics/texture/atlas/TextureAtlas.js

@@ -1,6 +1,5 @@
-import { MaxRectanglesPacker } from "../../../../core/geom/packing/MaxRectangles.js";
+import { MaxRectanglesPacker } from "../../../../core/geom/packing/max-rect/MaxRectangles.js";
 import { max2 } from "../../../../core/math/max2.js";
-import { min2 } from "../../../../core/math/min2.js";
 import { Sampler2D } from "../sampler/Sampler2D.js";
 import IdPool from "../../../../core/IdPool.js";
 import Vector2 from "../../../../core/geom/Vector2.js";
@@ -14,6 +13,7 @@ import {
 } from "../../../../core/collection/table/DataType2TypedArrayConstructorMapping.js";
 import { AbstractTextureAtlas } from "./AbstractTextureAtlas.js";
 import { invokeObjectClone } from "../../../../core/model/object/invokeObjectClone.js";
+import { ceilPowerOfTwo } from "../../../../core/binary/operations/ceilPowerOfTwo.js";
 
 export class TextureAtlas extends AbstractTextureAtlas {
     /**
@@ -161,15 +161,12 @@ export class TextureAtlas extends AbstractTextureAtlas {
             if (patch.getFlag(AtlasPatchFlag.Packed)) {
                 //only care about packed patches
 
-                const pp = patch.position;
-                const ps = patch.size;
+                const x1 = patch.packing.x1;
+                const y1 = patch.packing.y1;
 
-                const x1 = pp.x + ps.x + patch.padding;
-                const y1 = pp.y + ps.y + patch.padding;
-
-                if (x1 >= x || y1 >= y) {
+                if (x1 > x || y1 > y) {
                     // patch bounds would violate the desired atlas extends
-                    //Resizing atlas would result in some patches not fitting
+                    // Resizing atlas would result in some patches not fitting
                     return false;
                 }
             }
@@ -278,6 +275,16 @@ export class TextureAtlas extends AbstractTextureAtlas {
         return patch;
     }
 
+    /**
+     * Whether a patch of certain size could be packed without triggering repack or growing the atlas
+     * @param {number} w
+     * @param {number} h
+     * @returns {boolean}
+     */
+    can_pack(w, h) {
+        return this.packer.canAdd(w, h);
+    }
+
     /**
      *
      * @param {AtlasPatch} patch
@@ -482,32 +489,32 @@ export class TextureAtlas extends AbstractTextureAtlas {
         // console.group("TextureAtlas.update");
         // console.time('TextureAtlas.update');
 
-        const maxPower = 14; //4096
+        const maxPower = 14;
 
-        const initialPower = Math.floor(
-            max2(
-                0,
-                Math.log2(
-                    min2(this.size.x, this.size.y)
-                )
-            )
-        );
+        const initial_p_x = max2(0, Math.log2(ceilPowerOfTwo(this.size.x)));
+        const initial_p_y = max2(0, Math.log2(ceilPowerOfTwo(this.size.y)));
 
-        let power = initialPower;
+        let power_x = initial_p_x;
+        let power_y = initial_p_y;
 
         while (!this.pack()) {
             //packing failed, grow canvas
 
             for (; ;) {
-                power++;
+                if (power_x < power_y) {
+                    power_x++;
+                } else {
+                    power_y++;
+                }
 
-                if (power > maxPower) {
-                    throw new Error(`Packing failed, could not pack ${this.patches.length} into ${Math.pow(2, maxPower)} resolution texture. Initial power: ${initialPower}`);
+                if (power_x > maxPower || power_y > maxPower) {
+                    throw new Error(`Packing failed, could not pack ${this.patches.length} into ${Math.pow(2, maxPower)} resolution texture. Initial powers: ${initial_p_x}, ${initial_p_y}`);
                 }
 
-                const size = Math.pow(2, power);
+                const size_x = Math.pow(2, power_x);
+                const size_y = Math.pow(2, power_y);
 
-                if (this.resize(size, size)) {
+                if (this.resize(size_x, size_y)) {
                     break;
                 }
             }

package/engine/graphics/texture/atlas/gpu/WebGLTextureAtlas.js

@@ -1,6 +1,6 @@
 import { AtlasPatch } from "../AtlasPatch.js";
 import IdPool from "../../../../../core/IdPool.js";
-import { MaxRectanglesPacker } from "../../../../../core/geom/packing/MaxRectangles.js";
+import { MaxRectanglesPacker } from "../../../../../core/geom/packing/max-rect/MaxRectangles.js";
 import {
     ClampToEdgeWrapping,
     DataTexture,

package/engine/graphics/texture/sampler/filter/box.js

@@ -0,0 +1,16 @@
+/**
+ * @see https://github.com/terifan/ImageResampler/blob/dbc212ce6aaa769bf3c9623cb6ead58ffd51d76c/src/org/terifan/image_resampler/FilterFactory.java#L330
+ * @param {number} x
+ * @returns {number}
+ */
+export function box(x) {
+    if (x < -0.5) {
+        return 0;
+    }
+    if (x <= 0.5) {
+        return 1;
+    }
+    return 0;
+}
+
+box.support = 0.5;

package/engine/graphics/texture/sampler/filter/cubic2.js

@@ -0,0 +1,32 @@
+/**
+ * @see https://github.com/terifan/ImageResampler/blob/dbc212ce6aaa769bf3c9623cb6ead58ffd51d76c/src/org/terifan/image_resampler/FilterFactory.java#L431
+ * @see https://www.intel.com/content/www/us/en/develop/documentation/ipp-dev-reference/top/volume-2-image-processing/ipp-ref-interpolation-in-image-geometry-transform/interpolation-with-two-parameter-cubic-filters.html
+ * @param {number} x
+ * @returns {number}
+ */
+export function cubic2(x){
+    const b = 0;
+    const c = 1;
+
+    if (x < -2.0)
+    {
+        return 0;
+    }
+    if (x < -1.0)
+    {
+        return Math.pow((12 - 9*b - 6*c) * Math.abs(x), 3) + Math.pow((-18 + 12*b + 6*c) * Math.abs(x), 2) + (6 - 2 * b) / 6;
+    }
+    if (x < 0.0)
+    {
+        return Math.pow((-b-6*c)*Math.abs(x), 3) + Math.pow((6*b+30*c)*Math.abs(x),2) + (-12*b-48*c)*Math.abs(x)+(8*b+24*c);
+    }
+    if (x < 1.0)
+    {
+        return Math.pow((-b-6*c)*Math.abs(x), 3) + Math.pow((6*b+30*c)*Math.abs(x),2) + (-12*b-48*c)*Math.abs(x)+(8*b+24*c);
+    }
+    if (x < 2.0)
+    {
+        return Math.pow((12 - 9*b - 6*c) * Math.abs(x), 3) + Math.pow((-18 + 12*b + 6*c) * Math.abs(x), 2) + (6 - 2 * b);
+    }
+    return 0;
+}

package/engine/graphics/texture/sampler/filter/gaussian.js

@@ -0,0 +1,16 @@
+/**
+ * Precomputed constant term
+ * @type {number}
+ */
+const a = Math.sqrt(2.0 / Math.PI);
+
+/**
+ *
+ * @param {number} x
+ * @returns {number}
+ */
+export function gaussian(x) {
+    return a * Math.exp(-2.0 * x * x);
+}
+
+gaussian.support = 1.25;

package/engine/graphics/texture/sampler/filter/kaiser_1.js

@@ -0,0 +1,19 @@
+import { bessel_i0 } from "../../../../../core/math/bessel_i0.js";
+import { clamp } from "../../../../../core/math/clamp.js";
+
+const BASE_I0 = bessel_i0(6.5);
+
+/**
+ * Support kernel size is 1
+ * @see https://github.com/terifan/ImageResampler/blob/dbc212ce6aaa769bf3c9623cb6ead58ffd51d76c/src/org/terifan/image_resampler/FilterFactory.java#L815
+ * @param {number} x
+ * @returns {number}
+ */
+export function kaiser_1(x) {
+    const i = clamp(x * 0.6666666666666666, -1.0, 1.0);
+    const i0a = 1 / BASE_I0;
+
+    return bessel_i0(6.5 * Math.sqrt(1 - i * i)) * i0a;
+}
+
+kaiser_1.support = 1;

package/engine/graphics/texture/sampler/filter/kaiser_bessel_window.js

@@ -0,0 +1,19 @@
+import { bessel_3 } from "../../../../../core/math/bessel_3.js";
+import { clamp } from "../../../../../core/math/clamp.js";
+
+const PI3 = 3.0 * Math.PI;
+const BESSEL_3_PI_3 = bessel_3(PI3);
+
+/**
+ *
+ * Kaiser Bessel window
+ * @see https://bgolus.medium.com/sharper-mipmapping-using-shader-based-supersampling-ed7aadb47bec#5bfb:~:text=Kaiser%2Dfiltered%20Mipmaps
+ * @see https://www.shadertoy.com/view/wlf3RH
+ */
+export function kaiser_bessel_window(x) {
+    const i = clamp(x * 0.6666666666666666, -1.0, 1.0);
+    const t = Math.sqrt(1.0 - i * i);
+    return bessel_3(PI3 * t) / BESSEL_3_PI_3;
+}
+
+kaiser_bessel_window.support = 2;

package/engine/graphics/texture/sampler/filter/mitchell.js

@@ -0,0 +1,55 @@
+const b = 1.0 / 3.0;
+const c = 1.0 / 3.0;
+
+/**
+ * @see Don P. Mitchell, Arun N. Netravali. Reconstruction Filters in Computer Graphics. Computer Graphics, Volume 22, Number 4, AT&T Bell Laboratories, Murray Hill, New Jersey, August 1988
+ * @see https://github.com/terifan/ImageResampler/blob/dbc212ce6aaa769bf3c9623cb6ead58ffd51d76c/src/org/terifan/image_resampler/FilterFactory.java#L540
+ * @param {number} x
+ * @returns {number}
+ */
+export function mitchell(x) {
+    const p0 = (6.0 - 2.0 * b) / 6.0;
+    const p2 = (-18.0 + 12.0 * b + 6.0 * c) / 6.0;
+    const p3 = (12.0 - 9.0 * b - 6.0 * c) / 6.0;
+    const q0 = (8.0 * b + 24.0 * c) / 6.0;
+    const q1 = (-12.0 * b - 48.0 * c) / 6.0;
+    const q2 = (6.0 * b + 30.0 * c) / 6.0;
+    const q3 = (-b - 6.0 * c) / 6.0;
+
+    if (x < -2.0) {
+        return 0.0;
+    }
+    if (x < -1.0) {
+        return q0 - x * (q1 - x * (q2 - x * q3));
+    }
+    if (x < 0.0) {
+        return p0 + x * x * (p2 - x * p3);
+    }
+    if (x < 1.0) {
+        return p0 + x * x * (p2 + x * p3);
+    }
+    if (x < 2.0) {
+        return q0 + x * (q1 + x * (q2 + x * q3));
+    }
+    return 0.0;
+}
+mitchell.support = 2;
+
+/**
+ * Hand-optimized mitchell function with c = 0.3333333 and b = 0.3333333
+ * NOTE: assumes non-negative values only
+ * @param {number} x
+ * @returns {number}
+ */
+export function mitchell_v1(x) {
+
+    if (x < 1.0) {
+        return 0.8888888888888888 + x * x * (-2 + x * 1.1666666666666667);
+    }
+    if (x < 2.0) {
+        return 1.7777777777777777 + x * (-3.3333333333333335 + x * (2 + x * -0.3888888888888889));
+    }
+    return 0.0;
+}
+
+mitchell_v1.support = 2;

package/engine/graphics/texture/sampler/filter/sampler2d_scale_down_generic.js

@@ -0,0 +1,109 @@
+import { max2 } from "../../../../../core/math/max2.js";
+import { min2 } from "../../../../../core/math/min2.js";
+
+/**
+ *
+ * @param {Sampler2D} source
+ * @param {Sampler2D} destination
+ * @param {(number)=>number|{support:number}} weight_computer
+ * @param {number} support size of support kernel
+ */
+export function sampler2d_scale_down_generic(source, destination, weight_computer, support = weight_computer.support) {
+
+    const d_w = destination.width;
+    const d_h = destination.height;
+
+    const item_size = destination.itemSize;
+
+    const source_width = source.width;
+    const source_height = source.height;
+
+    if (source_width < d_w || source_height < d_h) {
+        throw new Error('Invalid scale, source is larger than destination in at least 1 dimension');
+    }
+
+    const source_data = source.data;
+    const destination_data = destination.data;
+
+    const ratio_x = source_width / d_w;
+    const ratio_y = source_height / d_h;
+
+    const rcp_ratio_y = 2 / ratio_x;
+    const rcp_ratio_x = 2 / ratio_x;
+
+
+    const range2_x = Math.ceil(ratio_x * support / 2);
+    const range2_y = Math.ceil(ratio_y * support / 2);
+
+    const sample = new Array(item_size);
+
+    let v, u, i, j, k;
+
+    for (v = 0; v < d_h; v++) {
+
+        const center_y = (v + 0.5) * ratio_y;
+        const i_center_y = Math.floor(center_y);
+        //
+        const source_y0 = max2(0, i_center_y - range2_y);
+        const source_y1 = min2(i_center_y + range2_y, source_height - 1);
+
+        for (u = 0; u < d_w; u++) {
+            const center_x = (u + 0.5) * ratio_x;
+            const i_center_x = Math.floor(center_x);
+
+            const source_x0 = max2(i_center_x - range2_x, 0);
+            const source_x1 = min2(i_center_x + range2_x, source_width - 1);
+
+            let z = 0;
+            // reset sample
+            for (i = 0; i < item_size; i++) {
+                sample[i] = 0;
+            }
+
+            for (j = source_y0; j <= source_y1; j++) {
+
+                const f_y = (j - center_y);
+
+                const f_y_rcp = f_y * rcp_ratio_y;
+                const f_y_rcp2 = f_y_rcp * f_y_rcp;
+
+                for (i = source_x0; i <= source_x1; i++) {
+
+                    const f_x = (i - center_x);
+
+                    const f_x_rcp = f_x * rcp_ratio_x;
+                    const f_x_rcp2 = f_x_rcp * f_x_rcp;
+
+                    const distance_from_center_sqr = f_x_rcp2 + f_y_rcp2;
+                    const distance_from_center = Math.sqrt(distance_from_center_sqr);
+
+                    const weight = weight_computer(distance_from_center);
+
+                    if (weight <= 0) {
+                        continue;
+                    }
+
+                    z += weight;
+
+                    const source_texel_address = (j * source_width + i) * item_size;
+
+                    for (k = 0; k < item_size; k++) {
+                        sample[k] += weight * source_data[source_texel_address + k];
+                    }
+
+                }
+            }
+
+
+            // dilute sample and write to destination
+            const inv_z = 1 / z;
+
+            const texel_address = (v * d_w + u) * item_size;
+
+            for (i = 0; i < item_size; i++) {
+                destination_data[texel_address + i] = sample[i] * inv_z;
+            }
+        }
+    }
+
+}