@forgeax/engine-render 0.1.19 → 0.1.21

package/dist/volume/inspection.d.ts

@@ -0,0 +1,38 @@
+import type { TextureFormat } from '@forgeax/engine-rhi';
+import type { VolumeRecoveryState, VolumeSelectedLightFacts } from './recovery';
+import type { VolumetricFogResourceFacts } from './resources';
+export type VolumetricFogInspectionStatus = 'off' | 'available' | 'unavailable' | 'degraded';
+export type VolumetricFogResourceStage = 'none' | 'candidate' | 'accepted' | 'lkg' | 'recovering';
+export interface VolumetricFogInspection {
+    readonly status: VolumetricFogInspectionStatus;
+    readonly resourceStage: VolumetricFogResourceStage;
+    readonly guid: string | undefined;
+    readonly generation: number | undefined;
+    readonly digest: string | undefined;
+    readonly candidateGeneration: number | undefined;
+    readonly candidateDigest: string | undefined;
+    readonly lkgGeneration: number | undefined;
+    readonly candidateFailure: VolumeRecoveryState['candidateFailure'];
+    readonly deviceEpoch: number;
+    readonly format: TextureFormat | undefined;
+    readonly passCount: number;
+    readonly sampleCount: number;
+    readonly memoryBytes: number;
+    readonly resourceFacts: VolumetricFogResourceFacts | undefined;
+    readonly selectedLight: VolumeSelectedLightFacts | undefined;
+    readonly candidateSelectedLight: VolumeSelectedLightFacts | undefined;
+}
+export interface VolumetricFogInspectionInput {
+    readonly authored: boolean;
+    readonly capability: 'available' | 'unavailable';
+    readonly degraded?: boolean;
+    readonly recovery?: VolumeRecoveryState;
+    readonly acceptedDigest?: string;
+    readonly format?: TextureFormat;
+    readonly passCount?: number;
+    readonly sampleCount?: number;
+    readonly memoryBytes?: number;
+    readonly resourceFacts?: VolumetricFogResourceFacts;
+}
+export declare function inspectVolumetricFog(input: VolumetricFogInspectionInput): VolumetricFogInspection;
+//# sourceMappingURL=inspection.d.ts.map

package/dist/volume/inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection.d.ts","sourceRoot":"","sources":["../../src/volume/inspection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAE9D,MAAM,MAAM,6BAA6B,GAAG,KAAK,GAAG,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;AAE7F,MAAM,MAAM,0BAA0B,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,GAAG,YAAY,CAAC;AAElG,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,0BAA0B,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,gBAAgB,EAAE,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;IACnE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,0BAA0B,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,aAAa,EAAE,wBAAwB,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,sBAAsB,EAAE,wBAAwB,GAAG,SAAS,CAAC;CACvE;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,WAAW,GAAG,aAAa,CAAC;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,0BAA0B,CAAC;CACrD;AAUD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,4BAA4B,GAAG,uBAAuB,CA4BjG"}

package/dist/volume/passes.d.ts

