@forgeax/engine-render 0.1.27 → 0.1.29

package/src/environment/background.ts

@@ -0,0 +1,263 @@
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import type { BindGroup, BindGroupLayout, RenderPipeline, Sampler } from '@forgeax/engine-rhi';
+import { RhiError } from '@forgeax/engine-rhi';
+import type { Result } from '@forgeax/engine-types';
+import type { _InternalRenderPipelineContext } from '../record/render-context';
+import { VIEW_UNIFORM_BYTES } from '../record/view-ubo';
+import type { RenderPipelineFrame, RenderPipelineTarget } from '../render-pipeline';
+
+const CUBE_SIZE = 128;
+
+/** One graph-owned sky cube feeds the background; the sun disc is added only there. */
+export function addAtmosphereBackground(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  color: RenderPipelineTarget,
+): Result<void, RenderGraphError> {
+  const cube = graph.createTexture('atmosphere-sky', {
+    format: 'rgba16float',
+    size: { width: CUBE_SIZE, height: CUBE_SIZE, depthOrArrayLayers: 6 },
+  });
+  if (!cube.ok) return cube;
+  const cubeView = graph.view(cube.value, { dimension: 'cube', arrayLayerCount: 6 });
+  if (!cubeView.ok) return cubeView;
+  const params = graph.createBuffer('atmosphere-params', { size: 64 });
+  if (!params.ok) return params;
+  const vertices = graph.createBuffer('atmosphere-face-vertices', { size: 6 * 3 * 3 * 4 });
+  if (!vertices.ok) return vertices;
+  const view = graph.importBuffer(
+    'atmosphere-view',
+    { size: VIEW_UNIFORM_BYTES, usage: 0x40 | 0x08 },
+    (frame) => (frame as _InternalRenderPipelineContext).pipelineState.viewUniformBuffer,
+  );
+  if (!view.ok) return view;
+  let submittedSignature: string | undefined;
+  let state:
+    | {
+        cubePipeline: RenderPipeline;
+        cubeLayout: BindGroupLayout;
+        backgroundPipeline: RenderPipeline;
+        backgroundLayout: BindGroupLayout;
+        sampler: Sampler;
+        cubeGroup?: BindGroup;
+        backgroundGroup?: BindGroup;
+      }
+    | undefined;
+  const frameOf = (frame: RenderPipelineFrame) => frame as _InternalRenderPipelineContext;
+  const dirty = (frame: RenderPipelineFrame) =>
+    frameOf(frame).frameState.environmentFrame?.environmentSignature !== submittedSignature;
+  const upload = graph.addCopyPass('atmosphere-prepare', {
+    accesses: [
+      { resource: params.value, usage: 'copy-dst' },
+      { resource: vertices.value, usage: 'copy-dst' },
+    ],
+    executeIf: dirty,
+    encode: ({ frame, resources }) => {
+      const environment = frameOf(frame).frameState.environmentFrame;
+      const sun = environment?.sun;
+      if (environment?.source.kind !== 'atmosphere' || sun === undefined) {
+        throw new RhiError({
+          code: 'webgpu-runtime-error',
+          expected: 'selected Atmosphere frame carries its directional sun',
+          hint: 'publish the validated resource-owner environment frame before graph recording',
+        });
+      }
+      const settings = environment.source.atmosphere;
+      const values = new Float32Array([
+        ...sun.direction,
+        sun.intensity,
+        ...sun.color,
+        0,
+        settings.turbidity,
+        settings.rayleigh,
+        settings.mieCoefficient,
+        settings.mieDirectionalG,
+        settings.sunAngularRadius,
+        settings.sunAngularRadius > 0 ? 1 : 0,
+        0,
+        0,
+      ]);
+      frame.runtime.device.queue
+        .writeBuffer(resources.buffer(params.value).unwrap(), 0, values)
+        .unwrap();
+      const triangles = new Float32Array(6 * 9);
+      for (let face = 0; face < 6; face += 1) {
+        triangles.set([-1, -1, face + 1, 3, -1, face + 1, -1, 3, face + 1], face * 9);
+      }
+      frame.runtime.device.queue
+        .writeBuffer(resources.buffer(vertices.value).unwrap(), 0, triangles)
+        .unwrap();
+    },
+  });
+  if (!upload.ok) return upload;
+  const ensureState = (frame: RenderPipelineFrame) => {
+    if (state !== undefined) return state;
+    const sources = frame.atmosphereShaders;
+    const factory = frame.runtime.shaderModuleFactory;
+    if (sources === undefined || factory === undefined) {
+      throw new RhiError({
+        code: 'shader-compile-failed',
+        expected: 'shader manifest includes the Atmosphere cube and background programs',
+        hint: 'rebuild the Engine shader manifest with the package-owned Atmosphere entries',
+      });
+    }
+    const device = frame.runtime.device;
+    const cubeModule = factory
+      .createShaderModule({ code: sources.cube, label: 'atmosphere_cube' })
+      .unwrap();
+    const backgroundModule = factory
+      .createShaderModule({ code: sources.background, label: 'atmosphere_background' })
+      .unwrap();
+    const cubeLayout = device
+      .createBindGroupLayout({
+        entries: [{ binding: 0, visibility: 2, buffer: { type: 'uniform', minBindingSize: 64 } }],
+      })
+      .unwrap();
+    const backgroundLayout = device
+      .createBindGroupLayout({
+        entries: [
+          { binding: 0, visibility: 2, texture: { sampleType: 'float', viewDimension: 'cube' } },
+          { binding: 1, visibility: 2, sampler: { type: 'filtering' } },
+          {
+            binding: 2,
+            visibility: 2,
+            buffer: { type: 'uniform', minBindingSize: VIEW_UNIFORM_BYTES },
+          },
+          { binding: 3, visibility: 2, buffer: { type: 'uniform', minBindingSize: 64 } },
+        ],
+      })
+      .unwrap();
+    const cubePipeline = device
+      .createRenderPipeline({
+        label: 'atmosphere_cube',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [cubeLayout] }).unwrap(),
+        vertex: {
+          module: cubeModule,
+          entryPoint: 'atmosphere_cubemap_vs',
+          buffers: [
+            {
+              arrayStride: 12,
+              attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }],
+            },
+          ],
+        },
+        fragment: {
+          module: cubeModule,
+          entryPoint: 'atmosphere_cubemap_fs',
+          targets: [{ format: 'rgba16float' }],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+      })
+      .unwrap();
+    const backgroundPipeline = device
+      .createRenderPipeline({
+        label: 'atmosphere_background',
+        layout: device.createPipelineLayout({ bindGroupLayouts: [backgroundLayout] }).unwrap(),
+        vertex: { module: backgroundModule, entryPoint: 'atmosphere_background_vs', buffers: [] },
+        fragment: {
+          module: backgroundModule,
+          entryPoint: 'atmosphere_background_fs',
+          targets: [{ format: color.format }],
+        },
+        primitive: { topology: 'triangle-list', cullMode: 'none' },
+        multisample: { count: color.sampleCount },
+      })
+      .unwrap();
+    const sampler = device
+      .createSampler({ minFilter: 'linear', magFilter: 'linear', mipmapFilter: 'linear' })
+      .unwrap();
+    state = { cubePipeline, cubeLayout, backgroundPipeline, backgroundLayout, sampler };
+    return state;
+  };
+  for (let face = 0; face < 6; face += 1) {
+    const faceView = graph.view(cube.value, {
+      dimension: '2d',
+      baseArrayLayer: face,
+      arrayLayerCount: 1,
+    });
+    if (!faceView.ok) return faceView;
+    const pass = graph.addRasterPass(`atmosphere-cube-${face}`, {
+      accesses: [
+        { resource: faceView.value, usage: 'color-attachment' },
+        { resource: params.value, usage: 'uniform-read' },
+        { resource: vertices.value, usage: 'vertex-read' },
+      ],
+      colorAttachments: [{ view: faceView.value, loadOp: 'clear', storeOp: 'store' }],
+      executeIf: dirty,
+      encode: ({ pass, frame, resources }) => {
+        const current = ensureState(frame);
+        current.cubeGroup ??= frame.runtime.device
+          .createBindGroup({
+            layout: current.cubeLayout,
+            entries: [
+              {
+                binding: 0,
+                resource: {
+                  kind: 'buffer',
+                  value: { buffer: resources.buffer(params.value).unwrap(), size: 64 },
+                },
+              },
+            ],
+          })
+          .unwrap();
+        pass.setPipeline(current.cubePipeline);
+        pass.setBindGroup(0, current.cubeGroup);
+        pass.setVertexBuffer(0, resources.buffer(vertices.value).unwrap());
+        pass.draw(3, 1, face * 3, 0);
+        if (face === 5) {
+          const signature = frameOf(frame).frameState.environmentFrame?.environmentSignature;
+          frameOf(frame).frameState.pendingAtmospherePublish = () => {
+            submittedSignature = signature;
+          };
+        }
+      },
+    });
+    if (!pass.ok) return pass;
+  }
+  return graph.addRasterPass('atmosphere-background', {
+    accesses: [
+      { resource: cubeView.value, usage: 'sampled-read' },
+      { resource: params.value, usage: 'uniform-read' },
+      { resource: view.value, usage: 'uniform-read' },
+      { resource: color.view, usage: 'color-attachment' },
+    ],
+    // Initialize scene radiance before opaque and transparent draws. Geometry
+    // uses the normal scene depth authority, so alpha blending sees the sky
+    // and no later background pass can overwrite a transparent foreground.
+    colorAttachments: [{ view: color.view, loadOp: 'clear', storeOp: 'store' }],
+    encode: ({ pass, frame, resources }) => {
+      const current = ensureState(frame);
+      current.backgroundGroup ??= frame.runtime.device
+        .createBindGroup({
+          layout: current.backgroundLayout,
+          entries: [
+            {
+              binding: 0,
+              resource: {
+                kind: 'textureView',
+                value: resources.textureView(cubeView.value).unwrap(),
+              },
+            },
+            { binding: 1, resource: { kind: 'sampler', value: current.sampler } },
+            {
+              binding: 2,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: resources.buffer(view.value).unwrap(), size: VIEW_UNIFORM_BYTES },
+              },
+            },
+            {
+              binding: 3,
+              resource: {
+                kind: 'buffer',
+                value: { buffer: resources.buffer(params.value).unwrap(), size: 64 },
+              },
+            },
+          ],
+        })
+        .unwrap();
+      pass.setPipeline(current.backgroundPipeline);
+      pass.setBindGroup(0, current.backgroundGroup);
+      pass.draw(3);
+    },
+  });
+}

