@flighthq/mesh 0.3.0-next.906.07cea63 → 0.3.0

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@flighthq/mesh",
-  "version": "0.3.0-next.906.07cea63",
+  "version": "0.3.0",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/flighthq/flight.git",
@@ -36,9 +38,9 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/entity": "0.3.0-next.906.07cea63",
-    "@flighthq/geometry": "0.3.0-next.906.07cea63",
-    "@flighthq/types": "0.3.0-next.906.07cea63"
+    "@flighthq/entity": "0.3.0",
+    "@flighthq/geometry": "0.3.0",
+    "@flighthq/types": "0.3.0"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/meshGeometry.test.ts

@@ -16,6 +16,7 @@ import {
   getMeshGeometrySkinBindPose,
   getMeshGeometryVertexCount,
   hasMeshGeometrySkin,
+  invalidateMeshGeometry,
   setMeshGeometryMorphBindPose,
   setMeshGeometrySkinBindPose,
 } from './meshGeometry';
@@ -67,6 +68,17 @@ describe('cloneMeshGeometry', () => {
     expect(clone.bounds!.min.x).toBe(-1);
     expect(clone.bounds!.max.z).toBe(1);
   });
+
+  it('copies tangent-split smoothing identity without sharing its runtime array', () => {
+    const source = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(2) });
+    (source[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources = new Uint32Array([0, 0]);
+
+    const clone = cloneMeshGeometry(source);
+
+    const clonedSources = (clone[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources;
+    expect(Array.from(clonedSources!)).toEqual([0, 0]);
+    expect(clonedSources).not.toBe((source[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources);
+  });
 });
 
 describe('createMeshGeometry', () => {
@@ -118,6 +130,7 @@ describe('createMeshGeometry', () => {
     const runtime = geometry[EntityRuntimeKey] as MeshGeometryRuntime;
     expect(runtime.webglData).toBeNull();
     expect(runtime.webgpuData).toBeNull();
+    expect(runtime.tangentSmoothingSources).toBeNull();
   });
 });
 
@@ -196,6 +209,18 @@ describe('hasMeshGeometrySkin', () => {
   });
 });
 