@@ -0,0 +1,38 @@
+import type { GraphBuffer, GraphTextureView, RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import { type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame, RenderPipelineTarget, RenderPipelineTopology } from '../render-pipeline';
+import type { VolumetricFogResources } from './resources';
+import type { VolumeProjectorTuple } from './temporal';
+export declare const VOLUMETRIC_FOG_PASS_ORDER: readonly ["volume-inject", "volume-integrate", "volume-temporal", "volume-composite"];
+export interface VolumetricFogTopology {
+    readonly passes: readonly string[];
+    readonly resources: readonly string[];
+    readonly colorInput: 'linear-hdr';
+    readonly depthInput: 'scene-depth';
+    readonly lightKind?: 'directional' | 'point' | 'spot';
+    readonly lightEntity?: number;
+    readonly lightRevision?: number;
+    readonly projector?: Pick<VolumeProjectorTuple, 'guid' | 'generation' | 'revision'>;
+}
+export declare function volumetricFogTopology(enabled: boolean, selectedLight?: {
+    readonly lightKind: 'directional' | 'point' | 'spot';
+    readonly lightEntity: number;
+    readonly lightRevision: number;
+}): VolumetricFogTopology;
+export interface VolumetricFogPassInputs {
+    readonly resources: VolumetricFogResources;
+    readonly linearHdr: RenderPipelineTarget;
+    readonly sceneDepth: GraphTextureView;
+    readonly density: GraphTextureView;
+    readonly params: GraphBuffer;
+    readonly view: GraphBuffer;
+    readonly directionalShadow?: GraphTextureView;
+    readonly spotShadow: GraphTextureView;
+    readonly pointLights: GraphBuffer;
+    readonly spotLights: GraphBuffer;
+    readonly selectedLightKind: 'directional' | 'point' | 'spot';
+    readonly projector?: GraphTextureView;
+}
+export declare function addAuthoredVolumetricFogPasses(graph: RenderGraphBuilder<RenderPipelineFrame>, topology: RenderPipelineTopology, linearHdr: RenderPipelineTarget, sceneDepth: GraphTextureView, directionalShadow: GraphTextureView | undefined, spotShadow: GraphTextureView): Result<void, RenderGraphError>;
+export declare function addVolumetricFogPasses(graph: RenderGraphBuilder<RenderPipelineFrame>, inputs: VolumetricFogPassInputs): Result<void, RenderGraphError>;
+//# sourceMappingURL=passes.d.ts.map

package/dist/volume/passes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passes.d.ts","sourceRoot":"","sources":["../../src/volume/passes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AAWtC,OAAO,EAAM,KAAK,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAcxD,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAQ1D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,eAAO,MAAM,yBAAyB,uFAK5B,CAAC;AACX,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,YAAY,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,YAAY,GAAG,UAAU,CAAC,CAAC;CACrF;AACD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,aAAa,CAAC,EAAE;IACd,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC,GACA,qBAAqB,CAevB;AACD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,gBAAgB,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAqLD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,QAAQ,EAAE,sBAAsB,EAChC,SAAS,EAAE,oBAAoB,EAC/B,UAAU,EAAE,gBAAgB,EAC5B,iBAAiB,EAAE,gBAAgB,GAAG,SAAS,EAC/C,UAAU,EAAE,gBAAgB,GAC3B,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CA2BhC;AACD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,MAAM,EAAE,uBAAuB,GAC9B,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAiXhC"}

package/dist/volume/recovery.d.ts

@@ -0,0 +1,38 @@
+import type { VolumeProjectorTuple } from './temporal';
+export interface VolumeSelectedLightFacts {
+    readonly entity: number;
+    readonly kind: 'directional' | 'point' | 'spot';
+    readonly revision: number;
+    readonly shadowTile: number;
+    readonly pointLightEntity?: number;
+    readonly spotLightEntity?: number;
+    readonly projector?: VolumeProjectorTuple;
+}
+export interface VolumeRecoveryState {
+    readonly guid: string;
+    readonly generation: number;
+    readonly deviceEpoch: number;
+    readonly status: 'accepted' | 'candidate' | 'degraded' | 'recovering';
+    readonly candidateGeneration?: number;
+    readonly candidateDigest?: string;
+    readonly lkgGeneration?: number;
+    readonly candidateFailure?: 'submit-failed' | 'stale-generation' | 'missing-selected-light' | 'missing-shadow';
+    readonly selectedLight?: VolumeSelectedLightFacts;
+    readonly candidateSelectedLight?: VolumeSelectedLightFacts;
+}
+export type VolumeRecoveryEvent = {
+    readonly kind: 'submit-failed';
+} | {
+    readonly kind: 'device-lost';
+    readonly deviceEpoch: number;
+} | {
+    readonly kind: 'accepted';
+    readonly generation: number;
+};
+export declare function stageVolumetricFog(state: VolumeRecoveryState, candidate: {
+    readonly generation: number;
+    readonly digest: string;
+    readonly selectedLight?: VolumeSelectedLightFacts;
+}): VolumeRecoveryState;
+export declare function recoverVolumetricFog(state: VolumeRecoveryState, event: VolumeRecoveryEvent): VolumeRecoveryState;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/volume/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../../src/volume/recovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,YAAY,CAAC;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EACtB,eAAe,GACf,kBAAkB,GAClB,wBAAwB,GACxB,gBAAgB,CAAC;IACrB,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,CAAC;IAClD,QAAQ,CAAC,sBAAsB,CAAC,EAAE,wBAAwB,CAAC;CAC5D;AAED,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,mBAAmB,EAC1B,SAAS,EAAE;IACT,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,CAAC,EAAE,wBAAwB,CAAC;CACnD,GACA,mBAAmB,CAUrB;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,mBAAmB,GACzB,mBAAmB,CA6BrB"}

package/dist/volume/resources.d.ts

@@ -0,0 +1,57 @@
+import type { CompiledRenderGraphInfo, GraphTexture, GraphTextureView, RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
+import { type Result } from '@forgeax/engine-types';
+import type { RenderPipelineFrame } from '../render-pipeline';
+export declare const VOLUME_FROXEL_FORMAT: "rgba8unorm";
+export declare const VOLUME_HISTORY_FORMAT: "rgba16float";
+export declare const VOLUME_RESOLVED_FORMAT: "rgba16float";
+export declare const VOLUME_DEPTH_FORMAT: "r32float";
+export declare const VOLUME_PACKING_Z = 4;
+/** Renderer-owned parameter allocation shared by staging and inspection. */
+export declare const VOLUMETRIC_FOG_PARAMS_BYTES: number;
+export interface VolumetricFogExtent {
+    readonly width: number;
+    readonly height: number;
+    readonly depth: number;
+}
+/** Derive the renderer's high profile grid from the actual surface descriptor. */
+export declare function deriveVolumetricFogExtent(surface: {
+    readonly width: number;
+    readonly height: number;
+}, depth?: number, tileSize?: number): VolumetricFogExtent;
+/** Derive the 2D resolve extent from the same profile tile without a second profile. */
+export declare function deriveVolumetricFogResolvedExtent(surface: {
+    readonly width: number;
+    readonly height: number;
+}, froxelTileSize?: number): VolumetricFogExtent;
+export interface VolumetricFogResources {
+    readonly extent: VolumetricFogExtent;
+    readonly resolvedExtent: VolumetricFogExtent;
+    readonly froxel: GraphTexture;
+    readonly froxelView: GraphTextureView;
+    readonly resolved: GraphTexture;
+    readonly resolvedView: GraphTextureView;
+    readonly history: GraphTexture;
+    readonly historyView: GraphTextureView;
+    readonly temporal: GraphTexture;
+    readonly temporalView: GraphTextureView;
+}
+export interface VolumetricFogResourceFacts {
+    readonly generation: number;
+    readonly liveResourceCount: number;
+    readonly currentBytes: number;
+    readonly historyBytes: number;
+    readonly scratchBytes: number;
+    readonly bufferBytes: number;
+    readonly totalBytes: number;
+    readonly physicalResourceCount: number;
+    readonly sampleCount: number;
+    readonly resolvedPixelCount: number;
+}
+/** Project graph descriptors into the volume inspection without a second ledger. */
+export interface VolumetricFogResourceInspectionOptions {
+    /** Number of non-null parameter buffers retained by the frame owner. */
+    readonly parameterBufferCount?: number;
+}
+export declare function inspectVolumetricFogResources(graph: CompiledRenderGraphInfo, options?: VolumetricFogResourceInspectionOptions): VolumetricFogResourceFacts;
+export declare function createVolumetricFogResources(graph: RenderGraphBuilder<RenderPipelineFrame>, extent?: VolumetricFogExtent, resolvedExtent?: VolumetricFogExtent): Result<VolumetricFogResources, RenderGraphError>;
+//# sourceMappingURL=resources.d.ts.map

package/dist/volume/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../src/volume/resources.ts"],"names":[],"mappings":"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"}

package/dist/volume/temporal.d.ts

@@ -0,0 +1,35 @@
+export interface VolumeTemporalSignature {
+    readonly cameraRevision: number;
+    readonly fogRevision: number;
+    readonly lightRevision: number;
+    readonly densityGeneration: number;
+    readonly width: number;
+    readonly height: number;
+    readonly lightKind?: 'directional' | 'point' | 'spot';
+    readonly lightEntity?: number;
+    readonly pointLightEntity?: number;
+    readonly spotLightEntity?: number;
+    readonly projector?: VolumeProjectorTuple;
+    readonly lightShadowRevision?: number;
+}
+/** Accepted projector facts shared by surface and volume consumers. */
+export interface VolumeProjectorTuple {
+    readonly guid: string;
+    readonly generation: number;
+    readonly view: string;
+    readonly sampler: string;
+    readonly projection: string;
+    readonly revision: number;
+}
+export type VolumeTemporalResetReason = 'camera-cut' | 'fog-revision' | 'light-revision' | 'density-generation' | 'resize' | 'reprojection-out-of-screen' | 'reprojection-depth-discontinuity';
+export type VolumeTemporalReset = {
+    readonly reset: false;
+} | {
+    readonly reset: true;
+    readonly reason: VolumeTemporalResetReason;
+};
+export declare function resolveVolumeTemporalReset(previous: VolumeTemporalSignature, next: VolumeTemporalSignature, options?: {
+    readonly taaEnabled?: boolean;
+    readonly reprojection?: 'out-of-screen' | 'depth-discontinuity';
+}): VolumeTemporalReset;
+//# sourceMappingURL=temporal.d.ts.map

package/dist/volume/temporal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../../src/volume/temporal.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,OAAO,GAAG,MAAM,CAAC;IACtD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,uEAAuE;AACvE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,yBAAyB,GACjC,YAAY,GACZ,cAAc,GACd,gBAAgB,GAChB,oBAAoB,GACpB,QAAQ,GACR,4BAA4B,GAC5B,kCAAkC,CAAC;AAEvC,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAA;CAAE,CAAC;AAEzE,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,uBAAuB,EACjC,IAAI,EAAE,uBAAuB,EAC7B,OAAO,GAAE;IACP,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,eAAe,GAAG,qBAAqB,CAAC;CAC5D,GACL,mBAAmB,CA2CrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-render",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Canonical ECS render schemas and renderer boundary.",
   "private": false,
   "type": "module",
@@ -37,27 +37,27 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-assets-runtime": "0.1.19",
-    "@forgeax/engine-audio-webaudio": "0.1.19",
-    "@forgeax/engine-codec": "0.1.19",
-    "@forgeax/engine-ecs": "0.1.19",
-    "@forgeax/engine-geometry": "0.1.19",
-    "@forgeax/engine-graphics-extras": "0.1.19",
-    "@forgeax/engine-math": "0.1.19",
-    "@forgeax/engine-pack": "0.1.19",
-    "@forgeax/engine-plugin": "0.1.19",
-    "@forgeax/engine-profiler": "0.1.19",
-    "@forgeax/engine-render-graph": "0.1.19",
-    "@forgeax/engine-rhi": "0.1.19",
-    "@forgeax/engine-scene": "0.1.19",
-    "@forgeax/engine-shader": "0.1.19",
-    "@forgeax/engine-skinning": "0.1.19",
-    "@forgeax/engine-types": "0.1.19"
+    "@forgeax/engine-assets-runtime": "0.1.21",
+    "@forgeax/engine-audio-webaudio": "0.1.21",
+    "@forgeax/engine-codec": "0.1.21",
+    "@forgeax/engine-ecs": "0.1.21",
+    "@forgeax/engine-geometry": "0.1.21",
+    "@forgeax/engine-graphics-extras": "0.1.21",
+    "@forgeax/engine-math": "0.1.21",
+    "@forgeax/engine-pack": "0.1.21",
+    "@forgeax/engine-plugin": "0.1.21",
+    "@forgeax/engine-profiler": "0.1.21",
+    "@forgeax/engine-render-graph": "0.1.21",
+    "@forgeax/engine-rhi": "0.1.21",
+    "@forgeax/engine-scene": "0.1.21",
+    "@forgeax/engine-shader": "0.1.21",
+    "@forgeax/engine-skinning": "0.1.21",
+    "@forgeax/engine-types": "0.1.21"
   },
   "devDependencies": {
-    "@forgeax/engine-rhi-null": "0.1.19",
-    "@forgeax/engine-rhi-webgpu": "0.1.19",
-    "@forgeax/engine-vite-plugin-shader": "0.1.19"
+    "@forgeax/engine-rhi-null": "0.1.21",
+    "@forgeax/engine-rhi-webgpu": "0.1.21",
+    "@forgeax/engine-vite-plugin-shader": "0.1.21"
   },
   "forgeax": {
     "metrics": {

package/src/__tests__/bloom-exact-zero.unit.test.ts

@@ -1,9 +1,13 @@
 import { readFileSync } from 'node:fs';
+import { mat4, vec3 } from '@forgeax/engine-math';
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type { RhiDevice } from '@forgeax/engine-rhi';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { ok } from '@forgeax/engine-types';
 import { beforeAll, describe, expect, it } from 'vitest';
+import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
+import { deriveStandardTopologyInput } from '../pipeline/standard-lighting/topology';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
 import { standardPipeline } from '../pipeline/standard-pipeline';
 import { inspectStandardBloomGraph, STANDARD_BLOOM_TARGET_SPEC } from '../pipeline/standard-post';
 import { DEFAULT_STANDARD_PROFILE, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
@@ -19,11 +23,11 @@ beforeAll(async () => {
   device = result.value;
 });
 
-function topology(lighting: 'direct' | 'clustered', bloom: 'off' | 'on'): RenderPipelineTopology {
+function topology(bloom: 'off' | 'on'): RenderPipelineTopology {
   return {
     pipelineId: STANDARD_PIPELINE_ID,
-    standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting },
-    config: lighting === 'clustered' ? { ssao: { enabled: false } } : undefined,
+    standardProfile: DEFAULT_STANDARD_PROFILE,
+    config: { ssao: { enabled: false } },
     surface: {
       width: 640,
       height: 360,
@@ -32,15 +36,15 @@ function topology(lighting: 'direct' | 'clustered', bloom: 'off' | 'on'): Render
     },
     camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom },
     shadow: {
-      mapSize: 64,
-      cascadeCount: 1,
+      directional: { mapSize: 64, cascadeCount: 1 },
+      spotMapSize: 64,
       pointCount: 0,
       pointFaceSize: 64,
       spotCount: 0,
     },
     lane: {
-      compute: lighting === 'clustered',
-      storageBuffer: lighting === 'clustered',
+      compute: true,
+      storageBuffer: true,
       multisample: false,
       maxColorAttachments: 8,
     },
@@ -49,15 +53,43 @@ function topology(lighting: 'direct' | 'clustered', bloom: 'off' | 'on'): Render
   };
 }
 
-function inspect(lighting: 'direct' | 'clustered', bloom: 'off' | 'on') {
+function clusteredStandardLighting() {
+  const prepared = prepareStandardLighting({
+    directional: undefined,
+    local: [{ kind: 'point' as const, shadowed: false, position: vec3.create(0, 0, -4), range: 2 }],
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: DEFAULT_STANDARD_PROFILE.lightCount,
+    renderPath: 'forward',
+  });
+  if (!prepared.ok) throw prepared.error;
+  const transport = selectStandardClusterTransport(
+    { compute: true, storageBuffer: true, membershipPipelineReady: true },
+    prepared.value,
+  );
+  if (!transport.ok) throw transport.error;
+  const lighting = deriveStandardTopologyInput({
+    kind: 'clustered',
+    prepared: prepared.value,
+    transport: transport.value,
+  });
+  if (!lighting.ok) throw lighting.error;
+  return lighting.value;
+}
+
+function inspect(bloom: 'off' | 'on') {
   const graph = new RenderGraphBuilder<RenderPipelineFrame>();
   const built = standardPipeline.build(
     {
       graph,
+      standardLighting: clusteredStandardLighting(),
       projectGpuDriven: () => ok(undefined),
       contributeFeatures: () => ok(undefined),
     },
-    topology(lighting, bloom),
+    topology(bloom),
   );
   if (!built.ok) throw built.error;
   const compiled = graph.compile({ device, surfaceSize: { width: 640, height: 360 } });
@@ -66,11 +98,8 @@ function inspect(lighting: 'direct' | 'clustered', bloom: 'off' | 'on') {
 }
 
 describe('Standard Bloom exact-zero topology', () => {
-  it.each([
-    'direct',
-    'clustered',
-  ] as const)('%s Bloom off declares no Bloom targets or passes', (lighting) => {
-    const info = inspect(lighting, 'off');
+  it('Bloom off declares no Bloom targets or passes', () => {
+    const info = inspect('off');
     const bloomPasses = info.passes.filter((pass) => pass.name.startsWith('bloom-'));
     const bloomResources = info.resources.filter((resource) => resource.label.startsWith('bloom-'));
     expect(bloomPasses).toHaveLength(0);
@@ -120,8 +149,8 @@ describe('Standard Bloom exact-zero topology', () => {
   });
 
   it('keeps one shared Bloom chain when enabled', () => {
-    for (const lighting of ['direct', 'clustered'] as const) {
-      const info = inspect(lighting, 'on');
+    {
+      const info = inspect('on');
       expect(inspectStandardBloomGraph(info)).toEqual({
         status: 'valid',
         targetCount: 4,
@@ -147,7 +176,7 @@ describe('Standard Bloom exact-zero topology', () => {
   });
 
   it('fails closed when a canonical Bloom descriptor drifts', () => {
-    const info = inspect('direct', 'on');
+    const info = inspect('on');
     const drifted = {
       ...info,
       resources: info.resources.map((resource) =>
@@ -171,7 +200,7 @@ describe('Standard Bloom exact-zero topology', () => {
   });
 
   it('rejects a graph with a missing canonical Bloom target', () => {
-    const info = inspect('direct', 'on');
+    const info = inspect('on');
     const drifted = {
       ...info,
       resources: info.resources.filter(
@@ -187,7 +216,7 @@ describe('Standard Bloom exact-zero topology', () => {
   });
 
   it('rejects a graph with a missing canonical Bloom pass', () => {
-    const info = inspect('direct', 'on');
+    const info = inspect('on');
     const drifted = {
       ...info,
       passes: info.passes.filter((pass) => pass.name !== 'bloom-blur-h'),

package/src/__tests__/bloom-lifecycle.integration.test.ts

@@ -1,9 +1,13 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
 import { RenderGraphBuilder } from '@forgeax/engine-render-graph';
 import type { RhiDevice } from '@forgeax/engine-rhi';
 import { rhi } from '@forgeax/engine-rhi-null';
 import { ok } from '@forgeax/engine-types';
 import { beforeAll, describe, expect, it } from 'vitest';
 import { DeviceScope, LifecycleTransaction } from '../device/device-scope';
+import { prepareStandardLighting } from '../pipeline/standard-lighting/prepare';
+import { deriveStandardTopologyInput } from '../pipeline/standard-lighting/topology';
+import { selectStandardClusterTransport } from '../pipeline/standard-lighting/transport';
 import { standardPipeline } from '../pipeline/standard-pipeline';
 import { DEFAULT_STANDARD_PROFILE, STANDARD_PIPELINE_ID } from '../pipeline/standard-profile';
 import type { RenderPipelineFrame, RenderPipelineTopology } from '../render-pipeline';
@@ -18,11 +22,11 @@ beforeAll(async () => {
   device = result.value;
 });
 
-function build(bloom: 'off' | 'on', lighting: 'direct' | 'clustered') {
+function build(bloom: 'off' | 'on') {
   const topology: RenderPipelineTopology = {
     pipelineId: STANDARD_PIPELINE_ID,
-    standardProfile: { ...DEFAULT_STANDARD_PROFILE, lighting },
-    config: lighting === 'clustered' ? { ssao: { enabled: false } } : undefined,
+    standardProfile: DEFAULT_STANDARD_PROFILE,
+    config: { ssao: { enabled: false } },
     surface: {
       width: 320,
       height: 180,
@@ -31,15 +35,15 @@ function build(bloom: 'off' | 'on', lighting: 'direct' | 'clustered') {
     },
     camera: { tonemap: 'aces-filmic', antialias: 'fxaa', bloom },
     shadow: {
-      mapSize: 64,
-      cascadeCount: 1,
+      directional: { mapSize: 64, cascadeCount: 1 },
+      spotMapSize: 64,
       pointCount: 0,
       pointFaceSize: 64,
       spotCount: 0,
     },
     lane: {
-      compute: lighting === 'clustered',
-      storageBuffer: lighting === 'clustered',
+      compute: true,
+      storageBuffer: true,
       multisample: false,
       maxColorAttachments: 8,
     },
@@ -47,9 +51,33 @@ function build(bloom: 'off' | 'on', lighting: 'direct' | 'clustered') {
     gpuDrivenTopologySignature: '',
   };
   const graph = new RenderGraphBuilder<RenderPipelineFrame>();
+  const prepared = prepareStandardLighting({
+    directional: undefined,
+    local: [{ kind: 'point' as const, shadowed: false, position: vec3.create(0, 0, -4), range: 2 }],
+    view: mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]),
+    projection: mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100),
+    near: 0.1,
+    far: 100,
+    grid: { x: 4, y: 3, z: 4 },
+    lightCount: DEFAULT_STANDARD_PROFILE.lightCount,
+    renderPath: 'forward',
+  });
+  if (!prepared.ok) throw prepared.error;
+  const transport = selectStandardClusterTransport(
+    { compute: true, storageBuffer: true, membershipPipelineReady: true },
+    prepared.value,
+  );
+  if (!transport.ok) throw transport.error;
+  const standardLighting = deriveStandardTopologyInput({
+    kind: 'clustered',
+    prepared: prepared.value,
+    transport: transport.value,
+  });
+  if (!standardLighting.ok) throw standardLighting.error;
   const built = standardPipeline.build(
     {
       graph,
+      standardLighting: standardLighting.value,
       projectGpuDriven: () => ok(undefined),
       contributeFeatures: () => ok(undefined),
     },
@@ -71,10 +99,10 @@ function bloomSummary(info: ReturnType<typeof build>) {
 }
 
 describe('Standard Bloom lifecycle contract', () => {
-  it.each(['direct', 'clustered'] as const)('supports on -> off -> on for %s', (lighting) => {
-    const on = bloomSummary(build('on', lighting));
-    const off = bloomSummary(build('off', lighting));
-    const recovered = bloomSummary(build('on', lighting));
+  it('supports on -> off -> on for the Standard clustered graph', () => {
+    const on = bloomSummary(build('on'));
+    const off = bloomSummary(build('off'));
+    const recovered = bloomSummary(build('on'));
     expect(on.passes).toHaveLength(4);
     expect(on.resources.length).toBeGreaterThan(0);
     expect(off).toEqual({ passes: [], resources: [] });
@@ -82,7 +110,7 @@ describe('Standard Bloom lifecycle contract', () => {
   });
 
   it('keeps post order scene -> Bloom -> output transform -> FXAA -> debug', () => {
-    const names = build('on', 'clustered').passes.map((pass) => pass.name);
+    const names = build('on').passes.map((pass) => pass.name);
     const order = [
       'forward',
       'bloom-bright',
@@ -117,7 +145,7 @@ describe('Standard Bloom lifecycle contract', () => {
   });
 
   it('FALSIFY rejects an injected Bloom contribution on the off path', () => {
-    const off = bloomSummary(build('off', 'direct'));
+    const off = bloomSummary(build('off'));
     const injected = { ...off, passes: ['bloom-falsified'] };
     expect(injected).not.toEqual({ passes: [], resources: [] });
     expect(off).toEqual({ passes: [], resources: [] });

package/src/__tests__/camera-target-consumption.unit.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest';
+import { type CameraTargetCandidate, selectCameraTargetViews } from '../render-system-extract';
+import type { RenderTargetDescriptor } from '../targets/contracts';
+import { createRenderTargetOwner } from '../targets/owner';
+
+const descriptor: RenderTargetDescriptor = {
+  shape: '2d',
+  width: 16,
+  height: 16,
+  format: 'rgba8unorm',
+  mipLevels: 1,
+  sampleCount: 1,
+  sampled: true,
+  readback: false,
+};
+
+function targets() {
+  const owner = createRenderTargetOwner({ rendererId: Symbol('renderer'), initialGeneration: 1 });
+  const first = owner.create(descriptor);
+  const second = owner.create(descriptor);
+  if (!first.ok) throw first.error;
+  if (!second.ok) throw second.error;
+  return [first.value, second.value] as const;
+}
+
+describe('Camera target consumption', () => {
+  it('keeps display authority separate and applies stable auxiliary ordering and budget', () => {
+    const [first, second] = targets();
+    const cameras: CameraTargetCandidate[] = [
+      { worldId: 2, entityKey: 20, target: first, requestVersion: 1, update: 'once' },
+      { worldId: 1, entityKey: 30, target: second, requestVersion: 1, update: 'continuous' },
+      { worldId: 1, entityKey: 10, requestVersion: 0, update: 'continuous' },
+    ];
+    const selected = selectCameraTargetViews(cameras, { displayEntityKey: 10, budget: 1 });
+    expect(selected.display?.entityKey).toBe(10);
+    expect(selected.auxiliary.map((camera) => camera.entityKey)).toEqual([30]);
+    expect(selected.rejected).toHaveLength(1);
+    expect(selected.rejected[0]?.reason).toBe('budget');
+  });
+
+  it('rejects a target camera selected as display and duplicate target producers', () => {
+    const [first] = targets();
+    const cameras: CameraTargetCandidate[] = [
+      { worldId: 1, entityKey: 3, target: first, requestVersion: 1, update: 'once' },
+      { worldId: 1, entityKey: 4, target: first, requestVersion: 2, update: 'once' },
+    ];
+    const selected = selectCameraTargetViews(cameras, { displayEntityKey: 3, budget: 2 });
+    expect(selected.display).toBeUndefined();
+    expect(selected.rejected.map((entry) => entry.reason)).toEqual(
+      expect.arrayContaining(['display-target', 'duplicate-target']),
+    );
+  });
+});

package/src/__tests__/cluster-binner.unit.test.ts

@@ -0,0 +1,35 @@
+import { mat4, vec3 } from '@forgeax/engine-math';
+import { describe, expect, it } from 'vitest';
+import { bin, createClusterBinScratch } from '../cluster-binner';
+
+describe('cluster binner structured boundaries', () => {
+  it('returns a complete structured overflow without truncating output', () => {
+    const grid = { x: 4, y: 3, z: 4 };
+    const view = mat4.lookAt(mat4.create(), [0, 0, 0], [0, 0, -1], [0, 1, 0]);
+    const projection = mat4.perspective(mat4.create(), Math.PI / 3, 1, 0.1, 100);
+    const clusterGrid = new Uint32Array(grid.x * grid.y * grid.z * 2).fill(7);
+    const lightIndexList = new Uint32Array(1).fill(9);
+    const result = bin(
+      [{ position: vec3.create(0, 0, -4), range: 100 }],
+      view,
+      projection,
+      grid,
+      0.1,
+      100,
+      clusterGrid,
+      lightIndexList,
+      0,
+      createClusterBinScratch(),
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('index-overflow');
+    expect(result.error.expected).toContain('writeCount <= 0');
+    expect(result.error.hint).toContain('reduce lights');
+    expect(result.error.detail.actual).toBeGreaterThan(0);
+    expect(result.error.detail.capacity).toBe(0);
+    expect(Array.from(clusterGrid)).toEqual(new Array(clusterGrid.length).fill(0));
+    expect(Array.from(lightIndexList)).toEqual([9]);
+  });
+});