Skip to content

3D engine that AI agents drive

15.3 KB
Raw Blame
import assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
import test from 'node:test';
import { cookInstalled, cookModule, cookTest } from './support/cook.js';
import { exportNativeSceneTables } from '../scripts/native-bake-page.js';
import { box } from '../src/geometry.js';
import { createCamera } from '../src/path-tracer.js';
import * as pack from '../src/path-tracer-gpu-pack.js';
import { buildTraceScene, partRayVisibilityFlags, RAY_VISIBILITY_BITS, refuseLocalVolumes, resolveTexture } from '../src/path-tracer-scene.js';

const cook = await cookModule();
const packV2 = await cookModule('pack-input-v2');
const jobInputModule = await cookModule('job-input');
const { buildNativeInput, buildNativeTexelInput, findNativeAddon, traceNative } = cook ?? {};
const { STRUCT_STRIDES_V2 } = packV2 ?? {};
const { buildFlattenedJobNativeInput, buildJobNativeInput } = jobInputModule ?? {};

const INSTANCE_VISIBILITY_OFFSET = 116;
const ALL_RAY_KINDS = 63;
const SHADOW_OFF = ALL_RAY_KINDS & ~RAY_VISIBILITY_BITS.shadow;
const WIDTH = 8;
const HEIGHT = 8;
const camera = createCamera({ eye: [0, 0, 8], target: [0, 0, 0], fov: 50 }, WIDTH, HEIGHT);
const options = { width: WIDTH, height: HEIGHT, samples: 4, bounces: 2, seed: 1, noiseThreshold: 0 };
const environment = { keyColor: [3, 3, 3], lightDirection: [0.4, 0.8, 0.5] };
const modules = { buildTraceScene, refuseLocalVolumes, resolveTexture, buildNativeInput, buildJobNativeInput, buildFlattenedJobNativeInput, pack };

const sharedBox = box(0, 1);
const translate = x => new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, 0, 0, 1]);
const surface = { tag: 'surface', color: [0.5, 0.5, 0.5], roughness: 0.8, metallic: 0 };

function sharedPart(name, x, extra = {}) {
  return { name, geometry: sharedBox, matrix: translate(x), material: surface, ...extra };
}

function uniquePart(name, x, extra = {}) {
  return { name, geometry: box(0, 1), matrix: translate(x), material: surface, ...extra };
}

function exportedVisibility(parts, instancing) {
  const exported = exportNativeSceneTables({ parts, environment, camera, options, kernel: 'cycles', instancing, modules });
  const bytes = Buffer.from(exported.tables.instances, 'base64');
  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
  const flags = [];
  for (let index = 0; index < bytes.byteLength / STRUCT_STRIDES_V2.instance; index++) {
    flags.push(view.getUint32(index * STRUCT_STRIDES_V2.instance + INSTANCE_VISIBILITY_OFFSET, true) & ALL_RAY_KINDS);
  }
  return { exported, flags };
}

function digestOfTables(exported) {
  const hash = createHash('sha256');
  for (const name of Object.keys(exported.tables).sort()) hash.update(name).update(exported.tables[name]);
  return hash.digest('hex');
}

test('the bits are the FORMAT-v2 instance visibility layout', () => {
  assert.deepEqual({ ...RAY_VISIBILITY_BITS }, { camera: 1, diffuse: 2, glossy: 4, transmission: 8, shadow: 16, volumeScatter: 32 });
});

test('a part maps rayVisibility and shadowOnly to visibility bits', () => {
  assert.equal(partRayVisibilityFlags({}), ALL_RAY_KINDS);
  assert.equal(partRayVisibilityFlags({ rayVisibility: {} }), ALL_RAY_KINDS);
  assert.equal(partRayVisibilityFlags({ rayVisibility: { shadow: true, camera: true } }), ALL_RAY_KINDS);
  assert.equal(partRayVisibilityFlags({ rayVisibility: { shadow: false } }), SHADOW_OFF);
  assert.equal(partRayVisibilityFlags({ rayVisibility: { camera: false, glossy: false } }), ALL_RAY_KINDS & ~1 & ~4);
  assert.equal(partRayVisibilityFlags({ rayVisibility: { diffuse: false, transmission: false, volumeScatter: false } }), 1 | 4 | 16);
  assert.equal(partRayVisibilityFlags({ shadowOnly: true }), 62);
  assert.equal(partRayVisibilityFlags({ shadowOnly: true, rayVisibility: { glossy: false } }), 62 & ~4);
});

