@forgeax/engine-geometry 0.1.28 → 0.1.29

package/README.md

@@ -204,6 +204,8 @@ produce the normal vec4 or mesh result.
 | `deriveVertexBufferLayout(map, opts?)` | fn | Derives a fixed-order `GpuVertexBufferLayoutEntry[]` from a `VertexAttributeMap`. The canonical 14-key order (position / normal / uv / tangent / skinIndex / skinWeight / uv1..uv7 / color) assigns `@location(N)` per key. Absent keys reserve no space; `opts.shaderUvSetCount` enables clamp-to-last alias for UV sets. |
 | `deriveVertexLayoutProjection(map)` | fn | Creates the immutable canonical projection (`schemaVersion`, attributes, mask, stride, digest). `color` is fixed at host location 13 and `float32x4`. |
 | `packInterleavedVertexAttributes(map, vertexCount)` | fn | Packs attribute arrays using that projection and returns `Result<{ projection, vertices }, VertexAttributePackError>`; closed detail reasons identify storage, cardinality, vertex-count, or non-finite failures. |
+| `DEFAULT_VERTEX_ATTRIBUTE_MAP` / `SKIN_VERTEX_ATTRIBUTE_MAP` | const | Canonical presence maps for ordinary and skinned interleaved meshes. Render, recovery, and feature assembly use these maps instead of spelling a fallback layout locally. |
+| `deriveVertexCount(vertices, projection)` | fn | Validates `vertices.byteLength % projection.arrayStride === 0` and derives the integer vertex count shared by upload, LOD, update, morph, and draw-range consumers. |
 | `deriveVertexLayoutProjectionFromMask(mask)` | fn | Reconstructs a wire projection through the same canonical key owner; returns a typed error for empty or unknown mask bits. |
 | `buildMeshAttributeMapForUvSets(uvSetCount)` | fn | Synthesise a `VertexAttributeMap` with empty `Float32Array(0)` placeholders for `uv` + `uv1..uvN-1`. Used by the forward record stage to pre-declare UV-set slots before interleaving. |
 | `GpuVertexBufferLayoutEntry` | type | `{ shaderLocation: number; offset: number; format: GPUVertexFormat }` -- one GPU vertex buffer layout entry. |
@@ -223,6 +225,12 @@ The canonical key order and per-key `GPUVertexFormat` mapping is the SSOT in
 Shader `@location(N)` declarations and naga reflection deep-equal tests keep
 them in sync.
 
+> [!IMPORTANT]
+> Keep vertex bytes and `VertexLayoutProjection` together across every GPU
+> owner. Derive the count with `deriveVertexCount`; a non-divisible payload is
+> rejected before GPU resource construction instead of being truncated into a
+> fractional draw range.
+
 ## Three.js r184 mental alignment
 
 The 6 factory signatures mirror Three.js `BufferGeometry` constructors

package/dist/index.d.ts

@@ -14,5 +14,5 @@ export { createSphereGeometry } from './sphere';
 export { computeTangentVec4 } from './tangent';
 export { createTeapotGeometry, type TeapotMeshAsset, type TeapotProvenance, } from './teapot';
 export { createTorusGeometry } from './torus';
-export { buildMeshAttributeMapForUvSets, deriveVertexBufferLayout, deriveVertexBufferLayoutFromProjection, deriveVertexLayoutProjection, deriveVertexLayoutProjectionFromMask, type GpuVertexBufferLayoutEntry, type PackedVertexAttributes, packInterleavedVertexAttributes, VertexAttributePackError, type VertexLayoutProjection, type VertexLayoutProjectionAttribute, type VertexLayoutProjectionMaskError, } from './vertex-attribute-layout';
+export { buildMeshAttributeMapForUvSets, DEFAULT_VERTEX_ATTRIBUTE_MAP, deriveVertexBufferLayout, deriveVertexBufferLayoutFromProjection, deriveVertexCount, deriveVertexLayoutProjection, deriveVertexLayoutProjectionFromMask, type GpuVertexBufferLayoutEntry, type PackedVertexAttributes, packInterleavedVertexAttributes, SKIN_VERTEX_ATTRIBUTE_MAP, VertexAttributePackError, type VertexLayoutProjection, type VertexLayoutProjectionAttribute, type VertexLayoutProjectionMaskError, } from './vertex-attribute-layout';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,YAAY,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,iBAAiB,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,IAAI,GACV,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EACL,8BAA8B,EAC9B,wBAAwB,EACxB,sCAAsC,EACtC,4BAA4B,EAC5B,oCAAoC,EACpC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,+BAA+B,EAC/B,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,+BAA+B,EACpC,KAAK,+BAA+B,GACrC,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,YAAY,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC/F,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,KAAK,iBAAiB,GACvB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,4BAA4B,GAC7B,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,IAAI,GACV,MAAM,QAAQ,CAAC;AAEhB,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EACL,oBAAoB,EACpB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,wBAAwB,EACxB,sCAAsC,EACtC,iBAAiB,EACjB,4BAA4B,EAC5B,oCAAoC,EACpC,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,+BAA+B,EAC/B,yBAAyB,EACzB,wBAAwB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,+BAA+B,EACpC,KAAK,+BAA+B,GACrC,MAAM,2BAA2B,CAAC"}

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { decodeMeshBinHeader, MESH_BIN_HEADER_V4_BYTES, MESH_BIN_VERSION } from '@forgeax/engine-pack';
 import { box3, circle2, box2 } from '@forgeax/engine-math';