+describe('invalidateMeshGeometry', () => {
+  it('advances the shared upload revision as a wrapping u32', () => {
+    const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(1) });
+    invalidateMeshGeometry(geometry);
+    expect(geometry.version).toBe(1);
+
+    geometry.version = 0xffffffff;
+    invalidateMeshGeometry(geometry);
+    expect(geometry.version).toBe(0);
+  });
+});
+
 describe('setMeshGeometryMorphBindPose', () => {
   it('stores and clears the morph base pose on the runtime slot', () => {
     const geometry = createMeshGeometry({ layout: CANONICAL_LAYOUT, vertices: makeVertices(3) });

package/src/meshGeometryCompute.test.ts

@@ -1,7 +1,7 @@
 import { createAabb, createBoundingSphere } from '@flighthq/geometry/contract';
 import type { VertexAttributeLayout } from '@flighthq/types/contract';
 
-import { createMeshGeometry } from './meshGeometry';
+import { createMeshGeometry, invalidateMeshGeometry } from './meshGeometry';
 import {
   computeMeshGeometryBoundingSphere,
   computeMeshGeometryBounds,
@@ -11,6 +11,7 @@ import {
   ensureMeshGeometryBounds,
   refreshMeshGeometryBounds,
 } from './meshGeometryCompute';
+import { CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT } from './meshGeometryLayout';
 
 const CANONICAL_LAYOUT: VertexAttributeLayout = {
   attributes: [
@@ -190,6 +191,8 @@ describe('computeMeshGeometryTangents', () => {
   it('writes a unit tangent aligned with +X for the canonical UV mapping', () => {
     const geometry = makeTriangle();
     computeMeshGeometryNormals(geometry, geometry);
+    const originalVertices = geometry.vertices;
+    const originalIndices = geometry.indices;
     computeMeshGeometryTangents(geometry, geometry);
     // u increases along +X, so tangent.xyz ~ (1,0,0).
     expect(geometry.vertices[6]).toBeCloseTo(1);
@@ -197,6 +200,9 @@ describe('computeMeshGeometryTangents', () => {
     expect(geometry.vertices[8]).toBeCloseTo(0);
     // Right-handed mapping => positive handedness.
     expect(geometry.vertices[9]).toBe(1);
+    // The common single-handed case writes in place without replacing either payload buffer.
+    expect(geometry.vertices).toBe(originalVertices);
+    expect(geometry.indices).toBe(originalIndices);
   });
 
   it('writes into a distinct out geometry', () => {
@@ -217,8 +223,190 @@ describe('computeMeshGeometryTangents', () => {
     computeMeshGeometryTangents(geometry, geometry);
     expect(geometry.vertices[9]).toBe(-1);
   });
+
+  it('splits shared vertices at a mirrored-UV handedness boundary', () => {
+    // Two CCW triangles share vertices 0/2. Their UV determinants have opposite signs, so a single
+    // tangent.w cannot describe both triangles: the shared records must be duplicated and remapped.
+    const vertices = new Float32Array(4 * 12);
+    setCanonicalVertex(vertices, 0, 0, 0, 0, 0);
+    setCanonicalVertex(vertices, 1, 1, 0, 1, 0);
+    setCanonicalVertex(vertices, 2, 0, 1, 0, 1);
+    setCanonicalVertex(vertices, 3, -1, 0, 1, 0);
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+      layout: CANONICAL_LAYOUT,
+      vertices,
+    });
+    computeMeshGeometryNormals(geometry, geometry);
+    const previousVersion = geometry.version;
+
+    computeMeshGeometryTangents(geometry, geometry);
+
+    expect(geometry.vertices.length / 12).toBe(6);
+    expect(geometry.version).toBe(previousVersion + 1);
+    const indices = geometry.indices!;
+    const firstSign = geometry.vertices[indices[0] * 12 + 9];
+    const mirroredSign = geometry.vertices[indices[3] * 12 + 9];
+    expect(firstSign).toBe(1);
+    expect(mirroredSign).toBe(-1);
+    for (let corner = 0; corner < 3; corner++) {
+      expect(geometry.vertices[indices[corner] * 12 + 9]).toBe(firstSign);
+      expect(geometry.vertices[indices[corner + 3] * 12 + 9]).toBe(mirroredSign);
+    }
+    // Both shared corners moved on the mirrored triangle; the positive triangle kept the originals.
+    expect(indices[0]).toBe(0);
+    expect(indices[2]).toBe(2);
+    expect(indices[3]).toBeGreaterThanOrEqual(4);
+    expect(indices[4]).toBeGreaterThanOrEqual(4);
+  });
+
+  it('splits same-handed corners whose tangent directions cannot share a stable frame', () => {
+    // Both triangles are CCW and both UV determinants are positive, but their U axes point in
+    // opposite model-space directions at shared vertex 0. Handedness-only reconciliation leaves the
+    // shared tangent cancelled or dominated by one face; Flight must create a second complete record.
+    const vertices = new Float32Array(5 * 12);
+    setCanonicalVertex(vertices, 0, 0, 0, 0, 0);
+    setCanonicalVertex(vertices, 1, 1, 0, 1, 0);
+    setCanonicalVertex(vertices, 2, 0, 1, 0, 1);
+    setCanonicalVertex(vertices, 3, -1, 0, 1, 0);
+    setCanonicalVertex(vertices, 4, 0, -1, 0, 1);
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 0, 3, 4]),
+      layout: CANONICAL_LAYOUT,
+      vertices,
+    });
+    computeMeshGeometryNormals(geometry, geometry);
+
+    computeMeshGeometryTangents(geometry, geometry);
+
+    expect(geometry.vertices.length / 12).toBe(6);
+    const indices = geometry.indices!;
+    expect(indices[0]).not.toBe(indices[3]);
+    expect(geometry.vertices[indices[0] * 12 + 6]).toBeGreaterThan(0.9);
+    expect(geometry.vertices[indices[3] * 12 + 6]).toBeLessThan(-0.9);
+    // This is a directional split within one handedness, not a mirror split.
+    expect(geometry.vertices[indices[0] * 12 + 9]).toBe(1);
+    expect(geometry.vertices[indices[3] * 12 + 9]).toBe(1);
+
+    // The reference MD5 demo historically repeated both authoring calls after import. Repeating them
+    // must neither grow topology again nor turn the Flight-created tangent split into a hard normal seam.
+    computeMeshGeometryNormals(geometry, geometry);
+    computeMeshGeometryTangents(geometry, geometry);
+    expect(geometry.vertices.length / 12).toBe(6);
+    expect(geometry.vertices[indices[0] * 12 + 3]).toBeCloseTo(geometry.vertices[indices[3] * 12 + 3]);
+    expect(geometry.vertices[indices[0] * 12 + 4]).toBeCloseTo(geometry.vertices[indices[3] * 12 + 4]);
+    expect(geometry.vertices[indices[0] * 12 + 5]).toBeCloseTo(geometry.vertices[indices[3] * 12 + 5]);
+  });
+
+  it('keeps smooth normals shared across a folded mirrored tangent seam', () => {
+    const vertices = new Float32Array(4 * 12);
+    setCanonicalVertex(vertices, 0, 0, 0, 0, 0);
+    setCanonicalVertex(vertices, 1, 1, 0, 1, 0);
+    setCanonicalVertex(vertices, 2, 0, 1, 0, 1);
+    setCanonicalVertex(vertices, 3, -1, 0, 1, 0);
+    vertices[3 * 12 + 2] = 1;
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+      layout: CANONICAL_LAYOUT,
+      vertices,
+    });
+    computeMeshGeometryNormals(geometry, geometry);
+    const originalNormal = Array.from(geometry.vertices.subarray(3, 6));
+    computeMeshGeometryTangents(geometry, geometry);
+    const indices = geometry.indices!;
+    expect(indices[0]).not.toBe(indices[3]);
+
+    computeMeshGeometryNormals(geometry, geometry);
+
+    for (const vertex of [indices[0], indices[3]]) {
+      expect(geometry.vertices[vertex * 12 + 3]).toBeCloseTo(originalNormal[0]);
+      expect(geometry.vertices[vertex * 12 + 4]).toBeCloseTo(originalNormal[1]);
+      expect(geometry.vertices[vertex * 12 + 5]).toBeCloseTo(originalNormal[2]);
+    }
+  });
+
+  it('copies the complete skinned record when splitting a mirrored tangent seam', () => {
+    const stride = CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT.stride / 4;
+    const vertices = new Float32Array(4 * stride);
+    setSkinnedVertex(vertices, stride, 0, 0, 0, 0, 0, 10);
+    setSkinnedVertex(vertices, stride, 1, 1, 0, 1, 0, 20);
+    setSkinnedVertex(vertices, stride, 2, 0, 1, 0, 1, 30);
+    setSkinnedVertex(vertices, stride, 3, -1, 0, 1, 0, 40);
+    const geometry = createMeshGeometry({
+      indices: new Uint16Array([0, 1, 2, 0, 2, 3]),
+      layout: CANONICAL_SKINNED_MESH_GEOMETRY_LAYOUT,
+      vertices,
+    });
+    computeMeshGeometryNormals(geometry, geometry);
+
+    computeMeshGeometryTangents(geometry, geometry);
+
+    const split = geometry.indices![3];
+    expect(split).toBeGreaterThanOrEqual(4);
+    // The split for source vertex 0 retains its joints0 and weights0 exactly. These channels are what
+    // make a topologically repaired MD5 vertex continue following the same skeleton influences.
+    expect(Array.from(geometry.vertices.subarray(split * stride + 12, split * stride + 16))).toEqual([10, 11, 12, 13]);
+    expect(geometry.vertices[split * stride + 16]).toBeCloseTo(0.1);
+    expect(geometry.vertices[split * stride + 17]).toBeCloseTo(0.2);
+    expect(geometry.vertices[split * stride + 18]).toBeCloseTo(0.3);
+    expect(geometry.vertices[split * stride + 19]).toBeCloseTo(0.4);
+  });
+
+  it('uses a unit perpendicular fallback for degenerate UVs', () => {
+    const geometry = makeTriangle();
+    for (let vertex = 0; vertex < 3; vertex++) {
+      const base = vertex * 12;
+      geometry.vertices[base + 3] = 1;
+      geometry.vertices[base + 4] = 0;
+      geometry.vertices[base + 5] = 0;
+      geometry.vertices[base + 10] = 0;
+      geometry.vertices[base + 11] = 0;
+    }
+
+    computeMeshGeometryTangents(geometry, geometry);
+
+    const tx = geometry.vertices[6];
+    const ty = geometry.vertices[7];
+    const tz = geometry.vertices[8];
+    expect(Math.hypot(tx, ty, tz)).toBeCloseTo(1);
+    expect(tx).toBeCloseTo(0);
+    expect(Math.abs(geometry.vertices[9])).toBe(1);
+  });
 });
 
+function setCanonicalVertex(vertices: Float32Array, vertex: number, x: number, y: number, u: number, v: number): void {
+  const base = vertex * 12;
+  vertices[base] = x;
+  vertices[base + 1] = y;
+  vertices[base + 10] = u;
+  vertices[base + 11] = v;
+}
+
+function setSkinnedVertex(
+  vertices: Float32Array,
+  stride: number,
+  vertex: number,
+  x: number,
+  y: number,
+  u: number,
+  v: number,
+  joint: number,
+): void {
+  const base = vertex * stride;
+  vertices[base] = x;
+  vertices[base + 1] = y;
+  vertices[base + 10] = u;
+  vertices[base + 11] = v;
+  vertices[base + 12] = joint;
+  vertices[base + 13] = joint + 1;
+  vertices[base + 14] = joint + 2;
+  vertices[base + 15] = joint + 3;
+  vertices[base + 16] = 0.1;
+  vertices[base + 17] = 0.2;
+  vertices[base + 18] = 0.3;
+  vertices[base + 19] = 0.4;
+}
+
 describe('ensureMeshGeometryBounds', () => {
   it('computes on first query, then reuses the cache until the version moves', () => {
     const geometry = makeTriangle();
@@ -232,8 +420,8 @@ describe('ensureMeshGeometryBounds', () => {
     geometry.vertices[12] = 4;
     expect(ensureMeshGeometryBounds(geometry)?.max.x).toBe(1);
 
-    // Bumping the version (what every deform does) is what marks the cache stale.
-    geometry.version++;
+    // The public direct-write escape hatch marks the cache stale.
+    invalidateMeshGeometry(geometry);
     expect(ensureMeshGeometryBounds(geometry)?.max.x).toBe(4);
   });
 

package/src/meshGeometryLayout.test.ts

@@ -1,4 +1,5 @@
-import type { VertexAttributeLayout } from '@flighthq/types/contract';
+import type { MeshGeometryRuntime, VertexAttributeLayout } from '@flighthq/types/contract';
+import { EntityRuntimeKey } from '@flighthq/types/contract';
 
 import { createMeshGeometry } from './meshGeometry';
 import {
@@ -90,6 +91,16 @@ describe('convertMeshGeometryLayout', () => {
     expect(converted.vertices[1]).toBeCloseTo(2);
     expect(converted.vertices[2]).toBeCloseTo(3);
   });
+  it('preserves tangent-split smoothing identity across a layout conversion', () => {
+    const source = createMeshGeometry({ layout: CANONICAL_MESH_GEOMETRY_LAYOUT, vertices: new Float32Array(24) });
+    (source[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources = new Uint32Array([0, 0]);
+
+    const converted = convertMeshGeometryLayout(source, POSITION_ONLY_LAYOUT);
+
+    const convertedSources = (converted[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources;
+    expect(Array.from(convertedSources!)).toEqual([0, 0]);
+    expect(convertedSources).not.toBe((source[EntityRuntimeKey] as MeshGeometryRuntime).tangentSmoothingSources);
+  });
   it('strips to position + uv0 layout', () => {
     const source = makeCanonicalGeometry();
     const converted = convertMeshGeometryLayout(source, POSITION_UV0_LAYOUT);