cookTest('castShadow never reaches the ray visibility, because library code sets it as a raster default', () => {
  assert.equal(partRayVisibilityFlags({ castShadow: false }), ALL_RAY_KINDS);
  const castingOff = [uniquePart('a', 0, { castShadow: false }), uniquePart('b', 2, { castShadow: false, shadowOnly: true })];
  assert.equal(buildTraceScene(castingOff, environment).partRayVisibility, null);
  const instanced = buildTraceScene([sharedPart('a', 0, { castShadow: false }), sharedPart('b', 2)], environment, { instancing: true });
  assert.equal(instanced.instances.some(instance => 'visibilityFlags' in instance), false);
  const plainFlattened = [uniquePart('a', 0), uniquePart('b', 2, { shadowOnly: true })];
  assert.equal(digestOfTables(exportedVisibility(castingOff, false).exported), digestOfTables(exportedVisibility(plainFlattened, false).exported));
  const plainShared = [sharedPart('a', 0), sharedPart('b', 2)];
  const castingOffShared = plainShared.map(part => ({ ...part, castShadow: false }));
  assert.equal(digestOfTables(exportedVisibility(castingOffShared, true).exported), digestOfTables(exportedVisibility(plainShared, true).exported));
});

test('a bad rayVisibility says what to pass', () => {
  assert.throws(() => partRayVisibilityFlags({ name: 'pane', rayVisibility: 'shadow' }), /part "pane" rayVisibility must be an object such as \{ shadow: false \}/);
  assert.throws(() => partRayVisibilityFlags({ rayVisibility: [] }), /part 0 rayVisibility must be an object/);
  assert.throws(() => partRayVisibilityFlags({ name: 'pane', rayVisibility: { refraction: false } }), /unknown ray kind "refraction": use camera, diffuse, glossy, transmission, shadow, volumeScatter/);
  assert.throws(() => partRayVisibilityFlags({ name: 'pane', rayVisibility: { shadow: 0 } }), /rayVisibility\.shadow must be true or false, got 0/);
  assert.throws(() => partRayVisibilityFlags({ name: 'ghost', shadowOnly: true, rayVisibility: { shadow: false } }), /shadowOnly with rayVisibility\.shadow: false/);
});

test('an emitter may hide from camera, shadow and volume rays but not from bounce rays, which would drop part of its light', () => {
  const lamp = { tag: 'surface', color: [1, 0.8, 0.6], emission: 4, roughness: 1 };
  assert.equal(partRayVisibilityFlags({ material: lamp, rayVisibility: { camera: false } }), ALL_RAY_KINDS & ~1);
  assert.equal(partRayVisibilityFlags({ material: lamp, rayVisibility: { shadow: false, volumeScatter: false } }), ALL_RAY_KINDS & ~16 & ~32);
  for (const kind of ['diffuse', 'glossy', 'transmission']) {
    assert.throws(() => partRayVisibilityFlags({ name: 'lamp', material: lamp, rayVisibility: { [kind]: false } }), /part "lamp" emits light and sets rayVisibility\.diffuse, glossy or transmission to false/);
  }
  assert.equal(partRayVisibilityFlags({ material: surface, rayVisibility: { diffuse: false } }), ALL_RAY_KINDS & ~2, 'a part that does not emit may hide from bounce rays');
  const parts = [uniquePart('wall', 0), uniquePart('lamp', 2, { material: lamp, rayVisibility: { glossy: false } })];
  assert.throws(() => buildTraceScene(parts, environment), /part "lamp" emits light/);
  assert.throws(() => buildTraceScene(parts.map(part => ({ ...part, geometry: sharedBox })), environment, { instancing: true }), /part "lamp" emits light/);
});

test('buildTraceScene refuses a bad rayVisibility on both scene shapes', () => {
  const flattened = [uniquePart('a', 0, { rayVisibility: { shadow: 'no' } }), uniquePart('b', 2)];
  assert.throws(() => buildTraceScene(flattened, environment), /part "a" rayVisibility\.shadow must be true or false/);
  const instanced = [sharedPart('a', 0, { rayVisibility: { bogus: false } }), sharedPart('b', 2)];
  assert.throws(() => buildTraceScene(instanced, environment, { instancing: true }), /unknown ray kind "bogus"/);
});

