@woosh/meep-engine 2.40.1 → 2.42.0

package/engine/graphics/geometry/MikkT/MikkTSpace.spec.js

@@ -14,7 +14,13 @@ test('single triangle', () => {
 
     ctx.geometry_buffer_index = [0, 1, 2];
     ctx.geometry_buffer_vertex_position = [1, 2, 3, 4, 5, 6, 7, 8, 9];
-    ctx.geometry_buffer_vertex_normal = [0, 1, 0, 0, 1, 0, 0, 1, 0];
+
+    ctx.geometry_buffer_vertex_normal = [
+        0, 1, 0,
+        0, 1, 0,
+        0, 1, 0
+    ];
+
     ctx.geometry_buffer_vertex_uv = [0, 0, 0, 0, 0, 0];
 
     genTangSpace(ctx);

package/engine/{asset/loaders/geometry/geometry → graphics/geometry/buffered}/computeBufferAttributeHash.js

@@ -1,4 +1,4 @@
-import { computeStridedIntegerArrayHash } from "../../../../computeStridedIntegerArrayHash.js";
+import { computeStridedIntegerArrayHash } from "../../../computeStridedIntegerArrayHash.js";
 
 /**
  *

package/engine/{asset/loaders/geometry/geometry → graphics/geometry/buffered}/computeGeometryEquality.js

@@ -1,5 +1,5 @@
-import { isArrayEqualStrict } from "../../../../../core/collection/array/isArrayEqualStrict.js";
-import { is_typed_array_equals } from "../../../../../core/collection/array/typed/is_typed_array_equals.js";
+import { isArrayEqualStrict } from "../../../../core/collection/array/isArrayEqualStrict.js";
+import { is_typed_array_equals } from "../../../../core/collection/array/typed/is_typed_array_equals.js";
 
 
 /**

package/engine/{asset/loaders/geometry/geometry → graphics/geometry/buffered}/computeGeometryHash.js

@@ -1,5 +1,5 @@
 import { computeBufferAttributeHash } from "./computeBufferAttributeHash.js";
-import { computeStringHash } from "../../../../../core/primitives/strings/computeStringHash.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
 
 /**
  *

package/engine/graphics/geometry/optimization/merge/merge_geometry_hierarchy.js

@@ -1,7 +1,7 @@
 import { StaticMaterialCache } from "../../../../asset/loaders/material/StaticMaterialCache.js";
 import { HashMap } from "../../../../../core/collection/HashMap.js";
-import { computeGeometryEquality } from "../../../../asset/loaders/geometry/geometry/computeGeometryEquality.js";
-import { computeGeometryHash } from "../../../../asset/loaders/geometry/geometry/computeGeometryHash.js";
+import { computeGeometryEquality } from "../../buffered/computeGeometryEquality.js";
+import { computeGeometryHash } from "../../buffered/computeGeometryHash.js";
 import { array_copy } from "../../../../../core/collection/array/copyArray.js";
 import { mat4 } from "gl-matrix";
 import { Group, Matrix4, Mesh } from "three";

package/engine/graphics/impostors/card_cluster/FacePlaneAssignment.js

@@ -0,0 +1,30 @@
+/**
+ * A geometry is separated into individual triangles, with each triangle projected onto a single plane.
+ * This class contains and fully describes such assignment
+ */
+export class FacePlaneAssignment {
+    /**
+     * Flat plane data array
+     * Format: [normal_0_x, normal_0_y, normal_0_z, plane_0_offset, normal_1_x, ... ]
+     * @type {number[]}
+     */
+    planes = [];
+
+    /**
+     *
+     * @type {number}
+     */
+    plane_count = 0;
+
+    /**
+     *
+     * @type {THREE.BufferGeometry|null}
+     */
+    geometry = null;
+
+    /**
+     * Indices of planes associated with each face (triangle) for a given face index
+     * @type {number[]}
+     */
+    face_assignments = [];
+}

package/engine/graphics/impostors/card_cluster/README.md

@@ -0,0 +1,13 @@
+# Card Cluster Impostors
+
+The system is fairly trivial in concept. It generates a specified number of *cards* (quads) along with textures to represent original mesh.
+
+The idea for this system was inspired by Sean Feeley's talk at GDC 2019 "Interactive Wind and Vegetation in 'God of War'", where he briefly explained how impostors work in their engine.
+
+---
+### References
+
+1. [2003] "Billboard Clouds for Extreme Model Simplification" by Xavier Decoret, Fr ´ edo Durand, Franc ´ ¸ois X. Sillion, Julie Dorsey
+2. [2005] "Extreme Model Simplification for Forest Rendering" by Anton L. Fuhrmann, Eike Umlauf and Stephan Mantler
+3. [2005] "Tree Rendering with Billboard Clouds" by Ismael Garcia, Mateu Sbert, and László Szirmay-Kalos
+4. [2009] "Implementation of an Improved Billboard Cloud Algorithm" by Christian Luksch

package/engine/graphics/impostors/octahedral/ImpostorBaker.js

@@ -0,0 +1,345 @@
+import { ImpostorCaptureType } from "./ImpostorCaptureType.js";
+import { assert } from "../../../../core/assert.js";
+import { isPowerOfTwo } from "../../../../core/math/isPowerOrTwo.js";
+import { Mesh, OrthographicCamera, Scene, Vector4, WebGLMultipleRenderTargets } from "three";
+import { ImpostorDescription } from "./ImpostorDescription.js";
+import { mat4, vec3 } from "gl-matrix";
+import { BakeShaderStandard } from "./shader/BakeShaderStandard.js";
+import { Sampler2D } from "../../texture/sampler/Sampler2D.js";
+import Signal from "../../../../core/events/signal/Signal.js";
+import { HashMap } from "../../../../core/collection/HashMap.js";
+import { computeMaterialHash } from "../../../asset/loaders/material/computeMaterialHash.js";
+import { computeMaterialEquality } from "../../../asset/loaders/material/computeMaterialEquality.js";
+import { UvEncoder } from "./grid/UvEncoder.js";
+import { OctahedralUvEncoder } from "./grid/OctahedralUvEncoder.js";
+import { HemiOctahedralUvEncoder } from "./grid/HemiOctahedralUvEncoder.js";
+import { prepare_bake_material } from "./bake/prepare_bake_material.js";
+import { collectIteratorValueToArray } from "../../../../core/collection/IteratorUtils.js";
+import { compute_bounding_sphere } from "./bake/compute_bounding_sphere.js";
+
+export class ImpostorBaker {
+
+    /**
+     *
+     * @type {THREE.WebGLRenderer|null}
+     * @private
+     */
+    _renderer = null;
+
+    /**
+     *
+     * @param {THREE.WebGLRenderer} v
+     */
+    set renderer(v) {
+        this._renderer = v;
+    }
+
+
+    /**
+     *
+     * @param {number[]|vec4} bounding_sphere
+     * @param {{mesh:ShadedGeometry, transform:mat4}[]} objects
+     * @param {number} resolution
+     * @param {number} frames
+     * @param {UvEncoder} encoder
+     */
+    bake_internal({
+                      bounding_sphere,
+                      objects,
+                      resolution,
+                      frames,
+                      encoder
+                  }) {
+
+        const distance = bounding_sphere[3];
+
+        assert.isNumber(distance, 'distance');
+        assert.isNonNegativeInteger(resolution, 'resolution');
+        assert.isNonNegativeInteger(frames, 'frames');
+
+        const unit_sphere_direction = [];
+
+        const cam = new OrthographicCamera();
+        const rt = new WebGLMultipleRenderTargets(resolution, resolution, 3);
+        rt.scissorTest = false;
+        rt.stencilBuffer = false;
+
+        rt.texture[0].name = 'diffuse+alpha';
+        rt.texture[1].name = 'normal+depth';
+        rt.texture[2].name = 'orm'; // Occlusion, Roughness, Metalness
+
+        const renderer = this._renderer;
+
+        // remember render state
+        const _rt = renderer.getRenderTarget();
+        const _vp = new Vector4();
+        renderer.getViewport(_vp);
+        const _autoClear = renderer.autoClear;
+        const _pixelRatio = renderer.getPixelRatio();
+
+        const gl = this._renderer.getContext();
+
+        // Baking should be done without anti-aliasing, so we make sure to disable it
+        const _enabled_antialias = gl.isEnabled(gl.SAMPLE_ALPHA_TO_COVERAGE);
+
+        if (_enabled_antialias) {
+            gl.disable(gl.SAMPLE_ALPHA_TO_COVERAGE);
+        }
+
+
+        // set new render state
+        renderer.autoClear = false;
+        renderer.setRenderTarget(rt);
+        renderer.setClearColor(0xFFFFFF, 0);
+        renderer.clearColor();
+        renderer.setPixelRatio(1);
+
+        const frame_width = resolution / frames;
+        const frame_height = resolution / frames;
+
+        const object_count = objects.length;
+
+        // construct scene
+        const scene = new Scene();
+
+        scene.autoUpdate = false;
+        scene.matrixAutoUpdate = false;
+        scene.matrixWorldNeedsUpdate = false;
+
+        const id = new ImpostorDescription();
+        id.frame_count = frames;
+        id.resolution = resolution;
+
+        /**
+         * Fired when all the rendering is done to indicate that cleanup should happen
+         * @type {Signal}
+         */
+        const cleanup_signal = new Signal();
+
+        /**
+         *
+         * @type {HashMap<Material, BakeShaderStandard>}
+         */
+        const bake_material_map = new HashMap({
+            keyHashFunction: computeMaterialHash,
+            keyEqualityFunction: computeMaterialEquality
+        });
+
+        const max_anisotropic_filtering_level = renderer.capabilities.getMaxAnisotropy();
+
+        for (let k = 0; k < object_count; k++) {
+            const object = objects[k];
+
+            const source_mesh = object.mesh;
+
+            // ensure tangents are generated
+            //buffer_geometry_ensure_tangents(source_mesh.geometry);
+
+            const source_material = source_mesh.material;
+
+            // obtain material for baking
+            const bake_material = bake_material_map.getOrCompute(source_material, (source_material) => {
+
+                const bake_material = new BakeShaderStandard();
+
+                // prepare bake material to match the source material
+                prepare_bake_material({
+                    bake_material: bake_material,
+                    source_material: source_material,
+                    cleanup_signal: cleanup_signal,
+                    anisotropy: max_anisotropic_filtering_level
+                });
+
+                bake_material.uniforms.uAtlasResolution.value.set(resolution, resolution);
+
+                cleanup_signal.addOne(bake_material.dispose, bake_material);
+
+                id.source_material_count++;
+
+                return bake_material;
+            });
+
+
+            const geometry = source_mesh.geometry;
+            const mesh = new Mesh(geometry, bake_material);
+
+            mesh.matrixAutoUpdate = false;
+            mesh.matrixWorldNeedsUpdate = false;
+            mesh.frustumCulled = false;
+
+            mat4.copy(mesh.matrixWorld.elements, object.transform);
+
+            scene.add(mesh);
+
+            // update stats
+            id.source_geometry_polygon_count += geometry.getIndex().count / 3;
+            id.source_geometry_vertex_count += geometry.getAttribute('position').count;
+            id.source_instance_count++;
+        }
+
+
+        const bake_material_array = collectIteratorValueToArray([], bake_material_map.values());
+
+        // traverse octahedron
+        const max_frame_index = frames - 1;
+
+        for (let i = 0; i < frames; i++) {
+            const octahedron_u = max_frame_index > 0 ? (i / max_frame_index) : 0;
+
+            for (let j = 0; j < frames; j++) {
+
+                const octahedron_v = max_frame_index > 0 ? (j / max_frame_index) : 0;
+
+                // compute vector direction where to place camera
+                encoder.uv_to_unit(unit_sphere_direction, [octahedron_u, octahedron_v]);
+
+                // offset by the radius of the sphere
+                const camera_px = distance * unit_sphere_direction[0] + bounding_sphere[0];
+                const camera_py = distance * unit_sphere_direction[1] + bounding_sphere[1];
+                const camera_pz = distance * unit_sphere_direction[2] + bounding_sphere[2];
+
+                // console.log(`UV:${octahedron_u.toFixed(2)},${octahedron_v.toFixed(2)}\t V3:${unit_sphere_direction.map(n => n.toFixed(2)).join(', ')}`);
+
+                // construct projection matrix
+                cam.left = -distance;
+                cam.right = distance;
+                cam.top = distance;
+                cam.bottom = -distance;
+                cam.near = 0;
+                cam.far = distance * 2;
+
+                cam.position.set(
+                    camera_px,
+                    camera_py,
+                    camera_pz
+                );
+
+                cam.lookAt(bounding_sphere[0], bounding_sphere[1], bounding_sphere[2]);
+                cam.updateProjectionMatrix();
+
+                // update materials
+                for (let k = 0; k < bake_material_array.length; k++) {
+                    const mat = bake_material_array[k];
+
+                    mat.uniforms.projection_params.value.set(
+                        0, 0, 0, 1 / cam.far
+                    );
+                    mat.uniformsNeedUpdate = true;
+                }
+
+                //TODO consider doing super-sampling for some textures for better-looking results
+
+                /*
+                TODO it's possible to reduce bounding sphere in some cases where thin geometry would produce 0 texels
+                 in the actual render, but we can't know that without doing the rendering first.
+                 Consider doing a cheap pre-pass, rendering out pixels and checking if we can crop the bounding sphere further
+                 */
+
+                renderer.setViewport(i * frame_width, j * frame_height, frame_width, frame_height);
+                renderer.render(scene, cam);
+            }
+        }
+
+        /*
+         TODO dilate non-color textures to prevent artifacts when sampling around the edges
+         */
+
+        //restore renderer state
+        renderer.setRenderTarget(_rt);
+        renderer.setViewport(_vp);
+        renderer.autoClear = _autoClear;
+        renderer.setPixelRatio(_pixelRatio);
+        if (_enabled_antialias) {
+            gl.enable(gl.SAMPLE_ALPHA_TO_COVERAGE);
+        }
+
+        // cleanup
+        cleanup_signal.send0();
+
+        // const sampler = convertTexture2Sampler2D(rt.texture);
+
+
+        id.atlas = Sampler2D.uint8(1, resolution, resolution);
+        // id.atlas = sampler;
+        id.rt = rt;
+
+        return id;
+    }
+
+    /**
+     *
+     * @param {{mesh:ShadedGeometry, transform:mat4}[]} objects objects that should make up the impostor. Baking will be done around the origin, so make sure to position meshes accordingly to make good use of texture space.
+     * @param {number} frames how many views to capture for the atlas in each X and Y direction. Setting this to 4 will result in 16 (4*4) views captured, higher value will sacrifice detail but result in transitions being more smooth
+     * @param {number} resolution resolution of the final asset, higher = more detail
+     * @param {ImpostorCaptureType} type
+     * @returns {ImpostorDescription}
+     */
+    bake({
+             objects,
+             frames = 12,
+             resolution = 1024,
+             type = ImpostorCaptureType.FullSphere
+         }) {
+
+        console.time('bake');
+
+        assert.defined(objects, 'object');
+        assert.isNonNegativeInteger(frames, 'frames');
+        assert.isNonNegativeInteger(resolution, 'resolution');
+        assert.greaterThanOrEqual(frames, 1, 'number of frames must be >= 1');
+
+        if (frames > resolution) {
+            throw new Error(`Frame count(=${frames}) is greater than the resolution(=${resolution}) of the bake texture, packing description is unachievable`);
+        }
+
+        const frame_resolution = resolution / frames;
+
+        if (frames >= resolution / 4) {
+            console.warn(`Bake configuration will produce less frames, this will likely result in a useless impostor that contains too little texel density to properly represent the underlying scene.  [frames=${frames}, resolution=${resolution}, resulting density = ${Math.pow(frame_resolution, 2)} texels per frame]`);
+        }
+
+        if (resolution % frames !== 0 && frame_resolution < 16) {
+            console.warn(`To get results at low frame resolutions number of frames should be a divisor of resolution, instead got [frames=${frames}, resolution=${resolution}, resolution/frames=${frame_resolution}]`);
+        }
+
+        if (!isPowerOfTwo(resolution)) {
+            throw new Error(` 'resolution' must be a power of two, instead was '${resolution}'`);
+        }
+
+        if (frames < 2) {
+            console.warn(`Frame count is set to ${frames}, which is too low to be useful. Consider values of 2 and above. A good default is 12`);
+        }
+
+        if (this._renderer === null) {
+            throw new Error('No renderer attached. Renderer is required for baking.');
+        }
+
+        const bounding_sphere = compute_bounding_sphere(objects);
+
+        // we need to compute bounding sphere around origin of the object
+        let encoder;
+        if (type === ImpostorCaptureType.FullSphere) {
+            encoder = new OctahedralUvEncoder();
+        } else if (type === ImpostorCaptureType.Hemisphere) {
+            encoder = new HemiOctahedralUvEncoder();
+        } else {
+            throw new Error(`Unsupported capture mode '${type}'`);
+        }
+
+        const r = this.bake_internal({
+            resolution,
+            frames,
+            objects,
+            bounding_sphere,
+            encoder
+        });
+
+        r.capture_type = type;
+        r.sphere_radius = bounding_sphere[3];
+        vec3.copy(r.offset,bounding_sphere);
+
+        console.timeEnd('bake');
+
+        return r;
+    }
+}

package/engine/graphics/impostors/octahedral/ImpostorCaptureType.js

@@ -0,0 +1,10 @@
+export const ImpostorCaptureType = {
+    /**
+     * Capture from all sides
+     */
+    FullSphere: 0,
+    /**
+     * Only capture from the top hemisphere, good for things that will never be seen from "below", such as trees, houses etc.
+     */
+    Hemisphere: 1
+};

package/engine/graphics/impostors/octahedral/ImpostorDescription.js

@@ -0,0 +1,69 @@
+import { ImpostorCaptureType } from "./ImpostorCaptureType.js";
+
+export class ImpostorDescription {
+    /**
+     * How many XY frames should be captured
+     * More frames will result in less distortion, but lower texel density (lower resolution for each individual frame)
+     * @type {number}
+     */
+    frame_count = 16;
+
+    /**
+     * How the impostor is being captured
+     * @type {number}
+     */
+    capture_type = ImpostorCaptureType.FullSphere;
+
+    /**
+     * Resolution of the texture atlas used for baking. All "frames" will be packed here
+     * Must be power of two
+     * @type {number}
+     */
+    resolution = 1024;
+
+    /**
+     * Radius of baking sphere, this is centered on origin
+     * @type {number}
+     */
+    sphere_radius = 0;
+
+    /**
+     * Baking offset
+     * @type {number[]}
+     */
+    offset = [0, 0, 0];
+
+    /**
+     * Actual baked data
+     * @type {Sampler2D|null}
+     */
+    atlas = null;
+
+    /**
+     * Source scene from which impostor was baked
+     * @type {number}
+     */
+    source_geometry_polygon_count = 0;
+    /**
+     * @type {number}
+     */
+    source_geometry_vertex_count = 0;
+    /**
+     *
+     * @type {number}
+     */
+    source_material_count = 0;
+    /**
+     *
+     * @type {number}
+     */
+    source_instance_count = 0;
+
+
+    /**
+     * TODO: replace with something non-three.js specific
+     * @deprecated use non-three.js specific accessors instead
+     * @type {THREE.WebGLMultipleRenderTargets}
+     */
+    rt = null;
+}

package/engine/graphics/impostors/octahedral/README.md

@@ -0,0 +1,30 @@
+# Octahedral Impostor system
+
+This system is based on the idea presented by Ryan Brucks
+
+Conceptually, the system has 2 parts:
+1. Baking. This is where we take the source mesh, and prepare assets for impostor. These assets are mainly textures, copied from materials of the source meshes as well as depth fields.
+2. Drawing. Assets prepared during "Baking" part are being rendered, using a simple geometry (6 triangles), and performing ray marching as well as shading inside the pixel shader. 
+
+This is inherently a deferred rendering technique, where an impostor asset is represented as a collection of pre-rendered G-Buffers from different view angles, those "frames" are looked up at runtime in the shader to create the best approximation of a G-Buffer for the given projection transform, and the shading is performed. Depth is written out as well, this allows impostors to not only exist in color space, but also in depth space. The fact that impostors write depth gives them ability to be used for shadow mapping as well.
+
+## Limitations
+* Materials. Currently only PBR rendering is supported with the following attributes recorded
+  * Albedo (vertex colors are included as well)
+  * Normal
+  * Metalness
+  * Roughness
+  * Ambient Occlusion
+* Animations are not supported, neither vertex, nor pixel-shader based ones. The whole impostor can move around and be transformed, but the contents are static and pre-baked.
+* When camera moves too close to the impostor, or an extreme projection is applied - artefacts will become visible. In case of camera getting too close - parts of the mesh that are occluded by outer shell will not become visible in the impostor, as that information is simply not captured. In cases of extreme projection - certain parts of the captured G-Buffer may undergo warping and stretching converting a handful of baked pixel to a larger number of on-screen pixels, creating pixelation and smearing. Note that impostors are not a replacement for your meshes, so use them sensibly.
+
+
+---
+references:
+
+- [2021] [Rendering a Sphere on a Quad](https://bgolus.medium.com/rendering-a-sphere-on-a-quad-13c92025570c) by Ben Golus
+- [2018] [Octahedral Impostors](https://shaderbits.com/blog/octahedral-impostors) by Ryan Brucks
+- [2018] https://github.com/xraxra/IMP
+- [2018] https://github.com/wojtekpil/Godot-Octahedral-Impostors
+- [2011] BN11 : "Real-time Realistic Rendering and Lighting of Forests" by Eric Bruneton, Fabrice Neyret
+- [2007] TSK07: "Fast (Spherical) Light Field Rendering with Per-Pixel Depth." by Severin Todt, Christof Rezk-Salama and Andreas Kolb

package/engine/graphics/impostors/octahedral/bake/compute_bounding_sphere.js

@@ -0,0 +1,45 @@
+import { Miniball } from "../../../../../core/geom/packing/miniball/Miniball.js";
+import { PointSet } from "../../../../../core/geom/packing/miniball/PointSet.js";
+import { apply_mat4_transform_to_v3_array } from "../../../../../core/geom/3d/apply_mat4_transform_to_v3_array.js";
+
+/**
+ *
+ * @param {{mesh:ShadedGeometry, transform:mat4}[]} objects
+ */
+export function compute_bounding_sphere(objects) {
+    let total_point_count = 0;
+    const object_count = objects.length;
+
+    for (let i = 0; i < object_count; i++) {
+        const object = objects[i];
+
+        const geometry = object.mesh.geometry;
+
+        const attribute = geometry.getAttribute('position');
+
+        total_point_count += attribute.count;
+    }
+
+    const final_buffer = new Float32Array(total_point_count * 3);
+
+    let pointer = 0;
+
+    for (let i = 0; i < object_count; i++) {
+        const object = objects[i];
+
+        const geometry = object.mesh.geometry;
+
+        const attribute = geometry.getAttribute('position');
+
+        const source_length = attribute.array.length;
+
+        apply_mat4_transform_to_v3_array(attribute.array, 0, final_buffer, pointer, attribute.count, object.transform);
+
+        pointer += source_length;
+    }
+
+    const points = new PointSet(total_point_count, 3, final_buffer);
+    const miniball = new Miniball(points);
+
+    return [...miniball.center(), miniball.radius()];
+}

package/engine/graphics/impostors/octahedral/bake/compute_bounding_sphere_radius_only.js

@@ -0,0 +1,37 @@
+import { max2 } from "../../../../../core/math/max2.js";
+import {
+    sphere_radius_sqr_from_v3_array_transformed
+} from "../../../../../core/geom/3d/sphere/sphere_radius_sqr_from_v3_array_transformed.js";
+
+/**
+ * Computes radius of bounding sphere around origin for given group of objects
+ *
+ * NOTE: This may seem pointless, but by doing this computation on per-vertex basis we get the tightest possible bounds,
+ * allowing us to get the best possible texture space utilization.
+ * @param {{mesh:ShadedGeometry, transform:mat4}[]} objects
+ * @returns {number}
+ */
+export function compute_bounding_sphere_radius_only(objects) {
+    let distance_sqr = 0;
+
+    const n = objects.length;
+    for (let i = 0; i < n; i++) {
+        const object = objects[i];
+
+        const attribute = object.mesh.geometry.getAttribute('position');
+
+        const array = attribute.array;
+
+        const transform = object.transform;
+
+        const n = array.length;
+
+        const radius2 = sphere_radius_sqr_from_v3_array_transformed(array, n, transform);
+
+        distance_sqr = max2(distance_sqr, radius2);
+
+    }
+
+
+    return Math.sqrt(distance_sqr);
+}