@forgeax/engine-render 0.1.24 → 0.1.26

package/src/systems/skin-palette-allocator.ts

@@ -98,6 +98,12 @@ export interface SkinPaletteAllocator {
    *         `device.limits.maxStorageBufferBindingSize`
    */
   allocateSlice(jointCount: number): SkinPaletteSlice;
+  /** Allocate one stable slice for a retained render source. */
+  allocateSliceFor(key: string, jointCount: number): SkinPaletteSlice;
+  /** Release a stable slice when its render source leaves the scene. */
+  releaseSliceFor(key: string): void;
+  /** Reconcile stable slices after a full render-source extraction. */
+  retainSliceKeys(keys: ReadonlySet<string>): void;
   /**
    * Write joint matrices into the slice's buffer at the slice's offset.
    * Computes M_i = jointWorldTransforms[i] * ibm[i] per joint.
@@ -129,6 +135,16 @@ export function createSkinPaletteAllocator(
   let storageBuffer: Buffer | null = null;
   let storageCapacity = 0;
   let storageCursor = 0;
+  let stableStorageCursor = 0;
+  const stableSlices = new Map<string, SkinPaletteSlice>();
+  const stableUniformBuffers = new Map<string, Buffer>();
+  const storageBufferCapacities = new WeakMap<Buffer, number>();
+  const stableFreeRanges: Array<{
+    start: number;
+    count: number;
+    buffer: Buffer;
+    capacity: number;
+  }> = [];
 
   // Uniform path: per-entity buffer pool. `pool` is the pre-allocated
   // 16320 B UBO ring; `poolCursor` advances per allocateSlice within a
@@ -158,14 +174,10 @@ export function createSkinPaletteAllocator(
     if (!bufRes.ok) throw bufRes.error;
     storageBuffer = bufRes.value;
     storageCapacity = newCapacity;
+    storageBufferCapacities.set(storageBuffer, newCapacity);
   }
 
-  function acquirePoolBuffer(): Buffer {
-    if (poolCursor < pool.length) {
-      const reused = pool[poolCursor];
-      // biome-ignore lint/style/noNonNullAssertion: poolCursor < pool.length guarantees the slot is set
-      return reused!;
-    }
+  function createUniformBuffer(): Buffer {
     if (BINDING_WINDOW_BYTES > maxBindingSize) {
       throw new SkinPaletteOverflowError(BINDING_WINDOW_BYTES, maxBindingSize);
     }
@@ -176,10 +188,20 @@ export function createSkinPaletteAllocator(
       mappedAtCreation: false,
     });
     if (!bufRes.ok) throw bufRes.error;
-    pool.push(bufRes.value);
     return bufRes.value;
   }
 
+  function acquirePoolBuffer(): Buffer {
+    if (poolCursor < pool.length) {
+      const reused = pool[poolCursor];
+      // biome-ignore lint/style/noNonNullAssertion: poolCursor < pool.length guarantees the slot is set
+      return reused!;
+    }
+    const buffer = createUniformBuffer();
+    pool.push(buffer);
+    return buffer;
+  }
+
   function allocateSlice(jointCount: number): SkinPaletteSlice {
     if (useStorageBuffer) {
       // Storage path: shared buffer + dynOffset window.
@@ -209,6 +231,103 @@ export function createSkinPaletteAllocator(
     return { jointCount, byteOffset: 0, buffer };
   }
 
+  function allocateSliceFor(key: string, jointCount: number): SkinPaletteSlice {
+    const existing = stableSlices.get(key);
+    if (existing !== undefined && existing.jointCount === jointCount) return existing;
+    if (existing !== undefined) releaseSliceFor(key);
+    if (useStorageBuffer) {
+      const span =
+        (jointCount * MAT4_BYTES + (PALETTE_OFFSET_ALIGN - 1)) & ~(PALETTE_OFFSET_ALIGN - 1);
+      const freeIndex = stableFreeRanges.findIndex(
+        (range) =>
+          range.buffer === storageBuffer &&
+          range.count >= span &&
+          range.start + BINDING_WINDOW_BYTES <= range.capacity,
+      );
+      let offset: number;
+      let buffer: Buffer;
+      if (freeIndex >= 0) {
+        const range = stableFreeRanges[freeIndex];
+        if (range === undefined) throw new Error('Skin palette free range disappeared.');
+        offset = range.start;
+        buffer = range.buffer;
+        if (range.count === span) stableFreeRanges.splice(freeIndex, 1);
+        else {
+          stableFreeRanges[freeIndex] = {
+            ...range,
+            start: range.start + span,
+            count: range.count - span,
+          };
+        }
+      } else {
+        offset = stableStorageCursor;
+        ensureStorageCapacity(offset + BINDING_WINDOW_BYTES);
+        const currentBuffer = storageBuffer;
+        if (currentBuffer === null) throw new Error('Skin palette storage buffer was not created.');
+        buffer = currentBuffer;
+        stableStorageCursor = offset + span;
+      }
+      const slice = { jointCount, byteOffset: offset, buffer };
+      stableSlices.set(key, slice);
+      return slice;
+    }
+    let buffer = stableUniformBuffers.get(key);
+    if (buffer === undefined) {
+      // Stable slices have a lifetime longer than the frame pool. Allocate a
+      // dedicated UBO so resetForFrame() can never hand it to another entity.
+      buffer = createUniformBuffer();
+      stableUniformBuffers.set(key, buffer);
+    }
+    const slice = { jointCount, byteOffset: 0, buffer };
+    stableSlices.set(key, slice);
+    return slice;
+  }
+
+  function releaseSliceFor(key: string): void {
+    const slice = stableSlices.get(key);
+    if (slice === undefined) return;
+    stableSlices.delete(key);
+    if (!useStorageBuffer) {
+      stableUniformBuffers.delete(key);
+      device.destroyBuffer(slice.buffer);
+      return;
+    }
+    const count =
+      (slice.jointCount * MAT4_BYTES + (PALETTE_OFFSET_ALIGN - 1)) & ~(PALETTE_OFFSET_ALIGN - 1);
+    stableFreeRanges.push({
+      start: slice.byteOffset,
+      count,
+      buffer: slice.buffer,
+      capacity: storageBufferCapacities.get(slice.buffer) ?? storageCapacity,
+    });
+    stableFreeRanges.sort((left, right) => left.start - right.start);
+    for (let index = stableFreeRanges.length - 1; index > 0; index -= 1) {
+      const current = stableFreeRanges[index];
+      const previous = stableFreeRanges[index - 1];
+      if (
+        current === undefined ||
+        previous === undefined ||
+        current.buffer !== previous.buffer ||
+        previous.start + previous.count !== current.start
+      ) {
+        continue;
+      }
+      stableFreeRanges[index - 1] = {
+        start: previous.start,
+        count: previous.count + current.count,
+        buffer: previous.buffer,
+        capacity: previous.capacity,
+      };
+      stableFreeRanges.splice(index, 1);
+    }
+  }
+
+  function retainSliceKeys(keys: ReadonlySet<string>): void {
+    for (const key of stableSlices.keys()) {
+      if (!keys.has(key)) releaseSliceFor(key);
+    }
+  }
+
   function writeJointPalette(
     slice: SkinPaletteSlice,
     ibms: readonly Float32Array[],
@@ -245,6 +364,9 @@ export function createSkinPaletteAllocator(
     bindingWindowBytes: BINDING_WINDOW_BYTES,
     useStorageBuffer,
     allocateSlice,
+    allocateSliceFor,
+    releaseSliceFor,
+    retainSliceKeys,
     writeJointPalette,
     resetForFrame,
   };

package/src/transmission/__tests__/surface-compatibility.integration.test.ts

@@ -0,0 +1,32 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { Materials } from '../../materials';
+
+function shaderSource(name: string): string {
+  return readFileSync(
+    fileURLToPath(new URL(`../../../../shader/src/${name}`, import.meta.url)),
+    'utf8',
+  );
+}
+
+describe('Surface compatibility boundaries', () => {
+  it('keeps transmission on its existing forward shading route', () => {
+    const material = Materials.standard({ baseColor: [1, 1, 1, 1], transmission: 1 });
+    expect(material.passes?.map((pass) => pass.name)).toEqual(['forward', 'shadow-caster']);
+    expect(material.passes?.map((pass) => pass.name)).not.toContain('deferred');
+  });
+
+  it('keeps the unlit sibling outside the Surface ABI', () => {
+    const unlit = shaderSource('unlit.wgsl');
+    expect(unlit).not.toContain('surface_v1');
+    expect(unlit).not.toContain('fs_gbuffer');
+    expect(unlit).toContain('fn fs_main');
+  });
+
+  it('keeps transmission fields out of the v1 Surface contract', () => {
+    const surface = shaderSource('surface_v1.wgsl');
+    expect(surface).not.toMatch(/transmission|thickness|attenuation/i);
+    expect(surface).not.toMatch(/@(vertex|fragment|compute)/);
+  });
+});

package/dist/assembly/material/pipeline-projection.d.ts

@@ -1,30 +0,0 @@
-import type { MaterialRuntimeArtifact } from '@forgeax/engine-shader';
-import type { MaterialValue } from '@forgeax/engine-types';
-import type { MaterialRenderProjection } from './assembly.js';
-export interface MaterialPipelineProjection {
-    readonly specializationKey: string;
-    readonly artifactHash: string;
-    readonly passes: MaterialRenderProjection['passes'];
-}
-export interface MaterialPipelineReady extends MaterialPipelineProjection {
-    readonly kind: 'ready';
-    readonly artifact: MaterialRuntimeArtifact;
-}
-export interface MaterialPipelineMiss {
-    readonly kind: 'error';
-    readonly error: {
-        readonly code: 'material-specialization-not-cooked';
-        readonly expected: string;
-        readonly hint: string;
-        readonly detail: {
-            readonly specializationKey: string;
-        };
-    };
-}
-export declare function projectMaterialPipeline(projection: MaterialRenderProjection): MaterialPipelineProjection;
-export declare function updateMaterialRuntimeValues(projection: MaterialRenderProjection, values: Readonly<Record<string, MaterialValue | null>>): MaterialRenderProjection;
-export declare function routeMaterialPipeline(args: {
-    readonly projection: MaterialRenderProjection;
-    readonly lookupArtifact: (key: string) => MaterialRuntimeArtifact | undefined;
-}): MaterialPipelineReady | MaterialPipelineMiss;
-//# sourceMappingURL=pipeline-projection.d.ts.map

package/dist/assembly/material/pipeline-projection.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pipeline-projection.d.ts","sourceRoot":"","sources":["../../../src/assembly/material/pipeline-projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAE9D,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC,QAAQ,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,qBAAsB,SAAQ,0BAA0B;IACvE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;CAC5C;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,oCAAoC,CAAC;QACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE;YAAE,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;SAAE,CAAC;KACzD,CAAC;CACH;AAED,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,wBAAwB,GACnC,0BAA0B,CAM5B;AAED,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,wBAAwB,EACpC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC,CAAC,GACrD,wBAAwB,CAK1B;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC;IAC9C,QAAQ,CAAC,cAAc,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,uBAAuB,GAAG,SAAS,CAAC;CAC/E,GAAG,qBAAqB,GAAG,oBAAoB,CAc/C"}