@forgeax/engine-render 0.1.28 → 0.1.30

package/src/pipeline/standard-output/auto-exposure/__tests__/graph.contract.unit.test.ts

@@ -0,0 +1,94 @@
+import { RhiError } from '@forgeax/engine-rhi';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  AUTO_EXPOSURE_FUSED_GRAPH_PASS,
+  AUTO_EXPOSURE_GRAPH_PASSES,
+  AUTO_EXPOSURE_HISTOGRAM_DISPATCH,
+  AUTO_EXPOSURE_HISTOGRAM_WORKGROUP_COUNT,
+  createAutoExposureGraphPlan,
+  resolveAutoExposureShaderModuleFactory,
+  validateAutoExposureGraphPlan,
+} from '../graph';
+
+describe('auto exposure graph contract', () => {
+  it('declares exactly clear, histogram, and adapt work', () => {
+    const plan = createAutoExposureGraphPlan({ width: 17, height: 9 });
+    expect(plan.passes.map((pass) => pass.name)).toEqual([...AUTO_EXPOSURE_GRAPH_PASSES]);
+    expect(plan.passes.map((pass) => pass.kind)).toEqual(['compute', 'compute', 'compute']);
+    expect(plan.physicalPass).toBe(AUTO_EXPOSURE_FUSED_GRAPH_PASS);
+    expect(plan.physicalPassCount).toBe(1);
+    expect(plan.histogramBytes).toBe(256 * 4);
+    expect(plan.stateBytes).toBe(2 * 16);
+    expect(plan.sampleCount).toBe(1);
+    expect(plan.cpuReadbackCount).toBe(0);
+    expect(plan.cpuUploadCount).toBe(0);
+    expect(plan.candidateAvailableSameFrame).toBe(true);
+    expect(validateAutoExposureGraphPlan(plan).ok).toBe(true);
+  });
+
+  it('keeps the fixed 32-workgroup cohort for non-divisible extents', () => {
+    const plan = createAutoExposureGraphPlan({ width: 17, height: 9 });
+    expect(plan.dispatch).toEqual(AUTO_EXPOSURE_HISTOGRAM_DISPATCH);
+    expect(plan.dispatch.x * plan.dispatch.y).toBe(AUTO_EXPOSURE_HISTOGRAM_WORKGROUP_COUNT);
+    expect(plan.sampleCount).toBe(1);
+    expect(plan.sampleBounds).toEqual({ x: 4, y: 4 });
+    expect(plan.passes.map((pass) => pass.workgroupSize)).toEqual([
+      [256, 1, 1],
+      [256, 1, 1],
+      [64, 1, 1],
+    ]);
+
+    const tiled = createAutoExposureGraphPlan({ width: 129, height: 133 });
+    expect(tiled.dispatch).toEqual(AUTO_EXPOSURE_HISTOGRAM_DISPATCH);
+  });
+
+  it('rejects an incorrectly ordered or duplicated work sequence', () => {
+    const plan = createAutoExposureGraphPlan({ width: 8, height: 8 });
+    const invalid = {
+      ...plan,
+      passes: [plan.passes[1], plan.passes[0], plan.passes[2], plan.passes[2]],
+    } as typeof plan;
+    const result = validateAutoExposureGraphPlan(invalid);
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('auto-exposure-graph-invalid');
+  });
+
+  it('rejects stale dispatch or workgroup declarations', () => {
+    const plan = createAutoExposureGraphPlan({ width: 8, height: 8 });
+    const invalidDispatch = {
+      ...plan,
+      dispatch: { x: 1, y: 1, z: 1 },
+    } as typeof plan;
+    expect(validateAutoExposureGraphPlan(invalidDispatch)).toMatchObject({ ok: false });
+
+    const invalidWorkgroup = {
+      ...plan,
+      passes: plan.passes.map((pass, index) =>
+        index === 1 ? { ...pass, workgroupSize: [128, 1, 1] as const } : pass,
+      ),
+    } as typeof plan;
+    expect(validateAutoExposureGraphPlan(invalidWorkgroup)).toMatchObject({ ok: false });
+  });
+
+  it('uses the immediate shader factory for the first non-pending frame', () => {
+    const immediate = {
+      createShaderModule: () => ok({} as import('@forgeax/engine-rhi').ShaderModule),
+    };
+    const validated = {
+      createShaderModule: () =>
+        err(
+          new RhiError({
+            code: 'rhi-not-available',
+            expected: 'an already prepared shader module',
+            hint: 'wait for the asynchronous warm-up',
+          }),
+        ),
+    };
+    const selected = resolveAutoExposureShaderModuleFactory({
+      immediateShaderModuleFactory: immediate,
+      shaderModuleFactory: validated,
+    });
+    expect(selected).toBe(immediate);
+  });
+});