test('an instanced scene carries visibility only on the parts that hide from a ray kind', () => {
  const parts = [
    sharedPart('plain', 0),
    sharedPart('pane', 2, { rayVisibility: { shadow: false } }),
    sharedPart('glow', 4, { rayVisibility: { camera: false, shadow: false } }),
    sharedPart('empty', 6, { rayVisibility: {} }),
  ];
  const scene = buildTraceScene(parts, environment, { instancing: true });
  assert.equal('visibilityFlags' in scene.instances[0], false, 'a default part adds no field');
  assert.equal(scene.instances[1].visibilityFlags, SHADOW_OFF);
  assert.equal(scene.instances[2].visibilityFlags, ALL_RAY_KINDS & ~1 & ~16);
  assert.equal('visibilityFlags' in scene.instances[3], false, 'an empty rayVisibility is the default');
});

test('a flattened scene carries one visibility byte per part, or none when no part hides from a ray kind', () => {
  assert.equal(buildTraceScene([uniquePart('a', 0), uniquePart('b', 2, { shadowOnly: true })], environment).partRayVisibility, null);
  const hidingNothing = [uniquePart('a', 0, { rayVisibility: {} }), uniquePart('b', 2, { rayVisibility: { shadow: true, camera: true } })];
  assert.equal(buildTraceScene(hidingNothing, environment).partRayVisibility, null);
  const hiding = [uniquePart('a', 0), uniquePart('b', 2, { rayVisibility: { shadow: false } }), uniquePart('c', 4, { shadowOnly: true, rayVisibility: { glossy: false } })];
  assert.deepEqual([...buildTraceScene(hiding, environment).partRayVisibility], [ALL_RAY_KINDS, SHADOW_OFF, 62 & ~4]);
});

cookTest('a native render job packs the visibility of an instanced scene into the instance table', () => {
  const parts = [sharedPart('wall', 0), sharedPart('pane', 2, { rayVisibility: { shadow: false } }), sharedPart('wall2', 4)];
  const { exported, flags } = exportedVisibility(parts, true);
  assert.equal(exported.instances, 3, 'the copies stay instances');
  assert.deepEqual(flags, [ALL_RAY_KINDS, SHADOW_OFF, ALL_RAY_KINDS]);
});

cookTest('a native render job packs the visibility of a flattened scene into the instance table', () => {
  const parts = [uniquePart('wall', 0), uniquePart('pane', 2, { rayVisibility: { shadow: false } }), uniquePart('lamp', 4, { shadowOnly: true })];
  const { exported, flags } = exportedVisibility(parts, false);
  assert.equal(exported.schemaVersion, 2);
  assert.deepEqual(flags, [ALL_RAY_KINDS, SHADOW_OFF, 62]);
});

cookTest('scenes whose rayVisibility hides nothing export the same tables as scenes without it', () => {
  const plain = [uniquePart('wall', 0), uniquePart('lamp', 4, { shadowOnly: true })];
  const withDefaults = [uniquePart('wall', 0, { rayVisibility: {} }), uniquePart('lamp', 4, { shadowOnly: true, rayVisibility: { shadow: true } })];
  assert.equal(digestOfTables(exportedVisibility(withDefaults, false).exported), digestOfTables(exportedVisibility(plain, false).exported));
  const sharedPlain = [sharedPart('a', 0), sharedPart('b', 2, { shadowOnly: true })];
  const sharedDefaults = [sharedPart('a', 0, { rayVisibility: {} }), sharedPart('b', 2, { shadowOnly: true, rayVisibility: { camera: true } })];
  assert.equal(digestOfTables(exportedVisibility(sharedDefaults, true).exported), digestOfTables(exportedVisibility(sharedPlain, true).exported));
});

function withoutRayVisibility(parts) {
  return parts.map(({ rayVisibility, ...part }) => part);
}

cookTest('the v1 tables of the legacy kernel refuse a hidden ray kind, and a light bake leaves it out', () => {
  const hiding = [uniquePart('wall', 0), uniquePart('pane', 2, { rayVisibility: { shadow: false } })];
  const scene = buildTraceScene(hiding, environment);
  assert.throws(() => buildNativeInput(scene, camera, options, pack), /v1 tables of kernel "legacy" cannot carry.*kernel "cycles"/);
  const bakeOptions = { texelCount: 4, samples: 4, bounces: 2, seed: 1 };
  const plainScene = buildTraceScene(withoutRayVisibility(hiding), environment);
  assert.deepEqual(buildNativeTexelInput(scene, bakeOptions, pack), buildNativeTexelInput(plainScene, bakeOptions, pack));
});

