Skip to content

3D engine that AI agents drive

8.8 KB
Raw Blame
import { buildTraceScene, refuseLocalVolumes } from './path-tracer-scene.js';
import { createCamera } from './path-tracer.js';
import { getContext, gpuTriangleLimit, getKernel, releaseResources, setSceneUniforms, uploadScene } from './path-tracer-gpu.js';
import { sceneUsesSubsurface } from './path-tracer-gpu-pack.js';
import { createRadianceCache } from './path-tracer-radiance-cache.js';
import { createTemporalDenoiser } from './path-tracer-temporal-denoise.js';
import { createFloatTexture, createFramebuffer, FIRST_PASS_TEXTURE_UNIT } from './path-tracer-realtime-gl.js';
import { cacheCellSizes, noteIgnoredClipStart, resolveRealtimeOptions, viewsMatch } from './path-tracer-realtime-options.js';

// A real-time hybrid view of the GPU path tracer (issue #624): one path per pixel and frame at half the output size,
// two bounces, ended by a spatial hash radiance cache, then a temporal denoiser that also upsamples to the output size.
// `frame(camera)` draws one picture to `canvas`. Primary hits are traced, not rasterized (the tracer's first hit already
// gives the albedo, normal and distance a G-buffer would), and motion vectors come from the camera's move (the scene is
// static). It shares the WebGL2 context of `traceOnGpu`, so one render at a time owns it. The pieces:
//   path-tracer-radiance-cache.js, path-tracer-temporal-denoise.js, path-tracer-reprojection.js.

// Builds and checks a scene before any GL object is made or released, so a refused scene leaves the tracer as it was.
function prepareTraceScene(parts, environment) {
  const traceScene = buildTraceScene(parts, environment, { gpuTriangleLimit: gpuTriangleLimit() });
  refuseLocalVolumes(traceScene, 'the WebGL realtime path tracer');
  return traceScene;
}

/**
 * `scene` is `{ parts, environment, camera }` as `renderPathTracedImage` takes them. `options`: `width` and `height` of the
 * output, `bounces` (2), `resolutionDivisor` (2: the tracing size is half the output), `seed`, `lightSelection`
 * ("importance"), `historyLimit` and `filterIterations` of the denoiser, `cacheCellSize` (the scene's size over 200).
 * The picture is tone mapped with ACES like the default view transform. `backend` is "gpu" (WebGL2, the default) or
 * "webgpu" (compute passes, path-tracer-realtime-webgpu.js): without WebGPU on the page, "webgpu" falls back to WebGL2, and
 * the tracer's `backend` and `fallbackReason` say so. The WebGPU tracer draws to its own `canvas` (or the one in
 * `options.canvas`), and its `readFrame` and `frame({ wait })` return promises.
 */
