@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VirtualGeometryMesh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/VirtualGeometryMesh.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA8CI;;;;;;;;;;;;;;OAcG;IACH,0CAFa,mBAAmB,CA+H/B;IA1JD;;;OAGG;IACH,sBAHW,cAAc,UACd,CAAC,kBAAgB,IAAI,CAAC,EAAE,EAUlC;IA3CD;;;OAGG;IACH,UAFU,cAAc,CAER;IAEhB;;;;;;OAMG;IACH,QAFU,CAAC,kBAAgB,IAAI,CAAC,EAAE,CAEtB;IAEZ;;;;;;;;;;;;;OAaG;IACH,aAFU,OAAO,EAAE,CAEyC;IA8J5D;;;OAGG;IACH,YAFa,MAAM,EAAE,CAcpB;CACJ;+BA1O8B,yEAAyE"}

package/src/shade/renderer/geometry/virtual/build/{VirtualGeometryMesh.js → mesh/VirtualGeometryMesh.js}

@@ -1,22 +1,26 @@
-import { assert } from "../../../../../core/assert.js";
-import { BinaryTopology } from "../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
+import { assert } from "../../../../../../core/assert.js";
+import { BinaryTopology } from "../../../../../../core/geom/3d/topology/struct/binary/BinaryTopology.js";
 import {
     bt_mesh_from_indexed_geometry
-} from "../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
-import { StandardAttributes } from "../../StandardAttributes.js";
-import { vgeo_layers_declare } from "../format/attribute/vgeo_layers_declare.js";
-import { VGEO_ATTRIBUTE } from "../format/attribute/VGEO_ATTRIBUTE.js";
-import { VGEO_ATTRIBUTES } from "../format/attribute/VGEO_ATTRIBUTES.js";
+} from "../../../../../../core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js";
+import { StandardAttributes } from "../../../StandardAttributes.js";
+import { vgeo_layers_declare } from "../../format/attribute/vgeo_layers_declare.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+import { VGEO_ATTRIBUTES } from "../../format/attribute/VGEO_ATTRIBUTES.js";
 
 /**
  * A level of geometry as the builder handles it: a `BinaryTopology` carrying the positions, the
  * connectivity, and the per-vertex attributes all together.
  *
- * Everything per-vertex lives in the topology. It has to: an edge collapse moves and removes
- * vertices, and the topology is the only thing that knows which. A vertex data layer is addressed
- * by vertex id and sized by the vertex pool, so a channel cannot fall out of step with the mesh it
- * describes — there is no second array to resize, no invariant to assert, and no way for the
- * simplifier to leave a live vertex without a slot.
+ * Everything per-element lives in the topology. It has to: a collapse moves and removes vertices and
+ * kills faces, and the topology is the only thing that knows which. A data layer is sized by its own
+ * pool, so a channel cannot fall out of step with the mesh it describes — there is no second array
+ * to resize, no invariant to assert, and no way for the simplifier to leave a live element without a
+ * slot.
+ *
+ * **Position is the vertex's; appearance is the corner's.** A hard edge and a texture seam are both
+ * one geometric vertex that shades two ways, and no per-vertex record can hold that — so the
+ * channels are loop data. See `WEDGE_PLAN_2026_09_18.md` §2.
  *
  * The channels are named by their index into {@link VGEO_ATTRIBUTES}, which is the format's frozen
  * table — {@link layers} has one slot per entry, holding a layer or null.
@@ -32,9 +36,10 @@ export class VirtualGeometryMesh {
     topology = null;
 
     /**
-     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the vertex data layer that carries that
+     * One slot per {@link VGEO_ATTRIBUTES} entry, holding the **loop** data layer that carries that
      * channel or null where this geometry does not carry it.
-     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own.
+     * {@link VGEO_ATTRIBUTE.POSITION}'s slot is always null — position is the topology's own, and is
+     * the one value that really is a vertex's rather than a corner's.
      * @type {(BinaryDataLayer|null)[]}
      */
     layers = [];
