@forgeax/engine-render 0.1.27 → 0.1.29

package/src/assembly/webgpu-vertex-layouts.ts

@@ -1,108 +1,190 @@
-import type { GpuVertexBufferLayoutEntry } from '@forgeax/engine-geometry';
+import {
+  buildMeshAttributeMapForUvSets,
+  DEFAULT_VERTEX_ATTRIBUTE_MAP,
+  deriveVertexBufferLayout,
+  deriveVertexBufferLayoutFromProjection,
+  type GpuVertexBufferLayoutEntry,
+  SKIN_VERTEX_ATTRIBUTE_MAP,
+  type VertexLayoutProjection,
+} from '@forgeax/engine-geometry';
 import type { VertexAttributeMap } from '@forgeax/engine-types';
+import { RENDER_FEATURE_VERTEX_LAYOUTS } from '../features/prepared-graphics';
 
-// feat-20260611-fox-skinning-vertex-attribute-chain M4 / w16 (D-4): a single
-// shared empty ArrayBuffer used by the pipeline builder to synthesize the
-// pbr-skin attribute map when no caller-supplied attributes are available.
-// `deriveVertexBufferLayout` is the SSOT for the layout and reads only key
-// presence, so a zero-byte buffer per key preserves the six-attribute stride.
-export const PBR_SKIN_SENTINEL_ATTR_BUFFER = new ArrayBuffer(0);
-
-/** Default 4-attribute vertex layout used as fallback when meshAttributes is undefined. */
-export const DEFAULT_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-};
+type FeatureFloatVertexFormat = 'float32x2' | 'float32x3' | 'float32x4';
 
-export const PREPARED_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-  uv1: new Float32Array(0),
-};
+interface FeatureVertexAttribute {
+  readonly shaderLocation: number;
+  readonly format: FeatureFloatVertexFormat;
+}
 
