Skip to content

3D engine that AI agents drive

6.2 KB
Raw Blame
import { buildTraceScene, buildTraceSceneForDevice, refuseLocalVolumes } from './path-tracer-scene.js';
import { checkBudget, checkedBakeSize, finishLightmaps, planLightmaps, rasterizeEntries, traceLightmaps } from './light-bake.js';

// The GPU side of the light bake: the texels of every part go to the path tracer's kernel in one batch, which starts a
// cosine weighted path at each texel and returns the light that arrives. The CPU gatherer in light-bake.js stays the
// reference. This module holds the asynchronous bake API, so the CPU bake and every bundle that uses it carry none of this.

const BAKE_SEED = 1;
// The bake keeps every bright sample (the CPU gatherer has no clamp), so the kernel's firefly clamp is set out of reach.
const NO_FIREFLY_CLAMP = 1e6;

/** The plan's lights in the shapes the path tracer reads. A light limited by `affects` cannot be traced: the kernel has no light linking. */
function traceEnvironment({ lights }) {
  const linked = [...lights.pointLights, ...lights.spotLights, ...lights.areaLights, ...(lights.sun ? [lights.sun] : [])].some(light => light.affects !== null);
  if (linked) throw new RangeError('A light bake on the GPU backend does not support light linking (`affects`). Use the CPU backend.');
  return {
    pointLights: lights.pointLights,
    spotLights: lights.spotLights.map(light => ({ ...light, angle: Math.acos(light.cosineHalfAngle), penumbra: light.cosineHalfAngle < 1 ? light.blend / (1 - light.cosineHalfAngle) : 0 })),
    areaLights: lights.areaLights.map(light => ({ ...light, direction: light.normal, up: light.along })),
    keyColor: lights.sun?.color ?? [0, 0, 0],
    lightDirection: lights.sun?.direction ?? [0, 1, 0],
  };
}

/** The covered texels of all parts as one list of world points and normals, and where each part's slice starts. */
function packCoveredTexels(rasterized) {
  let count = 0;
  for (const { covered } of rasterized) for (const flag of covered) count += flag;
  const points = new Float32Array(count * 3);
  const normals = new Float32Array(count * 3);
  const slices = [];
  let next = 0;
  for (const { positions, normals: texelNormals, covered } of rasterized) {
    const texelIndices = [];
    for (let texel = 0; texel < covered.length; texel++) {
      if (!covered[texel]) continue;
      points.set(positions.subarray(texel * 3, texel * 3 + 3), next * 3);
      normals.set(texelNormals.subarray(texel * 3, texel * 3 + 3), next * 3);
      texelIndices.push(texel);
      next++;
    }
    slices.push(texelIndices);
  }
  return { count, points, normals, slices };
}

/**
 * Traces every covered texel on the GPU and resolves with `entries` (per rasterized part, `light` and `escaped` in the
 * layout the CPU gatherer returns), the `gpu` name and the kernel's `compileSeconds`.
 */
/** The backend module of a bake; each is loaded only when a bake asks for it. */
async function loadBackendModule(backend) {
  if (backend === 'native') throw new RangeError('A light bake on the native backend needs a `texelTracer` function in its settings: the native tracer runs outside the page.');
  return backend === 'webgpu' ? import('./path-tracer-webgpu.js') : import('./path-tracer-gpu.js');
}

async function gatherOnGpu(plan, settings, rasterized, shouldStop) {
  const environment = traceEnvironment(plan);
  const texels = packCoveredTexels(rasterized);
  // A `texelTracer` of the settings (the native tracer) runs outside the page and keeps the default bound; the GPU backends bound the scene by their device.
  const backendModule = settings.texelTracer ? null : await loadBackendModule(settings.backend);
  const scene = backendModule ? await buildTraceSceneForDevice(plan.parts, environment, backendModule) : buildTraceScene(plan.parts, environment);
  refuseLocalVolumes(scene, 'the GPU light bake');
  const traceTexels = settings.texelTracer ?? (settings.backend === 'webgpu' ? backendModule.traceTexelsOnWebGpu : backendModule.traceTexelsOnGpu);
  const traced = await traceTexels(scene, texels, { samples: settings.samples, bounces: settings.bounces, seed: BAKE_SEED, fireflyClamp: NO_FIREFLY_CLAMP }, shouldStop);
  let next = 0;
  const entries = rasterized.map(({ resolution }, entryNumber) => {
    const light = new Float32Array(resolution * resolution * 3);
    const escaped = new Float32Array(resolution * resolution);
    for (const texel of texels.slices[entryNumber]) {
      light.set(traced.radiance.subarray(next * 3, next * 3 + 3), texel * 3);
      escaped[texel] = traced.escaped[next];
      next++;
    }
    return { light, escaped };
  });
  return { entries, gpu: traced.gpu, compileSeconds: traced.compileSeconds };
}

/** `traceLightmaps` for either backend: the CPU trace as it is, or the same steps with the texels gathered by the kernel. */
export async function traceLightmapsAsync(plan, tracedSettings) {
  const settings = { ...plan.settings, ...tracedSettings };
  if (settings.backend === 'cpu') return traceLightmaps(plan, settings);
  if (settings.skyOnly) throw new RangeError('A sky visibility bake runs on the CPU backend only.');
  const sizes = checkedBakeSize(plan, settings);
  const rasterized = rasterizeEntries(plan, settings);
  const gathered = await gatherOnGpu(plan, settings, rasterized, () => checkBudget(plan, settings));
  const result = finishLightmaps(plan, settings, rasterized, gathered.entries, sizes);
  return { parts: result.parts, report: { ...result.report, gpu: gathered.gpu, gpuCompileSeconds: gathered.compileSeconds } };
}

/**
 * `bakeLightmaps` with a choice of tracer: `options.backend` is "cpu" (the default, the reference) or "gpu", which traces the
 * texels with the GPU path tracer's kernel and needs a page with WebGL2, or "webgpu", which runs the WGSL kernel and needs `navigator.gpu`,
 * or "native", which hands the texels to `options.texelTracer` (the hardware ray query tracer outside the page, see
 * scripts/native-bake-page.js). Resolves with the same `{ parts, report }`;
 * `report.backend` names the tracer, and a GPU, WebGPU or native bake adds `gpu` and `gpuCompileSeconds`.
 */
export async function bakeLightmapsAsync(parts, lighting, options = {}) {
  const plan = planLightmaps(parts, lighting, options);
  return traceLightmapsAsync(plan, { ...plan.settings, skyOnly: options.skyOnly === true, ...(options.texelTracer ? { texelTracer: options.texelTracer } : {}) });
}