@woosh/meep-engine 2.73.0 → 2.75.0

package/src/engine/graphics/texture/virtual/v2/{TileLoader.js → VirtualTextureTileLoader.js}

@@ -3,24 +3,37 @@ import { arrayQuickSort } from "../../../../../core/collection/array/arrayQuickS
 import Signal from "../../../../../core/events/signal/Signal.js";
 import { AssetManager } from "../../../../asset/AssetManager.js";
 import { GameAssetType } from "../../../../asset/GameAssetType.js";
-import { compose_finger_print } from "./compose_finger_print.js";
-import { decompose_finger_print } from "./finger_print_to_tile_index.js";
-import { TextureTile } from "./TextureTile.js";
-
-export class TileLoader {
+import { compose_finger_print } from "./tile/compose_finger_print.js";
+import { decompose_finger_print } from "./tile/decompose_finger_print.js";
+import { VirtualTextureTile } from "./tile/VirtualTextureTile.js";
+
+/**
+ * Facilitates prioritized queueing and loading of individual texture tiles
+ */
+export class VirtualTextureTileLoader {
     /**
      * Where the tiles are stored
      * @type {string}
      */
     #root_path = "";
 
+    set path(v) {
+        this.#root_path = v;
+    }
+
+    /**
+     * When queue gets larger than this, we start discarding elements
+     * @type {number}
+     */
+    queue_limit = Infinity;
+
     /**
      *
      * @type {AssetManager}
      */
     #asset_manager = null;
 
-    set asset_manager(v){
+    set asset_manager(v) {
         this.#asset_manager = v;
     }
 
@@ -49,7 +62,7 @@ export class TileLoader {
      */
     on = {
         /**
-         * @type {Signal<TextureTile>}
+         * @type {Signal<VirtualTextureTile>}
          */
         loaded: new Signal()
     };
@@ -95,7 +108,6 @@ export class TileLoader {
             return false;
         }
 
-        // TODO limit queue size, if the queue grows too large we may end up with completely irrelevant tiles being loaded minutes after they were actually relevant
         if (this.#queue_add(fingerprint) === false) {
             return false;
         }
@@ -118,7 +130,7 @@ export class TileLoader {
 
     /**
      *
-     * @param {UsageMetadata} usage
+     * @param {VirtualTextureUsage} usage
      */
     #sort_queue_by_usage(usage) {
 
@@ -138,10 +150,16 @@ export class TileLoader {
 
     /**
      *
-     * @param {UsageMetadata} usage
+     * @param {VirtualTextureUsage} usage
      */
     update_usage(usage) {
         this.#sort_queue_by_usage(usage);
+
+        // truncate the queue if necessary
+        const queue_overflow = this.#queue.length - this.queue_limit;
+        if (queue_overflow > 0) {
+            this.#queue.splice(this.queue_limit, queue_overflow);
+        }
     }
 
     /**
@@ -165,7 +183,7 @@ export class TileLoader {
      */
     #prod() {
         while (this.#in_flight.length < this.#concurrency && this.#queue.length > 0) {
-            const fingerprint = this.#queue.pop();
+            const fingerprint = this.#queue[0];
             const { mip, x, y } = decompose_finger_print(fingerprint);
 
             this.#load(mip, x, y);
@@ -177,7 +195,7 @@ export class TileLoader {
      * @param {number} mip
      * @param {number} x
      * @param {number} y
-     * @returns {Promise<TextureTile>}
+     * @returns {Promise<VirtualTextureTile>}
      */
     #load(mip, x, y) {
         const file_name = this.#build_file_name(mip, x, y);
@@ -191,7 +209,7 @@ export class TileLoader {
 
                 const sampler = asset.create();
 
-                const tile = new TextureTile();
+                const tile = new VirtualTextureTile();
 
 
                 tile.data = sampler;
@@ -201,6 +219,8 @@ export class TileLoader {
 
 
                 return tile;
+            }, (reason) => {
+                console.error(`Failed to load tile ${file_name}, reason:${reason}`);
             })
             .finally(() => {
 

package/src/engine/graphics/texture/virtual/v2/{UsageMetadata.js → VirtualTextureUsage.js}

@@ -1,9 +1,21 @@
-import { compose_finger_print } from "./compose_finger_print.js";
-import { finger_print_to_tile_index } from "./finger_print_to_tile_index.js";
+import { arrayQuickSort } from "../../../../../core/collection/array/arrayQuickSort.js";
+import { compose_tile_address } from "./tile/compose_tile_address.js";
+import { finger_print_to_tile_address } from "./tile/finger_print_to_tile_address.js";
 
-export class UsageMetadata {
+
+export class VirtualTextureUsage {
 
     #counts_intrinsic = new Uint32Array(0);
+    /**
+     * Stores indices of tiles with usage > 0
+     * @type {Uint32Array}
+     */
+    #occupancy = new Uint32Array(0);
+    /**
+     * Points at the end of the occupancy list
+     * @type {number}
+     */
+    #occupancy_cursor = 0;
 
     get counts() {
         return this.#counts_intrinsic;
@@ -11,6 +23,7 @@ export class UsageMetadata {
 
     #max_mip_level = 0;
 
+
     set max_mip_level(v) {
         this.#max_mip_level = v;
 
@@ -21,14 +34,21 @@ export class UsageMetadata {
         return this.#max_mip_level;
     }
 
+
+    get occupancy() {
+        return this.#occupancy;
+    }
+
+    get occupancy_count() {
+        return this.#occupancy_cursor;
+    }
+
     /**
      *
      */
     #ensureCapacity() {
 
-        const finger_print = compose_finger_print(this.#max_mip_level + 1, 0, 0);
-
-        const size = finger_print_to_tile_index(finger_print);
+        const size = compose_tile_address(this.#max_mip_level + 1, 0, 0);
 
         if (this.#counts_intrinsic.length >= size) {
             // already large enough
@@ -36,12 +56,7 @@ export class UsageMetadata {
         }
 
         this.#counts_intrinsic = new Uint32Array(size);
-    }
-
-    #getIndexBy(mip, x, y) {
-        const finger_print = compose_finger_print(mip, x, y);
-
-        return finger_print_to_tile_index(finger_print);
+        this.#occupancy = new Uint32Array(size);
     }
 
     /**
@@ -50,8 +65,7 @@ export class UsageMetadata {
      * @returns {number}
      */
     getCountByFingerprint(fingerprint) {
-        const index = finger_print_to_tile_index(fingerprint);
-
+        const index = finger_print_to_tile_address(fingerprint);
 
         return this.#counts_intrinsic[index];
     }
@@ -64,13 +78,14 @@ export class UsageMetadata {
      * @returns {number}
      */
     getCountBy(mip, x, y) {
-        const finger_print = compose_finger_print(mip, x, y);
+        const address = compose_tile_address(mip, x, y);
 
-        return this.getCountByFingerprint(finger_print);
+        return this.#counts_intrinsic[address];
     }
 
     clear() {
         this.#counts_intrinsic.fill(0);
+        this.#occupancy_cursor = 0;
     }
 
     /**
@@ -81,7 +96,7 @@ export class UsageMetadata {
     promoteAncestors(bias = 1) {
 
         // traverse mip pyramid in reverse, so we can push counts to parents one level at a time
-        for (let mip = this.#max_mip_level - 1; mip > 0; mip--) {
+        for (let mip = this.#max_mip_level; mip > 0; mip--) {
 
             const mip_resolution = 1 << mip;
 
@@ -99,7 +114,7 @@ export class UsageMetadata {
                     const parent_x = x >>> 1;
                     const parent_y = y >>> 1;
 
-                    const parent_index = this.#getIndexBy(parent_level, parent_x, parent_y);
+                    const parent_index = compose_tile_address(parent_level, parent_x, parent_y);
 
                     const parent_count = this.#counts_intrinsic[parent_index];
 
@@ -107,6 +122,10 @@ export class UsageMetadata {
 
                     if (parent_count < expected_count) {
                         this.#counts_intrinsic[parent_index] = expected_count;
+
+                        if (parent_count === 0) {
+                            this.#append_to_occupancy(parent_index);
+                        }
                     }
 
                 }
@@ -115,6 +134,26 @@ export class UsageMetadata {
         }
     }
 
+    /**
+     *
+     * @param {number} address
+     */
+    #append_to_occupancy(address) {
+        this.#occupancy[this.#occupancy_cursor] = address;
+        this.#occupancy_cursor++;
+    }
+
+    /**
+     * Sort occupancy list in descending order
+     */
+    sortOccupancy() {
+        arrayQuickSort(
+            this.#occupancy,
+            (index) => -this.#counts_intrinsic[index], null,
+            0, this.#occupancy_cursor - 1
+        );
+    }
+
 
     /**
      *
@@ -125,7 +164,9 @@ export class UsageMetadata {
 
         const data_size = data.length;
 
-        this.#ensureCapacity(data_size >> 2);
+        this.#ensureCapacity();
+
+        const counts = this.#counts_intrinsic;
 
         for (let offset = 0; offset < data_size; offset += 4) {
 
@@ -142,11 +183,16 @@ export class UsageMetadata {
             const tile_x = data[offset + 1] & max_tile_value;
             const tile_y = data[offset + 2] & max_tile_value;
 
-            const finger_print = compose_finger_print(mip_level, tile_x, tile_y);
+            const tile_address = compose_tile_address(mip_level, tile_x, tile_y);
+
+            const previous_count = counts[tile_address];
 
-            const index0 = finger_print_to_tile_index(finger_print);
+            if (previous_count === 0) {
+                // first occurrence, mark occupancy
+                this.#append_to_occupancy(tile_address);
+            }
 
-            this.#counts_intrinsic[index0]++;
+            counts[tile_address] = previous_count + 1;
         }
 
     }

package/src/engine/graphics/texture/virtual/v2/{VirtualTextureManager.js → VirtualTextureUsageUpdater.js}

@@ -1,5 +1,6 @@
 import {
     ClampToEdgeWrapping,
+    DoubleSide,
     GLSL3,
     Matrix4,
     NearestFilter,
@@ -12,12 +13,14 @@ import {
     WebGLRenderTarget
 } from "three";
 import { assert } from "../../../../../core/assert.js";
+import { array_copy } from "../../../../../core/collection/array/array_copy.js";
 import { clamp } from "../../../../../core/math/clamp.js";
 import { max2 } from "../../../../../core/math/max2.js";
+import { generate_halton_jitter } from "../../../generate_halton_jitter.js";
 import { renderScreenSpace } from "../../../render/utils/renderScreenSpace.js";
 import { Sampler2D } from "../../sampler/Sampler2D.js";
-import { fragment, vertex } from "./ShaderUsage.js";
-import { UsageMetadata } from "./UsageMetadata.js";
+import { VirtualTextureUsage } from "./VirtualTextureUsage.js";
+import { fragment, vertex } from "./VirtualTextureUsageShader.js";
 
 const usage_material_uniforms = {
     "u_mt_params": { value: new Vector2(0.1, 1) },
@@ -38,6 +41,7 @@ const usage_material = new RawShaderMaterial({
     uniforms: usage_material_uniforms,
     vertexShader: vertex(),
     fragmentShader: fragment(),
+    side: DoubleSide,
     glslVersion: GLSL3
 
 });
@@ -65,7 +69,24 @@ const clear_usage_material = new RawShaderMaterial({
     glslVersion: GLSL3
 });
 
-export class VirtualTextureManager {
+const scratch_matrix = new Float32Array(16);
+
+export class VirtualTextureUsageUpdater {
+
+    #frame_index = 0;
+
+    /**
+     * In order to avoid aliasing due to the fact that we render at a lower resolution, we move the camera slightly each frame to sweep across texels in-between
+     * @type {Float32Array}
+     */
+    #frame_jitter_offsets = new Float32Array([0, 0]);
+    #frame_jitter_samples = 1;
+    #frame_jitter_enabled = false;
+
+    #initialize_frame_jitter() {
+        this.#frame_jitter_samples = this.#usage_resolution_scale;
+        this.#frame_jitter_offsets = generate_halton_jitter(this.#frame_jitter_samples);
+    }
 
     #usage_buffer = new WebGLRenderTarget(1, 1, {
         wrapT: ClampToEdgeWrapping,
@@ -90,7 +111,7 @@ export class VirtualTextureManager {
      */
     #usage_resolution_scale = 32;
 
-    #usage_metadata = new UsageMetadata();
+    #usage_metadata = new VirtualTextureUsage();
 
     #texture_id = 3;
     #texture_resolution = 65536;
@@ -115,6 +136,7 @@ export class VirtualTextureManager {
      */
     #usage_texture_bias = 0.1;
 
+
     /**
      *
      * @param {number} resolution
@@ -150,6 +172,7 @@ export class VirtualTextureManager {
 
     constructor() {
         this.#initialize_usage_uniforms();
+        this.#initialize_frame_jitter();
     }
 
     #initialize_usage_uniforms() {
@@ -208,6 +231,28 @@ export class VirtualTextureManager {
 
     }
 
+    #prepareUsageUniforms(camera) {
+
+        const uniforms = usage_material.uniforms;
+        const usage_buffer = this.#usage_buffer;
+        const camera_projection_matrix = camera.projectionMatrix.elements;
+
+        if (this.#frame_jitter_enabled) {
+            // apply jitter to projection matrix
+            const jitter_index = this.#frame_index % this.#frame_jitter_samples;
+
+            const jitter_offset_x = this.#frame_jitter_offsets[jitter_index * 2];
+            const jitter_offset_y = this.#frame_jitter_offsets[jitter_index * 2 + 1];
+
+            camera_projection_matrix[8] = jitter_offset_x / usage_buffer.width;
+            camera_projection_matrix[9] = jitter_offset_y / usage_buffer.height;
+        }
+
+
+        uniforms.modelViewMatrix.value.multiplyMatrices(camera.matrixWorldInverse, camera.matrixWorld);
+        uniforms.projectionMatrix.value.copy(camera.projectionMatrix);
+    }
+
     /**
      *
      * @param {WebGLRenderer} renderer
@@ -218,37 +263,49 @@ export class VirtualTextureManager {
 
         const usage_buffer = this.#usage_buffer;
 
-        const uniforms = usage_material.uniforms;
 
-        uniforms.modelViewMatrix.value.multiplyMatrices(camera.matrixWorldInverse, camera.matrixWorld);
-        uniforms.projectionMatrix.value.copy(camera.projectionMatrix);
+        const camera_projection_matrix = camera.projectionMatrix.elements;
 
         // remember existing state
         const _old_render_target = renderer.getRenderTarget();
         const _auto_clear = renderer.autoClear;
-
+        array_copy(camera_projection_matrix, 0, scratch_matrix, 0, 16);
         const _old_material = scene.overrideMaterial;
+        const _old_camera_matrix_update = camera.matrixAutoUpdate;
+
+        camera.matrixAutoUpdate = false;
 
         renderer.autoClear = false;
         renderer.setRenderTarget(usage_buffer);
-        scene.overrideMaterial = usage_material;
 
         // clear out usage texture
         renderScreenSpace(renderer, clear_usage_material);
 
         renderer.clearDepth();
 
+        scene.overrideMaterial = usage_material;
+
+        this.#prepareUsageUniforms(camera);
+
         renderer.render(scene, camera);
 
         scene.overrideMaterial = _old_material;
 
         renderer.readRenderTargetPixels(usage_buffer, 0, 0, usage_buffer.width, usage_buffer.height, this.#usage_pixel_data.data);
 
+        // restore state
         renderer.setRenderTarget(_old_render_target);
         renderer.autoClear = _auto_clear;
+        array_copy(scratch_matrix, 0, camera_projection_matrix, 0, 16);
 
+        camera.matrixAutoUpdate = _old_camera_matrix_update;
+
+        //
         this.#usage_metadata.fromTexture(this.#usage_pixel_data.data);
         this.#usage_metadata.promoteAncestors(1);
+        this.#usage_metadata.sortOccupancy();
+
+        this.#frame_index++;
     }
 
     dispose() {

package/src/engine/graphics/texture/virtual/v2/debug/ResidencyDebugView.js

@@ -0,0 +1,70 @@
+import { CSS_ABSOLUTE_POSITIONING } from "../../../../../../view/CSS_ABSOLUTE_POSITIONING.js";
+import { CanvasView } from "../../../../../../view/elements/CanvasView.js";
+import EmptyView from "../../../../../../view/elements/EmptyView.js";
+import { sampler2d_write_to_canvas_raw } from "../../../sampler/sampler2d_write_to_canvas_raw.js";
+
+export class ResidencyDebugView extends EmptyView {
+    /**
+     *
+     * @type {PageTexture|null}
+     */
+    texture = null;
+
+    #canvas = new CanvasView();
+
+    #previous_residency = new Uint32Array(1024);
+
+    constructor() {
+        super({
+            css: {
+                position: "absolute",
+                boxShadow: "0 0 8px black",
+                background: "black"
+            }
+        });
+
+        this.#canvas.css(CSS_ABSOLUTE_POSITIONING);
+
+        this.addChild(this.#canvas);
+
+        this.#previous_residency.fill(-1);
+    }
+
+    update() {
+
+        const t = this.texture;
+        if (t === null) {
+            return;
+        }
+
+        const canvas = this.#canvas;
+        canvas.size.readFromArray(t.page_texture_resolution);
+
+        this.size.copy(canvas.size);
+
+        const residentTiles = t.resident_tiles;
+
+        const temp = new CanvasView();
+        const tile_resolution = t.tile_resolution;
+        temp.size.setScalar(tile_resolution);
+
+        const tile_columns = t.page_texture_resolution[0] / tile_resolution;
+
+        for (let i = 0; i < residentTiles.length; i++) {
+            const tile = residentTiles[i];
+
+            const page_slot = tile.page_slot;
+            if (this.#previous_residency[page_slot] === tile.finder_print) {
+                continue;
+            }
+
+            sampler2d_write_to_canvas_raw(tile.data, temp.el);
+            const column = page_slot % tile_columns;
+            const row = (page_slot / tile_columns) | 0;
+
+            canvas.context2d.drawImage(temp.el, 0, 0, tile_resolution, tile_resolution, tile_resolution * column, tile_resolution * row, tile_resolution, tile_resolution);
+
+            this.#previous_residency[page_slot] = tile.finder_print;
+        }
+    }
+}

package/src/engine/graphics/texture/virtual/v2/debug/UsageDebugView.js

@@ -0,0 +1,63 @@
+import LabelView from "../../../../../../view/common/LabelView.js";
+import EmptyView from "../../../../../../view/elements/EmptyView.js";
+import { decompose_finger_print } from "../tile/decompose_finger_print.js";
+import { tile_address_to_finger_print } from "../tile/tile_address_to_finger_print.js";
+
+export class UsageDebugView extends EmptyView {
+    #tileCount = new LabelView("")
+    #tiles = new EmptyView();
+    #mip_levels = 0;
+
+
+    constructor(opt) {
+        super(opt);
+
+        this.addChild(this.#tileCount);
+        this.addChild(this.#tiles);
+
+        this.css({
+            position: "absolute",
+            left: "0",
+            top: "0",
+            background: "rgba(255,255,255,0.5)",
+            fontFamily: "monospace",
+            fontSize: "10px"
+        });
+    }
+
+    set mip_levels(v) {
+        this.#mip_levels = v;
+    }
+
+    /**
+     *
+     * @param {VirtualTextureUsage} usage
+     */
+    set usage(usage) {
+
+
+        this.#tiles.removeAllChildren();
+
+        const occupancy = usage.occupancy;
+        const occupancyCount = usage.occupancy_count;
+
+        for (let i = 0; i < occupancyCount; i++) {
+            const occupancy_index = occupancy[i];
+            const fingerPrint = tile_address_to_finger_print(occupancy_index);
+
+            const count = usage.getCountByFingerprint(fingerPrint);
+
+            if (count <= 0) {
+                continue;
+            }
+
+            const { mip, x, y } = decompose_finger_print(fingerPrint);
+
+            this.#tiles.addChild(new LabelView(`ID: ${0} Level: ${mip} X: ${x} Y: ${y} USAGE: ${count}`));
+        }
+
+        this.#tileCount.updateText(`Tile Count: ${occupancyCount}`);
+    }
+
+
+}