Skip to content

3D engine that AI agents drive

19.1 KB
Raw Blame
import { MAX_LOCAL_VOLUMES, LOCAL_VOLUME_MAXIMUM_STEPS, ONE_GRID_VOLUME_MESSAGE, resolveLocalVolumesWith } from './local-volume-resolve.js';
import { localVolumeFractalNoise } from './local-volume-noise.js';
import { sampleVolumeGrid, sampleVolumeGridVelocity, gridUnitVelocity, bakedGridEmission, volumeGridFloats } from './volume-grid.js';
import { LOCAL_VOLUME_RAMP_STOPS, rampSourceCode, resolveEmissionRamp } from './local-volume-ramp.js';
import { bakeEmissionRamp } from './local-volume-ramp-bake.js';
import { resolveGridVolume, LOCAL_VOLUME_GRID_MAXIMUM_STEPS } from './local-volume-grid.js';

export * from './local-volume-resolve.js';
export { LOCAL_VOLUME_GRID_MAXIMUM_STEPS };

/**
 * Checks a list of local volumes and returns them with every default filled in, grid volumes included. Throws an error that names the field.
 * The scene entry calls resolveLocalVolumesWith instead, so the grid resolver loads with the grid module and not with every scene.
 */
export function resolveLocalVolumes(input, label = 'localVolumes') {
  return resolveLocalVolumesWith(resolveGridVolume, input, label, resolveEmissionRamp);
}

/** The uniform arrays the post shader reads, one vec4 per volume. Pass resolved volumes. */
export function createLocalVolumeBuffers() {
  const size = MAX_LOCAL_VOLUMES * 4;
  return { count: 0, blurred: false, meshParts: [], grid: new Float32Array(size), gridVolume: null, gridShutter: 0, kind: 'both', noiseOctaves: false, centers: new Float32Array(size), extents: new Float32Array(size), absorption: new Float32Array(size), emission: new Float32Array(size), steps: new Float32Array(size), axes: new Float32Array(size * 3), rampSetup: new Float32Array(size), rampColors: new Float32Array(size * LOCAL_VOLUME_RAMP_STOPS) };
}

// The emission ramp of volume `index` (#1046): rampSetup holds x the source code (0 none), y the stop count and z, w the source range; rampColors
// holds the baked stops, one vec4 each, with the exposure and the emission strength already applied.
function packEmissionRamp(volume, index, buffers) {
  const { emissionRamp } = volume;
  const baked = bakeEmissionRamp(emissionRamp);
  buffers.rampSetup.set([rampSourceCode(emissionRamp.source), baked.count, ...emissionRamp.range], index * 4);
  for (let stop = 0; stop < baked.count; stop++) {
    const at = (index * LOCAL_VOLUME_RAMP_STOPS + stop) * 4;
    for (let channel = 0; channel < 3; channel++) buffers.rampColors[at + channel] = baked.colors[stop * 3 + channel] * volume.emissionStrength;
  }
}

const IDENTITY_AXES = Object.freeze([1, 0, 0, 0, 1, 0, 0, 0, 1]);

// The w of a packed centre tells the shader how to find the volume: 0 a box, 1 a sphere, 2 a closed mesh read from the mesh pass.
export const PACKED_SHAPE_MESH = 2;

