@forgeax/engine-vfx-render 0.1.7 → 0.1.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-vfx-render",
-  "version": "0.1.7",
+  "version": "0.1.19",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,13 +22,13 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-assets-runtime": "0.1.7",
-    "@forgeax/engine-ecs": "0.1.7",
-    "@forgeax/engine-math": "0.1.7",
-    "@forgeax/engine-render": "0.1.7",
-    "@forgeax/engine-scene": "0.1.7",
-    "@forgeax/engine-types": "0.1.7",
-    "@forgeax/engine-vfx": "0.1.7"
+    "@forgeax/engine-assets-runtime": "0.1.19",
+    "@forgeax/engine-ecs": "0.1.19",
+    "@forgeax/engine-math": "0.1.19",
+    "@forgeax/engine-render": "0.1.19",
+    "@forgeax/engine-scene": "0.1.19",
+    "@forgeax/engine-types": "0.1.19",
+    "@forgeax/engine-vfx": "0.1.19"
   },
   "devDependencies": {},
   "forgeax": {

package/src/__tests__/fog-producer.integration.test.ts

@@ -21,9 +21,11 @@ describe('VFX Fog producer contract', () => {
       );
       expect(source, name).toMatch(/#import\s+forgeax_view::fog::\{[^}]*\bapply_fog\b[^}]*\}/);
       expect(count(source, /\bapply_fog\s*\(/g), name).toBe(1);
-      expect(count(source, /\bFogRay\s*\(/g), name).toBe(1);
-      expect(source, name).toMatch(/world[_A-Za-z]*position|worldPosition/);
-      expect(source, name).toMatch(/ray[_A-Za-z]*distance|distance/);
+      expect(count(source, /\bFogRay\s*\(/g) + count(source, /\bfogRayFromNdc\s*\(/g), name).toBe(
+        1,
+      );
+      expect(source, name).toMatch(/world[_A-Za-z]*position|worldPosition|fogRayFromNdc/);
+      expect(source, name).toMatch(/ray[_A-Za-z]*distance|distance|fogRayFromNdc/);
       expect(source, name).toMatch(/\.a\b|alpha/);
       expect(source, name).not.toMatch(/texture_3d|raymarch/i);
     }

package/src/__tests__/gpu-host.integration.test.ts

@@ -50,7 +50,10 @@ describe('GPU VFX public host', () => {
     const world = new World();
     const lookups: string[] = [];
     class StatefulAssets {
-      readonly material: MaterialAsset = { kind: 'material', values: {} };
+      readonly material: MaterialAsset = {
+        kind: 'material',
+        passes: [{ name: 'particle-billboard', program: { module: 'custom-depth' } }],
+      };
       readonly loaders = { registerPackLoader: () => {} };
 
       lookup<T extends Asset = Asset>(guid: string): T | undefined {
@@ -118,14 +121,29 @@ describe('GPU VFX public host', () => {
         frameNumber: 1,
       } as never,
       {
-        targets: [],
+        targets: [
+          { name: 'scene-color', kind: 'color', format: 'rgba8unorm-srgb', sampleCount: 1 },
+          { name: 'scene-depth', kind: 'depth', format: 'depth24plus', sampleCount: 1 },
+        ],
         caps: {},
         frame: { frameNumber: 1 },
         generation: 1,
+        materialShaderBindingContract: () => 'group-0-resource',
       } as never,
     );
     expect(planned.ok).toBe(true);
     expect(lookups).toEqual(['material-guid']);
+    if (planned.ok) {
+      expect(planned.value.resources).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            kind: 'graphics-bindings',
+            values: expect.objectContaining({ sceneDepthBinding: 0 }),
+            logicalTargets: { sceneDepth: 'scene-depth' },
+          }),
+        ]),
+      );
+    }
     await host.detachWorld({ world });
   });
 

package/src/__tests__/particle-resources.unit.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from 'vitest';
 import {
   canonicalMeshVertices,
   particleMaterialPass,
+  particleMaterialSceneDepthBinding,
   particleMaterialUsesBindings,
 } from '../feature/particle-resources.js';
 
@@ -53,6 +54,14 @@ describe('particle material pass', () => {
     });
   });
 
+  it('maps renderer shader contracts to their scene-depth binding slots', () => {
+    expect(particleMaterialSceneDepthBinding('group-0-resource')).toBe(0);
+    expect(particleMaterialSceneDepthBinding('view-and-scene-depth')).toBe(1);
+    expect(particleMaterialSceneDepthBinding('group-0')).toBeUndefined();
+    expect(particleMaterialSceneDepthBinding('view-only')).toBeUndefined();
+    expect(particleMaterialSceneDepthBinding('render-material')).toBeUndefined();
+  });
+
   it('does not mistake an ordinary Forward pass for a particle shader', () => {
     const material: MaterialAsset = {
       kind: 'material',

package/src/__tests__/stage-plan.integration.test.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import type { RenderFeaturePlan } from '@forgeax/engine-render';
+import { createSceneDataCatalog, type RenderFeaturePlan } from '@forgeax/engine-render';
 import type { VfxGpuTickIntent } from '@forgeax/engine-vfx';
 import { describe, expect, it } from 'vitest';
 import { freezeRenderFeaturePlan } from '../../../render/src/features/plan';
@@ -108,6 +108,12 @@ describe('VFX managed stage execution seam', () => {
           { name: 'scene-color', kind: 'color', format: 'rgba16float', sampleCount: 1 },
           { name: 'scene-depth', kind: 'depth', format: 'depth24plus', sampleCount: 1 },
         ],
+        sceneData: createSceneDataCatalog({
+          featureIdentity: feature.identity,
+          generation: 1,
+          planIdentity: `${feature.identity}:1`,
+          rgba16floatRenderable: true,
+        }),
       },
     );
 

package/src/feature/gpu-particle-feature.ts

@@ -25,6 +25,7 @@ import {
   createTopologyResourcePlan,
   PARTICLE_SHADER_IDENTIFIERS,
   particleMaterialPass,
+  particleMaterialSceneDepthBinding,
   particleMaterialUsesBindings,
 } from './particle-resources.js';
 import type { VfxStagePlanObservation, VfxValidatedStagePlan } from './stage-plan.js';
@@ -346,6 +347,11 @@ export function gpuParticleRenderFeature(
   return {
     identity: IDENTITY,
     requiredCapabilities: ['compute', 'indirectDrawing'],
+    // Generated emitter programs are first-use assets. They must hand a
+    // WebGPU module to the prepared feature pipeline without waiting for the
+    // diagnostic-only getCompilationInfo() round trip; pipeline creation still
+    // validates the module before the pass is submitted.
+    shaderModuleMode: 'immediate',
     requiredMaterialShaders: Object.values(PARTICLE_SHADER_IDENTIFIERS),
     extract: (context) => {
       const extracted: ExtractedWorld[] = [];
@@ -552,6 +558,14 @@ export function gpuParticleRenderFeature(
             const submesh =
               renderer.kind === 'mesh' ? mesh?.submeshes[renderer.submesh ?? 0] : undefined;
             const indexFormat = mesh?.indices instanceof Uint32Array ? 'uint32' : 'uint16';
+            const sceneDepthBinding = isBillboard
+              ? particleMaterialSceneDepthBinding(
+                  context.materialShaderBindingContract?.(materialPass.shader) ??
+                    (materialPass.shader === PARTICLE_SHADER_IDENTIFIERS.billboard
+                      ? 'view-and-scene-depth'
+                      : undefined),
+                )
+              : undefined;
             const instances = `${rendererPrefix}.instances`;
             const history = `${rendererPrefix}.history`;
             const projectionRuntime = `${rendererPrefix}.runtime`;
@@ -690,9 +704,9 @@ export function gpuParticleRenderFeature(
                   group: 0,
                   runtime: projectionRuntime,
                   instances,
-                  ...(isBillboard ? { sceneDepthBinding: 1 } : {}),
+                  ...(sceneDepthBinding === undefined ? {} : { sceneDepthBinding }),
                 },
-                ...(isBillboard && depthTarget !== undefined
+                ...(sceneDepthBinding !== undefined && depthTarget !== undefined
                   ? { logicalTargets: { sceneDepth: depthTarget.name } }
                   : {}),
               },
@@ -784,7 +798,7 @@ export function gpuParticleRenderFeature(
                       depthStoreOp: 'store',
                     },
                   }),
-              ...(isBillboard && depthTarget !== undefined
+              ...(sceneDepthBinding !== undefined && depthTarget !== undefined
                 ? { sampledTargets: [depthTarget.name] }
                 : {}),
               draws: [

package/src/feature/particle-resources.ts

@@ -1,3 +1,4 @@
+import type { RenderFeatureMaterialShaderBindingContract } from '@forgeax/engine-render';
 import {
   err,
   type MaterialAsset,
@@ -161,6 +162,23 @@ export function particleMaterialUsesBindings(material: MaterialAsset | undefined
   return (material?.parameters?.length ?? 0) > 0;
 }
 
+/**
+ * Return the scene-depth binding slot required by a particle material shader.
+ *
+ * Custom particle shaders historically bind only the sampled depth resource at
+ * group(0)/binding(0), while the renderer-owned billboard shader also consumes
+ * the view UBO at binding(0) and therefore uses depth at binding(1). Keep this
+ * choice derived from the renderer contract instead of assuming every
+ * billboard has the built-in layout.
+ */
+export function particleMaterialSceneDepthBinding(
+  contract: RenderFeatureMaterialShaderBindingContract | undefined,
+): 0 | 1 | undefined {
+  if (contract === 'group-0-resource') return 0;
+  if (contract === 'view-and-scene-depth') return 1;
+  return undefined;
+}
+
 function floatAttribute(value: ArrayBuffer | Float32Array | Uint16Array | undefined): Float32Array {
   if (value instanceof Float32Array) return value;
   if (value instanceof Uint16Array) return Float32Array.from(value);

package/src/shaders/beam.wgsl

@@ -1,5 +1,5 @@
 #define_import_path forgeax::vfx-render.particles.beam
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
+#import forgeax_view::common::{View, FogViewParams, FogRay, view, fogRayFromNdc}
 #import forgeax_view::fog::{apply_fog}
 
 struct BeamInput {
@@ -15,29 +15,6 @@ struct VertexOutput {
   @location(1) clip_position: vec3<f32>,
 }
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 @vertex
 fn vs_main(input: BeamInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
   let corners = array<vec2<f32>, 6>(

package/src/shaders/billboard.wgsl

@@ -1,5 +1,5 @@
 #define_import_path forgeax::vfx-render.particles.billboard
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
+#import forgeax_view::common::{View, FogViewParams, FogRay, view, fogRayFromNdc}
 #import forgeax_view::fog::{apply_fog}
 
 @group(0) @binding(1) var scene_depth: texture_depth_2d;
@@ -51,29 +51,6 @@ fn softParticle(position: vec4<f32>, alpha: f32, fadeDistance: f32) -> f32 {
   return alpha * softParticleFactor(position.z, sceneDepth, fadeDistance);
 }
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 struct VertexInput {
   @location(0) position: vec3<f32>,
   @location(1) right: vec2<f32>,

package/src/shaders/mesh.wgsl

@@ -1,5 +1,5 @@
 #define_import_path forgeax::vfx-render.particles.mesh
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
+#import forgeax_view::common::{View, FogViewParams, FogRay, view, fogRayFromNdc}
 #import forgeax_view::fog::{apply_fog}
 
 struct VertexOutput {
@@ -26,29 +26,6 @@ struct VertexInput {
   @location(11) surface: vec4<f32>,
 };
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 @vertex
 fn vs_main(input: VertexInput) -> VertexOutput {
   var output: VertexOutput;

package/src/shaders/ribbon.wgsl

@@ -1,5 +1,5 @@
 #define_import_path forgeax::vfx-render.particles.ribbon
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
+#import forgeax_view::common::{View, FogViewParams, FogRay, view, fogRayFromNdc}
 #import forgeax_view::fog::{apply_fog}
 
 struct SegmentInput {
@@ -15,29 +15,6 @@ struct VertexOutput {
   @location(1) clip_position: vec3<f32>,
 }
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 @vertex
 fn vs_main(input: SegmentInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
   let corners = array<vec2<f32>, 6>(

package/src/shaders/trail.wgsl

@@ -1,5 +1,5 @@
 #define_import_path forgeax::vfx-render.particles.trail
-#import forgeax_view::common::{View, FogViewParams, FogRay, view}
+#import forgeax_view::common::{View, FogViewParams, FogRay, view, fogRayFromNdc}
 #import forgeax_view::fog::{apply_fog}
 
 struct SegmentInput {
@@ -15,29 +15,6 @@ struct VertexOutput {
   @location(1) clip_position: vec3<f32>,
 }
 
-fn fogWorldPoint(ndc: vec3<f32>) -> vec3<f32> {
-  let homogeneous = view.inverseViewProj * vec4<f32>(ndc, 1.0);
-  let divisor = select(1.0, homogeneous.w, abs(homogeneous.w) > 0.000001);
-  return homogeneous.xyz / divisor;
-}
-
-fn fogRayFromNdc(ndc: vec3<f32>) -> FogRay {
-  let worldPosition = fogWorldPoint(ndc);
-  let nearPosition = fogWorldPoint(vec3<f32>(ndc.xy, 0.0));
-  let farPosition = fogWorldPoint(vec3<f32>(ndc.xy, 1.0));
-  let perspective = view.temporalProjection.z < 0.5;
-  let perspectiveVector = worldPosition - view.cameraPos;
-  let orthographicVector = farPosition - nearPosition;
-  let direction = normalize(select(orthographicVector, perspectiveVector, perspective));
-  let origin = select(nearPosition, view.cameraPos, perspective);
-  let ray_distance = select(
-    max(dot(worldPosition - nearPosition, direction), 0.0),
-    length(perspectiveVector),
-    perspective,
-  );
-  return FogRay(origin, direction, ray_distance);
-}
-
 @vertex
 fn vs_main(input: SegmentInput, @builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
   let corners = array<vec2<f32>, 6>(