package/src/errors/gpu-driven.ts

@@ -8,7 +8,8 @@ export type GpuDrivenPreparationErrorCode =
   | 'alpha-mask-mismatch'
   | 'resource-not-ready'
   | 'stale-generation'
-  | 'skin-receipt-mismatch';
+  | 'skin-receipt-mismatch'
+  | 'shadow-ownership';
 
 export type GpuDrivenPreparationReason =
   | 'material-receipt-missing'
@@ -18,51 +19,81 @@ export type GpuDrivenPreparationReason =
   | 'alpha-mask-receipt-missing'
   | 'material-resource-missing'
   | 'generation-stale'
-  | 'skin-address-missing';
+  | 'skin-address-missing'
+  | 'shadow-ownership-missing';
+
+/** Closed next action; AI callers never need to parse an error message. */
+export type GpuDrivenRecoveryAction =
+  | 'rebuild-producer'
+  | 'route-cpu-lane'
+  | 'retry-same-draw'
+  | 'rebuild-generation'
+  | 'stop-promotion';
 
 export interface GpuDrivenPreparationErrorDetail {
   readonly reason: GpuDrivenPreparationReason;
-  readonly owner: 'material' | 'geometry' | 'skin' | 'generation';
+  readonly owner: 'material' | 'geometry' | 'skin' | 'generation' | 'shadow';
   readonly expected?: string;
   readonly actual?: string;
   readonly expectedGeneration?: number;
   readonly actualGeneration?: number;
+  readonly recovery?: GpuDrivenRecoveryAction;
 }
 
 const ERROR_POLICY: Readonly<
