@woosh/meep-engine 2.165.7 → 2.167.0

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

@@ -1,1232 +1,1235 @@
-import { m4_multiply } from "../../../../core/geom/3d/mat4/m4_multiply.js";
-import {
-    ClampToEdgeWrapping,
-    DataTexture,
-    DataTexture3D,
-    Frustum,
-    LinearFilter,
-    LinearMipMapLinearFilter,
-    NearestFilter,
-    RGBAFormat,
-    RGBAIntegerFormat,
-    UnsignedByteType,
-    UnsignedShortType
-} from "three";
-import { assert } from "../../../../core/assert.js";
-import { computeBinaryDataTypeByPrecision } from "../../../../core/binary/type/computeBinaryDataTypeByPrecision.js";
-import {
-    DataType2TypedArrayConstructorMapping
-} from "../../../../core/binary/type/DataType2TypedArrayConstructorMapping.js";
-import { BinaryUint32BVH } from "../../../../core/bvh2/binary/2/BinaryUint32BVH.js";
-import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
-import {
-    bvh_query_user_data_intersects_frustum
-} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_frustum.js";
-import { array_copy } from "../../../../core/collection/array/array_copy.js";
-import { array_sort_quick } from "../../../../core/collection/array/array_sort_quick.js";
-import { array_swap_one } from "../../../../core/collection/array/array_swap_one.js";
-import { frustum3_planes_to_flat_from_three } from "../../../../core/geom/3d/frustum/frustum3_planes_to_flat_from_three.js";
-import { frustum3_slice_linear_to_points } from "../../../../core/geom/3d/frustum/frustum3_slice_linear_to_points.js";
-import { v3_morton_encode_transformed } from "../../../../core/geom/3d/morton/v3_morton_encode_transformed.js";
-import { v3_distance } from "../../../../core/geom/vec3/v3_distance.js";
-import Vector3 from "../../../../core/geom/Vector3.js";
-import { NumericType } from "../../../../core/math/NumericType.js";
-import { frustum_from_camera } from "../../ecs/camera/frustum_from_camera.js";
-import { CachingTextureAtlas } from "../../texture/atlas/CachingTextureAtlas.js";
-import { ReferencedTextureAtlas } from "../../texture/atlas/ReferencedTextureAtlas.js";
-import { TextureAtlas } from "../../texture/atlas/TextureAtlas.js";
-import {
-    computeThreeTextureInternalFormatFromDataType
-} from "../../texture/computeThreeTextureInternalFormatFromDataType.js";
-import { computeThreeTextureTypeFromDataType } from "../../texture/computeThreeTextureTypeFromDataType.js";
-import { writeSample2DDataToDataTexture } from "../../texture/sampler/writeSampler2DDataToDataTexture.js";
-import { TextureBackedMemoryRegion } from "../../texture/TextureBackedMemoryRegion.js";
-import { IncrementalDeltaSet } from "../visibility/IncrementalDeltaSet.js";
-import { assign_cluster, LOOKUP_CACHE, scratch_corners, scratch_frustum_planes } from "./assign_cluster.js";
-import { compute_cluster_planes_from_points } from "./cluster/compute_cluster_planes_from_points.js";
-import { read_plane_pair } from "./cluster/read_plane_pair.js";
-import { computeFrustumCorners } from "./computeFrustumCorners.js";
-import { LightRenderMetadata } from "./LightRenderMetadata.js";
-import { Decal } from "./model/Decal.js";
-import { point_light_inside_volume } from "./query/point_light_inside_volume.js";
-
-
-/**
- * How many bits are used to encode light type
- * @type {number}
- */
-const LIGHT_ENCODING_TYPE_BIT_COUNT = 2;
-
-/**
- *
- * @param {AbstractLight|PointLight|Decal} light
- * @returns {number}
- */
-function encode_light_type(light) {
-    if (light.isPointLight === true) {
-        return 0;
-    } else if (light.isDecal === true) {
-        return 3;
-    } else {
-        throw new Error('Unsupported light type');
-    }
-}
-
-/**
- *
- * @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);
-}
-
-/**
- *
- * @param {IncrementalDeltaSet<LightRenderMetadata>} data_set
- * @param {BinaryUint32BVH} bvh
- */
-function build_light_data_bvh(data_set, bvh) {
-    const elements = data_set.elements;
-    const element_count = data_set.size;
-
-    bvh.setLeafCount(element_count);
-    bvh.initialize_structure();
-
-    for (let i = 0; i < element_count; i++) {
-
-        /**
-         *
-         * @type {LightRenderMetadata}
-         */
-        const datum = elements[i];
-
-        const bb = datum.bvh_leaf.bounds;
-
-        const payload = encode_light_descriptor(datum.address, datum.light);
-
-        bvh.setLeafData(
-            i, payload,
-            bb[0], bb[1], bb[2],
-            bb[3], bb[4], bb[5],
-        );
-    }
-
-    // vbvh.sort_morton(this.__projection_matrix);
-    // vbvh.sort_bubble_sah();
-
-    bvh.build();
-}
-
-/**
- *
- * @param {LightRenderMetadata} a
- * @param {LightRenderMetadata} b
- * @returns {number}
- */
-function compareLRMByLightId(a, b) {
-    return b.light.id - a.light.id;
-}
-
-export class LightManager {
-
-    /**
-     * @readonly
-     * @type {BVH}
-     */
-    #light_data_bvh = new BVH();
-
-    /**
-     * Mapping from a light/decal object ID internal metadata
-     * @type {Map<number,LightRenderMetadata>}
-     */
-    #metadata_map = new Map();
-
-
-    constructor() {
-
-        /**
-         * Number of cluster slices along each dimension
-         * @type {Vector3}
-         * @private
-         */
-        this.__tiles_resolution = new Vector3(32, 16, 8);
-
-        this.__cluster_texture_precision = 8;
-        this.__cluster_texture_needs_rebuild = false;
-
-        /**
-         * Texel layout:
-         *  - R: offset into lookup texture for lights
-         *  - G: light count
-         *  - B: offset into lookup texture for decals
-         *  - A: decal count
-         * @type {DataTexture3D}
-         * @private
-         */
-        this.__cluster_texture = new DataTexture3D(
-            new Uint16Array(4),
-            1,
-            1,
-            1,
-        );
-
-        this.__cluster_texture.flipY = false;
-        this.__cluster_texture.generateMipmaps = false;
-        this.__cluster_texture.unpackAlignment = 2;
-
-        this.__cluster_texture.magFilter = NearestFilter;
-        this.__cluster_texture.minFilter = NearestFilter;
-
-        this.__cluster_texture.type = UnsignedShortType;
-        this.__cluster_texture.format = RGBAIntegerFormat;
-        this.__cluster_texture.internalFormat = "RGBA16UI";
-
-        /**
-         *
-         * @type {TextureBackedMemoryRegion}
-         * @readonly
-         * @private
-         */
-        this.__lookup_data = new TextureBackedMemoryRegion();
-        this.__lookup_data.type = NumericType.Uint;
-        this.__lookup_data.channel_count = 1;
-        this.__lookup_data.precision = 8;
-        this.__lookup_data.resize(1);
-
-        /**
-         *
-         * @type {TextureBackedMemoryRegion}
-         * @readonly
-         * @private
-         */
-        this.__light_data = new TextureBackedMemoryRegion();
-        this.__light_data.type = NumericType.Float;
-        this.__light_data.precision = 32;
-        this.__light_data.channel_count = 4;
-        this.__light_data.resize(8);
-
-        /**
-         * @type {DataTexture}
-         * @readonly
-         * @private
-         */
-        this.__decal_atlas_texture = new DataTexture(new Uint8Array(4), 1, 1, RGBAFormat);
-        this.__decal_atlas_texture.type = UnsignedByteType;
-        this.__decal_atlas_texture.flipY = false;
-        this.__decal_atlas_texture.wrapS = ClampToEdgeWrapping;
-        this.__decal_atlas_texture.wrapT = ClampToEdgeWrapping;
-        this.__decal_atlas_texture.minFilter = LinearMipMapLinearFilter;
-        this.__decal_atlas_texture.magFilter = LinearFilter;
-        this.__decal_atlas_texture.generateMipmaps = true;
-        this.__decal_atlas_texture.unpackAlignment = 4;
-        this.__decal_atlas_texture.anisotropy = 8;
-
-        /**
-         *
-         * @type {AbstractTextureAtlas}
-         * @readonly
-         * @private
-         */
-        this.__decal_atlas = new CachingTextureAtlas({
-            atlas: new TextureAtlas(512)
-        });
-
-        /**
-         *
-         * @type {ReferencedTextureAtlas}
-         * @private
-         */
-        this.__decal_patch_references = new ReferencedTextureAtlas(this.__decal_atlas);
-
-        /**
-         *
-         * @type {Map<Decal, Reference<AtlasPatch>>}
-         * @private
-         */
-        this.__decal_references = new Map();
-
-        /**
-         *
-         * @type {IncrementalDeltaSet<LightRenderMetadata>}
-         * @readonly
-         * @private
-         */
-        this.__visible_lights = new IncrementalDeltaSet(compareLRMByLightId);
-        /**
-         *
-         * @type {IncrementalDeltaSet<LightRenderMetadata>}
-         * @readonly
-         * @private
-         */
-        this.__visible_decals = new IncrementalDeltaSet(compareLRMByLightId);
-
-        /**
-         *
-         * @type {LightRenderMetadata[]}
-         * @private
-         */
-        this.__sorted_visible_lights = [];
-
-        /**
-         *
-         * @type {BinaryUint32BVH}
-         * @private
-         */
-        this.__visible_bvh_lights = new BinaryUint32BVH();
-        /**
-         *
-         * @type {BinaryUint32BVH}
-         * @private
-         */
-        this.__visible_bvh_decals = new BinaryUint32BVH();
-
-        /**
-         *
-         * @type {Frustum}
-         * @private
-         */
-        this.__view_frustum = new Frustum();
-
-        /**
-         * Corner points of the view frustum
-         * @type {Float32Array}
-         * @private
-         */
-        this.__view_frustum_points = new Float32Array(24);
-
-        /**
-         *
-         * @type {Float32Array|mat4|number[]}
-         * @private
-         */
-        this.__projection_matrix = new Float32Array(16);
-
-
-        /**
-         * Accelerated data structure with pre-computed plane normals for clusters in each dimensions. Order: X, Y, Z
-         * @type {Float32Array}
-         * @private
-         */
-        this.__cluster_planes = new Float32Array(1);
-
-        /**
-         * Accelerated data structure with pre-computed corner coordinates of each cluster's frustum
-         * @type {Float32Array}
-         * @private
-         */
-        this.__cluster_frustum_points = new Float32Array(1);
-
-        this.setTileMapResolution(32, 16, 16);
-
-        this.__visible_lights.onAdded.add(this.__handle_visible_light_added, this);
-        this.__visible_lights.onRemoved.add(this.__handle_visible_light_removed, this);
-
-        this.__visible_decals.onAdded.add(this.__handle_visible_decal_added, this);
-        this.__visible_decals.onRemoved.add(this.__handle_visible_decal_removed, this);
-
-        /**
-         * Data needs to be re-written into the data texture
-         * Usually set when source lights change
-         * @type {boolean}
-         * @private
-         */
-        this.__light_data_needs_update = true;
-
-        /**
-         *
-         * @type {boolean}
-         * @private
-         */
-        this.__visible_bvh_needs_update = true;
-
-        // window.light_manager = this; // DEBUG
-    }
-
-    requestDataUpdate() {
-        this.__light_data_needs_update = true;
-    }
-
-    /**
-     * Please set this to false if you have a lot of overlapping decals in the scene
-     * Overlapping decals can provide filtering artifacts due to incorrect mipmap level detection by WebGL
-     * see article: https://0fps.net/2013/07/09/texture-atlases-wrapping-and-mip-mapping/
-     * NOTE: the technique mentioned in the article above is not implemented, as it would require significant increase in number of texture fetches
-     * @param {boolean} v
-     */
-    set decal_filtering_enabled(v) {
-        const t = this.__decal_atlas_texture;
-
-        if (t.generateMipmaps === v) {
-            return;
-        }
-
-        t.generateMipmaps = v;
-    }
-
-    /**
-     *
-     * @return {boolean}
-     */
-    get decal_filtering_enabled() {
-        return this.__decal_atlas_texture.generateMipmaps;
-    }
-
-    __update_decal_atlas_texture() {
-        const sampler = this.__decal_atlas.sampler;
-
-        if (sampler.version !== this.__decal_atlas_texture.version) {
-            writeSample2DDataToDataTexture(sampler, this.__decal_atlas_texture);
-
-            this.__decal_atlas_texture.version = sampler.version;
-        }
-    }
-
-    /**
-     * Sometimes light lookup table can get quite large, to make sure we can store these addresses in the cluster texture,
-     * we may need to switch to a larger data type, such as Uint8->Uint16 or Uint16->Uint32
-     * @param {number} bit_count How many bits should be addressable from the cluster content
-     * @returns {boolean} true if texture was rebuilt (underlying type change), false otherwise
-     * @private
-     */
-    __set_cluster_addressable_bit_range(bit_count) {
-        const rounded_value = Math.ceil(bit_count);
-
-        this.__cluster_texture_precision = rounded_value;
-        const dataType = computeBinaryDataTypeByPrecision(NumericType.Uint, rounded_value);
-
-        const threeTextureType = computeThreeTextureTypeFromDataType(dataType);
-
-        const texture = this.__cluster_texture;
-        if (threeTextureType !== texture.type) {
-            this.__cluster_texture_needs_rebuild = true;
-
-            return true;
-        } else {
-            return false;
-        }
-    }
-
-    __update_cluster_texture() {
-        if (this.__cluster_texture_needs_rebuild) {
-            this.__build_cluster_texture();
-        }
-    }
-
-    __build_cluster_texture() {
-        const dataType = computeBinaryDataTypeByPrecision(NumericType.Uint, this.__cluster_texture_precision);
-
-        const threeTextureType = computeThreeTextureTypeFromDataType(dataType);
-
-        const texture = this.__cluster_texture;
-
-        const channelCount = 4;
-
-        texture.dispose();
-
-        const image = texture.image;
-
-        const resolution = this.__tiles_resolution;
-
-        image.width = resolution.x;
-        image.height = resolution.y;
-        image.depth = resolution.z;
-
-        texture.type = threeTextureType;
-        texture.internalFormat = computeThreeTextureInternalFormatFromDataType(dataType, channelCount);
-
-        const ArrayConstructor = DataType2TypedArrayConstructorMapping[dataType];
-
-        image.data = new ArrayConstructor(resolution.x * resolution.y * resolution.z * channelCount);
-
-        texture.needsUpdate = true;
-
-        this.__cluster_texture_needs_rebuild = false;
-    }
-
-    /**
-     *
-     * @param {number} size
-     * @returns {boolean}
-     * @private
-     */
-    __ensure_lookup_size(size) {
-        return this.__lookup_data.resize(size);
-    }
-
-    /**
-     *
-     * @returns {DataTexture}
-     */
-    getTextureLookup() {
-        return this.__lookup_data.getTexture();
-    }
-
-    /**
-     *
-     * @returns {DataTexture}
-     */
-    getTextureData() {
-        return this.__light_data.getTexture();
-    }
-
-    /**
-     * @returns {DataTexture3D}
-     */
-    getTextureClusters() {
-        return this.__cluster_texture;
-    }
-
-    /**
-     * @returns {DataTexture}
-     */
-    getTextureDecalAtlas() {
-        return this.__decal_atlas_texture;
-    }
-
-    /**
-     * NOTE: do not modify the value
-     * @returns {Readonly<Vector3>}
-     */
-    getResolution() {
-        return this.__tiles_resolution;
-    }
-
-    /**
-     *
-     * @private
-     */
-    __handle_light_dimensions_change() {
-        // internal BVH needs to be rebuilt
-        this.__visible_bvh_needs_update = true;
-        // when dimensions change, typically data will need to be re-written to the GPU, things like light positions or projection matrix
-        this.__light_data_needs_update = true;
-    }
-
-    /**
-     *
-     * @private
-     */
-    __handle_light_appearance_change() {
-        // appearance changes (such as color or intensity) don't affect bounds, only the encoded data
-        this.__light_data_needs_update = true;
-    }
-
-    /**
-     *
-     * @param {LightRenderMetadata} data
-     * @private
-     */
-    __handle_visible_decal_added(data) {
-        this.__light_data_needs_update = true;
-
-        /**
-         *
-         * @type {Decal}
-         */
-        const light = data.light;
-
-        light.onDimensionChanged(this.__handle_light_dimensions_change, this);
-
-        const ref = this.__decal_patch_references.acquire(light.texture_diffuse);
-
-        const patch = ref.getValue();
-        const patch_uv = patch.uv;
-
-        patch_uv.position.onChanged.add(light.handleUvPositionChange, light);
-        patch_uv.size.onChanged.add(light.handleUvSizeChange, light);
-
-        light.uv[0] = patch_uv.position.x;
-        light.uv[1] = patch_uv.position.y;
-        light.uv[2] = patch_uv.size.x;
-        light.uv[3] = patch_uv.size.y;
-
-        this.__decal_references.set(light, ref);
-    }
-
-    /**
-     *
-     * @param {LightRenderMetadata} data
-     * @private
-     */
-    __handle_visible_decal_removed(data) {
-        this.__light_data_needs_update = true;
-
-        /**
-         *
-         * @type {Decal}
-         */
-        const light = data.light;
-
-        light.offDimensionChanged(this.__handle_light_dimensions_change, this);
-
-        const ref = this.__decal_references.get(light);
-
-        if (ref === undefined) {
-            // This can occur when decal changes while being in the visible list, messing with the IncrementalDeltaSet's compare order
-            console.warn(`Decal reference not found: ${light}`);
-            return;
-        }
-
-        const patch = ref.getValue();
-        const patch_uv = patch.uv;
-
-        // unsubscribe
-        patch_uv.position.onChanged.remove(light.handleUvPositionChange, light);
-        patch_uv.size.onChanged.remove(light.handleUvSizeChange, light);
-
-
-        ref.release();
-
-        this.__decal_references.delete(light);
-    }
-
-    /**
-     *
-     * @param {LightRenderMetadata} data
-     * @private
-     */
-    __handle_visible_light_added(data) {
-        this.__light_data_needs_update = true;
-
-        const light = data.light;
-
-        light.onDimensionChanged(this.__handle_light_dimensions_change, this);
-        light.onAppearanceChanged(this.__handle_light_appearance_change, this);
-    }
-
-    /**
-     *
-     * @param {LightRenderMetadata} data
-     * @private
-     */
-    __handle_visible_light_removed(data) {
-        this.__light_data_needs_update = true;
-
-        const light = data.light;
-        light.offDimensionChanged(this.__handle_light_dimensions_change, this);
-        light.offAppearanceChanged(this.__handle_light_appearance_change, this);
-    }
-
-    /**
-     *
-     * @param {LightRenderMetadata} light
-     * @returns {number}
-     * @protected
-     */
-    __sort_visible_light_score(light) {
-        const center = scratch_corners;
-
-        light.light.getCenter(center)
-
-        const x = center[0];
-        const y = center[1];
-        const z = center[2];
-
-        return v3_morton_encode_transformed(x, y, z, this.__projection_matrix);
-    }
-
-    /**
-     * DEBUG method
-     * @param {LightRenderMetadata} lights
-     * @param {number} count
-     * @returns {number} lower = better sorting score
-     * @private
-     */
-    __assess_sorting_score(lights, count) {
-
-        let r = 0;
-
-        const center_a = [];
-        const center_b = [];
-
-        for (let i = 0; i < count; i++) {
-            const a = lights[i];
-
-            const score_a = this.__sort_visible_light_score(a);
-            a.light.getCenter(center_a);
-
-            for (let j = i + 1; j < count; j++) {
-                const b = lights[j];
-
-                const score_b = this.__sort_visible_light_score(b);
-                b.light.getCenter(center_b);
-
-                //
-                const score_distance = Math.abs(score_a - score_b);
-                const position_distance = v3_distance(
-                    center_a[0], center_a[1], center_a[2],
-                    center_b[0], center_b[1], center_b[2],
-                );
-
-                r += score_distance / position_distance;
-            }
-        }
-
-
-        return r / (count * (count - 1) * 0.5);
-    }
-
-    /**
-     * Sort lights for better data locality
-     * @private
-     */
-    __sort_visible_light() {
-        const sorted_lights = this.__sorted_visible_lights;
-
-        const visible_light_set = this.__visible_lights;
-        const visible_light_count = visible_light_set.size;
-
-        const visible_decal_set = this.__visible_decals;
-        const visible_decal_count = visible_decal_set.size;
-
-        const expected_sorted_size = visible_light_count + visible_decal_count;
-
-        if (expected_sorted_size > visible_light_count) {
-            // crop array if it's too big
-            sorted_lights.splice(visible_light_count, expected_sorted_size - visible_light_count)
-        }
-
-        array_copy(visible_light_set.elements, 0, sorted_lights, 0, visible_light_count);
-        array_copy(visible_decal_set.elements, 0, sorted_lights, visible_light_count, visible_decal_count);
-
-        array_sort_quick(sorted_lights, this.__sort_visible_light_score, this, 0, expected_sorted_size - 1);
-    }
-
-    __update_visible_bvh() {
-        this.__visible_bvh_needs_update = false;
-
-        build_light_data_bvh(
-            this.__visible_lights,
-            this.__visible_bvh_lights
-        );
-
-        build_light_data_bvh(
-            this.__visible_decals,
-            this.__visible_bvh_decals
-        );
-    }
-
-
-    /**
-     *
-     * @param {Camera} camera
-     * @private
-     */
-    __build_view_frustum(camera) {
-        frustum_from_camera(camera, this.__view_frustum, false);
-
-        array_swap_one(this.__view_frustum.planes, 4, 5);
-
-        this.__build_view_frustum_points();
-    }
-
-    __build_visible_light_list() {
-
-        /**
-         *
-         * @type {IncrementalDeltaSet<LightRenderMetadata>}
-         */
-        const visible_lights = this.__visible_lights;
-
-        visible_lights.initializeUpdate();
-
-        const visible_decals = this.__visible_decals;
-
-        visible_decals.initializeUpdate();
-
-        const nodes = [];
-
-        frustum3_planes_to_flat_from_three(this.__view_frustum.planes, scratch_frustum_planes)
-
-        /*
-        Search is done in 2 phases:
-        1) broad phase using bounding boxes
-        2) granular phase where we use object-specific shape to check against frustum
-         */
-
-        const broad_match_count = bvh_query_user_data_intersects_frustum(nodes, 0, this.#light_data_bvh, scratch_frustum_planes);
-
-        for (let i = 0; i < broad_match_count; i++) {
-
-            const light_id = nodes[i];
-
-            /**
-             *
-             * @type {LightRenderMetadata}
-             */
-            const light_data = this.#metadata_map.get(light_id);
-
-            /**
-             *
-             * @type {PointLight|Decal}
-             */
-            const light = light_data.light;
-
-            if (light.isDecal === true) {
-
-
-                // decals go into a separate bucket
-                visible_decals.push(light_data);
-
-            } else if (light.isPointLight === true) {
-                // perform granular check
-
-                const light_position = light.position;
-
-                const light_x = light_position.x;
-                const light_y = light_position.y;
-                const light_z = light_position.z;
-
-                const radius = light.radius.getValue();
-
-                if (!point_light_inside_volume(light_x, light_y, light_z, radius, scratch_frustum_planes)) {
-                    // outside of view frustum
-                    continue;
-                }
-
-
-                // register as visible
-                visible_lights.push(light_data);
-            }
-
-        }
-
-        visible_lights.finalizeUpdate();
-
-        visible_decals.finalizeUpdate();
-    }
-
-    __write_light_data_texture() {
-
-        /**
-         *
-         * @type {LightRenderMetadata[]}
-         */
-        const visible_lights = this.__sorted_visible_lights;
-
-        // write light data into texture
-        const visible_light_count = visible_lights.length;
-
-        // compute amount of space required for the lights
-        let address = 0;
-        for (let i = 0; i < visible_light_count; i++) {
-            const datum = visible_lights[i];
-
-            /**
-             *
-             * @type {PointLight}
-             */
-            const light = datum.light;
-
-            address += light.ENCODED_SLOT_COUNT;
-        }
-
-        const expected_light_data_size = address;
-
-
-        const light_data = this.__light_data;
-        light_data.resize(Math.ceil(address / 4));
-
-        light_data.update();
-
-        // update required lookup precision
-        this.__lookup_data.precision = Math.max(
-            0,
-            Math.ceil(Math.log2(light_data.size))
-        ) + LIGHT_ENCODING_TYPE_BIT_COUNT;
-
-        const tx_light = light_data.getTexture();
-
-        /**
-         *
-         * @type {Float32Array}
-         */
-        const tx_light_data = tx_light.image.data;
-
-        address = 0;
-
-        for (let i = 0; i < visible_light_count; i++) {
-            const datum = visible_lights[i];
-
-            assert.lessThan(address, tx_light_data.length, "overflow");
-
-            /**
-             *
-             * @type {PointLight}
-             */
-            const light = datum.light;
-
-            datum.address = address >> 2;
-
-            const written_slots = light.toArray(tx_light_data, address);
-
-            address += written_slots;
-
-            // align address to 4 slot boundary
-            if ((address & 3) !== 0) {
-                // not on 4 slot boundary
-                address = ((address >> 2) + 1) << 2;
-            }
-        }
-
-        if (address !== expected_light_data_size) {
-            throw new Error(`Expected light data size is ${expected_light_data_size}, actual written data is size is ${address}`);
-        }
-
-        tx_light.needsUpdate = true;
-
-        this.__visible_bvh_needs_update = true;
-    }
-
-    /**
-     * Perform cluster assignment where each cluster is filled with overlapping lights
-     * @private
-     */
-    __assign_lights_to_clusters() {
-
-        const tiles_resolution = this.__tiles_resolution;
-
-        const tr_z = tiles_resolution.z;
-        const tr_y = tiles_resolution.y;
-        const tr_x = tiles_resolution.x;
-
-        const tr_x_1 = tr_x + 1;
-        const tr_y_1 = tr_y + 1;
-
-        const tr_xy_1 = tr_x_1 * tr_y_1;
-
-        /**
-         *
-         * @type {Float32Array}
-         */
-        const cluster_planes = this.__cluster_planes;
-
-        const bvh_lights = this.__visible_bvh_lights;
-        const bvh_decals = this.__visible_bvh_decals;
-
-
-        const cluster_planes_x_offset = 0;
-        const cluster_planes_y_offset = tr_x_1 * 4;
-        const cluster_planes_z_offset = cluster_planes_y_offset + tr_y_1 * 4;
-
-        /**
-         *
-         * @type {number[]|Float32Array}
-         */
-        const light_source_data = this.__light_data.getTexture().image.data;
-
-        const tile_slice_size = tr_x * tr_y;
-
-        const light_cluster_texture = this.__cluster_texture;
-        const tile_texture_data = light_cluster_texture.image.data;
-
-        const light_lookup = this.__lookup_data;
-        light_lookup.update();
-        const light_lookup_texture = light_lookup.getTexture();
-        const light_lookup_texture_data = light_lookup_texture.image.data;
-
-        let lookup_address_offset = 0;
-        let i_x_0, i_y_0, i_z_0;
-
-        // clear cache
-        LOOKUP_CACHE.fill(0xFFFFFFFF);
-
-        // console.log('Assignment Start');
-
-        for (i_z_0 = 0; i_z_0 < tr_z; i_z_0++) {
-
-            // construct z planes
-
-            const slice_offset = i_z_0 * tile_slice_size;
-
-            const z_plane_index_offset_0 = cluster_planes_z_offset + i_z_0 * 4;
-
-            read_plane_pair(cluster_planes, z_plane_index_offset_0, scratch_frustum_planes, 16);
-
-            for (i_y_0 = 0; i_y_0 < tr_y; i_y_0++) {
-
-                // construct y planes
-
-                const y_plane_index_offset_0 = cluster_planes_y_offset + i_y_0 * 4;
-
-                read_plane_pair(cluster_planes, y_plane_index_offset_0, scratch_frustum_planes, 8);
-
-                for (i_x_0 = 0; i_x_0 < tr_x; i_x_0++) {
-
-                    // construct x planes
-
-                    const x_plane_index_offset_0 = cluster_planes_x_offset + i_x_0 * 4;
-
-                    read_plane_pair(cluster_planes, x_plane_index_offset_0, scratch_frustum_planes, 0);
-
-                    const tile_index = slice_offset + (i_y_0 * tr_x) + i_x_0;
-
-                    const tile_data_offset = tile_index * 4;
-
-                    //assign lights
-                    lookup_address_offset += assign_cluster(
-                        tile_data_offset,
-                        bvh_lights,
-                        lookup_address_offset,
-                        light_lookup_texture_data,
-                        tile_texture_data,
-                        light_source_data
-                    );
-
-                    // assign decals
-                    const decal_count = assign_cluster(
-                        tile_data_offset + 2,
-                        bvh_decals,
-                        lookup_address_offset,
-                        light_lookup_texture_data,
-                        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;
-                }
-            }
-        }
-
-        light_cluster_texture.needsUpdate = true;
-        light_lookup_texture.needsUpdate = true;
-
-        // Post-fact lookup texture resize, this frame will be wrong, but next one should be ok
-        const current_lookup_size = this.__lookup_data.size;
-
-        const lookup_memory_resized = this.__ensure_lookup_size(lookup_address_offset);
-
-        const cluster_resized = this.__set_cluster_addressable_bit_range(Math.max(0, Math.log2(lookup_address_offset)));
-
-        if (
-            (lookup_memory_resized && current_lookup_size < lookup_address_offset)
-            || cluster_resized
-        ) {
-            // overflow, we ended up trying to write more lights into some clusters than what they could contain
-            this.__update_cluster_texture();
-
-            // re-do assignment
-            this.__assign_lights_to_clusters();
-        }
-
-        // console.log('Unique assignment count: ', assignment_count, ', Hash reuse:', hash_reuse_count);
-    }
-
-    /**
-     *
-     * @private
-     */
-    __build_cluster_frustum_planes() {
-        const tiles_resolution = this.__tiles_resolution;
-
-        const tr_z = tiles_resolution.z;
-        const tr_y = tiles_resolution.y;
-        const tr_x = tiles_resolution.x;
-
-        const destination = this.__cluster_planes;
-
-        compute_cluster_planes_from_points(destination, this.__cluster_frustum_points, tr_x, tr_y, tr_z);
-    }
-
-    /**
-     *
-     * @private
-     */
-    __build_view_frustum_points() {
-
-        const view_frustum = this.__view_frustum;
-
-        const points = this.__view_frustum_points;
-
-        computeFrustumCorners(points, view_frustum.planes);
-    }
-
-    /**
-     *
-     * @private
-     */
-    __build_cluster_frustum_points() {
-        const tiles_resolution = this.__tiles_resolution;
-
-        const tr_z = tiles_resolution.z;
-        const tr_y = tiles_resolution.y;
-        const tr_x = tiles_resolution.x;
-
-        const view_frustum_points = this.__view_frustum_points;
-        const points_data = this.__cluster_frustum_points;
-
-        frustum3_slice_linear_to_points(view_frustum_points, tr_x, tr_y, tr_z, points_data);
-    }
-
-    /**
-     * Build light tile texture
-     * @param {Camera|THREE.PerspectiveCamera} camera
-     */
-    buildTiles(camera) {
-        // camera.updateProjectionMatrix();
-        // camera.updateMatrix();
-        // camera.updateMatrixWorld(true);
-
-        //update world inverse matrix
-        camera.matrixWorldInverse.copy(camera.matrixWorld);
-        camera.matrixWorldInverse.invert();
-
-        // this.__projection_matrix.set(camera.matrixWorldInverse.elements);
-        m4_multiply(this.__projection_matrix, camera.projectionMatrix.elements, camera.matrixWorldInverse.elements);
-
-        // console.time('__build_view_frustum');
-        this.__build_view_frustum(camera);
-        // console.timeEnd('__build_view_frustum');
-
-
-        // console.time('__build_visible_light_list');
-        this.__build_visible_light_list();
-        // console.timeEnd('__build_visible_light_list');
-
-        // update decal atlas
-        this.__decal_atlas.update();
-        this.__update_decal_atlas_texture();
-
-        // console.time('__write_light_data_texture');
-        if (this.__light_data_needs_update) {
-            // sort light for better search and query locality
-            this.__sort_visible_light();
-
-            this.__write_light_data_texture();
-
-            // clear flag
-            this.__light_data_needs_update = false;
-        }
-        // console.timeEnd('__write_light_data_texture');
-
-        if (this.__visible_bvh_needs_update) {
-            this.__update_visible_bvh();
-        }
-
-        this.__build_cluster_frustum_points();
-        // console.time('__build_cluster_frustum_planes');
-        this.__build_cluster_frustum_planes();
-        // console.timeEnd('__build_cluster_frustum_planes');
-
-        // console.time('__assign_lights_to_clusters');
-        this.__assign_lights_to_clusters();
-        // console.timeEnd('__assign_lights_to_clusters');
-    }
-
-    dispose() {
-        this.__cluster_texture.dispose();
-        this.__light_data.dispose();
-        this.__lookup_data.dispose();
-        this.__decal_atlas_texture.dispose();
-    }
-
-    /**
-     * 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.isFinite(x, 'x');
-        assert.greaterThan(x, 0, 'x must be > 0');
-
-        assert.isNumber(y, 'y');
-        assert.isNonNegativeInteger(y, 'y');
-        assert.isFinite(y, 'y');
-        assert.greaterThan(y, 0, 'y must be > 0');
-
-        assert.isNumber(z, 'z');
-        assert.isNonNegativeInteger(z, 'z');
-        assert.isFinite(z, 'z');
-        assert.greaterThan(z, 0, 'z must be > 0');
-
-        const r = this.__tiles_resolution;
-
-        if (x === r.x && y === r.y && z === r.z) {
-            // special case, no change
-            return;
-        }
-
-        r.set(x, y, z);
-
-        this.__cluster_texture_needs_rebuild = true;
-        this.__update_cluster_texture();
-
-        const cluster_planes_size = ((x + 1) + (y + 1) + (z + 1)) * 4;
-        const cluster_frustum_points_size = (x + 1) * (y + 1) * (z + 1) * 3;
-
-        const buffer = new ArrayBuffer((cluster_planes_size + cluster_frustum_points_size) * 4);
-
-        this.__cluster_planes = new Float32Array(
-            buffer, 0,
-            cluster_planes_size
-        );
-        this.__cluster_frustum_points = new Float32Array(
-            buffer, cluster_planes_size * 4,
-            cluster_frustum_points_size
-        );
-    }
-
-    /**
-     *
-     * @param {AbstractLight} light
-     * @returns {boolean}
-     */
-    hasLight(light) {
-        return this.#metadata_map.has(light.id);
-    }
-
-    /**
-     *
-     * @param {AbstractLight} light
-     */
-    addLight(light) {
-        const lightData = new LightRenderMetadata(light);
-
-        lightData.link(this.#light_data_bvh);
-
-        this.#metadata_map.set(light.id, lightData);
-    }
-
-    /**
-     *
-     * @param {AbstractLight} light
-     * @returns {boolean}
-     */
-    removeLight(light) {
-
-        const light_id = light.id;
-
-        const data = this.#metadata_map.get(light_id);
-
-        if (data === undefined) {
-            return false;
-        }
-
-        data.unlink();
-
-        this.#metadata_map.delete(light_id);
-
-        return true;
-    }
-}
+import { m4_multiply } from "../../../../core/geom/3d/mat4/m4_multiply.js";
+import {
+    ClampToEdgeWrapping,
+    DataTexture,
+    DataTexture3D,
+    Frustum,
+    LinearFilter,
+    LinearMipMapLinearFilter,
+    NearestFilter,
+    RGBAFormat,
+    RGBAIntegerFormat,
+    UnsignedByteType,
+    UnsignedShortType
+} from "three";
+import { assert } from "../../../../core/assert.js";
+import { computeBinaryDataTypeByPrecision } from "../../../../core/binary/type/computeBinaryDataTypeByPrecision.js";
+import {
+    DataType2TypedArrayConstructorMapping
+} from "../../../../core/binary/type/DataType2TypedArrayConstructorMapping.js";
+import { BinaryUint32BVH } from "../../../../core/bvh2/binary/2/BinaryUint32BVH.js";
+import { BVH } from "../../../../core/bvh2/bvh3/BVH.js";
+import {
+    bvh_query_user_data_intersects_frustum
+} from "../../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_frustum.js";
+import { array_copy } from "../../../../core/collection/array/array_copy.js";
+import { array_sort_quick } from "../../../../core/collection/array/array_sort_quick.js";
+import { array_swap_one } from "../../../../core/collection/array/array_swap_one.js";
+import { frustum3_planes_to_flat_from_three } from "../../../../core/geom/3d/frustum/frustum3_planes_to_flat_from_three.js";
+import { frustum3_slice_linear_to_points } from "../../../../core/geom/3d/frustum/frustum3_slice_linear_to_points.js";
+import { v3_morton_encode_transformed } from "../../../../core/geom/3d/morton/v3_morton_encode_transformed.js";
+import { v3_distance } from "../../../../core/geom/vec3/v3_distance.js";
+import Vector3 from "../../../../core/geom/Vector3.js";
+import { NumericType } from "../../../../core/math/NumericType.js";
+import { frustum_from_camera } from "../../ecs/camera/frustum_from_camera.js";
+import { CachingTextureAtlas } from "../../texture/atlas/CachingTextureAtlas.js";
+import { ReferencedTextureAtlas } from "../../texture/atlas/ReferencedTextureAtlas.js";
+import { TextureAtlas } from "../../texture/atlas/TextureAtlas.js";
+import {
+    computeThreeTextureInternalFormatFromDataType
+} from "../../texture/computeThreeTextureInternalFormatFromDataType.js";
+import { computeThreeTextureTypeFromDataType } from "../../texture/computeThreeTextureTypeFromDataType.js";
+import { writeSample2DDataToDataTexture } from "../../texture/sampler/writeSampler2DDataToDataTexture.js";
+import { TextureBackedMemoryRegion } from "../../texture/TextureBackedMemoryRegion.js";
+import { IncrementalDeltaSet } from "../visibility/IncrementalDeltaSet.js";
+import { assign_cluster, LOOKUP_CACHE, scratch_corners, scratch_frustum_planes } from "./assign_cluster.js";
+import { compute_cluster_planes_from_points } from "./cluster/compute_cluster_planes_from_points.js";
+import { read_plane_pair } from "./cluster/read_plane_pair.js";
+import { computeFrustumCorners } from "./computeFrustumCorners.js";
+import { LightRenderMetadata } from "./LightRenderMetadata.js";
+import { Decal } from "./model/Decal.js";
+import { point_light_inside_volume } from "./query/point_light_inside_volume.js";
+
+
+/**
+ * How many bits are used to encode light type
+ * @type {number}
+ */
+const LIGHT_ENCODING_TYPE_BIT_COUNT = 2;
+
+/**
+ *
+ * @param {AbstractLight|PointLight|Decal} light
+ * @returns {number}
+ */
+function encode_light_type(light) {
+    if (light.isPointLight === true) {
+        return 0;
+    } else if (light.isDecal === true) {
+        return 3;
+    } else {
+        throw new Error('Unsupported light type');
+    }
+}
+
+/**
+ *
+ * @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);
+}
+
+/**
+ *
+ * @param {IncrementalDeltaSet<LightRenderMetadata>} data_set
+ * @param {BinaryUint32BVH} bvh
+ */
+function build_light_data_bvh(data_set, bvh) {
+    const elements = data_set.elements;
+    const element_count = data_set.size;
+
+    bvh.setLeafCount(element_count);
+    bvh.initialize_structure();
+
+    for (let i = 0; i < element_count; i++) {
+
+        /**
+         *
+         * @type {LightRenderMetadata}
+         */
+        const datum = elements[i];
+
+        const bb = datum.bvh_leaf.bounds;
+
+        const payload = encode_light_descriptor(datum.address, datum.light);
+
+        bvh.setLeafData(
+            i, payload,
+            bb[0], bb[1], bb[2],
+            bb[3], bb[4], bb[5],
+        );
+    }
+
+    // vbvh.sort_morton(this.__projection_matrix);
+    // vbvh.sort_bubble_sah();
+
+    bvh.build();
+}
+
+/**
+ *
+ * @param {LightRenderMetadata} a
+ * @param {LightRenderMetadata} b
+ * @returns {number}
+ */
+function compareLRMByLightId(a, b) {
+    return b.light.id - a.light.id;
+}
+
+export class LightManager {
+
+    /**
+     * @readonly
+     * @type {BVH}
+     */
+    #light_data_bvh = new BVH();
+
+    /**
+     * Mapping from a light/decal object ID internal metadata
+     * @type {Map<number,LightRenderMetadata>}
+     */
+    #metadata_map = new Map();
+
+
+    constructor() {
+
+        /**
+         * Number of cluster slices along each dimension
+         * @type {Vector3}
+         * @private
+         */
+        this.__tiles_resolution = new Vector3(32, 16, 8);
+
+        this.__cluster_texture_precision = 8;
+        this.__cluster_texture_needs_rebuild = false;
+
+        /**
+         * Texel layout:
+         *  - R: offset into lookup texture for lights
+         *  - G: light count
+         *  - B: offset into lookup texture for decals
+         *  - A: decal count
+         * @type {DataTexture3D}
+         * @private
+         */
+        this.__cluster_texture = new DataTexture3D(
+            new Uint16Array(4),
+            1,
+            1,
+            1,
+        );
+
+        this.__cluster_texture.flipY = false;
+        this.__cluster_texture.generateMipmaps = false;
+        this.__cluster_texture.unpackAlignment = 2;
+
+        this.__cluster_texture.magFilter = NearestFilter;
+        this.__cluster_texture.minFilter = NearestFilter;
+
+        this.__cluster_texture.type = UnsignedShortType;
+        this.__cluster_texture.format = RGBAIntegerFormat;
+        this.__cluster_texture.internalFormat = "RGBA16UI";
+
+        /**
+         *
+         * @type {TextureBackedMemoryRegion}
+         * @readonly
+         * @private
+         */
+        this.__lookup_data = new TextureBackedMemoryRegion();
+        this.__lookup_data.type = NumericType.Uint;
+        this.__lookup_data.channel_count = 1;
+        this.__lookup_data.precision = 8;
+        this.__lookup_data.resize(1);
+
+        /**
+         *
+         * @type {TextureBackedMemoryRegion}
+         * @readonly
+         * @private
+         */
+        this.__light_data = new TextureBackedMemoryRegion();
+        this.__light_data.type = NumericType.Float;
+        this.__light_data.precision = 32;
+        this.__light_data.channel_count = 4;
+        this.__light_data.resize(8);
+
+        /**
+         * @type {DataTexture}
+         * @readonly
+         * @private
+         */
+        this.__decal_atlas_texture = new DataTexture(new Uint8Array(4), 1, 1, RGBAFormat);
+        this.__decal_atlas_texture.type = UnsignedByteType;
+        this.__decal_atlas_texture.flipY = false;
+        this.__decal_atlas_texture.wrapS = ClampToEdgeWrapping;
+        this.__decal_atlas_texture.wrapT = ClampToEdgeWrapping;
+        this.__decal_atlas_texture.minFilter = LinearMipMapLinearFilter;
+        this.__decal_atlas_texture.magFilter = LinearFilter;
+        this.__decal_atlas_texture.generateMipmaps = true;
+        this.__decal_atlas_texture.unpackAlignment = 4;
+        this.__decal_atlas_texture.anisotropy = 8;
+
+        /**
+         *
+         * @type {AbstractTextureAtlas}
+         * @readonly
+         * @private
+         */
+        this.__decal_atlas = new CachingTextureAtlas({
+            atlas: new TextureAtlas(512)
+        });
+
+        /**
+         *
+         * @type {ReferencedTextureAtlas}
+         * @private
+         */
+        this.__decal_patch_references = new ReferencedTextureAtlas(this.__decal_atlas);
+
+        /**
+         *
+         * @type {Map<Decal, Reference<AtlasPatch>>}
+         * @private
+         */
+        this.__decal_references = new Map();
+
+        /**
+         *
+         * @type {IncrementalDeltaSet<LightRenderMetadata>}
+         * @readonly
+         * @private
+         */
+        this.__visible_lights = new IncrementalDeltaSet(compareLRMByLightId);
+        /**
+         *
+         * @type {IncrementalDeltaSet<LightRenderMetadata>}
+         * @readonly
+         * @private
+         */
+        this.__visible_decals = new IncrementalDeltaSet(compareLRMByLightId);
+
+        /**
+         *
+         * @type {LightRenderMetadata[]}
+         * @private
+         */
+        this.__sorted_visible_lights = [];
+
+        /**
+         *
+         * @type {BinaryUint32BVH}
+         * @private
+         */
+        this.__visible_bvh_lights = new BinaryUint32BVH();
+        /**
+         *
+         * @type {BinaryUint32BVH}
+         * @private
+         */
+        this.__visible_bvh_decals = new BinaryUint32BVH();
+
+        /**
+         *
+         * @type {Frustum}
+         * @private
+         */
+        this.__view_frustum = new Frustum();
+
+        /**
+         * Corner points of the view frustum
+         * @type {Float32Array}
+         * @private
+         */
+        this.__view_frustum_points = new Float32Array(24);
+
+        /**
+         *
+         * @type {Float32Array|mat4|number[]}
+         * @private
+         */
+        this.__projection_matrix = new Float32Array(16);
+
+
+        /**
+         * Accelerated data structure with pre-computed plane normals for clusters in each dimensions. Order: X, Y, Z
+         * @type {Float32Array}
+         * @private
+         */
+        this.__cluster_planes = new Float32Array(1);
+
+        /**
+         * Accelerated data structure with pre-computed corner coordinates of each cluster's frustum
+         * @type {Float32Array}
+         * @private
+         */
+        this.__cluster_frustum_points = new Float32Array(1);
+
+        this.setTileMapResolution(32, 16, 16);
+
+        this.__visible_lights.onAdded.add(this.__handle_visible_light_added, this);
+        this.__visible_lights.onRemoved.add(this.__handle_visible_light_removed, this);
+
+        this.__visible_decals.onAdded.add(this.__handle_visible_decal_added, this);
+        this.__visible_decals.onRemoved.add(this.__handle_visible_decal_removed, this);
+
+        /**
+         * Data needs to be re-written into the data texture
+         * Usually set when source lights change
+         * @type {boolean}
+         * @private
+         */
+        this.__light_data_needs_update = true;
+
+        /**
+         *
+         * @type {boolean}
+         * @private
+         */
+        this.__visible_bvh_needs_update = true;
+
+        // window.light_manager = this; // DEBUG
+    }
+
+    requestDataUpdate() {
+        this.__light_data_needs_update = true;
+    }
+
+    /**
+     * Please set this to false if you have a lot of overlapping decals in the scene
+     * Overlapping decals can provide filtering artifacts due to incorrect mipmap level detection by WebGL
+     * see article: https://0fps.net/2013/07/09/texture-atlases-wrapping-and-mip-mapping/
+     * NOTE: the technique mentioned in the article above is not implemented, as it would require significant increase in number of texture fetches
+     * @param {boolean} v
+     */
+    set decal_filtering_enabled(v) {
+        const t = this.__decal_atlas_texture;
+
+        if (t.generateMipmaps === v) {
+            return;
+        }
+
+        t.generateMipmaps = v;
+    }
+
+    /**
+     *
+     * @return {boolean}
+     */
+    get decal_filtering_enabled() {
+        return this.__decal_atlas_texture.generateMipmaps;
+    }
+
+    __update_decal_atlas_texture() {
+        const sampler = this.__decal_atlas.sampler;
+
+        if (sampler.version !== this.__decal_atlas_texture.version) {
+            writeSample2DDataToDataTexture(sampler, this.__decal_atlas_texture);
+
+            this.__decal_atlas_texture.version = sampler.version;
+        }
+    }
+
+    /**
+     * Sometimes light lookup table can get quite large, to make sure we can store these addresses in the cluster texture,
+     * we may need to switch to a larger data type, such as Uint8->Uint16 or Uint16->Uint32
+     * @param {number} bit_count How many bits should be addressable from the cluster content
+     * @returns {boolean} true if texture was rebuilt (underlying type change), false otherwise
+     * @private
+     */
+    __set_cluster_addressable_bit_range(bit_count) {
+        const rounded_value = Math.ceil(bit_count);
+
+        this.__cluster_texture_precision = rounded_value;
+        const dataType = computeBinaryDataTypeByPrecision(NumericType.Uint, rounded_value);
+
+        const threeTextureType = computeThreeTextureTypeFromDataType(dataType);
+
+        const texture = this.__cluster_texture;
+        if (threeTextureType !== texture.type) {
+            this.__cluster_texture_needs_rebuild = true;
+
+            return true;
+        } else {
+            return false;
+        }
+    }
+
+    __update_cluster_texture() {
+        if (this.__cluster_texture_needs_rebuild) {
+            this.__build_cluster_texture();
+        }
+    }
+
+    __build_cluster_texture() {
+        const dataType = computeBinaryDataTypeByPrecision(NumericType.Uint, this.__cluster_texture_precision);
+
+        const threeTextureType = computeThreeTextureTypeFromDataType(dataType);
+
+        const texture = this.__cluster_texture;
+
+        const channelCount = 4;
+
+        texture.dispose();
+
+        const image = texture.image;
+
+        const resolution = this.__tiles_resolution;
+
+        image.width = resolution.x;
+        image.height = resolution.y;
+        image.depth = resolution.z;
+
+        texture.type = threeTextureType;
+        texture.internalFormat = computeThreeTextureInternalFormatFromDataType(dataType, channelCount);
+
+        const ArrayConstructor = DataType2TypedArrayConstructorMapping[dataType];
+
+        image.data = new ArrayConstructor(resolution.x * resolution.y * resolution.z * channelCount);
+
+        texture.needsUpdate = true;
+
+        this.__cluster_texture_needs_rebuild = false;
+    }
+
+    /**
+     *
+     * @param {number} size
+     * @returns {boolean}
+     * @private
+     */
+    __ensure_lookup_size(size) {
+        return this.__lookup_data.resize(size);
+    }
+
+    /**
+     *
+     * @returns {DataTexture}
+     */
+    getTextureLookup() {
+        return this.__lookup_data.getTexture();
+    }
+
+    /**
+     *
+     * @returns {DataTexture}
+     */
+    getTextureData() {
+        return this.__light_data.getTexture();
+    }
+
+    /**
+     * @returns {DataTexture3D}
+     */
+    getTextureClusters() {
+        return this.__cluster_texture;
+    }
+
+    /**
+     * @returns {DataTexture}
+     */
+    getTextureDecalAtlas() {
+        return this.__decal_atlas_texture;
+    }
+
+    /**
+     * NOTE: do not modify the value
+     * @returns {Readonly<Vector3>}
+     */
+    getResolution() {
+        return this.__tiles_resolution;
+    }
+
+    /**
+     *
+     * @private
+     */
+    __handle_light_dimensions_change() {
+        // internal BVH needs to be rebuilt
+        this.__visible_bvh_needs_update = true;
+        // when dimensions change, typically data will need to be re-written to the GPU, things like light positions or projection matrix
+        this.__light_data_needs_update = true;
+    }
+
+    /**
+     *
+     * @private
+     */
+    __handle_light_appearance_change() {
+        // appearance changes (such as color or intensity) don't affect bounds, only the encoded data
+        this.__light_data_needs_update = true;
+    }
+
+    /**
+     *
+     * @param {LightRenderMetadata} data
+     * @private
+     */
+    __handle_visible_decal_added(data) {
+        this.__light_data_needs_update = true;
+
+        /**
+         *
+         * @type {Decal}
+         */
+        const light = data.light;
+
+        light.onDimensionChanged(this.__handle_light_dimensions_change, this);
+
+        const ref = this.__decal_patch_references.acquire(light.texture_diffuse);
+
+        const patch = ref.getValue();
+        const patch_uv = patch.uv;
+
+        patch_uv.position.onChanged.add(light.handleUvPositionChange, light);
+        patch_uv.size.onChanged.add(light.handleUvSizeChange, light);
+
+        light.uv[0] = patch_uv.position.x;
+        light.uv[1] = patch_uv.position.y;
+        light.uv[2] = patch_uv.size.x;
+        light.uv[3] = patch_uv.size.y;
+
+        this.__decal_references.set(light, ref);
+    }
+
+    /**
+     *
+     * @param {LightRenderMetadata} data
+     * @private
+     */
+    __handle_visible_decal_removed(data) {
+        this.__light_data_needs_update = true;
+
+        /**
+         *
+         * @type {Decal}
+         */
+        const light = data.light;
+
+        light.offDimensionChanged(this.__handle_light_dimensions_change, this);
+
+        const ref = this.__decal_references.get(light);
+
+        if (ref === undefined) {
+            // This can occur when decal changes while being in the visible list, messing with the IncrementalDeltaSet's compare order
+            console.warn(`Decal reference not found: ${light}`);
+            return;
+        }
+
+        const patch = ref.getValue();
+        const patch_uv = patch.uv;
+
+        // unsubscribe
+        patch_uv.position.onChanged.remove(light.handleUvPositionChange, light);
+        patch_uv.size.onChanged.remove(light.handleUvSizeChange, light);
+
+
+        ref.release();
+
+        this.__decal_references.delete(light);
+    }
+
+    /**
+     *
+     * @param {LightRenderMetadata} data
+     * @private
+     */
+    __handle_visible_light_added(data) {
+        this.__light_data_needs_update = true;
+
+        const light = data.light;
+
+        light.onDimensionChanged(this.__handle_light_dimensions_change, this);
+        light.onAppearanceChanged(this.__handle_light_appearance_change, this);
+    }
+
+    /**
+     *
+     * @param {LightRenderMetadata} data
+     * @private
+     */
+    __handle_visible_light_removed(data) {
+        this.__light_data_needs_update = true;
+
+        const light = data.light;
+        light.offDimensionChanged(this.__handle_light_dimensions_change, this);
+        light.offAppearanceChanged(this.__handle_light_appearance_change, this);
+    }
+
+    /**
+     *
+     * @param {LightRenderMetadata} light
+     * @returns {number}
+     * @protected
+     */
+    __sort_visible_light_score(light) {
+        const center = scratch_corners;
+
+        light.light.getCenter(center)
+
+        const x = center[0];
+        const y = center[1];
+        const z = center[2];
+
+        return v3_morton_encode_transformed(x, y, z, this.__projection_matrix);
+    }
+
+    /**
+     * DEBUG method
+     * @param {LightRenderMetadata} lights
+     * @param {number} count
+     * @returns {number} lower = better sorting score
+     * @private
+     */
+    __assess_sorting_score(lights, count) {
+
+        let r = 0;
+
+        const center_a = [];
+        const center_b = [];
+
+        for (let i = 0; i < count; i++) {
+            const a = lights[i];
+
+            const score_a = this.__sort_visible_light_score(a);
+            a.light.getCenter(center_a);
+
+            for (let j = i + 1; j < count; j++) {
+                const b = lights[j];
+
+                const score_b = this.__sort_visible_light_score(b);
+                b.light.getCenter(center_b);
+
+                //
+                const score_distance = Math.abs(score_a - score_b);
+                const position_distance = v3_distance(
+                    center_a[0], center_a[1], center_a[2],
+                    center_b[0], center_b[1], center_b[2],
+                );
+
+                r += score_distance / position_distance;
+            }
+        }
+
+
+        return r / (count * (count - 1) * 0.5);
+    }
+
+    /**
+     * Sort lights for better data locality
+     * @private
+     */
+    __sort_visible_light() {
+        const sorted_lights = this.__sorted_visible_lights;
+
+        const visible_light_set = this.__visible_lights;
+        const visible_light_count = visible_light_set.size;
+
+        const visible_decal_set = this.__visible_decals;
+        const visible_decal_count = visible_decal_set.size;
+
+        const expected_sorted_size = visible_light_count + visible_decal_count;
+
+        if (sorted_lights.length > expected_sorted_size) {
+            // crop the reused array back down to the current frame's size, otherwise stale records from a
+            // larger earlier frame are re-encoded into the light-data texture every frame. Truncate via
+            // `length =` (in place, drops the tail references for GC) rather than splice, which would
+            // allocate a throwaway array of the removed elements.
+            sorted_lights.length = expected_sorted_size;
+        }
+
+        array_copy(visible_light_set.elements, 0, sorted_lights, 0, visible_light_count);
+        array_copy(visible_decal_set.elements, 0, sorted_lights, visible_light_count, visible_decal_count);
+
+        array_sort_quick(sorted_lights, this.__sort_visible_light_score, this, 0, expected_sorted_size - 1);
+    }
+
+    __update_visible_bvh() {
+        this.__visible_bvh_needs_update = false;
+
+        build_light_data_bvh(
+            this.__visible_lights,
+            this.__visible_bvh_lights
+        );
+
+        build_light_data_bvh(
+            this.__visible_decals,
+            this.__visible_bvh_decals
+        );
+    }
+
+
+    /**
+     *
+     * @param {Camera} camera
+     * @private
+     */
+    __build_view_frustum(camera) {
+        frustum_from_camera(camera, this.__view_frustum, false);
+
+        array_swap_one(this.__view_frustum.planes, 4, 5);
+
+        this.__build_view_frustum_points();
+    }
+
+    __build_visible_light_list() {
+
+        /**
+         *
+         * @type {IncrementalDeltaSet<LightRenderMetadata>}
+         */
+        const visible_lights = this.__visible_lights;
+
+        visible_lights.initializeUpdate();
+
+        const visible_decals = this.__visible_decals;
+
+        visible_decals.initializeUpdate();
+
+        const nodes = [];
+
+        frustum3_planes_to_flat_from_three(this.__view_frustum.planes, scratch_frustum_planes)
+
+        /*
+        Search is done in 2 phases:
+        1) broad phase using bounding boxes
+        2) granular phase where we use object-specific shape to check against frustum
+         */
+
+        const broad_match_count = bvh_query_user_data_intersects_frustum(nodes, 0, this.#light_data_bvh, scratch_frustum_planes);
+
+        for (let i = 0; i < broad_match_count; i++) {
+
+            const light_id = nodes[i];
+
+            /**
+             *
+             * @type {LightRenderMetadata}
+             */
+            const light_data = this.#metadata_map.get(light_id);
+
+            /**
+             *
+             * @type {PointLight|Decal}
+             */
+            const light = light_data.light;
+
+            if (light.isDecal === true) {
+
+
+                // decals go into a separate bucket
+                visible_decals.push(light_data);
+
+            } else if (light.isPointLight === true) {
+                // perform granular check
+
+                const light_position = light.position;
+
+                const light_x = light_position.x;
+                const light_y = light_position.y;
+                const light_z = light_position.z;
+
+                const radius = light.radius.getValue();
+
+                if (!point_light_inside_volume(light_x, light_y, light_z, radius, scratch_frustum_planes)) {
+                    // outside of view frustum
+                    continue;
+                }
+
+
+                // register as visible
+                visible_lights.push(light_data);
+            }
+
+        }
+
+        visible_lights.finalizeUpdate();
+
+        visible_decals.finalizeUpdate();
+    }
+
+    __write_light_data_texture() {
+
+        /**
+         *
+         * @type {LightRenderMetadata[]}
+         */
+        const visible_lights = this.__sorted_visible_lights;
+
+        // write light data into texture
+        const visible_light_count = visible_lights.length;
+
+        // compute amount of space required for the lights
+        let address = 0;
+        for (let i = 0; i < visible_light_count; i++) {
+            const datum = visible_lights[i];
+
+            /**
+             *
+             * @type {PointLight}
+             */
+            const light = datum.light;
+
+            address += light.ENCODED_SLOT_COUNT;
+        }
+
+        const expected_light_data_size = address;
+
+
+        const light_data = this.__light_data;
+        light_data.resize(Math.ceil(address / 4));
+
+        light_data.update();
+
+        // update required lookup precision
+        this.__lookup_data.precision = Math.max(
+            0,
+            Math.ceil(Math.log2(light_data.size))
+        ) + LIGHT_ENCODING_TYPE_BIT_COUNT;
+
+        const tx_light = light_data.getTexture();
+
+        /**
+         *
+         * @type {Float32Array}
+         */
+        const tx_light_data = tx_light.image.data;
+
+        address = 0;
+
+        for (let i = 0; i < visible_light_count; i++) {
+            const datum = visible_lights[i];
+
+            assert.lessThan(address, tx_light_data.length, "overflow");
+
+            /**
+             *
+             * @type {PointLight}
+             */
+            const light = datum.light;
+
+            datum.address = address >> 2;
+
+            const written_slots = light.toArray(tx_light_data, address);
+
+            address += written_slots;
+
+            // align address to 4 slot boundary
+            if ((address & 3) !== 0) {
+                // not on 4 slot boundary
+                address = ((address >> 2) + 1) << 2;
+            }
+        }
+
+        if (address !== expected_light_data_size) {
+            throw new Error(`Expected light data size is ${expected_light_data_size}, actual written data is size is ${address}`);
+        }
+
+        tx_light.needsUpdate = true;
+
+        this.__visible_bvh_needs_update = true;
+    }
+
+    /**
+     * Perform cluster assignment where each cluster is filled with overlapping lights
+     * @private
+     */
+    __assign_lights_to_clusters() {
+
+        const tiles_resolution = this.__tiles_resolution;
+
+        const tr_z = tiles_resolution.z;
+        const tr_y = tiles_resolution.y;
+        const tr_x = tiles_resolution.x;
+
+        const tr_x_1 = tr_x + 1;
+        const tr_y_1 = tr_y + 1;
+
+        const tr_xy_1 = tr_x_1 * tr_y_1;
+
+        /**
+         *
+         * @type {Float32Array}
+         */
+        const cluster_planes = this.__cluster_planes;
+
+        const bvh_lights = this.__visible_bvh_lights;
+        const bvh_decals = this.__visible_bvh_decals;
+
+
+        const cluster_planes_x_offset = 0;
+        const cluster_planes_y_offset = tr_x_1 * 4;
+        const cluster_planes_z_offset = cluster_planes_y_offset + tr_y_1 * 4;
+
+        /**
+         *
+         * @type {number[]|Float32Array}
+         */
+        const light_source_data = this.__light_data.getTexture().image.data;
+
+        const tile_slice_size = tr_x * tr_y;
+
+        const light_cluster_texture = this.__cluster_texture;
+        const tile_texture_data = light_cluster_texture.image.data;
+
+        const light_lookup = this.__lookup_data;
+        light_lookup.update();
+        const light_lookup_texture = light_lookup.getTexture();
+        const light_lookup_texture_data = light_lookup_texture.image.data;
+
+        let lookup_address_offset = 0;
+        let i_x_0, i_y_0, i_z_0;
+
+        // clear cache
+        LOOKUP_CACHE.fill(0xFFFFFFFF);
+
+        // console.log('Assignment Start');
+
+        for (i_z_0 = 0; i_z_0 < tr_z; i_z_0++) {
+
+            // construct z planes
+
+            const slice_offset = i_z_0 * tile_slice_size;
+
+            const z_plane_index_offset_0 = cluster_planes_z_offset + i_z_0 * 4;
+
+            read_plane_pair(cluster_planes, z_plane_index_offset_0, scratch_frustum_planes, 16);
+
+            for (i_y_0 = 0; i_y_0 < tr_y; i_y_0++) {
+
+                // construct y planes
+
+                const y_plane_index_offset_0 = cluster_planes_y_offset + i_y_0 * 4;
+
+                read_plane_pair(cluster_planes, y_plane_index_offset_0, scratch_frustum_planes, 8);
+
+                for (i_x_0 = 0; i_x_0 < tr_x; i_x_0++) {
+
+                    // construct x planes
+
+                    const x_plane_index_offset_0 = cluster_planes_x_offset + i_x_0 * 4;
+
+                    read_plane_pair(cluster_planes, x_plane_index_offset_0, scratch_frustum_planes, 0);
+
+                    const tile_index = slice_offset + (i_y_0 * tr_x) + i_x_0;
+
+                    const tile_data_offset = tile_index * 4;
+
+                    //assign lights
+                    lookup_address_offset += assign_cluster(
+                        tile_data_offset,
+                        bvh_lights,
+                        lookup_address_offset,
+                        light_lookup_texture_data,
+                        tile_texture_data,
+                        light_source_data
+                    );
+
+                    // assign decals
+                    const decal_count = assign_cluster(
+                        tile_data_offset + 2,
+                        bvh_decals,
+                        lookup_address_offset,
+                        light_lookup_texture_data,
+                        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;
+                }
+            }
+        }
+
+        light_cluster_texture.needsUpdate = true;
+        light_lookup_texture.needsUpdate = true;
+
+        // Post-fact lookup texture resize, this frame will be wrong, but next one should be ok
+        const current_lookup_size = this.__lookup_data.size;
+
+        const lookup_memory_resized = this.__ensure_lookup_size(lookup_address_offset);
+
+        const cluster_resized = this.__set_cluster_addressable_bit_range(Math.max(0, Math.log2(lookup_address_offset)));
+
+        if (
+            (lookup_memory_resized && current_lookup_size < lookup_address_offset)
+            || cluster_resized
+        ) {
+            // overflow, we ended up trying to write more lights into some clusters than what they could contain
+            this.__update_cluster_texture();
+
+            // re-do assignment
+            this.__assign_lights_to_clusters();
+        }
+
+        // console.log('Unique assignment count: ', assignment_count, ', Hash reuse:', hash_reuse_count);
+    }
+
+    /**
+     *
+     * @private
+     */
+    __build_cluster_frustum_planes() {
+        const tiles_resolution = this.__tiles_resolution;
+
+        const tr_z = tiles_resolution.z;
+        const tr_y = tiles_resolution.y;
+        const tr_x = tiles_resolution.x;
+
+        const destination = this.__cluster_planes;
+
+        compute_cluster_planes_from_points(destination, this.__cluster_frustum_points, tr_x, tr_y, tr_z);
+    }
+
+    /**
+     *
+     * @private
+     */
+    __build_view_frustum_points() {
+
+        const view_frustum = this.__view_frustum;
+
+        const points = this.__view_frustum_points;
+
+        computeFrustumCorners(points, view_frustum.planes);
+    }
+
+    /**
+     *
+     * @private
+     */
+    __build_cluster_frustum_points() {
+        const tiles_resolution = this.__tiles_resolution;
+
+        const tr_z = tiles_resolution.z;
+        const tr_y = tiles_resolution.y;
+        const tr_x = tiles_resolution.x;
+
+        const view_frustum_points = this.__view_frustum_points;
+        const points_data = this.__cluster_frustum_points;
+
+        frustum3_slice_linear_to_points(view_frustum_points, tr_x, tr_y, tr_z, points_data);
+    }
+
+    /**
+     * Build light tile texture
+     * @param {Camera|THREE.PerspectiveCamera} camera
+     */
+    buildTiles(camera) {
+        // camera.updateProjectionMatrix();
+        // camera.updateMatrix();
+        // camera.updateMatrixWorld(true);
+
+        //update world inverse matrix
+        camera.matrixWorldInverse.copy(camera.matrixWorld);
+        camera.matrixWorldInverse.invert();
+
+        // this.__projection_matrix.set(camera.matrixWorldInverse.elements);
+        m4_multiply(this.__projection_matrix, camera.projectionMatrix.elements, camera.matrixWorldInverse.elements);
+
+        // console.time('__build_view_frustum');
+        this.__build_view_frustum(camera);
+        // console.timeEnd('__build_view_frustum');
+
+
+        // console.time('__build_visible_light_list');
+        this.__build_visible_light_list();
+        // console.timeEnd('__build_visible_light_list');
+
+        // update decal atlas
+        this.__decal_atlas.update();
+        this.__update_decal_atlas_texture();
+
+        // console.time('__write_light_data_texture');
+        if (this.__light_data_needs_update) {
+            // sort light for better search and query locality
+            this.__sort_visible_light();
+
+            this.__write_light_data_texture();
+
+            // clear flag
+            this.__light_data_needs_update = false;
+        }
+        // console.timeEnd('__write_light_data_texture');
+
+        if (this.__visible_bvh_needs_update) {
+            this.__update_visible_bvh();
+        }
+
+        this.__build_cluster_frustum_points();
+        // console.time('__build_cluster_frustum_planes');
+        this.__build_cluster_frustum_planes();
+        // console.timeEnd('__build_cluster_frustum_planes');
+
+        // console.time('__assign_lights_to_clusters');
+        this.__assign_lights_to_clusters();
+        // console.timeEnd('__assign_lights_to_clusters');
+    }
+
+    dispose() {
+        this.__cluster_texture.dispose();
+        this.__light_data.dispose();
+        this.__lookup_data.dispose();
+        this.__decal_atlas_texture.dispose();
+    }
+
+    /**
+     * 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.isFinite(x, 'x');
+        assert.greaterThan(x, 0, 'x must be > 0');
+
+        assert.isNumber(y, 'y');
+        assert.isNonNegativeInteger(y, 'y');
+        assert.isFinite(y, 'y');
+        assert.greaterThan(y, 0, 'y must be > 0');
+
+        assert.isNumber(z, 'z');
+        assert.isNonNegativeInteger(z, 'z');
+        assert.isFinite(z, 'z');
+        assert.greaterThan(z, 0, 'z must be > 0');
+
+        const r = this.__tiles_resolution;
+
+        if (x === r.x && y === r.y && z === r.z) {
+            // special case, no change
+            return;
+        }
+
+        r.set(x, y, z);
+
+        this.__cluster_texture_needs_rebuild = true;
+        this.__update_cluster_texture();
+
+        const cluster_planes_size = ((x + 1) + (y + 1) + (z + 1)) * 4;
+        const cluster_frustum_points_size = (x + 1) * (y + 1) * (z + 1) * 3;
+
+        const buffer = new ArrayBuffer((cluster_planes_size + cluster_frustum_points_size) * 4);
+
+        this.__cluster_planes = new Float32Array(
+            buffer, 0,
+            cluster_planes_size
+        );
+        this.__cluster_frustum_points = new Float32Array(
+            buffer, cluster_planes_size * 4,
+            cluster_frustum_points_size
+        );
+    }
+
+    /**
+     *
+     * @param {AbstractLight} light
+     * @returns {boolean}
+     */
+    hasLight(light) {
+        return this.#metadata_map.has(light.id);
+    }
+
+    /**
+     *
+     * @param {AbstractLight} light
+     */
+    addLight(light) {
+        const lightData = new LightRenderMetadata(light);
+
+        lightData.link(this.#light_data_bvh);
+
+        this.#metadata_map.set(light.id, lightData);
+    }
+
+    /**
+     *
+     * @param {AbstractLight} light
+     * @returns {boolean}
+     */
+    removeLight(light) {
+
+        const light_id = light.id;
+
+        const data = this.#metadata_map.get(light_id);
+
+        if (data === undefined) {
+            return false;
+        }
+
+        data.unlink();
+
+        this.#metadata_map.delete(light_id);
+
+        return true;
+    }
+}