test('a job on the legacy kernel refuses a hidden ray kind', () => {
  const parts = [uniquePart('wall', 0), uniquePart('pane', 2, { rayVisibility: { shadow: false } })];
  assert.throws(
    () => exportNativeSceneTables({ parts, environment, camera, options, kernel: 'legacy', instancing: false, modules }),
    /only the "cycles" kernel can carry/,
  );
});

cookTest('the v1 fallback of a cycles job draws without the visibility and reports why', () => {
  const parts = [uniquePart('wall', 0), uniquePart('pane', 2, { rayVisibility: { shadow: false } })];
  const failingModules = { ...modules, buildFlattenedJobNativeInput: () => { throw new Error('forced material failure'); } };
  const exported = exportNativeSceneTables({ parts, environment, camera, options, kernel: 'cycles', instancing: false, modules: failingModules });
  assert.equal(exported.wholeMaterials, false);
  assert.equal(exported.materialsReason, 'forced material failure');
  assert.equal(exported.rayVisibility, 'ignored');
  assert.equal(exported.rayVisibilityReason, 'forced material failure');
  const withoutSetting = exportNativeSceneTables({ parts: withoutRayVisibility(parts), environment, camera, options, kernel: 'cycles', instancing: false, modules: failingModules });
  assert.deepEqual(exported.tables, withoutSetting.tables);
});

// The sun is a delta light: only a shadow ray can reach it. Measured on the native kernel, the mean of the top-down picture
// is about 5.6 with the clear pane blocking shadow rays (the floor is dimmer, not black) and about 9.3 once it does not.
const skipWithoutAddon = !cookInstalled || findNativeAddon() === null ? 'the native addon is not built' : false;
const SIZE = 16;
const sunEnvironment = { keyColor: [3, 3, 3], lightDirection: [0, 1, 0] };
const topDownCamera = createCamera({ eye: [0, 6, 0], target: [0, 0, 0], up: [0, 0, -1], fov: 30 }, SIZE, SIZE);
const clearGlass = { tag: 'surface', color: [1, 1, 1], roughness: 0, metallic: 0, transmission: 1, ior: 1.5 };

function scaled(translation, scale) {
  return new Float32Array([scale[0], 0, 0, 0, 0, scale[1], 0, 0, 0, 0, scale[2], 0, translation[0], translation[1], translation[2], 1]);
}

function paneOverFloor(paneExtra, geometryFor) {
  return [
    { name: 'floor', geometry: geometryFor('floor'), matrix: scaled([0, -0.05, 0], [20, 0.1, 20]), material: surface },
    { name: 'pane', geometry: geometryFor('pane'), matrix: scaled([0, 1.5, 0], [6, 0.004, 6]), material: clearGlass, ...paneExtra },
  ];
}

function floorBrightness(parts, instancing) {
  const scene = buildTraceScene(parts, sunEnvironment, { instancing });
  assert.equal(Boolean(scene.instances), instancing, 'the scene has the shape under test');
  const tracedOptions = { width: SIZE, height: SIZE, samples: 64, bounces: 4, seed: 3, noiseThreshold: 0 };
  const input = instancing
    ? buildJobNativeInput(scene, topDownCamera, tracedOptions, pack, resolveTexture)
    : buildFlattenedJobNativeInput(scene, topDownCamera, tracedOptions, pack, resolveTexture);
  const rgba = traceNative(input, { width: SIZE, height: SIZE, samples: 64, kernel: 'cycles' }).rgba;
  let sum = 0;
  for (let pixel = 0; pixel < SIZE * SIZE; pixel++) sum += rgba[pixel * 4] + rgba[pixel * 4 + 1] + rgba[pixel * 4 + 2];
  return sum / (SIZE * SIZE);
}

for (const [shape, instancing, geometryFor] of [
  ['flattened', false, () => box(0, 1)],
  ['instanced', true, () => sharedBox],
]) {
  cookTest(`the native cycles kernel lights the floor through a ${shape} pane with rayVisibility shadow false`, { skip: skipWithoutAddon }, () => {
    const blocked = floorBrightness(paneOverFloor({}, geometryFor), instancing);
    const lit = floorBrightness(paneOverFloor({ rayVisibility: { shadow: false } }, geometryFor), instancing);
    assert.ok(lit > blocked * 1.3, `shadow rays that pass the pane reach the sun: ${lit} against ${blocked}`);
    assert.ok(lit - blocked > 2, `the sun reaches the floor through the pane: ${lit} less ${blocked}`);
  });
}