@forgeax/engine-render 0.1.19 → 0.1.21

package/src/extract/directional-shadow-projection.ts

@@ -0,0 +1,61 @@
+// @forgeax/engine-render - Directional CSM projection owner.
+
+import type { DirectionalShadowQuality } from '../components/directional-shadow-filter';
+import { directionalShadowQualityFromF32 } from '../components/directional-shadow-filter';
+
+/** Light-space bounds produced by one existing orthographic CSM fit. */
+export interface DirectionalShadowCascadeFit {
+  readonly split: number;
+  readonly minX: number;
+  readonly maxX: number;
+  readonly minY: number;
+  readonly maxY: number;
+  readonly minZ: number;
+  readonly maxZ: number;
+}
+
+/** Host projection sent to the shared View UBO. */
+export interface DirectionalShadowProjection {
+  readonly splitPlanes: Float32Array;
+  readonly directionalShadowQuality: DirectionalShadowQuality;
+}
+
+/**
+ * Project accepted Directional author facts and the existing CSM fit into the
+ * shared split vec4 lanes. `.x` is the split, `.y` is world units per texel,
+ * `.z` is the light-space depth span, and `.w` is reserved for the ABI.
+ */
+export function projectDirectionalShadow(
+  fits: readonly DirectionalShadowCascadeFit[],
+  mapSize: number,
+  shadowFilter: number,
+  shadowAngularRadius: number,
+  maxPenumbraTexels: number,
+): DirectionalShadowProjection | undefined {
+  if (!Number.isFinite(mapSize) || mapSize < 1) return undefined;
+  const directionalShadowQuality = directionalShadowQualityFromF32(
+    shadowFilter,
+    shadowAngularRadius,
+    maxPenumbraTexels,
+  );
+  if (directionalShadowQuality === undefined) return undefined;
+
+  const splitPlanes = new Float32Array(16);
+  for (let index = 0; index < fits.length && index < 4; index += 1) {
+    const fit = fits[index];
+    if (fit === undefined) continue;
+    const width = Math.abs(fit.maxX - fit.minX);
+    const height = Math.abs(fit.maxY - fit.minY);
+    const depth = Math.abs(fit.maxZ - fit.minZ);
+    const worldUnitsPerTexel = Math.max(width, height, Number.EPSILON) / mapSize;
+    const lightDepthWorldSpan = Math.max(depth, Number.EPSILON);
+    if (!Number.isFinite(worldUnitsPerTexel) || !Number.isFinite(lightDepthWorldSpan)) {
+      return undefined;
+    }
+    const lane = index * 4;
+    splitPlanes[lane] = fit.split;
+    splitPlanes[lane + 1] = worldUnitsPerTexel;
+    splitPlanes[lane + 2] = lightDepthWorldSpan;
+  }
+  return { splitPlanes, directionalShadowQuality };
+}

package/src/extract/environment.ts

@@ -76,6 +76,20 @@ export type EnvironmentSource =
 
 export interface FogFrame extends FogCandidate {}
 
+export interface FogParameterIssue {
+  readonly field: string;
+  readonly value: number;
+  readonly expected: string;
+}
+
+/** Structured failure retained when an invalid Fog update falls back to LKG. */
+export interface FogSelectionFailure {
+  readonly code: string;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: Readonly<Record<string, unknown>>;
+}
+
 export interface EnvironmentFrame {
   readonly source: EnvironmentSource;
   /** Descriptor of the real environment resource adopted for this frame. */
@@ -103,6 +117,49 @@ function freezeFog(candidate: FogCandidate): FogFrame {
   });
 }
 
