@forgeax/engine-render 0.1.2

package/src/record/__tests__/render-submission.perf.test.ts

@@ -0,0 +1,141 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { commandBufferPlanForFrame, createShadowSubmitModeState } from '../shadow-submit-mode';
+
+type WorkloadPass = {
+  readonly name: string;
+  readonly draws: readonly string[];
+};
+
+type SubmissionProbe = {
+  readonly events: string[];
+  readonly rawSubmitCount: number;
+  readonly rendererSubmitCount: number;
+};
+
+const publicWorkloadDescriptor: readonly WorkloadPass[] = [
+  { name: 'shadow', draws: ['shadow-caster'] },
+  { name: 'main', draws: ['forward-geometry', 'post-process'] },
+];
+
+function makeProbe(duplicateRhiSubmit: boolean): SubmissionProbe {
+  const events: string[] = [];
+  let rawSubmitCount = 0;
+  let rendererSubmitCount = 0;
+
+  const rawQueue = {
+    submit: () => {
+      rawSubmitCount += 1;
+      events.push('rhi-wrapper:raw-submit');
+      return { ok: true as const, value: undefined };
+    },
+  };
+  const queue = {
+    submit: (buffers: readonly unknown[]) => {
+      rendererSubmitCount += 1;
+      events.push(`renderer-submit:${buffers.length}`);
+      const first = rawQueue.submit();
+      if (duplicateRhiSubmit) rawQueue.submit();
+      return first;
+    },
+  };
+  for (const pass of publicWorkloadDescriptor) {
+    for (const draw of pass.draws) events.push(`draw:${pass.name}:${draw}`);
+  }
+  events.push('renderer-finish');
+  const plan = commandBufferPlanForFrame(createShadowSubmitModeState(), [], {
+    label: 'render-system-frame',
+  } as never);
+  expect(plan.ok).toBe(true);
+  if (plan.ok) {
+    for (const submission of plan.value.rawSubmissions) {
+      queue.submit(submission.commandBuffers);
+    }
+  }
+  return { events, rawSubmitCount, rendererSubmitCount };
+}
+
+function assertBoundedSubmission(probe: SubmissionProbe): void {
+  const drawEvents = probe.events.filter((event) => event.startsWith('draw:'));
+  const finishIndex = probe.events.indexOf('renderer-finish');
+  const submitIndex = probe.events.findIndex((event) => event.startsWith('renderer-submit:'));
+
+  expect(drawEvents).toEqual(
+    publicWorkloadDescriptor.flatMap((pass) =>
+      pass.draws.map((draw) => `draw:${pass.name}:${draw}`),
+    ),
+  );
+  expect(finishIndex).toBeGreaterThan(
+    probe.events.indexOf(drawEvents[drawEvents.length - 1] ?? ''),
+  );
+  expect(submitIndex).toBeGreaterThan(finishIndex);
+  expect(probe.rendererSubmitCount).toBe(1);
+  expect(probe.rawSubmitCount).toBe(1);
+}
+
+function findSubmitLines(source: string, pattern: RegExp): number[] {
+  return source.split('\n').flatMap((line, index) => (pattern.test(line) ? [index + 1] : []));
+}
+
+describe('render submission owner admission', () => {
+  it('preserves draw order and finish-before-submit at the renderer seam', () => {
+    const probe = makeProbe(false);
+    assertBoundedSubmission(probe);
+  });
+
+  it('fails the bounded assertion for the matched duplicated-RHI negative control', () => {
+    const pathological = makeProbe(true);
+    expect(() => assertBoundedSubmission(pathological)).toThrow();
+  });
+
+  it('records the renderer-versus-RHI admission result before implementation', () => {
+    const frameTargets = readFileSync(new URL('../frame-targets.ts', import.meta.url), 'utf8');
+    const shadowPass = readFileSync(new URL('../shadow-pass.ts', import.meta.url), 'utf8');
+    const rhiWgpuQueue = readFileSync(
+      new URL('../../../../rhi-wgpu/src/queue.ts', import.meta.url),
+      'utf8',
+    );
+    const rhiWebgpuDevice = readFileSync(
+      new URL('../../../../rhi-webgpu/src/device.ts', import.meta.url),
+      'utf8',
+    );
+    const rendererSubmissionSites = [
+      {
+        file: 'packages/render/src/record/frame-targets.ts',
+        lines: findSubmitLines(frameTargets, /internals\.device\.queue\.submit\s*\(/),
+      },
+      {
+        file: 'packages/render/src/record/shadow-pass.ts',
+        lines: findSubmitLines(shadowPass, /runtime\.device\.queue\.submit\s*\(/),
+      },
+    ];
+    const rhiWrapperSites = [
+      {
+        file: 'packages/rhi-wgpu/src/queue.ts',
+        lines: findSubmitLines(rhiWgpuQueue, /raw\.submit\.call\s*\(/),
+      },
+      {
+        file: 'packages/rhi-webgpu/src/device.ts',
+        lines: findSubmitLines(rhiWebgpuDevice, /rawQueue\.submit\s*\(/),
+      },
+    ];
+    const admission = {
+      status: 'inconclusive',
+      rendererSubmissionSites,
+      rhiWrapperSites,
+      matchedNegativeControl: {
+        variant: 'duplicated-rhi-wrapper-submit',
+        reproducesBoundedFailure: true,
+      },
+      reason:
+        'Renderer record code owns multiple submission boundaries, including the documented shadow depth barrier; the matched RHI control only fails when it is deliberately made to duplicate raw submit. The focused node test cannot attribute the public GPU-process pacing symptom to one renderer submission without backend evidence.',
+    } as const;
+
+    // biome-ignore lint/suspicious/noConsole: admission evidence is the task output
+    console.info(`[m6-owner-admission] ${JSON.stringify(admission)}`);
+    expect(admission.status).toBe('inconclusive');
+    expect(rendererSubmissionSites.some((site) => site.lines.length > 0)).toBe(true);
+    expect(rhiWrapperSites.every((site) => site.lines.length > 0)).toBe(true);
+    expect(admission.matchedNegativeControl.reproducesBoundedFailure).toBe(true);
+  });
+});

package/src/record/__tests__/shadow-submit-mode.unit.test.ts

@@ -0,0 +1,88 @@
+import { expect, test } from 'vitest';
+
+import {
+  SHADOW_SUBMIT_MODES,
+  type ShadowSubmitModeRequest,
+  validateShadowSubmitModeRequest,
+} from '../shadow-submit-mode';
+
+const identity = {
+  carrierId: 'studio-carrier-1',
+  pageIdentity: 'page-1',
+  browserRealmId: 'realm-1',
+  runtimeId: 'runtime-1',
+  canvasIdentity: 'canvas-1',
+  rendererGeneration: 'renderer-generation-1',
+} as const;
+
+function request(overrides: Partial<ShadowSubmitModeRequest> = {}): ShadowSubmitModeRequest {
+  return {
+    schema: 'renderer-owner-admission/v1',
+    shadowSubmitMode: 'independent',
+    identity,
+    ...overrides,
+  };
+}
+
+test('renderer mode exposes exactly the independent and coalesced values', () => {
+  expect(SHADOW_SUBMIT_MODES).toEqual(['independent', 'coalesced-with-frame']);
+  expect(validateShadowSubmitModeRequest(request()).ok).toBe(true);
+  expect(
+    validateShadowSubmitModeRequest(request({ shadowSubmitMode: 'coalesced-with-frame' })).ok,
+  ).toBe(true);
+});
+
+test('renderer mode rejects an unknown mode and preserves a structured recovery error', () => {
+  const result = validateShadowSubmitModeRequest(
+    request({ shadowSubmitMode: 'all-at-once' as never }),
+  );
+
+  expect(result).toMatchObject({
+    ok: false,
+    error: {
+      code: 'renderer-owner-admission-invalid-mode',
+      category: 'precondition',
+      expected: { shadowSubmitMode: SHADOW_SUBMIT_MODES },
+      recoveryActions: ['renderer.ownerAdmission.rediscover'],
+      safeRerun: true,
+    },
+  });
+});
+
+test('renderer mode requires every selected carrier and renderer identity field', () => {
+  for (const field of Object.keys(identity) as Array<keyof typeof identity>) {
+    const incompleteIdentity = { ...identity };
+    delete incompleteIdentity[field];
+    const result = validateShadowSubmitModeRequest(
+      request({ identity: incompleteIdentity as never }),
+    );
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: {
+        code: 'renderer-owner-admission-identity-mismatch',
+        category: 'precondition',
+        expected: { identityFields: Object.keys(identity) },
+        recoveryActions: ['renderer.ownerAdmission.rediscover'],
+        safeRerun: true,
+      },
+    });
+  }
+});
+
+test('renderer mode rejects a generation drift before a frame-boundary apply', () => {
+  const result = validateShadowSubmitModeRequest(
+    request({
+      identity: { ...identity, rendererGeneration: '' },
+    }),
+  );
+
+  expect(result).toMatchObject({
+    ok: false,
+    error: {
+      code: 'renderer-owner-admission-identity-mismatch',
+      observed: { rendererGeneration: '' },
+      recoveryActions: ['renderer.ownerAdmission.rediscover'],
+    },
+  });
+});

package/src/record/__tests__/video-texture-view.unit.test.ts

@@ -0,0 +1,90 @@
+import { World } from '@forgeax/engine-ecs';
+import {
+  VIDEO_ELEMENT_PROVIDER_KEY,
+  type VideoElementProvider,
+} from '@forgeax/engine-graphics-extras';
+import type { Result, RhiError, Texture, TextureView } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import type { Handle } from '@forgeax/engine-types';
+import { toShared } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { type DynamicTextureDevice, DynamicTextureStore } from '../../dynamic-texture-store';
+import type { RenderSystemRuntime } from '../../render-system';
+import { videoTextureView } from '../main-pass-material';
+
+interface Probe {
+  copies: number;
+}
+
+function makeStore(probe: Probe): DynamicTextureStore {
+  let textureId = 0;
+  const device: DynamicTextureDevice = {
+    createTexture: () => ok({ id: `video-texture-${textureId++}` } as unknown as Texture),
+    createTextureView: (texture) => ok({ texture } as unknown as TextureView),
+    destroyTexture: () => ok(undefined) as Result<void, RhiError>,
+    queue: {
+      copyExternalImageToTexture: () => {
+        probe.copies += 1;
+        return ok(undefined) as Result<void, RhiError>;
+      },
+    },
+  };
+  const store = new DynamicTextureStore();
+  store.configureGpuDevice(device);
+  return store;
+}
+
+function runtimeWithErrors(fire: (error: { readonly code: string }) => void): RenderSystemRuntime {
+  return { errorRegistry: { fire } } as unknown as RenderSystemRuntime;
+}
+
+const CLIP = toShared<'VideoAsset'>(7001) as Handle<'VideoAsset', 'shared'>;
+const ENTITY = 17;
+const VIDEO = {
+  videoWidth: 8,
+  videoHeight: 8,
+  readyState: 2,
+} as unknown as HTMLVideoElement;
+
+describe('videoTextureView provider-loss recovery', () => {
+  it('keeps the LKG view, bounds each loss episode, and clears it after upload recovery', () => {
+    const world = new World();
+    const probe: Probe = { copies: 0 };
+    const store = makeStore(probe);
+    const errors: { readonly code: string }[] = [];
+    const runtime = runtimeWithErrors((error) => errors.push(error));
+    const provider: VideoElementProvider = {
+      getElement: vi.fn(() => VIDEO),
+    };
+    world.insertResource(VIDEO_ELEMENT_PROVIDER_KEY, provider);
+
+    const lkg = videoTextureView(world, store, runtime, ENTITY, CLIP, false);
+    expect(lkg).toBeDefined();
+    expect(probe.copies).toBe(1);
+
+    world.removeResource(VIDEO_ELEMENT_PROVIDER_KEY);
+    expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
+    expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
+    expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]?.code).toBe('video-upload-unsupported');
+    expect(probe.copies).toBe(1);
+
+    world.insertResource(VIDEO_ELEMENT_PROVIDER_KEY, provider);
+    expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
+    expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
+    expect(errors).toHaveLength(1);
+    expect(probe.copies).toBe(3);
+
+    world.removeResource(VIDEO_ELEMENT_PROVIDER_KEY);
+    expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
+    expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
+    expect(errors).toHaveLength(2);
+    expect(probe.copies).toBe(3);
+
+    world.insertResource(VIDEO_ELEMENT_PROVIDER_KEY, provider);
+    expect(videoTextureView(world, store, runtime, ENTITY, CLIP, false)).toBe(lkg);
+    expect(errors).toHaveLength(2);
+    expect(probe.copies).toBe(4);
+  });
+});