package/src/pipeline/standard-output/auto-exposure/__tests__/oracle.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest';
+import {
+  adaptExposure,
+  autoExposureTarget,
+  bradfordAdaptD65,
+  centerWeight,
+  ciede2000,
+  histogramPercentile,
+  linearRgbToLab,
+  luminanceHistogram,
+  weightedLuminanceHistogram,
+} from '../oracle';
+
+describe('auto-exposure and color oracle', () => {
+  it('clips finite luminance into deterministic logarithmic histogram bins', () => {
+    const histogram = luminanceHistogram(
+      [
+        [0, 0, 0, 0],
+        [0.18, 0.18, 0.18, 1],
+        [4, 4, 4, 0.1],
+        [Number.NaN, 1, 1, 1],
+      ],
+      256,
+    );
+    expect(histogram.reduce((sum, value) => sum + value, 0)).toBe(2);
+    expect(histogramPercentile(histogram, 0.5)).toBeGreaterThan(0);
+  });
+
+  it('uses time-based adaptation independent of frame rate', () => {
+    const thirtyHz = Array.from({ length: 30 }, () => 1 / 30).reduce(
+      (value, dt) => adaptExposure(value, 2, dt, 3, 1),
+      1,
+    );
+    const sixtyHz = Array.from({ length: 60 }, () => 1 / 60).reduce(
+      (value, dt) => adaptExposure(value, 2, dt, 3, 1),
+      1,
+    );
+    expect(thirtyHz).toBeCloseTo(sixtyHz, 5);
+    expect(adaptExposure(2, 1, 1 / 60, 0, 0)).toBe(2);
+  });
+
+  it('matches the fixed center weighting and rejects non-finite samples', () => {
+    expect(centerWeight([1, 1], [3, 3])).toBe(3);
+    expect(centerWeight([0, 0], [3, 3])).toBe(1);
+    const histogram = weightedLuminanceHistogram(
+      [
+        [0.18, 0.18, 0.18, 1],
+        [Number.NaN, 1, 1, 1],
+        [0.18, 0.18, 0.18, 1],
+        [0.18, 0.18, 0.18, 1],
+      ],
+      [2, 2],
+      256,
+    );
+    expect(histogram.reduce((sum, value) => sum + value, 0)).toBe(6);
+  });
+
+  it('keeps edge and center weights exact on a non-4-divisible grid', () => {
+    const sampleGrid = [3, 2] as const;
+    const histogram = weightedLuminanceHistogram(
+      [
+        [1, 1, 1, 1],
+        [Number.NaN, 1, 1, 1],
+        [0.18, 0.18, 0.18, 1],
+        [Number.POSITIVE_INFINITY, 1, 1, 1],
+        [0.18, 0.18, 0.18, 1],
+        [Number.NEGATIVE_INFINITY, 1, 1, 1],
+      ],
+      sampleGrid,
+    );
+    const expectedWeight =
+      centerWeight([0, 0], sampleGrid) +
+      centerWeight([2, 0], sampleGrid) +
+      centerWeight([1, 1], sampleGrid);
+    expect(histogram.reduce((sum, value) => sum + value, 0)).toBe(expectedWeight);
+  });
+
+  it('applies compensation and EV range before frame-rate-independent adaptation', () => {
+    const histogram = weightedLuminanceHistogram(
+      Array.from({ length: 4 }, () => [0.18, 0.18, 0.18, 1] as const),
+      [2, 2],
+    );
+    const target = autoExposureTarget(histogram, 1, [-8, 8], 1);
+    expect(target).toBeCloseTo(2, 1);
+    expect(autoExposureTarget(histogram, 20, [-2, 2], 1)).toBeCloseTo(4, 6);
+    expect(autoExposureTarget(histogram, Number.NaN, [-8, 8], 1)).toBe(1);
+    expect(autoExposureTarget(histogram, 1, [8, -8], 1)).toBe(1);
+    const thirtyHz = Array.from({ length: 30 }, () => 1 / 30).reduce(
+      (value, dt) => adaptExposure(value, target, dt, 3, 1),
+      1,
+    );
+    const sixtyHz = Array.from({ length: 60 }, () => 1 / 60).reduce(
+      (value, dt) => adaptExposure(value, target, dt, 3, 1),
+      1,
+    );
+    expect(thirtyHz).toBeCloseTo(sixtyHz, 5);
+    expect(adaptExposure(2, target, 1 / 60, 0, 1)).toBe(2);
+  });
+
+  it('keeps D65 Bradford adaptation identity and alpha outside color math', () => {
+    expect(bradfordAdaptD65([0.25, 0.5, 0.75], 6504)).toEqual([0.25, 0.5, 0.75]);
+  });
+
+  it('matches the Lab/CIEDE2000 identity oracle', () => {
+    const lab = linearRgbToLab([0.18, 0.18, 0.18]);
+    expect(ciede2000(lab, lab)).toBeCloseTo(0, 10);
+  });
+});

