@woosh/meep-engine 2.163.11 → 2.165.0

package/src/engine/graphics/sh3/lightmap/prototypeLightmapBaker.js

@@ -0,0 +1,186 @@
+import { BoxBufferGeometry, MeshStandardMaterial, SphereBufferGeometry } from "three";
+import Quaternion from "../../../../core/geom/Quaternion.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+import Tag from "../../../ecs/components/Tag.js";
+import Entity from "../../../ecs/Entity.js";
+import { Transform } from "../../../ecs/transform/Transform.js";
+import { EngineHarness } from "../../../EngineHarness.js";
+import { Light } from "../../ecs/light/Light.js";
+import LightSystem from "../../ecs/light/LightSystem.js";
+import { ShadedGeometry } from "../../ecs/mesh-v2/ShadedGeometry.js";
+import { ShadedGeometryFlags } from "../../ecs/mesh-v2/ShadedGeometryFlags.js";
+import { ShadedGeometrySystem } from "../../ecs/mesh-v2/ShadedGeometrySystem.js";
+import { bake_lightmap_for_scene } from "./bake_lightmap_for_scene.js";
+
+const harness = new EngineHarness();
+
+/**
+ * Add one coloured {@link ShadedGeometry} entity to the scene.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {THREE.BufferGeometry} geometry
+ * @param {number} color hex colour
+ * @param {Vector3} position
+ * @param {Quaternion} [rotation]
+ */
+function spawn(ecd, geometry, color, position, rotation) {
+    const material = new MeshStandardMaterial({ color, roughness: 1, metalness: 0 });
+
+    const sg = ShadedGeometry.from(geometry, material);
+    sg.setFlag(ShadedGeometryFlags.CastShadow);
+    sg.setFlag(ShadedGeometryFlags.ReceiveShadow);
+    sg.setFlag(ShadedGeometryFlags.Visible);
+
+    const transform = new Transform();
+    transform.position.copy(position);
+    if (rotation !== undefined) {
+        transform.rotation.copy(rotation);
+    }
+
+    new Entity()
+        .add(sg)
+        .add(transform)
+        .add(Tag.fromJSON(["LightmapTarget"]))
+        .build(ecd);
+}
+
+/**
+ * Add a coloured light. DIRECTION lights bake crisp shadows; POINT lights add
+ * coloured bounce. Both are read by the path-traced bake.
+ *
+ * @param {EntityComponentDataset} ecd
+ * @param {number} type one of {@link Light.Type}
+ * @param {number[]} color linear [r, g, b] in 0..1
+ * @param {number} intensity
+ * @param {Object} placement
+ * @param {Vector3} [placement.position]
+ * @param {Vector3} [placement.direction]
+ * @param {number} [placement.distance] point-light influence radius
+ */
+function spawn_light(ecd, type, color, intensity, { position, direction, distance = 30 }) {
+    const light = new Light();
+    light.type.set(type);
+    light.color.setRGB(color[0], color[1], color[2]);
+    light.intensity.set(intensity);
+    light.distance.set(distance);
+    light.castShadow.set(true);
+
+    const transform = new Transform();
+    if (position !== undefined) {
+        transform.position.copy(position);
+    }
+    if (direction !== undefined) {
+        transform.rotation.lookRotation(direction.clone().normalize());
+    }
+
+    new Entity()
+        .add(light)
+        .add(transform)
+        .add(Tag.fromJSON(["Light"]))
+        .build(ecd);
+}
+
+/**
+ * @param {Engine} engine
+ */
+async function main(engine) {
+    const em = engine.entityManager;
+
+    await em.addSystem(new ShadedGeometrySystem(engine));
+    await em.addSystem(new LightSystem(engine, { shadowResolution: 2048 }));
+
+    // camera + orbital/keyboard controls; no terrain (we build our own platform),
+    // no engine lights (we place our own so we can dim them after the bake)
+    await EngineHarness.buildBasics({
+        engine,
+        focus: new Vector3(0, 1.5, 0),
+        pitch: 0.95,
+        yaw: 0.6,
+        distance: 18,
+        enableTerrain: false,
+        enableWater: false,
+        enableLights: false,
+        cameraController: true,
+        showFps: true,
+    });
+
+    const ecd = em.dataset;
+
+    // --- platform ---
+    spawn(ecd, new BoxBufferGeometry(16, 1, 16), 0xA1A1A1, new Vector3(0, -0.5, 0));
+
+    // --- a few shapes ---
+    spawn(ecd, new BoxBufferGeometry(2, 2, 2), 0xe23b3b, new Vector3(-4, 1, -2));
+    spawn(ecd, new BoxBufferGeometry(2, 4, 2), 0x3bd16f, new Vector3(3.5, 2, 2));
+    spawn(ecd, new SphereBufferGeometry(1.5, 32, 24), 0x4f86ff, new Vector3(0, 1.5, 3.5));
+    spawn(
+        ecd,
+        new BoxBufferGeometry(2.5, 2.5, 2.5),
+        0xf0c020,
+        new Vector3(2.5, 1.25, -3.5),
+        Quaternion.fromEulerAngles(0, Math.PI / 5, 0)
+    );
+
+    // --- lights (baked) ---
+    spawn_light(ecd, Light.Type.DIRECTION, [1.0, 0.95, 0.88], 1.6, { direction: new Vector3(-0.6, -1, -0.35) });
+    spawn_light(ecd, Light.Type.POINT, [1.0, 0.3, 0.18], 1, { position: new Vector3(-4, 2.5, 4), distance: 16 });
+    spawn_light(ecd, Light.Type.POINT, [0.18, 0.42, 1.0], 1, { position: new Vector3(5, 3, -5), distance: 16 });
+
+    const status = make_status_overlay();
+
+    // give the ECS one frame to settle transforms before baking
+    requestAnimationFrame(() => {
+        const group = bake_lightmap_for_scene({
+            ecd,
+            lightmap_resolution: 1024,
+            samples_per_texel: 1024,
+            min_bounce: 1,
+            max_bounce: 4,
+            padding: 2,
+        });
+
+        // expose for console poking
+        window.lightmap_bake = group;
+
+        // engine.executor.runGroup(group);
+
+        // progress readout
+        function poll() {
+            const p = group.computeProgress();
+            status.textContent = `Baking lightmap… ${(p * 100).toFixed(1)}%`;
+            if (p < 1) {
+                requestAnimationFrame(poll);
+            }
+        }
+
+        poll();
+    });
+}
+
+/**
+ * @returns {HTMLDivElement}
+ */
+function make_status_overlay() {
+    const el = document.createElement("div");
+    el.style.position = "fixed";
+    el.style.left = "8px";
+    el.style.top = "8px";
+    el.style.zIndex = "1000";
+    el.style.padding = "6px 10px";
+    el.style.font = "13px monospace";
+    el.style.color = "#fff";
+    el.style.background = "rgba(0,0,0,0.55)";
+    el.style.borderRadius = "4px";
+    el.style.pointerEvents = "none";
+    el.textContent = "Preparing bake…";
+    document.body.appendChild(el);
+    return el;
+}
+
+harness.initialize({
+    configuration(config) {
+
+        // config.addPlugin(AmbientOcclusionPostProcessEffect)
+
+    },
+}).then(main);