@@ -163,14 +168,17 @@ export class VirtualGeometryMesh {
 
         const topology = new BinaryTopology();
 
-        // Declared before the vertices exist: adding a layer widens every record already in the
-        // block, so a channel set is cheapest to state while there is nothing to widen.
+        // Declared before the mesh exists: adding a layer widens every record already in the block,
+        // and the block these go in is the *loop* block, which a triangulated source fills three
+        // records at a time. Cheapest to state while there is nothing to widen.
         const layers = vgeo_layers_declare(topology, carried);
 
         bt_mesh_from_indexed_geometry(
             topology, indices.subarray(0, triangle_count * 3), position.data
         );
 
+        const loop_pool = topology.loops;
+
         for (let attribute = 0; attribute < VGEO_ATTRIBUTES.length; attribute++) {
             const layer = layers[attribute];
 
@@ -182,8 +190,22 @@ export class VirtualGeometryMesh {
             const source = sources[attribute];
             const components = VGEO_ATTRIBUTES[attribute].components;
 
-            for (let vertex = 0; vertex < vertex_count; vertex++) {
-                layer.write(vertex, source.data, vertex * components);
+            /*
+             Per corner, through the vertex it names. A geometry's own attributes are per vertex,
+             which is the representation that cannot hold a seam — what a source splits, it splits by
+             *duplicating the vertex*, and the weld in `vgeo_normalize_source` is what then throws
+             that away. Reading them out per corner here is what gives the weld something to preserve
+             (`WEDGE_PLAN_2026_09_18.md` §6.2); until it does, every corner of a vertex gets the same
+             value and nothing downstream can tell.
+             */
+            for (let loop = 0; loop < loop_pool.size; loop++) {
+                if (!loop_pool.is_allocated(loop)) {
+                    continue;
+                }
+
+                layer.write(
+                    loop, source.data, topology.loop_read_vertex(loop) * components
+                );
             }
         }
 

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_layout.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Which of a mesh's channels travel through a collapse as plain numbers, and where each one sits in
+ * the flat vector that carries them.
+ *
+ * The simplifier moves vertices and merges them, and whatever a merged vertex is to shade as has to
+ * be decided *at the collapse*, from the values being merged — not re-derived afterwards from the
+ * coarse mesh, which is a different surface (`ATTRIBUTE_PLAN_2026_09_18.md` §1.2). So the channels
+ * are flattened into one array indexed by vertex, handed to the simplifier, and written back.
+ *
+ * Two channels are not simply `components` wide here:
+ *
+ * - **Position** is not in the vector at all. It lives in the topology, where the quadric solve
+ *   moves it.
+ * - **Tangent** contributes its `xyz` to the fitted vector and its fourth component to a second,
+ *   **verbatim** one. That component is a handedness flag — a discrete `±1` — and the average of
+ *   `+1` and `-1` is a number that means nothing, so it is carried rather than fitted: a survivor
+ *   keeps the flag it had.
+ *
+ *   It has to be *carried*, and leaving the stored record alone is not enough. A collapse re-points
+ *   the victim's corners onto the survivor and they arrive with the victim's flag, so "the
+ *   survivor's" has to be written back over them — which is what the verbatim vector is for. Left
+ *   alone, one vertex of a cube-sphere comes out of a cut with two different tangents in two
+ *   payloads, and that is the seam invariant broken.
+ *
+ * And the tangent is here **only when the mesh carries `UV0`**. A tangent is a direction in the
+ * texture parameterization; with no parameterization there is nothing for it to be tangent to, and
+ * the frame is an arbitrary well-conditioned basis around the normal — which
+ * {@link vgeo_compute_vertex_tangents} already builds, on this same condition, and which is a *pure
+ * function of the normal*. Deriving it is therefore both cheaper and safer than carrying it:
+ * Frisvad's basis turns discontinuously with the normal, so two neighbours' tangents can be nearly
+ * opposite and average to nothing at all.
+ *
+ * @param {(BinaryDataLayer|null)[]} layers channel set, as {@link vgeo_layers_declare} builds one
+ * @returns {{components: number, channels: {attribute: number, offset: number, source: number, count: number}[], verbatim_components: number, verbatim: {attribute: number, offset: number, source: number, count: number}[]}}
+ *     two vectors: the one the simplifier fits, and the one it never touches. `source` is where a
+ *     channel's run starts *within the layer's own record*, which is `0` for everything but the
+ *     handedness. A mesh carrying no travelling channel at all comes back with zero of both.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_layout(layers: (BinaryDataLayer | null)[]): {
+    components: number;
+    channels: {
+        attribute: number;
+        offset: number;
+        source: number;
+        count: number;
+    }[];
+    verbatim_components: number;
+    verbatim: {
+        attribute: number;
+        offset: number;
+        source: number;
+        count: number;
+    }[];
+};
+//# sourceMappingURL=vgeo_attribute_vector_layout.d.ts.map

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_attribute_vector_layout.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_layout.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qDATW,CAAC,kBAAgB,IAAI,CAAC,EAAE,GACtB;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAA;CAAC,CA0C7N"}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_layout.js

@@ -0,0 +1,79 @@
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+import { VGEO_ATTRIBUTES } from "../../format/attribute/VGEO_ATTRIBUTES.js";
+
+/**
+ * Which of a mesh's channels travel through a collapse as plain numbers, and where each one sits in
+ * the flat vector that carries them.
+ *
+ * The simplifier moves vertices and merges them, and whatever a merged vertex is to shade as has to
+ * be decided *at the collapse*, from the values being merged — not re-derived afterwards from the
+ * coarse mesh, which is a different surface (`ATTRIBUTE_PLAN_2026_09_18.md` §1.2). So the channels
+ * are flattened into one array indexed by vertex, handed to the simplifier, and written back.
+ *
+ * Two channels are not simply `components` wide here:
+ *
+ * - **Position** is not in the vector at all. It lives in the topology, where the quadric solve
+ *   moves it.
+ * - **Tangent** contributes its `xyz` to the fitted vector and its fourth component to a second,
+ *   **verbatim** one. That component is a handedness flag — a discrete `±1` — and the average of
+ *   `+1` and `-1` is a number that means nothing, so it is carried rather than fitted: a survivor
+ *   keeps the flag it had.
+ *
+ *   It has to be *carried*, and leaving the stored record alone is not enough. A collapse re-points
+ *   the victim's corners onto the survivor and they arrive with the victim's flag, so "the
+ *   survivor's" has to be written back over them — which is what the verbatim vector is for. Left
+ *   alone, one vertex of a cube-sphere comes out of a cut with two different tangents in two
+ *   payloads, and that is the seam invariant broken.
+ *
+ * And the tangent is here **only when the mesh carries `UV0`**. A tangent is a direction in the
+ * texture parameterization; with no parameterization there is nothing for it to be tangent to, and
+ * the frame is an arbitrary well-conditioned basis around the normal — which
+ * {@link vgeo_compute_vertex_tangents} already builds, on this same condition, and which is a *pure
+ * function of the normal*. Deriving it is therefore both cheaper and safer than carrying it:
+ * Frisvad's basis turns discontinuously with the normal, so two neighbours' tangents can be nearly
+ * opposite and average to nothing at all.
+ *
+ * @param {(BinaryDataLayer|null)[]} layers channel set, as {@link vgeo_layers_declare} builds one
+ * @returns {{components: number, channels: {attribute: number, offset: number, source: number, count: number}[], verbatim_components: number, verbatim: {attribute: number, offset: number, source: number, count: number}[]}}
+ *     two vectors: the one the simplifier fits, and the one it never touches. `source` is where a
+ *     channel's run starts *within the layer's own record*, which is `0` for everything but the
+ *     handedness. A mesh carrying no travelling channel at all comes back with zero of both.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_layout(layers) {
+    const channels = [];
+    const verbatim = [];
+
+    let components = 0;
+    let verbatim_components = 0;
+
+    for (let attribute = 0; attribute < VGEO_ATTRIBUTES.length; attribute++) {
+        if (attribute === VGEO_ATTRIBUTE.POSITION || layers[attribute] === null) {
+            continue;
+        }
+
+        if (attribute === VGEO_ATTRIBUTE.TANGENT && layers[VGEO_ATTRIBUTE.UV0] === null) {
+            continue;
+        }
+
+        const count = attribute === VGEO_ATTRIBUTE.TANGENT
+            ? 3
+            : VGEO_ATTRIBUTES[attribute].components;
+
+        channels.push({ attribute, offset: components, source: 0, count });
+
+        components += count;
+
+        if (attribute === VGEO_ATTRIBUTE.TANGENT) {
+            verbatim.push({
+                attribute, offset: verbatim_components, source: 3, count: 1,
+            });
+
+            verbatim_components += 1;
+        }
+    }
+
+    return { components, channels, verbatim_components, verbatim };
+}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_read.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lift a mesh's travelling channels out of its layers and into one flat vector the simplifier can
+ * carry through a collapse.
+ *
+ * Indexed by **wedge id**, holes and all, so a set with merged-away slots needs no compaction and
+ * no remap — the simplifier addresses wedges by id and nothing else would line up. A dead slot
+ * holds whatever the wedge that used to be a root left behind, which nothing reads.
+ *
+ * The values are stored per *corner* and read per *wedge*, and a wedge is by definition a set of
+ * corners that carry the same value. Each corner of a wedge writes over the last and it does not
+ * matter which one wins — **which is a checkable claim rather than an assumed one**, and the
+ * difference from §6.1 is exactly that: there, a *vertex* was asserted to have one appearance, and
+ * a hard edge is a vertex that does not.
+ *
+ * Float64 rather than the layers' float32: a value is blended at every collapse it survives, dozens
+ * of times over a deep DAG, and rounding to storage precision at each step is error the vector has
+ * no reason to accumulate. It is narrowed once, on the way back out
+ * ({@link vgeo_attribute_vector_write}).
+ *
+ * Takes a stride and a channel list rather than the whole layout, because there are two vectors and
+ * they differ only in which list they are over — the one the simplifier fits, and the one it never
+ * touches (`vgeo_attribute_vector_layout`'s `verbatim`).
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {number} components stride of one wedge's record
+ * @param {{attribute: number, offset: number, source: number, count: number}[]} channels
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
+ * @returns {Float64Array} `wedges.count * components` elements
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_read(mesh: VirtualGeometryMesh, components: number, channels: {
+    attribute: number;
+    offset: number;
+    source: number;
+    count: number;
+}[], wedges: BtWedgeSet): Float64Array;
+//# sourceMappingURL=vgeo_attribute_vector_read.d.ts.map

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_attribute_vector_read.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_read.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,kFARW,MAAM,YACN;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAC,EAAE,uBAElE,YAAY,CAgCxB"}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_read.js

@@ -0,0 +1,68 @@
+import { assert } from "../../../../../../core/assert.js";
+
+/**
+ * One vertex's widest channel record on its way out of a layer.
+ * @type {Float32Array}
+ */
+const scratch_record = new Float32Array(4);
+
+/**
+ * Lift a mesh's travelling channels out of its layers and into one flat vector the simplifier can
+ * carry through a collapse.
+ *
+ * Indexed by **wedge id**, holes and all, so a set with merged-away slots needs no compaction and
+ * no remap — the simplifier addresses wedges by id and nothing else would line up. A dead slot
+ * holds whatever the wedge that used to be a root left behind, which nothing reads.
+ *
+ * The values are stored per *corner* and read per *wedge*, and a wedge is by definition a set of
+ * corners that carry the same value. Each corner of a wedge writes over the last and it does not
+ * matter which one wins — **which is a checkable claim rather than an assumed one**, and the
+ * difference from §6.1 is exactly that: there, a *vertex* was asserted to have one appearance, and
+ * a hard edge is a vertex that does not.
+ *
+ * Float64 rather than the layers' float32: a value is blended at every collapse it survives, dozens
+ * of times over a deep DAG, and rounding to storage precision at each step is error the vector has
+ * no reason to accumulate. It is narrowed once, on the way back out
+ * ({@link vgeo_attribute_vector_write}).
+ *
+ * Takes a stride and a channel list rather than the whole layout, because there are two vectors and
+ * they differ only in which list they are over — the one the simplifier fits, and the one it never
+ * touches (`vgeo_attribute_vector_layout`'s `verbatim`).
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {number} components stride of one wedge's record
+ * @param {{attribute: number, offset: number, source: number, count: number}[]} channels
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one
+ * @returns {Float64Array} `wedges.count * components` elements
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_read(mesh, components, channels, wedges) {
+    assert.greaterThan(components, 0, 'components');
+
+    const topology = mesh.topology;
+
+    const values = new Float64Array(wedges.count * components);
+
+    const loop_pool = topology.loops;
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        if (!loop_pool.is_allocated(loop)) {
+            continue;
+        }
+
+        const base = wedges.find(wedges.of_loop[loop]) * components;
+
+        for (const channel of channels) {
+            mesh.layers[channel.attribute].read(scratch_record, 0, loop);
+
+            for (let component = 0; component < channel.count; component++) {
+                values[base + channel.offset + component] =
+                    scratch_record[channel.source + component];
+            }
+        }
+    }
+
+    return values;
+}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_write.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Put the simplifier's vector back into the mesh's layers, and square up the frame it describes.
+ *
+ * **Nothing is *derived* for a pinned vertex.** That is the whole of what pinning means here and it
+ * is what lets a cut place two levels of detail side by side: a vertex two groups share must carry
+ * byte-identical values in both payloads, or the seam that is watertight in geometry shades as a
+ * crease (`ATTRIBUTE_PLAN_2026_09_18.md` §3, invariant 2).
+ *
+ * Its corners are still *written*, with what the vector says it already had, and that is not a
+ * loophole — it is the same guarantee under corner storage. A collapse re-points the victim's corners
+ * onto the survivor and they arrive carrying the victim's appearance, so leaving a pinned vertex
+ * alone no longer means leaving its value alone. The write is exact: those float32 records are where
+ * the vector was read from.
+ *
+ * Two channels need more than a copy:
+ *
+ * - **The normal** is renormalized. A blend of two unit vectors is not one, and a normal that is
+ *   not unit is not a normal. Two exactly opposing normals blend to nothing, which has no direction
+ *   to report and so keeps whatever the vertex already carried, the same answer
+ *   {@link bt_mesh_compute_vertex_normals} gives for a vertex whose faces cancel.
+ * - **The colour** is clamped to `[0, 1]`. The value a collapse carries is a *fit*, not an average,
+ *   and a fit extrapolates — which is right for a texture coordinate and wrong for a channel with a
+ *   range. The encoder saturates anyway, so what this stops is not a corrupt word but the drift:
+ *   an out-of-range value left in the layer is what the next level's field is fitted from, and it
+ *   would walk further out at every round.
+ * - **The tangent** is re-orthogonalized against that normal and renormalized, and its fourth
+ *   component — handedness, a discrete `±1` — is left exactly as the survivor had it, because it is
+ *   a flag rather than a quantity and there is no average of `+1` and `-1`. A tangent that has
+ *   blended its way onto the normal has no perpendicular component left to keep, and falls back to
+ *   Frisvad's basis rather than to a zero vector the octahedral encoder cannot represent.
+ *
+ * @param {VirtualGeometryMesh} mesh mutated in place
+ * @param {{components: number, channels: {attribute: number, offset: number, count: number}[]}} layout
+ *     from {@link vgeo_attribute_vector_layout}, the same one {@link vgeo_attribute_vector_read} used
+ * @param {Float64Array} values indexed by wedge id, as the simplifier left it
+ * @param {Float64Array|null} verbatim indexed by wedge id, as it was read — the simplifier does not
+ *     take it and has nothing to say about it. `null` where the layout has no such component, which
+ *     is every mesh whose tangent is derived rather than carried.
+ * @param {Set<number>} pinned vertex ids nothing may be *derived* for
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one, as the simplifier left it
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_write(mesh: VirtualGeometryMesh, layout: {
+    components: number;
+    channels: {
+        attribute: number;
+        offset: number;
+        count: number;
+    }[];
+}, values: Float64Array, verbatim: Float64Array | null, pinned: Set<number>, wedges: BtWedgeSet): void;
+//# sourceMappingURL=vgeo_attribute_vector_write.d.ts.map

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_attribute_vector_write.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_write.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,+EAZW;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAC,EAAE,CAAA;CAAC,UAEpF,YAAY,YACZ,YAAY,GAAC,IAAI,UAGjB,IAAI,MAAM,CAAC,4BAiHrB"}

package/src/shade/renderer/geometry/virtual/build/mesh/vgeo_attribute_vector_write.js

@@ -0,0 +1,243 @@
+import { assert } from "../../../../../../core/assert.js";
+import { build_tangent_from_normal } from "../../../normals/build_tangent_from_normal.js";
+import { VGEO_ATTRIBUTE } from "../../format/attribute/VGEO_ATTRIBUTE.js";
+
+/**
+ * One vertex's widest channel record on its way into a layer.
+ * @type {Float32Array}
+ */
+const scratch_record = new Float32Array(4);
+
+/**
+ * The normal the tangent of the same vertex is squared up against.
+ * @type {Float32Array}
+ */
+const scratch_normal = new Float32Array(3);
+
+/**
+ * Frisvad's basis, when the carried tangent has degenerated.
+ * @type {Float32Array}
+ */
+const scratch_fallback = new Float32Array(4);
+
+/**
+ * Put the simplifier's vector back into the mesh's layers, and square up the frame it describes.
+ *
+ * **Nothing is *derived* for a pinned vertex.** That is the whole of what pinning means here and it
+ * is what lets a cut place two levels of detail side by side: a vertex two groups share must carry
+ * byte-identical values in both payloads, or the seam that is watertight in geometry shades as a
+ * crease (`ATTRIBUTE_PLAN_2026_09_18.md` §3, invariant 2).
+ *
+ * Its corners are still *written*, with what the vector says it already had, and that is not a
+ * loophole — it is the same guarantee under corner storage. A collapse re-points the victim's corners
+ * onto the survivor and they arrive carrying the victim's appearance, so leaving a pinned vertex
+ * alone no longer means leaving its value alone. The write is exact: those float32 records are where
+ * the vector was read from.
+ *
+ * Two channels need more than a copy:
+ *
+ * - **The normal** is renormalized. A blend of two unit vectors is not one, and a normal that is
+ *   not unit is not a normal. Two exactly opposing normals blend to nothing, which has no direction
+ *   to report and so keeps whatever the vertex already carried, the same answer
+ *   {@link bt_mesh_compute_vertex_normals} gives for a vertex whose faces cancel.
+ * - **The colour** is clamped to `[0, 1]`. The value a collapse carries is a *fit*, not an average,
+ *   and a fit extrapolates — which is right for a texture coordinate and wrong for a channel with a
+ *   range. The encoder saturates anyway, so what this stops is not a corrupt word but the drift:
+ *   an out-of-range value left in the layer is what the next level's field is fitted from, and it
+ *   would walk further out at every round.
+ * - **The tangent** is re-orthogonalized against that normal and renormalized, and its fourth
+ *   component — handedness, a discrete `±1` — is left exactly as the survivor had it, because it is
+ *   a flag rather than a quantity and there is no average of `+1` and `-1`. A tangent that has
+ *   blended its way onto the normal has no perpendicular component left to keep, and falls back to
+ *   Frisvad's basis rather than to a zero vector the octahedral encoder cannot represent.
+ *
+ * @param {VirtualGeometryMesh} mesh mutated in place
+ * @param {{components: number, channels: {attribute: number, offset: number, count: number}[]}} layout
+ *     from {@link vgeo_attribute_vector_layout}, the same one {@link vgeo_attribute_vector_read} used
+ * @param {Float64Array} values indexed by wedge id, as the simplifier left it
+ * @param {Float64Array|null} verbatim indexed by wedge id, as it was read — the simplifier does not
+ *     take it and has nothing to say about it. `null` where the layout has no such component, which
+ *     is every mesh whose tangent is derived rather than carried.
+ * @param {Set<number>} pinned vertex ids nothing may be *derived* for
+ * @param {BtWedgeSet} wedges which corners of each vertex shade as one, as the simplifier left it
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_attribute_vector_write(mesh, layout, values, verbatim, pinned, wedges) {
+    assert.greaterThan(layout.components, 0, 'layout.components');
+
+    const topology = mesh.topology;
+
+    const components = layout.components;
+    const channels = layout.channels;
+
+    const normal_layer = mesh.layers[VGEO_ATTRIBUTE.NORMAL];
+
+    const carries_tangent = channels.some(
+        (channel) => channel.attribute === VGEO_ATTRIBUTE.TANGENT
+    );
+
+    /*
+     Over corners. The value is decided per *wedge* and stored per corner, so every corner of a wedge
+     gets the same one — and the frame fixups below, being functions of that value, agree corner for
+     corner without having to be told to. Two corners of one vertex in different wedges get different
+     ones, which is a hard edge, and is the entire point.
+     */
+    const loop_pool = topology.loops;
+
+    for (let loop = 0; loop < loop_pool.size; loop++) {
+        if (!loop_pool.is_allocated(loop)) {
+            continue;
+        }
+
+        const vertex = topology.loop_read_vertex(loop);
+
+        /*
+         A pinned vertex IS written, and writing it is what keeps it pinned. The vector holds what it
+         had -- nothing in the simplifier touches a restricted survivor's entry -- while its *corners*
+         do not, because a collapse re-points the victim's onto it and those arrive carrying the
+         victim's appearance. Writing the vector back over all of them is what puts that right, and it
+         is exact: the value came out of these same float32 records and goes back into them unchanged.
+
+         What it must not do is *derive* anything for a pinned vertex, so the fixups below are the
+         one thing that stays behind the flag.
+         */
+        const restore = pinned.has(vertex);
+
+        const wedge = wedges.find(wedges.of_loop[loop]);
+
+        const base = wedge * components;
+
+        for (const channel of channels) {
+            const layer = mesh.layers[channel.attribute];
+
+            // Read first: a channel the vector carries only part of — the tangent, whose handedness
+            // stays with the survivor — keeps the rest of its record this way.
+            layer.read(scratch_record, 0, loop);
+
+            for (let component = 0; component < channel.count; component++) {
+                const value = values[base + channel.offset + component];
+
+                assert.isFinite(value, 'carried attribute component');
+
+                scratch_record[channel.source + component] = value;
+            }
+
+            if (restore) {
+                layer.write(loop, scratch_record, 0);
+
+                continue;
+            }
+
+            if (channel.attribute === VGEO_ATTRIBUTE.NORMAL) {
+                normalize_in_place(scratch_record, layer, loop);
+            } else if (channel.attribute === VGEO_ATTRIBUTE.COLOR) {
+                for (let component = 0; component < channel.count; component++) {
+                    scratch_record[component] = Math.min(1, Math.max(0, scratch_record[component]));
+                }
+            }
+
+            layer.write(loop, scratch_record, 0);
+        }
+
+        // After the loop rather than inside it, so the normal it squares up against is the one just
+        // written rather than whichever order the channel list happens to be in.
+        if (carries_tangent && !restore) {
+            orthogonalize_tangent(mesh, normal_layer, loop);
+        }
+
+        /*
+         Last, and over every corner whether the vertex is pinned or not. These components never
+         travelled through the fit and never will -- they are the survivor's, and putting them back
+         is what stops a corner a collapse donated from keeping the flag it arrived with.
+         */
+        if (verbatim === null) {
+            continue;
+        }
+
+        const verbatim_base = wedge * layout.verbatim_components;
+
+        for (const channel of layout.verbatim) {
+            const layer = mesh.layers[channel.attribute];
+
+            layer.read(scratch_record, 0, loop);
+
+            for (let component = 0; component < channel.count; component++) {
+                scratch_record[channel.source + component] =
+                    verbatim[verbatim_base + channel.offset + component];
+            }
+
+            layer.write(loop, scratch_record, 0);
+        }
+    }
+}
+
+/**
+ * Scale a channel record's first three components to unit length, leaving them alone when there is
+ * no direction there to scale.
+ *
+ * @param {Float32Array} record
+ * @param {BinaryDataLayer} layer the record came from, read again when the blend cancelled
+ * @param {number} loop
+ */
+function normalize_in_place(record, layer, loop) {
+    const length = Math.hypot(record[0], record[1], record[2]);
+
+    if (length === 0) {
+        layer.read(record, 0, loop);
+
+        return;
+    }
+
+    record[0] /= length;
+    record[1] /= length;
+    record[2] /= length;
+}
+
+/**
+ * Square one vertex's tangent up against its normal.
+ *
+ * @param {VirtualGeometryMesh} mesh
+ * @param {BinaryDataLayer} normal_layer
+ * @param {number} loop
+ */
+function orthogonalize_tangent(mesh, normal_layer, loop) {
+    const tangent_layer = mesh.layers[VGEO_ATTRIBUTE.TANGENT];
+
+    normal_layer.read(scratch_normal, 0, loop);
+    tangent_layer.read(scratch_record, 0, loop);
+
+    const nx = scratch_normal[0];
+    const ny = scratch_normal[1];
+    const nz = scratch_normal[2];
+
+    const dot = nx * scratch_record[0] + ny * scratch_record[1] + nz * scratch_record[2];
+
+    const tx = scratch_record[0] - nx * dot;
+    const ty = scratch_record[1] - ny * dot;
+    const tz = scratch_record[2] - nz * dot;
+
+    const length = Math.hypot(tx, ty, tz);
+
+    if (length === 0) {
+        // Nothing perpendicular survived: the carried tangent had blended its way onto the normal.
+        build_tangent_from_normal(nx, ny, nz, 0, scratch_fallback);
+
+        scratch_record[0] = scratch_fallback[0];
+        scratch_record[1] = scratch_fallback[1];
+        scratch_record[2] = scratch_fallback[2];
+    } else {
+        scratch_record[0] = tx / length;
+        scratch_record[1] = ty / length;
+        scratch_record[2] = tz / length;
+    }
+
+    // A frame the shading model cannot use and the octahedral encoder cannot represent would reach
+    // the asset as a silently wrong word.
+    assert.isFinite(scratch_record[0], 'tangent x');
+    assert.isFinite(scratch_record[1], 'tangent y');
+    assert.isFinite(scratch_record[2], 'tangent z');
+
+    tangent_layer.write(loop, scratch_record, 0);
+}