+/** Validate the bounded Fog domain once for every frame-selection producer. */
+export function validateFogParameters(candidate: FogCandidate): FogParameterIssue | undefined {
+  if (candidate.color.length !== 3) {
+    return {
+      field: 'color',
+      value: candidate.color.length,
+      expected: 'exactly three finite channels in [0, 1]',
+    };
+  }
+  for (let index = 0; index < candidate.color.length; index += 1) {
+    const value = candidate.color[index];
+    if (value === undefined || !Number.isFinite(value) || value < 0 || value > 1) {
+      return {
+        field: `color[${index}]`,
+        value: value ?? Number.NaN,
+        expected: 'a finite number in [0, 1]',
+      };
+    }
+  }
+  if (!Number.isFinite(candidate.density) || candidate.density < 0) {
+    return { field: 'density', value: candidate.density, expected: 'a finite number >= 0' };
+  }
+  if (!Number.isFinite(candidate.heightFalloff) || candidate.heightFalloff < 0) {
+    return {
+      field: 'heightFalloff',
+      value: candidate.heightFalloff,
+      expected: 'a finite number >= 0',
+    };
+  }
+  if (
+    !Number.isFinite(candidate.maxOpacity) ||
+    candidate.maxOpacity < 0 ||
+    candidate.maxOpacity > 1
+  ) {
+    return {
+      field: 'maxOpacity',
+      value: candidate.maxOpacity,
+      expected: 'a finite number in [0, 1]',
+    };
+  }
+  return undefined;
+}
+
 function freezeAtmosphere(parameters: AtmosphereParameters): AtmosphereParameters {
   return Object.freeze({ ...parameters });
 }

package/src/extract/visibility.ts

@@ -1,4 +1,5 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
+import { createWorldProjection } from '@forgeax/engine-ecs/projection';
 import {
   projectHierarchy,
   type SceneHierarchyDiagnostic,
@@ -37,6 +38,14 @@ interface ResolutionState {
   readonly source: VisibilitySource;
 }
 
+interface VisibilityCacheEntry {
+  readonly changes: ReturnType<typeof createWorldProjection>;
+  readonly hierarchy: SceneHierarchySnapshot;
+  readonly snapshot: VisibilitySnapshot;
+}
+
+const VISIBILITY_CACHE = new WeakMap<World, VisibilityCacheEntry>();
+
 /**
  * Resolve author intent against the scene-owned valid parent projection.
  * Diagnostics are preserved for callers to repair hierarchy input before retry.
@@ -45,6 +54,19 @@ export function resolveVisibility(
   world: World,
   hierarchy: SceneHierarchySnapshot = projectHierarchy(world),
 ): VisibilitySnapshot {
+  const cached = VISIBILITY_CACHE.get(world);
+  const changes = cached?.changes ?? createWorldProjection(world, { components: [Visibility] });
+  if (cached !== undefined) {
+    const evidence = changes.poll();
+    if (
+      evidence.status === 'delta' &&
+      evidence.changes.length === 0 &&
+      cached.hierarchy === hierarchy
+    ) {
+      return cached.snapshot;
+    }
+  }
+
   // Visibility is an opt-in component. Query only the owning archetypes
   // instead of walking every Entity row with an optional column; the latter
   // made a World with no visibility intents pay a full-scene scan on each
@@ -123,7 +145,7 @@ export function resolveVisibility(
     };
   };
 
-  return {
+  const snapshot: VisibilitySnapshot = {
     diagnostics: hierarchy.diagnostics,
     hasAnyIntent: intentCount > 0,
     hasAnyHiddenIntent,
@@ -136,4 +158,6 @@ export function resolveVisibility(
       return resolveEntity?.(entity)?.effective ?? 'visible';
     },
   };
+  VISIBILITY_CACHE.set(world, { changes, hierarchy, snapshot });
+  return snapshot;
 }

package/src/features/fullscreen.ts

@@ -28,6 +28,9 @@ export function createFullscreenRenderFeature(
   const resourceName = `fullscreen.${options.identity.replace(/[^a-z0-9.-]/gi, '-').toLowerCase()}`;
   return Object.freeze({
     identity: options.identity,
+    requiredFullscreenPostProcesses: Object.freeze([
+      Object.freeze({ identity: options.identity, source: options.source }),
+    ]),
     extract: (_context: RenderFeatureExtractContext) => ok(undefined),
     plan: (_data: undefined, _context: RenderFeaturePlanContext) =>
       ok({

package/src/features/targets.ts

@@ -57,8 +57,11 @@ export function resolveStandardRenderFeatureTargets(input: {
   readonly colorAttachmentFormat: TextureFormat;
 }): readonly RenderFeatureTargetHandle[] {
   const sampleCount: 1 | 4 = input.antialias === 'msaa' && input.multisample ? 4 : 1;
+  // Standard always exposes the scene to features as a linear float target;
+  // the shared Output Transform owns the eventual RGBA8 write for every
+  // antialias mode, including no-AA/WebGL2.
   const linearLdr =
-    (input.tonemap === 'none' && input.storageBuffer) ||
+    input.tonemap === 'none' ||
     input.antialias === 'fxaa' ||
     (input.antialias === 'msaa' && input.multisample);
   const colorFormat =

package/src/features/types.ts

@@ -98,6 +98,16 @@ export interface RenderFeature<FrameData> {
    * the same lazy module cache used by prepared graphics.
    */
   readonly requiredMaterialShaders?: readonly string[];
+  /**
+   * Fullscreen program sources that must be module-ready before the first
+   * frame. The renderer seeds the same lazy post-process module cache used by
+   * the typed graph, so a synchronous frame driver cannot observe a cleared
+   * target while a boot-installed effect is compiling.
+   */
+  readonly requiredFullscreenPostProcesses?: readonly {
+    readonly identity: string;
+    readonly source: string;
+  }[];
   extract(context: RenderFeatureExtractContext): Result<FrameData, RenderError>;
   plan(data: FrameData, context: RenderFeaturePlanContext): Result<RenderFeaturePlan, RenderError>;
 }

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

