Skip to content

3D engine that AI agents drive

13.1 KB
Raw Blame
// Reversed-Z depth (issue #310): with EXT_clip_control the depth range is zero to one, the projection maps the near plane to 1 and
// the far plane to 0, and the buffer is cleared to 0 and tested with GREATER. Floating point numbers are densest near 0, which is
// where the far surfaces land, so a 32-bit float buffer keeps its precision at distance instead of losing it as 1 / z does.
//
// The renderer constructor installs it (issue #751): `installReversedDepth(renderer)` wraps a few renderer steps and switches on at
// once wherever EXT_clip_control exists, at any far / near ratio. `false` opts out, and a browser without the extension keeps the
// standard path with a 24-bit buffer and a fitted near plane (near-plane-fit.js).
import { mat4 } from 'gl-matrix';
import { compileProgram, fullscreenVertex } from './gl-program.js';
import { shaderTransforms } from './shader-registry.js';

const ZERO_VECTOR = new Float32Array(4);

/**
 * Turns a projection that maps depth to -1..1 into one that maps it to 1..0 (the clip control range is 0..1).
 * Only the third row changes: the new z is (w - z) / 2, so it works for perspective, orthographic and oblique matrices.
 */
export function reverseProjectionDepth(out, projection) {
  for (let column = 0; column < 4; column++) {
    const depthIndex = column * 4 + 2;
    const clipDepth = projection[depthIndex];
    const clipW = projection[depthIndex + 1];
    out[column * 4] = projection[column * 4];
    out[column * 4 + 1] = projection[column * 4 + 1];
    out[depthIndex] = (clipW - clipDepth) / 2;
    out[depthIndex + 1] = clipW;
  }
  return out;
}

// Camera-relative vertex transform. The main vertex shader multiplies viewProjection by the world position, which is a sum of terms
// as large as the distance to the eye, so at 500 m a float32 step of 0.03 mm already hides a 0.1 mm gap. The patched line subtracts
// the eye first and sends w = 0 through the matrix (its linear part only), then adds the projection's own translation. The matrix
// stays whole for the passes that read the eye out of it, and with both uniforms at zero the line is the old product.
const WORLD_CLIP_LINE = 'gl_Position = viewProjection * world;';
const CAMERA_RELATIVE_LINE = 'gl_Position = viewProjection * vec4(world.xyz - cameraOffset.xyz, 1.0 - cameraOffset.w) + cameraShift;';
const CAMERA_UNIFORMS = 'uniform mat4 lightProjection;\nuniform vec4 cameraOffset;\nuniform vec4 cameraShift;';
let patchingMainProgram = false;
let transformInstalled = false;

function makeVertexCameraRelative(source) {
  if (!patchingMainProgram || !source.includes(WORLD_CLIP_LINE)) return source;
  return source.replace('uniform mat4 lightProjection;', CAMERA_UNIFORMS).replace(WORLD_CLIP_LINE, CAMERA_RELATIVE_LINE);
}

// The depth texture the other passes read holds standard depth (1 at the far plane), so a stage right after the resolve turns the
// reversed depth back, through a copy, with gl_FragDepth. Ambient occlusion, depth of field, fog and line art then need no change.
const STANDARD_DEPTH_FRAGMENT = `#version 300 es
precision highp float;
uniform highp sampler2D reversedDepth;
void main() {
  gl_FragDepth = 1.0 - texelFetch(reversedDepth, ivec2(gl_FragCoord.xy), 0).r;
}`;