-export const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS: VertexAttributeMap = {
-  position: new Float32Array(0),
-  normal: new Float32Array(0),
-  uv: new Float32Array(0),
-  tangent: new Float32Array(0),
-  skinIndex: new Uint16Array(0),
-  skinWeight: new Float32Array(0),
+interface FeatureVertexBufferSpec {
+  readonly stepMode: 'vertex' | 'instance';
+  readonly attributes: readonly FeatureVertexAttribute[];
+}
+
+const FLOAT32_COMPONENT_COUNT: Readonly<Record<FeatureFloatVertexFormat, number>> = {
+  float32x2: 2,
+  float32x3: 3,
+  float32x4: 4,
 };
 
+/**
+ * Keep feature layouts as one declarative attribute table. The stride and
+ * byte offsets are derived from that table so an attribute edit cannot leave
+ * a stale `arrayStride` or byte offset behind.
+ */
+function defineFeatureVertexBuffer(spec: FeatureVertexBufferSpec): GPUVertexBufferLayout {
+  let offsetFloats = 0;
+  const attributes = spec.attributes.map(({ shaderLocation, format }) => {
+    const attribute = {
+      shaderLocation,
+      offset: offsetFloats * Float32Array.BYTES_PER_ELEMENT,
+      format,
+    };
+    offsetFloats += FLOAT32_COMPONENT_COUNT[format];
+    return attribute;
+  });
+  return {
+    arrayStride: offsetFloats * Float32Array.BYTES_PER_ELEMENT,
+    stepMode: spec.stepMode,
+    attributes,
+  };
+}
+
+const POSITION_SIZE_COLOR_INSTANCE_SPEC = {
+  stepMode: 'instance',
+  attributes: [
+    { shaderLocation: 0, format: 'float32x3' },
+    { shaderLocation: 1, format: 'float32x2' },
+    { shaderLocation: 2, format: 'float32x4' },
+  ],
+} as const satisfies FeatureVertexBufferSpec;
+
+const BILLBOARD_MATERIAL_INSTANCE_SPEC = {
+  stepMode: 'instance',
+  attributes: [
+    { shaderLocation: 0, format: 'float32x3' },
+    { shaderLocation: 1, format: 'float32x2' },
+    { shaderLocation: 2, format: 'float32x2' },
+    { shaderLocation: 3, format: 'float32x4' },
+    { shaderLocation: 4, format: 'float32x4' },
+    { shaderLocation: 5, format: 'float32x4' },
+    { shaderLocation: 6, format: 'float32x4' },
+    { shaderLocation: 7, format: 'float32x4' },
+    { shaderLocation: 8, format: 'float32x4' },
+  ],
+} as const satisfies FeatureVertexBufferSpec;
+
+const TOPOLOGY_SEGMENT_INSTANCE_SPEC = {
+  stepMode: 'instance',
+  attributes: [
+    { shaderLocation: 0, format: 'float32x3' },
+    { shaderLocation: 1, format: 'float32x3' },
+    { shaderLocation: 2, format: 'float32x4' },
+    { shaderLocation: 3, format: 'float32x2' },
+  ],
+} as const satisfies FeatureVertexBufferSpec;
+
+const MESH_GEOMETRY_MATERIAL_INSTANCE_SPEC = {
+  stepMode: 'instance',
+  attributes: [
+    { shaderLocation: 4, format: 'float32x3' },
+    { shaderLocation: 5, format: 'float32x3' },
+    { shaderLocation: 6, format: 'float32x3' },
+    { shaderLocation: 7, format: 'float32x3' },
+    { shaderLocation: 8, format: 'float32x4' },
+    { shaderLocation: 9, format: 'float32x2' },
+  ],
+} as const satisfies FeatureVertexBufferSpec;
+
+/** Geometry-owned maps retained here only as feature-pipeline aliases. */
+export const PREPARED_INSTANCE_VERTEX_ATTRS = buildMeshAttributeMapForUvSets(2);
+export const PREPARED_MATERIAL_INSTANCE_VERTEX_ATTRS = SKIN_VERTEX_ATTRIBUTE_MAP;
+
+function canonicalMeshVertexBufferLayout(): GPUVertexBufferLayout {
+  const [buffer] = toGpuVertexBufferLayouts(deriveVertexBufferLayout(DEFAULT_VERTEX_ATTRIBUTE_MAP));
+  if (buffer === undefined) {
+    throw new Error('The canonical mesh vertex layout must contain one vertex buffer');
+  }
+  return { ...buffer, stepMode: 'vertex' };
+}
+
 export const POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 9 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
-      { shaderLocation: 2, offset: 5 * 4, format: 'float32x4' as const },
-    ],
-  },
+  defineFeatureVertexBuffer(POSITION_SIZE_COLOR_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 
 export const BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 31 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x2' as const },
-      { shaderLocation: 2, offset: 5 * 4, format: 'float32x2' as const },
-      { shaderLocation: 3, offset: 7 * 4, format: 'float32x4' as const },
-      { shaderLocation: 4, offset: 11 * 4, format: 'float32x4' as const },
-      { shaderLocation: 5, offset: 15 * 4, format: 'float32x4' as const },
-      { shaderLocation: 6, offset: 19 * 4, format: 'float32x4' as const },
-      { shaderLocation: 7, offset: 23 * 4, format: 'float32x4' as const },
-      { shaderLocation: 8, offset: 27 * 4, format: 'float32x4' as const },
-    ],
-  },
+  defineFeatureVertexBuffer(BILLBOARD_MATERIAL_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 
 export const TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 12 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 2, offset: 6 * 4, format: 'float32x4' as const },
