@woosh/meep-engine 2.72.0 → 2.74.0

package/src/engine/graphics/ecs/camera/FrustumProjector.js

@@ -6,190 +6,41 @@
 import { Vector3 as ThreeVector3 } from 'three';
 
 
-const projectInWorldSpace = (function () {
-    const corners = [
-        new ThreeVector3(-1, -1, 0),
-        new ThreeVector3(-1, -1, 0),
+const corners = [
+    new ThreeVector3(-1, -1, 0),
+    new ThreeVector3(-1, -1, 0),
 
-        new ThreeVector3(-1, 1, 0),
-        new ThreeVector3(-1, 1, 0),
+    new ThreeVector3(-1, 1, 0),
+    new ThreeVector3(-1, 1, 0),
 
-        new ThreeVector3(1, -1, 0),
-        new ThreeVector3(1, -1, 0),
+    new ThreeVector3(1, -1, 0),
+    new ThreeVector3(1, -1, 0),
 
-        new ThreeVector3(1, 1, 0),
-        new ThreeVector3(1, 1, 0)
-    ];
+    new ThreeVector3(1, 1, 0),
+    new ThreeVector3(1, 1, 0)
+];
 
 
-    /**
-     *
-     * @param {Number} nearZ
-     * @param {Number} farZ
-     * @param {THREE.Camera} camera
-     * @param {THREE.Matrix4} matrixWorldInverse
-     * @param {function} callback
-     */
-    function projectInWorldSpace(nearZ, farZ, camera, callback) {
-        corners[0].set(-1, -1, nearZ);
-        corners[1].set(-1, -1, farZ);
-
-        corners[2].set(-1, 1, nearZ);
-        corners[3].set(-1, 1, farZ);
-
-        corners[4].set(1, -1, nearZ);
-        corners[5].set(1, -1, farZ);
-
-        corners[6].set(1, 1, nearZ);
-        corners[7].set(1, 1, farZ);
-
-        //compute corners of view frustum in light space
-        let x0 = Number.POSITIVE_INFINITY;
-        let y0 = Number.POSITIVE_INFINITY;
-        let z0 = Number.POSITIVE_INFINITY;
-
-        let x1 = Number.NEGATIVE_INFINITY;
-        let y1 = Number.NEGATIVE_INFINITY;
-        let z1 = Number.NEGATIVE_INFINITY;
-
-
-        for (let i = 0; i < 8; i++) {
-            const corner = corners[i];
-            corner.unproject(camera);
-
-            if (corner.x < x0) {
-                x0 = corner.x;
-            }
-            if (corner.x > x1) {
-                x1 = corner.x;
-            }
-
-            if (corner.y < y0) {
-                y0 = corner.y;
-            }
-            if (corner.y > y1) {
-                y1 = corner.y;
-            }
-
-            if (corner.z < z0) {
-                z0 = corner.z;
-            }
-            if (corner.z > z1) {
-                z1 = corner.z;
-            }
-        }
-
-        callback(x0, y0, z0, x1, y1, z1);
-    }
-
-    return projectInWorldSpace;
-})();
-
-const project = (function () {
-    const corners = [
-        new ThreeVector3(-1, -1, 0),
-        new ThreeVector3(-1, -1, 0),
-
-        new ThreeVector3(-1, 1, 0),
-        new ThreeVector3(-1, 1, 0),
-
-        new ThreeVector3(1, -1, 0),
-        new ThreeVector3(1, -1, 0),
-
-        new ThreeVector3(1, 1, 0),
-        new ThreeVector3(1, 1, 0)
-    ];
-
-
-    /**
-     *
-     * @param {Number} nearZ
-     * @param {Number} farZ
-     * @param {THREE.Camera} camera
-     * @param {THREE.Matrix4} matrixWorldInverse
-     * @param {AABB3} result
-     */
-    function project(nearZ, farZ, camera, matrixWorldInverse, result) {
-        corners[0].set(-1, -1, nearZ);
-        corners[1].set(-1, -1, farZ);
-
-        corners[2].set(-1, 1, nearZ);
-        corners[3].set(-1, 1, farZ);
-
-        corners[4].set(1, -1, nearZ);
-        corners[5].set(1, -1, farZ);
-
-        corners[6].set(1, 1, nearZ);
-        corners[7].set(1, 1, farZ);
-
-        //compute corners of view frustum in light space
-        let x0 = Number.POSITIVE_INFINITY;
-        let y0 = Number.POSITIVE_INFINITY;
-        let z0 = Number.POSITIVE_INFINITY;
-
-        let x1 = Number.NEGATIVE_INFINITY;
-        let y1 = Number.NEGATIVE_INFINITY;
-        let z1 = Number.NEGATIVE_INFINITY;
-
-
-        for (let i = 0; i < 8; i++) {
-            const corner = corners[i];
-            corner.unproject(camera);
-            corner.applyMatrix4(matrixWorldInverse);
-
-            if (corner.x < x0) {
-                x0 = corner.x;
-            }
-            if (corner.x > x1) {
-                x1 = corner.x;
-            }
-
-            if (corner.y < y0) {
-                y0 = corner.y;
-            }
-            if (corner.y > y1) {
-                y1 = corner.y;
-            }
-
-            if (corner.z < z0) {
-                z0 = corner.z;
-            }
-            if (corner.z > z1) {
-                z1 = corner.z;
-            }
-        }
-
-        result.setBounds(x0, y0, z0, x1, y1, z1);
-    }
-
-    return project;
-})();
-
 /**
  *
- * @param _x0
- * @param _y0
- * @param _z0
- * @param _x1
- * @param _y1
- * @param _z1
- * @param {Camera} camera
- * @param callback
+ * @param {Number} nearZ
+ * @param {Number} farZ
+ * @param {THREE.Camera} camera
+ * @param {THREE.Matrix4} matrixWorldInverse
+ * @param {AABB3} result
  */
