@forgeax/engine-render 0.1.27 → 0.1.29

package/src/instances-derived-bounds.ts

@@ -1,4 +1,10 @@
-import { box3, type Mat4Like, mat4 } from '@forgeax/engine-math';
+import type { Mat4Like } from '@forgeax/engine-math';
+
+// `fingerprintNumericArray` runs on every bounds-cache lookup. Keep the bit
+// reinterpretation scratch outside the hot path so a cache hit does not
+// allocate a pair of typed arrays for each retained render slot.
+const fingerprintScalar = new Float32Array(1);
+const fingerprintBits = new Uint32Array(fingerprintScalar.buffer);
 
 /**
  * Inputs owned by the render extract/persistent-scene boundary. Bounds are
@@ -34,11 +40,9 @@ export type InstanceBoundsCacheInput = InstanceBoundsCacheKey & DerivedInstances
  */
 export function fingerprintNumericArray(values: ArrayLike<number>): number {
   let hash = 0x811c9dc5;
-  const scalar = new Float32Array(1);
-  const bits = new Uint32Array(scalar.buffer);
   for (let index = 0; index < values.length; index += 1) {
-    scalar[0] = Number(values[index]);
-    hash = Math.imul(hash ^ (bits[0] ?? 0), 0x01000193) >>> 0;
+    fingerprintScalar[0] = Number(values[index]);
+    hash = Math.imul(hash ^ (fingerprintBits[0] ?? 0), 0x01000193) >>> 0;
   }
   return hash >>> 0;
 }
@@ -72,14 +76,218 @@ function finiteMatrix(matrix: ArrayLike<number>): matrix is Mat4Like {
   return true;
 }
 
