@forgeax/engine-render 0.1.34 → 0.1.35

package/src/publication/contract.ts

@@ -0,0 +1,104 @@
+import type { TimeResource } from '@forgeax/engine-ecs';
+import type { MaterialRuntimeArtifact, MaterialShaderEntry } from '@forgeax/engine-shader';
+import type { Asset, Handle } from '@forgeax/engine-types';
+import type { DispatchEntry, ExtractedFrame, RenderableSnapshot } from '../render-system-extract';
+import type { TransparentSortConfig } from '../systems/transparent-sort-config';
+import type { PublishedRenderTarget, PublishedRenderTargetSource } from './targets';
+
+/** Chosen by App before creating the receiver; never inferred from the first packet. */
+export interface RenderPublicationIdentity {
+  readonly source: string;
+  readonly epoch: number;
+}
+
+export type RenderPublicationMetadata = Omit<
+  ExtractedFrame,
+  | 'renderables'
+  | 'dispatch'
+  | 'visibilitySnapshots'
+  | 'featureVisibilitySnapshots'
+  | 'hiddenEntityReports'
+  | 'shadowCasterEntityKeys'
+  | 'shadowCasterDrawKeys'
+  | 'shadowCasterMembership'
+>;
+
+export interface RenderPublicationTemplate {
+  readonly snapshot: Omit<RenderableSnapshot, 'worldId' | 'entityKey' | 'transform'>;
+  readonly dispatch: readonly Omit<DispatchEntry, 'entityIndex' | 'renderableIndex'>[];
+}
+
+/** Numeric storage is publisher-owned; no ECS or asset buffer is transferred. */
+export interface RenderPublication extends RenderPublicationIdentity {
+  readonly revision: number;
+  readonly base: number;
+  readonly baseline: boolean;
+  readonly time: TimeResource;
+  readonly sampleTimeSeconds: number;
+  readonly temporalReset: boolean;
+  readonly transparentSort: TransparentSortConfig;
+  readonly metadata: RenderPublicationMetadata;
+  readonly templates: readonly RenderPublicationTemplate[];
+  readonly videoFrames: readonly {
+    readonly entity: number;
+    readonly clip: number;
+    readonly frame: VideoFrame;
+  }[];
+  readonly targets: readonly PublishedRenderTarget[];
+  readonly targetSources: readonly PublishedRenderTargetSource[];
+  readonly features: readonly { readonly identity: string; readonly data: unknown }[];
+  readonly programs: readonly {
+    readonly key: string;
+    readonly shader: MaterialShaderEntry;
+    readonly artifact?: MaterialRuntimeArtifact;
+  }[];
+  /** entity, template index pairs. A publication source owns one World. */
+  readonly upserts: Uint32Array;
+  readonly removed: Uint32Array;
+  readonly transformEntities: Uint32Array;
+  readonly transforms: Float32Array;
+  readonly assets: readonly {
+    readonly handle: Handle<string, 'shared'>;
+    readonly guid?: string;
+    readonly value: Asset;
+  }[];
+  readonly retiredAssets: readonly Handle<string, 'shared'>[];
+  readonly invalidatedAssets: readonly Handle<string, 'shared'>[];
+}
+
+export interface PublishedRenderFrameInput {
+  readonly publication: RenderPublication;
+  /** Realm-local adapter invoked only after the feature's graph is submitted. */
+  readonly onFeatureSourceSubmitted?: (identity: string, feedback: unknown) => void;
+}
+
+export function renderPublicationTransfers(packet: RenderPublication): ArrayBuffer[] {
+  return [
+    packet.upserts.buffer,
+    packet.removed.buffer,
+    packet.transformEntities.buffer,
+    packet.transforms.buffer,
+  ] as ArrayBuffer[];
+}
+
+export type RenderPublicationFailure =
+  | 'identity'
+  | 'base'
+  | 'revision'
+  | 'shape'
+  | 'unsupported'
+  | 'in-flight'
+  | 'disposed';
+
+export class RenderPublicationError extends Error {
+  readonly code = 'render-publication-invalid' as const;
+  readonly expected = 'one valid publication for the bound source session and accepted base';
+  readonly hint =
+    'inspect detail.reason; repair the source or start a new session with a complete current baseline';
+  constructor(
+    readonly detail: { readonly reason: RenderPublicationFailure; readonly subject: string },
+  ) {
+    super(`render-publication-invalid: ${detail.reason}: ${detail.subject}`);
+    this.name = 'RenderPublicationError';
+  }
+}