-      { shaderLocation: 3, offset: 10 * 4, format: 'float32x2' as const },
-    ],
-  },
+  defineFeatureVertexBuffer(TOPOLOGY_SEGMENT_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 
+/**
+ * The mesh stream is derived from geometry's canonical attribute projection.
+ * The second stream remains a feature-owned instance ABI because it carries
+ * particle transform/material data rather than MeshAsset attributes.
+ */
 export const MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS = [
-  {
-    arrayStride: 12 * 4,
-    stepMode: 'vertex' as const,
-    attributes: [
-      { shaderLocation: 0, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 1, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 2, offset: 6 * 4, format: 'float32x2' as const },
-      { shaderLocation: 3, offset: 8 * 4, format: 'float32x4' as const },
-    ],
-  },
-  {
-    arrayStride: 28 * 4,
-    stepMode: 'instance' as const,
-    attributes: [
-      { shaderLocation: 4, offset: 0, format: 'float32x3' as const },
-      { shaderLocation: 5, offset: 3 * 4, format: 'float32x3' as const },
-      { shaderLocation: 6, offset: 6 * 4, format: 'float32x3' as const },
-      { shaderLocation: 7, offset: 9 * 4, format: 'float32x3' as const },
-      { shaderLocation: 8, offset: 12 * 4, format: 'float32x4' as const },
-      { shaderLocation: 9, offset: 16 * 4, format: 'float32x4' as const },
-      { shaderLocation: 10, offset: 20 * 4, format: 'float32x4' as const },
-      { shaderLocation: 11, offset: 24 * 4, format: 'float32x4' as const },
-    ],
-  },
+  canonicalMeshVertexBufferLayout(),
+  defineFeatureVertexBuffer(MESH_GEOMETRY_MATERIAL_INSTANCE_SPEC),
 ] satisfies readonly GPUVertexBufferLayout[];
 
+const PREPARED_MATERIAL_VERTEX_LAYOUTS: ReadonlySet<string> = new Set([
+  RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInputInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentMaterialInputInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance,
+  RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInputInstance,
+]);
+
+export function isPreparedMaterialVertexLayout(layout: string | undefined): boolean {
+  return layout !== undefined && PREPARED_MATERIAL_VERTEX_LAYOUTS.has(layout);
+}
+
+/**
+ * Derive the prepared particle layout that appends one to four material-input
+ * vec4 lanes to the instance stream. The base layouts stay shared with the
+ * no-input path; only the final stream stride and locations change, which
+ * keeps the vertex-data ABI and pipeline cache key in lockstep.
+ */
+export function particleMaterialInputVertexBuffers(
+  vertexLayout: string | undefined,
+  lanes?: number,
+): readonly GPUVertexBufferLayout[] | undefined {
+  const buffers =
+    vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInputInstance
+      ? BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS
+      : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentMaterialInputInstance
+        ? TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS
+        : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInputInstance
+          ? MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS
+          : undefined;
+  if (buffers === undefined || lanes === undefined) return undefined;
+  if (!Number.isInteger(lanes) || lanes < 1 || lanes > 4) {
+    throw new RangeError('Particle material input layouts require 1 through 4 lanes');
+  }
+  return buffers.map((buffer, index) => {
+    if (index !== buffers.length - 1) return buffer;
+    const attributes = [...buffer.attributes];
+    const firstLocation = Math.max(...attributes.map((attribute) => attribute.shaderLocation)) + 1;
+    return {
+      ...buffer,
+      arrayStride: buffer.arrayStride + lanes * 16,
+      attributes: [
+        ...attributes,
+        ...Array.from({ length: lanes }, (_, lane) => ({
+          shaderLocation: firstLocation + lane,
+          offset: buffer.arrayStride + lane * 16,
+          format: 'float32x4' as const,
+        })),
+      ],
+    };
+  });
+}
+
 function toGpuVertexFormat(
   format: GpuVertexBufferLayoutEntry['attributes'][number]['format'],
 ): GPUVertexFormat {
@@ -130,3 +212,67 @@ export function toGpuVertexBufferLayouts(
     })),
   }));
 }