-import { err, ok, countUvSets, AssetError, ASSET_ERROR_HINTS } from '@forgeax/engine-types';
+import { err, ok, AssetError, ASSET_ERROR_HINTS } from '@forgeax/engine-types';
 
 // src/assets/mesh-binary.ts
 var EPSILON = 1e-8;
@@ -275,9 +275,25 @@ var CANONICAL_KEYS = Object.keys(ATTRIBUTE_FORMAT_MAP).filter(isAttributeKey);
 var UV_KEYS = CANONICAL_KEYS.filter(
   (key) => key === "uv" || key.startsWith("uv")
 );
-function emitAliasEntries(entries, fromIndex, toIndex, aliasOffset, currentStride) {
-  for (let k = fromIndex; k < toIndex && k < UV_KEYS.length; k++) {
+var EMPTY_FLOAT32 = new Float32Array(0);
+var EMPTY_UINT16 = new Uint16Array(0);
+var DEFAULT_VERTEX_ATTRIBUTE_MAP = Object.freeze({
+  position: EMPTY_FLOAT32,
+  normal: EMPTY_FLOAT32,
+  uv: EMPTY_FLOAT32,
+  tangent: EMPTY_FLOAT32
+});
+var SKIN_VERTEX_ATTRIBUTE_MAP = Object.freeze({
+  ...DEFAULT_VERTEX_ATTRIBUTE_MAP,
+  skinIndex: EMPTY_UINT16,
+  skinWeight: EMPTY_FLOAT32
+});
+function emitAliasEntries(entries, toIndex, currentStride) {
+  const lastUv = entries.filter((entry) => UV_KEYS.includes(entry.key)).at(-1);
+  const aliasOffset = lastUv?.offset ?? currentStride;
+  for (let k = 0; k < toIndex && k < UV_KEYS.length; k++) {
     const uvKey = UV_KEYS[k];
+    if (entries.some((entry) => entry.key === uvKey)) continue;
     entries.push({
       key: uvKey,
       shaderLocation: CANONICAL_KEYS.indexOf(uvKey),
@@ -285,15 +301,10 @@ function emitAliasEntries(entries, fromIndex, toIndex, aliasOffset, currentStrid
       format: ATTRIBUTE_FORMAT_MAP[uvKey]
     });
   }
-  return fromIndex === 0 ? currentStride + ATTRIBUTE_BYTE_STRIDE.uv : currentStride;
+  return lastUv === void 0 ? currentStride + ATTRIBUTE_BYTE_STRIDE.uv : currentStride;
 }
 function buildMeshAttributeMapForUvSets(uvSetCount) {
-  const map = {
-    position: new Float32Array(0),
-    normal: new Float32Array(0),
-    uv: new Float32Array(0),
-    tangent: new Float32Array(0)
-  };
+  const map = { ...DEFAULT_VERTEX_ATTRIBUTE_MAP };
   for (let set = 1; set < uvSetCount && set < UV_KEYS.length; set++) {
     map[UV_KEYS[set]] = new Float32Array(0);
   }
@@ -315,14 +326,7 @@ function deriveVertexBufferLayout(map, opts) {
   }
   const present = entries.length;
   if (shaderUvSetCount > 0) {
-    const meshUvSetCount = countUvSets(map);
-    if (shaderUvSetCount > meshUvSetCount) {
-      const lastUvIndex = meshUvSetCount - 1;
-      const lastUvKey = lastUvIndex >= 0 && lastUvIndex < UV_KEYS.length ? UV_KEYS[lastUvIndex] : void 0;
-      const aliasOffset = lastUvKey !== void 0 ? CANONICAL_KEYS.indexOf(lastUvKey) : -1;
-      const aliasByteOffset = aliasOffset >= 0 ? entries.find((e) => e.shaderLocation === aliasOffset)?.offset ?? 0 : offset;
-      offset = emitAliasEntries(entries, meshUvSetCount, shaderUvSetCount, aliasByteOffset, offset);
-    }
+    offset = emitAliasEntries(entries, shaderUvSetCount, offset);
   }
   if (present === 0 && shaderUvSetCount === 0) return [];
   entries.sort((a, b) => a.shaderLocation - b.shaderLocation);
@@ -347,24 +351,7 @@ function deriveVertexBufferLayoutFromProjection(projection, opts) {
   let arrayStride = projection.arrayStride;
   const shaderUvSetCount = opts?.shaderUvSetCount ?? 0;
   if (shaderUvSetCount > 0) {
-    const meshUvSetCount = entries.filter(
-      (entry) => entry.key === "uv" || entry.key.startsWith("uv")
-    ).length;
-    if (shaderUvSetCount > meshUvSetCount) {
-      const lastUv = entries.filter((entry) => entry.key === "uv" || entry.key.startsWith("uv")).at(-1);
-      const aliasOffset = lastUv?.offset ?? arrayStride;
-      for (let index = meshUvSetCount; index < shaderUvSetCount && index < UV_KEYS.length; index += 1) {
-        const key = UV_KEYS[index];
-        if (key === void 0) continue;
-        entries.push({
-          key,
-          shaderLocation: CANONICAL_KEYS.indexOf(key),
-          offset: aliasOffset,
-          format: ATTRIBUTE_FORMAT_MAP[key]
-        });
-      }
-      if (meshUvSetCount === 0) arrayStride += ATTRIBUTE_BYTE_STRIDE.uv;
-    }
+    arrayStride = emitAliasEntries(entries, shaderUvSetCount, arrayStride);
   }
   entries.sort((a, b) => a.shaderLocation - b.shaderLocation);
   return projection.attributes.length === 0 ? [] : [
@@ -378,6 +365,15 @@ function deriveVertexBufferLayoutFromProjection(projection, opts) {
     }
   ];
 }
+function deriveVertexCount(vertices, projection) {
+  const stride = projection.arrayStride;
+  const byteLength = vertices.byteLength;
+  if (!Number.isSafeInteger(stride) || stride <= 0 || !Number.isSafeInteger(byteLength) || byteLength < 0 || byteLength % stride !== 0) {
+    return void 0;
+  }
+  const count = byteLength / stride;
+  return Number.isSafeInteger(count) ? count : void 0;
+}
 function bytesForFormat(format) {
   if (format === "uint16x4" || format === "float32x2") return 8;
   if (format === "float32x3") return 12;
@@ -4286,6 +4282,6 @@ function createTorusGeometry(radius, tube, radialSegments = 8, tubularSegments =
   return meshFromInterleaved(vertices, indices);
 }
 
-export { PROCEDURAL_FLOATS_PER_VERTEX, VertexAttributePackError, buildMeshAttributeMapForUvSets, compute2dBounds, computeTangentVec4, create2dGeometry, create2dRingGeometry, createBoxGeometry, createCapsuleGeometry, createConeGeometry, createCylinderGeometry, createEdgesGeometry, createMeshBuilder, createPlaneGeometry, createPrimitiveMesh, createProceduralMesh, createSphereGeometry, createTeapotGeometry, createTorusGeometry, createWireframeGeometry, decodeMeshBinary, deriveVertexBufferLayout, deriveVertexBufferLayoutFromProjection, deriveVertexLayoutProjection, deriveVertexLayoutProjectionFromMask, meshAssetContribution, meshAssetDecoder, meshAssetKind, meshFromInterleaved, normalizeMeshPayload, packInterleavedVertexAttributes };
+export { DEFAULT_VERTEX_ATTRIBUTE_MAP, PROCEDURAL_FLOATS_PER_VERTEX, SKIN_VERTEX_ATTRIBUTE_MAP, VertexAttributePackError, buildMeshAttributeMapForUvSets, compute2dBounds, computeTangentVec4, create2dGeometry, create2dRingGeometry, createBoxGeometry, createCapsuleGeometry, createConeGeometry, createCylinderGeometry, createEdgesGeometry, createMeshBuilder, createPlaneGeometry, createPrimitiveMesh, createProceduralMesh, createSphereGeometry, createTeapotGeometry, createTorusGeometry, createWireframeGeometry, decodeMeshBinary, deriveVertexBufferLayout, deriveVertexBufferLayoutFromProjection, deriveVertexCount, deriveVertexLayoutProjection, deriveVertexLayoutProjectionFromMask, meshAssetContribution, meshAssetDecoder, meshAssetKind, meshFromInterleaved, normalizeMeshPayload, packInterleavedVertexAttributes };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map