@forgeax/engine-render 0.1.27 → 0.1.29

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

@@ -12,3 +12,20 @@ export interface SkinPaletteSlice {
   /** GPU buffer containing the slice's joint matrices. */
   readonly buffer: Buffer;
 }
+
+export interface SkinPaletteDirtyRange {
+  readonly startJoint: number;
+  readonly jointCount: number;
+}
+
+export interface SkinPaletteReceipt extends SkinPaletteSlice {
+  readonly identity: string;
+  readonly generation: number;
+  readonly fence: number;
+  readonly customDataStart: number;
+  readonly storageOrUniform: 'storage' | 'uniform';
+  readonly bounds?: Float32Array;
+  readonly dirtyRanges: readonly SkinPaletteDirtyRange[];
+  readonly uploadBytes: number;
+  readonly retiredByteOffset?: number;
+}

package/src/systems/transparent-dispatch.ts

@@ -0,0 +1,90 @@
+import type { World } from '@forgeax/engine-ecs';
+import { RenderQueue } from '@forgeax/engine-types';
+import type { CameraSnapshot } from '../render-contract';
+import type { DispatchEntry, RenderableSnapshot } from '../render-system-extract';
+import {
+  getTransparentSortConfig,
+  TRANSPARENT_SORT_MODE_DISTANCE,
+  TRANSPARENT_SORT_MODE_LAYER_Y,
+  TRANSPARENT_SORT_MODE_LAYER_YZ,
+  TRANSPARENT_SORT_MODE_LAYER_Z,
+} from './transparent-sort-config';
+
+/**
+ * Reorder only the transparent queue while preserving every opaque slot.
+ * Equal depth/layer values use material identity as a fold-friendly tie break.
+ */
+export function sortTransparentDispatch(
+  dispatch: DispatchEntry[],
+  world: World,
+  cameras: readonly CameraSnapshot[],
+  renderables: readonly RenderableSnapshot[],
+): DispatchEntry[] {
+  const cfg = getTransparentSortConfig(world);
+  const mode = cfg.mode;
+  const transparentSlots: number[] = [];
+  for (let i = 0; i < dispatch.length; i++) {
+    if (dispatch[i]?.queue === RenderQueue.Transparent) transparentSlots.push(i);
+  }
+  if (transparentSlots.length <= 1) return dispatch;
+
+  let sortedSlotOrder: number[];
+  if (mode === TRANSPARENT_SORT_MODE_DISTANCE) {
+    const camera = cameras[0];
+    if (camera === undefined) return dispatch;
+    const camPos = camera.position;
+    const negDistSq = (entry: DispatchEntry): number => {
+      const tx = renderables[entry.renderableIndex]?.transform;
+      if (tx === undefined) return 0;
+      const w = tx.world;
+      const dx = (w[12] ?? 0) - (camPos[0] ?? 0);
+      const dy = (w[13] ?? 0) - (camPos[1] ?? 0);
+      const dz = (w[14] ?? 0) - (camPos[2] ?? 0);
+      return -(dx * dx + dy * dy + dz * dz);
+    };
+    sortedSlotOrder = transparentSlots.slice().sort((a, b) => {
+      const da = negDistSq(dispatch[a] as DispatchEntry);
+      const db = negDistSq(dispatch[b] as DispatchEntry);
+      if (da < db) return -1;
+      if (da > db) return 1;
+      return 0;
+    });
+  } else {
+    const sortVal = (entry: DispatchEntry): number => {
+      const tx = renderables[entry.renderableIndex]?.transform;
+      const w = tx?.world;
+      const posY = (w?.[13] ?? 0) as number;
+      const posZ = (w?.[14] ?? 0) as number;
+      if (mode === TRANSPARENT_SORT_MODE_LAYER_Z) return posZ;
+      const mat = renderables[entry.renderableIndex]?.material;
+      const pivotAndSize = mat?.paramSnapshot?.pivotAndSize as readonly number[] | undefined;
+      const pivotY = (pivotAndSize?.[1] ?? 0.5) as number;
+      const wy4 = (w?.[4] ?? 0) as number;
+      const wy5 = (w?.[5] ?? 1) as number;
+      const wy6 = (w?.[6] ?? 0) as number;
+      const sizeY = Math.sqrt(wy4 * wy4 + wy5 * wy5 + wy6 * wy6);
+      const footY = posY - pivotY * sizeY;
+      if (mode === TRANSPARENT_SORT_MODE_LAYER_Y) return -footY;
+      if (mode === TRANSPARENT_SORT_MODE_LAYER_YZ) return footY + cfg.yzAlpha * posZ;
+      return posZ;
+    };
+    sortedSlotOrder = transparentSlots.slice().sort((a, b) => {
+      const da = dispatch[a] as DispatchEntry;
+      const db = dispatch[b] as DispatchEntry;
+      if (da.layer !== db.layer) return da.layer - db.layer;
+      const va = sortVal(da);
+      const vb = sortVal(db);
+      if (va < vb) return -1;
+      if (va > vb) return 1;
+      return da.materialHandle - db.materialHandle;
+    });
+  }
+
+  const result = dispatch.slice();
+  for (let k = 0; k < transparentSlots.length; k++) {
+    const targetSlot = transparentSlots[k] as number;
+    const sourceSlot = sortedSlotOrder[k] as number;
+    result[targetSlot] = dispatch[sourceSlot] as DispatchEntry;
+  }
+  return result;
+}