-  Record<GpuDrivenPreparationErrorCode, { readonly expected: string; readonly hint: string }>
+  Record<
+    GpuDrivenPreparationErrorCode,
+    {
+      readonly expected: string;
+      readonly hint: string;
+      readonly recovery: GpuDrivenRecoveryAction;
+    }
+  >
 > = {
   'missing-material-receipt': {
     expected: 'a producer-owned Standard PBR material receipt is present',
     hint: 'cook and load the Standard PBR artifact, then retry preparation',
+    recovery: 'rebuild-producer',
   },
   'missing-uv': {
     expected: 'the geometry exposes every UV set named by the material receipt',
     hint: 'repair the geometry UV semantic or route the draw to the CPU semantic lane',
+    recovery: 'route-cpu-lane',
   },
   'reflection-mismatch': {
     expected: 'the loaded reflection receipt matches the artifact layout identity',
     hint: 'rebuild the material artifact and reflection from one source, then retry',
+    recovery: 'rebuild-producer',
   },
   'vertex-input-mismatch': {
     expected: 'geometry vertex semantics match the material reflection receipt',
     hint: 'repair the geometry vertex semantic layout or route the draw to the CPU lane',
+    recovery: 'route-cpu-lane',
   },
   'alpha-mask-mismatch': {
     expected: 'the Alpha Mask cutoff is present in the material receipt',
     hint: 'declare alphaCutoff in the Standard PBR material schema and recook it',
+    recovery: 'rebuild-producer',
   },
   'resource-not-ready': {
     expected: 'all material resource slots have resolved handles',
     hint: 'resolve the declared texture and sampler resources before recording',
+    recovery: 'retry-same-draw',
   },
   'stale-generation': {
     expected: 'receipt and prepared inputs belong to the requested generation',
     hint: 'discard stale GPU facts, rebuild the producer receipt, and retry the same draw',
+    recovery: 'rebuild-generation',
   },
   'skin-receipt-mismatch': {
     expected: 'skinned geometry has a current palette address receipt',
     hint: 'rebuild the Skin palette receipt for this generation before recording',
+    recovery: 'rebuild-producer',
+  },
+  'shadow-ownership': {
+    expected: 'every declared ShadowCaster pass has one GPU-compatible draw-item owner',
+    hint: 'repair the ShadowCaster producer membership or keep the residual on its explicit CPU lane',
+    recovery: 'route-cpu-lane',
   },
 };
 
