@woosh/meep-engine 2.44.7 → 2.45.1

package/engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js

@@ -20,6 +20,7 @@ import TaskState from "../../../../core/process/task/TaskState.js";
 import {
     bvh_query_user_data_overlaps_frustum
 } from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_frustum.js";
+import { iteratorTask } from "../../../../core/process/task/util/iteratorTask.js";
 
 
 /**
@@ -34,6 +35,31 @@ const scratch_point = new SurfacePoint3();
  */
 const scratch_ray_0 = new Float32Array(6);
 
+/**
+ *
+ * @param {ShadedGeometrySystem} system
+ * @return {Generator}
+ */
+function* maintenance_generator(system) {
+    while (true) { //infinite loop
+
+        const contexts = system.__view_contexts;
+
+        for (const [key, value] of contexts) {
+
+            if (value === undefined) {
+                continue;
+            }
+
+            yield* value.maintain();
+
+        }
+
+        // a small break between re-runs
+        yield;
+    }
+}
+
 export class ShadedGeometrySystem extends System {
     /**
      *
@@ -100,8 +126,15 @@ export class ShadedGeometrySystem extends System {
                 }
             }
         });
+
+        this.__maintenance_task = iteratorTask(
+            'Maintenance',
+            maintenance_generator(this),
+            TaskSignal.Yield
+        );
     }
 
+
     /**
      *
      * @returns {ExplicitBinaryBoundingVolumeHierarchy}
@@ -222,6 +255,9 @@ export class ShadedGeometrySystem extends System {
         this.__optimization_task.state.set(TaskState.INITIAL);
         engine.executor.run(this.__optimization_task);
 
+        this.__maintenance_task.state.set(TaskState.INITIAL);
+        engine.executor.run(this.__maintenance_task);
+
         readyCallback();
     }
 
@@ -233,6 +269,7 @@ export class ShadedGeometrySystem extends System {
         const view_list = graphics.views.elements;
 
         engine.executor.removeTask(this.__optimization_task);
+        engine.executor.removeTask(this.__maintenance_task);
 
         view_list.forEach(this.__handle_view_removed, this);
         view_list.on.added.remove(this.__handle_view_added, this);

package/engine/graphics/ecs/mesh-v2/render/ShadedGeometryRendererContext.js

@@ -30,6 +30,25 @@ export class ShadedGeometryRendererContext {
         ];
     }
 
+    /**
+     * Performs maintenance on the context, mainly to check the hash tables for changes
+     * @return {Generator}
+     */
+    * maintain() {
+        const adapters = this.adapters;
+        for (let i = 0; i < adapters.length; i++) {
+            const adapter = adapters[i];
+
+            if (adapter === undefined) {
+                // adapter may disappear between invocations, since this is a continuation-type function
+                continue;
+            }
+
+            // delegate to adapter's maintenance
+            yield* adapter.maintain();
+        }
+    }
+
     /**
      *
      * @param {number} index

package/engine/graphics/ecs/mesh-v2/render/adapters/AbstractRenderAdapter.js

@@ -2,8 +2,8 @@ import { array_quick_sort_by_comparator } from "../../../../../../core/collectio
 
 /**
  *
- * @param {THREE.Object3D} a
- * @param {THREE.Object3D} b
+ * @param {THREE.Object3D|{material?:Material}} a
+ * @param {THREE.Object3D|{material?:Material}} b
  * @returns {number}
  */
 function compare_by_material(a, b) {
@@ -96,6 +96,15 @@ export class AbstractRenderAdapter {
         this.__object_count = 0;
     }
 
+    /**
+     * Used to perform infrequent housekeeping on the adapter's internal data structures
+     * Returns a maintenance sequence
+     * @return {Generator}
+     */
+    * maintain() {
+        // override as necessary
+    }
+
     /**
      * @returns {THREE.Object3D[]}
      */

package/engine/graphics/render/forward_plus/LightManager.js

@@ -17,7 +17,6 @@ import Vector3 from "../../../../core/geom/Vector3.js";
 import { query_bvh_frustum_from_objects } from "./query/query_bvh_frustum_from_objects.js";
 import { IncrementalDeltaSet } from "../visibility/IncrementalDeltaSet.js";
 import { computeFrustumCorners } from "./computeFrustumCorners.js";
-import { compute_light_data_hash_0 } from "./cluster/compute_light_data_hash_0.js";
 import { read_plane_pair } from "./cluster/read_plane_pair.js";
 import { read_frustum_planes_to_array } from "../../../../core/geom/3d/frustum/read_frustum_planes_to_array.js";
 import { compute_cluster_planes_from_points } from "./cluster/compute_cluster_planes_from_points.js";
@@ -30,9 +29,7 @@ import { NumericType } from "./data/NumericType.js";
 import { computeDataType } from "./data/computeDataType.js";
 import { computeThreeTextureTypeFromDataType } from "./data/computeThreeTextureTypeFromDataType.js";
 import { computeThreeTextureInternalFormatFromDataType } from "./data/computeThreeTextureInternalFormatFromDataType.js";
-import { testClusterEquality } from "./testClusterEquality.js";
 import { BinaryUint32BVH } from "../../../../core/bvh2/binary/2/BinaryUint32BVH.js";
-import { query_bvh_frustum_from_texture } from "./query/query_bvh_frustum_from_texture.js";
 import { mat4 } from "gl-matrix";
 import { TextureAtlas } from "../../texture/atlas/TextureAtlas.js";
 import { CachingTextureAtlas } from "../../texture/atlas/CachingTextureAtlas.js";
@@ -48,46 +45,8 @@ import { arraySwapElements } from "../../../../core/collection/array/arraySwapEl
 import { compareObjectsByNumericId } from "../../../../core/model/object/compareObjectsByNumericId.js";
 import { slice_frustum_linear_to_points } from "../../../../core/geom/3d/frustum/slice_frustum_linear_to_points.js";
 import { read_cluster_frustum_corners } from "../../../../core/geom/3d/frustum/read_cluster_frustum_corners.js";
+import { assign_cluster, LOOKUP_CACHE, scratch_corners, scratch_frustum_planes } from "./assign_cluster.js";
 
-const LOOKUP_CACHE_SIZE = 1024; // must be power of two
-
-/**
- * Using continuous buffer for related attributes to get better cache utilization
- * @type {ArrayBuffer}
- * @private
- */
-const _scratch_array_buffer = new ArrayBuffer(
-    24 * 4
-    + 24 * 4
-    + LOOKUP_CACHE_SIZE * 4
-);
-
-/**
- *
- * @type {number[]|Float32Array|Float64Array}
- */
-const scratch_corners = new Float32Array(_scratch_array_buffer, 0, 24);
-
-
-/**
- * Linear access data structure with parameters of each plane of the frustum
- * 6 planes, 4 values per plane
- * Layout: [normal.x, normal.y, normal.z, constant]
- * @type {number[]|Float32Array|Float64Array}
- */
-const scratch_frustum_planes = new Float32Array(_scratch_array_buffer, 24 * 4, 24);
-
-/**
- * Cache used to identify duplicate cells. Helps reduce memory usage and just point to equivalent existing cells instead of allocating new ones.
- * @type {Uint16Array|Uint32Array}
- */
-const LOOKUP_CACHE = new Uint32Array(_scratch_array_buffer, (24 + 24) * 4, LOOKUP_CACHE_SIZE);
-
-/**
- *
- * @type {number[]}
- */
-const scratch_light_nodes = [];
 
 /**
  * How many bits are used to encode light type
@@ -121,84 +80,6 @@ function encode_light_descriptor(address, light) {
     return light_type | (address << 2);
 }
 
-function assign_cluster(
-    tile_texture_data_offset,
-    light_bvh,
-    lookup_address_offset,
-    light_lookup_texture_data,
-    tile_texture_data,
-    light_source_data
-) {
-
-    // at this point we have a fully constructed cluster, we can query lights within the cluster
-    const match_count = query_bvh_frustum_from_texture(
-        scratch_light_nodes,
-        0,
-        light_bvh,
-        light_source_data,
-        scratch_frustum_planes,
-        scratch_corners
-    );
-
-    // construct tile data
-
-    // write number of light entries
-    tile_texture_data[tile_texture_data_offset + 1] = match_count;
-
-    if (match_count === 0) {
-        // don't waste time on assignment, there are no lights in the cluster
-        return 0;
-    }
-
-    /*
-     We can sort lights by index to get higher cache utilization, but it turns out quite costly.
-     Through experimentation, sorting was taking around 20% of the whole assignment time
-     while improving number of cache hits by around 40% (8000 without sorting -> 11000 with sorting)
-     */
-    const cluster_data_hash = compute_light_data_hash_0(scratch_light_nodes, match_count) & (LOOKUP_CACHE_SIZE - 1);
-
-    const existing_lookup_address = LOOKUP_CACHE[cluster_data_hash];
-
-    if (existing_lookup_address !== 0xFFFFFFFF) {
-        // found a hash match, validate equality
-        const existing_lookup_entry_match = testClusterEquality(
-            scratch_light_nodes,
-            match_count,
-            light_lookup_texture_data,
-            existing_lookup_address
-        );
-
-        if (existing_lookup_entry_match) {
-            tile_texture_data[tile_texture_data_offset] = existing_lookup_address;
-
-            //hash_reuse_count++;
-
-            return 0;
-        }
-    } else {
-        // no hash entry exists, create one
-        LOOKUP_CACHE[cluster_data_hash] = lookup_address_offset;
-    }
-
-    // if we get to this point, that means no hash match was found, or equality check was failed
-
-    // write address of the lookup table
-    tile_texture_data[tile_texture_data_offset] = lookup_address_offset;
-
-    for (let i = 0; i < match_count; i++) {
-        /**
-         *
-         * @type {number}
-         */
-        const light_descriptor = scratch_light_nodes[i];
-
-        // construct lookup table
-        light_lookup_texture_data[lookup_address_offset + i] = light_descriptor;
-    }
-
-    return match_count;
-}
-
 /**
  *
  * @param {IncrementalDeltaSet<PointLightData>} data_set
@@ -968,7 +849,7 @@ export class LightManager {
 
         /**
          *
-         * @type {number[]|Uint8ClampedArray}
+         * @type {number[]|Float32Array}
          */
         const light_source_data = this.__light_data.getTexture().image.data;
 
@@ -1033,7 +914,7 @@ export class LightManager {
                         light_source_data
                     );
 
-                    lookup_address_offset += assign_cluster(
+                    const decal_count = assign_cluster(
                         tile_data_offset + 2,
                         bvh_decals,
                         lookup_address_offset,
@@ -1041,6 +922,23 @@ export class LightManager {
                         tile_texture_data,
                         light_source_data
                     );
+
+                    /*
+                    TODO fix decal sorting artifacts
+
+                    if (decal_count > 1) { // only sort when there are 2 or more, sorting 1 object is pointless
+                        // decals need to be sorted for correct blending result
+                        sort_decal_data(
+                            light_lookup_texture_data,
+                            light_source_data,
+                            lookup_address_offset,
+                            decal_count
+                        );
+                    }
+
+                     */
+
+                    lookup_address_offset += decal_count;
                 }
             }
         }
