@forgeax/engine-render 0.1.33 → 0.1.34

package/src/record/view-ubo.ts

@@ -21,7 +21,7 @@ import type { TemporalView as LegacyTemporalView } from '../temporal/temporal-vi
 import type { TemporalView } from '../temporal/view';
 import { computeProjectionMatrix, computeViewMatrix } from './helpers';
 
-export const VIEW_UNIFORM_BYTES = 960;
+export const VIEW_UNIFORM_BYTES = 1024;
 export const POINTS_LINES_VIEW_BYTES = 160;
 export const POINTS_LINES_VIEW_SLOT_STRIDE = 256;
 export const POINTS_LINES_VIEW_SLOT_COUNT = 1024;
@@ -129,7 +129,9 @@ export function writePointsLinesViewUbo(
  *   folded from standalone binding 9 to fix WebGL2 fragment uniform-buffer
  *   overflow; lane N = spot with shadowAtlasTile === N, 16 f32 / lane,
  *   16 B-aligned at byte 528 = float 132).
- *   [236..239] ssrParams (maxDistance, thickness, maxRoughness, enabled).
+ *   [228..231] temporalProjection (near, far, orthographic, cloud solar
+ *   transmittance), [232..235] temporalPreviousCameraPos, [236..239]
+ *   ssrParams (maxDistance, thickness, maxRoughness, enabled).
  *
  * @internal
  */