export async function createRealtimeTracer(scene, rawOptions = {}) {
  const resolved = resolveRealtimeOptions(rawOptions);
  let fallbackReason = null;
  if (resolved.backend === 'webgpu') {
    try {
      const { createWebGpuRealtimeTracer } = await import('./path-tracer-realtime-webgpu.js');
      return await createWebGpuRealtimeTracer(scene, resolved, rawOptions.canvas);
    } catch (error) {
      fallbackReason = error.message;
    }
  }
  const { outputWidth, outputHeight, traceWidth, traceHeight, options, historyLimit, filterIterations, cacheCellSize } = resolved;
  const { gl, gpu } = getContext();
  if (gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS) < FIRST_PASS_TEXTURE_UNIT + 12) throw new Error('The real-time path tracer needs 28 texture units.');
  gl.canvas.width = outputWidth;
  gl.canvas.height = outputHeight;

  const firstTraceScene = prepareTraceScene(scene.parts, scene.environment ?? {});
  const radianceTextures = [createFloatTexture(gl, traceWidth, traceHeight), createFloatTexture(gl, traceWidth, traceHeight)];
  const normalTextures = [createFloatTexture(gl, traceWidth, traceHeight), createFloatTexture(gl, traceWidth, traceHeight)];
  const albedoTexture = createFloatTexture(gl, traceWidth, traceHeight);
  const recordTexture = createFloatTexture(gl, traceWidth, traceHeight);
  const traceFramebuffers = [0, 1].map(index => createFramebuffer(gl, [
    { slot: 0, texture: radianceTextures[index] }, { slot: 1, texture: albedoTexture }, { slot: 2, texture: normalTextures[index] }, { slot: 4, texture: recordTexture },
  ]));
  const cache = createRadianceCache(gl);
  const denoiser = createTemporalDenoiser(gl, { traceWidth, traceHeight, outputWidth, outputHeight, historyLimit, filterIterations });
  const synchronizationPixel = new Uint8Array(4);

  let traceScene = null;
  let program = null;
  let lightCount = 0;
  let cacheTextureUnit = 0;
  let compileSeconds = 0;
  let currentSet = 0;
  let frameIndex = 0;
  let view = null;
  let previousView = null;
  let resetHistory = true;
  let disposed = false;

  const loadScene = nextTraceScene => {
    releaseResources(gl);
    traceScene = nextTraceScene;
    const kernel = getKernel(sceneUsesSubsurface(traceScene.materials), false, options);
    program = kernel.program;
    compileSeconds = kernel.compileSeconds;
    gl.useProgram(program);
    const uploaded = uploadScene(gl, program, traceScene, options);
    lightCount = uploaded.lightCount;
    cacheTextureUnit = uploaded.nextUnit;
    gl.uniform1i(gl.getUniformLocation(program, 'uRadianceCache'), cacheTextureUnit);
    const { cellSize, levelDistance } = cacheCellSizes(traceScene, cacheCellSize);
    gl.uniform1f(gl.getUniformLocation(program, 'uCacheCellSize'), cellSize);
    gl.uniform1f(gl.getUniformLocation(program, 'uCacheLevelDistance'), levelDistance);
    cache.clear();
    view = null;
    resetHistory = true;
  };

  const dispose = () => {
    disposed = true;
    cache.dispose();
    denoiser.dispose();
    for (const texture of [...radianceTextures, ...normalTextures, albedoTexture, recordTexture]) gl.deleteTexture(texture);
    for (const framebuffer of traceFramebuffers) gl.deleteFramebuffer(framebuffer);
    releaseResources(gl);
  };

  try {
    loadScene(firstTraceScene);
  } catch (error) {
    dispose();
    throw error;
  }

  const traceOneSample = () => {
    gl.useProgram(program);
    gl.uniform1i(gl.getUniformLocation(program, 'uSample'), frameIndex + 1);
    gl.activeTexture(gl.TEXTURE0 + cacheTextureUnit);
    gl.bindTexture(gl.TEXTURE_2D, cache.texture);
    gl.bindFramebuffer(gl.FRAMEBUFFER, traceFramebuffers[currentSet]);
    gl.viewport(0, 0, traceWidth, traceHeight);
    gl.disable(gl.BLEND);
    gl.disable(gl.SCISSOR_TEST);
    gl.drawArrays(gl.TRIANGLES, 0, 3);
  };

  const ignoredNotes = [];
  return {
    gpu,
    backend: 'gpu',
    fallbackReason,
    ignored: ignoredNotes,
    canvas: gl.canvas,
    width: outputWidth,
    height: outputHeight,
    traceWidth,
    traceHeight,
    get compileSeconds() { return compileSeconds; },
    get frameCount() { return frameIndex; },

    /** A new scene: the radiance cache and the denoiser's history start over. */
    update({ parts, environment }) {
      if (parts) loadScene(prepareTraceScene(parts, environment ?? {}));
    },

    /** Forgets the denoiser's history (the cache stays: it only depends on the scene). */
    resetHistory() {
      resetHistory = true;
    },

    /** Draws one frame to `canvas` for a camera. With `wait` the call returns once the GPU is done, for timing. */
    frame(camera, { wait = false } = {}) {
      if (disposed) throw new Error('This real-time tracer was disposed.');
      const nextView = createCamera(camera, outputWidth, outputHeight);
      noteIgnoredClipStart(ignoredNotes, nextView);
      previousView = view ?? nextView;
      if (!viewsMatch(view, nextView)) {
        gl.useProgram(program);
        setSceneUniforms(gl, program, traceScene, nextView, options, lightCount);
      }
      view = nextView;
      traceOneSample();
      cache.update(recordTexture, traceWidth, traceHeight);
      denoiser.run({
        radiance: radianceTextures[currentSet], albedo: albedoTexture, normal: normalTextures[currentSet],
        previousRadiance: radianceTextures[1 - currentSet], previousNormal: normalTextures[1 - currentSet],
        camera: view, previousCamera: previousView, resetHistory, farDistance: traceScene.farDistance,
      });
      resetHistory = false;
      currentSet = 1 - currentSet;
      frameIndex++;
      // gl.finish() does not wait in every browser; reading one value back does.
      if (wait) gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, synchronizationPixel);
      return { frame: frameIndex };
    },

    /** The last frame as tone mapped bytes, top row first. Call it right after `frame`, before the page gets a turn. */
    readFrame() {
      gl.bindFramebuffer(gl.FRAMEBUFFER, null);
      const bottomUp = new Uint8Array(outputWidth * outputHeight * 4);
      gl.readPixels(0, 0, outputWidth, outputHeight, gl.RGBA, gl.UNSIGNED_BYTE, bottomUp);
      const rgba = new Uint8ClampedArray(bottomUp.length);
      const rowBytes = outputWidth * 4;
      for (let row = 0; row < outputHeight; row++) rgba.set(bottomUp.subarray((outputHeight - 1 - row) * rowBytes, (outputHeight - row) * rowBytes), row * rowBytes);
      return { width: outputWidth, height: outputHeight, rgba };
    },

    dispose,
  };
}