package/src/targets/material-source.ts

@@ -39,6 +39,18 @@ export interface RenderTargetMaterialSourceExpectation {
 }
 
 const sourceBindings = new WeakMap<object, RenderTargetMaterialSourceBinding>();
+const targetIdentities = new WeakMap<object, number>();
+let nextTargetIdentity = 1;
+
+function targetIdentity(target: RenderTarget): number {
+  const object = target as object;
+  const existing = targetIdentities.get(object);
+  if (existing !== undefined) return existing;
+  const identity = nextTargetIdentity;
+  nextTargetIdentity += 1;
+  targetIdentities.set(object, identity);
+  return identity;
+}
 
 function sourceToken(): RenderTargetTextureSource {
   return Object.freeze({}) as RenderTargetTextureSource;
@@ -51,6 +63,28 @@ export function resolveRenderTargetMaterialSource(
   return sourceBindings.get(source as object);
 }
 
+/**
+ * Returns the stable renderer-local resource identity used by batch grouping.
+ * The opaque source object is intentionally not stringified: target identity,
+ * device generation, and view subresource are the producer-owned facts that
+ * determine whether two draws may share one material bind group.
+ */
+export function renderTargetMaterialSourceIdentity(
+  source: RenderTargetTextureSource,
+): string | undefined {
+  const binding = resolveRenderTargetMaterialSource(source);
+  if (binding === undefined) return undefined;
+  return [
+    targetIdentity(binding.target),
+    binding.generation,
+    binding.shape,
+    binding.format,
+    binding.view.dimension,
+    binding.view.mipLevel,
+    binding.view.resolveRequired ? 1 : 0,
+  ].join(':');
+}
+
 function invalid(
   field: string,
   value: unknown,

package/src/temporal/coverage.ts

@@ -23,7 +23,7 @@ export function createTemporalCoverage(width: number, height: number): TemporalC
   if (!Number.isSafeInteger(width) || width <= 0) throw new RangeError('width must be positive.');
   if (!Number.isSafeInteger(height) || height <= 0)
     throw new RangeError('height must be positive.');
-  return Object.freeze({ width, height, bytes: 32 * width * height, fullScreen: true as const });
+  return Object.freeze({ width, height, bytes: 34 * width * height, fullScreen: true as const });
 }
 
 export type SceneDataContributorKind = 'exact' | 'reactive';

package/src/temporal/frame-coordinator.ts

@@ -12,6 +12,9 @@ import {
 /** The only stages that may publish a temporal frame. */
 export type TemporalFrameStage = 'build' | 'encode' | 'finish' | 'submit';
 
+/** Closed list of consumers that share the renderer temporal transaction. */
+export type TemporalFrameConsumerId = 'taa' | 'motion-blur' | 'ssr';
+
 export type TemporalFrameErrorCode = 'taa-unavailable' | 'temporal-active' | 'temporal-not-active';
 
 export interface TemporalFrameError {
@@ -24,6 +27,7 @@ export interface TemporalFrameError {
 export interface TemporalFrameSnapshot<T = unknown> {
   readonly epoch: number;
   readonly previous: T | undefined;
+  readonly consumerIds: readonly TemporalFrameConsumerId[];
   readonly historyAttempt: 'none' | 'active' | 'committed' | 'aborted';
   readonly attempt: 'none' | 'active' | 'committed' | 'aborted';
   readonly lastFailure: TemporalFrameStage | undefined;
@@ -40,6 +44,8 @@ export interface TemporalFrameBeginInput<T = unknown> {
   readonly antialias: 'none' | 'fxaa' | 'msaa' | 'taa';
   /** Enables the shared transaction for a temporal feature without TAA. */
   readonly temporalDemand?: boolean;
+  /** Consumers registered on this one renderer-owned frame transaction. */
+  readonly consumerIds?: readonly TemporalFrameConsumerId[];
   readonly available?: boolean;
   readonly contributors?: readonly SceneDataContributor[];
   readonly requiredContributorIds?: readonly string[];
@@ -54,6 +60,7 @@ export interface TemporalFrameCandidate<T = unknown> {
   readonly history: { readonly direction: 'a-to-b' | 'b-to-a'; readonly valid: boolean };
   readonly contributors: readonly SceneDataContributor[];
   readonly requiredContributorIds: readonly string[];
+  readonly consumerIds: readonly TemporalFrameConsumerId[];
   readonly temporalView?: TemporalView;
 }
 
@@ -116,6 +123,7 @@ export class TemporalFrameCoordinator<T = unknown> {
   readonly historyStore: TaaHistoryStore;
   private epoch: number;
   private previous: T | undefined;
+  private consumerIds: readonly TemporalFrameConsumerId[] = [];
   private active: TemporalFrameCandidate<T> | undefined;
   private attempt: TemporalFrameSnapshot<T>['attempt'] = 'none';
   private historyAttempt: TemporalFrameSnapshot<T>['historyAttempt'] = 'none';
@@ -144,7 +152,9 @@ export class TemporalFrameCoordinator<T = unknown> {
   }
 
   begin(input: TemporalFrameBeginInput<T>): Result<TemporalFrameCandidate<T>, TemporalFrameError> {
-    const demanded = input.antialias === 'taa' || input.temporalDemand === true;
+    const consumerIds = Object.freeze([...(input.consumerIds ?? [])]);
+    const demanded =
+      input.antialias === 'taa' || input.temporalDemand === true || consumerIds.length > 0;
     if (!demanded) {
       return ok({
         epoch: this.epoch,
@@ -153,6 +163,7 @@ export class TemporalFrameCoordinator<T = unknown> {
         history: { direction: this.historyDirection, valid: false },
         contributors: Object.freeze([...(input.contributors ?? [])]),
         requiredContributorIds: Object.freeze([...(input.requiredContributorIds ?? [])]),
+        consumerIds,
         ...(input.temporalView === undefined ? {} : { temporalView: input.temporalView }),
       });
     }
@@ -176,6 +187,7 @@ export class TemporalFrameCoordinator<T = unknown> {
       history: { direction: this.historyDirection, valid: this.previous !== undefined },
       contributors: Object.freeze([...(input.contributors ?? [])]),
       requiredContributorIds: Object.freeze([...(input.requiredContributorIds ?? [])]),
+      consumerIds,
       ...(input.temporalView === undefined ? {} : { temporalView: input.temporalView }),
     };
     if (input.antialias === 'taa') {
@@ -201,6 +213,7 @@ export class TemporalFrameCoordinator<T = unknown> {
       this.temporalFrameIndex += 1;
     }
     this.historyDirection = candidate.history.direction === 'a-to-b' ? 'b-to-a' : 'a-to-b';
+    this.consumerIds = candidate.consumerIds;
     const historyAttempt = this.historyAttempts.get(candidate);
     historyAttempt?.commit({
       deviceGeneration: this.historyStore.inspect().deviceGeneration,
@@ -239,7 +252,13 @@ export class TemporalFrameCoordinator<T = unknown> {
     const started = this.begin(input);
     if (!started.ok) return started;
     const candidate = started.value;
-    if (input.antialias !== 'taa' && input.temporalDemand !== true) return ok(undefined);
+    if (
+      input.antialias !== 'taa' &&
+      input.temporalDemand !== true &&
+      (input.consumerIds?.length ?? 0) === 0
+    ) {
+      return ok(undefined);
+    }
     try {
       const built = phases.build();
       phases.encode(built);
@@ -262,6 +281,7 @@ export class TemporalFrameCoordinator<T = unknown> {
     return {
       epoch: this.epoch,
       previous: this.previous,
+      consumerIds: this.consumerIds,
       historyAttempt: this.historyAttempt,
       attempt: this.attempt,
       lastFailure: this.lastFailure,
@@ -327,6 +347,7 @@ export class TemporalFrameCoordinator<T = unknown> {
       missingContributorIds: [],
       omittedMissingContributorCount: 0,
     };
+    this.consumerIds = [];
   }
 
   private stageFromError(cause: unknown): TemporalFrameStage {

package/src/temporal/gpu.ts

@@ -5,6 +5,7 @@ import type {
   RhiQueue,
   Sampler,
   Texture,
+  TextureFormat,
   TextureView,
 } from '@forgeax/engine-rhi';
 import type { DeviceScope } from '../device/device-scope';
@@ -16,6 +17,12 @@ import {
 import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
 import type { RenderFrameState } from '../record/frame-snapshot';
 
+export const TEMPORAL_HISTORY_FORMATS = Object.freeze({
+  color: 'rgba16float',
+  temporal: 'rgba16float',
+  stability: 'r8unorm',
+} as const);
+
 interface TemporalSurface {
   readonly texture: Texture;
   readonly view: TextureView;
@@ -32,8 +39,10 @@ export interface TemporalGpuState {
   pendingIndex: 0 | 1 | undefined;
   readonly color: [TemporalSurface, TemporalSurface];
   readonly temporal: [TemporalSurface, TemporalSurface];
+  readonly stability: [TemporalSurface, TemporalSurface];
   bindGroupLayout: BindGroupLayout | undefined;
   sampler: Sampler | undefined;
+  temporalSampler: Sampler | undefined;
   paramsBuffer: Buffer | undefined;
   committed: boolean;
 }
@@ -44,11 +53,12 @@ function createSurface(
   label: string,
   width: number,
   height: number,
+  format: TextureFormat = TEMPORAL_HISTORY_FORMATS.color,
 ): TemporalSurface {
   const texture = device.createTexture({
     label,
     size: { width, height, depthOrArrayLayers: 1 },
-    format: 'rgba16float',
+    format,
     textureBindingViewDimension: undefined,
     usage:
       GPU_TEXTURE_USAGE_COPY_SRC |
@@ -93,11 +103,44 @@ function createState(
         createSurface(device, childScope, 'taa-history-color-b', width, height),
       ],
       temporal: [
-        createSurface(device, childScope, 'taa-history-temporal-a', width, height),
-        createSurface(device, childScope, 'taa-history-temporal-b', width, height),
+        createSurface(
+          device,
+          childScope,
+          'taa-history-temporal-a',
+          width,
+          height,
+          TEMPORAL_HISTORY_FORMATS.temporal,
+        ),
+        createSurface(
+          device,
+          childScope,
+          'taa-history-temporal-b',
+          width,
+          height,
+          TEMPORAL_HISTORY_FORMATS.temporal,
+        ),
+      ],
+      stability: [
+        createSurface(
+          device,
+          childScope,
+          'taa-history-stability-a',
+          width,
+          height,
+          TEMPORAL_HISTORY_FORMATS.stability,
+        ),
+        createSurface(
+          device,
+          childScope,
+          'taa-history-stability-b',
+          width,
+          height,
+          TEMPORAL_HISTORY_FORMATS.stability,
+        ),
       ],
       bindGroupLayout: undefined,
       sampler: undefined,
+      temporalSampler: undefined,
       paramsBuffer: undefined,
       committed: false,
     };
@@ -111,7 +154,7 @@ export function getTemporalParamsBuffer(state: TemporalGpuState): Buffer {
   if (state.paramsBuffer !== undefined) return state.paramsBuffer;
   const created = state.device.createBuffer({
     label: 'taa-resolve-params',
-    size: 16,
+    size: 32,
     usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
     mappedAtCreation: false,
   });
@@ -122,7 +165,7 @@ export function getTemporalParamsBuffer(state: TemporalGpuState): Buffer {
   state.childScope._adopt('buffer', created.value, (value) => {
     state.device.destroyBuffer(value);
   });
-  const written = state.device.queue.writeBuffer(created.value, 0, new Uint8Array(16));
+  const written = state.device.queue.writeBuffer(created.value, 0, new Uint8Array(32));
   if (!written.ok) {
     if (!state.committed) state.childScope.abandon();
     throw written.error;
@@ -164,11 +207,13 @@ export function getTemporalGpuState(
 export function getTemporalBindGroupResources(state: TemporalGpuState): {
   readonly layout: BindGroupLayout;
   readonly sampler: Sampler | null;
+  readonly temporalSampler: Sampler | null;
 } {
   if (state.bindGroupLayout !== undefined) {
     return {
       layout: state.bindGroupLayout,
       sampler: state.sampler ?? null,
+      temporalSampler: state.temporalSampler ?? null,
     };
   }
   try {
@@ -178,15 +223,15 @@ export function getTemporalBindGroupResources(state: TemporalGpuState): {
         {
           binding: 0,
           visibility: 2,
-          texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+          texture: { sampleType: 'float', viewDimension: '2d' },
         },
-        { binding: 1, visibility: 2, sampler: { type: 'non-filtering' } },
+        { binding: 1, visibility: 2, sampler: { type: 'filtering' } },
         {
           binding: 2,
           visibility: 2,
-          texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+          texture: { sampleType: 'float', viewDimension: '2d' },
         },
-        { binding: 3, visibility: 2, sampler: { type: 'non-filtering' } },
+        { binding: 3, visibility: 2, sampler: { type: 'filtering' } },
         {
           binding: 4,
           visibility: 2,
@@ -200,6 +245,12 @@ export function getTemporalBindGroupResources(state: TemporalGpuState): {
         },
         { binding: 7, visibility: 2, sampler: { type: 'non-filtering' } },
         { binding: 8, visibility: 2, buffer: { type: 'uniform' } },
+        { binding: 9, visibility: 2, texture: { sampleType: 'float', viewDimension: '2d' } },
+        {
+          binding: 10,
+          visibility: 2,
+          texture: { sampleType: 'unfilterable-float', viewDimension: '2d' },
+        },
       ],
     });
     if (!layout.ok) throw layout.error;
@@ -207,19 +258,29 @@ export function getTemporalBindGroupResources(state: TemporalGpuState): {
     const sampler = state.device.createSampler({
       addressModeU: 'clamp-to-edge',
       addressModeV: 'clamp-to-edge',
-      magFilter: 'nearest',
-      minFilter: 'nearest',
+      magFilter: 'linear',
+      minFilter: 'linear',
     });
     if (!sampler.ok) throw sampler.error;
     state.childScope._adopt('binding', sampler.value, () => undefined);
+    const temporalSampler = state.device.createSampler({
+      addressModeU: 'clamp-to-edge',
+      addressModeV: 'clamp-to-edge',
+      magFilter: 'nearest',
+      minFilter: 'nearest',
+    });
+    if (!temporalSampler.ok) throw temporalSampler.error;
+    state.childScope._adopt('binding', temporalSampler.value, () => undefined);
     state.bindGroupLayout = layout.value;
     state.sampler = sampler.value;
-    return { layout: layout.value, sampler: sampler.value };
+    state.temporalSampler = temporalSampler.value;
+    return { layout: layout.value, sampler: sampler.value, temporalSampler: temporalSampler.value };
   } catch (cause) {
     if (!state.committed) {
       state.childScope.abandon();
       state.bindGroupLayout = undefined;
       state.sampler = undefined;
+      state.temporalSampler = undefined;
     }
     throw cause;
   }
@@ -261,6 +322,7 @@ export function retireTemporalGpuState(state: TemporalGpuState): void {
   state.committed = false;
   state.bindGroupLayout = undefined;
   state.sampler = undefined;
+  state.temporalSampler = undefined;
   state.paramsBuffer = undefined;
 }
 

package/src/temporal/history.ts

@@ -41,7 +41,7 @@ export class TemporalHistory {
           bytes: 0,
           fullScreen: true as const,
         });
-    this.historyCount = taa ? 4 : 0;
+    this.historyCount = taa ? 6 : 0;
     this.historyBytes = this.coverage.bytes;
     if (!taa) {
       this.resources = [];
@@ -54,6 +54,8 @@ export class TemporalHistory {
       child.ref('texture', Object.freeze({ slot: 'color-b' })),
       child.ref('texture', Object.freeze({ slot: 'temporal-a' })),
       child.ref('texture', Object.freeze({ slot: 'temporal-b' })),
+      child.ref('texture', Object.freeze({ slot: 'stability-a' })),
+      child.ref('texture', Object.freeze({ slot: 'stability-b' })),
     ]);
   }
 

package/src/temporal/inspection.ts

@@ -1,3 +1,4 @@
+import { createTemporalCoverage } from './coverage';
 import type { TemporalGpuState } from './gpu';
 import type { TemporalHistory } from './history';
 import type { TemporalView } from './view';
@@ -28,7 +29,7 @@ export interface TemporalInspection {
 }
 
 function gpuBytes(state: TemporalGpuState | undefined): number {
-  return state === undefined ? 0 : state.width * state.height * 32;
+  return state === undefined ? 0 : createTemporalCoverage(state.width, state.height).bytes;
 }
 
 function gpuResources(state: TemporalGpuState | undefined): number {

package/src/temporal/standard-scene-data.ts

@@ -11,10 +11,11 @@ import { addTypedFullscreenPass, addTypedScenePass } from '../typed-render-graph
 export interface StandardTemporalDemandInput {
   readonly taa: boolean;
   readonly motionBlur: boolean;
+  readonly ssr?: boolean;
 }
 
 export interface StandardTemporalDemand {
-  readonly consumerIds: readonly ('taa' | 'motion-blur')[];
+  readonly consumerIds: readonly ('taa' | 'motion-blur' | 'ssr')[];
   readonly targetCount: 0 | 1;
   readonly producerPassCount: 0 | 1;
   readonly historyCount: 0 | 1;
@@ -35,6 +36,7 @@ export function aggregateTemporalDemand(
   const consumerIds = [
     ...(input.taa ? (['taa'] as const) : []),
     ...(input.motionBlur ? (['motion-blur'] as const) : []),
+    ...(input.ssr ? (['ssr'] as const) : []),
   ];
   const requested = consumerIds.length > 0;
   return Object.freeze({

package/src/temporal/temporal-view.ts

@@ -4,6 +4,9 @@ import type { CameraSnapshot } from '../render-contract';
 
 export const TEMPORAL_JITTER_SAMPLE_COUNT = 8;
 
+/** Current temporal view owns fixed surface dimensions; dynamic TAAU is deferred. */
+export const TEMPORAL_TAAU_DEPENDENCY_STATUS = 'dependency-deferred' as const;
+
 export type TemporalViewResetReason =
   | 'first-frame'
   | 'camera-switch'