@forgeax/engine-render 0.1.4 → 0.1.6

package/src/record/shadow-caster-uniform.ts

@@ -1,37 +0,0 @@
-import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
-import type { ExtractedLights } from '../render-system-extract';
-
-export const SHADOW_CASTER_SLOT_STRIDE = 256;
-export const SHADOW_CASTER_BUFFER_SIZE = SHADOW_CASTER_SLOT_STRIDE * 8;
-
-export function directionalShadowCasterOffset(cascadeIndex: number): number {
-  return SHADOW_CASTER_SLOT_STRIDE * cascadeIndex;
-}
-
-export function spotShadowCasterOffset(tile: number): number {
-  return SHADOW_CASTER_SLOT_STRIDE * (4 + tile);
-}
-
-export function writeShadowCasterUniforms(
-  queue: RhiQueue,
-  buffer: Buffer,
-  lights: ExtractedLights,
-): void {
-  for (let cascade = 0; cascade < 4; cascade += 1) {
-    const written = queue.writeBuffer(
-      buffer,
-      directionalShadowCasterOffset(cascade),
-      new Uint32Array([cascade, 0, 0, 0]),
-    );
-    if (!written.ok) throw written.error;
-  }
-  for (const snapshot of lights.spot) {
-    const tile = snapshot.shadowAtlasTile;
-    if (tile < 0 || tile >= 4 || snapshot.lightViewProj === undefined) continue;
-    const offset = spotShadowCasterOffset(tile);
-    const header = queue.writeBuffer(buffer, offset, new Uint32Array([0, 1, 0, 0]));
-    if (!header.ok) throw header.error;
-    const matrix = queue.writeBuffer(buffer, offset + 16, snapshot.lightViewProj);
-    if (!matrix.ok) throw matrix.error;
-  }
-}

package/src/record/shadow-submit-mode.ts

