@forgeax/engine-render 0.1.7 → 0.1.19

package/src/features/host.ts

@@ -15,9 +15,12 @@ import type {
   PreparedGraphicsResolver,
   PreparedGraphicsResourceLease,
 } from '../prepare/prepared-graphics-resolver';
+import type { SceneDataTarget } from '../temporal/scene-data';
+import { createSceneDataCatalog, type SceneDataCatalog } from '../temporal/scene-data-catalog';
 import {
   freezeRenderFeaturePlan,
   type RenderFeatureLogicalTarget,
+  type RenderFeatureMaterialShaderBindingContract,
   type RenderFeaturePassDeclaration,
   type RenderFeaturePlan,
   type RenderFeaturePlannedFrame,
@@ -53,6 +56,7 @@ import type {
   RenderFeatureExtractContext,
   RenderFeatureHiddenEntityReport,
   RenderFeatureRecoverInput,
+  RenderFeatureShaderModuleMode,
   RenderFeatureStatus,
   RenderFeatureTargetHandle,
   RenderFeatureWorldVisibilitySnapshot,
@@ -102,8 +106,14 @@ export interface RenderFeatureFrameInput {
   readonly hiddenEntityReports?: readonly RenderFeatureHiddenEntityReport[];
   /** Active-pipeline logical targets available to producer-owned features. */
   readonly targets?: readonly RenderFeatureTargetHandle[];
+  /** Optional renderer-owned semantic catalog for the current plan generation. */
+  readonly sceneData?: SceneDataCatalog;
   readonly generation?: number;
   readonly caps: Readonly<RhiCaps>;
+  /** Renderer-owned material binding contract projection for producer plans. */
+  readonly materialShaderBindingContract?: (
+    materialShaderId: string,
+  ) => RenderFeatureMaterialShaderBindingContract;
   readonly createPreparedGraphicsResolver?: (
     input: RenderFeaturePreparedGraphicsResolverInput,
   ) => PreparedGraphicsResolver;
@@ -115,6 +125,8 @@ export interface RenderFeaturePreparedGraphicsResolverInput {
   readonly featureIdentity: string;
   readonly order: number;
   readonly generation: number;
+  /** Shader preparation policy selected by the owning feature. */
+  readonly shaderModuleMode?: RenderFeatureShaderModuleMode;
   readonly transaction: PreparedGraphicsTransaction;
   readonly fullscreenEffects: ReadonlyMap<string, PostProcessShaderEntry>;
   readonly lookup: (
@@ -428,7 +440,7 @@ function logicalTargets(
 ): readonly RenderFeatureLogicalTarget[] {
   return Object.freeze(
     targets.map((target) => ({
-      name: target.kind === 'scene-color' ? 'color' : 'depth',
+      name: target.name ?? (target.kind === 'scene-color' ? 'color' : 'depth'),
       kind: target.kind === 'scene-color' ? ('color' as const) : ('depth' as const),
       format: target.format,
       sampleCount: target.sampleCount,
@@ -451,14 +463,17 @@ function planFailure(slot: FeatureSlot): RenderFeatureStageFailedError {
 }
 
 function targetHandle(
-  name: string,
+  name: string | SceneDataTarget,
   targets: readonly RenderFeatureTargetHandle[],
-): string | RenderFeatureTargetHandle | undefined {
+): string | RenderFeatureTargetHandle | SceneDataTarget | undefined {
   if (name === 'swapchain') return 'swapchain';
+  if (typeof name !== 'string') return name;
   return targets.find(
     (target) =>
-      (name === 'color' && target.kind === 'scene-color') ||
-      (name === 'depth' && target.kind === 'scene-depth'),
+      target.name === name ||
+      (target.name === undefined &&
+        ((name === 'color' && target.kind === 'scene-color') ||
+          (name === 'depth' && target.kind === 'scene-depth'))),
   );
 }
 
@@ -1169,6 +1184,7 @@ export function runRenderFeatureFrame(
     const gpu: RenderFeatureGpuPrepareSession | undefined = input.gpuWork?.beginFeature(
       identity,
       input.generation ?? 0,
+      feature.shaderModuleMode,
     );
     const featureHiddenEntityReports: RenderFeatureHiddenEntityReport[] = [];
     const extractContext = {
@@ -1194,6 +1210,14 @@ export function runRenderFeatureFrame(
     }
 
     const targets = logicalTargets(input.targets ?? []);
+    const sceneData =
+      input.sceneData ??
+      createSceneDataCatalog({
+        featureIdentity: identity,
+        generation: transaction.generation,
+        planIdentity: `${identity}:${transaction.generation}`,
+        rgba16floatRenderable: input.caps.rgba16floatRenderable === true,
+      });
     const declared = invokeStage(
       slot,
       'plan',
@@ -1203,6 +1227,10 @@ export function runRenderFeatureFrame(
           frame: { frameNumber: input.frameNumber },
           generation: transaction.generation,
           targets,
+          sceneData,
+          ...(input.materialShaderBindingContract === undefined
+            ? {}
+            : { materialShaderBindingContract: input.materialShaderBindingContract }),
         }),
       stageEvents,
       errors,
@@ -1246,6 +1274,9 @@ export function runRenderFeatureFrame(
       featureIdentity: identity,
       order,
       generation: transaction.generation,
+      ...(feature.shaderModuleMode === undefined
+        ? {}
+        : { shaderModuleMode: feature.shaderModuleMode }),
       transaction,
       fullscreenEffects,
       lookup: (reference) =>

package/src/features/motion-blur/__tests__/motion-blur-feature.unit.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest';
+import { SCENE_DATA_TEMPORAL_V1_SCHEMA } from '../../../temporal/scene-data';
+import { createSceneDataCatalog } from '../../../temporal/scene-data-catalog';
+import { freezeRenderFeaturePlan } from '../../plan';
+import { planMotionBlur } from '../motion-blur-feature';
+import { DEFAULT_MOTION_BLUR_PARAMS } from '../motion-blur-params';
+
+const caps = {
+  rgba16floatRenderable: true,
+  compute: true,
+  storageBuffer: true,
+} as never;
+
+describe('Motion Blur feature plan', () => {
+  it('declares one projected fullscreen draw with semantic reads', () => {
+    const catalog = createSceneDataCatalog({
+      featureIdentity: 'forgeax.motion-blur',
+      generation: 4,
+      planIdentity: 'forgeax.motion-blur:4',
+      rgba16floatRenderable: true,
+    });
+    const planned = planMotionBlur(DEFAULT_MOTION_BLUR_PARAMS, {
+      caps,
+      frame: { frameNumber: 7 },
+      generation: 4,
+      targets: [
+        { name: 'motion-input', kind: 'color', format: 'rgba16float', sampleCount: 1 },
+        { name: 'motion-output', kind: 'color', format: 'rgba16float', sampleCount: 1 },
+      ],
+      sceneData: catalog,
+    });
+    expect(planned.ok).toBe(true);
+    if (!planned.ok) return;
+    const frozen = freezeRenderFeaturePlan('forgeax.motion-blur', planned.value, [
+      { name: 'motion-input', kind: 'color', format: 'rgba16float', sampleCount: 1 },
+      { name: 'motion-output', kind: 'color', format: 'rgba16float', sampleCount: 1 },
+    ]);
+    expect(frozen.ok).toBe(true);
+    if (!frozen.ok) return;
+    const bindings = frozen.value.resources.find(
+      (resource) => resource.kind === 'graphics-bindings',
+    );
+    expect(bindings?.kind).toBe('graphics-bindings');
+    const program = frozen.value.resources.find(
+      (resource) => resource.kind === 'fullscreen-program',
+    );
+    expect(program?.kind).toBe('fullscreen-program');
+    if (program?.kind === 'fullscreen-program') {
+      expect(program.reads).toEqual(['scene-color', 'scene-temporal']);
+      expect(program.reads).not.toContainEqual({ key: 'scene-depth', sampleType: 'depth' });
+    }
+    if (bindings?.kind === 'graphics-bindings') {
+      expect(bindings.values).not.toHaveProperty('depth');
+      expect(bindings.logicalTargets).toEqual({ input: 'motion-input' });
+    }
+    expect(frozen.value.passes).toHaveLength(1);
+    const pass = frozen.value.passes[0];
+    expect(pass?.kind).toBe('raster');
+    if (pass?.kind !== 'raster') return;
+    expect(pass.draws[0]?.vertexLayout).toBe('none');
+    expect(pass.sampledTargets).toEqual(
+      expect.arrayContaining(['motion-input', catalog.require(SCENE_DATA_TEMPORAL_V1_SCHEMA)]),
+    );
+    expect(pass.sampledTargets).not.toContain('motion-depth');
+    expect(catalog.schema).toBe(SCENE_DATA_TEMPORAL_V1_SCHEMA);
+  });
+});

package/src/features/motion-blur/__tests__/motion-blur-params.unit.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import {
+  DEFAULT_MOTION_BLUR_PARAMS,
+  motionBlurTemporalDemand,
+  validateMotionBlurParams,
+} from '../motion-blur-params';
+
+describe('Motion Blur parameter validation', () => {
+  it('applies the bounded defaults', () => {
+    expect(validateMotionBlurParams({})).toEqual({ ok: true, value: DEFAULT_MOTION_BLUR_PARAMS });
+    expect(DEFAULT_MOTION_BLUR_PARAMS).toEqual({
+      shutterAngle: 180,
+      maxRadiusPixels: 32,
+      sampleCount: 8,
+    });
+  });
+
+  it.each([
+    [{ shutterAngle: 0 }, 'identity shutter'],
+    [{ shutterAngle: 360, maxRadiusPixels: 0, sampleCount: 4 }, 'lower and upper bounds'],
+    [{ shutterAngle: 12, maxRadiusPixels: 64, sampleCount: 16 }, 'valid upper bounds'],
+  ] as const)('accepts %s (%s)', (input, _label) => {
+    const result = validateMotionBlurParams(input);
+    expect(result.ok).toBe(true);
+  });
+
+  it.each([
+    ['shutterAngle', -0.01],
+    ['shutterAngle', 360.01],
+    ['maxRadiusPixels', -0.01],
+    ['maxRadiusPixels', 64.01],
+    ['sampleCount', 3],
+    ['sampleCount', 17],
+    ['sampleCount', 8.5],
+  ] as const)('returns structured failure for %s=%s', (field, value) => {
+    const result = validateMotionBlurParams({ [field]: value });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('motion-blur-invalid-params');
+      expect(result.error.detail.field).toBe(field);
+      expect(result.error.expected).toContain(field);
+      expect(result.error.hint).toContain(field);
+    }
+  });
+
+  it('does no temporal work when omitted or shutter is zero', () => {
+    expect(motionBlurTemporalDemand(undefined)).toBe(false);
+    expect(motionBlurTemporalDemand({ shutterAngle: 0, maxRadiusPixels: 32, sampleCount: 8 })).toBe(
+      false,
+    );
+    expect(motionBlurTemporalDemand(DEFAULT_MOTION_BLUR_PARAMS)).toBe(true);
+  });
+});

package/src/features/motion-blur/motion-blur-feature.ts

@@ -0,0 +1,119 @@
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import type { RenderError } from '../../errors/render';
+import type { RenderPipelineFrame, RenderPipelineTarget } from '../../render-pipeline';
+import { SCENE_DATA_TEMPORAL_V1_SCHEMA } from '../../temporal/scene-data';
+import { addTypedFullscreenPass } from '../../typed-render-graph-primitives';
+import type { RenderFeaturePlan, RenderFeaturePlanContext } from '../plan';
+import type { RenderFeature, RenderFeatureExtractContext } from '../types';
+import {
+  type MotionBlurParams,
+  motionBlurTemporalDemand,
+  validateMotionBlurParams,
+} from './motion-blur-params';
+
+export const MOTION_BLUR_FEATURE_IDENTITY = 'forgeax.motion-blur';
+
+export function addMotionBlurPass(
+  graph: RenderGraphBuilder<RenderPipelineFrame>,
+  input: RenderPipelineTarget,
+  temporal: RenderPipelineTarget,
+  output: RenderPipelineTarget,
+): Result<void, RenderGraphError> {
+  return addTypedFullscreenPass(graph, {
+    name: 'motion-blur',
+    shader: MOTION_BLUR_FEATURE_IDENTITY,
+    input,
+    additionalReads: [{ key: 'scene-temporal', target: temporal }],
+    output,
+  });
+}
+
+export interface MotionBlurFeatureFrame {
+  readonly params: MotionBlurParams | undefined;
+  readonly demanded: boolean;
+}
+
+export function planMotionBlur(
+  params: MotionBlurParams,
+  context: RenderFeaturePlanContext,
+): Result<RenderFeaturePlan, RenderError> {
+  if (!motionBlurTemporalDemand(params)) return ok({ resources: [], passes: [] });
+  try {
+    const temporal = context.sceneData.require(SCENE_DATA_TEMPORAL_V1_SCHEMA);
+    const outputFormat =
+      context.targets.find((target) => target.name === 'motion-output')?.format ?? 'rgba16float';
+    return ok({
+      resources: [
+        {
+          kind: 'fullscreen-program',
+          name: 'motion-blur',
+          source: 'forgeax::shader::motion-blur',
+          reads: ['scene-color', 'scene-temporal'],
+          params: { byteSize: 16, defaultValue: new Uint8Array(16) },
+        },
+        {
+          kind: 'graphics-program',
+          name: 'motion-blur-pipeline',
+          program: {
+            shader: MOTION_BLUR_FEATURE_IDENTITY,
+            vertexLayout: 'none',
+            colorFormats: [outputFormat],
+            sampleCount: 1,
+          },
+        },
+        {
+          kind: 'graphics-bindings',
+          name: 'motion-blur-bindings',
+          program: 'motion-blur-pipeline',
+          values: {
+            group: 1,
+            fullscreen: true,
+            shader: MOTION_BLUR_FEATURE_IDENTITY,
+            input: 'motion-input',
+            temporal,
+          },
+          logicalTargets: { input: 'motion-input' },
+        },
+      ],
+      passes: [
+        {
+          kind: 'raster',
+          name: 'motion-blur',
+          colorAttachments: [{ target: 'motion-output', loadOp: 'clear', storeOp: 'store' }],
+          sampledTargets: ['motion-input', temporal],
+          draws: [
+            {
+              program: 'motion-blur-pipeline',
+              bindings: ['motion-blur-bindings'],
+              vertexData: [],
+              vertexLayout: 'none',
+              draw: { kind: 'draw', vertexCount: 3, instanceCount: 1 },
+            },
+          ],
+        },
+      ],
+    });
+  } catch (cause) {
+    return err(cause as RenderError);
+  }
+}
+
+export function createMotionBlurFeature(
+  read: () => Partial<MotionBlurParams> | undefined,
+): RenderFeature<MotionBlurFeatureFrame> {
+  return Object.freeze({
+    identity: MOTION_BLUR_FEATURE_IDENTITY,
+    extract: (_context: RenderFeatureExtractContext) => {
+      const input = read();
+      const validated = validateMotionBlurParams(input);
+      if (!validated.ok) return err(validated.error as unknown as RenderError);
+      const params = input === undefined ? undefined : validated.value;
+      return ok({ params, demanded: motionBlurTemporalDemand(params) });
+    },
+    plan: (frame: MotionBlurFeatureFrame, context: RenderFeaturePlanContext) =>
+      frame.params === undefined
+        ? ok({ resources: [], passes: [] })
+        : planMotionBlur(frame.params, context),
+  });
+}

package/src/features/motion-blur/motion-blur-params.ts

@@ -0,0 +1,89 @@
+import { err, ok, type Result } from '@forgeax/engine-types';
+
+export interface MotionBlurParams {
+  readonly shutterAngle: number;
+  readonly maxRadiusPixels: number;
+  readonly sampleCount: number;
+}
+
+export const DEFAULT_MOTION_BLUR_PARAMS: MotionBlurParams = Object.freeze({
+  shutterAngle: 180,
+  maxRadiusPixels: 32,
+  sampleCount: 8,
+});
+
+export interface MotionBlurInvalidParamsDetail {
+  readonly field: keyof MotionBlurParams;
+  readonly value: unknown;
+  readonly min: number;
+  readonly max: number;
+  readonly integer?: boolean;
+}
+
+export class MotionBlurValidationError extends Error {
+  readonly code = 'motion-blur-invalid-params' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: MotionBlurInvalidParamsDetail;
+
+  constructor(detail: MotionBlurInvalidParamsDetail) {
+    const integer = detail.integer === true ? 'integer ' : '';
+    const expected = `${detail.field} ${integer}in [${detail.min}, ${detail.max}]`;
+    super(`motion-blur-invalid-params: ${expected}`);
+    this.name = 'MotionBlurValidationError';
+    this.expected = expected;
+    this.hint = `set ${detail.field} to an ${integer}value in [${detail.min}, ${detail.max}]`;
+    this.detail = detail;
+  }
+}
+
+function validateField(
+  field: keyof MotionBlurParams,
+  value: number,
+  min: number,
+  max: number,
+  integer = false,
+): MotionBlurValidationError | undefined {
+  if (
+    !Number.isFinite(value) ||
+    value < min ||
+    value > max ||
+    (integer && !Number.isInteger(value))
+  ) {
+    return new MotionBlurValidationError({
+      field,
+      value,
+      min,
+      max,
+      ...(integer ? { integer } : {}),
+    });
+  }
+  return undefined;
+}
+
+export function validateMotionBlurParams(
+  input: Partial<MotionBlurParams> | undefined,
+): Result<MotionBlurParams, MotionBlurValidationError> {
+  const value = input ?? {};
+  const shutterAngle = value.shutterAngle ?? DEFAULT_MOTION_BLUR_PARAMS.shutterAngle;
+  const maxRadiusPixels = value.maxRadiusPixels ?? DEFAULT_MOTION_BLUR_PARAMS.maxRadiusPixels;
+  const sampleCount = value.sampleCount ?? DEFAULT_MOTION_BLUR_PARAMS.sampleCount;
+  const shutterError = validateField('shutterAngle', shutterAngle, 0, 360);
+  if (shutterError !== undefined) return err(shutterError);
+  const radiusError = validateField('maxRadiusPixels', maxRadiusPixels, 0, 64);
+  if (radiusError !== undefined) return err(radiusError);
+  const sampleError = validateField('sampleCount', sampleCount, 4, 16, true);
+  if (sampleError !== undefined) return err(sampleError);
+  return ok(Object.freeze({ shutterAngle, maxRadiusPixels, sampleCount }));
+}
+
+export function motionBlurTemporalDemand(params: MotionBlurParams | undefined): boolean {
+  return params !== undefined && params.shutterAngle > 0;
+}
+
+export function resolveMotionBlurParams(
+  input: Partial<MotionBlurParams> | undefined,
+): Result<MotionBlurParams | undefined, MotionBlurValidationError> {
+  if (input === undefined) return ok(undefined);
+  return validateMotionBlurParams(input);
+}

package/src/features/plan.ts

@@ -2,6 +2,7 @@ import type { GraphBufferAccess, GraphTextureAccess } from '@forgeax/engine-rend
 import type { RhiCaps, TextureFormat } from '@forgeax/engine-rhi';
 import { err, ok, type Result } from '@forgeax/engine-types';
 import type { RenderError } from '../errors/render';
+import type { SceneDataTarget } from '../temporal/scene-data';
 import type {
   RenderFeatureGpuBufferUsage,
   RenderFeatureGpuProgramDescriptor,
@@ -10,10 +11,27 @@ import type { RenderFeaturePipelineDescriptor } from './prepared-graphics';
 
 export type RenderFeatureResourceUsage = GraphBufferAccess | GraphTextureAccess;
 
+/**
+ * Renderer-owned binding layout contract for a material shader.
+ *
+ * Producer features use this read-only projection to describe which logical
+ * scene resources a custom material consumes. The render owner remains the
+ * source of truth for the shader source and its pipeline layout.
+ */
+export type RenderFeatureMaterialShaderBindingContract =
+  | 'group-0'
+  | 'group-0-resource'
+  | 'view-only'
+  | 'view-and-scene-depth'
+  | 'render-material';
+
 export type RenderFeatureFullscreenRead =
   | string
   | { readonly key: string; readonly sampleType?: 'depth' };
 
+/** A named graph target or an authorized semantic sampled-read target. */
+export type RenderFeatureSampledTarget = string | SceneDataTarget;
+
 /** A cooked fullscreen shader declaration owned by a RenderFeature plan. */
 export interface RenderFeatureFullscreenProgramDeclaration {
   readonly kind: 'fullscreen-program';
@@ -32,6 +50,7 @@ export type RenderFeatureBindingValue =
   | number
   | string
   | ArrayBufferView
+  | SceneDataTarget
   | readonly RenderFeatureBindingValue[]
   | { readonly [name: string]: RenderFeatureBindingValue };
 
@@ -167,7 +186,7 @@ export type RenderFeaturePassDeclaration =
         readonly depthLoadOp: 'load' | 'clear';
         readonly depthStoreOp: 'store' | 'discard';
       };
-      readonly sampledTargets?: readonly string[];
+      readonly sampledTargets?: readonly RenderFeatureSampledTarget[];
       readonly draws: readonly RenderFeatureDrawDeclaration[];
     };
 
@@ -193,6 +212,12 @@ export interface RenderFeaturePlanContext {
   readonly frame: { readonly frameNumber: number };
   readonly generation: number;
   readonly targets: readonly RenderFeatureLogicalTarget[];
+  /** Read-only semantic scene-data resolver bound to this plan generation. */
+  readonly sceneData: import('../temporal/scene-data-catalog').SceneDataCatalog;
+  /** Resolve a material shader's renderer-owned binding contract. */
+  readonly materialShaderBindingContract?: (
+    materialShaderId: string,
+  ) => RenderFeatureMaterialShaderBindingContract;
 }
 
 /** Frozen declaration produced for one feature in one frame. */
@@ -303,12 +328,15 @@ export function deriveRenderFeaturePassAccess(
   if (pass.depthStencilAttachment !== undefined) {
     accesses.push({
       resource: pass.depthStencilAttachment.target,
-      usage: pass.sampledTargets?.includes(pass.depthStencilAttachment.target)
+      usage: pass.sampledTargets?.some(
+        (target) => typeof target === 'string' && target === pass.depthStencilAttachment?.target,
+      )
         ? 'depth-stencil-read'
         : 'depth-stencil-write',
     });
   }
   for (const target of pass.sampledTargets ?? []) {
+    if (typeof target !== 'string') continue;
     accesses.push({ resource: target, usage: 'sampled-read' });
   }
   for (const draw of pass.draws) {
@@ -411,7 +439,8 @@ export function freezeRenderFeaturePlan(
       pass.colorAttachments.some((attachment) => !targets.has(attachment.target)) ||
       (pass.depthStencilAttachment !== undefined &&
         !targets.has(pass.depthStencilAttachment.target)) ||
-      pass.sampledTargets?.some((target) => !targets.has(target)) === true
+      pass.sampledTargets?.some((target) => typeof target === 'string' && !targets.has(target)) ===
+        true
     ) {
       return err(stageFailure(identity));
     }

package/src/features/prepared-gpu-work.ts

@@ -13,6 +13,7 @@ import type {
 import { type BindGroupLayoutDescriptor, err, ok, type Result } from '@forgeax/engine-types';
 import { type RenderError, RenderFeaturePreparationFailedError } from '../errors/render';
 import type { PipelineBuilderShaderModuleFactory } from '../pipeline-builder';
+import type { RenderFeatureShaderModuleMode } from './types';
 
 declare const RenderFeatureGpuProgramBrand: unique symbol;
 export interface RenderFeatureGpuProgramRef {
@@ -909,7 +910,11 @@ function createRenderFeatureGpuWorkSession(input: {
  * retains the per-feature prepared GPU state and recreates it after recovery.
  */
 export interface RenderFeatureGpuWorkOwner {
-  beginFeature(featureIdentity: string, generation: number): RenderFeatureGpuPrepareSession;
+  beginFeature(
+    featureIdentity: string,
+    generation: number,
+    shaderModuleMode?: RenderFeatureShaderModuleMode,
+  ): RenderFeatureGpuPrepareSession;
   resolveBuffer(
     featureIdentity: string,
     reference: RenderFeatureGpuBufferRef,
@@ -920,27 +925,37 @@ export interface RenderFeatureGpuWorkOwner {
 export function createRenderFeatureGpuWorkOwner(input: {
   readonly getDevice: () => RhiDevice;
   readonly getShaderModuleFactory: () => PipelineBuilderShaderModuleFactory;
+  readonly getImmediateShaderModuleFactory?: () => PipelineBuilderShaderModuleFactory;
 }): RenderFeatureGpuWorkOwner {
   const sessions = new Map<
     string,
-    { generation: number; session: RenderFeatureGpuPrepareSession }
+    {
+      generation: number;
+      shaderModuleMode: RenderFeatureShaderModuleMode;
+      session: RenderFeatureGpuPrepareSession;
+    }
   >();
 
   return {
-    beginFeature: (featureIdentity, generation) => {
+    beginFeature: (featureIdentity, generation, requestedShaderModuleMode = 'validated') => {
+      const shaderModuleMode = requestedShaderModuleMode;
       const existing = sessions.get(featureIdentity);
-      if (existing?.generation === generation) {
+      if (existing?.generation === generation && existing.shaderModuleMode === shaderModuleMode) {
         existing.session.beginFrame();
         return existing.session;
       }
       if (existing !== undefined) existing.session.dispose();
+      const shaderModuleFactory =
+        shaderModuleMode === 'immediate'
+          ? (input.getImmediateShaderModuleFactory?.() ?? input.getShaderModuleFactory())
+          : input.getShaderModuleFactory();
       const session = createRenderFeatureGpuWorkSession({
         device: input.getDevice(),
-        shaderModuleFactory: input.getShaderModuleFactory(),
+        shaderModuleFactory,
         generation,
         featureIdentity,
       });
-      sessions.set(featureIdentity, { generation, session });
+      sessions.set(featureIdentity, { generation, shaderModuleMode, session });
       session.beginFrame();
       return session;
     },

package/src/features/prepared-graphics.ts

@@ -19,6 +19,7 @@ import {
   type RenderFeaturePreparedStateMismatchDetail,
   RenderFeaturePreparedStateMismatchError,
 } from '../errors/render';
+import type { SceneDataTarget } from '../temporal/scene-data';
 import type { RenderFeatureGpuBufferRef } from './prepared-gpu-work';
 import type { RenderFeatureTargetHandle } from './targets';
 import type { PreparedKind } from './vocabulary';
@@ -234,7 +235,7 @@ export type RenderFeatureDrawRecord =
 export interface RenderFeatureGraphicsPassDescriptor {
   readonly attachments: RenderFeatureGraphicsPassAttachments;
   /** Targets sampled by shaders but not attached for writing in this pass. */
-  readonly sampledTargets?: readonly RenderFeatureTargetHandle[];
+  readonly sampledTargets?: readonly (RenderFeatureTargetHandle | SceneDataTarget)[];
   readonly draws: readonly RenderFeatureDrawRecord[];
 }
 

package/src/features/render-graph-raster.ts

@@ -19,6 +19,7 @@ import type {
   PreparedGraphicsResolvedResource,
   PreparedGraphicsResolvedSnapshot,
 } from '../prepare/prepared-graphics-resolver';
+import type { SceneDataTarget } from '../temporal/scene-data';
 import type { RenderFeatureResolvedGpuBuffer } from './prepared-gpu-work';
 import type {
   RenderFeatureGraphicsPassDescriptor,
@@ -40,7 +41,7 @@ export interface RenderFeatureGraphTarget {
 }
 
 export type RenderFeatureGraphTargetResolver = (
-  resource: string | RenderFeatureTargetHandle,
+  resource: string | RenderFeatureTargetHandle | SceneDataTarget,
 ) => RenderFeatureGraphTarget | undefined;
 
 export type RenderFeatureGraphBindingsResolution =