@forgeax/engine-render 0.1.32 → 0.1.34

package/src/extract/contracts.ts

@@ -13,6 +13,7 @@ import type {
   MaterialAsset,
   MaterialPass,
   MaterialRenderState,
+  MaterialSurfaceModel,
   MaterialTextureCoordinates,
   MeshLodLevel,
   ParamSchemaEntry,
@@ -394,6 +395,8 @@ export interface ExtractedVolumetricFog {
   readonly generation?: number;
   readonly digest?: string;
   readonly worldId?: number;
+  /** Canonical simulation time projected from the owning World. */
+  readonly worldTimeSeconds?: number;
   readonly lightEntity?: EntityHandle;
   readonly lightKind?: 'directional' | 'point' | 'spot';
   readonly pointLightEntity?: EntityHandle;
@@ -530,6 +533,9 @@ export type RenderableReactiveReason =
 export interface RenderableTemporalSnapshot {
   readonly previousEpoch: number | undefined;
   readonly previousSource: RenderablePreviousSource;
+  /** True only when current and previous geometry belong to one stable source identity. */
+  readonly motionValid: boolean;
+  /** Color-history invalidation is independent from motion validity. */
   readonly reactive: boolean;
   readonly reactiveReasons: readonly RenderableReactiveReason[];
   readonly previousTransform: TransformSnapshot;
@@ -563,6 +569,8 @@ export interface GpuDrivenDrawSnapshot {
 export interface InstancesSnapshot {
   /** Packed column-major mat4 transforms (16 f32 per instance). */
   readonly transforms: Float32Array;
+  /** Optional unique identity generations; tokens travel with instances through reorder. */
+  readonly generations?: Uint32Array;
   /** Number of instances (transforms.length / 16). */
   readonly instanceCount: number;
   /** Stable per-entity GPU buffer cache key (the packed Entity u32). */
@@ -645,6 +653,10 @@ export interface MaterialSnapshot {
   readonly baseColor: Vec3;
   readonly metallic: number;
   readonly roughness: number;
+  /** Root-owned Surface model used only for typed pass routing. */
+  readonly surfaceModel?: MaterialSurfaceModel | undefined;
+  /** Whether this material publishes a Deferred pass consumed before the forward-only lane. */
+  readonly deferredPass?: boolean | undefined;
   readonly clearcoat?: number | undefined;
   readonly clearcoatRoughness?: number | undefined;
   /** Authored Standard PBR specular tint in linear runtime color space. */

package/src/extract/environment.ts

@@ -39,6 +39,8 @@ export interface AtmosphereParameters {
   readonly mieCoefficient: number;
   readonly mieDirectionalG: number;
   readonly sunAngularRadius: number;
+  readonly circumsolarStrength: number;
+  readonly circumsolarWidth: number;
 }
 
 /** Shared CPU contract for values accepted by the atmosphere shaders. */
@@ -50,6 +52,8 @@ export const ATMOSPHERE_PARAMETER_RANGES: Readonly<
   mieCoefficient: Object.freeze({ min: 0, max: Number.POSITIVE_INFINITY }),
   mieDirectionalG: Object.freeze({ min: 0, max: 0.999 }),
   sunAngularRadius: Object.freeze({ min: 0, max: Number.POSITIVE_INFINITY }),
+  circumsolarStrength: Object.freeze({ min: 0, max: 4 }),
+  circumsolarWidth: Object.freeze({ min: 0.25, max: 4 }),
 });
 
 export interface FogCandidate {

package/src/features/barrel-distortion.ts

@@ -0,0 +1,172 @@
+/** One graph-valid identity for the barrel stage, feature and shader prewarm. */
+export const BARREL_DISTORTION_POST_PROCESS_ID = 'fullscreen.forgeax.barrel-distortion';
+export const BARREL_DISTORTION_FEATURE_IDENTITY = BARREL_DISTORTION_POST_PROCESS_ID;
+
+import { ok, type Result } from '@forgeax/engine-types';
+import type { RenderError } from '../errors/render';
+import type { RenderFeaturePlan } from './plan';
+import type { RenderFeature, RenderFeatureExtractContext, RenderFeaturePlanContext } from './types';
+
+/**
+ * The coordinate function is exported beside the production shader so a real
+ * f32 device probe can compile exactly the same implementation.  Keeping the
+ * probe source here avoids a second test-only equation that could drift from
+ * the Standard pass.
+ */
+export const BARREL_DISTORTION_WGSL_COORDINATE = /* wgsl */ `
+struct BarrelDistortionParams {
+  strength : f32,
+  centerX : f32,
+  centerY : f32,
+  radiusSquared : f32,
+};
+
+fn barrel_distortion_display_to_scene_uv(
+  inputUv : vec2<f32>,
+  params : BarrelDistortionParams,
+  dimensions : vec2<f32>,
+) -> vec2<f32> {
+  let aspect = dimensions.x / max(dimensions.y, 1.0);
+  let p = vec2<f32>(
+    2.0 * aspect * (inputUv.x - params.centerX),
+    2.0 * (inputUv.y - params.centerY),
+  );
+  let t = dot(p, p) / max(params.radiusSquared, 1e-6);
+  let scale = (1.0 - params.strength) / (1.0 - params.strength * t);
+  return clamp(
+    vec2<f32>(
+      params.centerX + (inputUv.x - params.centerX) * scale,
+      params.centerY + (inputUv.y - params.centerY) * scale,
+    ),
+    vec2<f32>(0.0),
+    vec2<f32>(1.0),
+  );
+}
+`;
+
+/**
+ * Manifest-equivalent WGSL for the bounded analytic model.  The Standard
+ * owner registers this source once and keeps the graph, encoder, and submit
+ * lifecycle shared with every other fullscreen stage.
+ */
+export const BARREL_DISTORTION_WGSL = /* wgsl */ `${BARREL_DISTORTION_WGSL_COORDINATE}
+struct FullscreenOutput {
+  @builtin(position) position : vec4<f32>,
+  @location(0) uv : vec2<f32>,
+};
+
+fn fullscreen_triangle(vertex_index : u32) -> FullscreenOutput {
+  var x : f32 = -1.0;
+  var y : f32 = -1.0;
+  if (vertex_index == 1u) { x = 3.0; }
+  if (vertex_index == 2u) { y = 3.0; }
+  let u : f32 = (x + 1.0) * 0.5;
+  let v : f32 = 1.0 - (y + 1.0) * 0.5;
+  var out : FullscreenOutput;
+  out.position = vec4<f32>(x, y, 0.0, 1.0);
+  out.uv = vec2<f32>(u, v);
+  return out;
+}
+
+@group(1) @binding(0) var sceneColor : texture_2d<f32>;
+@group(1) @binding(1) var sceneSampler : sampler;
+
+@group(1) @binding(2) var<uniform> params : BarrelDistortionParams;
+
+@vertex
+fn vs_main(@builtin(vertex_index) vertex_index : u32) -> FullscreenOutput {
+  return fullscreen_triangle(vertex_index);
+}
+
+@fragment
+fn fs_main(input : FullscreenOutput) -> @location(0) vec4<f32> {
+  let dimensions = vec2<f32>(textureDimensions(sceneColor));
+  let sampleUv = barrel_distortion_display_to_scene_uv(input.uv, params, dimensions);
+  return textureSampleLevel(sceneColor, sceneSampler, sampleUv, 0.0);
+}
+`;
+
+/**
+ * Ordinary feature registration for the Standard linear-LDR stage.
+ * Standard still allocates the stage targets and chooses its position in the
+ * post chain; this feature owns the executable fullscreen declaration that is
+ * projected into that slot by the existing graph/encoder/submit path.
+ */
+export interface BarrelDistortionFeatureFrame {
+  /** True only when the extracted camera requires a spatial warp this frame. */
+  readonly active: boolean;
+}
+
+export function createBarrelDistortionRenderFeature(): RenderFeature<BarrelDistortionFeatureFrame> {
+  return Object.freeze({
+    identity: BARREL_DISTORTION_FEATURE_IDENTITY,
+    requiredCapabilities: ['rgba16floatRenderable'] as const,
+    requiredFullscreenPostProcesses: [
+      { identity: BARREL_DISTORTION_POST_PROCESS_ID, source: BARREL_DISTORTION_WGSL },
+    ],
+    extract: (
+      context: RenderFeatureExtractContext,
+    ): Result<BarrelDistortionFeatureFrame, RenderError> =>
+      ok({ active: (context.selectedCamera?.barrelDistortion?.strength ?? 0) > 0 }),
+    plan: (
+      data: BarrelDistortionFeatureFrame,
+      _context: RenderFeaturePlanContext,
+    ): Result<RenderFeaturePlan, RenderError> =>
+      ok({
+        resources: data.active
+          ? [
+              {
+                kind: 'fullscreen-program' as const,
+                name: BARREL_DISTORTION_POST_PROCESS_ID,
+                source: BARREL_DISTORTION_WGSL,
+                reads: ['ldrColor'],
+                params: { byteSize: 16, defaultValue: new Uint8Array(16) },
+              },
+              {
+                kind: 'graphics-program' as const,
+                name: 'barrel-distortion-pipeline',
+                program: {
+                  shader: BARREL_DISTORTION_POST_PROCESS_ID,
+                  vertexLayout: 'none',
+                  colorFormats: ['rgba16float'],
+                  sampleCount: 1,
+                },
+              },
+              {
+                kind: 'graphics-bindings' as const,
+                name: 'barrel-distortion-bindings',
+                program: 'barrel-distortion-pipeline',
+                values: {
+                  group: 1,
+                  fullscreen: true,
+                  shader: BARREL_DISTORTION_POST_PROCESS_ID,
+                  input: 'barrel-input',
+                },
+                logicalTargets: { input: 'barrel-input' },
+              },
+            ]
+          : [],
+        passes: data.active
+          ? [
+              {
+                kind: 'raster' as const,
+                name: 'barrel-distortion',
+                colorAttachments: [
+                  { target: 'barrel-output', loadOp: 'clear' as const, storeOp: 'store' as const },
+                ],
+                sampledTargets: ['barrel-input'],
+                draws: [
+                  {
+                    program: 'barrel-distortion-pipeline',
+                    bindings: ['barrel-distortion-bindings'],
+                    vertexData: [],
+                    vertexLayout: 'none' as const,
+                    draw: { kind: 'draw' as const, vertexCount: 3, instanceCount: 1 },
+                  },
+                ],
+              },
+            ]
+          : [],
+      }),
+  });
+}

package/src/features/error-reporting.ts

@@ -0,0 +1,98 @@
+import type { RenderError } from '../errors/render';
+
+/**
+ * Recoverable feature preparation failures are still useful diagnostics, but
+ * they are not new failures on every render tick. Keep the reporting policy
+ * independent from the frame orchestration so it can be exercised without a
+ * renderer or device.
+ */
+export const PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES = 60;
+
+export interface PendingRenderFeatureErrorReport {
+  readonly frame: number;
+  readonly fingerprint: string;
+}
+
+export function shouldReportPendingRenderFeatureError(
+  lastReportedFrame: Map<string, PendingRenderFeatureErrorReport>,
+  key: string,
+  frameNumber: number,
+  fingerprint = '',
+  intervalFrames = PENDING_RENDER_FEATURE_ERROR_REPORT_INTERVAL_FRAMES,
+): boolean {
+  const lastReported = lastReportedFrame.get(key);
+  if (
+    lastReported !== undefined &&
+    lastReported.fingerprint === fingerprint &&
+    frameNumber - lastReported.frame < intervalFrames
+  )
+    return false;
+  lastReportedFrame.set(key, { frame: frameNumber, fingerprint });
+  return true;
+}
+
+export function reportPendingRenderFeatureErrors(
+  errors: readonly RenderError[],
+  frameNumber: number,
+  lastReportedFrame: Map<string, PendingRenderFeatureErrorReport>,
+  errorRegistry: { fire(error: RenderError): void },
+): void {
+  for (const error of errors) {
+    if (!isPendingRenderFeaturePreparation(error)) {
+      errorRegistry.fire(error);
+      continue;
+    }
+    // A missing prepared resource during its normal asynchronous warm-up is
+    // an expected candidate state. Keep that path silent; other next-frame
+    // failures still receive first/periodic reporting.
+    if (isSilentRenderFeatureWarmup(error)) continue;
+    const key = pendingRenderFeatureErrorKey(error);
+    const cause = error.code === 'render-feature-stage-failed' ? error.detail.cause : undefined;
+    const causeText =
+      cause instanceof Error
+        ? `${cause.name}\0${cause.message}`
+        : typeof cause === 'string'
+          ? cause
+          : '';
+    const fingerprint = `${error.expected}\0${error.hint}\0${causeText}`;
+    // Retain one record per owner, not one record per changing cause string.
+    if (shouldReportPendingRenderFeatureError(lastReportedFrame, key, frameNumber, fingerprint)) {
+      errorRegistry.fire(error);
+    }
+  }
+}
+
+function isPendingRenderFeaturePreparation(error: RenderError): boolean {
+  if (!('detail' in error)) return false;
+  switch (error.code) {
+    case 'render-feature-stage-failed':
+    case 'render-feature-preparation-failed':
+    case 'render-feature-prepared-state-mismatch':
+    case 'render-feature-draw-recording-failed':
+      return error.detail.recovery === 'next-frame';
+    default:
+      return false;
+  }
+}
+
+function isSilentRenderFeatureWarmup(error: RenderError): boolean {
+  return (
+    error.code === 'render-feature-preparation-failed' &&
+    error.detail.reason.startsWith('rhi-not-available:')
+  );
+}
+
+function pendingRenderFeatureErrorKey(error: RenderError): string {
+  const detail = 'detail' in error ? error.detail : undefined;
+  const featureIdentity =
+    detail !== undefined &&
+    'featureIdentity' in detail &&
+    typeof detail.featureIdentity === 'string'
+      ? detail.featureIdentity
+      : '';
+  const order =
+    detail !== undefined && 'order' in detail && typeof detail.order === 'number'
+      ? detail.order
+      : -1;
+  return `${error.code}\0${featureIdentity}\0${order}`;
+}