@@ -142,6 +144,13 @@ export function writeViewUbo(
   spotShadowSnapshots: readonly SpotLightSnapshot[],
   temporalOrOffset?: TemporalView | LegacyTemporalView | number,
   projectorSpotIndex?: number,
+  cloudShadowProjection?: {
+    readonly origin: readonly [number, number, number];
+    readonly right: readonly [number, number, number];
+    readonly up: readonly [number, number, number];
+    readonly range: number;
+    readonly lowSun: boolean;
+  },
 ): void {
   const byteOffset = typeof temporalOrOffset === 'number' ? temporalOrOffset : 0;
   const resolvedTemporal = typeof temporalOrOffset === 'number' ? undefined : temporalOrOffset;
@@ -162,7 +171,7 @@ export function writeViewUbo(
   const mainProjection = mat4.create();
   mat4.multiply(mainProjection, jitteredProjection, viewMatrix);
 
-  const VIEW_PAYLOAD_FLOATS = 240;
+  const VIEW_PAYLOAD_FLOATS = 256;
   const viewPayload = new Float32Array(VIEW_PAYLOAD_FLOATS);
   for (let i = 0; i < 16; i++) viewPayload[i] = mainProjection[i] ?? 0;
   viewPayload[16] = light.direction[0] ?? 0;
@@ -229,6 +238,20 @@ export function writeViewUbo(
     viewPayload[238] = ssr.maxRoughness;
     viewPayload[239] = 1;
   }
+  if (cloudShadowProjection !== undefined) {
+    viewPayload[240] = cloudShadowProjection.origin[0] ?? 0;
+    viewPayload[241] = cloudShadowProjection.origin[1] ?? 0;
+    viewPayload[242] = cloudShadowProjection.origin[2] ?? 0;
+    viewPayload[244] = cloudShadowProjection.right[0] ?? 0;
+    viewPayload[245] = cloudShadowProjection.right[1] ?? 0;
+    viewPayload[246] = cloudShadowProjection.right[2] ?? 0;
+    viewPayload[248] = cloudShadowProjection.up[0] ?? 0;
+    viewPayload[249] = cloudShadowProjection.up[1] ?? 0;
+    viewPayload[250] = cloudShadowProjection.up[2] ?? 0;
+    viewPayload[252] = cloudShadowProjection.range;
+    viewPayload[253] = cloudShadowProjection.lowSun ? 0 : 1;
+    viewPayload[254] = cloudShadowProjection.lowSun ? 1 : 0;
+  }
   // splitPlanes at [108..123] (four vec4 lanes: split/world texel/depth span/reserved).
   if (lights.splitPlanes !== undefined) {
     for (let s = 0; s < 4; s++) {

package/src/record/volume-params.ts

@@ -0,0 +1,225 @@
+import type { World } from '@forgeax/engine-ecs';
+import { vec3 } from '@forgeax/engine-math';
+import { type Buffer, RhiError } from '@forgeax/engine-rhi';
+import { GPU_BUFFER_USAGE_COPY_DST, GPU_BUFFER_USAGE_UNIFORM } from '../gpu-usage';
+import type { SpotLightProjectorFrameContext, VolumetricFogFrameContext } from '../render-contract';
+import type { ExtractedLights, ExtractedVolumetricFog } from '../render-system-extract';
+import { VOLUMETRIC_FOG_PARAMS_BYTES } from '../volume/resources';
+import type { RenderFrameState } from './frame-snapshot';
+import type { RenderSystemInternals } from './render-context';
+
+type VolumetricFogParamsSlot = 0 | 1;
+
+function nextVolumetricFogParamsSlot(frameState: RenderFrameState): VolumetricFogParamsSlot {
+  const accepted = frameState.volumetricFogParamsAcceptedSlot;
+  const pending = frameState.volumetricFogParamsPendingSlot;
+  if (pending !== null && pending !== accepted) return pending;
+  return accepted === null ? 0 : accepted === 0 ? 1 : 0;
+}
+
+export function stageVolumetricFogParams(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  params: Float32Array,
+): Buffer | undefined {
+  const slot = nextVolumetricFogParamsSlot(frameState);
+  let buffer = frameState.volumetricFogParamsBuffers[slot];
+  if (buffer === null) {
+    const created = internals.device.createBuffer({
+      label: `volumetric-fog-params-${slot}`,
+      size: VOLUMETRIC_FOG_PARAMS_BYTES,
+      usage: GPU_BUFFER_USAGE_UNIFORM | GPU_BUFFER_USAGE_COPY_DST,
+      mappedAtCreation: false,
+    });
+    if (!created.ok) {
+      internals.errorRegistry.fire(created.error);
+      return undefined;
+    }
+    buffer = created.value;
+    frameState.volumetricFogParamsBuffers[slot] = buffer;
+  }
+  const written = internals.device.queue.writeBuffer(buffer, 0, params);
+  if (!written.ok) {
+    internals.errorRegistry.fire(written.error);
+    return undefined;
+  }
+  frameState.volumetricFogParamsPendingSlot = slot;
+  frameState.volumetricFogPendingParams = new Float32Array(params);
+  return buffer;
+}
+
+/**
+ * Resolve the authored density POD into the renderer-owned GPU resources used
+ * by the graph.  This is deliberately a pull operation: a missing/stale
+ * handle or failed upload produces a structured error and leaves the graph
+ * candidate disabled for this frame rather than binding a synthetic density.
+ */
+function prepareVolumetricFogMember(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  world: World,
+  worlds: readonly World[],
+  fog: ExtractedVolumetricFog | undefined,
+  lights: ExtractedLights,
+  volumeCapability: boolean,
+  projector: SpotLightProjectorFrameContext | undefined,
+):
+  | (Omit<VolumetricFogFrameContext, 'paramsBuffer'> & { readonly params: Float32Array })
+  | undefined {
+  if (
+    !volumeCapability ||
+    fog?.status !== 'available' ||
+    fog.fog === undefined ||
+    fog.densityHandle === undefined ||
+    fog.densityAsset === undefined ||
+    (fog.lightKind === 'spot'
+      ? lights.spot.find((light) => light.entity === fog.lightEntity) === undefined
+      : fog.lightKind === 'point'
+        ? lights.point.find((light) => light.entity === fog.lightEntity) === undefined
+        : lights.directional === undefined)
+  ) {
+    return undefined;
+  }
+  const ownerWorld = worlds[fog.worldId ?? 0] ?? world;
+  const resident = internals.gpuStore.ensureResident(
+    fog.densityHandle,
+    fog.densityAsset,
+    ownerWorld,
+  );
+  if (!resident.ok || !('texture' in resident.value)) {
+    if (!resident.ok) {
+      internals.errorRegistry.fire(
+        resident.error instanceof RhiError
+          ? resident.error
+          : new RhiError({
+              code: 'webgpu-runtime-error',
+              expected: 'volumetric density residency to resolve a GPU texture',
+              hint: 'repair the authored TextureAsset payload and retry the next frame',
+              detail: { error: resident.error },
+            }),
+      );
+    }
+    return undefined;
+  }
+  const params = new Float32Array(36);
+  params.set(fog.fog.bounds.min, 0);
+  params.set(fog.fog.bounds.max, 4);
+  params[7] = fog.fog.sampling === 'density' ? 1 : 0;
+  params.set(fog.fog.extinction, 8);
+  params.set(fog.fog.albedo, 12);
+  params.set(fog.fog.emission, 16);
+  const selectedPoint =
+    fog.pointLightEntity === undefined
+      ? undefined
+      : lights.point.find((light) => light.entity === fog.pointLightEntity);
+  const selectedSpot =
+    fog.spotLightEntity === undefined
+      ? fog.lightKind === 'spot'
+        ? lights.spot.find((light) => light.entity === fog.lightEntity)
+        : undefined
+      : lights.spot.find((light) => light.entity === fog.spotLightEntity);
+  const lightDirection =
+    selectedSpot?.direction ?? lights.directional?.direction ?? vec3.create(0, -1, 0);
+  const lightColor = selectedSpot?.color ?? lights.directional?.color ?? vec3.create(0, 0, 0);
+  if (lightDirection === undefined || lightColor === undefined) return undefined;
+  params.set(lightDirection, 20);
+  // Reserved padding: render frame identity must not move volume samples.
+  params[23] = 0;
+  const selectedPointIndex =
+    selectedPoint === undefined
+      ? -1
+      : lights.point.findIndex((light) => light.entity === selectedPoint.entity);
+  const selectedSpotIndex =
+    selectedSpot === undefined
+      ? -1
+      : lights.spot.findIndex((light) => light.entity === selectedSpot.entity);
+  // Cluster light_data is one point/spot/rect array. Point slots are emitted
+  // first, so volume stores the global slot rather than a per-kind array index.
+  const selectedSpotClusterIndex =
+    selectedSpotIndex < 0 ? -1 : lights.point.length + selectedSpotIndex;
+  params.set(lightColor, 24);
+  params[19] = selectedPointIndex;
+  params[27] = selectedSpotClusterIndex;
+  params[28] = fog.fog.maxDistance;
+  params[29] = fog.fog.anisotropy;
+  params[30] =
+    selectedPoint !== undefined && selectedSpot !== undefined
+      ? 3
+      : selectedPoint !== undefined
+        ? 1
+        : selectedSpot !== undefined
+          ? 2
+          : 0;
+  // The temporal shader reads this lane after the record stage resolves the
+  // accepted graph/slot. It is overwritten on the next queue-visible frame;
+  // the first candidate deliberately starts with history disabled.
+  params[31] =
+    frameState.temporalFrame !== undefined && frameState.temporalFrame.resetReason === 'none'
+      ? 1
+      : 0;
+  // World elapsed time is the sole authored-medium clock.
+  params[32] = fog.worldTimeSeconds ?? 0;
+  return {
+    densityTexture: resident.value.texture.handle,
+    densityView: resident.value.view,
+    params,
+    densityGeneration: resident.value.receipt.generation,
+    historyReadSlot: null,
+    historyWriteSlot: 0,
+    historyValid: false,
+    ...(projector === undefined
+      ? {}
+      : {
+          projectorTexture: projector.texture,
+          projectorView: projector.view,
+          projectorSampler: projector.sampler,
+        }),
+  };
+}
+
+export function prepareVolumetricFogFrame(
+  internals: RenderSystemInternals,
+  frameState: RenderFrameState,
+  world: World,
+  worlds: readonly World[],
+  fog: ExtractedVolumetricFog | undefined,
+  lights: ExtractedLights,
+  volumeCapability: boolean,
+  projector: SpotLightProjectorFrameContext | undefined,
+): VolumetricFogFrameContext | undefined {
+  if (fog === undefined) return undefined;
+  const sources = [fog, ...(fog.additional ?? [])];
+  const members = [];
+  for (const source of sources) {
+    const member = prepareVolumetricFogMember(
+      internals,
+      frameState,
+      world,
+      worlds,
+      { ...source, worldId: fog.worldId ?? 0 },
+      lights,
+      volumeCapability,
+      projector,
+    );
+    if (member === undefined) return undefined;
+    members.push(member);
+  }
+  const first = members[0];
+  if (first === undefined) return undefined;
+  const params = new Float32Array(VOLUMETRIC_FOG_PARAMS_BYTES / 4);
+  params.set(first.params);
+  params[3] = members.length;
+  for (const [index, member] of members.entries()) {
+    params.set(member.params, (index + 1) * first.params.length);
+    for (let axis = 0; axis < 3; axis++) {
+      params[axis] = Math.min(params[axis] ?? 0, member.params[axis] ?? 0);
+      params[axis + 4] = Math.max(params[axis + 4] ?? 0, member.params[axis + 4] ?? 0);
+    }
+    params[28] = Math.max(params[28] ?? 0, member.params[28] ?? 0);
+  }
+  const paramsBuffer = stageVolumetricFogParams(internals, frameState, params);
+  if (paramsBuffer === undefined) return undefined;
+  const { params: ignored, ...context } = first;
+  void ignored;
+  return { ...context, paramsBuffer, additional: members.slice(1) };
+}