package/src/publication/dependencies.ts

@@ -0,0 +1,54 @@
+import type { Handle } from '@forgeax/engine-types';
+import type { ExtractedFrame, RenderableSnapshot } from '../render-system-extract';
+
+/** One asset closure for source publication and receiver admission. */
+export function publicationDependencies(
+  row: Pick<RenderableSnapshot, 'assetHandle' | 'materials'>,
+): Handle<string, 'shared'>[] {
+  const handles = new Set<Handle<string, 'shared'>>([row.assetHandle as Handle<string, 'shared'>]);
+  for (const material of row.materials) {
+    for (const handle of [
+      material.materialHandle,
+      material.baseColorTexture,
+      material.metallicRoughnessTexture,
+      material.normalTexture,
+      material.emissiveTexture,
+      material.occlusionTexture,
+    ]) {
+      if (handle) handles.add(handle as Handle<string, 'shared'>);
+    }
+    for (const handle of material.textureHandles?.values() ?? []) handles.add(handle);
+    for (const handle of material.samplerHandles?.values() ?? []) handles.add(handle);
+  }
+  return [...handles];
+}
+
+/** Resources selected once for the frame rather than attached to geometry. */
+export function publicationFrameDependencies(
+  frame: Pick<
+    ExtractedFrame,
+    'cameras' | 'auxiliaryCameras' | 'skylight' | 'skybox' | 'lights' | 'volumetricFog'
+  >,
+): Handle<string, 'shared'>[] {
+  const handles = new Set<Handle<string, 'shared'>>();
+  const add = (handle: number | undefined) => {
+    if (handle) handles.add(handle as Handle<string, 'shared'>);
+  };
+  add(frame.skylight?.equirectHandle);
+  add(frame.skybox?.equirectHandle);
+  for (const camera of [...frame.cameras, ...frame.auxiliaryCameras]) add(camera.output?.colorLut);
+  for (const light of frame.lights.spot) {
+    add(light.iesProfileHandle);
+    add(light.cookieHandle);
+    add(light.projectorHandle);
+  }
+  const fogs =
+    frame.volumetricFog === undefined
+      ? []
+      : [frame.volumetricFog, ...(frame.volumetricFog.additional ?? [])];
+  for (const fog of fogs) {
+    add(fog.densityHandle);
+    add(fog.projectorHandle);
+  }
+  return [...handles];
+}

package/src/publication/prepare-geometry.ts