export function packLocalVolumes(volumes, buffers) {
  if (volumes.some(volume => volume.shape === 'mesh' && !volume.center)) throw new RangeError('A mesh volume names a part: bind it with bindLocalVolumeParts before packing');
  if (volumes.some(volume => volume.shape === 'grid' && !volume.gridData)) throw new RangeError('Bind a grid volume with bindLocalVolumeParts before packing');
  buffers.count = volumes.length;
  buffers.meshParts = [];
  buffers.gridVolume = null;
  buffers.gridShutter = 0;
  // Which march the frame needs (#1768): a mesh volume needs neither.
  const hasGrid = volumes.some(volume => volume.shape === 'grid');
  const hasShape = volumes.some(volume => volume.shape !== 'grid' && !volume.part);
  buffers.kind = hasGrid && !hasShape ? 'grid' : (hasShape && !hasGrid ? 'shape' : 'both');
  buffers.noiseOctaves = volumes.some(volume => volume.shape !== 'grid' && volume.noiseAmount > 0 && volume.noiseOctaves > 1);
  buffers.grid.fill(0);
  buffers.rampSetup.fill(0);
  buffers.blurred = volumes.some(volume => volume.blur > 0 && volume.density > 0);
  // A volume that glows is composited before bloom extraction, so its glow blooms (#1046).
  buffers.emissive = volumes.some(volume => volume.emissionStrength > 0 && (volume.shape === 'grid' || volume.emission.some(channel => channel > 0)));
  volumes.forEach((volume, index) => {
    const at = index * 4;
    const half = volume.shape === 'sphere' ? [volume.radius, volume.radius, volume.radius] : volume.size.map(extent => extent / 2);
    const packedShape = volume.shape === 'sphere' ? 1 : volume.part ? PACKED_SHAPE_MESH : 0;
    buffers.centers.set([...volume.center, packedShape], at);
    buffers.extents.set([...half, volume.falloff], at);
    buffers.absorption.set([...volume.absorption.map(channel => channel * volume.density), volume.noiseAmount], at);
    buffers.emission.set([...volume.emission.map(channel => channel * volume.emissionStrength), volume.noiseScale], at);
    buffers.steps.set([volume.steps, packedShape === PACKED_SHAPE_MESH ? buffers.meshParts.length : 0, volume.scatter ?? 0, volume.blur ?? 0], at);
    if (volume.emissionRamp) packEmissionRamp(volume, index, buffers);
    if (packedShape === PACKED_SHAPE_MESH) buffers.meshParts.push({ part: volume.part, label: `environment.localVolumes[${index}]` });
    if (volume.shape !== 'grid') {
      buffers.grid[at + 1] = volume.shadowDetail ? 1 : 0;
      buffers.grid[at + 2] = volume.castShadow === true ? 1 : 0;
    }
    if (volume.shape === 'grid') {
      if (buffers.gridVolume) throw new RangeError(ONE_GRID_VOLUME_MESSAGE);
      buffers.gridVolume = volume;
      buffers.gridShutter = volume.motionShutter ?? 0;
      buffers.grid.set([volume.castShadow === true ? 2 : 1, volume.temperatureScale, volume.blackbodyIntensity * volume.emissionStrength, volume.anisotropy], at);
    }
    const axes = volume.axes ?? IDENTITY_AXES;
    // The free fourth component of the first axis row carries the number of scatter octaves and that of the second the noise octaves, each beyond the first.
    for (let axis = 0; axis < 3; axis++) buffers.axes.set([axes[axis * 3], axes[axis * 3 + 1], axes[axis * 3 + 2], axis === 0 ? (volume.scatterOctaves ?? 1) - 1 : (axis === 1 ? (volume.noiseOctaves ?? 1) - 1 : 0)], (index * 3 + axis) * 4);
  });
  return buffers;
}

/**
 * How much the key light of a scattering volume is scaled over the single-scatter estimate. A smoke thick enough to show form scatters the sun many times
 * and reads about as bright as a surface in the same sun, which one isotropic scatter (1 / 4 pi of the key colour) leaves far too dark; the gain keeps the
 * sunlit side clearly above the shaded side. The rasterizer and the CPU path tracer both apply it.
 */
export const LOCAL_VOLUME_KEY_GAIN = 3;

/**
 * How much the faded outer share of a volume counts toward the depth the light crosses: the profile used for the sun and sky depth is
 * `min(profile * saturation, 1)`. The many scatters of a real smoke spread light through its thin fringe as through its body, so a sun
 * ray running along the faded top or side skin is shaded by the whole volume, not by the skin's low density. With the plain profile that
 * skin is lit far above the core and reads as a bright rim around the form.
 */
export const LOCAL_VOLUME_LIGHT_DEPTH_SATURATION = 6;

/**
 * How many times the volume's own depth toward the sun counts in the key light's attenuation. Counting it more than once keeps the shaded
 * side of the smoke clearly darker than the sunlit side, the way the many scatters of a real smoke take the light from its shade.
 */
export const LOCAL_VOLUME_SHADOW_STRENGTH = 1.2;

/**
 * The octave sum that approximates multiple scattering in a volume with `scatterOctaves` above 1 (Wrenninge et al. 2015, "Oz: the great and volumetric"), the one `volumeFog` has:
 * octave n scatters MULTI_SCATTER^n as much, sees MULTI_EXTINCTION^n of the light's optical depth and has MULTI_ANISOTROPY^n of the anisotropy.
 */
