@woosh/meep-engine 2.75.2 → 2.75.4

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

@@ -24,4 +24,96 @@ Based on the `Usage` data, we populate our `Physical` texture of pages, and base
 
 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.
+We can do filtering in software, that is - sample individual pixels and perform interpolation inside the shader.
+
+### Speeding up WebGL read-back
+
+From [Babylon](https://github.com/BabylonJS/Babylon.js/blob/90dbafed8de9de752cdc399604f9c7c51116d630/src/Engines/engine.ts#L1772)
+```ts
+public _readPixelsAsync(x: number, y: number, w: number, h: number, format: number, type: number, outputBuffer: ArrayBufferView) {
+    if (this._webGLVersion < 2) {
+        throw new Error("_readPixelsAsync only work on WebGL2+");
+    }
+
+    let gl = <WebGL2RenderingContext>(this._gl as any);
+    const buf = gl.createBuffer();
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, buf);
+    gl.bufferData(gl.PIXEL_PACK_BUFFER, outputBuffer.byteLength, gl.STREAM_READ);
+    gl.readPixels(x, y, w, h, format, type, 0);
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+
+    const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
+    if (!sync) {
+        return null;
+    }
+
+    gl.flush();
+
+    return this._clientWaitAsync(sync, 0, 10).then(() => {
+        gl.deleteSync(sync);
+
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, buf);
+        gl.getBufferSubData(gl.PIXEL_PACK_BUFFER, 0, outputBuffer);
+        gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+        gl.deleteBuffer(buf);
+
+        return outputBuffer;
+    });
+}
+    
+private _clientWaitAsync(sync: WebGLSync, flags = 0, intervalms = 10): Promise<void> {
+    const gl = <WebGL2RenderingContext>(this._gl as any);
+    return new Promise((resolve, reject) => {
+        const check = () => {
+            const res = gl.clientWaitSync(sync, flags, 0);
+            if (res == gl.WAIT_FAILED) {
+                reject();
+                return;
+            }
+            if (res == gl.TIMEOUT_EXPIRED) {
+                setTimeout(check, intervalms);
+                return;
+            }
+            resolve();
+        };
+
+        check();
+    });
+}
+```
+
+more links:
+https://forum.babylonjs.com/t/speeding-up-readpixels/12739
+
+
+## References
+
+* https://studiopixl.com/2022-04-27/sparse-virtual-textures
+* Anisotropic filtering in a shader: https://www.shadertoy.com/view/4lXfzn
+
+## WebGL fails
+
+WebGL doesn't seem to support mipmaps on integer textures
+
+## Anisotropic filtering:
+
+```glsl
+// R is viewport resolution
+// p is UV
+vec4 textureAniso(sampler2D T, vec2 R, vec2 p) {
+    mat2 J = inverse(mat2(dFdx(p),dFdy(p)));       // dFdxy: pixel footprint in texture space
+    J = transpose(J)*J;                            // quadratic form
+    float d = determinant(J), t = J[0][0]+J[1][1], // find ellipse: eigenvalues, max eigenvector
+          D = sqrt(abs(t*t-4.*d)),                 // abs() fix a bug: in weird view angles 0 can be slightly negative
+          V = (t-D)/2., v = (t+D)/2.,                     // eigenvalues. ( ATTENTION: not sorted )
+          M = 1./sqrt(V), m = 1./sqrt(v), l =log2(m*R.y); // = 1./radii^2
+          
+    //if (M/m>16.) l = log2(M/16.*R.y);                     // optional
+    
+    vec2 A = M * normalize(vec2( -J[0][1] , J[0][0]-V )); // max eigenvector = main axis
+    vec4 O = vec4(0);
+    for (float i = -7.5; i<8.; i++)                       // sample x16 along main axis at LOD min-radius
+        O += textureLod(T, p+(i/16.)*A, l);
+    return O/16.;
+}
+```

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

@@ -0,0 +1,193 @@
+import { DoubleSide, ShaderMaterial, Vector2 } from "three";
+
+export class VirtualTextureMaterial extends ShaderMaterial {
+    /**
+     *
+     * @param {VirtualTexturePage} page
+     * @param {VirtualTextureMemoryMapping} mapping
+     */
+    constructor({
+                    page,
+                    mapping
+                }) {
+        super({
+            side: DoubleSide,
+            uniforms: {
+                u_page: { value: page.texture },
+                u_page_resolution: {
+                    value: new Vector2(
+                        page.page_texture_resolution_in_tiles[0],
+                        page.page_texture_resolution_in_tiles[1]
+                    )
+                },
+                u_tile_resolution: { value: page.tile_resolution },
+                u_tile_padding: { value: page.tile_margin },
+                u_mapping: { value: mapping.texture },
+                u_texture_resolution: { value: mapping.resolution * page.tile_resolution },
+                u_max_mip_level: { value: mapping.max_mip_level },
+                u_mapping_texture_width: { value: mapping.texture.image.width }
+            },
+            vertexShader: `
+        
+    // uniform mat4 modelViewMatrix;
+    // uniform mat4 projectionMatrix;
+    
+    // in vec2 uv;
+    // in vec3 position;
+    out vec2 vUv;
+    
+    void main()
+    {
+        vUv = uv;
+        
+        vec4 mvPosition = modelViewMatrix * vec4( position, 1.0 );
+        gl_Position = projectionMatrix * mvPosition;
+    }
+            `,
+            fragmentShader: `
+            
+    precision highp usampler2D;
+
+    uniform sampler2D u_page;
+    uniform uvec2 u_page_resolution;
+    uniform usampler2D u_mapping;
+    
+    uniform uint u_tile_resolution;
+    uniform uint u_tile_padding;
+    
+    uniform uint u_texture_resolution;
+    uniform uint u_max_mip_level;
+    uniform uint u_mapping_texture_width;
+    
+    in vec2 vUv;
+    
+    float computeTextureLod(const in vec2 uv){
+        float scale_x = float(u_texture_resolution) ;
+        float scale_y = float(u_texture_resolution) ;
+        
+        vec2 dx = dFdx( uv * scale_x ) ;
+        vec2 dy = dFdy( uv * scale_y ) ;
+        
+        float d = max( dot( dx, dx ), dot( dy, dy ) );
+        
+        return log2( d ) * 0.5;
+    }
+    
+    uint split_by_2(const in uint a) {
+        uint x = a;
+        x = (x | x << 16) & 0x0000FFFFu;
+        x = (x | x << 8) & 0x00FF00FFu;
+        x = (x | x << 4) & 0x0F0F0F0Fu;
+        x = (x | x << 2) & 0x33333333u;
+        x = (x | x << 1) & 0x55555555u;
+        return x;
+    }
+    
+    uint compose_tile_address(uint mip, uint x, uint y){
+        uint mip_resolution = 1u << mip;
+         
+        uint mip_mask = mip_resolution - 1u;
+        uint index_offset = split_by_2(mip_mask);
+
+        return index_offset + x + y * mip_resolution;
+    }
+    
+    uvec2 PageTilePosition(
+        const in uint tile_lod,
+        const in uvec2 tile_coordinate, 
+        out float f_mip_size
+    ){
+    
+        uint tile_address = compose_tile_address(tile_lod, tile_coordinate.x , tile_coordinate.y);
+        
+        uint tile_mapping_x = tile_address % u_mapping_texture_width;
+        uint tile_mapping_y = tile_address / u_mapping_texture_width;
+    
+        uint encoded_mapping = texelFetch(u_mapping, ivec2(tile_mapping_x, tile_mapping_y), 0 ).r;
+        
+        // decode mapping
+        uint slot_index = encoded_mapping & 0x3FFFFFu;
+        uint mip_level = ( encoded_mapping >> 22) & 0x3FFu;
+        
+        uint mip_size = 1u << mip_level; 
+        
+        f_mip_size = float(mip_size);
+                        
+        return uvec2(
+            slot_index % u_page_resolution.x,
+            slot_index / u_page_resolution.x
+        );
+    }
+    
+    vec2 PageTileSoft(in vec2 uv , in uvec2 virtual_tile_position, uint tile_lod){
+    
+        float f_mip_size;
+        
+        uvec2 tp00 = PageTilePosition( tile_lod, virtual_tile_position,  f_mip_size) ;
+        
+        vec2 tile_uv = fract(uv * f_mip_size);
+        
+        return vec2(tp00) + tile_uv;
+    }
+    
+    vec4 VirtualFetchLod(const in vec2 uv,const in uint texture_lod_0){
+        uint ui_texture_lod_0 = u_max_mip_level - texture_lod_0;
+        uint tile_mip_size = 1u << ui_texture_lod_0;
+                
+        vec2 uvt = vec2(uv * float(tile_mip_size));
+                                
+        vec2 stuv = PageTileSoft(uv, uvec2(floor(uvt.x), floor(uvt.y)), ui_texture_lod_0);
+        
+        vec2 tile_uv = fract(stuv);
+        vec2 tile_offset = stuv - tile_uv;
+        
+        float f_tile_resolution = float(u_tile_resolution);
+        float slot_size = float(u_tile_resolution + u_tile_padding*2u);
+        
+        ivec2 texture_size = textureSize(u_page,0);        
+        
+        vec2 texel = tile_offset * slot_size + float(u_tile_padding)  + tile_uv*(f_tile_resolution) ;
+        // vec2 texel = tile_offset * slot_size + float(u_tile_padding)  + tile_uv*(f_tile_resolution) - 0.5;
+       
+        vec2 page_uv =  texel / vec2(texture_size);
+        
+        return textureLod(u_page, page_uv, 0.0);
+    }    
+    
+    vec4 VirtualFetch(const in vec2 uv){
+    
+        float texture_lod = computeTextureLod(uv);
+        
+        float lod_fract = fract(texture_lod);
+        
+        // return vec4(lod_fract, 1.0, 1.0, 1.0);
+        
+        float texture_lod_0 = float(texture_lod);
+        float texture_lod_1 = ceil(texture_lod);
+        
+       
+        vec4 lod_0 =  VirtualFetchLod(uv, uint(texture_lod_0));
+        vec4 lod_1 =  VirtualFetchLod(uv, uint(texture_lod_1));
+        
+        vec4 mip_blend = mix(
+            lod_0, lod_1, lod_fract
+        );
+        
+        return mip_blend;
+        
+        // return vec4(lod_fract, mip_blend.y, mip_blend.z, 1.0);
+        
+        // return texelFetch( u_page, tuv, 0 );
+       
+    }
+    
+    void main(){    
+        
+        pc_fragColor =  VirtualFetch(vUv);
+        
+    }
+    
+            `
+        });
+    }
+}

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

@@ -0,0 +1,203 @@
+import { ClampToEdgeWrapping, DataTexture, NearestFilter, RedIntegerFormat, UnsignedIntType } from "three";
+import { assert } from "../../../../../core/assert.js";
+import { UINT32_MAX } from "../../../../../core/binary/UINT32_MAX.js";
+import { compose_tile_address } from "./tile/compose_tile_address.js";
+import { decompose_finger_print } from "./tile/decompose_finger_print.js";
+
+const EMPTY_TILE = UINT32_MAX;
+
+/*
+ ENCODING:
+    22 bit  : slot index
+    10 bit   : tile mip
+ */
+
+/**
+ * Represents entire mip pyramid of tiles, where each tile slot points to an actual resident tile
+ */
+export class VirtualTextureMemoryMapping {
+    /**
+     * In tiles
+     * @type {number}
+     */
+    #resolution = 0;
+    #max_mip_level = 0;
+
+    get max_mip_level(){
+        return this.#max_mip_level;
+    }
+
+    #pyramid = new Uint32Array(0);
+    #texture = new DataTexture(
+        new Uint32Array(1),
+        1,
+        1,
+        RedIntegerFormat,
+        UnsignedIntType
+    )
+
+    get texture() {
+        return this.#texture;
+    }
+
+    constructor() {
+        const texture = this.#texture;
+
+        texture.internalFormat = "R32UI";
+        texture.generateMipmaps = false;
+
+        texture.wrapS = ClampToEdgeWrapping;
+        texture.wrapT = ClampToEdgeWrapping;
+
+        texture.magFilter = NearestFilter;
+        texture.minFilter = NearestFilter;
+        // texture.minFilter = NearestMipMapNearestFilter;
+        // texture.magFilter = NearestMipMapNearestFilter;
+    }
+
+    /**
+     *
+     * @param {number} resolution in tiles
+     */
+    set resolution(resolution) {
+        assert.isNonNegativeInteger(resolution, 'resolution');
+
+        if (this.#resolution === resolution) {
+            return;
+        }
+
+        this.#resolution = resolution;
+
+        //max mip
+        const max_mip_level = Math.log2(resolution);
+
+        const desired_size = compose_tile_address(max_mip_level + 1, 0, 0);
+
+        const texture_dimension = Math.ceil(Math.sqrt(desired_size));
+
+        const size = texture_dimension*texture_dimension;
+
+        this.#max_mip_level = max_mip_level;
+
+        const arrayBuffer = new ArrayBuffer(size * 4);
+
+        this.#pyramid = new Uint32Array(arrayBuffer);
+
+        const texture = this.#texture;
+        texture.dispose();
+
+
+        texture.image.data = this.#pyramid;
+        texture.image.width = texture_dimension;
+        texture.image.height = texture_dimension;
+
+        // texture.mipmaps.splice(0, texture.mipmaps.length);
+        // let buffer_offset = 0;
+        // for (let mip_level = 0; mip_level <= max_mip_level; mip_level++) {
+        //     const mip_resolution = 1 << mip_level;
+        //
+        //     const texel_count = mip_resolution * mip_resolution;
+        //     texture.mipmaps[mip_level] = {
+        //         data: new Uint32Array(arrayBuffer, buffer_offset, texel_count),
+        //         width: mip_resolution,
+        //         height: mip_resolution
+        //     };
+        //
+        //     buffer_offset += texel_count * 4;
+        // }
+        //
+        // texture.mipmaps.reverse();
+        //
+        // const top_mip = texture.mipmaps[0];
+        // texture.image.data = top_mip.data;
+        // texture.image.width = top_mip.width;
+        // texture.image.height = top_mip.height;
+
+        texture.needsUpdate = true;
+    }
+
+    get resolution() {
+        return this.#resolution;
+    }
+
+    /**
+     *
+     * @param {VirtualTexturePage} page
+     */
+    set residency(page) {
+
+        const tiles = page.resident_tiles;
+        const tile_count = tiles.length;
+
+        // clear pyramid
+
+        const pyramid = this.#pyramid;
+
+        pyramid.fill(EMPTY_TILE);
+
+        // fill by residence
+        for (let i = 0; i < tile_count; i++) {
+            const tile = tiles[i];
+
+            const fingerPrint = tile.finder_print;
+            const { mip, x, y } = decompose_finger_print(fingerPrint);
+            const address = compose_tile_address(mip, x, y);
+
+            const encoded =
+                (tile.page_slot & 0x3FFFFF)
+                | ((mip & 0x3FF) << 22) //mip
+            ;
+
+            pyramid[address] = encoded;
+        }
+
+        // back-fill empty slots
+        for (let mip = 1; mip <= this.#max_mip_level; mip++) {
+
+            const mip_resolution = 1 << mip;
+
+            for (let y = 0; y < mip_resolution; y++) {
+                for (let x = 0; x < mip_resolution; x++) {
+
+                    const tile_address = compose_tile_address(mip, x, y);
+
+                    if (pyramid[tile_address] !== EMPTY_TILE) {
+                        // page is filled, all is good, move on
+                        continue;
+                    }
+
+                    const parent_mip = mip - 1;
+                    const parent_x = x >>> 1;
+                    const parent_y = y >>> 1;
+
+                    const parent_tile_address = compose_tile_address(parent_mip, parent_x, parent_y);
+
+                    const parent_encoded_tile = pyramid[parent_tile_address];
+
+                    // decode parent tile
+                    const tile_index = (parent_encoded_tile) & 0x3FFFFF
+                    const tile_mip = (parent_encoded_tile >> 22) & 0x3FF
+
+                    // swap in parent tile
+
+
+                    const encoded_tile =
+                        (tile_index)
+                        | (tile_mip << 22)
+                    ;
+
+                    pyramid[tile_address] = encoded_tile;
+                }
+            }
+
+        }
+
+        // request texture update
+        this.#texture.needsUpdate = true;
+    }
+
+
+    dispose() {
+        this.#texture.dispose();
+    }
+}