@woosh/meep-engine 3.0.2 → 3.2.0

package/src/core/geom/3d/topology/struct/binary/BinaryTopology.js

@@ -1,1086 +1,1086 @@
-import { assert } from "../../../../../assert.js";
-import { BinaryDataBlock } from "./BinaryDataBlock.js";
-import { BinaryElementPool } from "./BinaryElementPool.js";
-
-/**
- * Byte size of FLOAT_32
- * @readonly
- * @type {number}
- */
-const FLOAT_32_SIZE = 4;
-
-/**
- * Byte size of UINT_32
- * @readonly
- * @type {number}
- */
-const UINT_32_SIZE = 4;
-
-/**
- * @readonly
- * @type {number}
- */
-export const NULL_POINTER = 0xFFFFFFFF;
-
-
-/*
-Heavily influenced by blender's internal mesh structure.
-@see https://github.com/blender/blender/blob/master/source/blender/bmesh/bmesh_class.h
- */
-
-/**
- * Bring one mesh's data block into line with another's, creating or dropping it as needed.
- *
- * The block is rebuilt rather than shared, so layer handles into `target` do not survive this —
- * whoever held them reads the new ones off {@link BinaryDataBlock#layers}.
- *
- * @param {BinaryDataBlock|null} target block currently held, if any
- * @param {BinaryElementPool} base pool the block belongs to, for when one has to be made
- * @param {BinaryDataBlock|null} source block to take after
- * @returns {BinaryDataBlock|null}
- */
-function copy_data_block(target, base, source) {
-    if (source === null) {
-        return null;
-    }
-
-    const result = target === null ? new BinaryDataBlock(base) : target;
-
-    result.copy(source);
-
-    // The pools were copied first, and a pool that reallocated to fit may have landed on more
-    // capacity than the one it copied from.
-    result.sync_capacity();
-
-    return result;
-}
-
-/**
- * A high-performance memory-efficient, binary-backed topological data structure for representing 3D meshes.
- * Manages interconnected vertices, edges, loops, and faces using contiguous memory pools.
- */
-export class BinaryTopology {
-    /**
-     * structure:
-     *      coordinate: float32[3] // vertex coordinates
-     *      normal: float32[3] // vertex normal
-     *      edge_pointer: uint32 // Pointer to (any) edge using this vertex (for disk cycles)
-     *
-     * @type {BinaryElementPool}
-     * @private
-     */
-    __vertex_pool = new BinaryElementPool(3 * FLOAT_32_SIZE + 3 * FLOAT_32_SIZE + UINT_32_SIZE);
-
-    /**
-     * structure:
-     *      v1: uint32 // Vertices (unordered)
-     *      v2: uint32 // Vertices (unordered)
-     *      l: uint32 // The list of loops around the edge points at a Loop
-     *      v1_disk_link: uint32[2] // Disk Cycle Pointers edge around vertex v1 and d2 does the same for v2.
-     *      v2_disk_link: uint32[2] // see above
-     *
-     * Disk cycle convention:
-     *   For every vertex v with at least one incident edge, the edges incident
-     *   to v form a doubly-linked cycle threaded through their disk_link slots.
-     *   Each non-self-loop edge e uses exactly ONE slot in v's cycle: the v1
-     *   slot if `vertex1(e) === v`, otherwise the v2 slot. Callers select the
-     *   side with `is_v1 = edge_read_vertex1(e) === v`.
-     *
-     *   Self-loops (vertex1(e) === vertex2(e) === v) are represented with ONE
-     *   slot too, by convention the v1 slot. The v2_disk_link of a self-loop is
-     *   UNSPECIFIED -- readers must not follow it, writers must not assume any
-     *   prior value. Insertion/removal helpers must be called exactly once per
-     *   self-loop (not once per "endpoint"), otherwise the v1 slot is scribbled
-     *   on a second time and the cycle is corrupted.
-     * @type {BinaryElementPool}
-     * @private
-     */
-    __edge_pool = new BinaryElementPool(UINT_32_SIZE * 7);
-
-    /**
-     * Loop represents a corner of the face
-     * structure:
-     *      v: uint32 // The vertex this loop points to. This vertex must be unique within the cycle
-     *      e: uint32 // The edge this loop uses.
-     *      f: uint32 // The face this loop is part of.
-     *      radial_next: uint32 // Other loops connected to this edge.
-     *      radial_prev: uint32
-     *      next: uint32 // Other loops that are part of this face.
-     *      prev: uint32
-     * @type {BinaryElementPool}
-     * @private
-     */
-    __loop_pool = new BinaryElementPool(UINT_32_SIZE * 7);
-
-    /**
-     * structure:
-     *      l_first: uint32 // first loop pointer
-     *      no: float32[3] // Face normal
-     * @type {BinaryElementPool}
-     * @private
-     */
-    __face_pool = new BinaryElementPool(UINT_32_SIZE + FLOAT_32_SIZE * 3);
-
-    /**
-     * Optional per-vertex attribute storage. Record IDs are vertex IDs.
-     * Null until {@link vertex_data_add_layer} is called.
-     * @type {BinaryDataBlock|null}
-     * @private
-     */
-    __vertex_data_block = null;
-
-    /**
-     * Optional per-edge attribute storage. See {@link __vertex_data_block}.
-     * @type {BinaryDataBlock|null}
-     * @private
-     */
-    __edge_data_block = null;
-
-    /**
-     * Optional per-loop attribute storage. See {@link __vertex_data_block}.
-     * @type {BinaryDataBlock|null}
-     * @private
-     */
-    __loop_data_block = null;
-
-    /**
-     * Optional per-face attribute storage. See {@link __vertex_data_block}.
-     * @type {BinaryDataBlock|null}
-     * @private
-     */
-    __face_data_block = null;
-
-
-    /**
-     * Total (approximate) size of this structure in memory, in bytes
-     * @return {number}
-     */
-    get byteSize() {
-        let total = this.__loop_pool.byteSize
-            + this.__vertex_pool.byteSize
-            + this.__edge_pool.byteSize
-            + this.__face_pool.byteSize;
-
-        if (this.__vertex_data_block !== null) total += this.__vertex_data_block.byteSize;
-        if (this.__edge_data_block !== null) total += this.__edge_data_block.byteSize;
-        if (this.__loop_data_block !== null) total += this.__loop_data_block.byteSize;
-        if (this.__face_data_block !== null) total += this.__face_data_block.byteSize;
-
-        return total;
-    }
-
-    /**
-     * Releases excess memory held by internal pools.
-     * Useful for serialization use cases.
-     */
-    trim() {
-        this.__loop_pool.trim();
-        this.__vertex_pool.trim();
-        this.__edge_pool.trim();
-        this.__face_pool.trim();
-
-        if (this.__vertex_data_block !== null) this.__vertex_data_block.trim();
-        if (this.__edge_data_block !== null) this.__edge_data_block.trim();
-        if (this.__loop_data_block !== null) this.__loop_data_block.trim();
-        if (this.__face_data_block !== null) this.__face_data_block.trim();
-    }
-
-    /**
-     *
-     * @return {BinaryElementPool}
-     */
-    get vertices() {
-        return this.__vertex_pool;
-    }
-
-    /**
-     * Edges are shared among faces, edges point to 2 unordered vertices
-     * @return {BinaryElementPool}
-     */
-    get edges() {
-        return this.__edge_pool;
-    }
-
-    /**
-     * Loops are corners of faces, a single vertex can be associated with many loops, one per connected face
-     * @return {BinaryElementPool}
-     */
-    get loops() {
-        return this.__loop_pool;
-    }
-
-    /**
-     *
-     * @returns {BinaryElementPool}
-     */
-    get faces() {
-        return this.__face_pool;
-    }
-
-    /**
-     * Per-vertex attribute storage: one interleaved record per vertex, addressed by vertex ID,
-     * carrying every layer declared through {@link vertex_data_add_layer}.
-     *
-     * Reading and writing goes through the layer handles that call returned, not through here —
-     * this is the raw block, for the passes that move whole records around.
-     *
-     * @returns {BinaryDataBlock|null} null until a layer has been declared
-     */
-    get vertex_data() {
-        return this.__vertex_data_block;
-    }
-
-    /**
-     * Per-edge attribute storage. See {@link vertex_data}.
-     * @returns {BinaryDataBlock|null} null until a layer has been declared
-     */
-    get edge_data() {
-        return this.__edge_data_block;
-    }
-
-    /**
-     * Per-loop attribute storage. See {@link vertex_data}.
-     * @returns {BinaryDataBlock|null} null until a layer has been declared
-     */
-    get loop_data() {
-        return this.__loop_data_block;
-    }
-
-    /**
-     * Per-face attribute storage. See {@link vertex_data}.
-     * @returns {BinaryDataBlock|null} null until a layer has been declared
-     */
-    get face_data() {
-        return this.__face_data_block;
-    }
-
-    /**
-     * Declare a per-vertex attribute, creating the vertex data block if this is its first.
-     *
-     * The returned handle is the way in and out of that attribute; hold on to it. It carries its
-     * own compiled accessors, so nothing has to look it up by name and two attributes of the same
-     * shape never collide.
-     *
-     * Declaring a layer on a mesh that already has vertices is fine — the existing records are
-     * widened in place and keep their contents, which is what lets a pass attach data to a mesh it
-     * did not build.
-     *
-     * @param {BinaryDataType} type
-     * @param {number} components 3 for a vec3
-     * @returns {BinaryDataLayer}
-     */
-    vertex_data_add_layer(type, components) {
-        if (this.__vertex_data_block === null) {
-            this.__vertex_data_block = new BinaryDataBlock(this.__vertex_pool);
-        }
-
-        const layer = this.__vertex_data_block.add_layer(type, components);
-
-        this.__vertex_data_block.sync_capacity();
-
-        return layer;
-    }
-
-    /**
-     * Declare a per-edge attribute. See {@link vertex_data_add_layer}.
-     * @param {BinaryDataType} type
-     * @param {number} components
-     * @returns {BinaryDataLayer}
-     */
-    edge_data_add_layer(type, components) {
-        if (this.__edge_data_block === null) {
-            this.__edge_data_block = new BinaryDataBlock(this.__edge_pool);
-        }
-
-        const layer = this.__edge_data_block.add_layer(type, components);
-
-        this.__edge_data_block.sync_capacity();
-
-        return layer;
-    }
-
-    /**
-     * Declare a per-loop attribute. See {@link vertex_data_add_layer}.
-     * @param {BinaryDataType} type
-     * @param {number} components
-     * @returns {BinaryDataLayer}
-     */
-    loop_data_add_layer(type, components) {
-        if (this.__loop_data_block === null) {
-            this.__loop_data_block = new BinaryDataBlock(this.__loop_pool);
-        }
-
-        const layer = this.__loop_data_block.add_layer(type, components);
-
-        this.__loop_data_block.sync_capacity();
-
-        return layer;
-    }
-
-    /**
-     * Declare a per-face attribute. See {@link vertex_data_add_layer}.
-     * @param {BinaryDataType} type
-     * @param {number} components
-     * @returns {BinaryDataLayer}
-     */
-    face_data_add_layer(type, components) {
-        if (this.__face_data_block === null) {
-            this.__face_data_block = new BinaryDataBlock(this.__face_pool);
-        }
-
-        const layer = this.__face_data_block.add_layer(type, components);
-
-        this.__face_data_block.sync_capacity();
-
-        return layer;
-    }
-
-    /**
-     * @returns {boolean} true if a data block was removed, false if there was none
-     */
-    delete_vertex_data() {
-        if (this.__vertex_data_block === null) {
-            return false;
-        }
-        this.__vertex_data_block = null;
-        return true;
-    }
-
-    /**
-     * @returns {boolean} true if a data block was removed, false if there was none
-     */
-    delete_edge_data() {
-        if (this.__edge_data_block === null) {
-            return false;
-        }
-        this.__edge_data_block = null;
-        return true;
-    }
-
-    /**
-     * @returns {boolean} true if a data block was removed, false if there was none
-     */
-    delete_loop_data() {
-        if (this.__loop_data_block === null) {
-            return false;
-        }
-        this.__loop_data_block = null;
-        return true;
-    }
-
-    /**
-     * @returns {boolean} true if a data block was removed, false if there was none
-     */
-    delete_face_data() {
-        if (this.__face_data_block === null) {
-            return false;
-        }
-        this.__face_data_block = null;
-        return true;
-    }
-
-    /**
-     * Clear the topology, removed all data
-     */
-    clear() {
-        this.__vertex_pool.clear();
-        this.__edge_pool.clear();
-        this.__loop_pool.clear();
-        this.__face_pool.clear();
-
-        // The data blocks hold no size of their own, so there is nothing in them to clear: with the
-        // pools empty, no element id reaches a record any more. Their layout and capacity are
-        // deliberately retained, exactly as the pools retain theirs — the next mesh built into this
-        // topology keeps the layers that were declared on it, and its first elements inherit the
-        // bytes the last mesh left, on the terms {@link vertex_create} sets out.
-    }
-
-    /**
-     *
-     * @param {number[]|ArrayLike<number>|Float32Array} result
-     * @param {number} result_offset
-     * @param {number} id vertex ID
-     */
-    vertex_read_coordinate(result, result_offset, id) {
-        const pool = this.__vertex_pool;
-
-        const v_address = pool.element_address(id);
-        const v_offset = v_address >> 2; // get 4-byte boundary
-        result[result_offset] = pool.data_float32[v_offset];
-        result[result_offset + 1] = pool.data_float32[v_offset + 1];
-        result[result_offset + 2] = pool.data_float32[v_offset + 2];
-    }
-
-    /**
-     *
-     * @param {number} id
-     * @param {number[]|Float32Array} value
-     * @param {number} value_offset
-     */
-    vertex_write_coordinate(id, value, value_offset) {
-        const pool = this.__vertex_pool;
-
-        const v_address = pool.element_address(id);
-        const v_offset = v_address >> 2; // get 4-byte boundary
-        pool.data_float32[v_offset] = value[value_offset];
-        pool.data_float32[v_offset + 1] = value[value_offset + 1];
-        pool.data_float32[v_offset + 2] = value[value_offset + 2];
-    }
-
-    /**
-     *
-     * @param {number[]|ArrayLike<number>|Float32Array} result
-     * @param {number} result_offset
-     * @param {number} id vertex ID
-     */
-    vertex_read_normal(result, result_offset, id) {
-        const pool = this.__vertex_pool;
-
-        const v_address = pool.element_address(id) + 3 * FLOAT_32_SIZE;
-        const v_offset = v_address >> 2; // get 4-byte boundary
-        result[result_offset] = pool.data_float32[v_offset];
-        result[result_offset + 1] = pool.data_float32[v_offset + 1];
-        result[result_offset + 2] = pool.data_float32[v_offset + 2];
-    }
-
-    /**
-     *
-     * @param {number} id
-     * @param {number[]|Float32Array} value
-     * @param {number} value_offset
-     */
-    vertex_write_normal(id, value, value_offset) {
-        const pool = this.__vertex_pool;
-
-        const v_address = pool.element_address(id) + 3 * FLOAT_32_SIZE;
-        const v_offset = v_address >> 2; // get 4-byte boundary
-        pool.data_float32[v_offset] = value[value_offset];
-        pool.data_float32[v_offset + 1] = value[value_offset + 1];
-        pool.data_float32[v_offset + 2] = value[value_offset + 2];
-    }
-
-    /**
-     * @param {number} id
-     * @returns {number}
-     */
-    vertex_read_edge(id) {
-        const pool = this.__vertex_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 6 * UINT_32_SIZE);
-
-    }
-
-    /**
-     *
-     * @param {number} edge_id
-     * @param {number} id
-     */
-    vertex_write_edge(id, edge_id) {
-        const pool = this.__vertex_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 6 * UINT_32_SIZE, edge_id);
-    }
-
-    /**
-     * @param {number} id edge ID
-     * @returns {number}
-     */
-    edge_read_vertex1(id) {
-        const pool = this.__edge_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address);
-
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id edge ID
-     */
-    edge_write_vertex1(id, value) {
-        const pool = this.__edge_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address, value);
-    }
-
-    /**
-     * @param {number} id edge ID
-     * @returns {number}
-     */
-    edge_read_vertex2(id) {
-        const pool = this.__edge_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + UINT_32_SIZE);
-
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id edge ID
-     */
-    edge_write_vertex2(id, value) {
-        const pool = this.__edge_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + UINT_32_SIZE, value);
-    }
-
-
-    /**
-     * @param {number} id edge ID
-     * @returns {number}
-     */
-    edge_read_loop(id) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__edge_pool;
-
-        assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 2 * UINT_32_SIZE);
-
-    }
-
-    /**
-     *
-     * @param {number} loop_id loop ID
-     * @param {number} id edge ID
-     */
-    edge_write_loop(id, loop_id) {
-        const pool = this.__edge_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 2 * UINT_32_SIZE, loop_id);
-    }
-
-    /**
-     * @param {number} id edge ID
-     * @returns {number} edge ID
-     */
-    edge_read_v1_disk_next(id) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__edge_pool;
-
-        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 3 * UINT_32_SIZE);
-
-    }
-
-    /**
-     *
-     * @param {number} value edge ID
-     * @param {number} id edge ID
-     */
-    edge_write_v1_disk_next(id, value) {
-        const pool = this.__edge_pool;
-
-        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 3 * UINT_32_SIZE, value);
-    }
-
-    /**
-     * @param {number} id edge ID
-     * @returns {number} edge ID
-     */
-    edge_read_v1_disk_prev(id) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__edge_pool;
-
-        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 4 * UINT_32_SIZE);
-
-    }
-
-    /**
-     *
-     * @param {number} value edge ID
-     * @param {number} id edge ID
-     */
-    edge_write_v1_disk_prev(id, value) {
-        const pool = this.__edge_pool;
-
-        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 4 * UINT_32_SIZE, value);
-    }
-
-    /**
-     * @param {number} id edge ID
-     * @returns {number} edge ID
-     */
-    edge_read_v2_disk_next(id) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__edge_pool;
-
-        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 5 * UINT_32_SIZE);
-
-    }
-
-    /**
-     *
-     * @param {number} value edge ID
-     * @param {number} id edge ID
-     */
-    edge_write_v2_disk_next(id, value) {
-        const pool = this.__edge_pool;
-
-        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 5 * UINT_32_SIZE, value);
-    }
-
-    /**
-     * @param {number} id edge ID
-     * @returns {number} edge ID
-     */
-    edge_read_v2_disk_prev(id) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__edge_pool;
-
-        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 6 * UINT_32_SIZE);
-
-    }
-
-    /**
-     *
-     * @param {number} value edge ID
-     * @param {number} id edge ID
-     */
-    edge_write_v2_disk_prev(id, value) {
-        const pool = this.__edge_pool;
-
-        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 6 * UINT_32_SIZE, value);
-    }
-
-    /**
-     * Allocate a new vertex, growing the vertex data block to match.
-     *
-     * Element lifetime is the topology's to manage, not the pool's: go through here and
-     * {@link vertex_destroy} rather than reaching for `vertices.allocate()`/`vertices.release()`,
-     * or the attribute storage is left behind. The block has no allocator of its own to drive —
-     * capacity is the only thing there is to keep in step.
-     *
-     * @returns {number} vertex ID
-     */
-    vertex_create() {
-        const id = this.__vertex_pool.allocate();
-
-        this.__vertex_data_block?.sync_capacity();
-
-        return id;
-    }
-
-    /**
-     * Allocate a contiguous run of vertex IDs. See {@link vertex_create}.
-     * @param {number} count
-     * @returns {number} first ID of the run
-     */
-    vertices_create_continuous(count) {
-        const offset = this.__vertex_pool.allocate_continuous(count);
-
-        this.__vertex_data_block?.sync_capacity();
-
-        return offset;
-    }
-
-    /**
-     * Free a vertex. See {@link vertex_create}.
-     *
-     * The vertex's record is left as it lies — nothing reads a dead ID, and a later
-     * {@link vertex_create} reusing the slot inherits whatever was there. A caller that needs a
-     * fresh vertex to start from a known value writes it.
-     *
-     * @param {number} id vertex ID
-     */
-    vertex_destroy(id) {
-        this.__vertex_pool.release(id);
-    }
-
-    /**
-     * Allocate a new edge. See {@link vertex_create}.
-     * @returns {number} edge ID
-     */
-    edge_create() {
-        const id = this.__edge_pool.allocate();
-
-        this.__edge_data_block?.sync_capacity();
-
-        return id;
-    }
-
-    /**
-     * Free an edge. See {@link vertex_destroy}.
-     * @param {number} id edge ID
-     */
-    edge_destroy(id) {
-        this.__edge_pool.release(id);
-    }
-
-    /**
-     * Allocate a new face. See {@link vertex_create}.
-     * @returns {number} face ID
-     */
-    face_create() {
-        const id = this.__face_pool.allocate();
-
-        this.__face_data_block?.sync_capacity();
-
-        return id;
-    }
-
-    /**
-     * Allocate a contiguous run of face IDs. See {@link vertex_create}.
-     * @param {number} count
-     * @returns {number} first ID of the run
-     */
-    faces_create_continuous(count) {
-        const offset = this.__face_pool.allocate_continuous(count);
-
-        this.__face_data_block?.sync_capacity();
-
-        return offset;
-    }
-
-    /**
-     * Free a face. See {@link vertex_destroy}.
-     * @param {number} id face ID
-     */
-    face_destroy(id) {
-        this.__face_pool.release(id);
-    }
-
-    /**
-     * Allocate a new loop and put it into a valid initial state.
-     * See {@link vertex_create} for the data block semantics.
-     * @returns {number} loop ID
-     */
-    loop_create() {
-        const id = this.__loop_pool.allocate();
-
-        this.__loop_data_block?.sync_capacity();
-
-        this.loop_initialize(id);
-
-        return id;
-    }
-
-    /**
-     * Free a loop. See {@link vertex_destroy}.
-     * @param {number} id loop ID
-     */
-    loop_destroy(id) {
-        this.__loop_pool.release(id);
-    }
-
-    /**
-     * Put loop into valid initial state, set all pointers to NULL
-     * @param {number} id
-     */
-    loop_initialize(id) {
-        this.loop_write_radial_next(id, id);
-        this.loop_write_radial_prev(id, id);
-        this.loop_write_next(id, id);
-        this.loop_write_prev(id, id);
-    }
-
-    /**
-     * @param {number} id loop ID
-     * @returns {number}
-     */
-    loop_read_vertex(id) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address);
-
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id loop ID
-     */
-    loop_write_vertex(id, value) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address, value);
-    }
-
-    /**
-     *
-     * @param {number} id loop ID
-     * @returns {number}
-     */
-    loop_read_edge(id) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + UINT_32_SIZE);
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id loop ID
-     */
-    loop_write_edge(id, value) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + UINT_32_SIZE, value);
-    }
-
-    /**
-     *
-     * @param {number} id loop ID
-     * @returns {number}
-     */
-    loop_read_face(id) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 2 * UINT_32_SIZE);
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id loop ID
-     */
-    loop_write_face(id, value) {
-        assert.isNonNegativeInteger(id, 'id');
-
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 2 * UINT_32_SIZE, value);
-    }
-
-    /**
-     *
-     * @param {number} id loop ID
-     * @returns {number}
-     */
-    loop_read_radial_next(id) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 3 * UINT_32_SIZE);
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id loop ID
-     */
-    loop_write_radial_next(id, value) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 3 * UINT_32_SIZE, value);
-    }
-
-    /**
-     *
-     * @param {number} id loop ID
-     * @returns {number}
-     */
-    loop_read_radial_prev(id) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 4 * UINT_32_SIZE);
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id loop ID
-     */
-    loop_write_radial_prev(id, value) {
-        assert.isNonNegativeInteger(id, 'id');
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 4 * UINT_32_SIZE, value);
-    }
-
-    /**
-     *
-     * @param {number} id loop ID
-     * @returns {number}
-     */
-    loop_read_next(id) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 5 * UINT_32_SIZE);
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id loop ID
-     */
-    loop_write_next(id, value) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 5 * UINT_32_SIZE, value);
-    }
-
-    /**
-     *
-     * @param {number} id loop ID
-     * @returns {number}
-     */
-    loop_read_prev(id) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address + 6 * UINT_32_SIZE);
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id loop ID
-     */
-    loop_write_prev(id, value) {
-        const pool = this.__loop_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address + 6 * UINT_32_SIZE, value);
-    }
-
-    /**
-     *
-     * @param {number} id face ID
-     * @returns {number}
-     */
-    face_read_loop(id) {
-        const pool = this.__face_pool;
-
-        const address = pool.element_address(id);
-        return pool.data_view.getUint32(address);
-    }
-
-    /**
-     *
-     * @param {number} value
-     * @param {number} id face ID
-     */
-    face_write_loop(id, value) {
-        const pool = this.__face_pool;
-
-        const address = pool.element_address(id);
-        pool.data_view.setUint32(address, value);
-    }
-
-    /**
-     * @param {number[]|ArrayLike<number>|Float32Array} result
-     * @param {number} result_offset
-     * @param {number} id face ID
-     */
-    face_read_normal(result, result_offset, id) {
-        const pool = this.__face_pool;
-        // Offset by the first loop pointer (UINT_32_SIZE)
-        const f_address = pool.element_address(id) + UINT_32_SIZE;
-        const f_offset = f_address >> 2;
-        result[result_offset] = pool.data_float32[f_offset];
-        result[result_offset + 1] = pool.data_float32[f_offset + 1];
-        result[result_offset + 2] = pool.data_float32[f_offset + 2];
-    }
-
-    /**
-     * @param {number} id face ID
-     * @param {number[]|Float32Array} value
-     * @param {number} value_offset
-     */
-    face_write_normal(id, value, value_offset) {
-        const pool = this.__face_pool;
-        const f_address = pool.element_address(id) + UINT_32_SIZE;
-        const f_offset = f_address >> 2;
-        pool.data_float32[f_offset] = value[value_offset];
-        pool.data_float32[f_offset + 1] = value[value_offset + 1];
-        pool.data_float32[f_offset + 2] = value[value_offset + 2];
-    }
-
-    /**
-     * Copy data from another mesh.
-     * @param {BinaryTopology} other
-     */
-    copy(other) {
-        assert.defined(other, 'other');
-        assert.notNull(other, 'other');
-        assert.isObject(other, 'other');
-        assert.equal(other.isBinaryTopology, true, 'other is not a BinaryTopology');
-
-        if (this === other) {
-            return;
-        }
-
-        this.__vertex_pool.copy(other.vertices);
-        this.__edge_pool.copy(other.edges);
-        this.__loop_pool.copy(other.loops);
-        this.__face_pool.copy(other.faces);
-
-        this.__vertex_data_block = copy_data_block(
-            this.__vertex_data_block, this.__vertex_pool, other.vertex_data
-        );
-        this.__edge_data_block = copy_data_block(
-            this.__edge_data_block, this.__edge_pool, other.edge_data
-        );
-        this.__loop_data_block = copy_data_block(
-            this.__loop_data_block, this.__loop_pool, other.loop_data
-        );
-        this.__face_data_block = copy_data_block(
-            this.__face_data_block, this.__face_pool, other.face_data
-        );
-    }
-
-    /**
-     *
-     * @returns {BinaryTopology}
-     */
-    clone() {
-        const clone = new BinaryTopology();
-        clone.copy(this);
-        return clone;
-    }
-
-}
-
-/**
- * Useful for type checking
- * @readonly
- * @type {boolean}
- */
+import { assert } from "../../../../../assert.js";
+import { BinaryDataBlock } from "./BinaryDataBlock.js";
+import { BinaryElementPool } from "./BinaryElementPool.js";
+
+/**
+ * Byte size of FLOAT_32
+ * @readonly
+ * @type {number}
+ */
+const FLOAT_32_SIZE = 4;
+
+/**
+ * Byte size of UINT_32
+ * @readonly
+ * @type {number}
+ */
+const UINT_32_SIZE = 4;
+
+/**
+ * @readonly
+ * @type {number}
+ */
+export const NULL_POINTER = 0xFFFFFFFF;
+
+
+/*
+Heavily influenced by blender's internal mesh structure.
+@see https://github.com/blender/blender/blob/master/source/blender/bmesh/bmesh_class.h
+ */
+
+/**
+ * Bring one mesh's data block into line with another's, creating or dropping it as needed.
+ *
+ * The block is rebuilt rather than shared, so layer handles into `target` do not survive this —
+ * whoever held them reads the new ones off {@link BinaryDataBlock#layers}.
+ *
+ * @param {BinaryDataBlock|null} target block currently held, if any
+ * @param {BinaryElementPool} base pool the block belongs to, for when one has to be made
+ * @param {BinaryDataBlock|null} source block to take after
+ * @returns {BinaryDataBlock|null}
+ */
+function copy_data_block(target, base, source) {
+    if (source === null) {
+        return null;
+    }
+
+    const result = target === null ? new BinaryDataBlock(base) : target;
+
+    result.copy(source);
+
+    // The pools were copied first, and a pool that reallocated to fit may have landed on more
+    // capacity than the one it copied from.
+    result.sync_capacity();
+
+    return result;
+}
+
+/**
+ * A high-performance memory-efficient, binary-backed topological data structure for representing 3D meshes.
+ * Manages interconnected vertices, edges, loops, and faces using contiguous memory pools.
+ */
+export class BinaryTopology {
+    /**
+     * structure:
+     *      coordinate: float32[3] // vertex coordinates
+     *      normal: float32[3] // vertex normal
+     *      edge_pointer: uint32 // Pointer to (any) edge using this vertex (for disk cycles)
+     *
+     * @type {BinaryElementPool}
+     * @private
+     */
+    __vertex_pool = new BinaryElementPool(3 * FLOAT_32_SIZE + 3 * FLOAT_32_SIZE + UINT_32_SIZE);
+
+    /**
+     * structure:
+     *      v1: uint32 // Vertices (unordered)
+     *      v2: uint32 // Vertices (unordered)
+     *      l: uint32 // The list of loops around the edge points at a Loop
+     *      v1_disk_link: uint32[2] // Disk Cycle Pointers edge around vertex v1 and d2 does the same for v2.
+     *      v2_disk_link: uint32[2] // see above
+     *
+     * Disk cycle convention:
+     *   For every vertex v with at least one incident edge, the edges incident
+     *   to v form a doubly-linked cycle threaded through their disk_link slots.
+     *   Each non-self-loop edge e uses exactly ONE slot in v's cycle: the v1
+     *   slot if `vertex1(e) === v`, otherwise the v2 slot. Callers select the
+     *   side with `is_v1 = edge_read_vertex1(e) === v`.
+     *
+     *   Self-loops (vertex1(e) === vertex2(e) === v) are represented with ONE
+     *   slot too, by convention the v1 slot. The v2_disk_link of a self-loop is
+     *   UNSPECIFIED -- readers must not follow it, writers must not assume any
+     *   prior value. Insertion/removal helpers must be called exactly once per
+     *   self-loop (not once per "endpoint"), otherwise the v1 slot is scribbled
+     *   on a second time and the cycle is corrupted.
+     * @type {BinaryElementPool}
+     * @private
+     */
+    __edge_pool = new BinaryElementPool(UINT_32_SIZE * 7);
+
+    /**
+     * Loop represents a corner of the face
+     * structure:
+     *      v: uint32 // The vertex this loop points to. This vertex must be unique within the cycle
+     *      e: uint32 // The edge this loop uses.
+     *      f: uint32 // The face this loop is part of.
+     *      radial_next: uint32 // Other loops connected to this edge.
+     *      radial_prev: uint32
+     *      next: uint32 // Other loops that are part of this face.
+     *      prev: uint32
+     * @type {BinaryElementPool}
+     * @private
+     */
+    __loop_pool = new BinaryElementPool(UINT_32_SIZE * 7);
+
+    /**
+     * structure:
+     *      l_first: uint32 // first loop pointer
+     *      no: float32[3] // Face normal
+     * @type {BinaryElementPool}
+     * @private
+     */
+    __face_pool = new BinaryElementPool(UINT_32_SIZE + FLOAT_32_SIZE * 3);
+
+    /**
+     * Optional per-vertex attribute storage. Record IDs are vertex IDs.
+     * Null until {@link vertex_data_add_layer} is called.
+     * @type {BinaryDataBlock|null}
+     * @private
+     */
+    __vertex_data_block = null;
+
+    /**
+     * Optional per-edge attribute storage. See {@link __vertex_data_block}.
+     * @type {BinaryDataBlock|null}
+     * @private
+     */
+    __edge_data_block = null;
+
+    /**
+     * Optional per-loop attribute storage. See {@link __vertex_data_block}.
+     * @type {BinaryDataBlock|null}
+     * @private
+     */
+    __loop_data_block = null;
+
+    /**
+     * Optional per-face attribute storage. See {@link __vertex_data_block}.
+     * @type {BinaryDataBlock|null}
+     * @private
+     */
+    __face_data_block = null;
+
+
+    /**
+     * Total (approximate) size of this structure in memory, in bytes
+     * @return {number}
+     */
+    get byteSize() {
+        let total = this.__loop_pool.byteSize
+            + this.__vertex_pool.byteSize
+            + this.__edge_pool.byteSize
+            + this.__face_pool.byteSize;
+
+        if (this.__vertex_data_block !== null) total += this.__vertex_data_block.byteSize;
+        if (this.__edge_data_block !== null) total += this.__edge_data_block.byteSize;
+        if (this.__loop_data_block !== null) total += this.__loop_data_block.byteSize;
+        if (this.__face_data_block !== null) total += this.__face_data_block.byteSize;
+
+        return total;
+    }
+
+    /**
+     * Releases excess memory held by internal pools.
+     * Useful for serialization use cases.
+     */
+    trim() {
+        this.__loop_pool.trim();
+        this.__vertex_pool.trim();
+        this.__edge_pool.trim();
+        this.__face_pool.trim();
+
+        if (this.__vertex_data_block !== null) this.__vertex_data_block.trim();
+        if (this.__edge_data_block !== null) this.__edge_data_block.trim();
+        if (this.__loop_data_block !== null) this.__loop_data_block.trim();
+        if (this.__face_data_block !== null) this.__face_data_block.trim();
+    }
+
+    /**
+     *
+     * @return {BinaryElementPool}
+     */
+    get vertices() {
+        return this.__vertex_pool;
+    }
+
+    /**
+     * Edges are shared among faces, edges point to 2 unordered vertices
+     * @return {BinaryElementPool}
+     */
+    get edges() {
+        return this.__edge_pool;
+    }
+
+    /**
+     * Loops are corners of faces, a single vertex can be associated with many loops, one per connected face
+     * @return {BinaryElementPool}
+     */
+    get loops() {
+        return this.__loop_pool;
+    }
+
+    /**
+     *
+     * @returns {BinaryElementPool}
+     */
+    get faces() {
+        return this.__face_pool;
+    }
+
+    /**
+     * Per-vertex attribute storage: one interleaved record per vertex, addressed by vertex ID,
+     * carrying every layer declared through {@link vertex_data_add_layer}.
+     *
+     * Reading and writing goes through the layer handles that call returned, not through here —
+     * this is the raw block, for the passes that move whole records around.
+     *
+     * @returns {BinaryDataBlock|null} null until a layer has been declared
+     */
+    get vertex_data() {
+        return this.__vertex_data_block;
+    }
+
+    /**
+     * Per-edge attribute storage. See {@link vertex_data}.
+     * @returns {BinaryDataBlock|null} null until a layer has been declared
+     */
+    get edge_data() {
+        return this.__edge_data_block;
+    }
+
+    /**
+     * Per-loop attribute storage. See {@link vertex_data}.
+     * @returns {BinaryDataBlock|null} null until a layer has been declared
+     */
+    get loop_data() {
+        return this.__loop_data_block;
+    }
+
+    /**
+     * Per-face attribute storage. See {@link vertex_data}.
+     * @returns {BinaryDataBlock|null} null until a layer has been declared
+     */
+    get face_data() {
+        return this.__face_data_block;
+    }
+
+    /**
+     * Declare a per-vertex attribute, creating the vertex data block if this is its first.
+     *
+     * The returned handle is the way in and out of that attribute; hold on to it. It carries its
+     * own compiled accessors, so nothing has to look it up by name and two attributes of the same
+     * shape never collide.
+     *
+     * Declaring a layer on a mesh that already has vertices is fine — the existing records are
+     * widened in place and keep their contents, which is what lets a pass attach data to a mesh it
+     * did not build.
+     *
+     * @param {BinaryDataType} type
+     * @param {number} components 3 for a vec3
+     * @returns {BinaryDataLayer}
+     */
+    vertex_data_add_layer(type, components) {
+        if (this.__vertex_data_block === null) {
+            this.__vertex_data_block = new BinaryDataBlock(this.__vertex_pool);
+        }
+
+        const layer = this.__vertex_data_block.add_layer(type, components);
+
+        this.__vertex_data_block.sync_capacity();
+
+        return layer;
+    }
+
+    /**
+     * Declare a per-edge attribute. See {@link vertex_data_add_layer}.
+     * @param {BinaryDataType} type
+     * @param {number} components
+     * @returns {BinaryDataLayer}
+     */
+    edge_data_add_layer(type, components) {
+        if (this.__edge_data_block === null) {
+            this.__edge_data_block = new BinaryDataBlock(this.__edge_pool);
+        }
+
+        const layer = this.__edge_data_block.add_layer(type, components);
+
+        this.__edge_data_block.sync_capacity();
+
+        return layer;
+    }
+
+    /**
+     * Declare a per-loop attribute. See {@link vertex_data_add_layer}.
+     * @param {BinaryDataType} type
+     * @param {number} components
+     * @returns {BinaryDataLayer}
+     */
+    loop_data_add_layer(type, components) {
+        if (this.__loop_data_block === null) {
+            this.__loop_data_block = new BinaryDataBlock(this.__loop_pool);
+        }
+
+        const layer = this.__loop_data_block.add_layer(type, components);
+
+        this.__loop_data_block.sync_capacity();
+
+        return layer;
+    }
+
+    /**
+     * Declare a per-face attribute. See {@link vertex_data_add_layer}.
+     * @param {BinaryDataType} type
+     * @param {number} components
+     * @returns {BinaryDataLayer}
+     */
+    face_data_add_layer(type, components) {
+        if (this.__face_data_block === null) {
+            this.__face_data_block = new BinaryDataBlock(this.__face_pool);
+        }
+
+        const layer = this.__face_data_block.add_layer(type, components);
+
+        this.__face_data_block.sync_capacity();
+
+        return layer;
+    }
+
+    /**
+     * @returns {boolean} true if a data block was removed, false if there was none
+     */
+    delete_vertex_data() {
+        if (this.__vertex_data_block === null) {
+            return false;
+        }
+        this.__vertex_data_block = null;
+        return true;
+    }
+
+    /**
+     * @returns {boolean} true if a data block was removed, false if there was none
+     */
+    delete_edge_data() {
+        if (this.__edge_data_block === null) {
+            return false;
+        }
+        this.__edge_data_block = null;
+        return true;
+    }
+
+    /**
+     * @returns {boolean} true if a data block was removed, false if there was none
+     */
+    delete_loop_data() {
+        if (this.__loop_data_block === null) {
+            return false;
+        }
+        this.__loop_data_block = null;
+        return true;
+    }
+
+    /**
+     * @returns {boolean} true if a data block was removed, false if there was none
+     */
+    delete_face_data() {
+        if (this.__face_data_block === null) {
+            return false;
+        }
+        this.__face_data_block = null;
+        return true;
+    }
+
+    /**
+     * Clear the topology, removed all data
+     */
+    clear() {
+        this.__vertex_pool.clear();
+        this.__edge_pool.clear();
+        this.__loop_pool.clear();
+        this.__face_pool.clear();
+
+        // The data blocks hold no size of their own, so there is nothing in them to clear: with the
+        // pools empty, no element id reaches a record any more. Their layout and capacity are
+        // deliberately retained, exactly as the pools retain theirs — the next mesh built into this
+        // topology keeps the layers that were declared on it, and its first elements inherit the
+        // bytes the last mesh left, on the terms {@link vertex_create} sets out.
+    }
+
+    /**
+     *
+     * @param {number[]|ArrayLike<number>|Float32Array} result
+     * @param {number} result_offset
+     * @param {number} id vertex ID
+     */
+    vertex_read_coordinate(result, result_offset, id) {
+        const pool = this.__vertex_pool;
+
+        const v_address = pool.element_address(id);
+        const v_offset = v_address >> 2; // get 4-byte boundary
+        result[result_offset] = pool.data_float32[v_offset];
+        result[result_offset + 1] = pool.data_float32[v_offset + 1];
+        result[result_offset + 2] = pool.data_float32[v_offset + 2];
+    }
+
+    /**
+     *
+     * @param {number} id
+     * @param {number[]|Float32Array} value
+     * @param {number} value_offset
+     */
+    vertex_write_coordinate(id, value, value_offset) {
+        const pool = this.__vertex_pool;
+
+        const v_address = pool.element_address(id);
+        const v_offset = v_address >> 2; // get 4-byte boundary
+        pool.data_float32[v_offset] = value[value_offset];
+        pool.data_float32[v_offset + 1] = value[value_offset + 1];
+        pool.data_float32[v_offset + 2] = value[value_offset + 2];
+    }
+
+    /**
+     *
+     * @param {number[]|ArrayLike<number>|Float32Array} result
+     * @param {number} result_offset
+     * @param {number} id vertex ID
+     */
+    vertex_read_normal(result, result_offset, id) {
+        const pool = this.__vertex_pool;
+
+        const v_address = pool.element_address(id) + 3 * FLOAT_32_SIZE;
+        const v_offset = v_address >> 2; // get 4-byte boundary
+        result[result_offset] = pool.data_float32[v_offset];
+        result[result_offset + 1] = pool.data_float32[v_offset + 1];
+        result[result_offset + 2] = pool.data_float32[v_offset + 2];
+    }
+
+    /**
+     *
+     * @param {number} id
+     * @param {number[]|Float32Array} value
+     * @param {number} value_offset
+     */
+    vertex_write_normal(id, value, value_offset) {
+        const pool = this.__vertex_pool;
+
+        const v_address = pool.element_address(id) + 3 * FLOAT_32_SIZE;
+        const v_offset = v_address >> 2; // get 4-byte boundary
+        pool.data_float32[v_offset] = value[value_offset];
+        pool.data_float32[v_offset + 1] = value[value_offset + 1];
+        pool.data_float32[v_offset + 2] = value[value_offset + 2];
+    }
+
+    /**
+     * @param {number} id
+     * @returns {number}
+     */
+    vertex_read_edge(id) {
+        const pool = this.__vertex_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 6 * UINT_32_SIZE);
+
+    }
+
+    /**
+     *
+     * @param {number} edge_id
+     * @param {number} id
+     */
+    vertex_write_edge(id, edge_id) {
+        const pool = this.__vertex_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 6 * UINT_32_SIZE, edge_id);
+    }
+
+    /**
+     * @param {number} id edge ID
+     * @returns {number}
+     */
+    edge_read_vertex1(id) {
+        const pool = this.__edge_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address);
+
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id edge ID
+     */
+    edge_write_vertex1(id, value) {
+        const pool = this.__edge_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address, value);
+    }
+
+    /**
+     * @param {number} id edge ID
+     * @returns {number}
+     */
+    edge_read_vertex2(id) {
+        const pool = this.__edge_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + UINT_32_SIZE);
+
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id edge ID
+     */
+    edge_write_vertex2(id, value) {
+        const pool = this.__edge_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + UINT_32_SIZE, value);
+    }
+
+
+    /**
+     * @param {number} id edge ID
+     * @returns {number}
+     */
+    edge_read_loop(id) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__edge_pool;
+
+        assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 2 * UINT_32_SIZE);
+
+    }
+
+    /**
+     *
+     * @param {number} loop_id loop ID
+     * @param {number} id edge ID
+     */
+    edge_write_loop(id, loop_id) {
+        const pool = this.__edge_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 2 * UINT_32_SIZE, loop_id);
+    }
+
+    /**
+     * @param {number} id edge ID
+     * @returns {number} edge ID
+     */
+    edge_read_v1_disk_next(id) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__edge_pool;
+
+        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 3 * UINT_32_SIZE);
+
+    }
+
+    /**
+     *
+     * @param {number} value edge ID
+     * @param {number} id edge ID
+     */
+    edge_write_v1_disk_next(id, value) {
+        const pool = this.__edge_pool;
+
+        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 3 * UINT_32_SIZE, value);
+    }
+
+    /**
+     * @param {number} id edge ID
+     * @returns {number} edge ID
+     */
+    edge_read_v1_disk_prev(id) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__edge_pool;
+
+        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 4 * UINT_32_SIZE);
+
+    }
+
+    /**
+     *
+     * @param {number} value edge ID
+     * @param {number} id edge ID
+     */
+    edge_write_v1_disk_prev(id, value) {
+        const pool = this.__edge_pool;
+
+        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 4 * UINT_32_SIZE, value);
+    }
+
+    /**
+     * @param {number} id edge ID
+     * @returns {number} edge ID
+     */
+    edge_read_v2_disk_next(id) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__edge_pool;
+
+        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 5 * UINT_32_SIZE);
+
+    }
+
+    /**
+     *
+     * @param {number} value edge ID
+     * @param {number} id edge ID
+     */
+    edge_write_v2_disk_next(id, value) {
+        const pool = this.__edge_pool;
+
+        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 5 * UINT_32_SIZE, value);
+    }
+
+    /**
+     * @param {number} id edge ID
+     * @returns {number} edge ID
+     */
+    edge_read_v2_disk_prev(id) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__edge_pool;
+
+        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 6 * UINT_32_SIZE);
+
+    }
+
+    /**
+     *
+     * @param {number} value edge ID
+     * @param {number} id edge ID
+     */
+    edge_write_v2_disk_prev(id, value) {
+        const pool = this.__edge_pool;
+
+        // assert.equal(pool.is_allocated(id), true, 'element is not allocated');
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 6 * UINT_32_SIZE, value);
+    }
+
+    /**
+     * Allocate a new vertex, growing the vertex data block to match.
+     *
+     * Element lifetime is the topology's to manage, not the pool's: go through here and
+     * {@link vertex_destroy} rather than reaching for `vertices.allocate()`/`vertices.release()`,
+     * or the attribute storage is left behind. The block has no allocator of its own to drive —
+     * capacity is the only thing there is to keep in step.
+     *
+     * @returns {number} vertex ID
+     */
+    vertex_create() {
+        const id = this.__vertex_pool.allocate();
+
+        this.__vertex_data_block?.sync_capacity();
+
+        return id;
+    }
+
+    /**
+     * Allocate a contiguous run of vertex IDs. See {@link vertex_create}.
+     * @param {number} count
+     * @returns {number} first ID of the run
+     */
+    vertices_create_continuous(count) {
+        const offset = this.__vertex_pool.allocate_continuous(count);
+
+        this.__vertex_data_block?.sync_capacity();
+
+        return offset;
+    }
+
+    /**
+     * Free a vertex. See {@link vertex_create}.
+     *
+     * The vertex's record is left as it lies — nothing reads a dead ID, and a later
+     * {@link vertex_create} reusing the slot inherits whatever was there. A caller that needs a
+     * fresh vertex to start from a known value writes it.
+     *
+     * @param {number} id vertex ID
+     */
+    vertex_destroy(id) {
+        this.__vertex_pool.release(id);
+    }
+
+    /**
+     * Allocate a new edge. See {@link vertex_create}.
+     * @returns {number} edge ID
+     */
+    edge_create() {
+        const id = this.__edge_pool.allocate();
+
+        this.__edge_data_block?.sync_capacity();
+
+        return id;
+    }
+
+    /**
+     * Free an edge. See {@link vertex_destroy}.
+     * @param {number} id edge ID
+     */
+    edge_destroy(id) {
+        this.__edge_pool.release(id);
+    }
+
+    /**
+     * Allocate a new face. See {@link vertex_create}.
+     * @returns {number} face ID
+     */
+    face_create() {
+        const id = this.__face_pool.allocate();
+
+        this.__face_data_block?.sync_capacity();
+
+        return id;
+    }
+
+    /**
+     * Allocate a contiguous run of face IDs. See {@link vertex_create}.
+     * @param {number} count
+     * @returns {number} first ID of the run
+     */
+    faces_create_continuous(count) {
+        const offset = this.__face_pool.allocate_continuous(count);
+
+        this.__face_data_block?.sync_capacity();
+
+        return offset;
+    }
+
+    /**
+     * Free a face. See {@link vertex_destroy}.
+     * @param {number} id face ID
+     */
+    face_destroy(id) {
+        this.__face_pool.release(id);
+    }
+
+    /**
+     * Allocate a new loop and put it into a valid initial state.
+     * See {@link vertex_create} for the data block semantics.
+     * @returns {number} loop ID
+     */
+    loop_create() {
+        const id = this.__loop_pool.allocate();
+
+        this.__loop_data_block?.sync_capacity();
+
+        this.loop_initialize(id);
+
+        return id;
+    }
+
+    /**
+     * Free a loop. See {@link vertex_destroy}.
+     * @param {number} id loop ID
+     */
+    loop_destroy(id) {
+        this.__loop_pool.release(id);
+    }
+
+    /**
+     * Put loop into valid initial state, set all pointers to NULL
+     * @param {number} id
+     */
+    loop_initialize(id) {
+        this.loop_write_radial_next(id, id);
+        this.loop_write_radial_prev(id, id);
+        this.loop_write_next(id, id);
+        this.loop_write_prev(id, id);
+    }
+
+    /**
+     * @param {number} id loop ID
+     * @returns {number}
+     */
+    loop_read_vertex(id) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address);
+
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id loop ID
+     */
+    loop_write_vertex(id, value) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address, value);
+    }
+
+    /**
+     *
+     * @param {number} id loop ID
+     * @returns {number}
+     */
+    loop_read_edge(id) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + UINT_32_SIZE);
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id loop ID
+     */
+    loop_write_edge(id, value) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + UINT_32_SIZE, value);
+    }
+
+    /**
+     *
+     * @param {number} id loop ID
+     * @returns {number}
+     */
+    loop_read_face(id) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 2 * UINT_32_SIZE);
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id loop ID
+     */
+    loop_write_face(id, value) {
+        assert.isNonNegativeInteger(id, 'id');
+
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 2 * UINT_32_SIZE, value);
+    }
+
+    /**
+     *
+     * @param {number} id loop ID
+     * @returns {number}
+     */
+    loop_read_radial_next(id) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 3 * UINT_32_SIZE);
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id loop ID
+     */
+    loop_write_radial_next(id, value) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 3 * UINT_32_SIZE, value);
+    }
+
+    /**
+     *
+     * @param {number} id loop ID
+     * @returns {number}
+     */
+    loop_read_radial_prev(id) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 4 * UINT_32_SIZE);
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id loop ID
+     */
+    loop_write_radial_prev(id, value) {
+        assert.isNonNegativeInteger(id, 'id');
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 4 * UINT_32_SIZE, value);
+    }
+
+    /**
+     *
+     * @param {number} id loop ID
+     * @returns {number}
+     */
+    loop_read_next(id) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 5 * UINT_32_SIZE);
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id loop ID
+     */
+    loop_write_next(id, value) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 5 * UINT_32_SIZE, value);
+    }
+
+    /**
+     *
+     * @param {number} id loop ID
+     * @returns {number}
+     */
+    loop_read_prev(id) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address + 6 * UINT_32_SIZE);
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id loop ID
+     */
+    loop_write_prev(id, value) {
+        const pool = this.__loop_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address + 6 * UINT_32_SIZE, value);
+    }
+
+    /**
+     *
+     * @param {number} id face ID
+     * @returns {number}
+     */
+    face_read_loop(id) {
+        const pool = this.__face_pool;
+
+        const address = pool.element_address(id);
+        return pool.data_view.getUint32(address);
+    }
+
+    /**
+     *
+     * @param {number} value
+     * @param {number} id face ID
+     */
+    face_write_loop(id, value) {
+        const pool = this.__face_pool;
+
+        const address = pool.element_address(id);
+        pool.data_view.setUint32(address, value);
+    }
+
+    /**
+     * @param {number[]|ArrayLike<number>|Float32Array} result
+     * @param {number} result_offset
+     * @param {number} id face ID
+     */
+    face_read_normal(result, result_offset, id) {
+        const pool = this.__face_pool;
+        // Offset by the first loop pointer (UINT_32_SIZE)
+        const f_address = pool.element_address(id) + UINT_32_SIZE;
+        const f_offset = f_address >> 2;
+        result[result_offset] = pool.data_float32[f_offset];
+        result[result_offset + 1] = pool.data_float32[f_offset + 1];
+        result[result_offset + 2] = pool.data_float32[f_offset + 2];
+    }
+
+    /**
+     * @param {number} id face ID
+     * @param {number[]|Float32Array} value
+     * @param {number} value_offset
+     */
+    face_write_normal(id, value, value_offset) {
+        const pool = this.__face_pool;
+        const f_address = pool.element_address(id) + UINT_32_SIZE;
+        const f_offset = f_address >> 2;
+        pool.data_float32[f_offset] = value[value_offset];
+        pool.data_float32[f_offset + 1] = value[value_offset + 1];
+        pool.data_float32[f_offset + 2] = value[value_offset + 2];
+    }
+
+    /**
+     * Copy data from another mesh.
+     * @param {BinaryTopology} other
+     */
+    copy(other) {
+        assert.defined(other, 'other');
+        assert.notNull(other, 'other');
+        assert.isObject(other, 'other');
+        assert.equal(other.isBinaryTopology, true, 'other is not a BinaryTopology');
+
+        if (this === other) {
+            return;
+        }
+
+        this.__vertex_pool.copy(other.vertices);
+        this.__edge_pool.copy(other.edges);
+        this.__loop_pool.copy(other.loops);
+        this.__face_pool.copy(other.faces);
+
+        this.__vertex_data_block = copy_data_block(
+            this.__vertex_data_block, this.__vertex_pool, other.vertex_data
+        );
+        this.__edge_data_block = copy_data_block(
+            this.__edge_data_block, this.__edge_pool, other.edge_data
+        );
+        this.__loop_data_block = copy_data_block(
+            this.__loop_data_block, this.__loop_pool, other.loop_data
+        );
+        this.__face_data_block = copy_data_block(
+            this.__face_data_block, this.__face_pool, other.face_data
+        );
+    }
+
+    /**
+     *
+     * @returns {BinaryTopology}
+     */
+    clone() {
+        const clone = new BinaryTopology();
+        clone.copy(this);
+        return clone;
+    }
+
+}
+
+/**
+ * Useful for type checking
+ * @readonly
+ * @type {boolean}
+ */
 BinaryTopology.prototype.isBinaryTopology = true;