+
+export function resolveWebGPUVertexBufferLayouts(options: {
+  vertexInputContract: 'none' | 'render-material';
+  vertexLayout: string | undefined;
+  vertexLayoutProjection: VertexLayoutProjection | undefined;
+  resolvedUvSetCount: number | undefined;
+  layoutKind: string;
+  meshAttributes: VertexAttributeMap | undefined;
+  particleInputLanes: number | undefined;
+}): readonly GPUVertexBufferLayout[] {
+  const {
+    vertexInputContract,
+    vertexLayout,
+    vertexLayoutProjection,
+    resolvedUvSetCount,
+    layoutKind,
+    meshAttributes,
+    particleInputLanes,
+  } = options;
+  const inputVertexBuffers = particleMaterialInputVertexBuffers(vertexLayout, particleInputLanes);
+  return vertexInputContract === 'none'
+    ? []
+    : inputVertexBuffers !== undefined
+      ? inputVertexBuffers
+      : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.positionSizeColorInstance
+        ? POSITION_SIZE_COLOR_INSTANCE_VERTEX_BUFFERS
+        : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.billboardMaterialInstance
+          ? BILLBOARD_MATERIAL_INSTANCE_VERTEX_BUFFERS
+          : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.topologySegmentInstance
+            ? TOPOLOGY_SEGMENT_INSTANCE_VERTEX_BUFFERS
+            : vertexLayout === RENDER_FEATURE_VERTEX_LAYOUTS.meshGeometryMaterialInstance
+              ? MESH_GEOMETRY_MATERIAL_INSTANCE_VERTEX_BUFFERS
+              : vertexLayoutProjection !== undefined
+                ? toGpuVertexBufferLayouts(
+                    deriveVertexBufferLayoutFromProjection(
+                      vertexLayoutProjection,
+                      resolvedUvSetCount !== undefined
+                        ? { shaderUvSetCount: resolvedUvSetCount }
+                        : undefined,
+                    ),
+                  )
+                : layoutKind === 'pbr-skin'
+                  ? toGpuVertexBufferLayouts(
+                      deriveVertexBufferLayout(
+                        meshAttributes ?? SKIN_VERTEX_ATTRIBUTE_MAP,
+                        resolvedUvSetCount !== undefined
+                          ? { shaderUvSetCount: resolvedUvSetCount }
+                          : undefined,
+                      ),
+                    )
+                  : meshAttributes !== undefined ||
+                      (resolvedUvSetCount !== undefined && resolvedUvSetCount > 1)
+                    ? toGpuVertexBufferLayouts(
+                        deriveVertexBufferLayout(
+                          meshAttributes ?? DEFAULT_VERTEX_ATTRIBUTE_MAP,
+                          resolvedUvSetCount !== undefined && resolvedUvSetCount > 1
+                            ? { shaderUvSetCount: resolvedUvSetCount }
+                            : undefined,
+                        ),
+                      )
+                    : toGpuVertexBufferLayouts(
+                        deriveVertexBufferLayout(DEFAULT_VERTEX_ATTRIBUTE_MAP),
+                      );
+}

package/src/components/__tests__/camera-exposure.contract.unit.test.ts