-function unproject(_x0, _y0, _z0, _x1, _y1, _z1, camera, callback) {
-    const corners = [
-        new ThreeVector3(_x0, _y0, _z0),
-        new ThreeVector3(_x0, _y0, _z1),
+function project(nearZ, farZ, camera, matrixWorldInverse, result) {
+    corners[0].set(-1, -1, nearZ);
+    corners[1].set(-1, -1, farZ);
 
-        new ThreeVector3(_x0, _y1, _z0),
-        new ThreeVector3(_x0, _y1, _z1),
+    corners[2].set(-1, 1, nearZ);
+    corners[3].set(-1, 1, farZ);
 
-        new ThreeVector3(_x1, _y0, _z0),
-        new ThreeVector3(_x1, _y0, _z1),
+    corners[4].set(1, -1, nearZ);
+    corners[5].set(1, -1, farZ);
 
-        new ThreeVector3(_x1, _y1, _z0),
-        new ThreeVector3(_x1, _y1, _z1)
-    ];
+    corners[6].set(1, 1, nearZ);
+    corners[7].set(1, 1, farZ);
 
     //compute corners of view frustum in light space
     let x0 = Number.POSITIVE_INFINITY;
@@ -201,8 +52,10 @@ function unproject(_x0, _y0, _z0, _x1, _y1, _z1, camera, callback) {
     let z1 = Number.NEGATIVE_INFINITY;
 
 
-    corners.forEach(function (corner) {
-        corner.project(camera);
+    for (let i = 0; i < 8; i++) {
+        const corner = corners[i];
+        corner.unproject(camera);
+        corner.applyMatrix4(matrixWorldInverse);
 
         if (corner.x < x0) {
             x0 = corner.x;
@@ -224,19 +77,15 @@ function unproject(_x0, _y0, _z0, _x1, _y1, _z1, camera, callback) {
         if (corner.z > z1) {
             z1 = corner.z;
         }
-    });
+    }
 
-    callback(x0, y0, z0, x1, y1, z1);
+    result.setBounds(x0, y0, z0, x1, y1, z1);
 }
 
+
 export default {
     /**
      * @deprecated use non-threejs specific code
      */
     project,
-    unproject,
-    /**
-     * @deprecated use non-threejs specific code
-     */
-    projectInWorldSpace
 };

package/src/engine/graphics/generate_halton_jitter.js

@@ -0,0 +1,21 @@
+import { assert } from "../../core/assert.js";
+import { halton_sequence } from "../../core/math/statistics/halton_sequence.js";
+
+/**
+ * Generates a number of 2d jitter offsets in range -1...1
+ * @param {number} point_count
+ * @return {Float32Array}
+ */
+export function generate_halton_jitter(point_count) {
+    assert.isNonNegativeInteger(point_count, 'point_count');
+
+    const result = new Float32Array(point_count * 2);
+
+    for (let i = 0; i < point_count; i++) {
+        const i2 = i * 2;
+        result[i2] = halton_sequence(2, i) * 2 - 1;
+        result[i2 + 1] = halton_sequence(3, i) * 2 - 1;
+    }
+
+    return result;
+}

package/src/engine/graphics/render/buffer/simple-fx/taa/TemporalSupersamplingRenderPlugin.js

@@ -1,23 +1,6 @@
-import { EnginePlugin } from "../../../../../plugin/EnginePlugin.js";
-import { halton_sequence } from "../../../../../../core/math/statistics/halton_sequence.js";
 import { array_copy } from "../../../../../../core/collection/array/array_copy.js";
-
-/**
- * Generates a number of 2d jitter offsets in range -1...1
- * @param {number} point_count
- * @return {Float32Array}
- */
-function generate_jitter(point_count) {
-    const result = new Float32Array(point_count * 2);
-
-    for (let i = 0; i < point_count; i++) {
-        const i2 = i * 2;
-        result[i2] = halton_sequence(2, i) * 2 - 1;
-        result[i2 + 1] = halton_sequence(3, i) * 2 - 1;
-    }
-
-    return result;
-}
+import { EnginePlugin } from "../../../../../plugin/EnginePlugin.js";
+import { generate_halton_jitter } from "../../../../generate_halton_jitter.js";
 
 export class TemporalSupersamplingRenderPlugin extends EnginePlugin {
     constructor() {
@@ -31,7 +14,7 @@ export class TemporalSupersamplingRenderPlugin extends EnginePlugin {
         this.__frame_index = 0;
 
         this.__sample_count = 16;
-        this.__jitter_offset = generate_jitter(this.__sample_count);
+        this.__jitter_offset = generate_halton_jitter(this.__sample_count);
 
 
         this.__projection_modifier = {

package/src/engine/graphics/texture/virtual/v2/NOTES.md

@@ -14,4 +14,14 @@ The original texture is mip-mapped, down to the size of a single tile, for the s
 
 This is achieved by pre-rendering the scene with a special shader that records UV and mip-level information, which we call `Usage`, this is then analysed to build a list of used tiles (mip level, x, y) and by counting occurrence of this tile in the `Usage` texture we get a much more useful data structure.
 
-Based on the `Usage` data, we populate our `Physical` texture of pages, and based on what's currently in the `Physical` texture - we populate the `Reference` texture that stores information about the entire mip pyramid, and for each tile contains a pointer to the `Physical` texture, where representative tile can be found. 
+Based on the `Usage` data, we populate our `Physical` texture of pages, and based on what's currently in the `Physical` texture - we populate the `Reference` texture that stores information about the entire mip pyramid, and for each tile contains a pointer to the `Physical` texture, where representative tile can be found. 
+
+
+## Considerations
+
+
+### Filtering
+
+Most papers suggest introducing a border into each tile of ~4 pixels. 
+4 pixel border on a 128x128 pixel tile is going to take up 12.1% of space, which is quite a lot.
+We can do filtering in software, that is - sample individual pixels and perform interpolation inside the shader.

package/src/engine/graphics/texture/virtual/v2/ShaderUsage.js

@@ -34,13 +34,15 @@ function fragment() {
     
     float MTCalculateMipLevel( const in vec2 uv, const in float bias ) {
         
-        float scale_x = float(u_mt_tex.x) / u_mt_viewport_size.x;
-        float scale_y = float(u_mt_tex.y) / u_mt_viewport_size.y;
+        float scale_x = float(u_mt_tex.x) ;
+        float scale_y = float(u_mt_tex.y) ;
         
-        vec2 dx = dFdx( uv * scale_x);
-        vec2 dy = dFdy( uv * scale_y);
+        vec2 dx = dFdx( uv * scale_x)/ u_mt_viewport_size.x;
+        vec2 dy = dFdy( uv * scale_y)/ u_mt_viewport_size.y;
         
-        return log2( max( dot( dx, dx ), dot( dy, dy ) ) ) * 0.5 + bias;
+        float d = max( dot( dx, dx ), dot( dy, dy ) );
+        
+        return log2( d ) * 0.5 + bias;
     }
     
     uvec4 MTCalculateTileKeyRGBA( const in vec2 uv ) {

package/src/engine/graphics/texture/virtual/v2/SparseTexture.js

@@ -0,0 +1,291 @@
+import { WebGLRenderTarget } from "three";
+import { BitSet } from "../../../../../core/binary/BitSet.js";
+import { Cache } from "../../../../../core/cache/Cache.js";
+import { array_copy } from "../../../../../core/collection/array/array_copy.js";
+import { passThrough, strictEquals } from "../../../../../core/function/Functions.js";
+import { max2 } from "../../../../../core/math/max2.js";
+import { min2 } from "../../../../../core/math/min2.js";
+import { tile_address_to_finger_print } from "./tile/tile_address_to_finger_print.js";
+import { TileLoader } from "./TileLoader.js";
+
+/**
+ * How much extra data to store in cache (in bytes)
+ * @type {number}
+ */
+const DEFAULT_CACHE_SIZE = 16 * 1024 * 1024;
+
+export class SparseTexture {
+    #page_texture = new WebGLRenderTarget(1, 1);
+
+    #page_texture_size = [1, 1];
+
+    #version = 0;
+
+    /**
+     * Maximum number of new page assignments per single update cycle
+     * This helps prevent thrashing and keep performance overhead of updating pages predictable
+     * @type {number}
+     */
+    #cycle_assignment_limit = 2;
+
+
+    get page_texture_resolution() {
+        return this.#page_texture_size;
+    }
+
+    /**
+     *
+     * @type {TextureTile[]}
+     */
+    #resident_tiles = [];
+
+    get resident_tiles() {
+        return this.#resident_tiles;
+    }
+
+    #page_slot_occupancy = new BitSet();
+
+    #tile_resolution = 128;
+
+    get tile_resolution() {
+        return this.#tile_resolution;
+    }
+
+    #residency_tile_capacity = 0;
+
+    /**
+     * Must be >=0
+     * When 0 - tiles that would not fit onto the page will not be loaded
+     * When >0 - same fraction of extra tiles will be fetching and put into cache, resulting in prefetching
+     * @type {number}
+     */
+    #prefetch_factor = 0.33;
+
+    #loader = new TileLoader();
+
+    /**
+     *
+     * @type {AssetManager|null}
+     */
+    #asset_manager = null;
+
+    constructor() {
+        this.#loader.on.loaded.add(this.#handle_tile_loaded, this);
+    }
+
+    /**
+     *
+     * @param {TextureTile} tile
+     */
+    #handle_tile_loaded(tile) {
+        const finderPrint = tile.finder_print;
+
+        if (this.#tile_cache.has(finderPrint)) {
+            // already loaded
+            return;
+        }
+
+        this.#tile_cache.put(finderPrint, tile);
+
+    }
+
+    /**
+     *
+     * @param {string} v
+     */
+    set path(v) {
+        this.#loader.path = v;
+    }
+
+    set asset_manager(v) {
+        this.#asset_manager = v
+
+        this.#loader.asset_manager = v;
+    }
+
+    #update_residency_capacity() {
+        const tile_resolution = this.#tile_resolution;
+        const size = this.#page_texture_size;
+
+        const x = size[0] / tile_resolution;
+        const y = size[1] / tile_resolution;
+
+        this.#residency_tile_capacity = x * y;
+
+        this.#loader.queue_limit = max2(16, this.#residency_tile_capacity);
+    }
+
+
+    /**
+     *
+     * @param {number} v
+     */
+    set tile_resolution(v) {
+        this.#tile_resolution = v;
+
+        this.#update_residency_capacity();
+    }
+
+    /**
+     * Tiles that are not currently resident live here
+     * key is the tile's "fingerprint"
+     * @type {Cache<number,TextureTile>}
+     */
+    #tile_cache = new Cache({
+        keyHashFunction: passThrough,
+        keyEqualityFunction: strictEquals,
+        maxWeight: DEFAULT_CACHE_SIZE,
+        valueWeigher: () => this.#tile_resolution * this.#tile_resolution * 4
+    });
+
+    #find_eviction_target_index() {
+        // find least-recently used
+        const tiles = this.#resident_tiles;
+        const count = tiles.length;
+
+        let min = Infinity;
+        let min_index = -1;
+
+        for (let i = 0; i < count; i++) {
+            const tile = tiles[i];
+
+            if (tile.last_used_time < min) {
+                min = tile.last_used_time;
+                min_index = i;
+            }
+        }
+
+        return min_index;
+    }
+
+    #evict_one() {
+        const index = this.#find_eviction_target_index();
+
+        if (index === -1) {
+            return false;
+        }
+
+        return this.#remove_resident_tile(index);
+    }
+
+    /**
+     *
+     * @param {number} index
+     * @returns {boolean}
+     */
+    #remove_resident_tile(index) {
+        const [removed] = this.#resident_tiles.splice(index, 1);
+
+        const pageSlot = removed.page_slot;
+
+        // mark slot as empty for next tile
+        this.#page_slot_occupancy.clear(pageSlot);
+
+        removed.page_slot = -1;
+
+        // push into cache
+        this.#tile_cache.put(removed.finder_print, removed);
+
+        return true;
+    }
+
+    /**
+     *
+     * @param {TextureTile} tile
+     */
+    #make_resident(tile) {
+
+        if (this.#residency_tile_capacity === 0) {
+            throw new Error('Capacity is 0');
+        }
+
+        let slot = this.#page_slot_occupancy.nextClearBit(0);
+
+        while (slot >= this.#residency_tile_capacity) {
+            this.#evict_one();
+
+            slot = this.#page_slot_occupancy.nextClearBit(0);
+        }
+
+        tile.page_slot = slot;
+
+        this.#page_slot_occupancy.set(slot, true);
+        this.#resident_tiles.push(tile);
+
+        return true;
+    }
+
+    /**
+     *
+     * @param {number[]} v
+     */
+    set page_texture_size(v) {
+        array_copy(
+            v, 0,
+            this.#page_texture_size, 0,
+            2
+        );
+
+        this.#page_texture.dispose();
+        this.#page_texture.setSize(this.#page_texture_size[0], this.#page_texture_size[1]);
+
+        this.#update_residency_capacity();
+    }
+
+    /**
+     *
+     * @param {UsageMetadata} usage
+     */
+    update_usage(usage) {
+        const usage_occupancy = usage.occupancy;
+        const usage_occupancy_count = usage.occupancy_count;
+
+
+        // Usage occupancy is already sorted by priority, so there's no point is trying to fetch more than t
+        let fetch_limit = this.#residency_tile_capacity * (1 + this.#prefetch_factor);
+
+        let writes_remaining = min2(
+            max2(1, this.#cycle_assignment_limit),
+            this.#residency_tile_capacity
+        );
+
+        let remaining_slots = this.#residency_tile_capacity;
+
+        for (let i = 0; i < usage_occupancy_count && fetch_limit > 0; i++) {
+            const tile_address = usage_occupancy[i];
+
+            const fingerPrint = tile_address_to_finger_print(tile_address);
+
+            const tile = this.#tile_cache.get(fingerPrint);
+            if (tile === null) {
+                this.#loader.enqueue(fingerPrint);
+            } else if (remaining_slots > 0) {
+                // found in cache, and we have some slots remaining to write into
+
+
+                // touch to prevent eviction
+                tile.last_used_time = this.#version;
+
+                if (tile.page_slot === -1 && writes_remaining > 0) {
+                    // tile is not active, and we can write it
+                    writes_remaining--;
+                    this.#make_resident(tile);
+                }
+
+                fetch_limit--;
+                remaining_slots--;
+            }
+        }
+
+
+        this.#loader.update_usage(usage);
+
+        this.#version++;
+    }
+
+    dispose() {
+        this.#page_texture.dispose();
+        this.#tile_cache.clear();
+        this.#page_slot_occupancy.reset();
+    }
+}