@forgeax/engine-render 0.1.7 → 0.1.19

package/src/features/targets.ts

@@ -12,6 +12,8 @@ export type RenderFeatureTargetKind = 'scene-color' | 'scene-depth';
  * internal graph key.
  */
 export interface RenderFeatureTargetHandle {
+  /** Stable alias used when a pipeline exposes more than one color role. */
+  readonly name?: string;
   readonly kind: RenderFeatureTargetKind;
   readonly format: TextureFormat;
   readonly sampleCount: 1 | 4;
@@ -19,6 +21,7 @@ export interface RenderFeatureTargetHandle {
 }
 
 export interface RenderFeatureTargetInput {
+  readonly name?: string;
   readonly kind: RenderFeatureTargetKind;
   readonly format: TextureFormat;
   readonly sampleCount: 1 | 4;
@@ -54,17 +57,36 @@ export function resolveStandardRenderFeatureTargets(input: {
   readonly colorAttachmentFormat: TextureFormat;
 }): readonly RenderFeatureTargetHandle[] {
   const sampleCount: 1 | 4 = input.antialias === 'msaa' && input.multisample ? 4 : 1;
-  const linearLdr = input.tonemap === 'none' && input.storageBuffer;
+  const linearLdr =
+    (input.tonemap === 'none' && input.storageBuffer) ||
+    input.antialias === 'fxaa' ||
+    (input.antialias === 'msaa' && input.multisample);
+  const colorFormat =
+    input.tonemap !== 'none' || linearLdr ? 'rgba16float' : input.colorAttachmentFormat;
   return [
     createRenderFeatureTarget({
+      name: 'color',
       kind: 'scene-color',
-      format: input.tonemap !== 'none' || linearLdr ? 'rgba16float' : input.colorAttachmentFormat,
+      format: colorFormat,
       sampleCount,
     }),
     createRenderFeatureTarget({
+      name: 'depth',
       kind: 'scene-depth',
       format: 'depth24plus-stencil8',
       sampleCount,
     }),
+    createRenderFeatureTarget({
+      name: 'motion-input',
+      kind: 'scene-color',
+      format: colorFormat,
+      sampleCount,
+    }),
+    createRenderFeatureTarget({
+      name: 'motion-output',
+      kind: 'scene-color',
+      format: colorFormat,
+      sampleCount: 1,
+    }),
   ];
 }

package/src/features/types.ts

@@ -42,6 +42,17 @@ export type {
 /** Closed lifecycle states exposed by the feature host. */
 export type RenderFeatureStatus = 'active' | 'failed' | 'disabled' | 'disposed';
 
+/**
+ * Shader preparation policy for feature-owned GPU programs.
+ *
+ * `validated` waits for the backend's diagnostic-rich shader preparation before
+ * exposing a module to the render graph. `immediate` is reserved for generated
+ * feature programs that must hand a WebGPU module to pipeline creation without
+ * serialising first-use on `getCompilationInfo()`; pipeline creation remains
+ * the validation boundary for that mode.
+ */
+export type RenderFeatureShaderModuleMode = 'validated' | 'immediate';
+
 export interface RenderFeatureResourceHandle {
   readonly __renderFeatureResource: unique symbol;
 }
@@ -79,6 +90,8 @@ export interface RenderFeatureExtractContext {
 export interface RenderFeature<FrameData> {
   readonly identity: string;
   readonly requiredCapabilities?: readonly RenderFeatureCapabilityKey[];
+  /** Optional feature-owned shader preparation policy; defaults to `validated`. */
+  readonly shaderModuleMode?: RenderFeatureShaderModuleMode;
   /**
    * Material shader identifiers whose modules must be ready before the first
    * frame. The renderer resolves these against the loaded manifest and seeds

package/src/fullscreen-post-process-pass.ts

@@ -23,6 +23,7 @@ import type {
   Sampler,
   TextureView,
 } from '@forgeax/engine-rhi';
+import { GPU_SHADER_STAGE_FRAGMENT } from './gpu-stage';
 import type { BglKind } from './pipeline-spec';
 import { buildBindGroupLayoutDescriptor, type PipelineSpec } from './pipeline-spec';
 
@@ -103,6 +104,15 @@ export interface PostProcessShaderEntry {
   readonly reads?: readonly (string | PostProcessReadEntry)[] | undefined;
 }
 
+/** Whether a feature binding opts into the temporal multi-read contract. */
+export function isTemporalFullscreenBinding(values: Readonly<Record<string, unknown>>): boolean {
+  return (
+    values.temporal !== undefined ||
+    values.shader === 'forgeax.taa-resolve' ||
+    values.shader === 'forgeax.motion-blur'
+  );
+}
+
 /**
  * Structured read entry for a post-process shader.
  *
@@ -252,6 +262,7 @@ export function buildFullscreenPostProcessPass(
   bindGroupLayout: BindGroupLayout;
   sampler: Sampler | null;
   depthSampler: Sampler | null;
+  extraColorBindings: readonly number[];
   createHandle: (
     name: string,
     pipeline: unknown,
@@ -279,11 +290,20 @@ export function buildFullscreenPostProcessPass(
     : entry.params !== undefined
       ? 'fullscreen-post-with-params'
       : 'fullscreen-post';
-  const bglRes = device.createBindGroupLayout(
-    buildBindGroupLayoutDescriptor(FULLSCREEN_DEFAULT_SPEC, {
-      kind: bglKind,
-    }),
+  const descriptor = buildBindGroupLayoutDescriptor(FULLSCREEN_DEFAULT_SPEC, { kind: bglKind });
+  const colorReads = (entry.reads ?? []).filter(
+    (read) => typeof read === 'string' || read.sampleType !== 'depth',
   );
+  const extraColorCount = Math.max(0, colorReads.length - 1);
+  const firstExtraBinding = hasDepth ? 5 : entry.params === undefined ? 2 : 3;
+  for (let index = 0; index < extraColorCount; index += 1) {
+    descriptor.entries.push({
+      binding: firstExtraBinding + index,
+      visibility: GPU_SHADER_STAGE_FRAGMENT,
+      texture: { sampleType: 'float', viewDimension: '2d' },
+    });
+  }
+  const bglRes = device.createBindGroupLayout(descriptor);
   if (!bglRes.ok) {
     ctx.errorRegistry.fire(bglRes.error);
     return null;
@@ -297,6 +317,9 @@ export function buildFullscreenPostProcessPass(
     bindGroupLayout: bglRes.value,
     sampler,
     depthSampler,
+    extraColorBindings: Object.freeze(
+      Array.from({ length: extraColorCount }, (_, index) => firstExtraBinding + index),
+    ),
     createHandle: (name, pipeline, paramsBuffer) => ({
       name,
       paramsBuffer,
@@ -334,6 +357,7 @@ export function createFullscreenBindGroup(
   paramsBuffer?: Buffer | null,
   depthTexView?: TextureView | null,
   depthSampler?: Sampler | null,
+  additionalViews: readonly { readonly binding: number; readonly view: TextureView }[] = [],
 ): BindGroup | null {
   const entries: { binding: number; resource: { kind: string; value: unknown } }[] = [
     { binding: 0, resource: { kind: 'textureView', value: inputView } },
@@ -353,6 +377,12 @@ export function createFullscreenBindGroup(
     entries.push({ binding: 3, resource: { kind: 'textureView', value: depthTexView } });
     entries.push({ binding: 4, resource: { kind: 'sampler', value: depthSampler } });
   }
+  for (const additional of additionalViews) {
+    entries.push({
+      binding: additional.binding,
+      resource: { kind: 'textureView', value: additional.view },
+    });
+  }
   const res = device.createBindGroup({
     label: 'fullscreen-post-process-bg',
     layout: bgl,

package/src/gpu-scene.ts

@@ -294,6 +294,30 @@ export class GpuScene {
     });
   }
 
+  /** Publish current transforms as previous only after a successful submit. */
+  commitTemporalFrame(): Result<void, RhiError> {
+    const nextTransform = this.tableBytes.transform.slice(0);
+    const next = new Uint8Array(nextTransform);
+    const current = new Uint8Array(this.tableBytes.transform);
+    const currentOffset = offset(TRANSFORM, 'currentWorld');
+    const previousOffset = offset(TRANSFORM, 'previousWorld');
+    for (let index = 0; index < this.capacity; index += 1) {
+      next.set(
+        current.subarray(
+          index * TRANSFORM.stride + currentOffset,
+          index * TRANSFORM.stride + currentOffset + 64,
+        ),
+        index * TRANSFORM.stride + previousOffset,
+      );
+    }
+    const uploaded = this.device.queue.writeBuffer(this.buffers.transform, 0, next);
+    if (!uploaded.ok) return uploaded;
+    this.tableBytes.transform = nextTransform;
+    this.uploadRanges += 1;
+    this.uploadBytes += next.byteLength;
+    return ok(undefined);
+  }
+
   rebuild(slots: readonly RenderSceneSlot[]): Result<GpuSceneSyncResult, RhiError> {
     this.allocations.clear();
     this.instances.reset();

package/src/ibl/skylight-bind-group.ts

@@ -1,5 +1,6 @@
 // skylight-bind-group.ts -- Skylight resources merged into @group(1) PBR
-// material BGL (binding 7..13) + fallback identity resource bundle.
+// material BGL (binding 7..13) + fallback identity resource bundle. The
+// complete Standard material group appends transmission entries.
 //
 // Plan-strategy D-5 (round-4 REVISED): the round-2 stand-alone @group(4)
 // Skylight BindGroupLayout collided with WebGPU's default maxBindGroups=4
@@ -18,9 +19,10 @@
 //     (createRenderer) is responsible for passing the result to
 //     `device.createBindGroupLayout`.
 //   - assembleMaterialWithSkylightEntries(materialEntries, skylightResources):
-//     given the existing 7 material BindGroupEntry values + a skylight
-//     resource bundle (active or fallback), returns the merged 14-entry
-//     array suitable for `device.createBindGroup`. Charter P5 minimal
+//     given the existing material BindGroupEntry values + a skylight
+//     resource bundle (active or fallback), returns the merged material
+//     array with the engine-owned transmission pair at the end, suitable for
+//     `device.createBindGroup`. Charter P5 minimal
 //     surface: this helper does NOT allocate samplers/textures itself.
 //   - createSkylightFallback(device, queue): allocate a 1x1 white
 //     irradiance/prefilter cube pair + a 1x1 BRDF approximation + intensity=0 uniform
@@ -232,22 +234,20 @@ export function mergeSkylightIntoMaterialBgl(
  * call site, same layout shape -- charter P4 + F1 (AI users do not need
  * a `if (hasSkylight)` branch when writing demos).
  */
-export interface EmissiveAoBindGroupResources {
-  readonly emissiveSampler: Sampler;
-  readonly emissiveView: TextureView;
-  readonly occlusionSampler: Sampler;
-  readonly occlusionView: TextureView;
+/** Engine-owned material transmission injection resources. */
+export interface TransmissionBindGroupResources {
+  readonly sampler: Sampler;
+  readonly backdropView?: TextureView | null;
 }
 
-// Lightmap (emissive + occlusion sampler/texture pair x 2) injection start
-// is computed from the assembled list length on each push — no hardcoded
-// 14-slot literal. After 7 material + 7 skylight entries are pushed below,
-// the lightmap binding land naturally at start = 14 (D-6 / w15).
+// Lightmap (emissive + occlusion sampler/texture pair x 2) and transmission
+// injection starts are computed from the assembled list length on each push —
+// no hardcoded binding literals.
 
 export function assembleMaterialWithSkylightEntries(
   materialEntries: readonly BindGroupEntry[],
   skylight: SkylightBindGroupResources,
-  emissiveAo?: EmissiveAoBindGroupResources | undefined,
+  transmission?: TransmissionBindGroupResources | undefined,
 ): BindGroupEntry[] {
   // IBL injection start = end of the user-region. The user-region IS
   // `materialEntries` (UBO binding 0 + N sampler/texture pairs), so its length
@@ -287,30 +287,22 @@ export function assembleMaterialWithSkylightEntries(
       resource: { kind: 'buffer', value: { buffer: skylight.intensityBuffer } },
     },
   ];
-  if (emissiveAo !== undefined) {
-    // Lightmap injection start = current accumulated length
-    // (post material + skylight). Mirrors the appendInjection contract
-    // in pbr-pipeline.ts (D-6).
-    const lightmapStart = result.length;
-    result.push(
-      {
-        binding: lightmapStart,
-        resource: { kind: 'sampler', value: emissiveAo.emissiveSampler },
-      },
-      {
-        binding: lightmapStart + 1,
-        resource: { kind: 'textureView', value: emissiveAo.emissiveView },
-      },
-      {
-        binding: lightmapStart + 2,
-        resource: { kind: 'sampler', value: emissiveAo.occlusionSampler },
-      },
-      {
-        binding: lightmapStart + 3,
-        resource: { kind: 'textureView', value: emissiveAo.occlusionView },
-      },
-    );
-  }
+  // Transmission injection is always present after IBL. Non-transmission
+  // variants bind the existing Skylight resources as layout-only placeholders;
+  // they are not a functional fallback and are never sampled by those shaders.
+  const transmissionSampler = transmission?.sampler ?? skylight.irradianceSampler;
+  const transmissionView = transmission?.backdropView ?? skylight.brdfLutView;
+  const transmissionStart = result.length;
+  result.push(
+    {
+      binding: transmissionStart,
+      resource: { kind: 'sampler', value: transmissionSampler },
+    },
+    {
+      binding: transmissionStart + 1,
+      resource: { kind: 'textureView', value: transmissionView },
+    },
+  );
   return result;
 }
 

package/src/index.ts

@@ -1,8 +1,8 @@
 // @forgeax/engine-render — AI-facing render vocabulary.
 //
 // The root is deliberately small: ECS render components, grouped closed
-// values, the renderer lifecycle/receipt contract, and the declarative
-// RenderFeature plan. Graph builders, prepared GPU state, pipeline
+// values, immutable frame facts, the renderer lifecycle/receipt contract, and
+// the declarative RenderFeature plan. Graph builders, prepared GPU state, pipeline
 // implementations, builtin feature factories, and diagnostic class names are
 // owner-local implementation details.
 
@@ -11,13 +11,20 @@ export {
   renderPipelineContribution,
   samplerContribution,
 } from './assets/asset-decoders';
-
+export { Atmosphere } from './components/atmosphere';
 // ECS render vocabulary and grouped closed values.
-export type { Antialias, BloomEnabled, CameraProjection, Tonemap } from './components/camera';
+export type {
+  Antialias,
+  BloomEnabled,
+  CameraData,
+  CameraProjection,
+  Tonemap,
+} from './components/camera';
 export {
   ANTIALIAS_FXAA,
   ANTIALIAS_MSAA,
   ANTIALIAS_NONE,
+  ANTIALIAS_TAA,
   BLOOM_DISABLED,
   BLOOM_ENABLED,
   CAMERA_PROJECTION_ORTHOGRAPHIC,
@@ -36,11 +43,13 @@ export {
   TONEMAP_REINHARD_EXTENDED,
 } from './components/camera';
 export * from './components/directional-light';
+export { Fog } from './components/fog';
 export { Instances, type InstancesData } from './components/instances';
 export { Layer } from './components/layer';
 export { Lines } from './components/lines';
 export * from './components/mesh-filter';
 export * from './components/mesh-renderer';
+export { MotionBlur } from './components/motion-blur';
 export { PointLight } from './components/point-light';
 export { PointLightShadow } from './components/point-light-shadow';
 export {
@@ -65,9 +74,35 @@ export {
   VisibilityStateValue,
   visibilityStateFromU32,
 } from './components/visibility';
+export type {
+  EnvironmentInspection,
+  EnvironmentInspectionFailure,
+  EnvironmentInspectionGeneration,
+  EnvironmentInspectionStatus,
+} from './environment/inspection';
 // Public structured operation failure union. Concrete error classes stay
 // behind the Renderer Result/event boundary.
-export type { RenderError, RenderErrorCode } from './errors/render';
+export type {
+  RenderError,
+  RenderErrorCode,
+  SceneDataUnavailableDetail,
+  SceneDataUnavailableReason,
+} from './errors/render';
+export {
+  AtmosphereInvalidParameterError,
+  EnvironmentGenerationFailedError,
+  EnvironmentSourceConflictError,
+  FogCardinalityError,
+  OwnerStageFailedError,
+  SceneDataUnavailableError,
+  TaaCapsInsufficientError,
+} from './errors/render';
+export type {
+  EnvironmentFrame,
+  EnvironmentSource,
+  FogFrame,
+  FramePlan,
+} from './extract/environment';
 export {
   resolveVisibility,
   type VisibilityResolution,
@@ -75,6 +110,7 @@ export {
 } from './extract/visibility';
 export type {
   RenderFeatureLogicalTarget,
+  RenderFeatureMaterialShaderBindingContract,
   RenderFeaturePassDeclaration,
   RenderFeaturePlan,
   RenderFeaturePlanContext,
@@ -90,10 +126,17 @@ export type {
   RenderFeatureErrorDescriptor,
   RenderFeatureExtractContext,
   RenderFeatureHiddenEntityReport,
+  RenderFeatureShaderModuleMode,
   RenderFeatureStatus,
   RenderFeatureWorldVisibilitySnapshot,
 } from './features/types';
-export { Materials } from './materials';
+export type {
+  BloomInspection,
+  MotionBlurInspection,
+  MotionBlurInspectionStatus,
+  TransmissionInspection,
+} from './inspection-types';
+export { Materials, MaterialTransmissionContractError } from './materials';
 // The host-facing default is a stable profile value; implementation-only
 // pipeline helpers remain behind the package boundary.
 export { DEFAULT_STANDARD_PROFILE } from './pipeline/standard-profile';
@@ -127,3 +170,20 @@ export type {
   RenderWorldLease,
 } from './render-contract';
 export { RENDER_PHASE_CATALOG } from './render-contract';
+export type { TemporalInspection, TemporalResourceInspection } from './temporal/inspection';
+export {
+  SCENE_DATA_TEMPORAL_V1_DESCRIPTOR,
+  SCENE_DATA_TEMPORAL_V1_SCHEMA,
+  type SceneDataLane,
+  type SceneDataSchemaId,
+  type SceneDataTarget,
+  type SceneDataTemporalV1Descriptor,
+} from './temporal/scene-data';
+export {
+  createSceneDataCatalog,
+  type SceneDataAvailability,
+  type SceneDataCatalog,
+  type SceneDataCatalogOptions,
+  type SceneDataInspection,
+} from './temporal/scene-data-catalog';
+export type { TemporalView } from './temporal/view';

package/src/inspection-types.ts

@@ -6,6 +6,24 @@
 
 import type { PointsLinesInspection } from './points-lines/inspection';
 
+export type BloomGraphStatus = 'empty' | 'valid' | 'invalid';
+
+export interface BloomInspection {
+  readonly graphStatus: BloomGraphStatus;
+  readonly enabled: boolean;
+  readonly targetCount: number;
+  readonly targetBytes: number;
+  readonly resourceCount: number;
+  readonly passCount: number;
+  readonly encodeCount: number;
+  readonly bindGroupCount: number;
+  readonly uploadCount: number;
+  readonly residentChildBytes: number;
+  readonly generation: number;
+  readonly state: 'off' | 'active' | 'retiring';
+}
+export type { TransmissionInspection } from './transmission/inspection';
+
 export interface BatchTopologyInspection {
   readonly revision: number;
   readonly batchCount: number;
@@ -47,6 +65,36 @@ export interface GpuDrivenProductionInspection {
   readonly cpuFallbackDrawItems: number;
 }
 
+/** Detached semantic descriptor for the Standard scene-temporal producer. */
+export interface TemporalTargetInspection {
+  readonly identity: 'standard-scene-temporal';
+  readonly producerId: 'forgeax::standard::scene-data';
+  readonly schema: 'forgeax::scene-data::temporal-v1';
+  readonly targetCount: 1;
+  readonly descriptor: {
+    readonly format: 'rgba16float';
+    readonly width: number;
+    readonly height: number;
+    readonly sampleCount: 1;
+    readonly bytes: number;
+  };
+}
+
+/** Detached, bounded Motion Blur facts; no graph, device, target, or history handle. */
+export type MotionBlurInspectionStatus = 'off' | 'active' | 'reset' | 'invalid';
+
+export interface MotionBlurInspection {
+  readonly enabled: boolean;
+  readonly status: MotionBlurInspectionStatus;
+  readonly shutterAngle: number;
+  readonly maxRadiusPixels: number;
+  readonly sampleCount: number;
+  readonly temporalDemand: 'none' | 'scene-data-temporal-v1';
+  readonly passName: 'motion-blur';
+  readonly historyWrites: 0;
+  readonly lastFailure?: 'invalid-params' | 'scene-data-unavailable';
+}
+
 export type RenderSceneResyncReason =
   | 'attach'
   | 'asset-catalog-changed'

package/src/internal.ts

@@ -7,3 +7,8 @@ export {
   type TilesetRuntimeError,
   type TilesetRuntimeErrorCode,
 } from '@forgeax/engine-assets-runtime';
+export {
+  type GraphTargetCaptureReadbackValidation,
+  validateGraphTargetCaptureReadback,
+} from './record/frame-snapshot';
+export { TemporalFrameCoordinator } from './temporal/frame-coordinator';