@forgeax/engine-render 0.1.33 → 0.1.35

package/src/assembly/render-target-host.ts

@@ -79,6 +79,11 @@ interface ReadbackRecord {
 export interface RenderTargetHost {
   /** The logical owner for every target lifecycle operation. */
   readonly owner: 'renderer';
+  /** Logical descriptions for the source publication boundary; no physical state escapes. */
+  descriptions(): readonly {
+    readonly target: RenderTarget;
+    readonly descriptor: RenderTargetDescriptor;
+  }[];
   createRenderTarget(descriptor: RenderTargetDescriptor): RenderResult<RenderTarget, RenderError>;
   resizeRenderTarget(
     target: RenderTarget,
@@ -231,53 +236,51 @@ function makePhysical(
   const faceViews: TextureView[] = [];
   const depthTextures: Texture[] = [];
   const depthViews: TextureView[] = [];
-  if (descriptor.shape === 'cube') {
-    for (let face = 0; face < layers; face += 1) {
-      const depth = device.createTexture({
-        label: `render-target.${generation}.depth.${face}`,
-        size: {
-          width: descriptor.width,
-          height: descriptor.height,
-          depthOrArrayLayers: descriptor.sampleCount === 4 ? 1 : layers,
-        },
-        mipLevelCount: 1,
-        sampleCount: descriptor.sampleCount,
-        dimension: '2d',
-        format: 'depth24plus-stencil8',
-        usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
-        viewFormats: undefined,
-        textureBindingViewDimension: undefined,
-      });
-      if (!depth.ok)
-        return {
-          ok: false,
-          error: new RenderTargetOperationFailedError({
-            operation: 'create',
-            stage: 'allocation',
-            generation,
-            cause: depth.error,
-            recovery: 'retry',
-          }),
-        };
-      const depthView = device.createTextureView(depth.value, {
-        dimension: '2d',
-        baseArrayLayer: descriptor.sampleCount === 4 ? 0 : face,
-        arrayLayerCount: 1,
-      });
-      if (!depthView.ok)
-        return {
-          ok: false,
-          error: new RenderTargetOperationFailedError({
-            operation: 'create',
-            stage: 'allocation',
-            generation,
-            cause: depthView.error,
-            recovery: 'retry',
-          }),
-        };
-      depthTextures.push(depth.value);
-      depthViews.push(depthView.value);
-    }
+  for (let face = 0; face < layers; face += 1) {
+    const depth = device.createTexture({
+      label: `render-target.${generation}.depth.${face}`,
+      size: {
+        width: descriptor.width,
+        height: descriptor.height,
+        depthOrArrayLayers: descriptor.sampleCount === 4 ? 1 : layers,
+      },
+      mipLevelCount: 1,
+      sampleCount: descriptor.sampleCount,
+      dimension: '2d',
+      format: 'depth24plus-stencil8',
+      usage: GPU_TEXTURE_USAGE_RENDER_ATTACHMENT,
+      viewFormats: undefined,
+      textureBindingViewDimension: undefined,
+    });
+    if (!depth.ok)
+      return {
+        ok: false,
+        error: new RenderTargetOperationFailedError({
+          operation: 'create',
+          stage: 'allocation',
+          generation,
+          cause: depth.error,
+          recovery: 'retry',
+        }),
+      };
+    const depthView = device.createTextureView(depth.value, {
+      dimension: '2d',
+      baseArrayLayer: descriptor.sampleCount === 4 ? 0 : face,
+      arrayLayerCount: 1,
+    });
+    if (!depthView.ok)
+      return {
+        ok: false,
+        error: new RenderTargetOperationFailedError({
+          operation: 'create',
+          stage: 'allocation',
+          generation,
+          cause: depthView.error,
+          recovery: 'retry',
+        }),
+      };
+    depthTextures.push(depth.value);
+    depthViews.push(depthView.value);
   }
   if (descriptor.sampleCount === 4) {
     for (let face = 0; face < layers; face += 1) {
@@ -405,6 +408,13 @@ export function createRenderTargetHost(options: RenderTargetHostOptions = {}): R
 
   return Object.freeze({
     owner: 'renderer' as const,
+    descriptions() {
+      return [...targets].map((target) => {
+        const state = owner.inspect(target);
+        if (!state.ok) throw state.error;
+        return { target, descriptor: state.value.candidate?.descriptor ?? state.value.descriptor };
+      });
+    },
     createRenderTarget(
       descriptor: RenderTargetDescriptor,
     ): RenderResult<RenderTarget, RenderError> {

package/src/assembly/renderer-facade.ts

@@ -1,3 +1,4 @@
+import { RenderPublicationError } from '../publication/contract';
 // Public renderer facade and profile validation.
 // This module narrows the lifetime-heavy host implementation to the stable
 // lease/receipt contract and owns the profile/error projection helpers.
@@ -64,7 +65,8 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
           cause: structuredRendererCause(cause, 'renderer-event'),
         });
   const drawError = (cause: RhiError | RenderError): RenderError => {
-    if (cause instanceof MotionBlurValidationError) return cause;
+    if (cause instanceof MotionBlurValidationError || cause instanceof RenderPublicationError)
+      return cause;
     if (cause instanceof RendererOperationError) return cause;
     if (cause instanceof RendererContractFailureError) {
       return new RendererOperationError('device-operation-failed', {
@@ -92,7 +94,7 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
   });
 
   return {
-    instances: renderer.instances,
+    setSurfaceDynamicInput: (frame) => renderer.setSurfaceDynamicInput(frame),
     bounds: (world, entity) => (disposed ? undefined : renderer.bounds(world, entity)),
     attach: (world) => {
       const result = renderer.attach(world);
@@ -155,6 +157,9 @@ export function exposeRenderer(renderer: RendererHostImplementation): Renderer {
           kind: 'frame-submitted',
           frameId: result.value.frameId,
           deviceGeneration: result.value.deviceGeneration,
+          ...(result.value.graphGeneration === undefined
+            ? {}
+            : { graphGeneration: result.value.graphGeneration }),
           receipt: result.value,
         }),
       );

package/src/assembly/renderer-feature-inspection.ts

@@ -1,13 +1,19 @@
+import type { CloudLayerInspection } from '../cloud/inspection';
 import type { RenderFeatureHost } from '../features/host';
 import type { RenderInspection } from '../render-contract';
 
 /** Project feature-host lifecycle facts without exposing the live host. */
 export function projectRendererFeatureInspection(
   featureHost: RenderFeatureHost | undefined,
-): Pick<RenderInspection, 'features' | 'featureDiagnostics' | 'featureHost'> {
+): Pick<RenderInspection, 'features' | 'featureDiagnostics' | 'featureHost' | 'cloudLayer'> {
+  const featureDiagnostics = featureHost?.diagnostics() ?? Object.freeze([]);
+  const cloudLayer = featureDiagnostics.find(
+    (diagnostic) => diagnostic.identity === 'forgeax.cloud-layer',
+  )?.inspection as CloudLayerInspection | undefined;
   return {
     features: Object.freeze((featureHost?.features ?? []).map((feature) => feature.identity)),
-    featureDiagnostics: featureHost?.diagnostics() ?? Object.freeze([]),
+    featureDiagnostics,
+    ...(cloudLayer === undefined ? {} : { cloudLayer }),
     ...(featureHost?.inspection === undefined ? {} : { featureHost: featureHost.inspection() }),
   };
 }

package/src/assembly/renderer-frame-transaction.ts

@@ -64,6 +64,29 @@ export interface ContinuationTerminator {
   guard(kind: ContinuationKind): boolean;
 }
 
+export type FrameCompletionResult<T, E> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly error: E };
+
+/**
+ * Preserve producer Result failures while fencing a fulfilled GPU completion
+ * against disposal or device-generation loss.
+ */
+export function guardFrameCompletion<T, E>(
+  completion: PromiseLike<FrameCompletionResult<T, E>>,
+  isCurrent: () => boolean,
+  staleError: () => E,
+  rejectedError: (cause: unknown) => E,
+): Promise<FrameCompletionResult<T, E>> {
+  return Promise.resolve(completion).then(
+    (result) => {
+      if (!result.ok) return result;
+      return isCurrent() ? result : { ok: false, error: staleError() };
+    },
+    (cause) => ({ ok: false, error: rejectedError(cause) }),
+  );
+}
+
 export function createContinuationTerminator(): ContinuationTerminator {
   let termination: ContinuationTerminationReason | undefined;
   let resolveTermination: ((reason: ContinuationTerminationReason) => void) | undefined;

package/src/assembly/renderer-inspection.ts

@@ -2,6 +2,7 @@ import type { CompiledRenderGraphInfo } from '@forgeax/engine-render-graph';
 import type { RhiCanvasSurfacePresentationProof, TextureFormat } from '@forgeax/engine-rhi';
 import type { AutoExposureInspection } from '../pipeline/standard-output/auto-exposure/inspection';
 import type { StandardLutInspection } from '../pipeline/standard-output/lut-state';
+import type { PipelineState } from '../record/render-context';
 import {
   type RenderOutputInspection,
   type RenderStandardOutputColorInspection,
@@ -112,6 +113,33 @@ export function projectRendererOutputInspection(
   };
 }
 
+/** Assemble output inspection inputs from the live surface owner. */
+export function projectRendererOutputInspectionFromSurface(input: {
+  readonly graph: CompiledRenderGraphInfo | undefined;
+  readonly surfaceReleased: boolean;
+  readonly pipelineState: PipelineState | null;
+  readonly rgba16floatRenderable: boolean;
+  readonly presentationProof?: RhiCanvasSurfacePresentationProof | undefined;
+  readonly autoExposure?: AutoExposureInspection | undefined;
+  readonly standardLut?: StandardLutInspection | undefined;
+}): RenderOutputInspection {
+  return projectRendererOutputInspection({
+    graph: input.graph,
+    surfaceAvailable: !input.surfaceReleased && input.pipelineState !== null,
+    surfaceStorage: input.pipelineState?.format ?? 'rgba8unorm',
+    surfaceDisplay: input.pipelineState?.colorAttachmentFormat ?? 'rgba8unorm',
+    ...(input.pipelineState?.surfaceProfile === undefined
+      ? {}
+      : { surfaceProfile: input.pipelineState.surfaceProfile }),
+    rgba16floatRenderable: input.rgba16floatRenderable,
+    autoExposure: input.autoExposure,
+    standardLut: input.standardLut,
+    ...(input.presentationProof === undefined
+      ? {}
+      : { presentationProof: input.presentationProof }),
+  });
+}
+
 /** Detached inspection projection helper; live renderer objects never cross this boundary. */
 export function detachRendererInspection<T extends object>(inspection: T): Readonly<T> {
   return Object.freeze({ ...inspection });

package/src/assembly/skin-palette-owner.ts

@@ -15,7 +15,7 @@ export function createSkinPaletteOwner(
   const limitKey = storageBufferCapable
     ? 'maxStorageBufferBindingSize'
     : 'maxUniformBufferBindingSize';
-  const deviceLimit = (device.limits as Readonly<Record<string, number>>)[limitKey];
+  const deviceLimit = device.limits[limitKey];
   const maxBindingBytes = typeof deviceLimit === 'number' && deviceLimit > 0 ? deviceLimit : 65536;
   return createSkinPaletteAllocator(device, maxBindingBytes, storageBufferCapable);
 }

package/src/assembly/temporal-post-process-prewarm.ts

@@ -24,17 +24,17 @@ export function createTemporalShaderPrewarmer(input: {
         input.asyncCreateShaderModule
           ? input.asyncCreateShaderModule(input.device, {
               code: entry.wgsl,
-              label: postProcessShaderModuleLabel(id, entry.wgsl),
+              label: postProcessShaderModuleLabel(entry.wgsl),
             })
           : invokeDeviceCreateShaderModule(input.device, {
               code: entry.wgsl,
-              label: postProcessShaderModuleLabel(id, entry.wgsl),
+              label: postProcessShaderModuleLabel(entry.wgsl),
             }),
       'shader-compile-failed',
       `${id} shader module compiled (unified post-process prewarm)`,
       `inspect manifest ${id} entry composed wgsl; check device.features`,
     );
     if (!prewarm.ok) throw prewarm.error;
-    input.seedShaderModule(postProcessShaderModuleLabel(id, entry.wgsl), prewarm.value);
+    input.seedShaderModule(postProcessShaderModuleLabel(entry.wgsl), prewarm.value);
   };
 }

package/src/assembly/webgpu-pbr-ready.ts

@@ -15,6 +15,7 @@ import {
   buildGpuDrivenPbrPipelineLayout,
   buildGpuDrivenPbrSkinPipelineLayout,
   buildPbrSkinLayouts,
+  buildSurfaceDirectInstancesBindGroupLayout,
   type PbrPipelineLayoutBundle,
   SKIN_MATERIAL_SHADER_ID,
 } from '../pbr-pipeline';
@@ -43,6 +44,7 @@ export interface GpuDrivenPbrReadyLayouts {
   readonly gpuDrivenInstancesBindGroupLayout: BindGroupLayout | null;
   readonly gpuDrivenPbrPipelineLayout: PipelineLayout | null;
   readonly gpuDrivenPbrSkinPipelineLayout: PipelineLayout | null;
+  readonly surfaceDirectInstancesBindGroupLayout: BindGroupLayout | null;
 }
 
 interface GpuDrivenPbrModuleInput {
@@ -183,6 +185,7 @@ export function buildGpuDrivenPbrReadyLayouts(
   let gpuDrivenInstancesBindGroupLayout: BindGroupLayout | null = null;
   let gpuDrivenPbrPipelineLayout: PipelineLayout | null = null;
   let gpuDrivenPbrSkinPipelineLayout: PipelineLayout | null = null;
+  let surfaceDirectInstancesBindGroupLayout: BindGroupLayout | null = null;
   const skinResult = runShimSyncStep(
     () => ok(buildPbrSkinLayouts(device, { storageBuffer: storageBufferCapable }, pbrLayouts)),
     'webgpu-runtime-error',
@@ -200,6 +203,9 @@ export function buildGpuDrivenPbrReadyLayouts(
         const instances = buildGpuDrivenPbrInstancesBindGroupLayout(device, {
           storageBuffer: true,
         });
+        const surfaceDirect = buildSurfaceDirectInstancesBindGroupLayout(device, {
+          storageBuffer: true,
+        });
         const rigid = buildGpuDrivenPbrPipelineLayout(device, pbrLayouts, instances);
         const skin =
           pbrSkinMeshBindGroupLayout === null
@@ -209,7 +215,7 @@ export function buildGpuDrivenPbrReadyLayouts(
                 { ...pbrLayouts, meshArrayBgl: pbrSkinMeshBindGroupLayout },
                 instances,
               );
-        return ok({ instances, rigid, skin });
+        return ok({ instances, rigid, skin, surfaceDirect });
       },
       'webgpu-runtime-error',
       'build GPU-driven PBR pipeline layouts succeeded',
@@ -219,6 +225,7 @@ export function buildGpuDrivenPbrReadyLayouts(
       gpuDrivenInstancesBindGroupLayout = layoutResult.value.instances;
       gpuDrivenPbrPipelineLayout = layoutResult.value.rigid;
       gpuDrivenPbrSkinPipelineLayout = layoutResult.value.skin;
+      surfaceDirectInstancesBindGroupLayout = layoutResult.value.surfaceDirect;
     }
   }
   return {
@@ -228,5 +235,6 @@ export function buildGpuDrivenPbrReadyLayouts(
     gpuDrivenInstancesBindGroupLayout,
     gpuDrivenPbrPipelineLayout,
     gpuDrivenPbrSkinPipelineLayout,
+    surfaceDirectInstancesBindGroupLayout,
   };
 }

package/src/assembly/webgpu-ready-per-pass.ts

@@ -0,0 +1,104 @@
+import type { PerPassResources } from '../record/render-context';
+
+export interface ReadyPerPassResourceInputs {
+  readonly fxaaPipeline: PerPassResources['fxaaPipeline'];
+  readonly fxaaBindGroupLayout: PerPassResources['fxaaBindGroupLayout'];
+  readonly fxaaSampler: PerPassResources['fxaaSampler'];
+  readonly skyboxPipeline: PerPassResources['skyboxPipeline'];
+  readonly skyboxPipelineMsaa: PerPassResources['skyboxPipelineMsaa'];
+  readonly skyboxBindGroupLayout: PerPassResources['skyboxBindGroupLayout'];
+  readonly skyboxSampler: PerPassResources['skyboxSampler'];
+  readonly skyboxRotationBuffer: PerPassResources['skyboxRotationBuffer'];
+  readonly shadowSampler: PerPassResources['shadowSampler'];
+  readonly shadowLightSpaceMatrix: PerPassResources['shadowLightSpaceMatrix'];
+  readonly shadowCsmLightViewProj: PerPassResources['shadowCsmLightViewProj'];
+  readonly shadowCsmSelection: PerPassResources['shadowCsmSelection'];
+  readonly bloomDownsamplePipeline: PerPassResources['bloomDownsamplePipeline'];
+  readonly bloomUpsamplePipeline: PerPassResources['bloomUpsamplePipeline'];
+  readonly bloomCompositePipeline: PerPassResources['bloomCompositePipeline'];
+  readonly bloomDownsampleBindGroupLayout: PerPassResources['bloomDownsampleBindGroupLayout'];
+  readonly bloomUpsampleBindGroupLayout: PerPassResources['bloomUpsampleBindGroupLayout'];
+  readonly bloomCompositeBindGroupLayout: PerPassResources['bloomCompositeBindGroupLayout'];
+  readonly bloomSampler: PerPassResources['bloomSampler'];
+  readonly bloomDownsampleParamsBuffer: PerPassResources['bloomDownsampleParamsBuffer'];
+  readonly bloomUpsampleParamsBuffer: PerPassResources['bloomUpsampleParamsBuffer'];
+  readonly bloomCompositeParamsBuffer: PerPassResources['bloomCompositeParamsBuffer'];
+  readonly ensureBloomResources: NonNullable<PerPassResources['ensureBloomResources']>;
+  readonly getBloomResources: NonNullable<PerPassResources['getBloomResources']>;
+  readonly commitBloomResources: NonNullable<PerPassResources['commitBloomResources']>;
+  readonly commitBloomFrameReceipts: NonNullable<PerPassResources['commitBloomFrameReceipts']>;
+  readonly discardBloomResources: NonNullable<PerPassResources['discardBloomResources']>;
+  readonly retireBloomResources: NonNullable<PerPassResources['retireBloomResources']>;
+  readonly drainBloomResources: NonNullable<PerPassResources['drainBloomResources']>;
+  readonly inspectBloomResources: NonNullable<PerPassResources['inspectBloomResources']>;
+  readonly ssaoCalcPipeline: PerPassResources['ssaoCalcPipeline'];
+  readonly ssaoBlurPipeline: PerPassResources['ssaoBlurPipeline'];
+  readonly ssaoBgl: PerPassResources['ssaoBgl'];
+}
+
+/** Creates the mutable per-pass slots owned by one prepared device generation. */
+export function createReadyPerPassResources(input: ReadyPerPassResourceInputs): PerPassResources {
+  return {
+    depthTexture: null,
+    depthTextureView: null,
+    depthTextureWidth: 0,
+    depthTextureHeight: 0,
+    configured: false,
+    hdrColorTexture: null,
+    hdrColorView: null,
+    hdrDepthTexture: null,
+    hdrDepthView: null,
+    hdrTextureWidth: 0,
+    hdrTextureHeight: 0,
+    hdrDepthSampleCount: 1,
+    fxaaPipeline: input.fxaaPipeline,
+    fxaaBindGroupLayout: input.fxaaBindGroupLayout,
+    fxaaSampler: input.fxaaSampler,
+    msaaColorTexture: null,
+    msaaColorView: null,
+    msaaSpriteColorTexture: null,
+    msaaSpriteColorView: null,
+    msaaDepthTexture: null,
+    msaaDepthView: null,
+    msaaTextureWidth: 0,
+    msaaTextureHeight: 0,
+    hdrColorMsaaTexture: null,
+    hdrColorMsaaView: null,
+    skyboxPipeline: input.skyboxPipeline,
+    skyboxPipelineMsaa: input.skyboxPipelineMsaa,
+    skyboxBindGroupLayout: input.skyboxBindGroupLayout,
+    skyboxSampler: input.skyboxSampler,
+    skyboxRotationBuffer: input.skyboxRotationBuffer,
+    shadowTexture: null,
+    shadowMapSize: 0,
+    shadowCascadeCount: 0,
+    shadowSampler: input.shadowSampler,
+    shadowLightSpaceMatrix: input.shadowLightSpaceMatrix,
+    shadowCsmLightViewProj: input.shadowCsmLightViewProj,
+    shadowCsmSelection: input.shadowCsmSelection,
+    bloomDownsamplePipeline: input.bloomDownsamplePipeline,
+    bloomUpsamplePipeline: input.bloomUpsamplePipeline,
+    bloomCompositePipeline: input.bloomCompositePipeline,
+    bloomDownsampleBindGroupLayout: input.bloomDownsampleBindGroupLayout,
+    bloomUpsampleBindGroupLayout: input.bloomUpsampleBindGroupLayout,
+    bloomCompositeBindGroupLayout: input.bloomCompositeBindGroupLayout,
+    bloomSampler: input.bloomSampler,
+    bloomDownsampleParamsBuffer: input.bloomDownsampleParamsBuffer,
+    bloomUpsampleParamsBuffer: input.bloomUpsampleParamsBuffer,
+    bloomCompositeParamsBuffer: input.bloomCompositeParamsBuffer,
+    ensureBloomResources: input.ensureBloomResources,
+    getBloomResources: input.getBloomResources,
+    commitBloomResources: input.commitBloomResources,
+    commitBloomFrameReceipts: input.commitBloomFrameReceipts,
+    discardBloomResources: input.discardBloomResources,
+    retireBloomResources: input.retireBloomResources,
+    drainBloomResources: input.drainBloomResources,
+    inspectBloomResources: input.inspectBloomResources,
+    ssaoCalcPipeline: input.ssaoCalcPipeline,
+    ssaoBlurPipeline: input.ssaoBlurPipeline,
+    ssaoBgl: input.ssaoBgl,
+    ssaoFilteringSampler: null,
+    ssaoDepthSampler: null,
+    ssaoFallbackRawView: null,
+  };
+}