@@ -67,7 +67,8 @@ export type PostProcessReadSampleType = 'depth';
  * no paramSchema (params are passed inline via a {type, value} struct — plan-strategy D-4).
  *
  * `params` carries the WGSL struct definition + default value. When `params` is
- * `undefined`, the post-process shader has no UBO (e.g. FXAA — Finding M2-1).
+ * `undefined`, the post-process shader has no params UBO. Special graph-owned
+ * passes such as FXAA may still register an internal policy UBO separately.
  *
  * `reads` declares graph resource keys this pass samples as input texture(s).
  * If omitted, the pass samples the swap-chain color attachment (default path).
@@ -81,7 +82,7 @@ export interface PostProcessShaderEntry {
   /** Composed WGSL source for the fragment stage (post-naga_oil). */
   readonly source: string;
   /**
-   * Params UBO schema. When undefined, the shader has no uniform buffer (e.g. FXAA)
+   * Params UBO schema. When undefined, the generic shader has no uniform buffer
    * and the BGL degrades to 2 entries (texture@0 + sampler@1). When present, the
    * primitive eager-creates a params UBO (at register, sized `byteSize`) and binds
    * it at bindgroup(1) binding(2) as part of a 3-entry BGL
@@ -104,6 +105,46 @@ export interface PostProcessShaderEntry {
   readonly reads?: readonly (string | PostProcessReadEntry)[] | undefined;
 }
 
+function postProcessSourceDigest(source: string): string {
+  let first = 0x811c9dc5;
+  let second = 0x9e3779b9;
+  for (let index = 0; index < source.length; index += 1) {
+    const code = source.charCodeAt(index);
+    first = Math.imul(first ^ code, 0x01000193);
+    second = Math.imul(second ^ (code + index), 0x01000193);
+  }
+  return `${source.length.toString(16)}-${(first >>> 0).toString(16).padStart(8, '0')}-${(second >>> 0).toString(16).padStart(8, '0')}`;
+}
+
+/** Content-addressed PSO label shared by the post-process pipeline factory. */
+export function postProcessShaderPipelineLabel(identity: string, source: string): string {
+  return `post-process-${identity}-pso-${postProcessSourceDigest(source)}`;
+}
+
+/** Content-addressed shader-module label shared by prewarm and lazy paths. */
+export function postProcessShaderModuleLabel(identity: string, source: string): string {
+  return `${postProcessShaderPipelineLabel(identity, source)}-module`;
+}
+
+/**
+ * Stable declaration identity used by graph admission and the renderer's
+ * device-bound pipeline cache.  Shader source, bind-group-affecting params,
+ * and graph reads must move together when a feature reuses its identity.
+ */
+export function postProcessShaderEntrySignature(entry: PostProcessShaderEntry): string {
+  return JSON.stringify({
+    source: entry.source,
+    params:
+      entry.params === undefined
+        ? undefined
+        : {
+            byteSize: entry.params.byteSize,
+            defaultValue: Array.from(entry.params.defaultValue),
+          },
+    reads: entry.reads,
+  });
+}
+
 /** Whether a feature binding opts into the temporal multi-read contract. */
 export function isTemporalFullscreenBinding(values: Readonly<Record<string, unknown>>): boolean {
   return (

package/src/gpu-driven/batch-topology.ts

@@ -53,6 +53,7 @@ function eligibleKeys(slot: RenderSceneSlot): readonly GpuDrivenBatchKey[] {
   if (
     draws === undefined ||
     draws.length === 0 ||
+    snapshot.instances?.instanceCount === 0 ||
     snapshot.localAabb === undefined ||
     snapshot.skin !== undefined ||
     snapshot.spriteInstances !== undefined

package/src/gpu-driven/production-raster.ts

@@ -427,7 +427,6 @@ export class GpuDrivenProduction {
     readonly meshes: ReadonlyMap<number, MeshGpuHandles>;
     readonly viewBindGroupLayout: BindGroupLayout;
     readonly meshResidencyEpoch: number;
-    readonly hdrp: boolean;
   }): Result<PreparedGpuDrivenFrame | undefined, RhiError> {
     this.gpuOwnedSnapshotsMaterialized = 0;
     this.filteredPlanBuilds = 0;
@@ -435,7 +434,6 @@ export class GpuDrivenProduction {
     this.validatedGpuOwnedRows = 0;
     this.cpuFallbackDrawItems = 0;
     if (
-      input.hdrp ||
       input.scene === undefined ||
       !this.device.caps.compute ||
       !this.device.caps.storageBuffer ||
@@ -611,7 +609,7 @@ export class GpuDrivenProduction {
             // shared by the GPU-driven raster pipeline, so even rigid draws
             // must provide the binding-10 offset (zero selects the frame
             // default slot).
-            pass.setBindGroup(0, viewBindGroup, [0]);
+            pass.setBindGroup(0, viewBindGroup, [0, 0]);
             let currentPipeline: RenderPipeline | undefined;
             let currentVertex: GraphBuffer | undefined;
             let currentIndex: GraphBuffer | undefined;

package/src/gpu-scene.ts

@@ -633,7 +633,14 @@ export class GpuScene {
     record: RenderSceneSlot,
     writes: Record<GpuSceneTableName, number[]>,
   ): void {
-    const instanceCount = Math.max(1, record.snapshot.instances?.instanceCount ?? 1);
+    // A present Instances component is authoritative even when its array is
+    // empty: preserve zero so neither the GPU Scene nor the indirect topology
+    // turns it into a synthetic identity instance. Entities without the
+    // component retain the ordinary one-instance identity path.
+    const instanceCount =
+      record.snapshot.instances === undefined
+        ? 1
+        : Math.max(0, Math.floor(record.snapshot.instances.instanceCount));
     const drawCount = Math.max(1, record.snapshot.gpuDrivenDraws?.length ?? 0);
     const materialCount = Math.max(1, record.snapshot.materials.length);
     const existing = this.allocations.get(record.slot);

package/src/gpu-usage.ts

@@ -12,3 +12,5 @@ export const GPU_BUFFER_USAGE_UNIFORM = 0x40;
 export const GPU_BUFFER_USAGE_STORAGE = 0x80;
 export const GPU_BUFFER_USAGE_INDIRECT = 0x100;
 export const GPU_BUFFER_USAGE_MAP_READ = 0x01;
+/** GPUBufferUsage.QUERY_RESOLVE, used by optional timestamp captures. */
+export const GPU_BUFFER_USAGE_QUERY_RESOLVE = 0x200;