@@ -1,277 +0,0 @@
-import type { CommandBuffer } from '@forgeax/engine-rhi';
-
-export const SHADOW_SUBMIT_MODES = ['independent', 'coalesced-with-frame'] as const;
-export type ShadowSubmitMode = (typeof SHADOW_SUBMIT_MODES)[number];
-
-export interface RendererOwnerIdentity {
-  readonly carrierId: string;
-  readonly pageIdentity: string;
-  readonly browserRealmId: string;
-  readonly runtimeId: string;
-  readonly canvasIdentity: string;
-  readonly rendererGeneration: string;
-}
-
-export interface ShadowSubmitModeRequest {
-  readonly schema: 'renderer-owner-admission/v1';
-  readonly shadowSubmitMode: ShadowSubmitMode;
-  readonly identity: RendererOwnerIdentity;
-}
-
-export interface ShadowSubmitModeError {
-  readonly code: string;
-  readonly category: 'precondition' | 'state';
-  readonly expected: unknown;
-  readonly observed: unknown;
-  readonly hint: string;
-  readonly recoveryActions: readonly ['renderer.ownerAdmission.rediscover'];
-  readonly safeRerun: true;
-}
-
-export type ShadowSubmitResult<T> =
-  | { readonly ok: true; readonly value: T }
-  | { readonly ok: false; readonly error: ShadowSubmitModeError };
-
-const IDENTITY_FIELDS = [
-  'carrierId',
-  'pageIdentity',
-  'browserRealmId',
-  'runtimeId',
-  'canvasIdentity',
-  'rendererGeneration',
-] as const;
-
-function record(value: unknown): Record<string, unknown> {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : {};
-}
-
-function failure(code: string, expected: unknown, observed: unknown): ShadowSubmitResult<never> {
-  return {
-    ok: false,
-    error: {
-      code,
-      category: 'precondition',
-      expected,
-      observed,
-      hint: 'Stop the selected public run, rediscover the renderer owner capability, and retry on one fresh carrier.',
-      recoveryActions: ['renderer.ownerAdmission.rediscover'],
-      safeRerun: true,
-    },
-  };
-}
-
-function isShadowSubmitMode(value: unknown): value is ShadowSubmitMode {
-  return typeof value === 'string' && (SHADOW_SUBMIT_MODES as readonly string[]).includes(value);
-}
-
-export function validateShadowSubmitModeRequest(
-  value: unknown,
-): ShadowSubmitResult<ShadowSubmitModeRequest> {
-  const input = record(value);
-  if (input.schema !== 'renderer-owner-admission/v1') {
-    return failure(
-      'renderer-owner-admission-invalid-schema',
-      { schema: 'renderer-owner-admission/v1' },
-      { schema: input.schema },
-    );
-  }
-  if (!isShadowSubmitMode(input.shadowSubmitMode)) {
-    return failure(
-      'renderer-owner-admission-invalid-mode',
-      { shadowSubmitMode: SHADOW_SUBMIT_MODES },
-      { shadowSubmitMode: input.shadowSubmitMode },
-    );
-  }
-  const candidateIdentity = record(input.identity);
-  const missingField = IDENTITY_FIELDS.find((field) => {
-    const fieldValue = candidateIdentity[field];
-    return typeof fieldValue !== 'string' || fieldValue.trim() === '';
-  });
-  if (missingField !== undefined) {
-    return failure(
-      'renderer-owner-admission-identity-mismatch',
-      { identityFields: IDENTITY_FIELDS },
-      { missingField, rendererGeneration: candidateIdentity.rendererGeneration },
-    );
-  }
-  return {
-    ok: true,
-    value: {
-      schema: 'renderer-owner-admission/v1',
-      shadowSubmitMode: input.shadowSubmitMode,
-      identity: candidateIdentity as unknown as RendererOwnerIdentity,
-    },
-  };
-}
-
-export interface ShadowSubmitFrame<TCommandBuffer> {
-  readonly rendererGeneration: string;
-  readonly expectedRendererGeneration?: string;
-  readonly shadowCommandBuffers: readonly TCommandBuffer[];
-  readonly frameCommandBuffer: TCommandBuffer;
-  readonly drawCaptureParity: unknown;
-}
-
-export interface ShadowSubmitPlan<TCommandBuffer> {
-  readonly shadowSubmitMode: ShadowSubmitMode;
-  readonly rendererGeneration: string;
-  readonly rawSubmissions: readonly { readonly commandBuffers: readonly TCommandBuffer[] }[];
-  readonly deferredShadowCommandBuffers: readonly TCommandBuffer[];
-  readonly rawSubmitCount: number;
-  readonly reRecorded: false;
-  readonly drawCaptureParity: unknown;
-}
-
-export function createShadowSubmitPlan<TCommandBuffer>(
-  input: ShadowSubmitFrame<TCommandBuffer> & { readonly shadowSubmitMode: ShadowSubmitMode },
-): ShadowSubmitResult<ShadowSubmitPlan<TCommandBuffer>> {
-  if (input.rendererGeneration.trim() === '') {
-    return failure(
-      'renderer-owner-admission-generation-mismatch',
-      { rendererGeneration: 'non-empty' },
-      { rendererGeneration: input.rendererGeneration },
-    );
-  }
-  if (
-    input.expectedRendererGeneration !== undefined &&
-    input.expectedRendererGeneration !== input.rendererGeneration
-  ) {
-    return failure(
-      'renderer-owner-admission-generation-mismatch',
-      { rendererGeneration: input.expectedRendererGeneration },
-      { rendererGeneration: input.rendererGeneration },
-    );
-  }
-  if (!isShadowSubmitMode(input.shadowSubmitMode)) {
-    return failure(
-      'renderer-owner-admission-invalid-mode',
-      { shadowSubmitMode: SHADOW_SUBMIT_MODES },
-      { shadowSubmitMode: input.shadowSubmitMode },
-    );
-  }
-
-  const independentSubmissions = input.shadowCommandBuffers.map((commandBuffer) => ({
-    commandBuffers: [commandBuffer],
-  }));
-  const rawSubmissions =
-    input.shadowSubmitMode === 'coalesced-with-frame'
-      ? [{ commandBuffers: [...input.shadowCommandBuffers, input.frameCommandBuffer] }]
-      : [...independentSubmissions, { commandBuffers: [input.frameCommandBuffer] }];
-  return {
-    ok: true,
-    value: {
-      shadowSubmitMode: input.shadowSubmitMode,
-      rendererGeneration: input.rendererGeneration,
-      rawSubmissions,
-      deferredShadowCommandBuffers:
-        input.shadowSubmitMode === 'coalesced-with-frame' ? [...input.shadowCommandBuffers] : [],
-      rawSubmitCount: rawSubmissions.length,
-      reRecorded: false,
-      drawCaptureParity: input.drawCaptureParity,
-    },
-  };
-}
-
-export interface ShadowSubmitModeState {
-  readonly mode: ShadowSubmitMode;
-  readonly rendererGeneration: string | null;
-  readonly appliedCount: number;
-  readonly restoredCount: number;
-  readonly active: boolean;
-}
-
-export function createShadowSubmitModeState(): ShadowSubmitModeState {
-  return {
-    mode: 'independent',
-    rendererGeneration: null,
-    appliedCount: 0,
-    restoredCount: 0,
-    active: false,
-  };
-}
-
-export function applyShadowSubmitMode(
-  state: ShadowSubmitModeState,
-  mode: ShadowSubmitMode,
-  rendererGeneration: string,
-): ShadowSubmitResult<ShadowSubmitModeState> {
-  if (!isShadowSubmitMode(mode)) {
-    return failure(
-      'renderer-owner-admission-invalid-mode',
-      { shadowSubmitMode: SHADOW_SUBMIT_MODES },
-      { shadowSubmitMode: mode },
-    );
-  }
-  if (rendererGeneration.trim() === '') {
-    return failure(
-      'renderer-owner-admission-generation-mismatch',
-      { rendererGeneration: 'non-empty' },
-      { rendererGeneration },
-    );
-  }
-  if (state.rendererGeneration !== null && state.rendererGeneration !== rendererGeneration) {
-    return failure(
-      'renderer-owner-admission-generation-mismatch',
-      { rendererGeneration: state.rendererGeneration },
-      { rendererGeneration },
-    );
-  }
-  if (state.active) {
-    return state.mode === mode
-      ? { ok: true, value: state }
-      : failure(
-          'renderer-owner-admission-mode-already-applied',
-          { shadowSubmitMode: state.mode },
-          { shadowSubmitMode: mode },
-        );
-  }
-  return {
-    ok: true,
-    value: {
-      mode,
-      rendererGeneration,
-      appliedCount: state.appliedCount + 1,
-      restoredCount: state.restoredCount,
-      active: true,
-    },
-  };
-}
-
-export function restoreShadowSubmitMode(
-  state: ShadowSubmitModeState,
-  rendererGeneration: string,
-): ShadowSubmitResult<ShadowSubmitModeState> {
-  if (state.rendererGeneration !== null && state.rendererGeneration !== rendererGeneration) {
-    return failure(
-      'renderer-owner-admission-generation-mismatch',
-      { rendererGeneration: state.rendererGeneration },
-      { rendererGeneration },
-    );
-  }
-  if (!state.active) return { ok: true, value: state };
-  return {
-    ok: true,
-    value: {
-      ...state,
-      mode: 'independent',
-      restoredCount: state.restoredCount + 1,
-      active: false,
-    },
-  };
-}
-
-export function commandBufferPlanForFrame(
-  state: ShadowSubmitModeState,
-  pendingShadowCommandBuffers: readonly CommandBuffer[],
-  frameCommandBuffer: CommandBuffer,
-): ShadowSubmitResult<ShadowSubmitPlan<CommandBuffer>> {
-  return createShadowSubmitPlan({
-    shadowSubmitMode: state.mode,
-    rendererGeneration: state.rendererGeneration ?? 'renderer-generation-0',
-    shadowCommandBuffers: pendingShadowCommandBuffers,
-    frameCommandBuffer,
-    drawCaptureParity: null,
-  });
-}