function createDepthConversionStage() {
  let program = null;
  let uniform = null;
  let copy = null;

  function releaseTargets(context) {
    if (!copy) return;
    context.deleteTexture(copy.texture);
    context.deleteFramebuffer(copy.framebuffer);
    copy = null;
  }

  function createCopy(context, width, height) {
    const texture = context.createTexture();
    context.bindTexture(context.TEXTURE_2D, texture);
    context.texImage2D(context.TEXTURE_2D, 0, context.DEPTH_COMPONENT32F, width, height, 0, context.DEPTH_COMPONENT, context.FLOAT, null);
    context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.NEAREST);
    context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.NEAREST);
    const framebuffer = context.createFramebuffer();
    context.bindFramebuffer(context.FRAMEBUFFER, framebuffer);
    context.framebufferTexture2D(context.FRAMEBUFFER, context.DEPTH_ATTACHMENT, context.TEXTURE_2D, texture, 0);
    return { texture, framebuffer, width, height };
  }

  function apply(renderer) {
    if (!renderer.depthTexture) return null;
    const context = renderer.context;
    const { width, height } = renderer.canvas;
    if (!program) {
      program = compileProgram(context, fullscreenVertex, STANDARD_DEPTH_FRAGMENT);
      uniform = context.getUniformLocation(program, 'reversedDepth');
    }
    if (copy && (copy.width !== width || copy.height !== height)) releaseTargets(context);
    copy ??= createCopy(context, width, height);
    context.bindFramebuffer(context.READ_FRAMEBUFFER, renderer.resolveFramebuffer);
    context.bindFramebuffer(context.DRAW_FRAMEBUFFER, copy.framebuffer);
    context.blitFramebuffer(0, 0, width, height, 0, 0, width, height, context.DEPTH_BUFFER_BIT, context.NEAREST);
    context.bindFramebuffer(context.FRAMEBUFFER, renderer.resolveFramebuffer);
    context.viewport(0, 0, width, height);
    context.useProgram(program);
    context.activeTexture(context.TEXTURE0);
    context.bindTexture(context.TEXTURE_2D, copy.texture);
    context.uniform1i(uniform, 0);
    context.enable(context.DEPTH_TEST);
    context.depthFunc(context.ALWAYS);
    context.colorMask(false, false, false, false);
    context.disable(context.CULL_FACE);
    context.bindVertexArray(null);
    context.drawArrays(context.TRIANGLES, 0, 3);
    context.colorMask(true, true, true, true);
    context.depthFunc(context.LESS);
    context.disable(context.DEPTH_TEST);
    return null;
  }

  function dispose(context) {
    releaseTargets(context);
    if (program) context.deleteProgram(program);
    program = null;
  }

  return { name: 'Reversed depth', apply, releaseTargets, dispose };
}

// The frame targets are allocated with 24-bit depth by the core; this respecifies the two depth stores as 32-bit float.
function useFloatDepthTargets(renderer) {
  const context = renderer.context;
  if (!renderer.multisampleFramebuffer) return;
  const { width, height } = renderer.canvas;
  context.bindRenderbuffer(context.RENDERBUFFER, renderer.multisampleDepth);
  context.renderbufferStorageMultisample(context.RENDERBUFFER, renderer.multisampleSamples, context.DEPTH_COMPONENT32F, width, height);
  renderer.renderTargets?.record('multisampleDepth', { width, height, format: 'DEPTH_COMPONENT32F', samples: renderer.multisampleSamples });
  if (renderer.depthTexture) {
    context.bindTexture(context.TEXTURE_2D, renderer.depthTexture);
    context.texImage2D(context.TEXTURE_2D, 0, context.DEPTH_COMPONENT32F, width, height, 0, context.DEPTH_COMPONENT, context.FLOAT, null);
    renderer.renderTargets?.record('sceneDepth', { width, height, format: 'DEPTH_COMPONENT32F' });
  }
  for (const framebuffer of [renderer.multisampleFramebuffer, renderer.resolveFramebuffer]) {
    context.bindFramebuffer(context.FRAMEBUFFER, framebuffer);
    if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) throw new Error('Reversed depth targets failed to allocate. Pass reversedDepth: false to the install.');
  }
  context.bindFramebuffer(context.FRAMEBUFFER, null);
}

/**
 * Makes the renderer's main vertex shader camera-relative from its first compile. The constructor calls this before it compiles, so
 * switching reversed depth on does not compile the main program a second time.
 */
export function prepareCameraRelativeProgram(renderer) {
  if (renderer.cameraRelativeMainProgram) return;
  if (!transformInstalled) {
    shaderTransforms.push(makeVertexCameraRelative);
    transformInstalled = true;
  }
  const startMainProgram = renderer.startMainProgram;
  renderer.startMainProgram = function startCameraRelativeMainProgram() {
    patchingMainProgram = true;
    try {
      return startMainProgram.call(this);
    } finally {
      patchingMainProgram = false;
    }
  };
  renderer.cameraRelativeMainProgram = true;
}

/**
 * Wraps the renderer so its colour pass draws with reversed-Z and a float depth buffer. Returns the renderer.
 * `mode` is `false` to opt out; anything else switches it on. `renderer.reversedDepth` is true once it is on. A browser without
 * EXT_clip_control, or a benchmark renderer, stays standard.
 */