package/src/pipeline/standard-output/auto-exposure/__tests__/preset.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { AUTO_EXPOSURE_PRESET_V1, type AutoExposurePreset } from '../preset';
+
+describe('auto-exposure product preset', () => {
+  it('freezes the V1 sampling, histogram, clipping, and middle-gray contract', () => {
+    const preset: AutoExposurePreset = AUTO_EXPOSURE_PRESET_V1;
+    expect(preset).toMatchObject({
+      version: 'auto-exposure-v1',
+      histogramBins: 256,
+      sampleBlockSize: 4,
+      lowPercentile: 0.05,
+      highPercentile: 0.95,
+      middleGray: 0.18,
+    });
+    expect(Object.isFrozen(preset)).toBe(true);
+  });
+
+  it('keeps product constants separate from external formula references', () => {
+    expect(AUTO_EXPOSURE_PRESET_V1.referenceFormulas).toEqual([
+      'linear-rgb-to-xyz-d65',
+      'bradford-d65-adaptation',
+      'cielab-delta-e-2000',
+    ]);
+    expect(AUTO_EXPOSURE_PRESET_V1).not.toHaveProperty('histogramBuckets');
+  });
+});

package/src/pipeline/standard-output/auto-exposure/capability.ts

@@ -0,0 +1,38 @@
+import type { RhiCaps } from '@forgeax/engine-rhi';
+import { err, ok, type Result } from '@forgeax/engine-types';
+import { AutoExposureCapabilityUnavailableError } from './inspection';
+
+export type AutoExposureCapabilityFacts = Pick<
+  RhiCaps,
+  'compute' | 'storageBuffer' | 'float32Filterable' | 'rgba16floatRenderable'
+>;
+
+export interface AutoExposureCapability {
+  readonly available: true;
+  readonly generation: number;
+  readonly rgba16floatRenderable: boolean;
+}
+
+function unavailable(
+  capability: 'compute' | 'storage-buffer' | 'float-filterable',
+  generation: number,
+): Result<never, AutoExposureCapabilityUnavailableError> {
+  return err(new AutoExposureCapabilityUnavailableError({ capability, generation }));
+}
+
+/** Resolve live device facts; no capability is inferred from a neighboring format. */
+export function resolveAutoExposureCapability(
+  caps: AutoExposureCapabilityFacts,
+  generation: number,
+): Result<AutoExposureCapability, AutoExposureCapabilityUnavailableError> {
+  if (!caps.compute) return unavailable('compute', generation);
+  if (!caps.storageBuffer) return unavailable('storage-buffer', generation);
+  if (!caps.float32Filterable) return unavailable('float-filterable', generation);
+  return ok(
+    Object.freeze({
+      available: true as const,
+      generation,
+      rgba16floatRenderable: caps.rgba16floatRenderable,
+    }),
+  );
+}