export const LOCAL_VOLUME_MULTI_SCATTER = 0.5;
export const LOCAL_VOLUME_MULTI_EXTINCTION = 0.5;
export const LOCAL_VOLUME_MULTI_ANISOTROPY = 0.5;

/** How many taps along the key light measure the optical depth a volume puts between a surface and the sun (#1047). */
export const LOCAL_VOLUME_SURFACE_SHADOW_TAPS = 8;


/** The taps along the light of a volume with `shadowDetail` (the others take 3), so the shadow follows the noise and not only the smooth profile. The shader's loop is bounded by the same number. */
export const LOCAL_VOLUME_DETAIL_SHADOW_TAPS = 8;

/** The share of the mean sky radiance the sky term of a scattering volume keeps. The sky lights the whole volume evenly, so a high share flattens the form the sun gives it. */
export const LOCAL_VOLUME_SKY_GAIN = 0.5;

/**
 * The widest blur, in pixels of a 540 row frame (it scales with the frame height), that the light behind a volume gets: the radius grows as
 * `cap * (1 - exp(-LOCAL_VOLUME_BLUR_RATE * opticalDepth))`, so none at zero depth, most of the cap by an optical depth of 1.5, and it never passes the cap. A thick volume hides the
 * background anyway, a thin one shows it blurred (#855).
 */
export const LOCAL_VOLUME_BLUR_PIXELS = 24;

/** How fast the blur grows with optical depth: a thin wisp of optical depth 0.7 already blurs by about 15 px, so a haze visibly softens the horizon behind it (#855). */
export const LOCAL_VOLUME_BLUR_RATE = 1.5;

/** Samples the march takes per cell of the density noise at least: fewer step over whole cells and the dither of the start offset shows as pixel-pitch grain (#855). */
export const LOCAL_VOLUME_STEPS_PER_NOISE_CELL = 2;

/** The most samples a ray takes through a volume whose noise has several octaves: its finest cell is 2^(octaves - 1) times smaller, so the cap of LOCAL_VOLUME_MAXIMUM_STEPS undercounts it (#1855). */
export const LOCAL_VOLUME_MAXIMUM_OCTAVE_STEPS = 96;

/**
 * The samples a ray of `chord` length needs for noise of `octaves` octaves at base `scale`: LOCAL_VOLUME_STEPS_PER_NOISE_CELL per cell of the finest
 * octave (scale * 2^(octaves - 1), lacunarity 2), at most LOCAL_VOLUME_MAXIMUM_OCTAVE_STEPS. The post shader repeats the rule.
 */
export function localVolumeOctaveStepCount(octaves, scale, chord) {
  const finestScale = scale * 2 ** (octaves - 1);
  return Math.min(LOCAL_VOLUME_MAXIMUM_OCTAVE_STEPS, Math.ceil(chord * finestScale * LOCAL_VOLUME_STEPS_PER_NOISE_CELL));
}

/**
 * The samples a ray takes through a noisy volume: the volume's `steps`, raised so that each noise cell along `length` gets
 * LOCAL_VOLUME_STEPS_PER_NOISE_CELL of them, up to LOCAL_VOLUME_MAXIMUM_STEPS (LOCAL_VOLUME_MAXIMUM_OCTAVE_STEPS counted from the finest octave
 * when noiseOctaves is above 1). Without noise it is `steps`. The post shader repeats the rule.
 */
export function localVolumeStepCount(volume, length) {
  if (!(volume.noiseAmount > 0)) return volume.steps;
  if (volume.noiseOctaves > 1) return Math.max(volume.steps, localVolumeOctaveStepCount(volume.noiseOctaves, volume.noiseScale, length));
  const cellSteps = Math.ceil(length * volume.noiseScale * LOCAL_VOLUME_STEPS_PER_NOISE_CELL);
  return Math.min(LOCAL_VOLUME_MAXIMUM_STEPS, Math.max(volume.steps, cellSteps));
}

/**
 * How much of the sun's elevation the depth toward the sun keeps (1 is the true direction). A low sun lights a smoke box through its top face as
 * quickly as through its side, so with the true direction the top edge glows as bright as the sunward edge and the gradient across the form is lost;
 * flattening the direction measures the depth the light crosses sideways, as the many scatters of a real smoke spread it. Above 0 so a sun straight
 * overhead keeps a direction.
 */
export const LOCAL_VOLUME_SUN_FLATTEN = 0.1;