package/src/record/__tests__/view-ubo-layout.unit.test.ts

@@ -0,0 +1,101 @@
+import { vec3 } from '@forgeax/engine-math';
+import type { Buffer, RhiQueue } from '@forgeax/engine-rhi';
+import { ok } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import type {
+  CameraSnapshot,
+  DirectionalLightSnapshot,
+  ExtractedLights,
+  FogSnapshot,
+} from '../../render-system-extract';
+import { VIEW_UNIFORM_BYTES, VIEW_UNIFORM_SLOT_STRIDE, writeViewUbo } from '../view-ubo';
+
+function camera(): CameraSnapshot {
+  return {
+    worldId: 0,
+    entityKey: 0,
+    position: vec3.create(0, 1, 3),
+    world: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 1, 3, 1]),
+    fov: Math.PI / 4,
+    aspect: 1,
+    near: 0.1,
+    far: 100,
+    projection: 'perspective',
+    orthoLeft: -1,
+    orthoRight: 1,
+    orthoBottom: -1,
+    orthoTop: 1,
+    tonemap: 'none',
+    exposure: 1,
+    whitePoint: 4,
+    antialias: 'none',
+    historyVersion: 0,
+    bloom: 'off',
+    bloomThreshold: 1,
+    bloomIntensity: 1,
+    bloomBlurRadius: 4,
+    clearColor: [0, 0, 0, 1],
+  };
+}
+
+const light: DirectionalLightSnapshot = {
+  kind: 'directional',
+  direction: vec3.create(0, -1, 0),
+  color: vec3.create(1, 1, 1),
+  intensity: 1,
+};
+
+const lights = {
+  directional: light,
+  directionalCount: 1,
+  point: [],
+  spot: [],
+  lightViewProj: undefined,
+  splitPlanes: undefined,
+  cascadeCount: undefined,
+  cascadeBlend: undefined,
+  depthBias: undefined,
+  normalBias: undefined,
+  pcfKernelSize: undefined,
+  pointShadow: [],
+} as unknown as ExtractedLights;
+
+function capture(fog: FogSnapshot): Float32Array {
+  let payload: Float32Array | undefined;
+  const queue = {
+    writeBuffer: (_buffer: Buffer, _offset: number, data: ArrayBufferView | ArrayBuffer) => {
+      payload = new Float32Array((data as ArrayBufferView).buffer);
+      return ok(undefined);
+    },
+  } as unknown as RhiQueue;
+  writeViewUbo(queue, {} as Buffer, camera(), light, lights, [], undefined, fog);
+  if (payload === undefined) throw new Error('writeViewUbo did not write');
+  return payload;
+}
+
+describe('View UBO Fog payload ABI', () => {
+  it('derives a 16-byte aligned payload inside the existing View slot', () => {
+    expect(VIEW_UNIFORM_BYTES).toBeGreaterThan(928);
+    expect(VIEW_UNIFORM_BYTES % 16).toBe(0);
+    expect(VIEW_UNIFORM_BYTES).toBeLessThanOrEqual(VIEW_UNIFORM_SLOT_STRIDE);
+  });
+
+  it('packs color, density, heightFalloff, and maxOpacity after existing View facts', () => {
+    const payload = capture({
+      color: [0.2, 1.5, 3.0],
+      density: 0.035,
+      heightFalloff: 0.28,
+      maxOpacity: 0.92,
+      revision: 7,
+    });
+    expect(payload.length).toBe(VIEW_UNIFORM_BYTES / 4);
+    expect(payload[232]).toBeCloseTo(0.2, 6);
+    expect(payload[233]).toBeCloseTo(1.5, 6);
+    expect(payload[234]).toBeCloseTo(3.0, 6);
+    expect(payload[235]).toBeCloseTo(0.035, 6);
+    expect(payload[236]).toBeCloseTo(0.28, 6);
+    expect(payload[237]).toBeCloseTo(0.92, 6);
+    expect(payload[238]).toBe(0);
+    expect(payload[239]).toBe(0);
+  });
+});