@@ -0,0 +1,94 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import type { Handle, MeshAsset } from '@forgeax/engine-types';
+import { buildGpuDrivenDraws } from '../extract/gpu-driven';
+import type { InstanceProjectionStore } from '../instances';
+import type { extractFrames, RenderableSnapshot } from '../render-system-extract';
+import type { PersistentRenderScene } from '../scene/render-scene';
+import type { SkinPaletteAllocator } from '../systems/skin-palette-allocator';
+import { RenderPublicationError } from './contract';
+import type { PreparedRenderPublication } from './receiver';
+import { renderAssetByGuid } from './resource-scope';
+
+/** Resolve GPU ownership after source data has crossed the publication boundary. */
+export function preparePublicationGeometry(
+  input: PreparedRenderPublication,
+  scene: PersistentRenderScene,
+  palette: SkinPaletteAllocator | null | undefined,
+  assets: AssetRegistry,
+  instances: InstanceProjectionStore,
+  getMaterialShaderArtifact?: NonNullable<
+    Parameters<typeof extractFrames>[5]
+  >['getMaterialShaderArtifact'],
+): PreparedRenderPublication {
+  const replacements = new Map<number, RenderableSnapshot>();
+  for (const operation of input.operations) {
+    if (operation.kind !== 'remove' && operation.snapshot === undefined) continue;
+    if (operation.kind === 'remove' || operation.snapshot?.instances === undefined)
+      instances.release(input.resources, operation.entityKey);
+    const prior = scene.compositionSlot(0, operation.entityKey)?.snapshot.skin;
+    const pose = operation.kind === 'remove' ? undefined : operation.snapshot?.skinPose;
+    if (prior !== undefined && prior.identity !== pose?.identity)
+      palette?.releasePersistentSlice(prior.identity);
+  }
+  for (const row of input.frame.renderables) {
+    const { skinPose, ...source } = row;
+    let skin = row.skin;
+    if (skinPose !== undefined) {
+      if (palette == null)
+        throw new RenderPublicationError({
+          reason: 'unsupported',
+          subject: 'skin palette allocator',
+        });
+      palette.observePersistentJoints(
+        skinPose.identity,
+        skinPose.inverseBindMatrices,
+        skinPose.jointWorlds,
+      );
+      skin = palette.allocatePersistentSlice(skinPose);
+      palette.writePersistentJointPalette(skin, skinPose.inverseBindMatrices, skinPose.jointWorlds);
+    }
+    const projected =
+      row.instances === undefined
+        ? undefined
+        : instances.project(input.resources, row.entityKey, row.instances.transforms);
+    const snapshot: RenderableSnapshot = {
+      ...source,
+      ...(skin === undefined ? {} : { skin }),
+      ...(projected === undefined || row.instances === undefined
+        ? {}
+        : { instances: { ...row.instances, ...projected, archVersion: 0 } }),
+    };
+    if (projected !== undefined) instances.accept(input.resources, row.entityKey, projected);
+    const mesh = input.resources.resolveAsset<MeshAsset>(
+      row.assetHandle as Handle<'MeshAsset', 'shared'>,
+    );
+    if (!mesh.ok) throw mesh.error;
+    const gpuDrivenDraws =
+      row.morph === undefined
+        ? buildGpuDrivenDraws({
+            mesh: mesh.value,
+            materials: row.materials,
+            fallbackMaterial: row.material,
+            baseSnapshot: snapshot,
+            ...(getMaterialShaderArtifact === undefined ? {} : { getMaterialShaderArtifact }),
+            ...(row.lods === undefined
+              ? {}
+              : {
+                  lodMeshes: row.lods.map((lod) =>
+                    renderAssetByGuid<MeshAsset>(input.resources, assets, lod.mesh),
+                  ),
+                }),
+          })
+        : [];
+    replacements.set(row.entityKey, { ...snapshot, gpuDrivenDraws });
+  }
+  return {
+    ...input,
+    frame: { ...input.frame, renderables: [...replacements.values()] },
+    operations: input.operations.map((operation) =>
+      operation.kind !== 'remove' && operation.snapshot !== undefined
+        ? { ...operation, snapshot: replacements.get(operation.entityKey) as RenderableSnapshot }
+        : operation,
+    ),
+  };
+}

package/src/publication/programs.ts

@@ -0,0 +1,45 @@
+import type { AssetRegistry } from '@forgeax/engine-assets-runtime';
+import { MaterialArtifactRegistry, ShaderRegistry } from '@forgeax/engine-shader';
+import { type RenderPublication, RenderPublicationError } from './contract';
+
+/** Admit immutable producer artifacts before the full Renderer prepares their pipelines. */
+export function installPublicationPrograms(
+  assets: AssetRegistry,
+  programs: RenderPublication['programs'],
+): void {
+  if (programs.length === 0) return;
+  const validation = new MaterialArtifactRegistry();
+  const shaders = new ShaderRegistry({ manifestUrl: undefined });
+  const keys = new Set<string>();
+  for (const row of programs) {
+    if (keys.has(row.key) || (row.artifact !== undefined && row.artifact.key !== row.key))
+      throw new RenderPublicationError({
+        reason: 'shape',
+        subject: 'duplicate or mismatched program key',
+      });
+    keys.add(row.key);
+    shaders.installMaterialArtifact(row.key, row.shader);
+    const previous = assets.shaderRegistry.findMaterialArtifact(row.key);
+    if (
+      previous.ok &&
+      (previous.value.source !== row.shader.source ||
+        JSON.stringify(previous.value.paramSchema) !== JSON.stringify(row.shader.paramSchema) ||
+        JSON.stringify(previous.value.receipt) !== JSON.stringify(row.shader.receipt))
+    ) {
+      throw new RenderPublicationError({
+        reason: 'shape',
+        subject: `conflicting immutable shader ${row.key}`,
+      });
+    }
+    if (row.artifact !== undefined) {
+      const existing = assets.getMaterialArtifact(row.key);
+      if (existing !== undefined) validation.register(existing).unwrap();
+      validation.register(row.artifact).unwrap();
+    }
+  }
+  for (const row of programs) {
+    if (row.artifact !== undefined) assets.materialArtifactRegistry.register(row.artifact).unwrap();
+    if (!assets.shaderRegistry.findMaterialArtifact(row.key).ok)
+      assets.shaderRegistry.installMaterialArtifact(row.key, row.shader);
+  }
+}