@@ -0,0 +1,153 @@
+import { World } from '@forgeax/engine-ecs';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+import { extractCameraSnapshots } from '../../extract/camera';
+import {
+  CAMERA_EXPOSURE_MODE_AUTO,
+  CAMERA_EXPOSURE_MODE_MANUAL,
+  Camera,
+  CameraError,
+  type CameraExposure,
+  cameraExposureFromColumns,
+  orthographic,
+  perspective,
+  validateCameraColorGrading,
+  validateCameraExposure,
+} from '../index';
+
+function describeExposure(exposure: CameraExposure): string {
+  switch (exposure.kind) {
+    case 'manual':
+      return `manual:${exposure.multiplier}`;
+    case 'auto':
+      return `auto:${exposure.fallback}`;
+  }
+  const unreachable: never = exposure;
+  return unreachable;
+}
+
+describe('CameraExposure contract', () => {
+  it('keeps manual, auto, and defaults in the Camera schema', () => {
+    expect(Camera.fields.exposureMode.default).toBe(CAMERA_EXPOSURE_MODE_MANUAL);
+    expect(Camera.fields.exposure.default).toBe(1);
+    expect(Camera.fields.rangeEv.default).toEqual(new Float32Array([-8, 8]));
+    expect(Camera.fields.rates.default).toEqual(new Float32Array([3, 1]));
+    expect(Camera.fields.temperature.default).toBe(6504);
+    expect(Camera.fields.tint.default).toBe(0);
+    expect(Camera.fields.colorLut.type).toBe('shared<TextureAsset>');
+    expect(Camera.fields.colorLutStrength.default).toBe(0);
+  });
+
+  it('projects the same public output through both camera factories', () => {
+    const exposure: CameraExposure = {
+      kind: 'auto',
+      fallback: 1.25,
+      compensationEv: -0.5,
+      rangeEv: [-6, 6],
+      rates: [3, 1],
+    };
+    const perspectiveCamera = perspective({
+      fov: Math.PI / 3,
+      aspect: 16 / 9,
+      exposure,
+      temperature: 5000,
+      tint: 0.1,
+      colorLutStrength: 0.5,
+    });
+    const orthographicCamera = orthographic({
+      left: -10,
+      right: 10,
+      bottom: -10,
+      top: 10,
+      exposure,
+      temperature: 5000,
+      tint: 0.1,
+      colorLutStrength: 0.5,
+    });
+    expect(perspectiveCamera.exposureMode).toBe(CAMERA_EXPOSURE_MODE_AUTO);
+    expect(orthographicCamera.exposureMode).toBe(CAMERA_EXPOSURE_MODE_AUTO);
+    expect(perspectiveCamera.exposure).toBe(1.25);
+    expect(orthographicCamera.rangeEv).toEqual(new Float32Array([-6, 6]));
+    expect(describeExposure(cameraExposureFromColumns(perspectiveCamera))).toBe('auto:1.25');
+  });
+
+  it('rejects non-finite, reversed, and negative-rate authoring', () => {
+    expect(() => validateCameraExposure({ kind: 'manual', multiplier: 0 })).toThrow(CameraError);
+    try {
+      validateCameraExposure({ kind: 'manual', multiplier: 0 });
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: 'camera-exposure-invalid',
+        expected: 'a finite number greater than zero',
+        detail: { field: 'multiplier', actual: 0 },
+      });
+    }
+    expect(() =>
+      validateCameraExposure({
+        kind: 'auto',
+        fallback: Number.NaN,
+        compensationEv: 0,
+        rangeEv: [-8, 8],
+        rates: [3, 1],
+      }),
+    ).toThrow();
+    expect(() =>
+      validateCameraExposure({
+        kind: 'auto',
+        fallback: 1,
+        compensationEv: 0,
+        rangeEv: [8, -8],
+        rates: [3, 1],
+      }),
+    ).toThrow();
+    expect(() =>
+      validateCameraExposure({
+        kind: 'auto',
+        fallback: 1,
+        compensationEv: 0,
+        rangeEv: [-8, 8],
+        rates: [-1, 1],
+      }),
+    ).toThrow();
+  });
+
+  it('reports closed structured failures for Camera color fields and column modes', () => {
+    expect(() => validateCameraExposure({ kind: 'manual', multiplier: Number.NaN })).toThrow(
+      CameraError,
+    );
+    expect(() => validateCameraColorGrading(500, 0, 0)).toThrow(CameraError);
+    expect(() => validateCameraColorGrading(6504, 2, 0)).toThrow(CameraError);
+    expect(() =>
+      cameraExposureFromColumns({
+        exposureMode: 7,
+        exposure: 1,
+        compensationEv: 0,
+        rangeEv: new Float32Array([-8, 8]),
+        rates: new Float32Array([3, 1]),
+      }),
+    ).toThrow(CameraError);
+  });
+
+  it('closes the Camera -> SoA extract identity for perspective and orthographic', () => {
+    const world = new World();
+    world
+      .spawn(
+        { component: Transform, data: {} },
+        {
+          component: Camera,
+          data: perspective({
+            fov: Math.PI / 3,
+            aspect: 1,
+            exposure: { kind: 'manual', multiplier: 2 },
+          }),
+        },
+      )
+      .unwrap();
+    const [snapshot] = extractCameraSnapshots(world);
+    expect(snapshot?.output?.exposure).toEqual({ kind: 'manual', multiplier: 2 });
+    expect(snapshot?.output?.temperature).toBe(6504);
+    expect(snapshot?.output?.tint).toBe(0);
+    expect(snapshot?.output?.colorLutStrength).toBe(0);
+    expect(snapshot?.projection).toBe('perspective');
+  });
+});