package/src/engine/graphics/sh3/lpv/PathTracerProbeRenderer.js

@@ -5,8 +5,8 @@ import {
     sh3_dering_optimize_positive
 } from "../../../../core/geom/3d/sphere/harmonics/sh3_dering_optimize_positive.js";
 import { sh3_vector_accumulate } from "../../../../core/geom/3d/sphere/harmonics/sh3_vector_accumulate.js";
-import { randomPointOnSphere } from "../../../../core/geom/random/randomPointOnSphere.js";
-import { vector_scale_array } from "../../../../core/geom/vec/vector_scale_array.js";
+import { random_point_on_sphere } from "../../../../core/geom/random/random_point_on_sphere.js";
+import { vector_scale_offset } from "../../../../core/geom/vec/vector_scale_offset.js";
 import { seededRandom } from "../../../../core/math/random/seededRandom.js";
 import { PathTracedScene } from "../path_tracer/PathTracedScene.js";
 import { PathTracer } from "../path_tracer/PathTracer.js";
@@ -69,7 +69,7 @@ export class PathTracerProbeRenderer extends ProbeRenderer {
 
         for (let i = 0; i < this.sample_count; i++) {
 
-            randomPointOnSphere(this.random, ray, 3);
+            random_point_on_sphere(this.random, ray, 3);
             ray.tMax = Infinity;
             ray.tMin = 0;
 
@@ -88,7 +88,7 @@ export class PathTracerProbeRenderer extends ProbeRenderer {
         // Area of a unit sphere is (4*PI)
         const normalization_weight = (4 * Math.PI) / this.sample_count;
 
-        vector_scale_array(coefficients, 0, coefficients, 0, 27, normalization_weight);
+        vector_scale_offset(coefficients, 0, coefficients, 0, 27, normalization_weight);
 
         sh3_dering_optimize_positive(coefficients, 0, coefficients, 0, 3);
 

package/src/engine/graphics/sh3/lpv/depth/octahedral/bake_octahedral_depth_map.js

@@ -6,7 +6,7 @@ import {
 } from "../../../../../../core/geom/3d/normal/octahedron/decode_octahedron_to_unit.js";
 import { Ray3 } from "../../../../../../core/geom/3d/ray/Ray3.js";
 import { v3_distance } from "../../../../../../core/geom/vec3/v3_distance.js";
-import { v3_dot_array_array } from "../../../../../../core/geom/vec3/v3_dot_array_array.js";
+import { v3_dot_array } from "../../../../../../core/geom/vec3/v3_dot_array.js";
 import { max2 } from "../../../../../../core/math/max2.js";
 import { generate_hammersley_jitter } from "../../../../../../core/math/statistics/generate_hammersley_jitter.js";
 
@@ -119,7 +119,7 @@ export function bake_octahedral_depth_map(
 
                 }
 
-                const direction_dot_product = v3_dot_array_array(ray_direction, 0, probe_direction, 0);
+                const direction_dot_product = v3_dot_array(ray_direction, 0, probe_direction, 0);
 
                 const weight = Math.pow(
                     max2(0,

package/src/engine/graphics/sh3/lpv/depth/octahedral/bake_octahedral_depth_map_fibonacci.js

@@ -10,7 +10,7 @@ import {
 import { Ray3 } from "../../../../../../core/geom/3d/ray/Ray3.js";
 import { sphere_fibonacci_point } from "../../../../../../core/geom/3d/sphere/sphere_fibonacci_point.js";
 import { v3_distance } from "../../../../../../core/geom/vec3/v3_distance.js";
-import { v3_dot_array_array } from "../../../../../../core/geom/vec3/v3_dot_array_array.js";
+import { v3_dot_array } from "../../../../../../core/geom/vec3/v3_dot_array.js";
 import { max2 } from "../../../../../../core/math/max2.js";
 
 /**
@@ -124,7 +124,7 @@ export function bake_octahedral_depth_map_fibonacci(
 
         }
 
-        const direction_dot_product = v3_dot_array_array(
+        const direction_dot_product = v3_dot_array(
             ray_direction, 0,
             probe_direction, 0
         );

package/src/engine/graphics/sh3/lpv/depth/sh3_bake_depth.js

@@ -2,7 +2,7 @@ import { array_copy } from "../../../../../core/collection/array/array_copy.js";
 import { Ray3 } from "../../../../../core/geom/3d/ray/Ray3.js";
 import { sh3_basis_at } from "../../../../../core/geom/3d/sphere/harmonics/sh3_basis_at.js";
 import { sh3_vector_accumulate } from "../../../../../core/geom/3d/sphere/harmonics/sh3_vector_accumulate.js";
-import { vector_scale_array } from "../../../../../core/geom/vec/vector_scale_array.js";
+import { vector_scale_offset } from "../../../../../core/geom/vec/vector_scale_offset.js";
 import { clamp01 } from "../../../../../core/math/clamp01.js";
 import { OctahedralUvEncoder } from "../../../impostors/octahedral/grid/OctahedralUvEncoder.js";
 
@@ -66,7 +66,7 @@ export function sh3_bake_depth(
     // Note that we do not scale the depth samples by sphere surface area as we are not attempting to approximate radiance
     const normalization_weight = 1 / resolution * resolution;
 
-    vector_scale_array(sh, 0, sh, 0, 27, normalization_weight);
+    vector_scale_offset(sh, 0, sh, 0, 27, normalization_weight);
 
     array_copy(sh, 0, result, result_offset, 9);
 }

package/src/engine/graphics/sh3/path_tracer/BufferedGeometryBVH.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BufferedGeometryBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/BufferedGeometryBVH.js"],"names":[],"mappings":"AAwCA;IAkBI;;;OAGG;IACH,eAFW,KAAK,GAAC,MAAM,EAAE,QAIxB;IAIG;;;;OAIG;IACH,mBAAsB;IAEtB;;;;OAIG;IACH,yBAA4B;IAE5B;;;;OAIG;IACH,6BAAgC;IAGhC;;;;OAIG;IACH,yBAAyB;IAG7B;;;OAGG;IACH,WAFW,MAAM,cAAc,QAgD9B;IAED;;;;;OAKG;IACH,qBAFa,OAAO,CAmHnB;IAED;;;;;;;OAOG;IACH,4BANW,aAAa,KACb,MAAM,KACN,MAAM,KACN,MAAM,GACJ,OAAO,CAUnB;IAGD;;;;;;OAMG;IACH,iBAJW,MAAM,EAAE,OACR,MAAM,EAAE,OAAK,GACX,MAAM,CAoIlB;IAED;;;;;OAKG;IACH,gBAJW,MAAM,EAAE,OACR,MAAM,EAAE,OAAK,GACX,MAAM,CA2ElB;;CACJ;sBAhfqB,wCAAwC;8BAGhC,2CAA2C"}
+{"version":3,"file":"BufferedGeometryBVH.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/BufferedGeometryBVH.js"],"names":[],"mappings":"AAsCA;IAkBI;;;OAGG;IACH,eAFW,KAAK,GAAC,MAAM,EAAE,QAIxB;IAIG;;;;OAIG;IACH,mBAAsB;IAEtB;;;;OAIG;IACH,yBAA4B;IAE5B;;;;OAIG;IACH,6BAAgC;IAGhC;;;;OAIG;IACH,yBAAyB;IAG7B;;;OAGG;IACH,WAFW,MAAM,cAAc,QAgD9B;IAED;;;;;OAKG;IACH,qBAFa,OAAO,CAoHnB;IAED;;;;;;;OAOG;IACH,4BANW,aAAa,KACb,MAAM,KACN,MAAM,KACN,MAAM,GACJ,OAAO,CAUnB;IAGD;;;;;;OAMG;IACH,iBAJW,MAAM,EAAE,OACR,MAAM,EAAE,OAAK,GACX,MAAM,CAoIlB;IAED;;;;;OAKG;IACH,gBAJW,MAAM,EAAE,OACR,MAAM,EAAE,OAAK,GACX,MAAM,CA2ElB;;CACJ;sBA/eqB,wCAAwC;8BAGhC,2CAA2C"}

package/src/engine/graphics/sh3/path_tracer/BufferedGeometryBVH.js

@@ -16,9 +16,7 @@ import { aabb3_from_v3_array } from "../../../../core/geom/3d/aabb/aabb3_from_v3
 import { aabb3_intersects_ray_segment } from "../../../../core/geom/3d/aabb/aabb3_intersects_ray_segment.js";
 import { SurfacePoint3 } from "../../../../core/geom/3d/SurfacePoint3.js";
 
-import {
-    computeTriangleRayIntersectionBarycentricGeometry
-} from "../../../../core/geom/3d/triangle/computeTriangleRayIntersectionBarycentricGeometry.js";
+import { tri3_ray_intersection_indexed } from "../../../../core/geom/3d/triangle/tri3_ray_intersection_indexed.js";
 import Vector4 from "../../../../core/geom/Vector4.js";
 import { makeGeometryIndexed } from "../../geometry/buffered/makeGeometryIndexed.js";
 import { query_bvh_geometry_nearest } from "../../geometry/buffered/query/query_bvh_geometry_nearest.js";
@@ -173,7 +171,8 @@ export class BufferedGeometryBVH {
         const root = bvh.root;
 
         if (root === NULL_NODE) {
-            return -1;
+            // empty geometry cannot occlude anything
+            return false;
         }
 
         /**
@@ -243,7 +242,7 @@ export class BufferedGeometryBVH {
 
                 const triangle_index = uint32[address + COLUMN_USER_DATA];
 
-                const intersection_found = computeTriangleRayIntersectionBarycentricGeometry(
+                const intersection_found = tri3_ray_intersection_indexed(
                     v3_scratch_0,
                     origin_x, origin_y, origin_z,
                     direction_x, direction_y, direction_z,
@@ -391,7 +390,7 @@ export class BufferedGeometryBVH {
 
                 const triangle_index = uint32[address + COLUMN_USER_DATA];
 
-                const intersection_found = computeTriangleRayIntersectionBarycentricGeometry(
+                const intersection_found = tri3_ray_intersection_indexed(
                     v3_scratch_0,
                     origin_x, origin_y, origin_z,
                     direction_x, direction_y, direction_z,
@@ -451,8 +450,8 @@ export class BufferedGeometryBVH {
         const bvh = this.#bvh;
 
         const count = bvh_query_user_data_ray_segment(
-            bvh, bvh.root,
             scratch_uint32_array, 0,
+            bvh, bvh.root,
             origin_x, origin_y, origin_z,
             direction_x, direction_y, direction_z,
             0, max_distance
@@ -474,7 +473,7 @@ export class BufferedGeometryBVH {
         for (let i = 0; i < count; i++) {
             const triangle_index = scratch_uint32_array[i];
 
-            const intersection_found = computeTriangleRayIntersectionBarycentricGeometry(
+            const intersection_found = tri3_ray_intersection_indexed(
                 v3_scratch_0,
                 origin_x, origin_y, origin_z,
                 direction_x, direction_y, direction_z,

package/src/engine/graphics/sh3/path_tracer/PathTracedMesh.d.ts

@@ -25,6 +25,7 @@ export class PathTracedMesh {
      */
     material: StandardMaterial | null;
     get transform_inverse(): Float32Array;
+    get normal_matrix(): Float32Array;
     build_tight_bounds(): void;
     update_bounds(): void;
     set transform(arg: Float32Array);

package/src/engine/graphics/sh3/path_tracer/PathTracedMesh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PathTracedMesh.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/PathTracedMesh.js"],"names":[],"mappings":"AAeA;IACI;;;OAGG;IACH,IAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,MAFU,KAAK,CAEI;IAEnB;;;OAGG;IACH,KAFU,sBAAoB,IAAI,CAEvB;IAGX;;;OAGG;IACH,UAFU,MAAM,cAAc,GAAC,IAAI,CAEnB;IAEhB;;;OAGG;IACH,UAFU,mBAAiB,IAAI,CAEf;IAKhB,sCAEC;IAED,2BAqBC;IAED,sBAGC;IAED,iCAQC;IAED,8BAEC;IAED;;;;OAIG;IACH,cAHW,IAAI,GACF,OAAO,CAWnB;IAED;;;;;;OAMG;IACH,SALW,MAAM,EAAE,OACR,MAAM,EAAE,GAAC,IAAI,aACb,MAAM,GACJ,MAAM,CA4BlB;;CACJ;sBAhJqB,wCAAwC;qBAIzC,sCAAsC"}
+{"version":3,"file":"PathTracedMesh.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/PathTracedMesh.js"],"names":[],"mappings":"AAgBA;IACI;;;OAGG;IACH,IAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,MAFU,KAAK,CAEI;IAEnB;;;OAGG;IACH,KAFU,sBAAoB,IAAI,CAEvB;IAGX;;;OAGG;IACH,UAFU,MAAM,cAAc,GAAC,IAAI,CAEnB;IAEhB;;;OAGG;IACH,UAFU,mBAAiB,IAAI,CAEf;IAYhB,sCAEC;IAED,kCAEC;IAED,2BAqBC;IAED,sBAGC;IAED,iCAUC;IAED,8BAEC;IAED;;;;OAIG;IACH,cAHW,IAAI,GACF,OAAO,CAWnB;IAED;;;;;;OAMG;IACH,SALW,MAAM,EAAE,OACR,MAAM,EAAE,GAAC,IAAI,aACb,MAAM,GACJ,MAAM,CA4BlB;;CACJ;sBA/JqB,wCAAwC;qBAMzC,sCAAsC"}

package/src/engine/graphics/sh3/path_tracer/PathTracedMesh.js

@@ -1,9 +1,10 @@
-import { mat4 } from "gl-matrix";
 import { array_copy } from "../../../../core/collection/array/array_copy.js";
 import { AABB3 } from "../../../../core/geom/3d/aabb/AABB3.js";
 import { aabb3_from_v3_array_transformed } from "../../../../core/geom/3d/aabb/aabb3_from_v3_array_transformed.js";
-import { allocate_m4 } from "../../../../core/geom/3d/mat4/allocate_m4.js";
-import { decompose_matrix_4_array } from "../../../../core/geom/3d/mat4/decompose_matrix_4_array.js";
+import { m4_allocate } from "../../../../core/geom/3d/mat4/m4_allocate.js";
+import { m4_decompose } from "../../../../core/geom/3d/mat4/m4_decompose.js";
+import { m4_normal_matrix3 } from "../../../../core/geom/3d/mat4/m4_normal_matrix3.js";
+import { m4_invert } from "../../../../core/geom/3d/mat4/m4_invert.js";
 import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
 import Quaternion from "../../../../core/geom/Quaternion.js";
 import { v3_distance } from "../../../../core/geom/vec3/v3_distance.js";
@@ -45,19 +46,30 @@ export class PathTracedMesh {
      */
     material = null;
 
-    #transform = allocate_m4();
-    #transform_inverse = allocate_m4();
+    #transform = m4_allocate();
+    #transform_inverse = m4_allocate();
+
+    /**
+     * Normal matrix (transpose-adjugate of the transform's 3x3) — transforms normals correctly
+     * under non-uniform scale. Produces non-unit vectors, so transformed normals must be re-normalized.
+     * @type {Float32Array}
+     */
+    #normal_matrix = new Float32Array(9);
 
     get transform_inverse() {
         return this.#transform_inverse;
     }
 
+    get normal_matrix() {
+        return this.#normal_matrix;
+    }
+
     build_tight_bounds() {
         const position = new Vector3();
         const rotation = new Quaternion();
         const scale = new Vector3();
 
-        decompose_matrix_4_array(this.#transform, position, rotation, scale);
+        m4_decompose(this.#transform, position, rotation, scale);
 
         if (rotation.roughlyEquals(Quaternion.identity)) {
             // no rotation component, can safely scale/translate geometry bounds to get tight fit
@@ -83,7 +95,9 @@ export class PathTracedMesh {
     set transform(m) {
         array_copy(m, 0, this.#transform, 0, 16);
 
-        mat4.invert(this.#transform_inverse, m);
+        m4_invert(this.#transform_inverse, m);
+
+        m4_normal_matrix3(this.#normal_matrix, this.#transform);
 
         if (this.bvh !== null) {
             this.update_bounds();
@@ -130,7 +144,7 @@ export class PathTracedMesh {
 
         if (distance_to_hit >= 0) {
             // transform output
-            ray_hit_apply_transform(out, out, this.#transform);
+            ray_hit_apply_transform(out, out, this.#transform, this.#normal_matrix);
 
             out[10] = this.id;
 

package/src/engine/graphics/sh3/path_tracer/PathTracedRenderer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Drives a {@link PathTracer} over a camera + scene, writing tone-mapped, sRGB-encoded bytes into a
+ * sampler. The render is exposed as a generator that yields once per pixel, so a caller can drive it
+ * incrementally (e.g. from a task scheduler) and spread the work across frames.
+ */
+export class PathTracedRenderer {
+    /**
+     *
+     * @param {PathTracer} [tracer]
+     */
+    constructor(tracer?: PathTracer);
+    /**
+     * @type {PathTracer}
+     */
+    tracer: PathTracer;
+    /**
+     * Number of primary rays traced per pixel.
+     * @type {number}
+     */
+    samples_per_pixel: number;
+    /**
+     * Bounce index at and beyond which russian-roulette path termination starts.
+     * @type {number}
+     */
+    min_bounce: number;
+    /**
+     * Maximum number of bounces along a path.
+     * @type {number}
+     */
+    max_bounce: number;
+    /**
+     * Edge length, in pixels, of the square tiles the image is rendered in. Tiling improves cache
+     * locality since nearby rays tend to hit the same geometry.
+     * @type {number}
+     */
+    tile_size: number;
+    /**
+     * Seed for the deterministic sampler, so a render is reproducible.
+     * @type {number}
+     */
+    seed: number;
+    /**
+     * Render the scene into the target sampler. Yields once per pixel so the caller can pump the
+     * generator incrementally.
+     *
+     * @param {Sampler2D} target output sampler (uint8 RGBA)
+     * @param {Camera} camera
+     * @param {PathTracedScene} scene
+     * @param {{current:number, total:number}} progress mutated in place as pixels complete
+     */
+    render(target: Sampler2D, camera: Camera, scene: PathTracedScene, progress?: {
+        current: number;
+        total: number;
+    }): Generator<any, void, unknown>;
+}
+import { PathTracer } from "./PathTracer.js";
+//# sourceMappingURL=PathTracedRenderer.d.ts.map

package/src/engine/graphics/sh3/path_tracer/PathTracedRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PathTracedRenderer.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/sh3/path_tracer/PathTracedRenderer.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH;IAEI;;;OAGG;IACH,qBAFW,UAAU,EAOpB;IAJG;;OAEG;IACH,QAFU,UAAU,CAEA;IAGxB;;;OAGG;IACH,mBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,MAFU,MAAM,CAEP;IAET;;;;;;;;OAQG;IACH,6EAFW;QAAC,OAAO,EAAC,MAAM,CAAC;QAAC,KAAK,EAAC,MAAM,CAAA;KAAC,iCAuHxC;CACJ;2BAlL0B,iBAAiB"}

package/src/engine/graphics/sh3/path_tracer/PathTracedRenderer.js

@@ -0,0 +1,186 @@
+import { float_to_uint8 } from "../../../../core/binary/float_to_uint8.js";
+import { linear_to_sRGB } from "../../../../core/color/sRGB/linear_to_sRGB.js";
+import { tonemap_aces } from "../../../../core/color/tonemap/tonemap_aces.js";
+import { Ray3 } from "../../../../core/geom/3d/ray/Ray3.js";
+import { min2 } from "../../../../core/math/min2.js";
+import { seededRandom } from "../../../../core/math/random/seededRandom.js";
+import { number_pretty_print } from "../../../../core/primitives/numbers/number_pretty_print.js";
+import { PathTracer } from "./PathTracer.js";
+
+/**
+ * Drives a {@link PathTracer} over a camera + scene, writing tone-mapped, sRGB-encoded bytes into a
+ * sampler. The render is exposed as a generator that yields once per pixel, so a caller can drive it
+ * incrementally (e.g. from a task scheduler) and spread the work across frames.
+ */
+export class PathTracedRenderer {
+
+    /**
+     *
+     * @param {PathTracer} [tracer]
+     */
+    constructor(tracer = new PathTracer()) {
+        /**
+         * @type {PathTracer}
+         */
+        this.tracer = tracer;
+    }
+
+    /**
+     * Number of primary rays traced per pixel.
+     * @type {number}
+     */
+    samples_per_pixel = 32;
+
+    /**
+     * Bounce index at and beyond which russian-roulette path termination starts.
+     * @type {number}
+     */
+    min_bounce = 1;
+
+    /**
+     * Maximum number of bounces along a path.
+     * @type {number}
+     */
+    max_bounce = 7;
+
+    /**
+     * Edge length, in pixels, of the square tiles the image is rendered in. Tiling improves cache
+     * locality since nearby rays tend to hit the same geometry.
+     * @type {number}
+     */
+    tile_size = 8;
+
+    /**
+     * Seed for the deterministic sampler, so a render is reproducible.
+     * @type {number}
+     */
+    seed = 0;
+
+    /**
+     * Render the scene into the target sampler. Yields once per pixel so the caller can pump the
+     * generator incrementally.
+     *
+     * @param {Sampler2D} target output sampler (uint8 RGBA)
+     * @param {Camera} camera
+     * @param {PathTracedScene} scene
+     * @param {{current:number, total:number}} progress mutated in place as pixels complete
+     */
+    * render(target, camera, scene, progress = { current: 0, total: 0 }) {
+
+        const tracer = this.tracer;
+        const samples_per_pixel = this.samples_per_pixel;
+        const min_bounce = this.min_bounce;
+        const max_bounce = this.max_bounce;
+        const tile_size = this.tile_size;
+
+        const random = seededRandom(this.seed);
+
+        // update camera
+        camera.updateProjectionMatrix();
+        camera.updateMatrixWorld(true);
+
+        //update world inverse matrix
+        camera.matrixWorldInverse.copy(camera.matrixWorld);
+        camera.matrixWorldInverse.invert();
+
+        const pixel_color = [];
+        const pixel_accummulation = [];
+        const ray = new Ray3();
+
+        const width = target.width;
+        const height = target.height;
+
+
+        const t0 = performance.now();
+        let sample_count = 0;
+
+        const pixel_scale_x = 1 / (width - 1);
+        const pixel_scale_y = 1 / (height - 1);
+
+        progress.total = width * height;
+
+        const max_y = height - 1;
+
+        const tile_count_x = width / tile_size;
+        const tile_count_y = height / tile_size;
+
+        // render in square tiles to get better memory exploitation, as rays are more likely to hit same things in smaller region
+        for (let tile_y = 0; tile_y < tile_count_y; tile_y++) {
+
+            const y0 = tile_y * tile_size;
+            const y1 = min2(height, y0 + tile_size);
+
+            for (let tile_x = 0; tile_x < tile_count_x; tile_x++) {
+
+                const x0 = tile_x * tile_size;
+                const x1 = min2(width, x0 + tile_size);
+
+                for (let y = y0; y < y1; y++) {
+
+                    const v = y * pixel_scale_y;
+                    const _y = v * 2 - 1;
+
+                    for (let x = x0; x < x1; x++) {
+
+                        const u = x * pixel_scale_x;
+                        const _x = u * 2 - 1;
+
+                        pixel_accummulation[0] = 0;
+                        pixel_accummulation[1] = 0;
+                        pixel_accummulation[2] = 0;
+
+                        const pixel_address = ((max_y - y) * width + x) * 4;
+
+                        const output_data = target.data;
+                        output_data[pixel_address + 3] = 255;
+
+                        for (let i = 0; i < samples_per_pixel; i++) {
+
+                            ray.projectFromPerspectiveCamera(
+                                _x + random() * pixel_scale_x * 2,
+                                _y + random() * pixel_scale_y * 2,
+                                0.5,
+                                camera.matrixWorld.elements,
+                                camera.projectionMatrixInverse.elements
+                            );
+
+                            ray.tMax = Infinity;
+                            tracer.path_trace(pixel_color, ray, min_bounce, max_bounce, random, scene);
+
+                            pixel_accummulation[0] += pixel_color[0];
+                            pixel_accummulation[1] += pixel_color[1];
+                            pixel_accummulation[2] += pixel_color[2];
+
+
+                            sample_count++;
+                        }
+
+                        pixel_accummulation[0] /= samples_per_pixel
+                        pixel_accummulation[1] /= samples_per_pixel
+                        pixel_accummulation[2] /= samples_per_pixel
+
+                        // tone map HDR radiance into [0,1] (linear sRGB primaries) before the sRGB OETF
+                        tonemap_aces(pixel_accummulation, 0, pixel_accummulation, 0);
+
+                        linear_to_sRGB(pixel_accummulation, 0, pixel_accummulation, 0);
+
+                        output_data[pixel_address] = float_to_uint8(pixel_accummulation[0]);
+                        output_data[pixel_address + 1] = float_to_uint8(pixel_accummulation[1]);
+                        output_data[pixel_address + 2] = float_to_uint8(pixel_accummulation[2]);
+
+
+                        progress.current++;
+
+                        yield;
+                    }
+                }
+            }
+
+        }
+
+        const total_time = performance.now() - t0;
+
+        console.log(`Trace finished in ${number_pretty_print(total_time)}ms. Total of ${number_pretty_print(sample_count)} samples, ${number_pretty_print(sample_count * 1000 / total_time)} samples per second`);
+
+    }
+}