package/src/render-dispatch-membership.ts

@@ -1,155 +0,0 @@
-import {
-  buildDirectionalCsmCasterCandidates,
-  type DirectionalCsmCandidateSource,
-  type DirectionalCsmCasterCandidate,
-} from './extract/directional-csm';
-import type { DispatchEntry, RenderableSnapshot } from './render-system-extract';
-
-function candidateIdentity(candidate: RenderableSnapshot): string {
-  return `${candidate.worldId}:${candidate.entityKey}`;
-}
-
-/**
- * Immutable candidate-domain membership derived from one dispatch snapshot.
- *
- * The dispatch array is the identity of the snapshot. Consumers may retain
- * this owner across camera-only culls, but must publish a new owner whenever
- * the candidate dispatch array changes. Keeping the Set here prevents the
- * extract and persistent-scene paths from each rebuilding or rescanning the
- * same dispatch domain.
- */
-export interface RenderDispatchMembership {
-  readonly dispatch: readonly DispatchEntry[];
-  readonly shadowCasterCandidateIndices: ReadonlySet<number>;
-}
-
-/**
- * Immutable owner for the complete pre-main-cull candidate domain.
- *
- * The candidate array and its dispatch are a pair: the former gives the
- * stable renderable index and the latter gives pass ownership. Keeping the
- * identity index beside the dispatch membership means persistent CSM
- * broadphase joins do not rebuild a string map for every camera/cascade
- * refresh, and every consumer uses the same candidate-domain identity.
- */
-export interface RenderCandidateDomain {
-  readonly renderables: readonly RenderableSnapshot[];
-  readonly dispatch: readonly DispatchEntry[];
-  readonly membership: RenderDispatchMembership;
-  readonly indexByIdentity: ReadonlyMap<string, number>;
-}
-
-const membershipByDispatch = new WeakMap<readonly DispatchEntry[], RenderDispatchMembership>();
-const candidateDomainByRenderables = new WeakMap<
-  readonly RenderableSnapshot[],
-  WeakMap<readonly DispatchEntry[], RenderCandidateDomain>
->();
-const csmCandidatesByDomain = new WeakMap<
-  RenderCandidateDomain,
-  readonly DirectionalCsmCasterCandidate[]
->();
-
-export function buildRenderDispatchMembership(
-  dispatch: readonly DispatchEntry[],
-): RenderDispatchMembership {
-  const cached = membershipByDispatch.get(dispatch);
-  if (cached !== undefined) return cached;
-
-  const shadowCasterCandidateIndices = new Set<number>();
-  for (const entry of dispatch) {
-    if (entry.tags.LightMode === 'ShadowCaster') {
-      shadowCasterCandidateIndices.add(entry.renderableIndex);
-    }
-  }
-  const membership: RenderDispatchMembership = {
-    dispatch,
-    shadowCasterCandidateIndices,
-  };
-  membershipByDispatch.set(dispatch, membership);
-  return membership;
-}
-
-/** Reuse an extracted owner only when it still belongs to this dispatch. */
-export function reuseRenderDispatchMembership(
-  dispatch: readonly DispatchEntry[],
-  existing: RenderDispatchMembership | undefined,
-): RenderDispatchMembership {
-  return existing?.dispatch === dispatch ? existing : buildRenderDispatchMembership(dispatch);
-}
-
-export function buildRenderCandidateDomain(
-  renderables: readonly RenderableSnapshot[],
-  dispatch: readonly DispatchEntry[],
-  indexByIdentity?: ReadonlyMap<string, number>,
-): RenderCandidateDomain {
-  let byDispatch = candidateDomainByRenderables.get(renderables);
-  if (byDispatch === undefined) {
-    byDispatch = new WeakMap<readonly DispatchEntry[], RenderCandidateDomain>();
-    candidateDomainByRenderables.set(renderables, byDispatch);
-  }
-  const cached = byDispatch.get(dispatch);
-  if (cached !== undefined) return cached;
-
-  const stableIndexByIdentity = indexByIdentity ?? buildRenderCandidateIdentityIndex(renderables);
-  const domain: RenderCandidateDomain = {
-    renderables,
-    dispatch,
-    membership: buildRenderDispatchMembership(dispatch),
-    indexByIdentity: stableIndexByIdentity,
-  };
-  byDispatch.set(dispatch, domain);
-  return domain;
-}
-
-/** Build the candidate identity join once for a new immutable candidate array. */
-export function buildRenderCandidateIdentityIndex(
-  renderables: readonly RenderableSnapshot[],
-): ReadonlyMap<string, number> {
-  const indexByIdentity = new Map<string, number>();
-  for (let index = 0; index < renderables.length; index += 1) {
-    const candidate = renderables[index];
-    if (candidate !== undefined) indexByIdentity.set(candidateIdentity(candidate), index);
-  }
-  return indexByIdentity;
-}
-
-export function reuseRenderCandidateDomain(
-  renderables: readonly RenderableSnapshot[],
-  dispatch: readonly DispatchEntry[],
-  existing: RenderCandidateDomain | undefined,
-): RenderCandidateDomain {
-  return existing?.renderables === renderables && existing.dispatch === dispatch
-    ? existing
-    : buildRenderCandidateDomain(renderables, dispatch);
-}
-
-/**
- * Lazily derive the CSM caster view once for a candidate-domain owner.
- *
- * CSM fitting is camera-dependent, but the candidate-to-caster projection is
- * not. Keeping this derived array beside the dispatch membership prevents
- * persistent camera refreshes from rebuilding transformed caster bounds for
- * every cascade while preserving the candidate-domain identity contract.
- */
-export function renderCandidateCsmCandidates(
-  domain: RenderCandidateDomain,
-): readonly DirectionalCsmCasterCandidate[] {
-  const cached = csmCandidatesByDomain.get(domain);
-  if (cached !== undefined) return cached;
-
-  const sources: DirectionalCsmCandidateSource[] = domain.renderables.map(
-    (candidate, renderableIndex) => ({
-      renderableIndex,
-      worldId: candidate.worldId,
-      entityKey: candidate.entityKey,
-      localAabb: candidate.localAabb,
-      transformWorld: candidate.boundsWorld ?? candidate.transform.world,
-      instanceTransforms: candidate.candidateInstanceTransforms ?? candidate.instances?.transforms,
-      featureOwnedBoundsUnavailable: candidate.skin !== undefined,
-      shadowCaster: domain.membership.shadowCasterCandidateIndices.has(renderableIndex),
-    }),
-  );
-  const derived = Object.freeze(buildDirectionalCsmCasterCandidates(sources));
-  csmCandidatesByDomain.set(domain, derived);
-  return derived;
-}