function fadeProfile(ratio) {
  const clamped = Math.min(1, Math.max(0, ratio));
  return 1 - clamped * clamped * (3 - 2 * clamped);
}

/**
 * How far the noise pushes the faded edge of a volume in and out, as a share of the fade width, at its largest (#855). The fade is a smooth
 * ramp from the core to the edge of the form, so without this a box or a sphere keeps a flat top and flat sides under the noise and reads as
 * a rounded rectangle, not a cloud. The push is zero at the core and at the outer face, so the core stays as thick and no step shows where the form ends.
 */
export const LOCAL_VOLUME_EDGE_WARP = 1;

/** The fade position (0 at the core, 1 at the outer face) after the noise has pushed the edge: `position` moved by the noise, most at the middle of the fade. */
export function warpedFadePosition(position, noiseAmount, noise) {
  const clamped = Math.min(1, Math.max(0, position));
  return clamped + (0.5 - noise) * noiseAmount * LOCAL_VOLUME_EDGE_WARP * 4 * clamped * (1 - clamped);
}

const gridScratch = new Float64Array(3);
const velocityScratch = new Float64Array(3);

/**
 * Writes into `out` the point a motion-blurred grid volume reads instead of (x, y, z) (#1759). The frame's grid is the gas as the shutter opens, and the gas moves on by its
 * velocity, so the point seen `timeFraction * motionShutter` seconds into the shutter reads the grid back along the velocity there: the sum over the shutter is a smear that
 * leads the gas, which is what Cycles does with a velocity grid (measured on the #1735 blast, docs/volumetric.md). A volume with no `motionShutter`, and a point outside the
 * box (no gas, no velocity), read where they are.
 */
export function localVolumeGridMotionPoint(volume, x, y, z, timeFraction, out) {
  out[0] = x;
  out[1] = y;
  out[2] = z;
  if (!(volume.motionShutter > 0)) return out;
  const unitX = (x - volume.center[0]) / volume.size[0] + 0.5;
  const unitY = (y - volume.center[1]) / volume.size[1] + 0.5;
  const unitZ = (z - volume.center[2]) / volume.size[2] + 0.5;
  if (unitX < 0 || unitX > 1 || unitY < 0 || unitY > 1 || unitZ < 0 || unitZ > 1) return out;
  sampleVolumeGridVelocity(gridUnitVelocity(volume.gridData, volume.size), volume.gridData.resolution, unitX, unitY, unitZ, velocityScratch);
  const seconds = volume.motionShutter * timeFraction;
  out[0] -= velocityScratch[0] * volume.size[0] * seconds;
  out[1] -= velocityScratch[1] * volume.size[1] * seconds;
  out[2] -= velocityScratch[2] * volume.size[2] * seconds;
  return out;
}

/**
 * Writes the density, temperature and flame of a grid volume at a world point into `out` (all 0 outside its box) and returns it. With `withBlackbody`, `out` has
 * six entries and out[3] to out[5] get the baked blackbody radiance there, before the blackbody intensity and emission strength (see sampleVolumeGrid).
 */
export function localVolumeGridSample(volume, x, y, z, out, withBlackbody = false) {
  const unitX = (x - volume.center[0]) / volume.size[0] + 0.5;
  const unitY = (y - volume.center[1]) / volume.size[1] + 0.5;
  const unitZ = (z - volume.center[2]) / volume.size[2] + 0.5;
  if (unitX < 0 || unitX > 1 || unitY < 0 || unitY > 1 || unitZ < 0 || unitZ > 1) {
    out.fill(0);
    return out;
  }
  const baked = withBlackbody ? bakedGridEmission(volume.gridData, volume.temperatureScale, volume.flameTemperature) : null;
  return sampleVolumeGrid(volumeGridFloats(volume.gridData), volume.gridData.resolution, unitX, unitY, unitZ, out, baked);
}

