@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/renderer/light/GPULightCollection.js

@@ -1,314 +1,323 @@
-import { assert } from "../../../core/assert.js";
-import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
-import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
-import { GPUSceneShadowmapContext } from "../shadow/map/GPUSceneShadowmapContext.js";
-import { GPUTextureContext } from "../texture/GPUTextureContext.js";
-import { compute_max_mip_count } from "../../util/compute_max_mip_count.js";
-import { texture_write_to_gpu } from "../texture/texture_write_to_gpu.js";
-import { execute_filter_environment_map } from "./environment/execute_filter_environment_map.js";
-import { LIGHT_DATABASE_SPEC } from "./LIGHT_DATABASE_SPEC.js";
-import { light_record_directional } from "./model/io/light_record_directional.js";
-import { light_record_point } from "./model/io/light_record_point.js";
-import { light_record_spot } from "./model/io/light_record_spot.js";
-
-/**
- * Directional-light cap. Sized so the directional occupancy bitmap
- * fits in a single u32, which is what
- * {@link chunk_directional_lights_iteration_mask} reads. Writing past
- * key 31 would silently drop the light from iteration; {@link #build}
- * warns once per build when this happens.
- *
- * Point and spot lights have no analogous cap — their consumers walk
- * the full per-page bitmap, so any number of point/spot lights
- * iterate correctly (e.g. clustered rendering routinely deals in
- * hundreds).
- *
- * @type {number}
- */
-const MAX_DIRECTIONAL_LIGHTS = 32;
-
-export class GPULightCollection {
-
-    /**
-     * @type {LightCollection}
-     */
-    #source
-
-    /**
-     *
-     * @returns {LightCollection}
-     */
-    get source() {
-        return this.#source;
-    }
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device
-
-    /**
-     * Backing GPUDatabase for the per-type light tables (point, spot, directional)
-     * and shadowmap regions. Layout is defined by {@link LIGHT_DATABASE_SPEC}.
-     *
-     * @type {GPUDatabase}
-     */
-    #database;
-
-    /**
-     * @returns {GPUDatabase}
-     */
-    get database() {
-        return this.#database;
-    }
-
-    /**
-     * The single GPU buffer that backs the database. Bind this as `array<u32>` in
-     * shaders that need to read light records via the auto-generated
-     * {@link GPUTypedTableDescriptor.chunk_read} helpers.
-     *
-     * @returns {GPUBuffer}
-     */
-    get buffer_data() {
-        return this.#database.buffer;
-    }
-
-    /**
-     * Per-scene shadow allocator + rasterizer, owned by this collection because the
-     * shadow records live in the same database (shadow_point / shadow_spot /
-     * shadow_directional tables) and the per-light `shadow_id` field is the index into
-     * those tables. Lifecycle, update, and destruction are all chained off this object.
-     * @type {GPUSceneShadowmapContext}
-     */
-    #shadow_context;
-
-    /**
-     * @returns {GPUSceneShadowmapContext}
-     */
-    get shadow_context() {
-        return this.#shadow_context;
-    }
-
-    /**
-     *
-     * @type {number}
-     */
-    #committed_version = -1;
-
-    /**
-     * Per-type counts written in the previous {@link build} pass. Used to identify
-     * the trailing slot range that must be removed to keep each table tightly packed.
-     */
-    #prev_point_count = 0;
-    #prev_spot_count = 0;
-    #prev_directional_count = 0;
-
-    /**
-     * Octahedral encoded texture, convolved
-     * see {@link LightCollection.environment}
-     * @type {GPUTextureContext}
-     */
-    #environment;
-
-    /**
-     * @type {ShadeTexture}
-     */
-    #environment_source;
-
-
-    /**
-     *
-     * @returns {GPUTextureContext}
-     */
-    get environment() {
-        return this.#environment;
-    }
-
-
-    get gpu_memory_usage() {
-        return this.#environment.gpu_memory_usage
-            + this.#database.gpu_memory_usage
-            ;
-    }
-
-    /**
-     *
-     * @param {GraphicsContext} graphics
-     * @param {GPUSceneContext} scene_ctx the GPU-side context for this scene; the shadow
-     *        context constructs its own ViewManager that needs to look up this same context
-     *        when materializing GPUViewContexts for shadow views.
-     */
-    constructor(graphics, scene_ctx) {
-        assert.defined(graphics, 'graphics');
-        assert.defined(scene_ctx, 'scene_ctx');
-        assert.equal(scene_ctx.isGPUSceneContext, true, 'scene_ctx.isGPUSceneContext !== true');
-
-        const scene = scene_ctx.scene;
-        const device = graphics.device;
-
-        this.#device = device;
-        this.#source = scene.lights;
-
-        this.#environment = new GPUTextureContext(this.#device);
-        this.#environment.descriptor.label = "environment map";
-        this.#environment.descriptor.format = "rgba16float";
-        this.#environment.descriptor.usage |=
-            GPUTextureUsage.COPY_DST // so we can write to it
-            | GPUTextureUsage.STORAGE_BINDING // so we can convolve it in compute shader
-        ;
-
-        this.#database = new GPUDatabase({
-            device,
-            label: 'Light Collection / Database',
-            definition: LIGHT_DATABASE_SPEC,
-        });
-
-        this.#shadow_context = new GPUSceneShadowmapContext(graphics, scene_ctx, this);
-    }
-
-    /**
-     *
-     * @param {GraphicsContext} ctx
-     */
-    #update_environment(ctx) {
-        const source_env = this.#source.environment;
-
-        if (this.#environment_source === source_env) {
-            // assume up-to-date
-            return;
-        }
-
-        this.#environment_source = source_env;
-
-        const gpu_ctx = this.#environment;
-
-        const source_image = source_env.image;
-        gpu_ctx.resize(source_image.width, source_image.height);
-        gpu_ctx.descriptor.mipLevelCount = compute_max_mip_count(source_image.width, source_image.height);
-
-        gpu_ctx.allocate();
-
-        if (
-            source_image.source instanceof ImageBitmap
-            && (gpu_ctx.descriptor.usage & GPUTextureUsage.RENDER_ATTACHMENT) === 0
-        ) {
-            // need RENDER_ATTACHMENT to use GPUQueue.copyExternalImageToTexture API
-            // update descriptor and re-allocate texture
-            gpu_ctx.descriptor.usage |= GPUTextureUsage.RENDER_ATTACHMENT;
-            gpu_ctx.allocate(false);
-        }
-
-        texture_write_to_gpu(source_image, gpu_ctx.gpu_texture, this.#device.queue);
-
-        // convolve
-        const cmd = ShadeGPUCommandContext.create(ctx);
-
-        execute_filter_environment_map(gpu_ctx, cmd);
-
-        cmd.finish();
-    }
-
-    /**
-     *
-     * @param {GraphicsContext} ctx
-     */
-    update(ctx) {
-        assert.defined(ctx, 'ctx');
-
-        this.#update_environment(ctx);
-
-        // Reconcile shadow allocations against the current scene every frame, even when
-        // {@link LightCollection.version} hasn't moved. Shadow allocations can shift on
-        // changes that don't bump version (e.g. flipping `light.casts_shadow`), and the
-        // `shadow_id` we stamp into each light record depends on this allocation. When
-        // process_lights touches anything we mark the source dirty so the build below
-        // re-publishes those records.
-        if (this.#shadow_context.process_lights()) {
-            this.#source.needsUpdate = true;
-        }
-
-        if (this.#committed_version === this.#source.version) {
-            return;
-        }
-
-        const cmd = ShadeGPUCommandContext.create(ctx, 'GPULightCollection/build');
-
-        this.#build(cmd);
-
-        cmd.finish();
-    }
-
-    /**
-     * Marshal source lights into the per-type database tables, keeping each table
-     * tightly packed in the index range [0, type_count).
-     *
-     * @param {ShadeGPUCommandContext} cmd
-     */
-    #build(cmd) {
-        const lights = this.#source.elements;
-
-        const table_point = this.#database.get('light_point');
-        const table_spot = this.#database.get('light_spot');
-        const table_directional = this.#database.get('light_directional');
-
-        let point_count = 0;
-        let spot_count = 0;
-        let directional_count = 0;
-
-        // Directional only — silently dropping a directional light
-        // would surface as a missing visual; flagging keeps consumers
-        // iterating only the first bitmap word correct for whatever
-        // did fit. Point and spot have no cap.
-        let directional_overflow_warned = false;
-
-        for (let i = 0; i < lights.length; i++) {
-            const light = lights[i];
-
-            if (light.isPointLight === true) {
-                table_point.set(point_count, light_record_point(light));
-                point_count++;
-            } else if (light.isDirectionalLight === true) {
-                if (directional_count >= MAX_DIRECTIONAL_LIGHTS) {
-                    if (!directional_overflow_warned) {
-                        console.warn(
-                            `GPULightCollection: directional light count exceeds MAX_DIRECTIONAL_LIGHTS (${MAX_DIRECTIONAL_LIGHTS}); extras will not be written to the database.`
-                        );
-                        directional_overflow_warned = true;
-                    }
-                    continue;
-                }
-                table_directional.set(directional_count, light_record_directional(light));
-                directional_count++;
-            } else if (light.isSpotLight === true) {
-                table_spot.set(spot_count, light_record_spot(light));
-                spot_count++;
-            }
-            // unrecognized light kinds are silently dropped
-        }
-
-        // trim trailing slots from previous build to keep each table tightly packed
-        for (let i = point_count; i < this.#prev_point_count; i++) {
-            table_point.remove(i);
-        }
-        for (let i = spot_count; i < this.#prev_spot_count; i++) {
-            table_spot.remove(i);
-        }
-        for (let i = directional_count; i < this.#prev_directional_count; i++) {
-            table_directional.remove(i);
-        }
-
-        this.#prev_point_count = point_count;
-        this.#prev_spot_count = spot_count;
-        this.#prev_directional_count = directional_count;
-
-        this.#database.update(cmd);
-
-        this.#committed_version = this.#source.version;
-    }
-
-    destroy() {
-        this.#shadow_context.destroy();
-        this.#database.destroy();
-        this.#environment.destroy();
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
+import { GPUDatabase } from "../buffer/table/GPUDatabase.js";
+import { GPUSceneShadowmapContext } from "../shadow/map/GPUSceneShadowmapContext.js";
+import { GPUTextureContext } from "../texture/GPUTextureContext.js";
+import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
+import { texture_write_to_gpu } from "../texture/texture_write_to_gpu.js";
+import { execute_filter_environment_map } from "./environment/execute_filter_environment_map.js";
+import { LIGHT_DATABASE_SPEC } from "./LIGHT_DATABASE_SPEC.js";
+import { light_record_directional } from "./model/io/light_record_directional.js";
+import { light_record_point } from "./model/io/light_record_point.js";
+import { light_record_spot } from "./model/io/light_record_spot.js";
+
+/**
+ * Directional-light cap. Sized so the directional occupancy bitmap
+ * fits in a single u32, which is what
+ * {@link chunk_directional_lights_iteration_mask} reads. Writing past
+ * key 31 would silently drop the light from iteration; {@link #build}
+ * warns once per build when this happens.
+ *
+ * Point and spot lights have no analogous cap — their consumers walk
+ * the full per-page bitmap, so any number of point/spot lights
+ * iterate correctly (e.g. clustered rendering routinely deals in
+ * hundreds).
+ *
+ * @type {number}
+ */
+const MAX_DIRECTIONAL_LIGHTS = 32;
+
+export class GPULightCollection {
+
+    /**
+     * @type {LightCollection}
+     */
+    #source
+
+    /**
+     *
+     * @returns {LightCollection}
+     */
+    get source() {
+        return this.#source;
+    }
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device
+
+    /**
+     * Backing GPUDatabase for the per-type light tables (point, spot, directional)
+     * and shadowmap regions. Layout is defined by {@link LIGHT_DATABASE_SPEC}.
+     *
+     * @type {GPUDatabase}
+     */
+    #database;
+
+    /**
+     * @returns {GPUDatabase}
+     */
+    get database() {
+        return this.#database;
+    }
+
+    /**
+     * The single GPU buffer that backs the database. Bind this as `array<u32>` in
+     * shaders that need to read light records via the auto-generated
+     * {@link GPUTypedTableDescriptor.chunk_read} helpers.
+     *
+     * @returns {GPUBuffer}
+     */
+    get buffer_data() {
+        return this.#database.buffer;
+    }
+
+    /**
+     * Per-scene shadow allocator + rasterizer, owned by this collection because the
+     * shadow records live in the same database (shadow_point / shadow_spot /
+     * shadow_directional tables) and the per-light `shadow_id` field is the index into
+     * those tables. Lifecycle, update, and destruction are all chained off this object.
+     * @type {GPUSceneShadowmapContext}
+     */
+    #shadow_context;
+
+    /**
+     * @returns {GPUSceneShadowmapContext}
+     */
+    get shadow_context() {
+        return this.#shadow_context;
+    }
+
+    /**
+     *
+     * @type {number}
+     */
+    #committed_version = -1;
+
+    /**
+     * Per-type counts written in the previous {@link build} pass. Used to identify
+     * the trailing slot range that must be removed to keep each table tightly packed.
+     */
+    #prev_point_count = 0;
+    #prev_spot_count = 0;
+    #prev_directional_count = 0;
+
+    /**
+     * Octahedral encoded texture, convolved
+     * see {@link LightCollection.environment}
+     * @type {GPUTextureContext}
+     */
+    #environment;
+
+    /**
+     * @type {ShadeTexture}
+     */
+    #environment_source;
+
+
+    /**
+     *
+     * @returns {GPUTextureContext}
+     */
+    get environment() {
+        return this.#environment;
+    }
+
+
+    get gpu_memory_usage() {
+        return this.#environment.gpu_memory_usage
+            + this.#database.gpu_memory_usage
+            ;
+    }
+
+    /**
+     *
+     * @param {GraphicsContext} graphics
+     * @param {GPUSceneContext} scene_ctx the GPU-side context for this scene; the shadow
+     *        context constructs its own ViewManager that needs to look up this same context
+     *        when materializing GPUViewContexts for shadow views.
+     */
+    constructor(graphics, scene_ctx) {
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene_ctx, 'scene_ctx');
+        assert.equal(scene_ctx.isGPUSceneContext, true, 'scene_ctx.isGPUSceneContext !== true');
+
+        const scene = scene_ctx.scene;
+        const device = graphics.device;
+
+        this.#device = device;
+        this.#source = scene.lights;
+
+        this.#environment = new GPUTextureContext(this.#device);
+        this.#environment.descriptor.label = "environment map";
+        this.#environment.descriptor.format = "rgba16float";
+        this.#environment.descriptor.usage |=
+            GPUTextureUsage.COPY_DST // so we can write to it
+            | GPUTextureUsage.STORAGE_BINDING // so we can convolve it in compute shader
+        ;
+
+        this.#database = new GPUDatabase({
+            device,
+            label: 'Light Collection / Database',
+            definition: LIGHT_DATABASE_SPEC,
+        });
+
+        this.#shadow_context = new GPUSceneShadowmapContext(graphics, scene_ctx, this);
+    }
+
+    /**
+     *
+     * @param {GraphicsContext} ctx
+     */
+    #update_environment(ctx) {
+        const source_env = this.#source.environment;
+
+        if (this.#environment_source === source_env) {
+            // assume up-to-date
+            return;
+        }
+
+        this.#environment_source = source_env;
+
+        const gpu_ctx = this.#environment;
+
+        const source_image = source_env.image;
+        gpu_ctx.resize(source_image.width, source_image.height);
+        /*
+         The environment map is equirectangular and this context is built 2D a few lines up — the
+         descriptor keeps the default dimension and `resize` above only takes two axes. Asked of the
+         descriptor rather than assumed, so the count follows if that ever stops being true.
+        */
+        const gpu_size = gpu_ctx.descriptor.size;
+
+        gpu_ctx.descriptor.mipLevelCount = texture_mip_level_count(
+            gpu_size.width, gpu_size.height, gpu_size.depthOrArrayLayers, gpu_ctx.descriptor.dimension
+        );
+
+        gpu_ctx.allocate();
+
+        if (
+            source_image.source instanceof ImageBitmap
+            && (gpu_ctx.descriptor.usage & GPUTextureUsage.RENDER_ATTACHMENT) === 0
+        ) {
+            // need RENDER_ATTACHMENT to use GPUQueue.copyExternalImageToTexture API
+            // update descriptor and re-allocate texture
+            gpu_ctx.descriptor.usage |= GPUTextureUsage.RENDER_ATTACHMENT;
+            gpu_ctx.allocate(false);
+        }
+
+        texture_write_to_gpu(source_image, gpu_ctx.gpu_texture, this.#device.queue, source_image.level_count);
+
+        // convolve
+        const cmd = ShadeGPUCommandContext.create(ctx);
+
+        execute_filter_environment_map(gpu_ctx, cmd);
+
+        cmd.finish();
+    }
+
+    /**
+     *
+     * @param {GraphicsContext} ctx
+     */
+    update(ctx) {
+        assert.defined(ctx, 'ctx');
+
+        this.#update_environment(ctx);
+
+        // Reconcile shadow allocations against the current scene every frame, even when
+        // {@link LightCollection.version} hasn't moved. Shadow allocations can shift on
+        // changes that don't bump version (e.g. flipping `light.casts_shadow`), and the
+        // `shadow_id` we stamp into each light record depends on this allocation. When
+        // process_lights touches anything we mark the source dirty so the build below
+        // re-publishes those records.
+        if (this.#shadow_context.process_lights()) {
+            this.#source.needsUpdate = true;
+        }
+
+        if (this.#committed_version === this.#source.version) {
+            return;
+        }
+
+        const cmd = ShadeGPUCommandContext.create(ctx, 'GPULightCollection/build');
+
+        this.#build(cmd);
+
+        cmd.finish();
+    }
+
+    /**
+     * Marshal source lights into the per-type database tables, keeping each table
+     * tightly packed in the index range [0, type_count).
+     *
+     * @param {ShadeGPUCommandContext} cmd
+     */
+    #build(cmd) {
+        const lights = this.#source.elements;
+
+        const table_point = this.#database.get('light_point');
+        const table_spot = this.#database.get('light_spot');
+        const table_directional = this.#database.get('light_directional');
+
+        let point_count = 0;
+        let spot_count = 0;
+        let directional_count = 0;
+
+        // Directional only — silently dropping a directional light
+        // would surface as a missing visual; flagging keeps consumers
+        // iterating only the first bitmap word correct for whatever
+        // did fit. Point and spot have no cap.
+        let directional_overflow_warned = false;
+
+        for (let i = 0; i < lights.length; i++) {
+            const light = lights[i];
+
+            if (light.isPointLight === true) {
+                table_point.set(point_count, light_record_point(light));
+                point_count++;
+            } else if (light.isDirectionalLight === true) {
+                if (directional_count >= MAX_DIRECTIONAL_LIGHTS) {
+                    if (!directional_overflow_warned) {
+                        console.warn(
+                            `GPULightCollection: directional light count exceeds MAX_DIRECTIONAL_LIGHTS (${MAX_DIRECTIONAL_LIGHTS}); extras will not be written to the database.`
+                        );
+                        directional_overflow_warned = true;
+                    }
+                    continue;
+                }
+                table_directional.set(directional_count, light_record_directional(light));
+                directional_count++;
+            } else if (light.isSpotLight === true) {
+                table_spot.set(spot_count, light_record_spot(light));
+                spot_count++;
+            }
+            // unrecognized light kinds are silently dropped
+        }
+
+        // trim trailing slots from previous build to keep each table tightly packed
+        for (let i = point_count; i < this.#prev_point_count; i++) {
+            table_point.remove(i);
+        }
+        for (let i = spot_count; i < this.#prev_spot_count; i++) {
+            table_spot.remove(i);
+        }
+        for (let i = directional_count; i < this.#prev_directional_count; i++) {
+            table_directional.remove(i);
+        }
+
+        this.#prev_point_count = point_count;
+        this.#prev_spot_count = spot_count;
+        this.#prev_directional_count = directional_count;
+
+        this.#database.update(cmd);
+
+        this.#committed_version = this.#source.version;
+    }
+
+    destroy() {
+        this.#shadow_context.destroy();
+        this.#database.destroy();
+        this.#environment.destroy();
+    }
+}