export function installReversedDepth(renderer, mode = 'auto') {
  if (mode === false) renderer.reversedDepth ??= false;
  if (mode === false || renderer.reversedDepth !== undefined) return renderer;
  const context = renderer.context;
  const original = {
    render: renderer.render,
    applyEnvironmentUniforms: renderer.applyEnvironmentUniforms,
    applyDepthRank: renderer.applyDepthRank,
    resolveFrame: renderer.resolveFrame,
    allocateFrameTargets: renderer.allocateFrameTargets,
  };
  const rasterProjection = mat4.create();
  const rasterViewProjection = mat4.create();
  const cameraOffset = new Float32Array([0, 0, 0, 1]);
  const cameraShift = new Float32Array(4);
  let clipControl = null;
  let inFrame = false;
  let reversed = false;
  let frameEye = null;
  let cameraRelativeProgram = null;

  // Back to the standard range before the backgrounds, the post passes and the shadow maps draw.
  function endReversed() {
    if (!reversed || clipControl.active === false) return;
    clipControl.extension.clipControlEXT(clipControl.extension.LOWER_LEFT_EXT, clipControl.extension.NEGATIVE_ONE_TO_ONE_EXT);
    context.depthFunc(context.LESS);
    clipControl.active = false;
  }

  // The main program is in use. A program that a new shader feature builds starts with both uniforms at zero.
  function setCameraRelative(offset, shift) {
    context.uniform4fv(context.getUniformLocation(renderer.program, 'cameraOffset'), offset);
    context.uniform4fv(context.getUniformLocation(renderer.program, 'cameraShift'), shift);
    cameraRelativeProgram = renderer.program;
  }

  // The next frame, or a pass that draws with the standard matrix, expects the camera offset to be off.
  function clearCameraRelative() {
    if (cameraRelativeProgram !== renderer.program) return;
    context.useProgram(renderer.program);
    setCameraRelative(ZERO_VECTOR, ZERO_VECTOR);
    cameraRelativeProgram = null;
  }

  // Called with the main program in use, after its standard matrix is set: swap in the reversed one and clear to the far value.
  function beginReversed() {
    reverseProjectionDepth(rasterProjection, renderer.projection);
    mat4.multiply(rasterViewProjection, rasterProjection, renderer.view);
    context.uniformMatrix4fv(renderer.uniforms.viewProjection, false, rasterViewProjection);
    renderer.setFlushProjection(rasterViewProjection);
    cameraOffset.set(frameEye);
    cameraShift.set(rasterProjection.subarray(12, 16));
    setCameraRelative(cameraOffset, cameraShift);
    context.clearDepth(0);
    context.clear(context.DEPTH_BUFFER_BIT);
    context.clearDepth(1);
    clipControl.extension.clipControlEXT(clipControl.extension.LOWER_LEFT_EXT, clipControl.extension.ZERO_TO_ONE_EXT);
    context.depthFunc(context.GREATER);
    clipControl.active = true;
  }

  // The program was compiled with the patched line (prepareCameraRelativeProgram) or is compiled again now, and again whenever a
  // new shader feature rebuilds it.
  function useCameraRelativeProgram() {
    if (!renderer.shaderFeatures) return;
    if (renderer.cameraRelativeMainProgram) return;
    prepareCameraRelativeProgram(renderer);
    renderer.rebuildMainProgram();
  }

  function enable() {
    const extension = renderer.benchmark ? null : context.getExtension?.('EXT_clip_control');
    if (!extension) {
      renderer.reversedDepth = false;
      return false;
    }
    clipControl = { extension, active: false };
    reversed = true;
    renderer.reversedDepth = true;
    renderer.rasterProjection = rasterProjection;
    renderer.rasterViewProjection = rasterViewProjection;
    if (renderer.capabilities) renderer.capabilities.reversedDepth = true;
    renderer.applyEnvironmentUniforms = function applyEnvironmentUniformsReversed(map, uniforms) {
      original.applyEnvironmentUniforms.call(this, map, uniforms);
      if (inFrame && !clipControl.active && uniforms === undefined) beginReversed();
    };
    // Reversed depth grows toward the eye, so a depth rank pulls the other way there.
    renderer.applyDepthRank = function applyDepthRankReversed(rank) {
      original.applyDepthRank.call(this, rank, clipControl.active ? 1 : -1);
    };
    renderer.resolveFrame = function resolveFrameStandard(...parameters) {
      endReversed();
      return original.resolveFrame.apply(this, parameters);
    };
    renderer.allocateFrameTargets = function allocateFloatDepthTargets(width, height) {
      original.allocateFrameTargets.call(this, width, height);
      useFloatDepthTargets(this);
    };
    renderer.postStages.unshift(createDepthConversionStage());
    useFloatDepthTargets(renderer);
    useCameraRelativeProgram();
    return true;
  }

  renderer.render = function renderReversed(frame) {
    const outerEye = frameEye;
    frameEye = frame.eye;
    inFrame = true;
    try {
      return original.render.call(this, frame);
    } finally {
      inFrame = false;
      frameEye = outerEye;
      endReversed();
      clearCameraRelative();
    }
  };
  enable();
  return renderer;
}