/** The density factor of a volume at a point: 1 at the core, fading over the outer `falloff` share, times the noise factor (up to 2) when `noiseAmount` is above 0, as the post shader does. With noise the fade edge is also pushed in and out (LOCAL_VOLUME_EDGE_WARP). */
export function localVolumeProfile(volume, x, y, z, withNoise = true) {
  if (volume.shape === 'mesh') return 1;
  if (volume.gridData) return localVolumeGridSample(volume, x, y, z, gridScratch)[0];
  let offsetX = x - volume.center[0];
  let offsetY = y - volume.center[1];
  let offsetZ = z - volume.center[2];
  if (volume.axes) {
    const axes = volume.axes;
    const alongX = axes[0] * offsetX + axes[1] * offsetY + axes[2] * offsetZ;
    const alongY = axes[3] * offsetX + axes[4] * offsetY + axes[5] * offsetZ;
    offsetZ = axes[6] * offsetX + axes[7] * offsetY + axes[8] * offsetZ;
    offsetX = alongX;
    offsetY = alongY;
  }
  const noisy = withNoise && volume.noiseAmount > 0;
  const noise = noisy ? localVolumeFractalNoise(x * volume.noiseScale, y * volume.noiseScale, z * volume.noiseScale, volume.noiseOctaves) : 0.5;
  let profile = 1;
  if (volume.shape === 'sphere') {
    const distance = Math.hypot(offsetX, offsetY, offsetZ) / volume.radius;
    if (distance >= 1) return 0;
    if (volume.falloff > 0) profile = fadeProfile(warpedFadePosition((distance - (1 - volume.falloff)) / volume.falloff, noisy ? volume.noiseAmount : 0, noise));
  } else {
    const ratioX = Math.abs(offsetX) / (volume.size[0] / 2);
    const ratioY = Math.abs(offsetY) / (volume.size[1] / 2);
    const ratioZ = Math.abs(offsetZ) / (volume.size[2] / 2);
    if (Math.max(ratioX, ratioY, ratioZ) >= 1) return 0;
    if (volume.falloff > 0) {
      // The distance past the core box, which is round at the corners: the plain largest ratio fades along boxes with mitred creases.
      const core = 1 - volume.falloff;
      const fadeDistance = Math.hypot(Math.max(ratioX - core, 0), Math.max(ratioY - core, 0), Math.max(ratioZ - core, 0));
      profile = fadeProfile(warpedFadePosition(fadeDistance / volume.falloff, noisy ? volume.noiseAmount : 0, noise));
    }
  }
  if (noisy) profile *= 1 + (2 * noise - 1) * volume.noiseAmount;
  return profile;
}

/** Where a ray is inside a volume, as distances along it: writes `[entry, exit]` into `out`, clipped to `[0, limit]`, and returns true; false when it misses. */
export function localVolumeInterval(volume, originX, originY, originZ, directionX, directionY, directionZ, limit, out) {
  let entry = 0;
  let exit = limit;
  if (volume.shape === 'sphere') {
    const offsetX = originX - volume.center[0];
    const offsetY = originY - volume.center[1];
    const offsetZ = originZ - volume.center[2];
    const along = offsetX * directionX + offsetY * directionY + offsetZ * directionZ;
    const discriminant = along * along - (offsetX * offsetX + offsetY * offsetY + offsetZ * offsetZ - volume.radius * volume.radius);
    if (discriminant <= 0) return false;
    const root = Math.sqrt(discriminant);
    entry = Math.max(entry, -along - root);
    exit = Math.min(exit, -along + root);
  } else {
    const axes = volume.axes;
    const offsetX = originX - volume.center[0];
    const offsetY = originY - volume.center[1];
    const offsetZ = originZ - volume.center[2];
    for (let axis = 0; axis < 3; axis++) {
      const origin = axis === 0 ? originX : axis === 1 ? originY : originZ;
      let direction = axis === 0 ? directionX : axis === 1 ? directionY : directionZ;
      let relative = volume.center[axis] - origin;
      if (axes) {
        const at = axis * 3;
        relative = -(axes[at] * offsetX + axes[at + 1] * offsetY + axes[at + 2] * offsetZ);
        direction = axes[at] * directionX + axes[at + 1] * directionY + axes[at + 2] * directionZ;
      }
      const halfSize = volume.size[axis] / 2;
      if (direction === 0) {
        if (Math.abs(relative) > halfSize) return false;
        continue;
      }
      const first = (relative - halfSize) / direction;
      const second = (relative + halfSize) / direction;
      entry = Math.max(entry, Math.min(first, second));
      exit = Math.min(exit, Math.max(first, second));
    }
  }
  if (!(entry < exit)) return false;
  out[0] = entry;
  out[1] = exit;
  return true;
}

/** How many taps along the key light measure the optical depth a grid volume puts between a surface and the sun: more than a box takes, because a simulated density has structure along the ray that a smooth profile does not. */
export const LOCAL_VOLUME_GRID_SHADOW_TAPS = 16;