@@ -1178,12 +1076,24 @@ export class LightManager {
     }
 
     /**
-     *
+     * Set resolution of the cluster texture, higher resolution will result in less load on the GPU, but will take up more RAM to represent and more time to build the clusters each frame
      * @param {number} x
      * @param {number} y
      * @param {number} z
      */
     setTileMapResolution(x, y, z) {
+        assert.isNumber(x,'x');
+        assert.isNonNegativeInteger(x,'x');
+        assert.isFiniteNumber(x,'x');
+
+        assert.isNumber(y,'y');
+        assert.isNonNegativeInteger(y,'y');
+        assert.isFiniteNumber(y,'y');
+
+        assert.isNumber(z,'z');
+        assert.isNonNegativeInteger(z,'z');
+        assert.isFiniteNumber(z,'z');
+
         const r = this.__tiles_resolution;
 
         if (x === r.x && y === r.y && z === r.z) {

package/engine/graphics/render/forward_plus/SPECIFICATION.md

@@ -0,0 +1,155 @@
+# Clustered Lighting Specification
+
+## 1. GPU Data structures
+
+Data is organized into 3 main textures:
+
+ - Clusters. `type: UINT, format: RGBA, dimension: 3D, filtering: nearest(none)`
+   - R - Offset into lookup texture for lights
+   - G - number of lights
+   - B - Offset into lookup texture for decals
+   - A - number of decals
+ - Lookup. `type: UINT, format: R, dimensions: 2D, filtering: nearest(none)`
+   - R - encoded reference into data texture, where actual lighting information is stored
+ - Data. `type: FLOAT, format: RGBA, dimensions: 2D, filtering: nearest(none)`
+   - RGBA - single `word` of data, you can think of it as a collection of `VEC4`s
+
+Below is a glsl snippet with initialization of uniforms for these textures:
+```glsl
+uniform usampler3D fp_t_light_clusters;
+uniform usampler2D fp_t_light_lookup;
+uniform sampler2D fp_t_light_data;
+```
+
+## 2. Light Data Format
+
+Each light is represented as a collection of `VEC4`s inside the `Data` texture. 
+
+ - Point Light:
+   - `[ position.x, position.y, position.z, radius ]`
+   - `[ color.r, color.g, color.b, intensity ]`
+ - Directional Light:
+   - `[ direction.x, direction.y, direction.z, UNUSED ]`
+   - `[ color.r, color.g, color.b, intensity ]`
+
+## 3. Light reference encoding
+
+Lookup texture contains integers that encode both the address of light data, and the type of light found at that address, this is done by encoding light type into lower 2 bits of a UINT32 
+
+Light type codes:
+ - 0 - PointLight
+ - 1 - Directional Light
+ - 2 - Spotlight
+
+Encoding snippet in JavaScript:
+```js
+/**
+ *
+ * @param {number} address
+ * @param {AbstractLight} light
+ * @returns {number}
+ */
+function encode_light_descriptor(address, light) {
+    const light_type = encode_light_type(light);
+    return light_type | (address << 2);
+}
+```
+
+Decoding snippet in GLSL
+```glsl
+ivec2 address_to_data_texture_coordinates(uint address){
+    // Lookup texture has 128 width
+    uint lookup_index_x = address % 128u;
+    uint lookup_index_y = address >> 7;
+
+    return ivec2(int(lookup_index_x),int(lookup_index_y));
+}
+
+// ...
+uint light_descriptor = texelFetch(fp_t_light_lookup, address_to_data_texture_coordinates(lookup_index), 0 ).r;
+
+uint type = (light_descriptor) & 0x3u;
+uint light_address = light_descriptor >> 2;
+```
+
+## 4. Auxiliary material
+
+Convert projection-space depth to linear space
+```glsl
+float convert_depth_to_linear(in float d){
+    float d_n = 2.0*d - 1.0;
+
+    float f = fp_f_camera_far;
+    float n = fp_f_camera_near;
+
+    float fn = f*n;
+    
+    float z_diff = f - n;
+    
+    float denominator = (f + n - d_n * z_diff );
+
+    float z_view = (2.0*fn) / denominator;
+
+    return (z_view - n) / z_diff;
+}
+```
+
+Fetching cluster information from fragment shader inside a forward pass
+```glsl
+    // v3_cluster_resolution is resolution of our cluster 3d texture
+    ivec3 v3_cluster_resolution = textureSize(fp_t_light_tiles, 0);
+    ivec3 v3_cluster_position = ivec3(  clip_v.x * float(v3_cluster_resolution.x), clip_v.y*float(v3_cluster_resolution.y),  (clip_v.z)*float(v3_cluster_resolution.z) );
+
+    uvec4 fp_cluster_metadata = texelFetch( fp_t_light_tiles, v3_cluster_position, 0 ).rgba;
+```
+
+Perform lighting (point-light only)
+```glsl
+// read light data
+for(uint i=0u; i < fp_cluster_metadata.y; i++){
+    uint lookup_index = fp_cluster_metadata.x + i;
+
+    uint light_descriptor = texelFetch(fp_t_light_lookup, address_to_data_texture_coordinates(lookup_index), 0 ).r;
+
+    uint type = (light_descriptor) & 0x3u;
+    uint light_address = light_descriptor >> 2;
+    
+
+    if(type == 0u){
+        // point light
+        
+        vec4 light_data_0 = texelFetch(fp_t_light_data, address_to_data_texture_coordinates(light_address), 0);
+        vec4 light_data_1 = texelFetch(fp_t_light_data, address_to_data_texture_coordinates(light_address+1u), 0);
+        
+        vec3 light_position = light_data_0.xyz;
+        float light_radius = light_data_0.w;
+        
+        vec3 light_color = light_data_1.xyz;
+        float light_intensity = light_data_1.w;
+        
+        PointLight pointlight;
+        
+        pointlight.position = light_position;
+        pointlight.distance = light_radius;
+        pointlight.color = light_color*light_intensity;
+        pointlight.decay = 1.0;
+        
+        fp_getPointDirectLightIrradiance( pointlight, directLight, vViewPosition );
+        RE_Direct( directLight, geometry, material, reflectedLight );
+    
+    } else if(type == 1u){
+        // directional light
+        
+        // ...
+    }
+}
+```
+
+## References:
+- [Dr.Strangelight or: How I learned to Stop Worrying and Love the Cluster](https://discourse.threejs.org/t/dr-strangelight-or-how-i-learned-to-stop-worrying-and-love-the-cluster/23104)
+- [Practical Clustered Shading by Emil Persson](http://www.humus.name/Articles/PracticalClusteredShading.pdf)
+
+---
+Author: Alexander Goldring, Company Named Limited
+
+Private and confidential, copyright (c) Company Named Limited, 2022

package/engine/graphics/render/forward_plus/assign_cluster.js

@@ -0,0 +1,125 @@
+import { query_bvh_frustum_from_texture } from "./query/query_bvh_frustum_from_texture.js";
+import { compute_light_data_hash_0 } from "./cluster/compute_light_data_hash_0.js";
+import { testClusterEquality } from "./testClusterEquality.js";
+
+const LOOKUP_CACHE_SIZE = 1024; // must be power of two
+/**
+ * Using continuous buffer for related attributes to get better cache utilization
+ * @type {ArrayBuffer}
+ * @private
+ */
+const _scratch_array_buffer = new ArrayBuffer(
+    24 * 4
+    + 24 * 4
+    + LOOKUP_CACHE_SIZE * 4
+);
+/**
+ *
+ * @type {number[]|Float32Array|Float64Array}
+ */
+export const scratch_corners = new Float32Array(_scratch_array_buffer, 0, 24);
+/**
+ * Linear access data structure with parameters of each plane of the frustum
+ * 6 planes, 4 values per plane
+ * Layout: [normal.x, normal.y, normal.z, constant]
+ * @type {number[]|Float32Array|Float64Array}
+ */
+export const scratch_frustum_planes = new Float32Array(_scratch_array_buffer, 24 * 4, 24);
+/**
+ * Cache used to identify duplicate cells. Helps reduce memory usage and just point to equivalent existing cells instead of allocating new ones.
+ * @type {Uint16Array|Uint32Array}
+ */
+export const LOOKUP_CACHE = new Uint32Array(_scratch_array_buffer, (24 + 24) * 4, LOOKUP_CACHE_SIZE);
+/**
+ *
+ * @type {number[]}
+ */
+const scratch_light_nodes = [];
+
+/**
+ *
+ * @param {number} tile_texture_data_offset
+ * @param {BinaryUint32BVH} bvh
+ * @param {number} lookup_address_offset
+ * @param {number[]|ArrayLike<number>|Uint8ClampedArray|Uint8Array|Uint16Array|Uint32Array} lookup_data
+ * @param {number[]|ArrayLike<number>|Uint8Array|Uint8ClampedArray|Uint16Array|Uint32Array} cluster_data
+ * @param {number[]|ArrayLike<number>|Float32Array} source_data Light/Decal source information is stored in here, such as position, color etc.
+ * @return {number}
+ */
+export function assign_cluster(
+    tile_texture_data_offset,
+    bvh,
+    lookup_address_offset,
+    lookup_data,
+    cluster_data,
+    source_data
+) {
+
+    // at this point we have a fully constructed cluster, we can query lights within the cluster
+    const match_count = query_bvh_frustum_from_texture(
+        scratch_light_nodes,
+        0,
+        bvh,
+        source_data,
+        scratch_frustum_planes,
+        scratch_corners
+    );
+
+    // construct tile data
+
+    // write number of light entries
+    cluster_data[tile_texture_data_offset + 1] = match_count;
+
+    if (match_count === 0) {
+        // don't waste time on assignment, there are no lights in the cluster
+        return 0;
+    }
+
+    /*
+     We can sort lights by index to get higher cache utilization, but it turns out quite costly.
+     Through experimentation, sorting was taking around 20% of the whole assignment time
+     while improving number of cache hits by around 40% (8000 without sorting -> 11000 with sorting)
+     */
+    const cluster_data_hash = compute_light_data_hash_0(scratch_light_nodes, match_count) & (LOOKUP_CACHE_SIZE - 1);
+
+    const existing_lookup_address = LOOKUP_CACHE[cluster_data_hash];
+
+    if (existing_lookup_address !== 0xFFFFFFFF) {
+        // found a hash match, validate equality
+        const existing_lookup_entry_match = testClusterEquality(
+            scratch_light_nodes,
+            match_count,
+            lookup_data,
+            existing_lookup_address
+        );
+
+        if (existing_lookup_entry_match) {
+            cluster_data[tile_texture_data_offset] = existing_lookup_address;
+
+            //hash_reuse_count++;
+
+            return 0;
+        }
+    } else {
+        // no hash entry exists, create one
+        LOOKUP_CACHE[cluster_data_hash] = lookup_address_offset;
+    }
+
+    // if we get to this point, that means no hash match was found, or equality check was failed
+
+    // write address of the lookup table
+    cluster_data[tile_texture_data_offset] = lookup_address_offset;
+
+    for (let i = 0; i < match_count; i++) {
+        /**
+         *
+         * @type {number}
+         */
+        const light_descriptor = scratch_light_nodes[i];
+
+        // construct lookup table
+        lookup_data[lookup_address_offset + i] = light_descriptor;
+    }
+
+    return match_count;
+}

package/engine/graphics/render/forward_plus/model/Decal.js

@@ -100,7 +100,11 @@ export class Decal extends AbstractLight {
 
         array_copy(this.uv, 0, destination, address + 16, 4);
 
-        return 20;
+        // required for sorting
+        destination[address + 20] = this.draw_priority;
+        destination[address + 21] = this.id;
+
+        return 24;
     }
 }
 
@@ -110,4 +114,4 @@ export class Decal extends AbstractLight {
  */
 Decal.prototype.isDecal = true;
 
-Decal.prototype.ENCODED_SLOT_COUNT = 20;
+Decal.prototype.ENCODED_SLOT_COUNT = 24;

package/engine/graphics/render/forward_plus/plugin/ForwardPlusRenderingPlugin.d.ts

@@ -0,0 +1,5 @@
+import {EnginePlugin} from "../../../../plugin/EnginePlugin";
+
+export class ForwardPlusRenderingPlugin extends EnginePlugin {
+    setClusterResolution(x: number, y: number, z: number): void
+}

package/engine/graphics/render/forward_plus/plugin/ForwardPlusRenderingPlugin.js

@@ -9,6 +9,7 @@ export class ForwardPlusRenderingPlugin extends EnginePlugin {
         super();
 
         this.__light_manager = new LightManager();
+        lm.setTileMapResolution(16, 8, 8);
 
         this.__resolution = new ThreeVector2();
 
@@ -19,6 +20,16 @@ export class ForwardPlusRenderingPlugin extends EnginePlugin {
         });
     }
 
+    /**
+     * Set resolution of the cluster texture, higher resolution will result in less load on the GPU, but will take up more RAM to represent and more time to build the clusters each frame
+     * @param {number} x
+     * @param {number} y
+     * @param {number} z
+     */
+    setClusterResolution(x, y, z) {
+        this.__light_manager.setTileMapResolution(x, y, z);
+    }
+
     /**
      *
      * @param {CameraView} view
@@ -37,10 +48,6 @@ export class ForwardPlusRenderingPlugin extends EnginePlugin {
     }
 
     async startup() {
-        const lm = this.__light_manager;
-
-        lm.setTileMapResolution(16, 8, 8);
-
         const graphics = this.engine.graphics;
 
         graphics.getMaterialManager().addCompileStep(this.__material_transformer);