@forgeax/engine-render 0.1.27 → 0.1.29

package/src/pipeline/standard-output/__tests__/lut-admission.unit.test.ts

@@ -0,0 +1,103 @@
+import type { TextureAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  admitStandardColorLut,
+  createStandardLutSamplerDescriptor,
+  lutTexelCenter,
+  type StandardColorLutAdmissionInput,
+} from '../lut-admission';
+
+function texture(overrides: Partial<TextureAsset> = {}): TextureAsset {
+  return {
+    kind: 'texture',
+    shape: { viewDimension: '3d', extent: { width: 16, height: 16, depth: 16 } },
+    format: 'rgba16float',
+    data: new Uint8Array(16 * 16 * 16 * 8),
+    colorSpace: 'linear',
+    mips: { kind: 'none' },
+    ...overrides,
+  };
+}
+
+function input(overrides: Partial<StandardColorLutAdmissionInput> = {}) {
+  return {
+    texture: texture(),
+    maxTextureDimension3D: 2048,
+    rgba16floatFilterable: true,
+    bind: () => true,
+    ...overrides,
+  } satisfies StandardColorLutAdmissionInput;
+}
+
+describe('Standard output 3D LUT admission', () => {
+  it('accepts a linear, equal-extent, single-mip rgba16float texture', () => {
+    const result = admitStandardColorLut(input());
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.viewDimension).toBe('3d');
+    expect(result.value.extent).toEqual({ width: 16, height: 16, depth: 16 });
+    expect(result.value.sampler).toEqual(createStandardLutSamplerDescriptor());
+  });
+
+  it.each([
+    ['view dimension', { shape: { viewDimension: '2d', extent: { width: 16, height: 16 } } }],
+    [
+      'unequal extent',
+      { shape: { viewDimension: '3d', extent: { width: 16, height: 17, depth: 16 } } },
+    ],
+    ['format', { format: 'rgba32float' }],
+    ['color space', { colorSpace: 'srgb' }],
+    ['mip policy', { mips: { kind: 'generate' } }],
+  ] as const)('rejects invalid %s', (_name, overrides) => {
+    const result = admitStandardColorLut(input({ texture: texture(overrides as never) }));
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('standard-lut-shape-invalid');
+  });
+
+  it('rejects dimensions over the live 3D limit', () => {
+    const result = admitStandardColorLut(
+      input({
+        texture: texture({
+          shape: { viewDimension: '3d', extent: { width: 4096, height: 4096, depth: 4096 } },
+        }),
+        maxTextureDimension3D: 2048,
+      }),
+    );
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('standard-lut-limit-exceeded');
+  });
+
+  it('does not infer rgba16float filterability from float32 filterability', () => {
+    const result = admitStandardColorLut(input({ rgba16floatFilterable: false }));
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('standard-lut-filter-unavailable');
+  });
+
+  it('requires a successful live bind probe', () => {
+    const result = admitStandardColorLut(input({ bind: () => false }));
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.code).toBe('standard-lut-bind-failed');
+  });
+
+  it('uses texel centers and clamp-to-edge linear filtering', () => {
+    expect(lutTexelCenter(0, 16)).toBe(0.5 / 16);
+    expect(lutTexelCenter(15, 16)).toBe(15.5 / 16);
+    expect(createStandardLutSamplerDescriptor()).toEqual({
+      addressModeU: 'clamp-to-edge',
+      addressModeV: 'clamp-to-edge',
+      addressModeW: 'clamp-to-edge',
+      magFilter: 'linear',
+      minFilter: 'linear',
+      mipmapFilter: 'nearest',
+    });
+  });
+});

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

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest';
+import { resolveAutoExposureCapability } from '../capability';
+
+const complete = {
+  compute: true,
+  storageBuffer: true,
+  float32Filterable: true,
+  rgba16floatRenderable: true,
+};
+
+describe('auto exposure capability contract', () => {
+  it('requires live compute, storage, and float filtering facts', () => {
+    expect(resolveAutoExposureCapability(complete, 8)).toMatchObject({
+      ok: true,
+      value: { available: true, generation: 8 },
+    });
+    expect(resolveAutoExposureCapability({ ...complete, compute: false }, 8)).toMatchObject({
+      ok: false,
+      error: { code: 'auto-exposure-capability-unavailable', detail: { capability: 'compute' } },
+    });
+    expect(
+      resolveAutoExposureCapability({ ...complete, float32Filterable: false }, 8),
+    ).toMatchObject({
+      ok: false,
+      error: {
+        code: 'auto-exposure-capability-unavailable',
+        detail: { capability: 'float-filterable' },
+      },
+    });
+  });
+
+  it('does not infer float filtering from rgba16float renderability', () => {
+    expect(
+      resolveAutoExposureCapability(
+        { ...complete, float32Filterable: false, rgba16floatRenderable: true },
+        9,
+      ),
+    ).toMatchObject({ ok: false, error: { detail: { capability: 'float-filterable' } } });
+  });
+});

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