-function includeBox(out: box3.Box3, candidate: box3.Box3Like): void {
-  for (const x of [candidate[0] as number, candidate[3] as number]) {
-    for (const y of [candidate[1] as number, candidate[4] as number]) {
-      for (const z of [candidate[2] as number, candidate[5] as number]) {
-        box3.expandByPoint(out, [x, y, z]);
-      }
+function multiplyMat4(
+  out: Float32Array,
+  left: ArrayLike<number>,
+  right: ArrayLike<number>,
+  rightOffset = 0,
+): void {
+  for (let column = 0; column < 4; column += 1) {
+    const rightColumn = rightOffset + column * 4;
+    const right0 = Number(right[rightColumn] ?? 0);
+    const right1 = Number(right[rightColumn + 1] ?? 0);
+    const right2 = Number(right[rightColumn + 2] ?? 0);
+    const right3 = Number(right[rightColumn + 3] ?? 0);
+    const outOffset = column * 4;
+    out[outOffset] =
+      Number(left[0] ?? 0) * right0 +
+      Number(left[4] ?? 0) * right1 +
+      Number(left[8] ?? 0) * right2 +
+      Number(left[12] ?? 0) * right3;
+    out[outOffset + 1] =
+      Number(left[1] ?? 0) * right0 +
+      Number(left[5] ?? 0) * right1 +
+      Number(left[9] ?? 0) * right2 +
+      Number(left[13] ?? 0) * right3;
+    out[outOffset + 2] =
+      Number(left[2] ?? 0) * right0 +
+      Number(left[6] ?? 0) * right1 +
+      Number(left[10] ?? 0) * right2 +
+      Number(left[14] ?? 0) * right3;
+    out[outOffset + 3] =
+      Number(left[3] ?? 0) * right0 +
+      Number(left[7] ?? 0) * right1 +
+      Number(left[11] ?? 0) * right2 +
+      Number(left[15] ?? 0) * right3;
+  }
+}
+
+function finiteMatrixAt(values: ArrayLike<number>, offset: number): boolean {
+  if (values.length - offset < 16) return false;
+  for (let index = 0; index < 16; index += 1) {
+    if (!Number.isFinite(values[offset + index] as number)) return false;
+  }
+  return true;
+}
+
+function isAffine(matrix: ArrayLike<number>): boolean {
+  return (
+    (matrix[3] as number) === 0 &&
+    (matrix[7] as number) === 0 &&
+    (matrix[11] as number) === 0 &&
+    (matrix[15] as number) === 1
+  );
+}
+
+function includeBox(
+  out: Float32Array,
+  candidate: ArrayLike<number>,
+  initialized: boolean,
+): boolean {
+  const minX = candidate[0] as number;
+  const minY = candidate[1] as number;
+  const minZ = candidate[2] as number;
+  const maxX = candidate[3] as number;
+  const maxY = candidate[4] as number;
+  const maxZ = candidate[5] as number;
+  if (!initialized) {
+    out[0] = minX;
+    out[1] = minY;
+    out[2] = minZ;
+    out[3] = maxX;
+    out[4] = maxY;
+    out[5] = maxZ;
+    return true;
+  }
+  if (minX < (out[0] ?? Number.POSITIVE_INFINITY)) out[0] = minX;
+  if (minY < (out[1] ?? Number.POSITIVE_INFINITY)) out[1] = minY;
+  if (minZ < (out[2] ?? Number.POSITIVE_INFINITY)) out[2] = minZ;
+  if (maxX > (out[3] ?? Number.NEGATIVE_INFINITY)) out[3] = maxX;
+  if (maxY > (out[4] ?? Number.NEGATIVE_INFINITY)) out[4] = maxY;
+  if (maxZ > (out[5] ?? Number.NEGATIVE_INFINITY)) out[5] = maxZ;
+  return true;
+}
+
+/** Transform an AABB without per-instance arrays or corner tuples. */
+function transformAabb(
+  out: Float32Array,
+  local: ArrayLike<number>,
+  matrix: ArrayLike<number>,
+): boolean {
+  const minX = local[0] as number;
+  const minY = local[1] as number;
+  const minZ = local[2] as number;
+  const maxX = local[3] as number;
+  const maxY = local[4] as number;
+  const maxZ = local[5] as number;
+  const centerX = (minX + maxX) * 0.5;
+  const centerY = (minY + maxY) * 0.5;
+  const centerZ = (minZ + maxZ) * 0.5;
+  const extentX = (maxX - minX) * 0.5;
+  const extentY = (maxY - minY) * 0.5;
+  const extentZ = (maxZ - minZ) * 0.5;
+
+  if (isAffine(matrix)) {
+    const centerWorldX =
+      (matrix[0] as number) * centerX +
+      (matrix[4] as number) * centerY +
+      (matrix[8] as number) * centerZ +
+      (matrix[12] as number);
+    const centerWorldY =
+      (matrix[1] as number) * centerX +
+      (matrix[5] as number) * centerY +
+      (matrix[9] as number) * centerZ +
+      (matrix[13] as number);
+    const centerWorldZ =
+      (matrix[2] as number) * centerX +
+      (matrix[6] as number) * centerY +
+      (matrix[10] as number) * centerZ +
+      (matrix[14] as number);
+    const extentWorldX =
+      Math.abs(matrix[0] as number) * extentX +
+      Math.abs(matrix[4] as number) * extentY +
+      Math.abs(matrix[8] as number) * extentZ;
+    const extentWorldY =
+      Math.abs(matrix[1] as number) * extentX +
+      Math.abs(matrix[5] as number) * extentY +
+      Math.abs(matrix[9] as number) * extentZ;
+    const extentWorldZ =
+      Math.abs(matrix[2] as number) * extentX +
+      Math.abs(matrix[6] as number) * extentY +
+      Math.abs(matrix[10] as number) * extentZ;
+    out[0] = centerWorldX - extentWorldX;
+    out[1] = centerWorldY - extentWorldY;
+    out[2] = centerWorldZ - extentWorldZ;
+    out[3] = centerWorldX + extentWorldX;
+    out[4] = centerWorldY + extentWorldY;
+    out[5] = centerWorldZ + extentWorldZ;
+    return finiteAabb(out);
+  }
+
+  // Projective/non-affine matrices need the reference corner route. A w
+  // interval crossing zero is unbounded, so explicitly return no-cull rather
+  // than pretending the finite corner samples enclose the volume.
+  let minimumW = Number.POSITIVE_INFINITY;
+  let maximumW = Number.NEGATIVE_INFINITY;
+  for (let corner = 0; corner < 8; corner += 1) {
+    const x = (corner & 1) === 0 ? minX : maxX;
+    const y = (corner & 2) === 0 ? minY : maxY;
+    const z = (corner & 4) === 0 ? minZ : maxZ;
+    const w =
+      (matrix[3] as number) * x +
+      (matrix[7] as number) * y +
+      (matrix[11] as number) * z +
+      (matrix[15] as number);
+    if (!Number.isFinite(w)) return false;
+    if (w < minimumW) minimumW = w;
+    if (w > maximumW) maximumW = w;
+  }
+  if (minimumW <= 0 && maximumW >= 0) return false;
+
+  let unionMinX = Number.POSITIVE_INFINITY;
+  let unionMinY = Number.POSITIVE_INFINITY;
+  let unionMinZ = Number.POSITIVE_INFINITY;
+  let unionMaxX = Number.NEGATIVE_INFINITY;
+  let unionMaxY = Number.NEGATIVE_INFINITY;
+  let unionMaxZ = Number.NEGATIVE_INFINITY;
+  for (let corner = 0; corner < 8; corner += 1) {
+    const x = (corner & 1) === 0 ? minX : maxX;
+    const y = (corner & 2) === 0 ? minY : maxY;
+    const z = (corner & 4) === 0 ? minZ : maxZ;
+    const rawX =
+      (matrix[0] as number) * x +
+      (matrix[4] as number) * y +
+      (matrix[8] as number) * z +
+      (matrix[12] as number);
+    const rawY =
+      (matrix[1] as number) * x +
+      (matrix[5] as number) * y +
+      (matrix[9] as number) * z +
+      (matrix[13] as number);
+    const rawZ =
+      (matrix[2] as number) * x +
+      (matrix[6] as number) * y +
+      (matrix[10] as number) * z +
+      (matrix[14] as number);
+    const w =
+      (matrix[3] as number) * x +
+      (matrix[7] as number) * y +
+      (matrix[11] as number) * z +
+      (matrix[15] as number);
+    const projectedX = rawX / w;
+    const projectedY = rawY / w;
+    const projectedZ = rawZ / w;
+    if (
+      !Number.isFinite(projectedX) ||
+      !Number.isFinite(projectedY) ||
+      !Number.isFinite(projectedZ)
+    ) {
+      return false;
     }
+    if (projectedX < unionMinX) unionMinX = projectedX;
+    if (projectedY < unionMinY) unionMinY = projectedY;
+    if (projectedZ < unionMinZ) unionMinZ = projectedZ;
+    if (projectedX > unionMaxX) unionMaxX = projectedX;
+    if (projectedY > unionMaxY) unionMaxY = projectedY;
+    if (projectedZ > unionMaxZ) unionMaxZ = projectedZ;
   }
+  out[0] = unionMinX;
+  out[1] = unionMinY;
+  out[2] = unionMinZ;
+  out[3] = unionMaxX;
+  out[4] = unionMaxY;
+  out[5] = unionMaxZ;
+  return finiteAabb(out);
 }
 
 /**
@@ -97,36 +305,31 @@ export function deriveInstancesUnionBounds(
     return undefined;
   }
   if (transforms.length === 0 || transforms.length % 16 !== 0) return undefined;
-
-  const local = box3.create(
-    meshAabb[0] as number,
-    meshAabb[1] as number,
-    meshAabb[2] as number,
-    meshAabb[3] as number,
-    meshAabb[4] as number,
-    meshAabb[5] as number,
-  );
-  const union = box3.create();
-  const composed = mat4.create();
-  const transformed = box3.create();
+  const local = meshAabb;
+  const union = new Float32Array(6);
+  const composed = new Float32Array(16);
+  const transformed = new Float32Array(6);
+  let initialized = false;
   for (let offset = 0; offset < transforms.length; offset += 16) {
-    const instance = new Float32Array(16);
-    for (let lane = 0; lane < 16; lane += 1) {
-      instance[lane] = transforms[offset + lane] as number;
-    }
-    if (!finiteMatrix(instance)) return undefined;
-    mat4.multiply(composed, entityWorld, instance);
-    box3.transformBox3(transformed, local, composed);
-    if (!finiteAabb(transformed)) return undefined;
-    includeBox(union, transformed);
+    if (!finiteMatrixAt(transforms, offset)) return undefined;
+    multiplyMat4(composed, entityWorld, transforms, offset);
+    if (!finiteMatrix(composed) || !transformAabb(transformed, local, composed)) return undefined;
+    initialized = includeBox(union, transformed, initialized);
   }
-  return new Float32Array(union);
+  return initialized && finiteAabb(union) ? union : undefined;
 }
 
 interface InstanceBoundsCacheEntry extends InstanceBoundsCacheKey {
   readonly bounds: Float32Array | undefined;
 }
 
+export interface InstanceBoundsCacheInspection {
+  readonly hits: number;
+  readonly misses: number;
+  readonly derives: number;
+  readonly invalidations: number;
+}
+
 /**
  * Small renderer-owned per-entity cache. A changed generation replaces the
  * entry atomically; packed-id reuse is safe when its owner supplies a new
@@ -134,6 +337,10 @@ interface InstanceBoundsCacheEntry extends InstanceBoundsCacheKey {
  */
 export class InstanceBoundsCache {
   private readonly entries = new Map<string, InstanceBoundsCacheEntry>();
+  private hits = 0;
+  private misses = 0;
+  private derives = 0;
+  private invalidations = 0;
 
   private key(input: Pick<InstanceBoundsCacheKey, 'worldId' | 'entityKey'>): string {
     return `${input.worldId === undefined ? '' : `${input.worldId}:`}${input.entityKey}`;
@@ -147,8 +354,11 @@ export class InstanceBoundsCache {
       previous.transformGeneration === input.transformGeneration &&
       previous.matrixGeneration === input.matrixGeneration
     ) {
+      this.hits += 1;
       return previous.bounds;
     }
+    this.misses += 1;
+    this.derives += 1;
     const bounds = deriveInstancesUnionBounds(input);
     this.entries.set(this.key(input), {
       ...(input.worldId === undefined ? {} : { worldId: input.worldId }),
@@ -163,9 +373,23 @@ export class InstanceBoundsCache {
 
   invalidate(entityKey?: number, worldId?: number): void {
     if (entityKey === undefined) {
+      if (this.entries.size > 0) this.invalidations += this.entries.size;
       this.entries.clear();
     } else {
-      this.entries.delete(this.key({ entityKey, ...(worldId === undefined ? {} : { worldId }) }));
+      if (
+        this.entries.delete(this.key({ entityKey, ...(worldId === undefined ? {} : { worldId }) }))
+      ) {
+        this.invalidations += 1;
+      }
     }
   }
+
+  inspect(): InstanceBoundsCacheInspection {
+    return {
+      hits: this.hits,
+      misses: this.misses,
+      derives: this.derives,
+      invalidations: this.invalidations,
+    };
+  }
 }