@woosh/meep-engine 2.71.0 → 2.73.0

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

@@ -0,0 +1,27 @@
+# Sparse Virtual Texture 
+
+This tech is based on popular Megatexture technique developed for Rage by John Carmack, working at id software.
+
+The key idea boils down to having a very large texture that is impractical to keep in memory, and only load and keep in memory pieces of it that are relevant to the current view.
+
+There are 2 parts to this technique, offline and online.
+
+## Offline
+
+The original texture is mip-mapped, down to the size of a single tile, for the sake of this document let it be 128x128 pixels. Each mip level is then cut into tiles and stored on disk. A good intuition for this is to think of each tile as a separate pixel, representing non-color data.
+
+## Online
+
+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. 
+
+
+## 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

@@ -1,6 +1,15 @@
 function vertex() {
     return `
-    varying vec2 vUv;
+    precision mediump float;
+    precision mediump int;
+    
+    uniform mat4 modelViewMatrix;
+    uniform mat4 projectionMatrix;
+    
+    in vec2 uv;
+    in vec3 position;
+    
+    out vec2 vUv;
     void main()
     {
         vUv = uv;
@@ -13,32 +22,48 @@ function vertex() {
 
 function fragment() {
     return `
-uniform vec4 u_mt_tex; // [ width, height, tileSize, id ]
-uniform vec2 u_mt_params; // [ bias, maxLevel, xx, xx ]
-varying vec2 vUv;
-
-float MTCalculateMipLevel( const in vec2 uv, const in float bias ) {
-    vec2 dx = dFdx( uv * u_mt_tex.x );
-    vec2 dy = dFdy( uv * u_mt_tex.y );
-    return log2( max( dot( dx, dx ), dot( dy, dy ) ) ) / 2.0 + bias;
-}
-
-vec4 MTCalculateTileKeyRGBA( const in vec2 uv ) {
-   float level = clamp( floor( MTCalculateMipLevel( uv, u_mt_params.x ) ), 0.0, u_mt_params.y );
-   vec2 texIS = uv.xy * u_mt_tex.xy;                     // [0-1]x[0-1] -> [0-texwidth]x[0-texheight]
-   vec2 texLS = texIS / exp2( level );                   // -> [0-levelwidth]x[0-levelheight]
-   vec2 texTS = floor( texLS / u_mt_tex.z );             // -> [0->tileswide]x[0-tileshigh]
-   return vec4( u_mt_params.y - level, texTS.xy, u_mt_tex.w ) / 255.0; // [  level, tileX, tileY, texId ] -> RGBA
-}
-
+    precision highp float;
+    precision highp int;
     
-void main(){
-    vec4 tile =  MTCalculateTileKeyRGBA(vUv);
-    // gl_FragColor = tile;
-    gl_FragColor = vec4(mix(0.1,1.0,tile.x*255.0/u_mt_params.y), tile.yz*64.0, 1.0);
-    // gl_FragColor = MTCalculateTileKeyRGBA(vUv);
-    // gl_FragColor = vec4(1.0);
-}
+    uniform uvec4 u_mt_tex; // [ width, height, tileSize, id ]
+    uniform vec2 u_mt_params; // [ bias, maxLevel ]
+    uniform vec2 u_mt_viewport_size;
+    in vec2 vUv;
+    
+    out uvec4 out_decoded;
+    
+    float MTCalculateMipLevel( const in vec2 uv, const in float bias ) {
+        
+        float scale_x = float(u_mt_tex.x) ;
+        float scale_y = float(u_mt_tex.y) ;
+        
+        vec2 dx = dFdx( uv * scale_x)/ u_mt_viewport_size.x;
+        vec2 dy = dFdy( uv * scale_y)/ u_mt_viewport_size.y;
+        
+        float d = max( dot( dx, dx ), dot( dy, dy ) );
+        
+        return log2( d ) * 0.5 + bias;
+    }
+    
+    uvec4 MTCalculateTileKeyRGBA( const in vec2 uv ) {
+       uint level = clamp(  uint( floor( MTCalculateMipLevel( uv, u_mt_params.x ) ) ), 0u, uint(u_mt_params.y) );
+       
+       uint mip_resolution_in_tiles = 1u << level;
+       
+       uint mip_resolution_in_texels = mip_resolution_in_tiles * u_mt_tex.z;
+              
+       vec2 texel_position = fract(uv.xy) * vec2(u_mt_tex.xy);
+            
+       uvec2 tile_position = uvec2( texel_position / float(mip_resolution_in_texels)  );
+           
+       // [ level, tileX, tileY, texId ] -> RGBA
+       return uvec4( uint(u_mt_params.y) - level, tile_position, u_mt_tex.w );
+    }
+    
+        
+    void main(){
+        out_decoded =  MTCalculateTileKeyRGBA(vUv);
+    }
 `;
 }
 

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

@@ -0,0 +1,182 @@
+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 { compose_finger_print } from "./compose_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];
+
+    /**
+     *
+     * @type {TextureTile[]}
+     */
+    #resident_tiles = [];
+
+    #page_slot_occupancy = new BitSet();
+
+    #tile_resolution = 128;
+
+    #residency_tile_capacity = 0;
+
+    #loader = new TileLoader();
+
+    /**
+     *
+     * @type {AssetManager|null}
+     */
+    #asset_manager = null;
+
+    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;
+    }
+
+
+    /**
+     *
+     * @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 max = -1;
+        let max_index = -1;
+
+        for (let i = 0; i < count; i++) {
+            const tile = tiles[i];
+
+            if (tile.last_used_time > max) {
+                max = tile.last_used_time;
+                max_index = i;
+            }
+        }
+
+        return max_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);
+
+        // push into cache
+        this.#tile_cache.put(removed.finder_print, removed);
+
+        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[0], this.#page_texture[1]);
+
+        this.#update_residency_capacity();
+    }
+
+    /**
+     *
+     * @param {UsageMetadata} usage
+     */
+    update_usage(usage) {
+        const max_mip = usage.max_mip_level;
+
+        for (let mip = 0; mip < max_mip; mip++) {
+
+            const resolution = 1 << mip;
+
+            for (let y = 0; y < resolution; y++) {
+                for (let x = 0; x < resolution; x++) {
+
+                    const count = usage.getCountBy(mip, x, y);
+
+                    if (count === 0) {
+                        continue;
+                    }
+
+                    const fingerprint = compose_finger_print(mip, x, y);
+
+                    this.#loader.enqueue(fingerprint);
+
+                }
+            }
+
+        }
+
+        this.#loader.update_usage(usage);
+    }
+
+    dispose() {
+        this.#page_texture.dispose();
+        this.#tile_cache.clear();
+        this.#page_slot_occupancy.reset();
+    }
+}

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

@@ -0,0 +1,31 @@
+export class TextureTile {
+
+    finder_print = 0;
+
+    last_used_time = 0;
+
+    /**
+     * Currently occupied page slot, only valid when page is resident
+     * @type {number}
+     */
+    page_slot = 0;
+
+    /**
+     *
+     * @type {Sampler2D|null}
+     */
+    data = null;
+
+    /**
+     *
+     * @param {TextureTile} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        return false;
+    }
+
+    hash() {
+        return 0;
+    }
+}

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

@@ -0,0 +1,215 @@
+import { assert } from "../../../../../core/assert.js";
+import { arrayQuickSort } from "../../../../../core/collection/array/arrayQuickSort.js";
+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 {
+    /**
+     * Where the tiles are stored
+     * @type {string}
+     */
+    #root_path = "";
+
+    /**
+     *
+     * @type {AssetManager}
+     */
+    #asset_manager = null;
+
+    set asset_manager(v){
+        this.#asset_manager = v;
+    }
+
+    /**
+     * How many tiles can be loaded at the same time
+     * @type {number}
+     */
+    #concurrency = 4;
+
+    /**
+     * Tiles that are currently being loaded
+     * @readonly
+     * @type {number[]}
+     */
+    #in_flight = [];
+
+    /**
+     * Contains fingerprints
+     * @readonly
+     * @type {number[]}
+     */
+    #queue = [];
+
+    /**
+     * @readonly
+     */
+    on = {
+        /**
+         * @type {Signal<TextureTile>}
+         */
+        loaded: new Signal()
+    };
+
+
+    /**
+     *
+     * @param {number} fingerprint
+     * @returns {boolean}
+     */
+    #queue_remove(fingerprint) {
+        assert.isNonNegativeInteger(fingerprint, 'fingerprint');
+
+        const i = this.#queue.indexOf(fingerprint);
+
+        if (i === -1) {
+            return false;
+        }
+
+        this.#queue.splice(i, 1);
+
+        return true;
+    }
+
+    #queue_add(fingerprint) {
+        assert.isNonNegativeInteger(fingerprint, 'fingerprint');
+
+        if (this.is_queued(fingerprint)) {
+            return false;
+        }
+
+        this.#queue.push(fingerprint);
+
+        return true;
+    }
+
+    /**
+     *
+     * @param {number} fingerprint
+     */
+    enqueue(fingerprint) {
+        if (this.#in_flight.indexOf(fingerprint) !== -1) {
+            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;
+        }
+
+        this.#prod();
+
+        return true;
+    }
+
+    /**
+     *
+     * @param {number} fingerprint
+     * @returns {boolean}
+     */
+    is_queued(fingerprint) {
+        assert.isNonNegativeInteger(fingerprint, 'fingerprint');
+
+        return this.#queue.indexOf(fingerprint) !== -1;
+    }
+
+    /**
+     *
+     * @param {UsageMetadata} usage
+     */
+    #sort_queue_by_usage(usage) {
+
+        /**
+         *
+         * @param {number} fingerprint
+         */
+        const score = (fingerprint) => -usage.getCountByFingerprint(fingerprint);
+
+        arrayQuickSort(
+            this.#queue,
+            score, null,
+            0, this.#queue.length - 1
+        );
+
+    }
+
+    /**
+     *
+     * @param {UsageMetadata} usage
+     */
+    update_usage(usage) {
+        this.#sort_queue_by_usage(usage);
+    }
+
+    /**
+     *
+     * @param {number} mip
+     * @param {number} x
+     * @param {number} y
+     * @returns {string}
+     */
+    #build_file_name(mip, x, y) {
+
+        assert.isNonNegativeInteger(mip, 'mip');
+        assert.isNonNegativeInteger(x, 'x');
+        assert.isNonNegativeInteger(y, 'y');
+
+        return `${mip}-${x}-${y}.png`;
+    }
+
+    /**
+     * Initializes load of the next element in the queue if there is capacity
+     */
+    #prod() {
+        while (this.#in_flight.length < this.#concurrency && this.#queue.length > 0) {
+            const fingerprint = this.#queue.pop();
+            const { mip, x, y } = decompose_finger_print(fingerprint);
+
+            this.#load(mip, x, y);
+        }
+    }
+
+    /**
+     *
+     * @param {number} mip
+     * @param {number} x
+     * @param {number} y
+     * @returns {Promise<TextureTile>}
+     */
+    #load(mip, x, y) {
+        const file_name = this.#build_file_name(mip, x, y);
+        const finger_print = compose_finger_print(mip, x, y);
+
+        this.#queue_remove(finger_print);
+        this.#in_flight.push(finger_print);
+
+        return this.#asset_manager.promise(`${this.#root_path}/${file_name}`, GameAssetType.Image)
+            .then(asset => {
+
+                const sampler = asset.create();
+
+                const tile = new TextureTile();
+
+
+                tile.data = sampler;
+                tile.finder_print = finger_print;
+
+                this.on.loaded.send1(tile);
+
+
+                return tile;
+            })
+            .finally(() => {
+
+                const index = this.#in_flight.indexOf(finger_print);
+                this.#in_flight.splice(index, 1);
+
+                this.#prod();
+
+            })
+
+    }
+}

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

@@ -0,0 +1,64 @@
+import LabelView from "../../../../../view/common/LabelView.js";
+import EmptyView from "../../../../../view/elements/EmptyView.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 {UsageMetadata} usage
+     */
+    set usage(usage) {
+
+
+        this.#tiles.removeAllChildren();
+
+        let tileCount = 0;
+
+        for (let mip = 0; mip < this.#mip_levels; mip++) {
+            const resolution = 1 << mip;
+
+            for (let y = 0; y < resolution; y++) {
+                for (let x = 0; x < resolution; x++) {
+
+                    const count = usage.getCountBy(mip, x, y);
+
+                    if (count <= 0) {
+                        continue;
+                    }
+
+                    this.#tiles.addChild(new LabelView(`ID: ${0} Level: ${mip} X: ${x} Y: ${y} USAGE: ${count}`));
+
+                    tileCount++;
+                }
+            }
+        }
+
+        this.#tileCount.updateText(`Tile Count: ${tileCount}`);
+    }
+
+
+}