@@ -79,7 +110,10 @@ export class GpuDrivenPreparationError extends Error {
     this.code = code;
     this.expected = policy.expected;
     this.hint = policy.hint;
-    this.detail = detail;
+    this.detail = Object.freeze({
+      ...detail,
+      recovery: detail.recovery ?? policy.recovery,
+    });
   }
 }
 

package/src/errors/render.ts

@@ -25,6 +25,7 @@ import type {
   RenderFeatureRecovery,
   RenderFeatureStage,
 } from '../features/vocabulary';
+import type { AutoExposureError } from '../pipeline/standard-output/auto-exposure/inspection';
 import type { SceneDataLane, SceneDataSchemaId } from '../temporal/scene-data';
 import type { TransmissionCapabilityFact } from '../transmission/backdrop';
 import type { RecoveryOutcome, RecoveryPhase } from './recover';
@@ -33,6 +34,28 @@ import type { RecoveryOutcome, RecoveryPhase } from './recover';
 // expected state, actionable `hint`, then typed `detail`. Consumers branch on
 // that shape and never use Error.message as a protocol.
 
+export type {
+  AutoExposureCapabilityUnavailableDetail,
+  AutoExposureError,
+  AutoExposureErrorCode,
+  AutoExposureErrorDetail,
+  AutoExposureErrorDetailByCode,
+  AutoExposureErrorRecord,
+  AutoExposureInspection,
+  AutoExposureInspectionInput,
+  AutoExposureInvalidParameterDetail,
+  AutoExposureReceipt,
+  AutoExposureResetReason,
+  AutoExposureStageFailedDetail,
+  AutoExposureStaleGenerationDetail,
+} from '../pipeline/standard-output/auto-exposure/inspection';
+export {
+  AutoExposureCapabilityUnavailableError,
+  AutoExposureInvalidParameterError,
+  AutoExposureStageFailedError,
+  AutoExposureStaleGenerationError,
+} from '../pipeline/standard-output/auto-exposure/inspection';
+
 export interface LifecycleConstructionFailureDetail {
   readonly owner: string;
   readonly generation: number;
@@ -1177,7 +1200,7 @@ export class FrameReceiptStaleError extends Error {
 }
 
 export interface RendererContractFailureDetail {
-  readonly operation: 'construct' | 'attach' | 'draw' | 'observe';
+  readonly operation: 'construct' | 'attach' | 'draw' | 'request-observation' | 'observe';
   readonly cause: string;
 }
 
@@ -1328,7 +1351,7 @@ export interface RendererOperationDetailByCode {
     readonly cause: RendererOperationCause;
   };
   readonly 'frame-input-invalid': {
-    readonly operation: 'draw' | 'set-profile';
+    readonly operation: 'draw' | 'set-profile' | 'request-observation';
     readonly cause: RendererOperationCause;
   };
   readonly 'scene-projection-failed': {
@@ -1358,7 +1381,7 @@ export interface RendererOperationDetailByCode {
     readonly cause: RendererOperationCause;
   };
   readonly 'renderer-state-invalid': {
-    readonly operation: 'draw' | 'set-profile' | 'recover' | 'dispose';
+    readonly operation: 'draw' | 'set-profile' | 'request-observation' | 'recover' | 'dispose';
     readonly state: string;
     readonly cause?: RendererOperationCause;
   };
@@ -1851,6 +1874,7 @@ export type RenderErrorCode = RenderError['code'];
  */
 export type RenderError =
   | LifecycleConstructionError
+  | AutoExposureError
   | RendererExpectedOperationError
   | FrameReceiptStaleError
   | RendererContractFailureError

package/src/extract/camera.ts

@@ -6,10 +6,13 @@ import {
   antialiasFromF32,
   bloomEnabledFromF32,
   Camera,
+  cameraExposureFromColumns,
   cameraProjectionFromF32,
   tonemapFromF32,
+  validateCameraColorGrading,
 } from '../components/camera';
 import { MotionBlur } from '../components/motion-blur';
+import { ScreenSpaceReflection } from '../components/screen-space-reflection';
 import type { CameraSnapshot } from '../render-contract';
 import { getActiveCamera, selectActiveCameraIndex } from '../systems/active-camera';
 
@@ -23,11 +26,17 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
   const cameras: CameraSnapshot[] = [];
   const cameraEntities: number[] = [];
   const cameraQuery = world
-    .query({ read: [Camera], optional: [MotionBlur], with: [GlobalTransform] })
+    .query({
+      read: [Camera],
+      optional: [MotionBlur, ScreenSpaceReflection],
+      with: [GlobalTransform],
+    })
     .unwrap();
   for (const row of cameraQuery) {
     const cam = row.get(Camera);
     const motionBlur = row.get(MotionBlur);
+    validateCameraColorGrading(cam.temperature, cam.tint, cam.colorLutStrength);
+    const screenSpaceReflection = row.get(ScreenSpaceReflection);
     const entity = row.entity as EntityHandle;
     const worldMat = readWorldMatrix(world, entity);
     if (worldMat === undefined) continue;
@@ -48,6 +57,13 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
       tonemap: tonemapFromF32(cam.tonemap),
       exposure: cam.exposure,
       whitePoint: cam.whitePoint,
+      output: {
+        exposure: cameraExposureFromColumns(cam),
+        temperature: cam.temperature,
+        tint: cam.tint,
+        colorLut: cam.colorLut,
+        colorLutStrength: cam.colorLutStrength,
+      },
       antialias: antialiasFromF32(cam.antialias),
       bloom: bloomEnabledFromF32(cam.bloom),
       bloomThreshold: cam.bloomThreshold,
@@ -68,6 +84,15 @@ export function extractCameraSnapshots(world: World): CameraSnapshot[] {
               sampleCount: motionBlur.sampleCount,
             },
           }),
+      ...(screenSpaceReflection === undefined
+        ? {}
+        : {
+            screenSpaceReflection: {
+              maxDistance: screenSpaceReflection.maxDistance,
+              thickness: screenSpaceReflection.thickness,
+              maxRoughness: screenSpaceReflection.maxRoughness,
+            },
+          }),
     });
     cameraEntities.push(entity as number);
   }