@@ -0,0 +1,125 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  addAutoExposureExposurePass,
+  addAutoExposureGraphPasses,
+  createAutoExposureApplyWgsl,
+} from '../gpu';
+
+describe('auto exposure GPU pass contract', () => {
+  it('encodes clear, histogram, and adapt in one compute pass with a fixed cohort', () => {
+    type Descriptor = {
+      readonly accesses: readonly unknown[];
+      readonly encode: (context: never) => void;
+    };
+    const passes: Array<{ name: string; kind: string; descriptor: Descriptor }> = [];
+    const graph = {
+      addComputePass: (name: string, descriptor: Descriptor) => {
+        passes.push({ name, kind: 'compute', descriptor });
+        return ok(undefined);
+      },
+    };
+    const result = addAutoExposureGraphPasses(
+      { graph } as never,
+      {
+        source: { view: {} },
+        resources: { histogram: {}, state: {}, candidate: {}, parameters: {} },
+        width: 1080,
+        height: 1920,
+      } as never,
+    );
+
+    expect(result.ok).toBe(true);
+    expect(passes.map(({ name, kind }) => [name, kind])).toEqual([
+      ['auto-exposure-meter', 'compute'],
+    ]);
+    expect(passes[0]?.descriptor.accesses).toEqual([
+      { resource: {}, usage: 'sampled-read' },
+      { resource: {}, usage: 'storage-write' },
+      { resource: {}, usage: 'storage-write' },
+      { resource: {}, usage: 'storage-write' },
+      { resource: {}, usage: 'storage-read' },
+    ]);
+
+    const pipelineNames: string[] = [];
+    const setPipeline = vi.fn((pipeline: { readonly label: string }) => {
+      pipelineNames.push(pipeline.label);
+    });
+    const setBindGroup = vi.fn();
+    const dispatchWorkgroups = vi.fn();
+    const shaderFactory = {
+      createShaderModule: vi.fn(({ label }: { readonly label: string }) => ok({ label })),
+    };
+    const device = {
+      createBindGroupLayout: vi.fn((descriptor: unknown) => ok({ descriptor })),
+      createPipelineLayout: vi.fn((descriptor: unknown) => ok({ descriptor })),
+      createComputePipeline: vi.fn((descriptor: { readonly label: string }) =>
+        ok({ label: descriptor.label }),
+      ),
+      createBindGroup: vi.fn((descriptor: unknown) => ok({ descriptor })),
+    };
+    const encoded = passes[0]?.descriptor.encode({
+      pass: { setPipeline, setBindGroup, dispatchWorkgroups },
+      frame: { runtime: { device, immediateShaderModuleFactory: shaderFactory } },
+      resources: {
+        textureView: () => ok({}),
+        buffer: () => ok({}),
+      },
+    } as never);
+
+    expect(encoded).toBeUndefined();
+    expect(pipelineNames).toEqual([
+      'auto_exposure_clear',
+      'auto_exposure_histogram',
+      'auto_exposure_adapt',
+    ]);
+    expect(dispatchWorkgroups).toHaveBeenCalledTimes(3);
+    expect(dispatchWorkgroups).toHaveBeenNthCalledWith(1, 1, 1, 1);
+    expect(dispatchWorkgroups).toHaveBeenNthCalledWith(2, 4, 8, 1);
+    expect(dispatchWorkgroups).toHaveBeenNthCalledWith(3, 1, 1, 1);
+    expect(setBindGroup).toHaveBeenCalledTimes(1);
+    expect(device.createComputePipeline).toHaveBeenCalledTimes(3);
+  });
+
+  it('routes the same-frame GPU candidate into the exposure consumer', () => {
+    const passes: Array<{ name: string; descriptor: { accesses: readonly unknown[] } }> = [];
+    const graph = {
+      addRasterPass: (name: string, descriptor: { accesses: readonly unknown[] }) => {
+        passes.push({ name, descriptor });
+        return ok(undefined);
+      },
+    };
+    const result = addAutoExposureExposurePass(
+      { graph } as never,
+      { view: {}, format: 'rgba16float' } as never,
+      { view: {}, format: 'rgba16float' } as never,
+      { histogram: {}, state: {}, candidate: {}, parameters: {} } as never,
+    );
+    expect(result.ok).toBe(true);
+    expect(passes).toHaveLength(1);
+    expect(passes[0]).toMatchObject({
+      name: 'standard-exposure-white-balance',
+      descriptor: {
+        accesses: [
+          { resource: {}, usage: 'sampled-read' },
+          { resource: {}, usage: 'storage-read' },
+          { resource: {}, usage: 'color-attachment' },
+        ],
+      },
+    });
+  });
+
+  it('keeps Bradford white balance in the sole linear-HDR consumer and preserves alpha', () => {
+    const withCandidate = createAutoExposureApplyWgsl({ temperature: 5000, tint: 0.2 }, true);
+    expect(withCandidate).toContain('@group(0) @binding(2) var<storage, read> candidate');
+    expect(withCandidate).toContain('mul_bradford');
+    expect(withCandidate).toContain('blackbody_white_point');
+    expect(withCandidate).toContain('WB_TEMPERATURE: f32 = 5000.00000000');
+    expect(withCandidate).toContain('WB_TINT: f32 = 0.20000000');
+    expect(withCandidate).toContain('color.a');
+
+    const manual = createAutoExposureApplyWgsl({ temperature: 6504, tint: 0 }, false);
+    expect(manual).not.toContain('var<storage, read> candidate');
+    expect(manual).toContain('let exposed = color.rgb * 1.0');
+  });
+});

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,
+    }),
+  );
+}