3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
import { resolveBackground, clearColourFor } from './clear-colour.js';
import { materialTags } from './shader-registry.js';
import { mat4, mat3 } from 'gl-matrix';
import { BLEND_FACTORS } from './blend-output.js';
import { SPLAT_UNITS, requireSplatSupport, layerTextureSupport, LIGHT_SHADING_FEATURE, FRAGMENT_SHADOW_POSITION_FEATURE, SHADING_MODES, LIGHT_SHADING_MAXIMUM_SAMPLES, createVertexShader, vertexShader, liquidFragmentSource, createFragmentShader, liquidPassDrawer, createDepthFragmentShader, benchmarkVertexShader, benchmarkFragmentShader, viewTransformShader, createDepthVertexShader } from './shaders.js';
import { postFragment, createPostFragment, GRID_MOTION_STEP, NOISE_OCTAVES_STEP, localVolumeKindSteps, POST_STEPS, POST_STEPS_WITH_OPTIONAL_CODE, skyFragment, bloomFragment } from './post.js';
import { createGlazeBackend } from './glaze-backend.js';
import { fullscreenVertex, compileProgram, ProgramNotReady, isLinkComplete, setPreparing, releaseStartedPrograms } from './gl-program.js';
import { ambientOcclusionFragment } from './ambient-occlusion.js';
import { planRenderSize, estimateTextureBytes, estimateFrameBytes, memoryBudgetError } from './budget.js';
import { applyProjection } from './camera.js';
import { fittedNearPlane, sceneBoundsOfParts } from './near-plane-fit.js';
import { installReversedDepth, prepareCameraRelativeProgram } from './reversed-depth.js';
import { isBloomActive, resolveEffects } from './effects.js';
import { frameDiagnostics } from './frame-diagnostics.js';
import { depthLayerOf, flushOrderOf, RANKS_PER_LAYER } from './depth-layer.js';
import { createLightingState, updateLightingState } from './lighting.js';
import { RenderTargetLedger } from './render-target-ledger.js';
import { SHADOW_ATLAS_WIDTH, SHADOW_TILE_SIZE, SHADOW_TILES_PER_ROW, tileViewport, writeShadowTile } from './local-shadows.js';
import { resolveVolumeFog, validateFogField } from './volumetric.js';
import { requireEnvironmentSupport, DEFAULT_SUN_ANGULAR_RADIUS } from './environment-shading.js';
import { materialLayerState, materialLayerValue } from './material-layers.js';
import { MaterialSnapshot } from './material-snapshot.js';
import { wearUniformValues } from './material-wear.js';
import { fittedFogDensity } from './fog-fit.js';
import { canUseCompactColor, respecifyColorTargets } from './compact-color.js';
import { InstanceSelection, extractFrustumPlanes, geometryBoundingSphere, selectInstances } from './render-culling.js';
import { fitWorldShadowView, resolveShadowLight, shadowBiasPerSlope } from './shadow-light.js';
import { MAX_MORPH_TARGETS, requireFeatureCode, deformationSupport, requireDeformationSupport, texturedReplaceSupport, textureUpdateSupport } from './shader-registry.js';
const SHADOW_MAP_SIZE = 2048;
// Liquid and foam see the resolved opaque scene, so they draw in their own pass after it.
const TRANSLUCENT_TAGS = new Set(['liquid', 'foam']);
// The 42nd float is the opacity of a blend or add part, so parts that differ only in opacity share a batch.
const INSTANCE_STRIDE = 42;
const OPACITY_OFFSET = 41;
// Shaders get this in place of an infinite attenuation distance, which is not a safe uniform value.
const MAX_FINITE_DISTANCE = 3e38;
const ALPHA_MODES = { opaque: 0, mask: 1, blend: 2, add: 3 };
/** Blend and add draw after the opaque loop, sorted, without writing depth. */
function isTranslucentMode(alphaMode) {
return alphaMode === 'blend' || alphaMode === 'add';
}
const ZERO_VECTOR = Object.freeze([0, 0, 0]);
const MATERIAL_MAPS = ['map', 'normalMap', 'metallicRoughnessMap', 'occlusionMap', 'emissiveMap'];
const MAP_UNIFORMS = ['baseMap', 'normalMap', 'metallicRoughnessMap', 'occlusionMap', 'emissiveMap'];
const MAP_FLAGS = ['hasBaseMap', 'hasNormalMap', 'hasMetallicRoughnessMap', 'hasOcclusionMap', 'hasEmissiveMap'];
const DEFAULT_NORMAL_SCALE = [1, 1];
// The most texture taps a mipmapped texture may take along a grazing axis (16 is the usual hardware ceiling, 8 costs less).
const MAX_TEXTURE_ANISOTROPY = 8;
const PROCEDURAL_MATERIAL_TAGS = new Set(['water', 'foliage', 'grass', 'terrain', 'floor', 'fire', 'smoke', 'liquid', 'foam']);
// Tags whose vertices sway in the wind; the shadow pass must be redrawn when time moves.
const SWAYING_TAGS = new Set(['foliage', 'grass']);
// One depth rank (applyDepthRank): 0.1 mm, plus 2^-19 of the distance (2 mm at 1 km), plus a quarter of a subpixel of
// slope. On the 24-bit fallback a rank also moves two depth steps, since that buffer cannot hold the metric step far away.
const FLUSH_STEP = 1e-4;
const FLUSH_RELATIVE_STEP = 2 ** -19;
const FLUSH_CLIP_STEP = 2 ** -22;
const FLUSH_SLOPE_STEP = 4 / 256;
const clipPerMetreScratch = new Float32Array(4);
// Tags whose vertex shader moves vertices away from the instance matrix, so a bounding sphere would not hold.
const DEFORMING_TAGS = new Set(['foliage', 'grass', 'water', 'fire', 'smoke']);
// The farthest a vertex of a swaying tag moves in the world, per unit of wind strength (windOffset in shaders.js): foliage
// reaches 0.1 * 2.5 * 1.9 + 0.08 = 0.555 and grass 0.42 + 0.05 + 0.04 = 0.51. Their bounds grow by this much times the
// strength, so they can be culled and given levels like rigid parts.
const SWAY_REACH_PER_STRENGTH = 0.56;
const POST_UNIFORMS = ['transparent', 'frameTexture', 'bloomTexture', 'bloomStrength', 'hdrEnabled', 'grade', 'vignette', 'grainAmount', 'resolution', 'monochrome', 'fade', 'cinematic', 'time', 'volumeExplosion', 'explosionProgress', 'inverseViewProjection', 'eye', 'sceneDepth', 'volumeShadowMap', 'volumeLightProjection', 'volumeLightDirection', 'volumeLightColor', 'volumeDensity', 'volumeMinimum', 'volumeMaximum', 'volumeColor', 'volumeAmbient', 'volumeDrift', 'volumeSteps', 'volumeAnisotropy', 'volumeShadowAmbient', 'volumeGridFog', 'volumeNoiseAmount', 'volumeNoiseScale', 'volumeHeightFalloff', 'volumeMaxDistance', 'volumeField', 'volumeProfile', 'volumeFlowStrength', 'volumeFlowPeriod', 'volumeLightCount', 'volumeLightPositions[0]', 'volumeLightColors[0]', 'volumeLightDirections[0]', 'volumeLightCones[0]', 'fogSkyVisibility', 'orthographic', 'occlusionTexture', 'occlusionStrength', 'occlusionTexel'];
function postUniformLocations(context, program) {
return Object.fromEntries(POST_UNIFORMS.map(name => [name, context.getUniformLocation(program, name)]));
}
const MAP_SHADER_FEATURES = ['baseMap', 'normalMap', 'metallicRoughnessMap', 'occlusionMap', 'emissiveMap'];
// Part or material fields that name their shader feature and switch it on when set.
const PRESENT_SHADER_FEATURES = ['skin', 'crowd', 'morph', 'lightMap', 'waterReflection', 'retro', 'waterGlint'];
// Material fields that name their shader feature and switch it on above zero.
const POSITIVE_SHADER_FEATURES = ['moss', 'anisotropy', 'iridescence', 'toon', 'boxMapScale', 'emissionFresnel'];
// Tags whose look the main fragment shader draws with code that other tags never reach.
const TAG_SHADER_FEATURES = new Set(['floor', 'water', 'foliage', 'terrain', 'grass', 'fire', 'smoke', 'unlit']);
function shaderFeaturesOfLighting(lighting) {
const features = [];
if (lighting.spotCount > 0) features.push('spotLights');
if (lighting.areaCount > 0) features.push('areaLights');
if (lighting.shadowCasters.length > 0) features.push('localShadows');
if (lighting.extraFeatures) features.push(...lighting.extraFeatures);
if (lighting.fillIntensity > 0) features.push('fill');
return features;
}
/**
* A few parts that need the same shader features as all of `parts`, plus one instanced pair when any geometry repeats.
* A renderer built on these compiles the program the whole scene needs; replaceParts then adds the rest without a recompile.
*/
export function shaderFeatureRepresentatives(parts) {
const covered = new Set();
const representatives = [];
const firstOfGeometry = new Map();
let instancedPair = null;
for (const part of parts) {
const features = shaderFeaturesOfParts([part]);
if ([...features].some(feature => !covered.has(feature))) {
features.forEach(feature => covered.add(feature));
representatives.push(part);
}
if (!instancedPair && firstOfGeometry.has(part.geometry)) instancedPair = [firstOfGeometry.get(part.geometry), part];
else if (!firstOfGeometry.has(part.geometry)) firstOfGeometry.set(part.geometry, part);
}
if (instancedPair) for (const part of instancedPair) if (!representatives.includes(part)) representatives.push(part);
return representatives.length > 0 ? representatives : parts.slice(0, 1);
}
export function shaderFeaturesOfParts(parts) {
const features = new Set();
for (const part of parts) {
const { material } = part;
for (const name of PRESENT_SHADER_FEATURES) {
if (part[name] || material[name]) features.add(name);
}
MATERIAL_MAPS.forEach((field, index) => {
if (material[field]) features.add(MAP_SHADER_FEATURES[index]);
});
if (castsTintedShadow(part)) features.add('tintedShadows');
if (material.environmentProbe) features.add('probe');
if (material.irradianceGrid) features.add('irradianceGrid');
if (material.normalMap?.uvTransform) features.add('normalMapTransform');
Object.keys(material.layerMaps ?? {}).forEach(name => features.add(name));
if (material.layers) features.add('splat');
for (const name of POSITIVE_SHADER_FEATURES) {
if (material[name] > 0) features.add(name);
}
if (material.emissionMask) features.add('emissionMask');
if (material.lightMask !== undefined) features.add('lightLinking');
if ((material.alphaMode ?? 'opaque') !== 'opaque') features.add('alphaMode');
if (material.subsurface?.weight > 0) features.add('subsurface');
if (material.wear) features.add('surfaceWear');
if (material.snippet) {
features.add(material.snippet.feature);
// A water hook reads the water values the world material code declares, so that code is compiled in.
if (/\bvoid\s+waterHook\s*\(/.test(material.snippet.fragment)) features.add('water');
}
if (materialLayerValue(material, 'clearcoat') > 0) features.add('clearcoat');
if (materialLayerValue(material, 'sheenColor').some(channel => channel !== 0)) features.add('sheen');
if (TAG_SHADER_FEATURES.has(material.tag)) features.add(material.tag);
// Without vertex colours the tint and sky visibility are the constants of the unbound attribute, so no varying carries them.
if ([part.geometry, ...(part.lods ?? []).map(level => level.geometry)].some(geometry => geometry.colors || vertexAlpha(geometry))) features.add('vertexColors');
}
return features;
}
function renderPass(material) {
if (material.transmission > 0) return 'liquid';
return TRANSLUCENT_TAGS.has(material.tag) ? material.tag : 'opaque';
}
// Regrouping parts that already draw (a mirrored sign change) reuses their cached textures, so it needs no texture bookkeeping.
function partNeedsFullUpload(part, texturesReplaceable = Boolean(texturedReplaceSupport.begin)) {
return Boolean(part.skin || part.morph || part.geometry.morphTargets || part.geometry.skinIndices || hasMaterialMap(part.material) && !texturesReplaceable);
}
// A shadow-only part joins the shadow passes and none of the colour, depth or ID passes, so the camera never sees it.
function partPass(part) {
return part.shadowOnly === true ? 'shadowOnly' : renderPass(part.material);
}
function batchPass(batch) {
return batch.pass ?? 'opaque';
}
const SKIN_UNIFORMS = ['skinEnabled', 'skinInfluences', 'jointPalette', 'crowdEnabled'];
const ALPHA_UNIFORMS = ['alphaMode', 'alphaCutoff', 'materialOpacity', 'alphaToCoverage', 'doubleSided'];
const DEPTH_ALPHA_UNIFORMS = ['alphaMasked', 'alphaCutoff', 'materialOpacity', 'hasBaseMap', 'baseMap', 'tintPass', 'tintTransmission', 'tintMapSize', 'tintBias', 'opaqueShadow'];
const MORPH_UNIFORMS = ['morphEnabled', 'morphVertexCount', 'morphTargetCount', 'morphWeights[0]', 'morphSlotTargets[0]', 'morphTargets'];
const ENVIRONMENT_LOOKUP_UNIFORMS = ['environmentSpecular', 'environmentEnabled', 'environmentIntensity', 'environmentRotation', 'environmentLevelMax'];
const ENVIRONMENT_UNIFORMS = [...ENVIRONMENT_LOOKUP_UNIFORMS, 'environmentBrdf', 'environmentIrradiance[0]', 'environmentBounce', 'environmentDiffuseFrame'];
// Shares a unit with the skin influence texture, which no light-mapped (rigid) batch binds.
const LIGHT_MAP_UNIT = 6;
const ENVIRONMENT_SPECULAR_UNIT = 9;
const ENVIRONMENT_BRDF_UNIT = 10;
const LOCAL_SHADOW_UNIT = 15;
// Tinted shadows: one half float map holds the colour of the light that blended and transmissive casters let through (rgb)
// and the depth of the nearest one (alpha). Units 0 to 15 are all taken somewhere, and 13 is the one only a part with three
// layer textures or splat layers also reads, so those parts are blind to the tint (batch.tintBlind).
const TINT_UNIT = 13;
const TINT_MAP_SIZE = 1024;
// The shadow program's opaqueShadow sampler reads the sun map on this unit in the tint draw. Unit 0 would read the map while
// the opaque pass renders into it, a feedback loop that drops every opaque shadow caster.
const OPAQUE_SHADOW_UNIT = 2;
const LIGHT_UNIFORMS = ['pointLightCount', 'pointLightPositions[0]', 'pointLightColors[0]', 'pointLightRadii[0]', 'pointLightShadowTiles[0]',
'spotLightCount', 'spotLightPositions[0]', 'spotLightColors[0]', 'spotLightDirections[0]', 'spotLightParameters[0]',
'areaLightCount', 'areaLightPositions[0]', 'areaLightColors[0]', 'areaLightNormals[0]', 'areaLightTangents[0]',
'localShadowAtlas', 'localShadowMatrices[0]', 'localShadowTexelAngles[0]', 'keyColor', 'fillIntensity', 'ambientIntensity', 'specularAntiAliasing'];
const SPLAT_UNIFORMS = ['splatEnabled', 'splatColor', 'splatNormal', 'splatPacked', 'splatMask', 'splatLayer[0]', 'splatTint[0]', 'splatSlope[0]', 'splatHeightRange[0]', 'splatMaskChannel[0]', 'splatMaskInvert[0]', 'splatBlend', 'splatOptions', 'splatMaskBounds', 'splatVariation'];
function validateMaterialMaps(material) {
if (PROCEDURAL_MATERIAL_TAGS.has(material.tag)) {
for (let index = 1; index < MATERIAL_MAPS.length; index++) {
// Scanned leaf cards carry a normal map; the swaying tags apply it on top of their canopy normal.
const leafNormalMap = MATERIAL_MAPS[index] === 'normalMap' && SWAYING_TAGS.has(material.tag);
if (material[MATERIAL_MAPS[index]] && !leafNormalMap) throw new Error('Material maps require a standard PBR material tag. Procedural tags accept only a base map, and foliage and grass also a normal map.');
}
}
if (material.tag === 'unlit' && (material.normalMap || material.metallicRoughnessMap || material.occlusionMap)) {
throw new Error('Unlit materials support only base and emissive maps.');
}
const normalScale = material.normalScale ?? DEFAULT_NORMAL_SCALE;
if (normalScale.length !== 2 || !Number.isFinite(normalScale[0]) || !Number.isFinite(normalScale[1]) || !Number.isFinite(Math.fround(normalScale[0])) || !Number.isFinite(Math.fround(normalScale[1]))) throw new Error('normalScale must contain two finite floats.');
const occlusionStrength = material.occlusionStrength ?? 1;
if (!Number.isFinite(occlusionStrength) || occlusionStrength < 0 || occlusionStrength > 1) throw new Error('occlusionStrength must be within zero and one.');
validateMoss(material);
}
const DEFAULT_MOSS_COLOR = Object.freeze([0.05, 0.085, 0.02]);
function validateMoss(material) {
if (material.moss === undefined) return;
if (typeof material.moss !== 'number' || !(material.moss >= 0 && material.moss <= 1)) throw new Error('moss must be within zero and one.');
if (material.moss > 0 && PROCEDURAL_MATERIAL_TAGS.has(material.tag)) throw new Error('Moss needs a standard PBR material tag.');
const color = material.mossColor ?? DEFAULT_MOSS_COLOR;
if (!Array.isArray(color) || color.length !== 3 || !color.every(Number.isFinite)) throw new Error('mossColor must be three linear RGB numbers.');
}
/** Moss amount and linear colour, as the shader's materialMoss uniform. */
function mossState(material) {
return [material.moss ?? 0, ...(material.mossColor ?? DEFAULT_MOSS_COLOR)];
}
function materialMapState(material) {
validateMaterialMaps(material);
const normalScale = material.normalScale ?? DEFAULT_NORMAL_SCALE;
const occlusionStrength = material.occlusionStrength ?? 1;
if (material.layers || material.splat) requireSplatSupport().validate(material);
if (material.layers && PROCEDURAL_MATERIAL_TAGS.has(material.tag)) throw new Error('Splat layers require a standard PBR material tag.');
return [...MATERIAL_MAPS.map(field => material[field] ?? null), normalScale[0], normalScale[1], occlusionStrength, ...mossState(material), material.boxMapScale ?? 0, material.boxMapAxis ?? 1, ...lightMapState(material), material.layers ?? null, material.splat ?? null, material.layerMaps ?? null, material.environmentProbe ?? null, material.waterReflection ?? null, material.irradianceGrid ?? null, material.wear ?? null, material.waterRamp ?? null];
}
// A baked light map reads the second UV set, so it is only drawn for parts that cannot be skinned or morphed.
function lightMapState(material) {
if (!material.lightMap) return [null, 0];
const scale = material.lightMapScale ?? 1;
if (!Number.isFinite(scale) || scale < 0) throw new RangeError('lightMapScale must be a nonnegative number.');
if ((material.lightMap.colorSpace ?? 'srgb') !== 'srgb') throw new Error('lightMap requires an srgb texture descriptor.');
return [material.lightMap, scale];
}
function validateAlphaMaterial(material) {
const alphaMode = material.alphaMode ?? 'opaque';
if (!Object.hasOwn(ALPHA_MODES, alphaMode)) throw new Error("alphaMode must be 'opaque', 'mask', 'blend' or 'add'.");
for (const field of ['alphaCutoff', 'opacity']) {
const value = material[field] ?? 1;
if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) throw new Error(`${field} must be a number within zero and one.`);
}
if (material.doubleSided !== undefined && typeof material.doubleSided !== 'boolean') throw new TypeError('doubleSided must be a boolean');
}
/** Opacity of one instance: blend and add parts carry it per instance, so it never splits a batch. */
function instanceOpacity(material) {
const alphaMode = material.alphaMode ?? 'opaque';
return isTranslucentMode(alphaMode) ? (material.opacity ?? 1) + (material.opacityBias ?? 0) : 1;
}
/** Alpha settings that every instance of one draw call must share. Fields that a mode ignores, and the per-instance opacity, are normalized away. */
function materialAlphaState(material) {
validateAlphaMaterial(material);
const alphaMode = material.alphaMode ?? 'opaque';
const alphaCutoff = alphaMode === 'mask' ? material.alphaCutoff ?? 0.5 : 0;
const opacity = alphaMode === 'mask' ? (material.opacity ?? 1) + (material.opacityBias ?? 0) : 1;
return [alphaMode, alphaCutoff, opacity, material.doubleSided === true, material.retro, material.waterGlint];
}
// A decal or depth layer draws with a scoped polygon offset so it wins against the surface it lies on (z-fighting).
// Larger layers win over smaller ones; geometry never moves.
// Additive light is not a shadow caster unless the part asks for it. A blended part lying on a surface (a decal) would shade
// the surface it covers, so it casts only when asked too. A shadow catcher only shows the shadow it receives, so it never
// casts one unless the part asks for it. Other blended parts cast a shadow weighted by their opacity.
function castsShadow(part) {
const alphaMode = part.material.alphaMode ?? 'opaque';
const decal = alphaMode === 'blend' && depthLayerOf(part) > 0;
return part.castShadow ?? !(part.shadowCatcher === true || alphaMode === 'add' || decal);
}
/** A caster whose shadow is weighted by opacity or tinted by its colour: blended and transmissive parts. */
function castsTintedShadow(part) {
return castsShadow(part) && part.material.tag !== 'floor' && ((part.material.alphaMode ?? 'opaque') === 'blend' || part.material.transmission > 0);
}
const receivesShadow = part => part.receiveShadow !== false;
// Uniform value of a batch: 0 draws normally, 1 is a holdout (zero colour, zero alpha), 2 is a shadow catcher (black, alpha = shadow).
const compositeModeOf = part => (part.holdout === true ? 1 : part.shadowCatcher === true ? 2 : 0);
const BOOLEAN_PART_FLAGS = ['castShadow', 'receiveShadow', 'holdout', 'shadowCatcher', 'shadowOnly', 'visible'];
function validatePartFlags(part) {
for (const flag of BOOLEAN_PART_FLAGS) {
if (part[flag] !== undefined && typeof part[flag] !== 'boolean') throw new TypeError(`${flag} must be a boolean`);
}
if (part.holdout === true && part.shadowCatcher === true) throw new Error(`A part is a holdout or a shadow catcher, not both: ${part.name}`);
}
/** A hidden part keeps its slot in the batch but draws and casts nothing: its instance matrices are packed as zeros. */
const isHidden = part => part.visible === false || part.visibility?.visible === false;
function hasMaterialMap(material) {
return MATERIAL_MAPS.some(field => material[field]);
}
// Math.fround turns a double of 2^128 - 2^103 or more into Infinity, so that is the first value that is not a finite float.
const FLOAT_OVERFLOW = 2 ** 128 - 2 ** 103;
function finiteFloat(value) {
return typeof value === 'number' && value > -FLOAT_OVERFLOW && value < FLOAT_OVERFLOW;
}
function finiteVector(value, size) {
if (value?.length !== size) return false;
if (value instanceof Float32Array) {
// Every float is already in range, so it is finite exactly when 0 * value is 0 and not NaN. This runs without a branch per element.
let zeroSum = 0;
for (let index = 0; index < size; index++) zeroSum += value[index] * 0;
return zeroSum === 0;
}
for (let index = 0; index < size; index++) if (!finiteFloat(value[index])) return false;
return true;
}
function validateTransform(part, normalMatrix = mat3.create()) {
if (!finiteVector(part.matrix, 16)) throw new Error(`Invalid transform: ${part.name}`);
if (!mat3.normalFromMat4(normalMatrix, part.matrix) || !finiteVector(normalMatrix, 9)) throw new Error(`Singular transform: ${part.name}`);
// An absent emissive colour or assembly offset packs as the base colour or zero, which need no second check.
const material = part.material;
const assembly = part.assembly;
if (!finiteVector(material.color, 3) || (material.emissiveColor !== undefined && !finiteVector(material.emissiveColor, 3)) ||
(assembly && (!finiteVector(assembly.offset ?? ZERO_VECTOR, 3) || !finiteVector(assembly.detailOffset ?? ZERO_VECTOR, 3)))) {
throw new Error(`Invalid instance vector: ${part.name}`);
}
if (!finiteFloat(part.material.metallic) || !finiteFloat(part.material.roughness) || !finiteFloat(part.material.emission ?? 0)) throw new Error(`Invalid material: ${part.name}`);
return normalMatrix;
}
// TypedArray.set costs more per call than three stores, and a loop shared by every vector length reads its source through a slow polymorphic path.
function copyVector3(target, offset, source) {
target[offset] = source[0];
target[offset + 1] = source[1];
target[offset + 2] = source[2];
}
/**
* True when the matrix reflects space (negative determinant of its upper 3x3, column major), which reverses the screen
* winding of every triangle. The renderer owns this: it groups such parts apart and draws them with clockwise front faces.
*/
export function isMirroredMatrix(matrix) {
const determinant = matrix[0] * (matrix[5] * matrix[10] - matrix[6] * matrix[9])
- matrix[4] * (matrix[1] * matrix[10] - matrix[2] * matrix[9])
+ matrix[8] * (matrix[1] * matrix[6] - matrix[2] * matrix[5]);
return determinant < 0;
}
function packInstance(data, index, part, normalMatrix) {
const offset = index * INSTANCE_STRIDE;
const material = part.material;
if (isHidden(part)) {
data.fill(0, offset, offset + 25);
} else {
data.set(part.matrix, offset);
data.set(normalMatrix, offset + 16);
}
copyVector3(data, offset + 25, material.color);
data[offset + 28] = material.metallic;
data[offset + 29] = material.roughness;
data[offset + 30] = material.emission ?? 0;
data[offset + 31] = materialTags[material.tag] ?? 0;
copyVector3(data, offset + 32, part.assembly?.offset ?? ZERO_VECTOR);
copyVector3(data, offset + 35, part.assembly?.detailOffset ?? ZERO_VECTOR);
copyVector3(data, offset + 38, material.emissiveColor ?? material.color);
data[offset + OPACITY_OFFSET] = instanceOpacity(material);
}
// The objectId mode of RENDER_PASS_MODES in render-passes.js.
const OBJECT_ID_PASS_MODE = 5;
function isCullable(parts) {
const first = parts[0];
if (first.skin || first.morph) return false;
if (DEFORMING_TAGS.has(first.material.tag) && !SWAYING_TAGS.has(first.material.tag)) return false;
if (renderPass(first.material) !== 'opaque' || isTranslucentMode(materialAlphaState(first.material)[0])) return false;
return parts.every(part => !part.assembly || part.crowd);
}
/** Whether a part may take `lods`: rigid or swaying and opaque, without assembly motion (the parts that culling can choose levels for). */
export function partTakesLods(part) {
return isCullable([part]);
}
function validateLods(part, levels) {
if (!Array.isArray(levels) || levels.length < 2 || levels[0].geometry !== part.geometry) {
throw new TypeError(`lods must list level 0 (the own geometry of the part) and at least one coarser level: ${part.name}`);
}
levels.forEach((level, index) => {
if (!level.geometry?.positions || !level.geometry.indices) throw new TypeError(`Every lods entry needs a geometry: ${part.name}`);
if (!Number.isFinite(level.error) || level.error < 0 || (index > 0 && level.error < levels[index - 1].error)) {
throw new RangeError(`lods errors must be finite and not decrease from level to level: ${part.name}`);
}
});
}
/** Every geometry a part can draw: its own, the levels of `lods` and the levels of `shadowLods`. */
function partGeometries(part) {
const drawn = [part.geometry, ...(part.lods ?? []).map(level => level.geometry), ...(part.shadowLods ?? []).map(level => level.geometry)];
// A part with hidden flush faces cut away draws its cut geometry, which lives and is released like any other.
const clipped = flushOrderOf(part)?.geometry;
if (clipped) drawn.push(clipped);
return drawn;
}
/** The state of one list of levels: errors, geometries, the draw of each level once it is first needed, and a selection. */
function createLevelSet(levels, instanceCount) {
return { levelErrors: levels.map(level => level.error), levelGeometries: levels.map(level => level.geometry), levelDraws: [], selection: new InstanceSelection(instanceCount, levels.length) };
}
/**
* The studio floor sits at y 0.019. When that would hide more than a tenth of the scene's height (a pencil, a hand that
* hangs below y 0), it sits 2% up from the scene's lowest point instead, so small objects are not buried (issue #468).
* Scenes a metre or more tall resting on y 0, and large scenes that dip below it, keep the floor where it was.
*/
export function studioFloorHeight(parts) {
let bottom = Infinity;
let top = -Infinity;
for (const { geometry, matrix } of parts) {
if (!geometry?.positions?.length || !matrix) continue;
// The world heights of the part's local box: each axis adds its row-one term at the box's lower or upper end.
const { minimum, maximum } = geometryBoundingSphere(geometry);
let low = matrix[13];
let spread = 0;
for (let axis = 0; axis < 3; axis++) {
const scale = matrix[1 + axis * 4];
low += Math.min(scale * minimum[axis], scale * maximum[axis]);
spread += Math.abs(scale) * (maximum[axis] - minimum[axis]);
}
bottom = Math.min(bottom, low);
top = Math.max(top, low + spread);
}
const height = top - bottom;
return 0.019 - bottom > height * 0.1 ? bottom + height * 0.02 : 0.019;
}
function groundPart(height = 0.019) {
return {
name: 'Studio floor',
geometry: {
positions: new Float32Array([-100, height, -100, -100, height, 100, 100, height, 100, 100, height, -100]),
normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]),
indices: new Uint32Array([0, 1, 2, 0, 2, 3]),
},
matrix: mat4.create(),
material: { color: [0.04, 0.05, 0.06], metallic: 0, roughness: 1, emission: 0, tag: 'floor' },
};
}
// The skin and morph code loads with skinning.js and morph.js (any module that makes a pose imports them), so a part without
// a skin or morph targets never reaches it.
const skinSupport = () => requireDeformationSupport('validateSkinGeometry', 'skinning.js');
// A draw applies at most MAX_MORPH_TARGETS targets. With more stored, the draw uploads the largest weights and their indices.
const MORPH_SLOT_COUNT = MAX_MORPH_TARGETS;
const IDENTITY_MORPH_SLOTS = Float32Array.from({ length: MORPH_SLOT_COUNT }, (_, index) => index);
const MORPH_SLOT_TARGETS = new Float32Array(MORPH_SLOT_COUNT);
const MORPH_SLOT_WEIGHTS = new Float32Array(MORPH_SLOT_COUNT);
const morphSupport = () => requireDeformationSupport('validateMorphGeometry', 'morph.js');
const hasSkinData = part => Boolean(part.skin || part.geometry.skinIndices || part.geometry.skinWeights);
const hasMorphData = part => Boolean(part.morph || part.geometry.morphTargets !== undefined);
function validatePartForGrouping(part, morphInfos) {
validateTransform(part);
validatePartFlags(part);
if (hasSkinData(part)) {
const { validateSkinGeometry, validateSkinPose } = skinSupport();
validateSkinGeometry(part.geometry, part.skin);
if (part.skin) validateSkinPose(part.skin, part.geometry, part.matrix);
}
if (part.skin && PROCEDURAL_MATERIAL_TAGS.has(part.material.tag)) throw new Error('Skinned parts require a standard material tag.');
if (hasMorphData(part)) {
const { validateMorphGeometry, validateMorphPose, validateMorphTransform } = morphSupport();
if (!morphInfos.has(part.geometry)) morphInfos.set(part.geometry, validateMorphGeometry(part.geometry, part.morph));
else validateMorphPose(part.morph, morphInfos.get(part.geometry));
if (part.morph) validateMorphTransform(part.morph, morphInfos.get(part.geometry), part.matrix, part.skin);
}
if (part.morph && PROCEDURAL_MATERIAL_TAGS.has(part.material.tag)) throw new Error('Morphed parts require a standard material tag.');
}
/**
* Groups parts into batches one part at a time, in the order they arrive: a batch starts at the first part with its key and
* collects every later part with the same key. Adding parts later gives the batches a single call over all of them would give.
*/
function createPartGrouper(batching) {
// One flat map from a compact string key to a batch: a nested map per key value cost about 12 KB for every batch.
const batchesByKey = new Map();
const batches = [];
const morphInfos = new Map();
const materialKeyValues = new Map();
const materialKeyTails = new Map();
// A key value (a geometry, a material map, a flag) is replaced by a small number, so the key stays a short string.
const valueNumbers = new Map();
function numberOf(value) {
let number = valueNumbers.get(value);
if (number === undefined) {
number = valueNumbers.size;
valueNumbers.set(value, number);
}
return number;
}
function addPart(part) {
validatePartForGrouping(part, morphInfos);
// Thousands of parts share a few materials, so the material half of the key is built once per material.
let materialValues = materialKeyValues.get(part.material);
if (!materialValues) {
materialValues = [...materialMapState(part.material), ...materialLayerState(part.material)];
materialKeyValues.set(part.material, materialValues);
}
let materialTail = materialKeyTails.get(part.material);
if (!materialTail) {
materialTail = [renderPass(part.material), ...materialAlphaState(part.material), part.material.aovMap ?? null, part.material.transmissionMap ?? null, ...(part.material.aov ?? ZERO_VECTOR)];
materialKeyTails.set(part.material, materialTail);
}
const values = [batching ? part.geometry : part, ...materialValues, part.skin ?? null, part.material.snippet, part.crowd ?? null, part.morph ?? null, castsShadow(part), receivesShadow(part), compositeModeOf(part), part.shadowOnly === true, depthLayerOf(part), flushOrderOf(part), part.lods ?? null, part.shadowLods ?? null, isMirroredMatrix(part.matrix), ...materialTail];
const key = values.map(numberOf).join(',');
let batch = batchesByKey.get(key);
if (!batch) {
batch = [];
batchesByKey.set(key, batch);
batches.push(batch);
}
batch.push(part);
}
return {
batches,
addParts(parts) {
for (const part of parts) addPart(part);
},
};
}
export function groupParts(parts, batching = true) {
const grouper = createPartGrouper(batching);
grouper.addParts(parts);
return grouper.batches;
}
/**
* Groups a world that grows, as replaceParts({ retainedUnchanged: true }) receives it in slices.
* When `parts` starts with the parts of `previous`, the appended parts join the batches built so far: a new part lands in the
* batch that already has its key, or starts a batch after the others, which is where groupParts over the whole list puts it. Only
* the appended parts are grouped and validated. Anything else, including a state left behind by a failed call, groups the whole list.
* Returns the batches and the state to pass on the next call. The batches of a state that continues grow in place, so use them
* before grouping again.
*/
export function groupPartsIncrementally(previous, parts, batching = true) {
const startsWithPrevious = Boolean(previous?.intact) && batching && previous.parts.length <= parts.length &&
previous.parts.every((part, index) => part === parts[index]);
if (startsWithPrevious) {
// The grouper changes as it takes parts, so a call that throws leaves this state unusable.
previous.intact = false;
const appended = parts.slice(previous.parts.length);
previous.grouper.addParts(appended);
for (const part of appended) previous.geometries.add(part.geometry);
const { grouper, geometries } = previous;
return { batches: grouper.batches, state: { parts: parts.slice(), geometries, batches: grouper.batches, grouper, intact: true } };
}
const grouper = createPartGrouper(batching);
grouper.addParts(parts);
return { batches: grouper.batches, state: { parts: parts.slice(), geometries: new Set(parts.map(part => part.geometry)), batches: grouper.batches, grouper, intact: true } };
}
/**
* Groups the world and its floor for replaceParts. Without `retainedUnchanged` this is groupParts over the parts and the floor, with no state kept.
* With it, only the appended slice is grouped; the floor is one more batch unless it shares a geometry with a world part,
* where groupParts would have merged them, so that case groups everything.
*/
export function groupWorld(previous, parts, groundPart, batching, retainedUnchanged) {
if (!retainedUnchanged) return { batches: groupParts(groundPart ? [...parts, groundPart] : parts, batching), state: null };
const grouped = groupPartsIncrementally(previous, parts, batching);
if (!groundPart) return grouped;
const floorMerges = grouped.state.geometries.has(groundPart.geometry);
const batches = floorMerges ? groupParts([...parts, groundPart], batching) : [...grouped.batches, ...groupParts([groundPart], batching)];
return { batches, state: grouped.state };
}
// Sampler state and mipmaps of the texture bound to TEXTURE_2D, once its level 0 is uploaded. Needs only the renderer's context and applyAnisotropy.
export function configureTexture(renderer, info) {
const context = renderer.context;
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, info.wrapS);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, info.wrapT);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, info.minFilter);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, info.magFilter);
if (info.mipmaps) {
context.generateMipmap(context.TEXTURE_2D);
if (filtersSmoothly(info)) renderer.applyAnisotropy(context.TEXTURE_2D);
}
}
// Anisotropic filtering replaces both filters with its own smooth one, so it would turn a NEAREST sampler (pixel art, block
// textures) into a blur. Only a texture that already filters linearly in both directions gets it.
function filtersSmoothly({ minFilter, magFilter }) {
const LINEAR = 9729;
const LINEAR_MIPMAP_NEAREST = 9985;
const LINEAR_MIPMAP_LINEAR = 9987;
return magFilter === LINEAR && (minFilter === LINEAR_MIPMAP_NEAREST || minFilter === LINEAR_MIPMAP_LINEAR);
}
export function textureDescriptorInfo(map, maximumSize = Infinity) {
const width = map.image?.naturalWidth ?? map.image?.width;
const height = map.image?.naturalHeight ?? map.image?.height;
if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0 || width > maximumSize || height > maximumSize) throw new Error('Texture image dimensions are invalid or exceed MAX_TEXTURE_SIZE.');
if (![0, 1].includes(map.uvChannel ?? 0)) throw new Error('Only texture UV channels 0 and 1 are supported.');
if (map.transform || map.offset || map.repeat || map.rotation !== undefined || map.extensions && Object.keys(map.extensions).length) throw new Error('Texture transforms and extensions are unsupported. Bake them into UV channel 0.');
if (map.colorSpace && !['srgb', 'linear'].includes(map.colorSpace)) throw new Error('Texture color space must be srgb or linear.');
const wrapS = map.wrapS ?? 10497;
const wrapT = map.wrapT ?? 10497;
const minFilter = map.minFilter ?? 9987;
const magFilter = map.magFilter ?? 9729;
if (![10497, 33071, 33648].includes(wrapS) || ![10497, 33071, 33648].includes(wrapT)) throw new Error('Unsupported texture wrap mode.');
if (![9728, 9729, 9984, 9985, 9986, 9987].includes(minFilter) || ![9728, 9729].includes(magFilter)) throw new Error('Unsupported texture filtering mode.');
const compressed = map.image.compressed;
// Precompressed mips come with the image and are never generated. The image supplies its own filter and byte count.
if (compressed) return { width, height, wrapS, wrapT, minFilter: compressed.minFilter(minFilter), magFilter, mipmaps: false, bytes: compressed.bytes };
const mipmaps = minFilter >= 9984;
return { width, height, wrapS, wrapT, minFilter, magFilter, mipmaps, bytes: estimateTextureBytes(width, height, { mipmaps }) };
}
// Light-mapped geometry uploads its two UV sets as one four-wide attribute (zeros where channel 0 is absent).
function uvBufferBytes(geometry) {
if (!geometry.lightUvs) return geometry.uvs?.byteLength ?? 0;
return geometry.lightUvs.byteLength * 2;
}
function interleaveUvSets(geometry) {
const vertexCount = geometry.lightUvs.length / 2;
const combined = new Float32Array(vertexCount * 4);
for (let vertex = 0; vertex < vertexCount; vertex++) {
combined[vertex * 4] = geometry.uvs?.[vertex * 2] ?? 0;
combined[vertex * 4 + 1] = geometry.uvs?.[vertex * 2 + 1] ?? 0;
combined[vertex * 4 + 2] = geometry.lightUvs[vertex * 2];
combined[vertex * 4 + 3] = geometry.lightUvs[vertex * 2 + 1];
}
return combined;
}
// Sky visibility, or the packed surface wear masks of a material with `wear`, rides in the fourth component of the vertex
// colour attribute, so the attribute layout stays the same.
function vertexAlpha(geometry) {
return geometry.surfaceMasks ?? geometry.skyVisibility;
}
function interleaveColorsWithSkyVisibility(geometry) {
const vertexCount = vertexAlpha(geometry).length;
const combined = new Float32Array(vertexCount * 4);
for (let vertex = 0; vertex < vertexCount; vertex++) {
for (let channel = 0; channel < 3; channel++) {
combined[vertex * 4 + channel] = geometry.colors ? geometry.colors[vertex * 3 + channel] : 1;
}
combined[vertex * 4 + 3] = vertexAlpha(geometry)[vertex];
}
return combined;
}
function geometryBufferBytes(geometry) {
const plainBytes = ['positions', 'normals', 'colors', 'indices'].reduce((total, field) => total + (geometry[field]?.byteLength ?? 0), uvBufferBytes(geometry));
if (!vertexAlpha(geometry)) return plainBytes;
return plainBytes - (geometry.colors?.byteLength ?? 0) + vertexAlpha(geometry).length * 16;
}
function validateReplacementGeometry(geometry) {
const vertexCount = geometry.positions?.length / 3;
if (!(geometry.positions instanceof Float32Array) || !Number.isInteger(vertexCount) || vertexCount < 1 ||
!(geometry.normals instanceof Float32Array) || geometry.normals.length !== vertexCount * 3 ||
!(geometry.indices instanceof Uint32Array) || geometry.indices.length < 3 || geometry.indices.length % 3 !== 0) {
throw new TypeError('Replacement geometry needs matching Float32 positions/normals and Uint32 triangles.');
}
// Plain loops: replaceParts runs this every frame for streamed meshes, where callback-based
// `every` cost about ten times more than the upload itself.
for (const [field, count] of [['positions', 3], ['normals', 3], ['uvs', 2], ['colors', 3]]) {
const values = geometry[field];
if (!values && ['uvs', 'colors'].includes(field)) continue;
if (!(values instanceof Float32Array) || values.length !== vertexCount * count || !allFinite(values)) {
throw new TypeError(`Replacement ${field} must contain finite matching Float32 data.`);
}
}
const indices = geometry.indices;
for (let index = 0; index < indices.length; index++) {
if (indices[index] >= vertexCount) throw new RangeError('Replacement triangle indices must address existing vertices.');
}
}
function allFinite(values) {
for (let index = 0; index < values.length; index++) {
const value = values[index];
// NaN fails both comparisons; infinities fail one.
if (!(value > -Infinity && value < Infinity)) return false;
}
return true;
}
// Triangles per pixel above which `denseSamples` replaces `samples`: past one triangle per pixel every pixel is shaded about once per sample anyway, so the extra samples cost fragment work and buy little edge quality (#1163).
export const DENSE_TRIANGLES_PER_PIXEL = 1;
export function samplesForDensity(parts, canvas, pixelRatio, samples, denseSamples) {
if (!Number.isInteger(denseSamples) || denseSamples < 1) throw new Error('denseSamples must be a positive integer or null.');
let triangles = 0;
for (const part of parts) triangles += part.geometry.indices.length / 3;
const pixels = Math.max(1, canvas.clientWidth) * Math.max(1, canvas.clientHeight) * pixelRatio * pixelRatio;
return triangles / pixels > DENSE_TRIANGLES_PER_PIXEL ? Math.min(samples, denseSamples) : samples;
}
export class CrucibleRenderer {
constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, denseSamples = null, hdr = false, compactColor = true, depth = false, memoryBudgetMiB, environment = {}, shadowBounds = {}, shadowCascades = null, culling = true, lodPixelError = 1, createGpuTimer = null, skyOpenness = null, fogSkyVisibility = null, shading = 'full', viewTransform = 'aces', look = null, resolveCoplanar = false, reversedDepth = 'auto', exactFrames = false, deferProgramLink = false, deferEnvironmentPrefilter = false, background = null, maximumMemoryBudgetMiB } = {}) {
this.background = background ? resolveBackground(background) : null;
this.canvas = canvas;
this.sceneParts = parts;
// `skyOpenness` from closed-room.js is passed in, which keeps the ray code out of scenes without volume fog.
this.skyOpenness = skyOpenness;
// `fogSkyVisibility` from fog-sky-visibility.js is passed in for the same reason; without it the post shader has no grid.
this.fogSkyVisibility = fogSkyVisibility;
this.fogFieldOverride = null;
this.fogFieldTexture = null;
// fog-shader.js creates the light buffers on the first frame that draws a volume fog.
this.fogLightBuffers = null;
// `createGpuTimer` from adaptive-quality.js is passed in, which keeps the timer code out of scenes that do not time frames.
this.createGpuTimer = createGpuTimer;
this.gpuTimer = undefined;
/** Milliseconds the GPU took for a recent frame, when `createGpuTimer` is given. */
this.gpuMilliseconds = null;
this.culling = culling;
this.lodPixelError = lodPixelError;
this.frustumPlanes = new Float32Array(24);
if (!Number.isInteger(samples) || samples < 1) throw new Error('MSAA sample count must be a positive integer.');
if (!SHADING_MODES.includes(shading)) throw new Error(`shading must be one of ${SHADING_MODES.join(', ')}.`);
this.shading = shading;
if (new Set(parts).size !== parts.length) throw new Error('Scene parts must have distinct object identities for animation.');
this.lighting = createLightingState();
updateLightingState(this.lighting, environment, { world });
const volume = resolveVolumeFog(environment.volumeFog);
if (volume.density > 0 && (!depth || benchmark || transparent || !hdr)) throw new Error('Volume fog requires depth:true, hdr:true, an opaque canvas and normal rendering');
this.backend = createGlazeBackend(canvas, { transparent });
this.context = this.backend.context;
this.transparent = Boolean(transparent);
this.pixelRatio = pixelRatio;
this.benchmark = benchmark;
this.depth = Boolean(depth && !benchmark);
this.world = world;
this.environment = environment;
this.fittedFogDensity = world ? fittedFogDensity(parts) : undefined;
this.shadowBounds = shadowBounds;
/** Set by installCoplanarDiagnostics (coplanar-overlap.js): called with the batches, returns coplanar-overlap warnings. */
this.coplanarDiagnostics = null;
/** `false` keeps the standard depth buffer; the default draws every colour pass with reversed-Z and a 32-bit float depth buffer where EXT_clip_control exists. */
this.reversedDepthMode = reversedDepth;
// A frame that must match every later draw of it (a render job, a still) waits for a post program the driver is still building instead of drawing with the all-steps fallback, whose maths differs by a half-float step (#1767).
this.exactFrames = exactFrames;
const reversedDepthWanted = reversedDepth !== false && !benchmark && Boolean(this.context.getExtension?.('EXT_clip_control'));
/** Warnings about the last frame drawn, in the shape of `agent-diagnostics.js`; see `frame-diagnostics.js`. */
this.diagnostics = [];
this.activeLightDirection = environment.lightDirection ?? [-3, 6, 4];
this.shadowCascades = shadowCascades;
this.renderTargets = new RenderTargetLedger();
// The constructor options are the default; a frame's environment (a recipe's viewTransform and look) overrides them.
this.defaultViewTransform = viewTransform;
this.defaultLook = look;
this.viewTransform = 'aces';
this.look = null;
this.lookSource = null;
this.selectViewTransform(viewTransform, look);
this.hdr = Boolean(hdr && !benchmark && this.context.getExtension('EXT_color_buffer_float'));
this.compactColor = compactColor !== false;
if (volume.density > 0 && !this.hdr) throw new Error('Volume fog requires EXT_color_buffer_float for HDR rendering');
this.baseSamples = samples;
this.denseSamples = denseSamples;
this.densityParts = parts;
this.multisampleSamples = this.chooseMultisampleSamples(this.densityParts);
this.capabilities = { hdr: this.hdr, hdrRequested: Boolean(hdr), hdrFallbackReason: hdr && !this.hdr ? benchmark ? 'HDR is disabled in benchmark mode' : 'EXT_color_buffer_float is unavailable' : null, samples: this.multisampleSamples };
this.geometryBytes = 0;
this.geometryBuffers = new Map();
this.batching = batching;
this.groundPart = ground === true ? groundPart(studioFloorHeight(parts)) : ground || null;
this.buffers = [];
this.batches = [];
this.partLocations = new Map();
this.updateBatches = new Set();
// Addons plug in here: full-frame effects (camera-effects.js) run between the resolve and the post pass, and
// render-passes.js sets passSupport. None by default.
this.postStages = [];
this.passSupport = null;
this.updateSkins = new Set();
this.updateMorphs = new Set();
this.skinTextures = new Map();
this.influenceTextures = new Map();
this.morphTextures = new Map();
this.textures = new Map();
this.splatResources = new Map();
this.textureBytes = 4;
this.shadowsDirty = true;
this.windState = { time: 0, strength: 0.3 };
// The shadow map the constructor draws uses no assembly, so a first frame with none does not draw it again.
this.assemblyAmount = 0;
// `resolveCoplanar` is resolveFlushParts from the coplanar-overlap addon, passed in so the search stays out of the core bundle.
// It ranks near-coplanar triangles (flushOrderOf in depth-layer.js) before the parts are grouped into batches.
if (resolveCoplanar && typeof resolveCoplanar !== 'function') throw new TypeError('resolveCoplanar is resolveFlushParts from crucible/addons/coplanar-overlap.');
if (resolveCoplanar && !benchmark) resolveCoplanar(parts);
this.fitParts = this.groundPart ? [...parts, this.groundPart] : parts;
const groups = groupParts(this.fitParts, batching);
const textureLimit = this.context.getParameter(this.context.MAX_TEXTURE_SIZE);
this.hasSkins = groups.some(group => group[0].skin || group[0].crowd);
this.hasMorphs = groups.some(group => group[0].morph);
if (this.hasSkins && (this.context.getParameter(this.context.MAX_VERTEX_TEXTURE_IMAGE_UNITS) < 2 || this.context.getParameter(this.context.MAX_COMBINED_TEXTURE_IMAGE_UNITS) < 8)) throw new Error('GPU skinning requires two vertex texture units and eight combined texture units.');
if (this.hasMorphs && (this.context.getParameter(this.context.MAX_VERTEX_TEXTURE_IMAGE_UNITS) < (this.hasSkins ? 3 : 1) || this.context.getParameter(this.context.MAX_COMBINED_TEXTURE_IMAGE_UNITS) < 9)) throw new Error('GPU morphing requires one additional vertex texture unit and nine combined texture units.');
const morphGeometries = new Set();
for (const group of groups) {
const part = group[0];
if (!part.morph || morphGeometries.has(part.geometry)) continue;
const texelCount = part.geometry.positions.length / 3 * part.geometry.morphTargets.length * 2;
this.textureBytes += morphSupport().skinTextureLayout(texelCount, textureLimit, 2).bytes;
morphGeometries.add(part.geometry);
}
const poses = new Set();
const skinGeometries = new Set();
for (const group of groups) {
const part = group[0];
if (part.crowd && !poses.has(part.crowd)) {
this.textureBytes += skinSupport().skinTextureLayout(part.crowd.data.length / 4, textureLimit, 4).bytes;
poses.add(part.crowd);
}
if (!part.skin) continue;
if (!poses.has(part.skin)) this.textureBytes += skinSupport().skinTextureLayout(part.skin.jointMatrices.length / 4, textureLimit, 4).bytes;
if (!skinGeometries.has(part.geometry)) this.textureBytes += skinSupport().skinTextureLayout(part.geometry.positions.length / 3 * 2, textureLimit, 2).bytes;
poses.add(part.skin);
skinGeometries.add(part.geometry);
}
const maps = new Set();
for (const group of groups) {
const material = group[0].material;
for (const [field, map] of [...MATERIAL_MAPS, 'lightMap'].map(name => [name, material[name]]).concat(Object.entries(material.layerMaps ?? {}))) {
if (!map) continue;
const info = textureDescriptorInfo(map, textureLimit);
if (['normalMap', 'metallicRoughnessMap', 'occlusionMap'].includes(field) && map.colorSpace !== 'linear') throw new Error(`${field} requires a linear texture descriptor.`);
if (field === 'emissiveMap' && (map.colorSpace ?? 'srgb') !== 'srgb') throw new Error('emissiveMap requires an srgb texture descriptor.');
if (!maps.has(map)) this.textureBytes += info.bytes;
maps.add(map);
}
}
this.splatBytes = 0;
const splatLayerSets = new Set();
for (const group of groups) {
const material = group[0].material;
if (!material.layers || splatLayerSets.has(material.layers)) continue;
splatLayerSets.add(material.layers);
this.splatBytes += requireSplatSupport().textureBytes(requireSplatSupport().resolveSize(material, textureLimit), material.layers.length) + (material.splat?.maskMap ? textureDescriptorInfo(material.splat.maskMap, textureLimit).bytes : 0);
}
this.textureBytes += this.splatBytes;
this.capabilities.maximumTextureSize = textureLimit;
this.environmentResources = null;
this.environmentBackgroundProgram = null;
this.environmentBytes = !benchmark && environment.map ? requireEnvironmentSupport().estimateBytes(environment.map, textureLimit) : 0;
this.textureBytes += this.environmentBytes;
for (const group of groups) {
const geometry = group[0].geometry;
if (geometry.uvs && geometry.uvs.length !== geometry.positions.length / 3 * 2) throw new Error('Geometry UV count must match the vertex count.');
if (hasMaterialMap(group[0].material) && !geometry.uvs && !geometry.lightUvs && !group[0].material.boxMapScale) throw new Error('Textured geometry requires UV channel 0.');
for (const coordinate of geometry.uvs ?? []) {
if (!Number.isFinite(coordinate)) throw new Error('Geometry UVs must be finite.');
}
if (geometry.colors && geometry.colors.length !== geometry.positions.length) throw new Error('Geometry colors must contain RGB for every vertex.');
}
const expectedGeometryBytes = groups.reduce((total, group) => total + geometryBufferBytes(group[0].geometry) + group.length * INSTANCE_STRIDE * 4, 0);
this.memoryBudgetMiB = planRenderSize({ width: Math.max(1, canvas.clientWidth), height: Math.max(1, canvas.clientHeight), pixelRatio, samples: this.samples, memoryBudgetMiB, geometryBytes: expectedGeometryBytes, textureBytes: this.textureBytes, hdr: this.hdr, bloom: !benchmark, depth: this.depth, maximumSize: textureLimit, maximumMemoryBudgetMiB }).memoryBudgetMiB;
this.maximumMemoryBudgetMiB = maximumMemoryBudgetMiB;
this.view = mat4.create();
this.projection = mat4.create();
this.viewProjection = mat4.create();
this.lightProjection = mat4.create();
this.shadowBiasPerSlope = 0;
this.inverseViewProjection = mat4.create();
this.shaderFeatures = shaderFeaturesOfParts(groups.flat());
if (groups.some(group => group.length > 1)) this.shaderFeatures.add('instanced');
this.shaderFeatures.add(environment.map ? 'environmentMap' : 'studioLighting');
shaderFeaturesOfLighting(this.lighting).forEach(feature => this.shaderFeatures.add(feature));
if (shading === 'light') this.shaderFeatures.add(LIGHT_SHADING_FEATURE);
this.shaderFeatures.add(FRAGMENT_SHADOW_POSITION_FEATURE);
if (shadowCascades) this.shaderFeatures.add(shadowCascades.shaderFeature);
// Cascades replace the single map the tint is cut against, and the tint map is a half float render target.
if (this.shaderFeatures.has('tintedShadows') && (shadowCascades || !this.context.getExtension('EXT_color_buffer_float'))) this.shaderFeatures.delete('tintedShadows');
this.tintedShadowsActive = this.shaderFeatures.has('tintedShadows');
// The camera-relative vertex line is part of the first compile, so reversed depth does not compile the main program twice.
if (reversedDepthWanted) prepareCameraRelativeProgram(this);
const pending = {
main: this.startMainProgram(),
depth: this.backend.startProgram(createDepthVertexShader(this.shaderFeatures), createDepthFragmentShader(this.shaderFeatures)),
};
if (!benchmark) {
pending.post = this.backend.startProgram(fullscreenVertex, this.withViewTransform(postFragment, 'post'));
pending.sky = this.backend.startProgram(fullscreenVertex, skyFragment);
pending.bloom = this.backend.startProgram(fullscreenVertex, bloomFragment);
if (environment.map) this.startEnvironmentPrograms();
}
// The driver links the programs on its own threads while the textures and buffers upload; only then is the link result read.
groups.forEach((group) => this.batches.push(this.uploadBatch(group)));
this.pendingConstruction = { pending, parts, environment };
this.deferEnvironmentPrefilter = deferEnvironmentPrefilter;
if (!deferProgramLink) this.finishConstruction();
}
// The second half of construction, which reads the link results. Reading a result waits for the driver, so a page that
// builds a heavy renderer passes deferProgramLink and awaits programsReady() instead of freezing for the whole compile.
finishConstruction({ deferFrameTargets = false } = {}) {
if (this.disposed || !this.pendingConstruction) return;
const { pending, parts, environment } = this.pendingConstruction;
this.pendingConstruction = null;
const benchmark = this.benchmark;
this.finishMainProgram(pending.main);
this.depthProgram = this.backend.finishProgram(pending.depth);
this.depthSkinUniforms = Object.fromEntries(SKIN_UNIFORMS.map(name => [name, this.context.getUniformLocation(this.depthProgram, name)]));
this.depthMorphUniforms = Object.fromEntries(MORPH_UNIFORMS.map(name => [name, this.context.getUniformLocation(this.depthProgram, name)]));
if (!benchmark) {
this.postProgram = this.backend.finishProgram(pending.post);
this.skyProgram = this.backend.finishProgram(pending.sky);
this.postUniforms = postUniformLocations(this.context, this.postProgram);
this.postVariants = new Map();
this.bloomProgram = this.backend.finishProgram(pending.bloom);
this.bloomUniforms = Object.fromEntries(['sourceTexture', 'texelDirection', 'threshold', 'extract'].map(name => [name, this.context.getUniformLocation(this.bloomProgram, name)]));
this.skyUniforms = Object.fromEntries(['skyTop', 'skyBottom', 'sunDirection', 'inverseViewProjection', 'eye', 'time', 'daylight', 'hdrEnabled'].map((name) => [name, this.context.getUniformLocation(this.skyProgram, name)]));
}
this.depthAlphaUniforms = Object.fromEntries(DEPTH_ALPHA_UNIFORMS.map(name => [name, this.context.getUniformLocation(this.depthProgram, name)]));
this.depthUniform = this.context.getUniformLocation(this.depthProgram, 'lightProjection');
this.depthAssemblyUniform = this.context.getUniformLocation(this.depthProgram, 'assemblyAmount');
this.depthWindUniforms = { time: this.context.getUniformLocation(this.depthProgram, 'time'), wind: this.context.getUniformLocation(this.depthProgram, 'wind') };
this.partCount = parts.length;
this.triangles = parts.reduce((total, part) => total + part.geometry.indices.length / 3, 0);
this.whiteTexture = this.createTexture(null);
// Disabled skin samplers still need distinct units from the depth sampler.
for (const [program, uniforms] of [[this.program, this.uniforms], [this.depthProgram, this.depthSkinUniforms]]) {
this.context.useProgram(program);
this.context.uniform1i(uniforms.skinInfluences, 6);
this.context.uniform1i(uniforms.jointPalette, 7);
}
for (const [program, uniforms] of [[this.program, this.uniforms], [this.depthProgram, this.depthMorphUniforms]]) {
this.context.useProgram(program);
this.context.uniform1i(uniforms.morphTargets, 8);
}
for (const unit of [6, 7, 8]) {
this.context.activeTexture(this.context.TEXTURE0 + unit);
this.context.bindTexture(this.context.TEXTURE_2D, this.whiteTexture);
}
if (this.shaderFeatures.has('splat')) requireSplatSupport().initializePlaceholders(this);
this.initializeEnvironment(environment.map);
this.createShadowMap();
if (this.reversedDepthMode !== false && !benchmark) installReversedDepth(this, this.reversedDepthMode);
if (!deferFrameTargets) this.allocateInitialTargets();
}
// The size plan and the frame targets: the largest driver calls of construction, so a page that awaits programsReady() takes them in a task of their own.
allocateInitialTargets() {
if (this.disposed) return;
this.resize();
if (!this.benchmark && !this.multisampleFramebuffer) this.allocateFrameTargets(this.canvas.width, this.canvas.height);
}
/** Resolves once every program started by the constructor has linked, polling without blocking the main thread, then finishes construction. Needs deferProgramLink. After dispose() it resolves at once without finishing construction. */
async programsReady() {
if (this.disposed) return;
if (!this.pendingConstruction) {
await this.initialTargetsPending;
return;
}
const context = this.context;
const parallelCompile = context.getExtension('KHR_parallel_shader_compile');
const { pending } = this.pendingConstruction;
const programs = [...Object.values(pending), ...(this.pendingEnvironmentPrograms?.values() ?? [])].map(started => started.program);
// A renderer disposed during the wait has deleted these programs, which would never report complete.
while (!this.disposed && parallelCompile && programs.some(program => !context.getProgramParameter(program, parallelCompile.COMPLETION_STATUS_KHR))) {
await new Promise(resolve => setTimeout(resolve, 8));
}
if (this.pendingConstruction) {
this.finishConstruction({ deferFrameTargets: true });
this.initialTargetsPending = new Promise(resolve => setTimeout(resolve, 0)).then(() => this.allocateInitialTargets());
}
await this.initialTargetsPending;
}
/**
* Draws `frame` once the way a real frame is drawn, but without freezing the page for programs the driver has not finished
* building (the post pass of a fog or sky frame, liquids, ambient occlusion, a reversed-depth copy). Each draw that meets one
* stops there; the driver's thread keeps building while this waits in short timers, then the draw runs again. The last
* draw is complete and leaves every program, target and texture that frame uses ready, so the next frame costs no more than
* any other. Call it while the canvas is hidden or another world is on screen. Past `timeoutMilliseconds` it draws the
* frame at once and resolves true when it never had to, false otherwise. On a disposed renderer it resolves false without drawing.
*/
async prepareFrame(frame, { timeoutMilliseconds = 6000 } = {}) {
await this.programsReady();
if (this.disposed) return false;
// The bloom targets take the driver tens of milliseconds under load: a frame that blooms allocates them in a task of its own, not inside the draw.
if (!this.benchmark && !this.bloomTargets.length && isBloomActive(resolveEffects(frame.effects))) {
await new Promise(resolve => setTimeout(resolve, 0));
if (this.disposed) return false;
this.ensureBloomTargets();
}
const context = this.context;
const deadline = performance.now() + timeoutMilliseconds;
setPreparing(context, true);
try {
for (;;) {
// dispose() may have run during any wait below: its programs are deleted and a draw would leak and raise GL errors.
if (this.disposed) return false;
try {
this.render(frame);
return true;
} catch (error) {
if (!(error instanceof ProgramNotReady)) throw error;
while (!this.disposed && !isLinkComplete(context, error.program) && performance.now() < deadline) await new Promise(resolve => setTimeout(resolve, 8));
if (this.disposed) return false;
if (performance.now() >= deadline) break;
}
}
} finally {
setPreparing(context, false);
}
this.render(frame);
return false;
}
selectViewTransform(viewTransform, lookSource) {
if ((viewTransform !== 'aces' || lookSource) && !viewTransformShader.apply) throw new Error("viewTransform and look need their shader code: add import '@codepawlhq/crucible/addons/view-transform-shader' (a recipe: await loadAgentSceneModules(recipe)).");
this.viewTransform = viewTransform;
this.lookSource = lookSource;
this.look = lookSource ? viewTransformShader.resolveLook(lookSource) : null;
}
// A recipe's environment.viewTransform and environment.look reach the renderer in each frame; a change recompiles the
// programs that carry the display curve (main, liquid, environment background, post) before the frame is drawn.
syncViewTransform(environment) {
const viewTransform = environment.viewTransform ?? this.defaultViewTransform;
const lookSource = environment.look ?? this.defaultLook;
if (viewTransform === this.viewTransform && lookSource === this.lookSource) return;
viewTransformShader.dispose?.(this);
this.selectViewTransform(viewTransform, lookSource);
if (this.benchmark) return;
const context = this.context;
this.rebuildMainProgram();
for (const variant of this.postVariants.values()) context.deleteProgram(variant.pending ? this.backend.finishProgram(variant.pending) : variant.program);
this.postVariants.clear();
context.deleteProgram(this.postProgram);
this.postProgram = this.backend.finishProgram(this.backend.startProgram(fullscreenVertex, this.withViewTransform(postFragment, 'post')));
this.postUniforms = postUniformLocations(context, this.postProgram);
// The liquid pass builds its program on its next draw, with the new curve (liquid-renderer.js).
if (this.liquidProgram) context.deleteProgram(this.liquidProgram);
this.liquidProgram = null;
if (this.environmentBackgroundProgram) context.deleteProgram(this.environmentBackgroundProgram);
this.environmentBackgroundProgram = null;
}
// The display curve and look of this renderer, spliced into one of its programs (view-transform-shader.js); the default curve changes nothing.
withViewTransform(source, kind) {
if (this.viewTransform === 'aces' && !this.look) return source;
return viewTransformShader.apply(source, kind, this.viewTransform, Boolean(this.look));
}
// Compiles the main program with only the shader features that this renderer's parts use, and finds its uniforms.
startMainProgram() {
const benchmark = this.benchmark;
const fragmentSource = benchmark ? benchmarkFragmentShader : this.withViewTransform(createFragmentShader(this.shaderFeatures), 'main');
return this.backend.startProgram(benchmark ? benchmarkVertexShader : createVertexShader(this.shaderFeatures), fragmentSource);
}
buildMainProgram() {
this.finishMainProgram(this.startMainProgram());
}
finishMainProgram(pendingProgram) {
this.program = this.backend.finishProgram(pendingProgram);
this.uniforms = Object.fromEntries(['materialDielectric', 'materialEmissionFresnel', 'materialCoat', 'materialSheen', 'materialAnisotropy', 'materialIridescence', 'lightLinkMask', 'boxMapScale', 'boxMapAxis', 'lightMap', 'lightMapScale', 'hasLightMap', 'viewProjection', 'flushBias', 'clipPerMetre', 'lightProjection', 'eye', 'armorColor', 'armorSurface', 'exposure', 'inspection', 'shadowMap', 'shadowBiasPerSlope', ...MAP_UNIFORMS, ...MAP_FLAGS, ...SKIN_UNIFORMS, ...MORPH_UNIFORMS, 'normalScale', 'occlusionStrength', 'materialMoss', 'wearEnabled', 'wearMetal', 'wearDirt', 'wearShape', 'wearDirtShape', ...SPLAT_UNIFORMS, 'hdrEnabled', 'time', 'wind', 'worldMode', 'daylight', 'fogColor', 'lightDirection', 'fogDensity', 'waterRipple', 'rippleTime', 'explosionProgress', 'explosionCenter', 'assemblyAmount', 'renderPassMode', 'renderPassDepthRange', 'renderPassObjectBase', 'baseColor', 'surface', 'instanceEmission', 'instanceOpacity', 'boxNormalMatrix', 'shadowBlind', 'compositeMode', 'tintShadowMap', 'tintBlind', ...ALPHA_UNIFORMS].map((name) => [name, this.context.getUniformLocation(this.program, name)]));
for (const name of LIGHT_UNIFORMS) {
this.uniforms[name] = this.context.getUniformLocation(this.program, name);
}
for (const name of ENVIRONMENT_UNIFORMS) this.uniforms[name] = this.context.getUniformLocation(this.program, name);
this.keepSamplerTypesApart();
}
// A sampler nobody has set reads texture unit 0, which holds the shadow map as a comparison sampler. One unit may not serve
// two sampler types, so every 2D sampler starts on unit 1 until a draw sets it.
keepSamplerTypesApart() {
const context = this.context;
context.useProgram(this.program);
const count = context.getProgramParameter(this.program, context.ACTIVE_UNIFORMS);
for (let index = 0; index < count; index++) {
const uniform = context.getActiveUniform(this.program, index);
if (uniform.type === context.SAMPLER_2D) context.uniform1iv(context.getUniformLocation(this.program, uniform.name), new Int32Array(uniform.size).fill(1));
}
}
/** The MSAA sample count for these parts at the canvas's current size: `samples`, or `denseSamples` when the scene is dense (#1163). */
chooseMultisampleSamples(parts) {
if (this.benchmark) return 0;
const requestedSamples = this.denseSamples == null ? this.baseSamples : samplesForDensity(parts, this.canvas, this.pixelRatio, this.baseSamples, this.denseSamples);
const shaded = this.shading === 'light' ? Math.min(requestedSamples, LIGHT_SHADING_MAXIMUM_SAMPLES) : requestedSamples;
return this.backend.supportedSampleCount(this.hdr ? this.context.RGBA16F : this.context.RGBA8, shaded);
}
get samples() {
return Math.max(1, this.multisampleSamples);
}
uploadBuffer(target, data, usage = this.context.STATIC_DRAW) {
const buffer = this.backend.createBuffer();
this.buffers.push(buffer);
this.backend.uploadBuffer(target, buffer, data, usage);
this.geometryBytes += data.byteLength;
return buffer;
}
// Without anisotropic filtering a mipmapped texture seen at a grazing angle (a floor, a road, an apron) falls to a
// blurred level long before its detail is gone. Applies to the texture bound to `target`.
applyAnisotropy(target) {
const context = this.context;
const extension = context.getExtension('EXT_texture_filter_anisotropic');
if (!extension) return;
// The limit is fixed for the context, and asking for it is a round trip to the GPU process, so it is asked once.
this.supportedAnisotropy ??= Math.min(MAX_TEXTURE_ANISOTROPY, context.getParameter(extension.MAX_TEXTURE_MAX_ANISOTROPY_EXT));
context.texParameterf(target, extension.TEXTURE_MAX_ANISOTROPY_EXT, this.supportedAnisotropy);
}
/**
* Uploads the large textures of `source` (parts, or texture descriptors) in bands of at most `maximumBytes`, yielding to
* the page after each band, so a later replaceParts or createTexture finds them ready instead of handing the driver every
* image in one call. Pixels equal a single upload. Compressed and small textures are left to createTexture.
* `checkpoint` is an async function that yields (createSlicer from cooperative.js).
*/
async preloadTextures(source, options = {}) {
const descriptors = source.flatMap(item => (item?.material ? materialMapState(item.material).slice(0, 5) : [item]));
// The slicing code loads on demand, so a renderer that never preloads does not carry it.
const { preloadRendererTextures } = await import('./texture-upload.js');
await preloadRendererTextures(this, descriptors, options);
}
createTexture(map) {
if (this.textures.has(map)) return this.textures.get(map);
const context = this.context;
const texture = context.createTexture();
context.bindTexture(context.TEXTURE_2D, texture);
const previousFlip = context.getParameter(context.UNPACK_FLIP_Y_WEBGL);
const previousColorSpace = context.getParameter(context.UNPACK_COLORSPACE_CONVERSION_WEBGL);
try {
context.pixelStorei(context.UNPACK_FLIP_Y_WEBGL, map?.flipY ?? false);
context.pixelStorei(context.UNPACK_COLORSPACE_CONVERSION_WEBGL, context.NONE);
if (map) {
const info = textureDescriptorInfo(map, context.getParameter(context.MAX_TEXTURE_SIZE));
if (map.image.compressed) map.image.compressed.upload(context);
else context.texImage2D(context.TEXTURE_2D, 0, map.colorSpace === 'linear' ? context.RGBA8 : context.SRGB8_ALPHA8, context.RGBA, context.UNSIGNED_BYTE, map.image);
configureTexture(this, info);
} else {
context.texImage2D(context.TEXTURE_2D, 0, context.RGBA8, 1, 1, 0, context.RGBA, context.UNSIGNED_BYTE, new Uint8Array([255, 255, 255, 255]));
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.LINEAR);
}
} catch (error) {
context.deleteTexture(texture);
throw error;
} finally {
context.pixelStorei(context.UNPACK_FLIP_Y_WEBGL, previousFlip);
context.pixelStorei(context.UNPACK_COLORSPACE_CONVERSION_WEBGL, previousColorSpace);
}
this.textures.set(map, texture);
return texture;
}
// Re-uploads a descriptor's pixels: the whole image (update.image, or the descriptor image again) or update.region {x, y, width, height, data}.
// The code is in the texture-update addon, so a scene that never updates a texture does not carry it.
updateTexture(descriptor, update = {}) {
if (!textureUpdateSupport.update) throw new Error("updateTexture needs its code: add import '@codepawlhq/crucible/addons/texture-update'.");
textureUpdateSupport.update(this, descriptor, update);
}
// Parts can arrive after construction (replaceParts) or change their tag (updateParts). When one needs a shader feature
// that the program left out, the program is compiled again with that feature added.
requireShaderFeatures(parts) {
this.requireFeatureNames([...shaderFeaturesOfParts(parts), ...(parts.length > 1 ? ['instanced'] : [])]);
}
requireFeatureNames(features) {
if (this.benchmark || !this.shaderFeatures) return;
const missing = features.filter(feature => !this.shaderFeatures.has(feature));
if (missing.length === 0) return;
missing.forEach(feature => this.shaderFeatures.add(feature));
this.rebuildMainProgram();
}
rebuildMainProgram() {
const context = this.context;
const previousProgram = this.program;
this.buildMainProgram();
context.deleteProgram(previousProgram);
context.useProgram(this.program);
for (const [name, unit] of [['skinInfluences', 6], ['jointPalette', 7], ['morphTargets', 8], ...Object.entries(SPLAT_UNITS), ['environmentSpecular', ENVIRONMENT_SPECULAR_UNIT], ['environmentBrdf', ENVIRONMENT_BRDF_UNIT]]) {
context.uniform1i(this.uniforms[name], unit);
}
context.uniform1f(this.uniforms.splatEnabled, 0);
if (this.shaderFeatures.has('splat') && !this.splatPlaceholder) requireSplatSupport().initializePlaceholders(this);
}
uploadBatch(parts) {
this.requireShaderFeatures(parts);
const context = this.context;
const vertexArray = context.createVertexArray();
try {
return this.uploadBatchData(parts, vertexArray);
} catch (error) {
context.bindVertexArray(null);
context.deleteVertexArray(vertexArray);
throw error;
}
}
/** Sets the surface wear uniforms of a batch; a material without wear turns the term off. */
bindSurfaceWear(wear) {
const { context, uniforms } = this;
context.uniform1f(uniforms.wearEnabled, wear ? 1 : 0);
if (!wear) return;
const values = wearUniformValues(wear);
context.uniform4fv(uniforms.wearMetal, values.metal);
context.uniform4fv(uniforms.wearDirt, values.dirt);
context.uniform4fv(uniforms.wearShape, values.shape);
context.uniform2fv(uniforms.wearDirtShape, values.dirtShape);
}
/** Binds the geometry's vertex buffers and attributes into the bound vertex array. */
bindGeometryAttributes(geometry, material) {
const context = this.context;
let geometryBuffers = this.geometryBuffers.get(geometry);
if (!geometryBuffers) {
geometryBuffers = new Map();
for (const field of ['positions', 'normals', 'uvs', 'colors', 'indices', 'crowdPacked']) {
if (geometry[field]) {
const target = field === 'indices' ? context.ELEMENT_ARRAY_BUFFER : context.ARRAY_BUFFER;
const values = field === 'uvs' && geometry.lightUvs ? interleaveUvSets(geometry) : geometry[field];
geometryBuffers.set(field, this.uploadBuffer(target, field === 'colors' && vertexAlpha(geometry) ? interleaveColorsWithSkyVisibility(geometry) : values));
}
}
if (vertexAlpha(geometry) && !geometry.colors) geometryBuffers.set('colors', this.uploadBuffer(context.ARRAY_BUFFER, interleaveColorsWithSkyVisibility(geometry)));
if (geometry.lightUvs && !geometry.uvs) geometryBuffers.set('uvs', this.uploadBuffer(context.ARRAY_BUFFER, interleaveUvSets(geometry)));
this.geometryBuffers.set(geometry, geometryBuffers);
}
for (const [location, field] of [[0, 'positions'], [1, 'normals']]) {
context.bindBuffer(context.ARRAY_BUFFER, geometryBuffers.get(field));
context.enableVertexAttribArray(location);
context.vertexAttribPointer(location, 3, context.FLOAT, false, 0, 0);
}
if (geometry.lightUvs && geometry.lightUvs.length !== geometry.positions.length / 3 * 2) throw new Error('Geometry lightUvs count must match the vertex count.');
if (geometry.uvs || geometry.lightUvs) {
if (geometry.uvs && geometry.uvs.length !== geometry.positions.length / 3 * 2) throw new Error('Geometry UV count must match the vertex count.');
context.bindBuffer(context.ARRAY_BUFFER, geometryBuffers.get('uvs'));
context.enableVertexAttribArray(13);
context.vertexAttribPointer(13, geometry.lightUvs ? 4 : 2, context.FLOAT, false, 0, 0);
} else {
if (hasMaterialMap(material) && !material.boxMapScale) throw new Error('Textured geometry requires UV channel 0.');
context.disableVertexAttribArray(13);
// (-1, -1) marks "no UVs": grass wind then bends by local height instead of by blade position.
context.vertexAttrib2f(13, -1, -1);
}
if (geometry.colors && geometry.colors.length !== geometry.positions.length) throw new Error('Geometry colors must contain RGB for every vertex.');
if (vertexAlpha(geometry) && vertexAlpha(geometry).length !== geometry.positions.length / 3) throw new Error('Geometry skyVisibility must hold one value for every vertex.');
if (geometry.colors || vertexAlpha(geometry)) {
context.bindBuffer(context.ARRAY_BUFFER, geometryBuffers.get('colors'));
context.enableVertexAttribArray(14);
context.vertexAttribPointer(14, vertexAlpha(geometry) ? 4 : 3, context.FLOAT, false, 0, 0);
} else {
context.disableVertexAttribArray(14);
context.vertexAttrib3f(14, 1, 1, 1);
}
// A crowd geometry packs four joint ids and weights into the colour attribute; its UVs stay free for maps.
if (geometry.crowdPacked) {
context.bindBuffer(context.ARRAY_BUFFER, geometryBuffers.get('crowdPacked'));
context.enableVertexAttribArray(14);
context.vertexAttribPointer(14, 4, context.FLOAT, false, 0, 0);
}
context.bindBuffer(context.ELEMENT_ARRAY_BUFFER, geometryBuffers.get('indices'));
}
/** Points the instance attributes of the bound vertex array at the bound array buffer. */
pointInstanceAttributes() {
const stride = INSTANCE_STRIDE;
for (let column = 0; column < 4; column++) this.attribute(2 + column, 4, stride * 4, column * 16);
for (let column = 0; column < 3; column++) this.attribute(6 + column, 3, stride * 4, 64 + column * 12);
this.attribute(9, 3, stride * 4, 100);
this.attribute(10, 4, stride * 4, 112);
this.attribute(11, 3, stride * 4, 128);
this.attribute(12, 3, stride * 4, 140);
this.attribute(15, 4, stride * 4, 152);
}
createCullingState(parts) {
const first = parts[0];
const cullable = isCullable(parts);
if (first.lods) {
validateLods(first, first.lods);
if (!cullable) throw new RangeError(`lods need rigid or swaying, opaque parts without assembly motion: ${first.name}`);
}
if (first.shadowLods) {
validateLods(first, first.shadowLods);
if (!cullable) throw new RangeError(`shadowLods need rigid or swaying, opaque parts without assembly motion: ${first.name}`);
}
const levels = first.lods ?? [{ geometry: first.geometry, error: 0 }];
const sphere = first.crowd?.bounds ?? geometryBoundingSphere(first.geometry);
const bounds = { center: sphere.center, radius: sphere.radius + Math.max(...levels.map(level => level.error)) };
const shadowLevels = first.shadowLods ? createLevelSet(first.shadowLods, parts.length) : null;
const swayReach = SWAYING_TAGS.has(first.material.tag) ? SWAY_REACH_PER_STRENGTH : 0;
return { cullable, bounds, swayReach, ...createLevelSet(levels, parts.length), shadowLevels };
}
/** The vertex array and instance buffer that draw one level of a batch (or of its `shadowLevels`) from the instances selected for it. */
levelDraw(batch, level, levelSet = batch) {
if (levelSet.levelDraws[level]) return levelSet.levelDraws[level];
const context = this.context;
const ranked = levelSet === batch && level === 0;
const geometry = (ranked && batch.flushOrder?.geometry) || levelSet.levelGeometries[level];
const vertexArray = context.createVertexArray();
context.bindVertexArray(vertexArray);
this.bindGeometryAttributes(geometry, batch.parts[0].material);
if (batch.flushIndexBuffer && ranked) context.bindBuffer(context.ELEMENT_ARRAY_BUFFER, batch.flushIndexBuffer);
const instanceBuffer = context.createBuffer();
this.buffers.push(instanceBuffer);
context.bindBuffer(context.ARRAY_BUFFER, instanceBuffer);
context.bufferData(context.ARRAY_BUFFER, batch.instanceData.byteLength, context.DYNAMIC_DRAW);
this.pointInstanceAttributes();
context.bindVertexArray(null);
levelSet.levelDraws[level] = { vertexArray, instanceBuffer, indexCount: geometry.indices.length };
return levelSet.levelDraws[level];
}
releaseLevelDraws(batch, releasedBuffers) {
for (const levelSet of [batch, batch.shadowLevels]) {
if (!levelSet) continue;
for (const draw of levelSet.levelDraws) {
if (!draw) continue;
this.context.deleteVertexArray(draw.vertexArray);
releasedBuffers?.add(draw.instanceBuffer);
}
levelSet.levelDraws = [];
}
}
/** The instances of a batch that the camera can see, split by level; null when the whole batch draws as it is. */
selectBatchInstances(batch) {
if (!this.culling || !batch.cullable) return null;
return selectInstances(batch.selection, {
instanceData: batch.instanceData, instanceCount: batch.instanceCount, stride: INSTANCE_STRIDE, bounds: batch.bounds, margin: batch.swayReach * Math.abs(this.windState.strength),
levelErrors: batch.levelErrors, planes: this.frustumPlanes, viewProjection: this.viewProjection,
pixelsPerUnit: this.canvas.height / 2 * this.projection[5], pixelError: this.lodPixelError * (this.mirrorCulling?.lodScale ?? 1),
belowHeight: this.mirrorCulling?.belowHeight, minimumPixelRadius: this.mirrorCulling?.minimumPixelRadius,
});
}
drawSelectedLevels(batch, selection, levelSet = batch, flushRanges = null) {
const context = this.context;
const stride = INSTANCE_STRIDE;
for (let level = 0; level < selection.counts.length; level++) {
const count = selection.counts[level];
if (count === 0) continue;
const draw = this.levelDraw(batch, level, levelSet);
if (!(this.selectionScratch?.length >= count * stride)) this.selectionScratch = new Float32Array(count * stride);
for (let slot = 0; slot < count; slot++) {
const instance = selection.indices[level][slot];
this.selectionScratch.set(batch.instanceData.subarray(instance * stride, (instance + 1) * stride), slot * stride);
}
context.bindBuffer(context.ARRAY_BUFFER, draw.instanceBuffer);
context.bufferSubData(context.ARRAY_BUFFER, 0, this.selectionScratch, 0, count * stride);
context.bindVertexArray(draw.vertexArray);
// Only level 0 holds the ranked index order; the simpler levels draw far away, as one range.
if (flushRanges && level === 0) this.drawFlushRanges(batch, flushRanges, count);
else this.backend.drawIndexedInstanced(draw.indexCount, count);
}
}
/** Draws a batch rank by rank from its ranked index order (flush-resolve.js), each rank a little closer in depth. */
drawFlushRanges(batch, ranges, instanceCount) {
const base = (batch.depthLayer ?? 0) * RANKS_PER_LAYER;
for (const range of ranges) {
this.applyDepthRank(base + range.rank);
this.backend.drawIndexedInstanced(range.count, instanceCount, range.start);
}
this.applyDepthRank(base);
}
uploadBatchData(parts, vertexArray) {
const context = this.context;
const geometry = parts[0].geometry;
context.bindVertexArray(vertexArray);
const flushOrder = flushOrderOf(parts[0]);
// A cut geometry carries the ranked order as its own indices. Without cuts the ranked order replaces the geometry's
// index buffer in this vertex array only; the vertex buffers stay shared.
this.bindGeometryAttributes(flushOrder?.geometry ?? geometry, parts[0].material);
const flushIndexBuffer = flushOrder && !flushOrder.geometry ? this.uploadBuffer(context.ELEMENT_ARRAY_BUFFER, flushOrder.indices) : null;
const stride = INSTANCE_STRIDE;
const instanceData = new Float32Array(parts.length * stride);
const normalMatrix = mat3.create();
parts.forEach((part, index) => {
mat3.normalFromMat4(normalMatrix, part.matrix);
packInstance(instanceData, index, part, normalMatrix);
});
const instanceBuffer = this.uploadBuffer(context.ARRAY_BUFFER, instanceData, context.DYNAMIC_DRAW);
this.pointInstanceAttributes();
context.bindVertexArray(null);
const map = parts[0].material.map ?? null;
const mapState = materialMapState(parts[0].material);
const textures = mapState.slice(0, 5).map(descriptor => this.createTexture(descriptor));
const splat = parts[0].material.layers ? requireSplatSupport().createResources(this, parts[0].material, requireSplatSupport()) : null;
const lightMapTexture = mapState[14] ? this.createTexture(mapState[14]) : null;
if (lightMapTexture && (parts[0].skin || parts[0].morph || !geometry.lightUvs)) throw new Error('A light map needs lightUvs on rigid geometry, with no skin or morph.');
const skin = parts[0].skin ?? null;
const skinTexture = skin ? this.createSkinTexture(this.skinTextures, skin, skin.jointMatrices, 4) : null;
const influenceTexture = skin ? this.createSkinTexture(this.influenceTextures, geometry, null, 2) : null;
const crowd = parts[0].crowd ?? null;
const crowdTexture = crowd ? this.createSkinTexture(this.skinTextures, crowd, crowd.data, 4) : null;
const morph = parts[0].morph ?? null;
const morphTexture = morph ? this.createMorphTexture(geometry, morph) : null;
const morphWeights = morph ? new Float32Array(morph.weights) : null;
const [alphaMode, alphaCutoff, opacity, doubleSided, retro, waterGlint] = materialAlphaState(parts[0].material);
const layerState = materialLayerState(parts[0].material);
const culling = this.createCullingState(parts);
const batch = { ...culling, alphaMode, alphaCutoff, opacity, doubleSided, retro, waterGlint, mirrored: isMirroredMatrix(parts[0].matrix), layerState, wear: parts[0].material.wear ?? null, parts: [...parts], vertexArray, instanceBuffer, instanceData, textures, mapState, splat, lightMapTexture, texture: textures[0], map, skin, skinTexture, influenceTexture, crowd, crowdTexture, morph, morphTexture, morphWeights, indexCount: flushOrder?.indices.length ?? geometry.indices.length, instanceCount: parts.length, floor: parts[0].material.tag === 'floor', castShadow: castsShadow(parts[0]), tintedShadow: castsTintedShadow(parts[0]), tintBlind: Boolean(splat) || Object.keys(parts[0].material.layerMaps ?? {}).length >= 3, receivesShadow: receivesShadow(parts[0]), compositeMode: compositeModeOf(parts[0]), depthLayer: depthLayerOf(parts[0]), flushOrder, flushIndexBuffer, pass: partPass(parts[0]) };
if (parts[0].lods) culling.levelGeometries.forEach((geometryOfLevel, level) => this.levelDraw(batch, level));
culling.shadowLevels?.levelGeometries.forEach((geometryOfLevel, level) => this.levelDraw(batch, level, batch.shadowLevels));
parts.forEach((part, index) => this.partLocations.set(part, { batch, index, geometry: part.geometry, map, mapState, layerState, skin, jointMatrices: skin?.jointMatrices, skinIndices: geometry.skinIndices, skinWeights: geometry.skinWeights, morph, morphWeights: morph?.weights, morphTargets: geometry.morphTargets, normalMatrix: mat3.create(), committedMatrix: batch.instanceData.subarray(index * INSTANCE_STRIDE, index * INSTANCE_STRIDE + 16) }));
return batch;
}
/** Reconcile immutable rigid, untextured geometry without rebuilding programs or render targets. `retainedUnchanged` skips the re-sync of parts in kept batches, for a world that grows in slices. */
replaceParts(parts, { regroupOnly = false, retainedUnchanged = false } = {}) {
if (!Array.isArray(parts) || new Set(parts).size !== parts.length) {
throw new TypeError('Scene parts must be an array with distinct object identities.');
}
const renderParts = this.groundPart ? [...parts, this.groundPart] : parts;
// Local volumes bind to parts by name, so they must see the new list after a topology change.
this.sceneParts = parts;
this.fitParts = renderParts;
this.fitBounds = undefined;
this.densityParts = parts;
// A scene that gained or lost triangles can cross the density threshold with no size change; resize() judges it again and rebuilds the targets.
const resampled = this.denseSamples != null && this.chooseMultisampleSamples(this.densityParts) !== this.multisampleSamples;
const grouped = groupWorld(retainedUnchanged ? this.incrementalGrouping : null, parts, this.groundPart, this.batching, retainedUnchanged);
this.incrementalGrouping = grouped.state;
const groups = grouped.batches;
const geometries = new Set(renderParts.flatMap(partGeometries));
// Uploaded geometry was validated when it arrived; rechecking a large static scene every frame dominated streamed playback.
for (const geometry of geometries) {
if (!this.geometryBuffers.has(geometry)) validateReplacementGeometry(geometry);
}
const retained = new Set();
// Groups share a few materials, and the layer state is 28 validated values, so each material answers once per call.
const layerStates = new Map();
const layerStateOf = material => {
if (!layerStates.has(material)) layerStates.set(material, materialLayerState(material));
return layerStates.get(material);
};
const replacements = groups.map(group => {
const first = group[0];
const location = this.partLocations.get(first);
const batch = location?.batch;
const mapState = materialMapState(first.material);
const sameParts = batch?.parts.length === group.length && batch.parts.every((part, index) => part === group[index]);
const alphaState = materialAlphaState(first.material);
const sameState = location?.geometry === first.geometry && batch?.castShadow === castsShadow(first) && batch.receivesShadow === receivesShadow(first) && batch.compositeMode === compositeModeOf(first) && (batch.depthLayer ?? 0) === depthLayerOf(first) && (batch.flushOrder ?? null) === flushOrderOf(first) &&
batch.floor === (first.material.tag === 'floor') && batchPass(batch) === partPass(first) &&
[batch.alphaMode, batch.alphaCutoff, batch.opacity, batch.doubleSided, batch.retro, batch.waterGlint].every((value, index) => value === alphaState[index]) &&
batch.mapState.every((value, index) => value === mapState[index]) &&
batch.layerState.every((value, index) => value === layerStateOf(first.material)[index]);
if (sameParts && sameState) {
retained.add(batch);
return { group, batch };
}
return { group, batch: null };
});
// Skinned and morphed batches stay valid only while retained unchanged. Textured ones need the replace-textured-parts addon to be added or dropped.
for (const item of replacements) {
if (!item.batch && item.group.some(part => partNeedsFullUpload(part, regroupOnly || Boolean(texturedReplaceSupport.begin)))) {
throw new Error('replaceParts can add or change only rigid, untextured parts. Keep textured, skinned and morphed parts unchanged, or import replace-textured-parts to add textured ones.');
}
}
for (const [part, location] of this.partLocations) {
if (retained.has(location.batch)) continue;
if (location.skin || location.morph || location.morphTargets || location.skinIndices || (location.mapState.slice(0, 5).some(Boolean) && !texturedReplaceSupport.begin && !regroupOnly)) {
throw new Error(`replaceParts can remove or regroup only existing rigid, untextured parts; ${part.name} is textured, skinned or morphed and needs a new renderer.`);
}
}
const newGeometryBytes = [...geometries].filter(geometry => !this.geometryBuffers.has(geometry)).reduce((total, geometry) => total + geometryBufferBytes(geometry), 0);
const newInstanceBytes = replacements.filter(item => !item.batch).reduce((total, item) => total + item.group.length * INSTANCE_STRIDE * 4, 0);
const frameBytes = estimateFrameBytes(this.canvas.width, this.canvas.height, this.samples, 2048, { hdr: this.hdr, bloom: !this.benchmark, depth: this.depth });
const peakBytes = frameBytes + this.textureBytes + this.geometryBytes + newGeometryBytes + newInstanceBytes;
if (peakBytes > this.memoryBudgetMiB * 1024 * 1024) {
throw memoryBudgetError(this.geometryBytes + newGeometryBytes + newInstanceBytes, this.textureBytes, frameBytes, this.memoryBudgetMiB, { maximumMemoryBudgetMiB: this.maximumMemoryBudgetMiB });
}
const previousLocations = this.partLocations;
const previousBuffers = [...this.buffers];
const previousGeometryBytes = this.geometryBytes;
const previousGeometryBuffers = new Map(this.geometryBuffers);
const settleTextures = texturedReplaceSupport.begin?.(this);
const stagedLocations = new Map();
const stagedBatches = [];
this.partLocations = stagedLocations;
try {
for (const item of replacements) {
if (item.batch) {
stagedBatches.push(item.batch);
for (const part of item.group) {
stagedLocations.set(part, previousLocations.get(part));
}
} else {
stagedBatches.push(this.uploadBatch(item.group));
}
}
const error = this.context.getError();
if (error !== 0) {
throw new Error(`WebGL replacement allocation failed with error ${error}.`);
}
} catch (error) {
for (const batch of stagedBatches) {
if (!retained.has(batch)) {
this.context.deleteVertexArray(batch.vertexArray);
this.releaseLevelDraws(batch);
}
}
for (const buffer of this.buffers.slice(previousBuffers.length)) {
this.context.deleteBuffer(buffer);
}
this.context.bindVertexArray(null);
this.buffers = previousBuffers;
this.geometryBytes = previousGeometryBytes;
this.geometryBuffers = previousGeometryBuffers;
settleTextures?.();
this.partLocations = previousLocations;
throw error;
}
const releasedBuffers = new Set();
for (const batch of this.batches) {
if (!retained.has(batch)) {
this.context.deleteVertexArray(batch.vertexArray);
releasedBuffers.add(batch.instanceBuffer);
if (batch.flushIndexBuffer) releasedBuffers.add(batch.flushIndexBuffer);
this.releaseLevelDraws(batch, releasedBuffers);
}
}
for (const [geometry, buffers] of this.geometryBuffers) {
if (!geometries.has(geometry)) {
for (const buffer of buffers.values()) releasedBuffers.add(buffer);
this.geometryBuffers.delete(geometry);
}
}
for (const buffer of releasedBuffers) this.context.deleteBuffer(buffer);
this.buffers = this.buffers.filter(buffer => !releasedBuffers.has(buffer));
settleTextures?.(this.batches, stagedBatches);
this.geometryBytes = [...geometries].reduce((total, geometry) => total + geometryBufferBytes(geometry), 0) + renderParts.length * INSTANCE_STRIDE * 4;
this.batches = stagedBatches;
this.partCount = parts.length;
this.triangles = parts.reduce((total, part) => total + part.geometry.indices.length / 3, 0);
this.updateBatches.clear();
this.shadowsDirty = true;
// With retainedUnchanged the caller promises that parts of kept batches did not move, so only the new batches are re-synced.
this.updateParts(retainedUnchanged ? renderParts.filter(part => !retained.has(this.partLocations.get(part)?.batch)) : renderParts);
if (resampled) this.resize();
return parts.length;
}
createSkinTexture(cache, identity, matrices, groupSize) {
if (cache.has(identity)) return cache.get(identity);
const context = this.context;
const texelCount = matrices ? matrices.length / 4 : identity.positions.length / 3 * 2;
const layout = skinSupport().skinTextureLayout(texelCount, context.getParameter(context.MAX_TEXTURE_SIZE), groupSize);
const data = matrices ? new Float32Array(layout.width * layout.height * 4) : skinSupport().packSkinInfluences(identity, layout);
if (matrices) data.set(matrices);
const record = this.createPackedTexture(layout, data);
record.pose = matrices ? identity : null;
cache.set(identity, record);
return record;
}
createMorphTexture(geometry, pose) {
if (this.morphTextures.has(geometry)) return this.morphTextures.get(geometry);
const info = morphSupport().validateMorphGeometry(geometry, pose);
const layout = morphSupport().skinTextureLayout(info.vertexCount * info.targetCount * 2, this.context.getParameter(this.context.MAX_TEXTURE_SIZE), 2);
const record = this.createPackedTexture(layout, morphSupport().packMorphTargets(geometry, layout));
record.info = info;
this.morphTextures.set(geometry, record);
return record;
}
createPackedTexture(layout, data) {
const context = this.context;
const texture = context.createTexture();
context.bindTexture(context.TEXTURE_2D, texture);
try {
context.texImage2D(context.TEXTURE_2D, 0, context.RGBA32F, layout.width, layout.height, 0, context.RGBA, context.FLOAT, data);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.NEAREST);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.NEAREST);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, context.CLAMP_TO_EDGE);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, context.CLAMP_TO_EDGE);
} catch (error) {
context.deleteTexture(texture);
throw error;
}
return { ...layout, texture, data };
}
/**
* Upload changed parts. `checks: false` skips the per-frame pose checks (finite, non-singular, unmirrored skin and
* morph transforms) for poses already checked where they were made, such as `applyAnimation(time, clip, { checks: false })`.
* Identity, material and transform rules still apply.
*/
updateParts(parts, { shadows = true, checks = true } = {}) {
if (typeof checks !== "boolean") throw new TypeError("updateParts checks must be a boolean.");
this.updatePartIdentities ??= new Set();
this.updatePartIdentities.clear();
this.updateSkins.clear();
this.updateMorphs ??= new Set();
this.updateMorphs.clear();
this.updateBatches.clear();
const locations = this.updateLocations ??= [];
locations.length = parts.length;
let mirrorChanged = false;
// Preflight every part before touching packed data or submitting GPU writes.
for (let partIndex = 0; partIndex < parts.length; partIndex++) {
const part = parts[partIndex];
const location = this.partLocations.get(part);
if (!location) throw new Error(`Unknown part identity: ${part.name}`);
locations[partIndex] = location;
if (part.skin || part.morph) this.updatePartIdentities.add(part);
validatePartFlags(part);
if (castsShadow(part) !== location.batch.castShadow) throw new Error(`Shadow casting changes require a new renderer: ${part.name}`);
if (receivesShadow(part) !== location.batch.receivesShadow || (part.shadowOnly === true) !== (batchPass(location.batch) === 'shadowOnly') || compositeModeOf(part) !== location.batch.compositeMode) throw new Error(`receiveShadow, holdout, shadowCatcher and shadowOnly changes require replaceParts: ${part.name}`);
if (depthLayerOf(part) !== (location.batch.depthLayer ?? 0)) throw new Error(`depthLayer changes require replaceParts: ${part.name}`);
// A material whose fields still equal the ones that passed the full checks below needs none of them again.
const materialUnchanged = location.materialSnapshot?.matches(part.material) === true;
if (!materialUnchanged) {
const alphaState = materialAlphaState(part.material);
const batchAlphaState = [location.batch.alphaMode, location.batch.alphaCutoff, location.batch.opacity, location.batch.doubleSided, location.batch.retro, location.batch.waterGlint];
if (alphaState.some((value, index) => value !== batchAlphaState[index])) throw new Error(`Alpha mode, cutoff, double-sided, retro and mask opacity changes require a new renderer: set them when the part is made (blend and add opacity may change): ${part.name}`);
}
if (part.geometry !== location.geometry) throw new Error(`Geometry changes require a new renderer: ${part.name}`);
if (isMirroredMatrix(part.matrix) !== Boolean(location.batch.mirrored)) mirrorChanged = true;
if (!materialUnchanged && partPass(part) !== batchPass(location.batch)) throw new Error(`Moving a part into or out of the liquid or foam pass requires replaceParts: ${part.name}`);
if ((part.skin ?? null) !== location.skin || part.skin?.jointMatrices !== location.jointMatrices || part.geometry.skinIndices !== location.skinIndices || part.geometry.skinWeights !== location.skinWeights) throw new Error(`Skin identity changes require a new renderer: ${part.name}`);
if (part.skin) {
if (PROCEDURAL_MATERIAL_TAGS.has(part.material.tag)) throw new Error('Skinned parts require a standard material tag.');
if (checks) skinSupport().validateSkinPose(part.skin, part.geometry, part.matrix);
this.updateSkins.add(location.batch.skinTexture);
}
if ((part.morph ?? null) !== (location.morph ?? null) || part.morph?.weights !== location.morphWeights || part.geometry.morphTargets !== location.morphTargets) throw new Error(`Morph identity changes require a new renderer: ${part.name}`);
if (part.morph) {
if (PROCEDURAL_MATERIAL_TAGS.has(part.material.tag)) throw new Error('Morphed parts require a standard material tag.');
if (checks) morphSupport().validateMorphTransform(part.morph, location.batch.morphTexture.info, part.matrix, part.skin);
this.updateMorphs.add(part.morph);
}
if (materialUnchanged) {
validateTransform(part, location.normalMatrix);
continue;
}
if ((part.material.map ?? null) !== location.map) throw new Error(`Texture map changes require a new renderer: ${part.name}`);
validateMaterialMaps(part.material);
const normalScale = part.material.normalScale ?? DEFAULT_NORMAL_SCALE;
const mapState = location.mapState;
for (let index = 0; index < MATERIAL_MAPS.length; index++) {
if ((part.material[MATERIAL_MAPS[index]] ?? null) !== mapState[index]) throw new Error(`Material map or scale changes require a new renderer: ${part.name}`);
}
const [lightMapDescriptor, lightMapScale] = lightMapState(part.material);
if (lightMapDescriptor !== (mapState[14] ?? null) || lightMapScale !== (mapState[15] ?? 0) || (part.material.layerMaps ?? null) !== (mapState[18] ?? null)) throw new Error(`Light map and layer texture changes require a new renderer: ${part.name}`);
if (normalScale[0] !== mapState[5] || normalScale[1] !== mapState[6] || (part.material.occlusionStrength ?? 1) !== mapState[7] || mossState(part.material).some((value, index) => value !== mapState[8 + index]) || materialLayerState(part.material).some((value, index) => value !== location.layerState[index])) throw new Error(`Material map or scale changes require a new renderer: ${part.name}`);
validateTransform(part, location.normalMatrix);
location.materialSnapshot = MaterialSnapshot.of(part.material);
}
// A part that crossed a mirror (a flip animation, a toggled billboard) belongs to the other winding batch: regroup every part once.
// replaceParts packs all parts again, so the rest of this update is done.
if (mirrorChanged) {
this.replaceParts([...this.partLocations.keys()].filter(part => part !== this.groundPart), { regroupOnly: true });
return parts.length;
}
// A palette upload also changes consumers absent from the submitted part list.
if (checks && this.updateSkins.size) {
for (const [part, location] of this.partLocations) {
if (!location.skin || !this.updateSkins.has(location.batch.skinTexture) || this.updatePartIdentities.has(part)) continue;
const committedMatrix = location.committedMatrix ?? location.batch.instanceData.subarray(location.index * INSTANCE_STRIDE, location.index * INSTANCE_STRIDE + 16);
skinSupport().validateSkinPose(location.skin, location.geometry, committedMatrix);
}
}
// Shared weights also affect batches absent from the submitted part list.
// Nothing is shared when the update carries no morph and no skin.
if (checks && (this.updateMorphs.size || this.updateSkins.size)) {
for (const [part, location] of this.partLocations) {
if (!location.morph || this.updatePartIdentities.has(part)) continue;
if (!this.updateMorphs.has(location.morph) && !this.updateSkins.has(location.batch.skinTexture)) continue;
const committedMatrix = location.committedMatrix ?? location.batch.instanceData.subarray(location.index * INSTANCE_STRIDE, location.index * INSTANCE_STRIDE + 16);
morphSupport().validateMorphTransform(location.morph, location.batch.morphTexture.info, committedMatrix, location.skin);
}
}
this.updateBatches.clear();
for (let partIndex = 0; partIndex < parts.length; partIndex++) {
const part = parts[partIndex];
const location = locations[partIndex];
// A tag can change between frames without a new batch, so its shader code may not be compiled yet.
if (TAG_SHADER_FEATURES.has(part.material.tag) && !this.shaderFeatures?.has(part.material.tag)) this.requireShaderFeatures([part]);
packInstance(location.batch.instanceData, location.index, part, location.normalMatrix);
this.updateBatches.add(location.batch);
}
for (const batch of this.updateBatches) {
this.context.bindBuffer(this.context.ARRAY_BUFFER, batch.instanceBuffer);
this.context.bufferSubData(this.context.ARRAY_BUFFER, 0, batch.instanceData);
}
for (const record of this.updateSkins) {
// Each texture record belongs to one pose and keeps its padded upload buffer.
const pose = record.pose;
record.data.set(pose.jointMatrices);
this.context.bindTexture(this.context.TEXTURE_2D, record.texture);
this.context.texSubImage2D(this.context.TEXTURE_2D, 0, 0, 0, record.width, record.height, this.context.RGBA, this.context.FLOAT, record.data);
}
for (const batch of this.batches ?? []) {
if (batch.morph && this.updateMorphs.has(batch.morph)) batch.morphWeights.set(batch.morph.weights);
}
if (shadows && parts.length > 0) this.shadowsDirty = true;
return parts.length;
}
attribute(location, size, stride, offset) {
this.context.enableVertexAttribArray(location);
this.context.vertexAttribPointer(location, size, this.context.FLOAT, false, stride, offset);
this.context.vertexAttribDivisor(location, 1);
}
// A one texel map stays cleared to the far depth, so every point reads as lit. That is exact when nothing casts, and when
// cascades replace the main shader's lookup and nothing else (volume fog, subsurface thickness) still reads this map.
shadowMapSizeWanted() {
const casts = this.batches.some(batch => !batch.floor && batch.castShadow && !this.tintsShadow(batch));
return casts && !this.shadowCascades?.replacesSingleMap(this) ? SHADOW_MAP_SIZE : 1;
}
createShadowMap() {
const context = this.context;
const mapSize = this.shadowMapSizeWanted();
this.shadowTexture ??= context.createTexture();
context.activeTexture(context.TEXTURE0);
context.bindTexture(context.TEXTURE_2D, this.shadowTexture);
if (mapSize !== this.shadowMapSize) {
this.shadowMapSize = mapSize;
context.texImage2D(context.TEXTURE_2D, 0, context.DEPTH_COMPONENT24, mapSize, mapSize, 0, context.DEPTH_COMPONENT, context.UNSIGNED_INT, null);
this.renderTargets.record('shadowMap', { width: mapSize, height: mapSize, format: 'DEPTH_COMPONENT24' });
}
// Compare on fetch (the default function is LEQUAL) with linear filtering gives a 2 x 2 percentage-closer result from one fetch.
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_COMPARE_MODE, context.COMPARE_REF_TO_TEXTURE);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, context.CLAMP_TO_EDGE);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, context.CLAMP_TO_EDGE);
if (!this.shadowFramebuffer) this.shadowFramebuffer = context.createFramebuffer();
context.bindFramebuffer(context.FRAMEBUFFER, this.shadowFramebuffer);
context.framebufferTexture2D(context.FRAMEBUFFER, context.DEPTH_ATTACHMENT, context.TEXTURE_2D, this.shadowTexture, 0);
context.drawBuffers([context.NONE]);
context.readBuffer(context.NONE);
// The status is a round trip to the GPU process. The attachment only changes with the map size, so it is checked once per size,
// not on each of the several refreshes a second an animated world makes.
if (this.shadowFramebufferCheckedSize !== mapSize) {
if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) throw new Error('Shadow framebuffer is incomplete.');
this.shadowFramebufferCheckedSize = mapSize;
}
const light = resolveShadowLight(this.world, this.activeLightDirection, this.shadowBounds, this.fittedWorldShadowView());
const lightView = mat4.lookAt(mat4.create(), light.eye, light.target, light.up ?? [0, 1, 0]);
mat4.ortho(this.lightProjection, -light.extent, light.extent, -light.extent, light.extent, light.near, light.far);
mat4.multiply(this.lightProjection, this.lightProjection, lightView);
context.viewport(0, 0, mapSize, mapSize);
context.enable(context.DEPTH_TEST);
context.enable(context.CULL_FACE);
context.clear(context.DEPTH_BUFFER_BIT);
this.shadowBiasPerSlope = shadowBiasPerSlope(light, SHADOW_MAP_SIZE);
this.drawShadowCasters(this.lightProjection, mapSize, true);
this.drawTintedShadows();
context.bindFramebuffer(context.FRAMEBUFFER, null);
this.shadowsDirty = false;
}
/** True when the batch casts into the tint map instead of the depth map of the sun. */
tintsShadow(batch) {
return Boolean(this.tintedShadowsActive && batch.tintedShadow);
}
// The shadow program's opaqueShadow sampler is a comparison sampler, so while a depth map renders it needs a comparison-capable
// depth texture on its unit that is not the render target: a 2D map left there, or the sun map itself, fails the draw.
bindPlaceholderOpaqueShadow() {
const context = this.context;
context.activeTexture(context.TEXTURE0 + OPAQUE_SHADOW_UNIT);
if (!this.placeholderShadowTexture) {
this.placeholderShadowTexture = context.createTexture();
context.bindTexture(context.TEXTURE_2D, this.placeholderShadowTexture);
context.texImage2D(context.TEXTURE_2D, 0, context.DEPTH_COMPONENT24, 1, 1, 0, context.DEPTH_COMPONENT, context.UNSIGNED_INT, null);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.NEAREST);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.NEAREST);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_COMPARE_MODE, context.COMPARE_REF_TO_TEXTURE);
}
context.bindTexture(context.TEXTURE_2D, this.placeholderShadowTexture);
context.activeTexture(context.TEXTURE0);
}
allocateTintTarget() {
const context = this.context;
this.tintTexture = context.createTexture();
context.activeTexture(context.TEXTURE0 + TINT_UNIT);
context.bindTexture(context.TEXTURE_2D, this.tintTexture);
context.texImage2D(context.TEXTURE_2D, 0, context.RGBA16F, TINT_MAP_SIZE, TINT_MAP_SIZE, 0, context.RGBA, context.HALF_FLOAT, null);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, context.CLAMP_TO_EDGE);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, context.CLAMP_TO_EDGE);
this.renderTargets.record('tintShadow', { width: TINT_MAP_SIZE, height: TINT_MAP_SIZE, format: 'RGBA16F' });
this.tintFramebuffer = context.createFramebuffer();
context.bindFramebuffer(context.FRAMEBUFFER, this.tintFramebuffer);
context.framebufferTexture2D(context.FRAMEBUFFER, context.COLOR_ATTACHMENT0, context.TEXTURE_2D, this.tintTexture, 0);
context.drawBuffers([context.COLOR_ATTACHMENT0]);
if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) throw new Error('Tinted shadow framebuffer is incomplete.');
}
/**
* Draws the light that blended and transmissive casters let through, as seen from the sun, in one draw of those casters:
* the colour map starts white and each caster multiplies its transmittance into rgb while alpha keeps the nearest depth
* (blend equation MIN). Does nothing, and allocates nothing, when no caster of that kind exists.
*/
drawTintedShadows() {
const tinting = this.batches.filter(batch => !batch.floor && batch.castShadow && this.tintsShadow(batch));
if (tinting.length === 0) return;
const context = this.context;
if (!this.tintFramebuffer) this.allocateTintTarget();
context.bindFramebuffer(context.FRAMEBUFFER, this.tintFramebuffer);
context.viewport(0, 0, TINT_MAP_SIZE, TINT_MAP_SIZE);
context.activeTexture(context.TEXTURE0 + OPAQUE_SHADOW_UNIT);
context.bindTexture(context.TEXTURE_2D, this.shadowTexture);
context.activeTexture(context.TEXTURE0);
context.useProgram(this.depthProgram);
const uniforms = this.depthAlphaUniforms;
context.uniform1f(uniforms.tintMapSize, TINT_MAP_SIZE);
context.uniform1f(uniforms.tintBias, this.shadowBiasPerSlope * 2);
context.uniform1f(uniforms.tintPass, 1);
context.disable(context.DEPTH_TEST);
context.enable(context.BLEND);
context.blendEquationSeparate(context.FUNC_ADD, context.MIN);
context.blendFuncSeparate(context.DST_COLOR, context.ZERO, context.ONE, context.ONE);
context.clearColor(1, 1, 1, 1);
context.clear(context.COLOR_BUFFER_BIT);
context.enable(context.POLYGON_OFFSET_FILL);
context.polygonOffset(1, 1);
for (const batch of tinting) {
this.applyAlphaState(batch, false);
context.uniform1f(uniforms.tintTransmission, batch.layerState[9]);
this.drawBatch(batch, false, this.selectShadowInstances(batch, batch, this.lightProjection, TINT_MAP_SIZE), batch);
}
context.disable(context.POLYGON_OFFSET_FILL);
context.enable(context.CULL_FACE);
context.disable(context.BLEND);
context.blendEquation(context.FUNC_ADD);
context.enable(context.DEPTH_TEST);
context.uniform1f(uniforms.tintPass, 0);
}
bindTintedShadows() {
if (!this.tintedShadowsActive || !this.tintTexture) return;
const context = this.context;
context.activeTexture(context.TEXTURE0 + TINT_UNIT);
context.bindTexture(context.TEXTURE_2D, this.tintTexture);
context.uniform1i(this.uniforms.tintShadowMap, TINT_UNIT);
context.activeTexture(context.TEXTURE0);
}
/**
* The instances of a batch that can land in a shadow map, split by level. An instance outside the light's frustum
* writes nothing. With an orthographic light and a known map size, the level follows the world size of one texel,
* so a tree far smaller than a texel uses its coarsest level. Null when the whole batch draws as it is.
*/
selectShadowInstances(batch, levelSet, lightMatrix, resolution) {
if (!this.culling || !batch.cullable) return null;
const planes = extractFrustumPlanes(lightMatrix, this.shadowFrustumPlanes ??= new Float32Array(24));
const isOrthographic = lightMatrix[3] === 0 && lightMatrix[7] === 0 && lightMatrix[11] === 0 && lightMatrix[15] === 1;
const selectsLevels = Boolean(resolution) && isOrthographic && levelSet.levelErrors.length > 1;
// Texels per world unit along the map's x axis; an orthographic matrix has depth 1 everywhere.
const texelsPerUnit = selectsLevels ? Math.hypot(lightMatrix[0], lightMatrix[4], lightMatrix[8]) * resolution / 2 : 0;
return selectInstances(levelSet.selection, {
instanceData: batch.instanceData, instanceCount: batch.instanceCount, stride: INSTANCE_STRIDE, bounds: batch.bounds, margin: batch.swayReach * Math.abs(this.windState.strength),
levelErrors: selectsLevels ? levelSet.levelErrors : [0], planes, viewProjection: lightMatrix,
pixelsPerUnit: texelsPerUnit, pixelError: this.lodPixelError,
});
}
// `mainMap` is true for the sun's map, where blended and transmissive casters draw into the tint map instead. Elsewhere
// (cascades, point and spot tiles) they draw as opaque casters, except a blended part that did not ask to cast.
// A world scene that sets neither shadowBounds.target nor extent gets a sun view fitted to its casters (issue #1695).
// Skinned, morphed or crowd casters can leave any box, so they keep the fixed view.
fittedWorldShadowView() {
if (!this.world || this.shadowBounds?.target !== undefined || this.shadowBounds?.extent !== undefined) return null;
const casters = this.batches.filter(batch => !batch.floor && batch.castShadow).flatMap(batch => batch.parts);
if (casters.length === 0) return null;
return fitWorldShadowView(sceneBoundsOfParts(casters));
}
drawShadowCasters(lightMatrix = this.lightProjection, resolution = null, mainMap = false) {
const context = this.context;
context.useProgram(this.depthProgram);
context.uniformMatrix4fv(this.depthUniform, false, lightMatrix);
context.uniform1f(this.depthAssemblyUniform, this.assemblyAmount ?? 0);
context.uniform1f(this.depthWindUniforms.time, this.windState.time);
context.uniform1f(this.depthWindUniforms.wind, this.windState.strength);
// The base map sampler must not alias the shadow texture on unit 0 while that texture is the render target.
context.uniform1i(this.depthAlphaUniforms.baseMap, 1);
if (this.tintedShadowsActive) {
context.uniform1f(this.depthAlphaUniforms.tintPass, 0);
context.uniform1i(this.depthAlphaUniforms.opaqueShadow, OPAQUE_SHADOW_UNIT);
this.bindPlaceholderOpaqueShadow();
}
context.enable(context.POLYGON_OFFSET_FILL);
context.polygonOffset(1, 1);
for (const batch of this.batches) {
if (batch.floor || !batch.castShadow) continue;
if (batch.tintedShadow && (mainMap && this.tintedShadowsActive || batch.alphaMode === 'blend' && batch.parts[0].castShadow !== true)) continue;
const levelSet = batch.shadowLevels ?? batch;
const selection = this.selectShadowInstances(batch, levelSet, lightMatrix, resolution);
if (selection?.visibleCount === 0) continue;
this.applyAlphaState(batch, false);
this.drawBatch(batch, false, selection, levelSet);
}
context.disable(context.POLYGON_OFFSET_FILL);
context.enable(context.CULL_FACE);
}
// The atlas has one row of tiles per four shadow tiles in use. The shader fetches by texel, so the height is free.
allocateLocalShadowAtlas(tileCount) {
const context = this.context;
if (this.localShadowTexture) context.deleteTexture(this.localShadowTexture);
if (this.localShadowFramebuffer) context.deleteFramebuffer(this.localShadowFramebuffer);
this.localShadowAtlasHeight = Math.ceil(tileCount / SHADOW_TILES_PER_ROW) * SHADOW_TILE_SIZE;
this.localShadowTexture = context.createTexture();
context.activeTexture(context.TEXTURE0 + LOCAL_SHADOW_UNIT);
context.bindTexture(context.TEXTURE_2D, this.localShadowTexture);
context.texImage2D(context.TEXTURE_2D, 0, context.DEPTH_COMPONENT24, SHADOW_ATLAS_WIDTH, this.localShadowAtlasHeight, 0, context.DEPTH_COMPONENT, context.UNSIGNED_INT, null);
this.renderTargets.record('localShadowAtlas', { width: SHADOW_ATLAS_WIDTH, height: this.localShadowAtlasHeight, format: 'DEPTH_COMPONENT24' });
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.NEAREST);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.NEAREST);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, context.CLAMP_TO_EDGE);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, context.CLAMP_TO_EDGE);
this.localShadowFramebuffer = context.createFramebuffer();
context.bindFramebuffer(context.FRAMEBUFFER, this.localShadowFramebuffer);
context.framebufferTexture2D(context.FRAMEBUFFER, context.DEPTH_ATTACHMENT, context.TEXTURE_2D, this.localShadowTexture, 0);
context.drawBuffers([context.NONE]);
context.readBuffer(context.NONE);
if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) throw new Error('Local shadow framebuffer is incomplete.');
context.activeTexture(context.TEXTURE0);
}
// Builds the view of each atlas tile, and draws the atlas again only when a light moved or the casters changed.
updateLocalShadows(casterChanged) {
const casters = this.lighting.shadowCasters;
if (casters.length === 0 || this.benchmark) return;
const matrices = this.localShadowMatrices ??= new Float32Array(24 * 16);
const texelAngles = this.localShadowTexelAngles ??= new Float32Array(24);
const previous = this.localShadowPreviousMatrices ??= new Float32Array(24 * 16);
const tileMatrix = new Float32Array(16);
casters.forEach((caster, tile) => {
texelAngles[tile] = writeShadowTile(caster, tileMatrix);
matrices.set(tileMatrix, tile * 16);
});
const moved = casters.length !== this.localShadowTileCount || matrices.some((value, index) => value !== previous[index]);
if (!moved && !casterChanged && this.localShadowTexture) return;
previous.set(matrices);
this.localShadowTileCount = casters.length;
const context = this.context;
if (!this.localShadowTexture || Math.ceil(casters.length / SHADOW_TILES_PER_ROW) * SHADOW_TILE_SIZE > this.localShadowAtlasHeight) this.allocateLocalShadowAtlas(casters.length);
context.bindFramebuffer(context.FRAMEBUFFER, this.localShadowFramebuffer);
context.viewport(0, 0, SHADOW_ATLAS_WIDTH, this.localShadowAtlasHeight);
context.enable(context.DEPTH_TEST);
context.clear(context.DEPTH_BUFFER_BIT);
for (let tile = 0; tile < casters.length; tile++) {
context.viewport(...tileViewport(tile));
this.drawShadowCasters(matrices.subarray(tile * 16, tile * 16 + 16));
}
context.bindFramebuffer(context.FRAMEBUFFER, null);
}
/** Stores the wind time and strength the shadow pass must use; true when swaying batches need a new shadow map. */
updateWindState(frame) {
const next = { time: frame.time ?? 0, strength: frame.wind ?? 0.3 };
const previous = this.windState;
this.windState = next;
if (previous.time === next.time && previous.strength === next.strength) return false;
return this.batches.some(batch => batch.castShadow && SWAYING_TAGS.has(batch.parts[0].material.tag));
}
// Sets the clear colour behind the scene as [red, green, blue] or [red, green, blue, alpha] from 0 to 1; null restores the default.
setBackground(background) {
this.background = background ? resolveBackground(background) : null;
}
resize() {
// A lost context answers every parameter query with null, so there is no size limit to plan against. This class has no restore path: the caller disposes the renderer and builds a new one when the context comes back.
if (this.context.isContextLost()) return;
// A canvas that grew or shrank changes the triangles per pixel, so denseSamples is judged again; a new count needs new render targets.
const previousSamples = this.multisampleSamples;
if (this.denseSamples != null) {
this.multisampleSamples = this.chooseMultisampleSamples(this.densityParts);
this.capabilities.samples = this.multisampleSamples;
}
const plan = planRenderSize({ width: Math.max(1, this.canvas.clientWidth), height: Math.max(1, this.canvas.clientHeight), pixelRatio: this.pixelRatio, samples: this.samples, memoryBudgetMiB: this.memoryBudgetMiB, geometryBytes: this.geometryBytes, textureBytes: this.textureBytes, hdr: this.hdr, bloom: !this.benchmark, depth: this.depth, maximumSize: Math.min(this.context.getParameter(this.context.MAX_RENDERBUFFER_SIZE), this.context.getParameter(this.context.MAX_TEXTURE_SIZE)), maximumMemoryBudgetMiB: this.maximumMemoryBudgetMiB });
const { width, height } = plan;
this.memoryPlan = plan;
const sizeChanged = this.canvas.width !== width || this.canvas.height !== height;
if (sizeChanged || this.multisampleSamples !== previousSamples) {
this.canvas.width = width;
this.canvas.height = height;
if (!this.benchmark) this.allocateFrameTargets(width, height);
}
mat4.perspective(this.projection, this.world ? Math.PI / 4 : Math.PI / 5.5, width / height, 0.1, this.world ? 600 : 100);
}
/**
* Without reversed depth the 24-bit buffer needs a tight near plane: a camera that left near unset gets one just in front of the
* nearest scene bounds (near-plane-fit.js). A frame with its own near, an orthographic lens or a scene that can move out of its
* bounds keeps the frame as it is.
*/
withFittedNear(frame) {
if (this.reversedDepth || frame.near !== undefined || frame.projection === 'orthographic') return frame;
if (this.fitBounds === undefined) this.fitBounds = sceneBoundsOfParts(this.fitParts);
if (!this.fitBounds) return frame;
const far = frame.far ?? (this.world ? 600 : 100);
const near = fittedNearPlane(this.fitBounds, this.view, far);
return near === 0.1 ? frame : { ...frame, near };
}
/** Every GPU render target this renderer holds: name, size, format, samples and bytes, largest first, with the total. */
memoryReport() {
return this.renderTargets.report();
}
releaseFrameTargets() {
const context = this.context;
if (this.multisampleFramebuffer) this.backend.deleteFramebuffer(this.multisampleFramebuffer);
if (this.resolveFramebuffer) this.backend.deleteFramebuffer(this.resolveFramebuffer);
if (this.multisampleColor) this.backend.deleteRenderbuffer(this.multisampleColor);
if (this.multisampleDepth) this.backend.deleteRenderbuffer(this.multisampleDepth);
if (this.frameTexture) this.backend.deleteTexture(this.frameTexture);
if (this.depthTexture) this.backend.deleteTexture(this.depthTexture);
for (const target of this.bloomTargets ?? []) {
context.deleteTexture(target.texture);
context.deleteFramebuffer(target.framebuffer);
}
this.bloomTargets = [];
this.renderTargets.release('multisampleColor', 'multisampleDepth', 'frameColor', 'sceneDepth', 'bloomA', 'bloomB');
this.releaseOcclusionTarget();
this.passSupport?.releaseTargets(context);
for (const stage of this.postStages ?? []) stage.releaseTargets(context);
if (this.localVolumeComposite) requireFeatureCode('volumeFog').support.releaseLocalVolumeComposite(this, false);
this.multisampleFramebuffer = null;
this.resolveFramebuffer = null;
this.multisampleColor = null;
this.multisampleDepth = null;
this.frameTexture = null;
this.depthTexture = null;
}
releaseOcclusionTarget() {
if (!this.occlusionTarget) return;
this.context.deleteTexture(this.occlusionTarget.texture);
this.context.deleteFramebuffer(this.occlusionTarget.framebuffer);
this.renderTargets.release('ambientOcclusion');
this.occlusionTarget = null;
}
/** Whether a batch is drawn by the opaque loop, and so by render passes. Its parts take object IDs in this order. */
drawsInOpaqueLoop(batch) {
return batchPass(batch) === 'opaque' && !isTranslucentMode(batch.alphaMode);
}
// Compiled and allocated on first use, so scenes without occlusion pay nothing.
ensureOcclusionTarget() {
const context = this.context;
if (!this.occlusionProgram) {
this.occlusionProgram = compileProgram(context, fullscreenVertex, ambientOcclusionFragment);
const names = ['sceneDepth', 'inverseViewProjection', 'radius', 'projectionScale', 'aspect', 'orthographic'];
this.occlusionUniforms = Object.fromEntries(names.map(name => [name, context.getUniformLocation(this.occlusionProgram, name)]));
}
if (this.occlusionTarget) return;
const width = Math.max(1, Math.ceil(this.canvas.width / 2));
const height = Math.max(1, Math.ceil(this.canvas.height / 2));
const texture = context.createTexture();
context.bindTexture(context.TEXTURE_2D, texture);
context.texImage2D(context.TEXTURE_2D, 0, context.R8, width, height, 0, context.RED, context.UNSIGNED_BYTE, null);
this.renderTargets.record('ambientOcclusion', { width, height, format: 'R8' });
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, context.CLAMP_TO_EDGE);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, context.CLAMP_TO_EDGE);
const framebuffer = context.createFramebuffer();
context.bindFramebuffer(context.FRAMEBUFFER, framebuffer);
context.framebufferTexture2D(context.FRAMEBUFFER, context.COLOR_ATTACHMENT0, context.TEXTURE_2D, texture, 0);
this.occlusionTarget = { texture, framebuffer, width, height };
}
drawAmbientOcclusion(frame, effects) {
const context = this.context;
this.ensureOcclusionTarget();
const uniforms = this.occlusionUniforms;
context.bindFramebuffer(context.FRAMEBUFFER, this.occlusionTarget.framebuffer);
context.viewport(0, 0, this.occlusionTarget.width, this.occlusionTarget.height);
context.disable(context.DEPTH_TEST);
context.disable(context.CULL_FACE);
context.bindVertexArray(null);
context.useProgram(this.occlusionProgram);
context.activeTexture(context.TEXTURE1);
context.bindTexture(context.TEXTURE_2D, this.depthTexture);
context.uniform1i(uniforms.sceneDepth, 1);
context.uniformMatrix4fv(uniforms.inverseViewProjection, false, mat4.invert([], this.projection));
context.uniform1f(uniforms.radius, effects.ambientOcclusionRadius);
context.uniform1f(uniforms.projectionScale, 0.5 * this.projection[5]);
context.uniform1f(uniforms.aspect, this.canvas.width / this.canvas.height);
context.uniform1f(uniforms.orthographic, frame.projection === 'orthographic' ? 1 : 0);
context.drawArrays(context.TRIANGLES, 0, 3);
}
allocateFrameTargets(width, height) {
this.releaseFrameTargets();
// 24 bits at least (issue #751): 16 bits is one step per 1.5 cm at 10 m. Reversed depth respecifies this store as 32-bit float.
const depthFormat = 'DEPTH_COMPONENT24';
const multisample = this.backend.createMultisampleTarget({ width, height, samples: this.multisampleSamples, hdr: this.hdr });
this.multisampleFramebuffer = multisample.framebuffer;
this.multisampleColor = multisample.colorBuffer;
this.multisampleDepth = multisample.depthBuffer;
this.renderTargets.record('multisampleColor', { width, height, format: this.hdr ? 'RGBA16F' : 'RGBA8', samples: this.multisampleSamples });
this.renderTargets.record('multisampleDepth', { width, height, format: depthFormat, samples: this.multisampleSamples });
this.renderTargets.record('frameColor', { width, height, format: this.hdr ? 'RGBA16F' : 'RGBA8' });
const resolve = this.backend.createResolveTarget({ width, height, hdr: this.hdr, depth: this.depth });
this.resolveFramebuffer = resolve.framebuffer;
this.frameTexture = resolve.colorTexture;
this.depthTexture = resolve.depthTexture;
if (this.depth) this.renderTargets.record('sceneDepth', { width, height, format: depthFormat });
this.bloomWidth = Math.max(1, Math.ceil(width / 2));
this.bloomHeight = Math.max(1, Math.ceil(height / 2));
this.backend.bindCanvasTarget();
this.chooseColorFormat(width, height);
}
// An opaque canvas never reads the frame's alpha, so the frame and multisample colour take 4 bytes a pixel instead of 8 (#2179).
// A device that refuses the compact framebuffers gets the RGBA16F targets back.
chooseColorFormat(width, height) {
this.colorFormat = this.hdr ? 'RGBA16F' : 'RGBA8';
if (!canUseCompactColor(this)) return;
try {
respecifyColorTargets(this, width, height);
} catch {
this.compactColor = false;
this.allocateFrameTargets(width, height);
}
}
// The prefilter and BRDF programs build while the other programs do, instead of after them.
startEnvironmentPrograms() {
this.pendingEnvironmentPrograms = new Map();
for (const fragmentSource of [requireEnvironmentSupport().prefilterFragment, requireEnvironmentSupport().brdfFragment]) {
this.pendingEnvironmentPrograms.set(fragmentSource, this.backend.startProgram(fullscreenVertex, fragmentSource));
}
}
compileEnvironmentProgram(context, vertexSource, fragmentSource) {
const pendingProgram = this.pendingEnvironmentPrograms?.get(fragmentSource);
if (!pendingProgram) return compileProgram(context, vertexSource, fragmentSource);
this.pendingEnvironmentPrograms.delete(fragmentSource);
return this.backend.finishProgram(pendingProgram);
}
initializeEnvironment(map) {
const context = this.context;
context.useProgram(this.program);
context.uniform1i(this.uniforms.environmentSpecular, ENVIRONMENT_SPECULAR_UNIT);
context.uniform1i(this.uniforms.environmentBrdf, ENVIRONMENT_BRDF_UNIT);
if (this.liquidProgram) {
context.useProgram(this.liquidProgram);
context.uniform1i(this.liquidUniforms.environmentSpecular, ENVIRONMENT_SPECULAR_UNIT);
}
this.bindEnvironmentTextures(this.whiteTexture, this.whiteTexture);
if (!this.benchmark && map && !this.deferEnvironmentPrefilter) this.prepareEnvironment(map);
}
bindEnvironmentTextures(specularTexture, brdfTexture) {
const context = this.context;
context.activeTexture(context.TEXTURE0 + ENVIRONMENT_SPECULAR_UNIT);
context.bindTexture(context.TEXTURE_2D, specularTexture);
context.activeTexture(context.TEXTURE0 + ENVIRONMENT_BRDF_UNIT);
context.bindTexture(context.TEXTURE_2D, brdfTexture);
}
// Prefilters a map the first time it is seen; maps spread from one created map share its data and reuse the GPU textures (an `irradianceSource` map, which only the diffuse light reads, counts as part of the map). Returns true when new textures were built.
prepareEnvironment(map) {
requireEnvironmentSupport().assertMap(map);
if (this.environmentResources?.data === map.data && this.environmentResources.irradianceSource === map.irradianceSource) return false;
requireEnvironmentSupport().estimateBytes(map, this.capabilities.maximumTextureSize);
const resources = requireEnvironmentSupport().createResources(this.context, map, { compileProgram: (context, vertexSource, fragmentSource) => this.compileEnvironmentProgram(context, vertexSource, fragmentSource), fullscreenVertex });
this.environmentResources?.dispose();
this.environmentResources = resources;
this.textureBytes += resources.bytes - this.environmentBytes;
this.environmentBytes = resources.bytes;
return true;
}
/**
* Prefilters the map in steps, awaiting `checkpoint()` between them, for a renderer built with `deferEnvironmentPrefilter: true`.
* Call it before the first render: the steps leave GL state mid-pass, so no frame may draw on this context until it resolves.
*/
async prepareEnvironmentInSlices(map, checkpoint) {
requireEnvironmentSupport().assertMap(map);
if (this.environmentResources?.data === map.data && this.environmentResources.irradianceSource === map.irradianceSource) return false;
requireEnvironmentSupport().estimateBytes(map, this.capabilities.maximumTextureSize);
const resources = await requireEnvironmentSupport().createResourcesInSlices(this.context, map, { compileProgram: (context, vertexSource, fragmentSource) => this.compileEnvironmentProgram(context, vertexSource, fragmentSource), fullscreenVertex }, checkpoint);
this.environmentResources?.dispose();
this.environmentResources = resources;
this.textureBytes += resources.bytes - this.environmentBytes;
this.environmentBytes = resources.bytes;
return true;
}
// Binds the prefiltered textures for this frame and returns the active map, or null for the built-in studio lighting.
activateEnvironment(map) {
this.activeMap = this.benchmark ? null : map;
if (this.benchmark || !map) {
this.bindEnvironmentTextures(this.whiteTexture, this.whiteTexture);
return null;
}
if (this.prepareEnvironment(map)) this.resize();
this.bindEnvironmentTextures(this.environmentResources.specularTexture, this.environmentResources.brdfTexture);
return map;
}
applyEnvironmentUniforms(map, uniforms = this.uniforms) {
const context = this.context;
context.uniform1f(uniforms.environmentEnabled, map ? 1 : 0);
if (!map) return;
this.applyDiffuseUniforms(map, uniforms, true);
context.uniform1f(uniforms.environmentIntensity, map.intensity);
context.uniform2f(uniforms.environmentRotation, Math.cos(map.rotation), Math.sin(map.rotation));
context.uniform1f(uniforms.environmentLevelMax, this.environmentResources.levelCount - 1);
}
// The diffuse light of the global map: the fitted coefficients (kept for the light shading preset), the map's rotation and intensity, and the
// constant bounce a room adds on top of the exact irradiance grid. A reflection probe passes withBounce false, as it never bounced.
applyDiffuseUniforms(map, uniforms, withBounce) {
const context = this.context;
const coefficients = this.environmentResources.irradiance;
const bounced = withBounce ? map.irradianceWithBounce?.(coefficients) : null;
if (uniforms['environmentIrradiance[0]']) context.uniform3fv(uniforms['environmentIrradiance[0]'], bounced ?? coefficients);
if (uniforms.environmentBounce) context.uniform3f(uniforms.environmentBounce, bounced ? bounced[0] - coefficients[0] : 0, bounced ? bounced[1] - coefficients[1] : 0, bounced ? bounced[2] - coefficients[2] : 0);
if (uniforms.environmentDiffuseFrame) context.uniform3f(uniforms.environmentDiffuseFrame, Math.cos(map.rotation), Math.sin(map.rotation), map.intensity);
}
drawEnvironmentBackground(map, frame, exposure) {
if (!map?.showBackground || this.transparent) return false;
const context = this.context;
if (!this.environmentBackgroundProgram) {
this.environmentBackgroundProgram = compileProgram(context, fullscreenVertex, this.withViewTransform(requireEnvironmentSupport().backgroundFragment, 'background'));
const names = ['inverseViewProjection', 'eye', 'backgroundLevel', 'exposure', 'hdrEnabled', 'environmentSpecular', 'environmentRotation', 'environmentIntensity', 'environmentLevelMax', 'sunMapDirection', 'sunDiscRadiance', 'sunDiscRadius'];
this.environmentBackgroundUniforms = Object.fromEntries(names.map(name => [name, context.getUniformLocation(this.environmentBackgroundProgram, name)]));
}
const uniforms = this.environmentBackgroundUniforms;
const levelMax = this.environmentResources.levelCount - 1;
context.disable(context.DEPTH_TEST);
context.disable(context.CULL_FACE);
context.bindVertexArray(null);
context.useProgram(this.environmentBackgroundProgram);
context.uniformMatrix4fv(uniforms.inverseViewProjection, false, this.inverseViewProjection);
context.uniform3fv(uniforms.eye, frame.eye);
context.uniform1f(uniforms.backgroundLevel, map.backgroundBlur * levelMax);
context.uniform1f(uniforms.exposure, exposure);
context.uniform1f(uniforms.hdrEnabled, this.hdr ? 1 : 0);
context.uniform1i(uniforms.environmentSpecular, ENVIRONMENT_SPECULAR_UNIT);
context.uniform2f(uniforms.environmentRotation, Math.cos(map.rotation), Math.sin(map.rotation));
context.uniform1f(uniforms.environmentIntensity, map.intensity);
context.uniform1f(uniforms.environmentLevelMax, levelMax);
const sunDisc = map.sunDisc;
context.uniform3fv(uniforms.sunMapDirection, sunDisc?.direction ?? [0, -1, 0]);
context.uniform3fv(uniforms.sunDiscRadiance, sunDisc?.radiance ?? [0, 0, 0]);
context.uniform1f(uniforms.sunDiscRadius, frame.environment?.sunAngularRadius ?? this.environment?.sunAngularRadius ?? DEFAULT_SUN_ANGULAR_RADIUS);
context.drawArrays(context.TRIANGLES, 0, 3);
return true;
}
drawSky(frame) {
const context = this.context;
const environment = { skyTop: [0.20, 0.38, 0.52], skyBottom: [0.62, 0.70, 0.67], lightDirection: [-3, 6, 4], daylight: 1, ...this.environment, ...frame.environment };
context.disable(context.DEPTH_TEST);
context.disable(context.CULL_FACE);
context.bindVertexArray(null);
context.useProgram(this.skyProgram);
context.uniform3fv(this.skyUniforms.skyTop, environment.skyTop);
context.uniform3fv(this.skyUniforms.skyBottom, environment.skyBottom);
context.uniform3fv(this.skyUniforms.sunDirection, environment.lightDirection);
context.uniformMatrix4fv(this.skyUniforms.inverseViewProjection, false, this.inverseViewProjection);
context.uniform3fv(this.skyUniforms.eye, frame.eye);
context.uniform1f(this.skyUniforms.time, frame.time ?? 0);
context.uniform1f(this.skyUniforms.daylight, environment.daylight);
context.uniform1f(this.skyUniforms.hdrEnabled, this.hdr ? 1 : 0);
context.drawArrays(context.TRIANGLES, 0, 3);
}
// True when the frame draws local volumes. An empty list costs nothing; anything else is checked here, before a program is bound.
prepareLocalVolumes(input, frame, volumeTime, volumeShutter = 0) {
if (input === undefined || (Array.isArray(input) && input.length === 0)) return false;
return requireFeatureCode('volumeFog').support.prepareLocalVolumes(this, input, frame, volumeTime, volumeShutter) > 0;
}
// The post steps this frame uses. A step that is off costs nothing in a program that has it compiled out.
postStepsOf(frame, effects, volume, occluded, fogSky, localVolumes) {
const steps = [];
if (this.transparent) steps.push('transparent');
if (occluded) steps.push('occlusion');
if (isBloomActive(effects)) steps.push('bloom');
if (volume.density > 0) steps.push('volume');
if (volume.density > 0 && volume.field) steps.push('field');
if (volume.density > 0 && requireFeatureCode('volumeFog').support.usesDetail(volume)) steps.push('detail');
if (volume.density > 0 && this.fogLightBuffers?.count > 0) steps.push('lights');
if (localVolumes) steps.push('local');
if (localVolumes && this.localVolumeBuffers.gridShutter > 0) steps.push(GRID_MOTION_STEP);
if (localVolumes) steps.push(...localVolumeKindSteps(this.localVolumeBuffers.kind));
if (localVolumes && this.localVolumeBuffers.noiseOctaves) steps.push(NOISE_OCTAVES_STEP);
if (fogSky) steps.push('sky');
if (frame.volumeExplosion) steps.push('explosion');
if (frame.linearOutput) steps.push(requireFeatureCode('linearOutput').step(this, frame));
const gradesColor = effects.saturation !== 1 || effects.contrast !== 1 || effects.temperature !== 0;
const finishes = gradesColor || (frame.monochrome ?? 0) !== 0 || Boolean(frame.cinematic) || effects.vignette !== 0 || effects.grain !== 0;
if (finishes) steps.push('finish');
return steps;
}
// Compiles a program for the steps of this frame the first time they occur. The program with every step stays in use
// until the driver has finished building the new one, so a step that appears later does not stall a frame.
selectPostProgram(steps) {
if (steps.join() === POST_STEPS.join()) return { program: this.postProgram, uniforms: this.postUniforms };
const key = steps.join(',');
let variant = this.postVariants.get(key);
if (!variant) {
variant = { pending: this.backend.startProgram(fullscreenVertex, this.withViewTransform(createPostFragment(steps), 'post')) };
this.postVariants.set(key, variant);
}
if (variant.pending) {
const parallelCompile = this.context.getExtension('KHR_parallel_shader_compile');
const building = !this.exactFrames && parallelCompile && !POST_STEPS_WITH_OPTIONAL_CODE.some(step => steps.includes(step)) && !this.context.getProgramParameter(variant.pending.program, parallelCompile.COMPLETION_STATUS_KHR);
if (building) return { program: this.postProgram, uniforms: this.postUniforms };
variant.program = this.backend.finishProgram(variant.pending);
variant.uniforms = postUniformLocations(this.context, variant.program);
variant.pending = null;
}
return variant;
}
// The fog step leaves the last frame's texture on a mipmapped filter. The stages and bloom read before this frame's
// mip chain exists, so on that filter they would sample the previous frame's blurred levels: a ghost after a seek.
restoreSingleLevelFiltering() {
if (!this.mipmappedTexture) return;
const context = this.context;
context.bindTexture(context.TEXTURE_2D, this.mipmappedTexture);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR);
this.mipmappedTexture = null;
}
resolveFrame(frame, effects, environment, volume) {
const context = this.context;
this.backend.resolveMultisample({ source: this.multisampleFramebuffer, destination: this.resolveFramebuffer, width: this.canvas.width, height: this.canvas.height, depth: this.depth });
this.restoreSingleLevelFiltering();
let sourceTexture = this.frameTexture;
for (const stage of this.postStages) sourceTexture = stage.apply(this, frame, effects, sourceTexture) ?? sourceTexture;
// A grid with velocity blurs over the shutter of the scene's motion blur, or over environment.volumeShutter when the caller sets one (#1759).
const localVolumes = this.prepareLocalVolumes(environment.localVolumes, frame, environment.volumeTime ?? frame.time ?? 0, environment.volumeShutter ?? effects.motionBlur.shutter);
// A glowing volume is drawn before bloom extraction so it blooms; the final pass then skips its local step.
const compositedLocalVolumes = localVolumes && isBloomActive(effects) && this.localVolumeBuffers.emissive;
if (compositedLocalVolumes) sourceTexture = requireFeatureCode('volumeFog').support.compositeLocalVolumes(this, frame, environment, sourceTexture);
if (isBloomActive(effects)) this.drawBloom(effects.bloom, sourceTexture);
const occluded = effects.ambientOcclusion > 0 && Boolean(this.depthTexture);
if (occluded) this.drawAmbientOcclusion(frame, effects);
// A frame that names an outputFramebuffer (src/float-output.js) draws its final pass there, not on the canvas.
context.bindFramebuffer(context.FRAMEBUFFER, frame.outputFramebuffer ?? null);
context.viewport(0, 0, this.canvas.width, this.canvas.height);
context.disable(context.DEPTH_TEST);
context.disable(context.CULL_FACE);
context.bindVertexArray(null);
const fogSky = this.fogSkyVisibility?.(this.sceneParts, volume, context, environment);
const fogSupport = volume.density > 0 ? requireFeatureCode('volumeFog').support : null;
if (fogSupport) fogSupport.packLights(this);
else if (this.fogLightBuffers) this.fogLightBuffers.count = 0;
const post = this.selectPostProgram(this.postStepsOf(frame, effects, volume, occluded, fogSky, localVolumes && !compositedLocalVolumes));
context.useProgram(post.program);
if (this.look) viewTransformShader.bindLook(this, post.program);
context.activeTexture(context.TEXTURE0);
context.bindTexture(context.TEXTURE_2D, sourceTexture);
// The fog's glow reads blurred copies of the frame from its mip chain, so a tap is smooth instead of one speckled pixel.
if (volume.density > 0 || (localVolumes && !compositedLocalVolumes && this.localVolumeBuffers.blurred)) {
context.generateMipmap(context.TEXTURE_2D);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR_MIPMAP_LINEAR);
this.mipmappedTexture = sourceTexture;
} else if (this.mipmappedTexture === sourceTexture) {
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR);
this.mipmappedTexture = null;
}
context.uniform1i(post.uniforms.frameTexture, 0);
context.activeTexture(context.TEXTURE1);
context.bindTexture(context.TEXTURE_2D, this.depthTexture ?? this.whiteTexture);
context.uniform1i(post.uniforms.sceneDepth, 1);
fogSupport?.bindUniforms(this, post, volume, environment, frame);
if (localVolumes && !compositedLocalVolumes) requireFeatureCode('volumeFog').support.bindLocalVolumes(this, post, frame, environment);
context.activeTexture(context.TEXTURE2);
context.bindTexture(context.TEXTURE_2D, isBloomActive(effects) ? this.bloomTargets[1].texture : this.whiteTexture);
context.uniform1i(post.uniforms.bloomTexture, 2);
context.uniform1f(post.uniforms.bloomStrength, isBloomActive(effects) ? effects.bloom.strength : 0);
context.activeTexture(context.TEXTURE4);
context.bindTexture(context.TEXTURE_2D, occluded ? this.occlusionTarget.texture : this.whiteTexture);
context.uniform1i(post.uniforms.occlusionTexture, 4);
context.uniform1f(post.uniforms.occlusionStrength, occluded ? effects.ambientOcclusion : 0);
context.uniform2f(post.uniforms.occlusionTexel, 1 / Math.ceil(this.canvas.width / 2), 1 / Math.ceil(this.canvas.height / 2));
context.uniform1f(post.uniforms.transparent, this.transparent ? 1 : 0);
context.uniform1f(post.uniforms.hdrEnabled, this.hdr ? 1 : 0);
context.uniform3f(post.uniforms.grade, effects.saturation, effects.contrast, effects.temperature);
context.uniform1f(post.uniforms.vignette, effects.vignette);
context.uniform1f(post.uniforms.grainAmount, effects.grain);
context.uniform2f(post.uniforms.resolution, this.canvas.width, this.canvas.height);
context.uniform1f(post.uniforms.monochrome, frame.monochrome ?? 0);
context.uniform1f(post.uniforms.fade, frame.fade ?? 0);
context.uniform1f(post.uniforms.cinematic, frame.cinematic ? 1 : 0);
context.uniform1f(post.uniforms.time, frame.time ?? 0);
context.uniform1f(post.uniforms.volumeExplosion, frame.volumeExplosion ? 1 : 0);
context.uniform1f(post.uniforms.explosionProgress, frame.explosionProgress ?? 1);
context.uniformMatrix4fv(post.uniforms.inverseViewProjection, false, this.inverseViewProjection);
context.uniform3fv(post.uniforms.eye, frame.eye);
context.drawArrays(context.TRIANGLES, 0, 3);
}
drawTranslucent(frame, environment, assemblyAmount, environmentMap) {
this.activateEnvironment(environmentMap);
const liquids = this.batches.filter(batch => batchPass(batch) === 'liquid');
const foams = this.batches.filter(batch => batchPass(batch) === 'foam');
if (liquids.length === 0 && foams.length === 0) return;
liquidPassDrawer()(this, { frame, environment, assemblyAmount, environmentMap, liquids, foams, environmentSpecularUnit: ENVIRONMENT_SPECULAR_UNIT, maximumDistance: MAX_FINITE_DISTANCE, vertexSource: vertexShader, fragmentSource: liquidFragmentSource() });
}
// Allocated on the first frame that asks for bloom, so scenes without it pay nothing.
ensureBloomTargets() {
if (this.bloomTargets.length > 0) return;
const context = this.context;
for (let index = 0; index < 2; index++) {
const texture = context.createTexture();
const framebuffer = context.createFramebuffer();
this.bloomTargets.push({ texture, framebuffer });
context.bindTexture(context.TEXTURE_2D, texture);
context.texImage2D(context.TEXTURE_2D, 0, this.hdr ? context.RGBA16F : context.RGBA8, this.bloomWidth, this.bloomHeight, 0, context.RGBA, this.hdr ? context.HALF_FLOAT : context.UNSIGNED_BYTE, null);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MIN_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_MAG_FILTER, context.LINEAR);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_S, context.CLAMP_TO_EDGE);
context.texParameteri(context.TEXTURE_2D, context.TEXTURE_WRAP_T, context.CLAMP_TO_EDGE);
context.bindFramebuffer(context.FRAMEBUFFER, framebuffer);
context.framebufferTexture2D(context.FRAMEBUFFER, context.COLOR_ATTACHMENT0, context.TEXTURE_2D, texture, 0);
if (context.checkFramebufferStatus(context.FRAMEBUFFER) !== context.FRAMEBUFFER_COMPLETE) throw new Error('Bloom framebuffer allocation failed. Choose a lower quality preset.');
}
context.bindFramebuffer(context.FRAMEBUFFER, null);
this.renderTargets.record('bloomA', { width: this.bloomWidth, height: this.bloomHeight, format: this.hdr ? 'RGBA16F' : 'RGBA8' });
this.renderTargets.record('bloomB', { width: this.bloomWidth, height: this.bloomHeight, format: this.hdr ? 'RGBA16F' : 'RGBA8' });
}
drawBloom(bloom, sourceTexture = this.frameTexture) {
const context = this.context;
this.ensureBloomTargets();
context.disable(context.DEPTH_TEST);
context.disable(context.CULL_FACE);
context.bindVertexArray(null);
context.useProgram(this.bloomProgram);
context.viewport(0, 0, this.bloomWidth, this.bloomHeight);
context.uniform1i(this.bloomUniforms.sourceTexture, 0);
context.uniform1f(this.bloomUniforms.threshold, bloom.threshold);
for (let pass = 0; pass < 2; pass++) {
context.bindFramebuffer(context.FRAMEBUFFER, this.bloomTargets[pass].framebuffer);
context.activeTexture(context.TEXTURE0);
context.bindTexture(context.TEXTURE_2D, pass === 0 ? sourceTexture : this.bloomTargets[0].texture);
context.uniform1f(this.bloomUniforms.extract, pass === 0 ? 1 : 0);
context.uniform2f(this.bloomUniforms.texelDirection, pass === 0 ? bloom.radius / this.bloomWidth : 0, pass === 1 ? bloom.radius / this.bloomHeight : 0);
context.drawArrays(context.TRIANGLES, 0, 3);
}
}
/** Culling, cutout and opacity state for one batch, in the color pass (textured) or the shadow depth pass. */
applyAlphaState(batch, textured) {
const context = this.context;
// The shadow depth pass (not textured) draws both faces. A single-sided terrain edge, leaf card or open shell seen from
// behind would otherwise write no depth, and the sun would pass through it.
if (batch.doubleSided || !textured) {
context.disable(context.CULL_FACE);
} else {
context.enable(context.CULL_FACE);
}
const masked = batch.alphaMode === 'mask';
if (!textured) {
const uniforms = this.depthAlphaUniforms;
context.uniform1f(uniforms.alphaMasked, masked ? 1 : 0);
context.uniform1f(uniforms.alphaCutoff, batch.alphaCutoff);
context.uniform1f(uniforms.materialOpacity, batch.opacity);
context.uniform1f(uniforms.hasBaseMap, batch.mapState[0] ? 1 + (batch.mapState[0].uvChannel ?? 0) : 0);
layerTextureSupport.bindDepth?.(this, batch);
if (masked || batch.tintedShadow) {
context.activeTexture(context.TEXTURE0 + 1);
context.bindTexture(context.TEXTURE_2D, batch.textures[0]);
}
return;
}
this.applyDepthRank((batch.depthLayer ?? 0) * RANKS_PER_LAYER);
const useCoverage = masked && this.samples > 1 && !this.benchmark && !this.renderingPass;
if (useCoverage) {
context.enable(context.SAMPLE_ALPHA_TO_COVERAGE);
} else {
context.disable(context.SAMPLE_ALPHA_TO_COVERAGE);
}
const uniforms = this.uniforms;
context.uniform1f(uniforms.alphaMode, ALPHA_MODES[batch.alphaMode]);
context.uniform1f(uniforms.alphaCutoff, batch.alphaCutoff);
context.uniform1f(uniforms.materialOpacity, batch.opacity);
context.uniform1f(uniforms.alphaToCoverage, useCoverage ? 1 : 0);
context.uniform1f(uniforms.doubleSided, batch.doubleSided ? 1 : 0);
}
/**
* Pulls what draws next `rank` steps toward the eye, in depth only, for the colour pass; rank 0 is the plain depth test.
* A step is a view-space distance (FLUSH_STEP metres plus FLUSH_RELATIVE_STEP of the depth), so it separates two faces the
* same way on every depth format, plus a slope-only polygon offset for the depth the rasteriser's snapping adds on a
* grazing face. `towardEye` is the sign of nearer depth values: -1 for standard depth, 1 for reversed depth.
*/
applyDepthRank(rank, towardEye = -1) {
const context = this.context;
context.uniform3f(this.uniforms.flushBias, rank * FLUSH_STEP, rank * FLUSH_RELATIVE_STEP, towardEye < 0 && rank ? -rank * FLUSH_CLIP_STEP : 0);
if (rank) {
context.enable(context.POLYGON_OFFSET_FILL);
context.polygonOffset(towardEye * rank * FLUSH_SLOPE_STEP, 0);
} else {
context.disable(context.POLYGON_OFFSET_FILL);
}
}
/** Tells the main program how clip space moves per metre along the view direction, for the depth ranks. */
setFlushProjection(viewProjection) {
const view = this.view;
const forward = [-view[2], -view[6], -view[10]];
for (let row = 0; row < 4; row++) {
clipPerMetreScratch[row] = viewProjection[row] * forward[0] + viewProjection[4 + row] * forward[1] + viewProjection[8 + row] * forward[2];
}
this.context.uniform4fv(this.uniforms.clipPerMetre, clipPerMetreScratch);
}
/** Reorders a blend batch's instances back to front for this eye; translation columns stand in for object centers. */
uploadSortedInstances(batch, eye) {
if (batch.instanceCount < 2) return;
const data = batch.instanceData;
const distances = Array.from({ length: batch.instanceCount }, (unused, index) => {
const offset = index * INSTANCE_STRIDE;
return { index, distance: Math.hypot(data[offset + 12] - eye[0], data[offset + 13] - eye[1], data[offset + 14] - eye[2]) };
});
distances.sort((first, second) => second.distance - first.distance);
batch.sortedData ??= new Float32Array(data.length);
distances.forEach(({ index }, rank) => {
batch.sortedData.set(data.subarray(index * INSTANCE_STRIDE, (index + 1) * INSTANCE_STRIDE), rank * INSTANCE_STRIDE);
});
this.context.bindBuffer(this.context.ARRAY_BUFFER, batch.instanceBuffer);
this.context.bufferSubData(this.context.ARRAY_BUFFER, 0, batch.sortedData);
}
/** Whether any instance of a blend batch is fully opaque, and so has opaque texels to draw as a cutout first. */
hasOpaqueInstance(batch) {
for (let index = 0; index < batch.instanceCount; index++) {
if (batch.instanceData[index * INSTANCE_STRIDE + OPACITY_OFFSET] >= 0.999) return true;
}
return false;
}
/** Alpha-blended batches draw after opaque and masked geometry, farthest first, without writing depth. Additive batches draw last. */
drawBlendBatches(frame) {
const context = this.context;
const eye = frame.eye;
const blendBatches = this.batches.filter(batch => batch.alphaMode === 'blend' && batchPass(batch) === 'opaque');
// Light adds in any order, so additive batches need no sort.
const addBatches = this.batches.filter(batch => batch.alphaMode === 'add' && batchPass(batch) === 'opaque');
if (blendBatches.length === 0 && addBatches.length === 0) return;
// The liquid and foam pass may have switched program, texture unit 0 and the viewport.
context.bindFramebuffer(context.FRAMEBUFFER, this.multisampleFramebuffer);
context.viewport(0, 0, this.canvas.width, this.canvas.height);
context.enable(context.DEPTH_TEST);
context.useProgram(this.program);
context.activeTexture(context.TEXTURE0);
context.bindTexture(context.TEXTURE_2D, this.shadowTexture);
context.uniform1i(this.uniforms.shadowMap, 0);
const distance = (batch) => {
let total = 0;
for (let index = 0; index < batch.instanceCount; index++) {
const offset = index * INSTANCE_STRIDE;
total += Math.hypot(batch.instanceData[offset + 12] - eye[0], batch.instanceData[offset + 13] - eye[1], batch.instanceData[offset + 14] - eye[2]);
}
return total / batch.instanceCount;
};
const ordered = blendBatches.map(batch => ({ batch, distance: distance(batch) })).sort((first, second) => second.distance - first.distance);
// Fully opaque texels (most of a baked scene exported as BLEND) draw first as a cutout that writes depth, so they hide
// whatever lies behind them in any draw order. The blend pass below then shades only the translucent texels (depth LESS).
for (const { batch } of ordered) {
if (this.hasOpaqueInstance(batch)) this.drawAlphaBatch({ ...batch, alphaMode: 'mask', alphaCutoff: 0.999 }, true);
}
context.enable(context.BLEND);
// The program writes a blended part premultiplied, so its specular is not faded by alpha (blend-output.js).
context.blendFuncSeparate(context[BLEND_FACTORS.sourceColor], context[BLEND_FACTORS.destinationColor], context[BLEND_FACTORS.sourceAlpha], context[BLEND_FACTORS.destinationAlpha]);
context.depthMask(false);
for (const { batch } of ordered) {
this.uploadSortedInstances(batch, eye);
this.drawAlphaBatch(batch, true);
}
if (addBatches.length > 0) {
// Source colour times opacity is added to the frame; the destination alpha is kept.
context.blendFuncSeparate(context.SRC_ALPHA, context.ONE, context.ZERO, context.ONE);
for (const batch of addBatches) this.drawAlphaBatch(batch, true);
}
context.depthMask(true);
this.applyDepthRank(0);
context.disable(context.BLEND);
context.disable(context.SAMPLE_ALPHA_TO_COVERAGE);
context.enable(context.CULL_FACE);
context.bindVertexArray(null);
}
drawAlphaBatch(batch, textured, culled = false) {
const selection = culled ? this.selectBatchInstances(batch) : null;
if (selection?.visibleCount === 0) return;
this.applyAlphaState(batch, textured);
this.drawBatch(batch, textured, selection);
}
// When every batch holds one instance, its flat values (colour, surface, emission, box normal matrix) are uniforms, not varyings.
setSingleInstanceUniforms(data) {
const context = this.context;
context.uniform3f(this.uniforms.baseColor, data[25], data[26], data[27]);
context.uniform4f(this.uniforms.surface, data[28], data[29], data[30], data[31]);
context.uniform4f(this.uniforms.instanceEmission, data[38], data[39], data[40], 0);
context.uniform1f(this.uniforms.instanceOpacity, data[OPACITY_OFFSET]);
if (this.shaderFeatures.has('boxMapScale')) context.uniformMatrix3fv(this.uniforms.boxNormalMatrix, false, data.subarray(16, 25));
}
drawBatch(batch, textured = false, selection = null, levelSet = batch) {
if (this.hasMorphs) {
const uniforms = textured ? this.uniforms : this.depthMorphUniforms;
this.context.uniform1f(uniforms.morphEnabled, batch.morph ? 1 : 0);
if (batch.morph) {
this.context.uniform1i(uniforms.morphVertexCount, batch.morphTexture.info.vertexCount);
const targetCount = batch.morphWeights.length;
const selected = targetCount > MORPH_SLOT_COUNT;
const slotCount = selected ? morphSupport().selectMorphSlots(batch.morphWeights, MORPH_SLOT_TARGETS, MORPH_SLOT_WEIGHTS) : targetCount;
this.context.uniform1i(uniforms.morphTargetCount, slotCount);
this.context.uniform1fv(uniforms['morphWeights[0]'], selected ? MORPH_SLOT_WEIGHTS : batch.morphWeights);
this.context.uniform1fv(uniforms['morphSlotTargets[0]'], selected ? MORPH_SLOT_TARGETS : IDENTITY_MORPH_SLOTS);
this.context.activeTexture(this.context.TEXTURE0 + 8);
this.context.bindTexture(this.context.TEXTURE_2D, batch.morphTexture.texture);
}
}
if (this.hasSkins) {
const uniforms = textured ? this.uniforms : this.depthSkinUniforms;
this.context.uniform1f(uniforms.crowdEnabled, batch.crowd ? 1 : 0);
this.context.uniform1f(uniforms.skinEnabled, batch.skin ? 1 : 0);
if (batch.crowd) {
this.context.activeTexture(this.context.TEXTURE0 + 7);
this.context.bindTexture(this.context.TEXTURE_2D, batch.crowdTexture.texture);
this.context.uniform1i(uniforms.jointPalette, 7);
} else if (batch.skin) {
this.context.activeTexture(this.context.TEXTURE0 + 6);
this.context.bindTexture(this.context.TEXTURE_2D, batch.influenceTexture.texture);
this.context.uniform1i(uniforms.skinInfluences, 6);
this.context.activeTexture(this.context.TEXTURE0 + 7);
this.context.bindTexture(this.context.TEXTURE_2D, batch.skinTexture.texture);
this.context.uniform1i(uniforms.jointPalette, 7);
}
}
if (textured && !this.benchmark) {
this.context.uniform1f(this.uniforms.shadowBlind, batch.receivesShadow === false ? 1 : 0);
this.context.uniform1f(this.uniforms.tintBlind, batch.tintBlind ? 1 : 0);
this.context.uniform1f(this.uniforms.compositeMode, batch.compositeMode ?? 0);
for (let index = 0; index < MATERIAL_MAPS.length; index++) {
this.context.activeTexture(this.context.TEXTURE0 + index + 1);
this.context.bindTexture(this.context.TEXTURE_2D, batch.textures[index]);
this.context.uniform1i(this.uniforms[MAP_UNIFORMS[index]], index + 1);
this.context.uniform1f(this.uniforms[MAP_FLAGS[index]], batch.mapState[index] ? 1 + (batch.mapState[index].uvChannel ?? 0) : 0);
}
this.context.uniform2f(this.uniforms.normalScale, batch.mapState[5], batch.mapState[6]);
this.context.uniform1f(this.uniforms.occlusionStrength, batch.mapState[7]);
this.context.uniform4f(this.uniforms.materialMoss, batch.mapState[8], batch.mapState[9], batch.mapState[10], batch.mapState[11]);
this.bindSurfaceWear(batch.wear);
const layers = batch.layerState;
this.context.uniform3f(this.uniforms.materialDielectric, layers[0], layers[1], layers[2]);
this.context.uniform2f(this.uniforms.materialCoat, layers[3], layers[4]);
this.context.uniform4f(this.uniforms.materialSheen, layers[5], layers[6], layers[7], layers[8]);
this.context.uniform2f(this.uniforms.materialAnisotropy, layers[16], layers[17]);
this.context.uniform3f(this.uniforms.materialIridescence, layers[18], layers[19], layers[20]);
this.context.uniform1i(this.uniforms.lightLinkMask, layers[21]);
this.context.uniform1f(this.uniforms.materialToon, layers[22]);
this.context.uniform1f(this.uniforms.materialEmissionFresnel, layers[24]);
this.context.uniform1f(this.uniforms.boxMapScale, batch.mapState[12]);
this.context.uniform1i(this.uniforms.boxMapAxis, batch.mapState[13]);
if (this.shaderFeatures?.has('splat')) requireSplatSupport().bind(this, batch.splat);
layerTextureSupport.bind?.(this, batch.mapState, layers, batch);
this.context.uniform1f(this.uniforms.hasLightMap, batch.lightMapTexture ? 1 : 0);
if (batch.lightMapTexture) {
this.context.activeTexture(this.context.TEXTURE0 + LIGHT_MAP_UNIT);
this.context.bindTexture(this.context.TEXTURE_2D, batch.lightMapTexture);
this.context.uniform1i(this.uniforms.lightMap, LIGHT_MAP_UNIT);
this.context.uniform1f(this.uniforms.lightMapScale, batch.mapState[15]);
}
}
if (textured && !this.benchmark && this.shaderFeatures?.has('instanced') === false)this.setSingleInstanceUniforms(batch.instanceData);
// A reflecting matrix reverses screen winding: clockwise triangles are the front faces of a mirrored batch.
if (batch.mirrored) this.backend.setFrontFaceClockwise(true);
// The shadow pass (not textured) draws the whole index buffer; its order does not matter there.
const flushRanges = textured && !this.benchmark ? batch.flushOrder?.ranges ?? null : null;
if (selection && !selection.isEverything) {
this.drawSelectedLevels(batch, selection, levelSet, levelSet === batch ? flushRanges : null);
} else {
this.context.bindVertexArray(batch.vertexArray);
if (flushRanges) this.drawFlushRanges(batch, flushRanges, batch.instanceCount);
else this.backend.drawIndexedInstanced(batch.indexCount, batch.instanceCount);
}
if (batch.mirrored) this.backend.setFrontFaceClockwise(false);
}
// A render pass draws raw material data instead of the lit image; the addon validates frame.pass and returns the shader mode.
preparePass(frame) {
if (frame.pass === undefined) return 0;
if (!this.passSupport) throw new Error('Render passes need installRenderPasses(renderer) from crucible/addons/render-passes.');
return this.passSupport.prepare(frame);
}
/**
* Sets the fog's density and velocity field (see docs/volumetric.md) until it is replaced or cleared with null. It wins over
* a field in the constructor's or the frame's volumeFog. The same size is written into the existing texture on the next frame.
*/
setFogField(field) {
this.fogFieldOverride = field === null ? null : validateFogField(field);
}
render(frame) {
const { eye, target = [0, 1.2, 0], armorColor = [0.53, 0.39, 0.24], armorSurface = [0.88, 0.32], exposure = 1, inspection = false } = frame;
const effects = resolveEffects(frame.effects);
const environment = { lightDirection: [-3, 6, 4], fogColor: [0.35, 0.43, 0.43], fogDensity: 0.006, daylight: 1, explosionCenter: [0, 0, 0], ...this.environment, ...frame.environment };
environment.fogDensity ??= this.fittedFogDensity ?? 0.006;
if (environment.localVolumes?.some?.(localVolume => localVolume?.lightsScene === true)) {
// Fire lights the set: the emitting volumes add point lights before the lighting state is written (#1046).
environment.pointLights = requireFeatureCode('volumeFog').support.withVolumeFireLights(this, environment, environment.volumeTime ?? frame.time ?? 0).pointLights;
}
const volume = resolveVolumeFog(environment.volumeFog);
if (this.fogFieldOverride) volume.field = this.fogFieldOverride;
if (volume.density > 0) {
requireFeatureCode('volumeFog');
if (!this.depth || !this.hdr || this.transparent || this.benchmark) throw new Error('Volume fog requires depth:true, active HDR and an opaque canvas');
if (!Number.isFinite(frame.time ?? 0) || Math.abs(frame.time ?? 0) > 1e6) throw new RangeError('Volume time must be finite and within ±1000000 seconds');
const direction = environment.lightDirection;
const lightLength = direction?.length === 3 ? Math.hypot(...direction) : NaN;
if (!Number.isFinite(lightLength) || lightLength < 1e-6 || !Array.from(direction).every(component => typeof component === 'number' && Math.abs(component) <= 1e6)) throw new RangeError('Volume light direction must have a finite nonzero length and bounded components');
}
updateLightingState(this.lighting, environment, { world: this.world });
this.syncViewTransform(environment);
// The shadow view follows the sun, so a moved sun redraws the map.
const lightChanged = String(this.activeLightDirection) !== String(environment.lightDirection);
this.activeLightDirection = environment.lightDirection;
this.diagnostics = frameDiagnostics({ world: this.world, depth: this.depth, effects, lightDirection: environment.lightDirection, shadowBounds: this.shadowBounds, coplanarProblems: this.coplanarDiagnostics?.(this.batches), skinProblems: deformationSupport.reflectedSkinDiagnostics?.(this.partLocations) });
const start = performance.now();
const context = this.context;
this.beginGpuTiming();
const assemblyAmount = Math.max(0, Math.min(1, frame.assemblyAmount ?? 0));
// Swaying foliage moves every frame, so its shadow map is redrawn whenever time or wind changes.
const windChanged = this.updateWindState(frame);
const casterChanged = this.assemblyAmount !== assemblyAmount || this.shadowsDirty || windChanged || lightChanged;
this.requireFeatureNames(shaderFeaturesOfLighting(this.lighting));
const passMode = this.preparePass(frame);
this.renderingPass = passMode > 0;
this.volumeShadowWanted = volume.density > 0 || (Array.isArray(environment.localVolumes) && environment.localVolumes.some(localVolume => localVolume?.scatter > 0));
if (casterChanged || this.shadowMapSizeWanted() !== this.shadowMapSize) {
this.assemblyAmount = assemblyAmount;
this.createShadowMap();
}
this.updateLocalShadows(casterChanged);
const environmentMap = this.activateEnvironment(environment.map);
this.requireFeatureNames([environmentMap ? 'environmentMap' : 'studioLighting']);
mat4.lookAt(this.view, eye, target, frame.up ?? [0, 1, 0]);
applyProjection(this.projection, this.withFittedNear(frame), this.canvas.width / this.canvas.height, { world: this.world });
mat4.multiply(this.viewProjection, this.projection, this.view);
mat4.invert(this.inverseViewProjection, this.viewProjection);
extractFrustumPlanes(this.viewProjection, this.frustumPlanes);
this.viewForward = [-this.view[2], -this.view[6], -this.view[10]];
// The water mirror is a cheap draw: it reuses the cascades of the last lit frame and leaves their redraw to the lit frame that follows.
if (frame.reflectionTarget && this.shadowCascades?.texture) {
this.cascadeCastersChanged ||= casterChanged;
} else {
this.shadowCascades?.update(this, casterChanged || Boolean(this.cascadeCastersChanged));
this.cascadeCastersChanged = false;
}
// The water reflection addon draws the scene a second time into its own smaller target (frame.reflectionTarget).
const mirrorTarget = frame.reflectionTarget;
context.bindFramebuffer(context.FRAMEBUFFER, mirrorTarget ? mirrorTarget.framebuffer : passMode ? this.passSupport.framebuffer : this.benchmark ? null : this.multisampleFramebuffer);
context.viewport(0, 0, mirrorTarget?.width ?? this.canvas.width, mirrorTarget?.height ?? this.canvas.height);
if (passMode) {
context.clearColor(...this.passSupport.background(frame.pass));
} else {
context.clearColor(...clearColourFor(this.background, this.transparent));
}
// The environment background covers every pixel, so the colour clear before it would be overwritten.
const backgroundCoversFrame = !passMode && Boolean(environmentMap?.showBackground) && !this.transparent;
context.clear(backgroundCoversFrame ? context.DEPTH_BUFFER_BIT : context.COLOR_BUFFER_BIT | context.DEPTH_BUFFER_BIT);
const environmentBackgroundDrawn = !passMode && this.drawEnvironmentBackground(environmentMap, frame, exposure);
if (this.world && !this.benchmark && !passMode && !environmentBackgroundDrawn) this.drawSky(frame);
context.enable(context.DEPTH_TEST);
context.enable(context.CULL_FACE);
context.useProgram(this.program);
context.uniformMatrix4fv(this.uniforms.viewProjection, false, this.viewProjection);
this.setFlushProjection(this.viewProjection);
context.uniformMatrix4fv(this.uniforms.lightProjection, false, this.lightProjection);
context.uniform1f(this.uniforms.shadowBiasPerSlope, this.shadowBiasPerSlope);
context.uniform3fv(this.uniforms.eye, eye);
this.shadowCascades?.bindUniforms(this);
context.uniform3fv(this.uniforms.armorColor, armorColor);
context.uniform2fv(this.uniforms.armorSurface, armorSurface);
context.uniform1f(this.uniforms.exposure, exposure);
context.uniform1f(this.uniforms.inspection, inspection ? 1 : 0);
context.uniform1f(this.uniforms.hdrEnabled, this.hdr ? 1 : 0);
context.uniform1i(this.uniforms.pointLightCount, frame.reflectionTarget ? 0 : this.lighting.pointCount);
context.uniform4fv(this.uniforms['pointLightPositions[0]'], this.lighting.positions);
context.uniform4fv(this.uniforms['pointLightColors[0]'], this.lighting.colors);
context.uniform1fv(this.uniforms['pointLightRadii[0]'], this.lighting.radii);
this.applyLocalLightUniforms(Boolean(frame.reflectionTarget));
this.lighting.bind?.(this);
context.uniform3fv(this.uniforms.keyColor, this.lighting.keyColor);
context.uniform1f(this.uniforms.fillIntensity, this.lighting.fillIntensity);
context.uniform1f(this.uniforms.ambientIntensity, this.lighting.ambientIntensity);
context.uniform1f(this.uniforms.specularAntiAliasing, this.lighting.specularAntiAliasing);
context.uniform1f(this.uniforms.time, frame.time ?? 0);
context.uniform1f(this.uniforms.wind, frame.wind ?? 0.3);
context.uniform1f(this.uniforms.worldMode, this.world ? 1 : 0);
context.uniform1f(this.uniforms.daylight, environment.daylight);
context.uniform3fv(this.uniforms.lightDirection, environment.lightDirection);
context.uniform3fv(this.uniforms.fogColor, environment.fogColor);
context.uniform1f(this.uniforms.fogDensity, environment.fogDensity);
context.uniform3fv(this.uniforms.waterRipple, frame.waterRipple ?? [10000, 0, 10000]);
context.uniform1f(this.uniforms.rippleTime, frame.rippleTime ?? -1000);
context.uniform1f(this.uniforms.explosionProgress, frame.explosionProgress ?? 1);
context.uniform3fv(this.uniforms.explosionCenter, environment.explosionCenter);
context.uniform1f(this.uniforms.assemblyAmount, assemblyAmount);
context.activeTexture(context.TEXTURE0);
context.bindTexture(context.TEXTURE_2D, this.shadowTexture);
context.uniform1i(this.uniforms.shadowMap, 0);
this.bindTintedShadows();
this.applyEnvironmentUniforms(environmentMap);
context.uniform1f(this.uniforms.renderPassMode, passMode);
context.uniform1f(this.uniforms.renderPassDepthRange, frame.passDepthRange ?? 100);
if (passMode > 5) this.passSupport.bindFrame(frame, environment, volume);
let objectBase = 0;
for (const batch of this.batches) {
if (this.benchmark) {
this.drawBatch(batch, true);
} else if ((passMode > 5 ? this.passSupport.drawsInPass(batch, passMode) : this.drawsInOpaqueLoop(batch)) && !(mirrorTarget && batch.mapState[20])) {
context.uniform1f(this.uniforms.renderPassObjectBase, objectBase);
objectBase += batch.instanceCount;
// Object IDs are the instance ordinal, which culling and level selection renumber, so that pass draws every instance.
if (passMode > 5) this.passSupport.drawBatch(batch, passMode, frame, objectBase - batch.instanceCount);
else this.drawAlphaBatch(batch, true, passMode !== OBJECT_ID_PASS_MODE);
}
}
this.applyDepthRank(0);
context.disable(context.SAMPLE_ALPHA_TO_COVERAGE);
context.enable(context.CULL_FACE);
context.bindVertexArray(null);
if (mirrorTarget) {
this.renderingPass = false;
this.endGpuTiming();
return;
}
if (passMode) {
this.passSupport.copyToCanvas();
} else if (!this.benchmark) {
this.drawTranslucent(frame, environment, assemblyAmount, environmentMap);
this.drawBlendBatches(frame);
this.resolveFrame(frame, effects, environment, volume);
}
this.renderingPass = false;
this.endGpuTiming();
this.cpuMilliseconds = performance.now() - start;
}
beginGpuTiming() {
if (this.gpuTimer === undefined) this.gpuTimer = this.createGpuTimer?.(this.context) ?? null;
this.gpuTimer?.begin();
}
endGpuTiming() {
if (!this.gpuTimer) return;
this.gpuTimer.end();
this.gpuMilliseconds = this.gpuTimer.collect();
}
// The water mirror draws without local lights: it is blurred and rippled, and the sun, sky and fog colour carry the picture.
applyLocalLightUniforms(withoutLights = false) {
const context = this.context;
const lighting = this.lighting;
const uniforms = this.uniforms;
context.uniform1fv(uniforms['pointLightShadowTiles[0]'], lighting.pointShadows);
context.uniform1i(uniforms.spotLightCount, withoutLights ? 0 : lighting.spotCount);
context.uniform4fv(uniforms['spotLightPositions[0]'], lighting.spotPositions);
context.uniform4fv(uniforms['spotLightColors[0]'], lighting.spotColors);
context.uniform4fv(uniforms['spotLightDirections[0]'], lighting.spotDirections);
context.uniform4fv(uniforms['spotLightParameters[0]'], lighting.spotParameters);
context.uniform1i(uniforms.areaLightCount, withoutLights ? 0 : lighting.areaCount);
context.uniform4fv(uniforms['areaLightPositions[0]'], lighting.areaPositions);
context.uniform4fv(uniforms['areaLightColors[0]'], lighting.areaColors);
context.uniform4fv(uniforms['areaLightNormals[0]'], lighting.areaNormals);
context.uniform4fv(uniforms['areaLightTangents[0]'], lighting.areaTangents);
if (lighting.shadowCasters.length === 0 || !this.localShadowTexture) return;
context.uniformMatrix4fv(uniforms['localShadowMatrices[0]'], false, this.localShadowMatrices);
context.uniform1fv(uniforms['localShadowTexelAngles[0]'], this.localShadowTexelAngles);
context.activeTexture(context.TEXTURE0 + LOCAL_SHADOW_UNIT);
context.bindTexture(context.TEXTURE_2D, this.localShadowTexture);
context.uniform1i(uniforms.localShadowAtlas, LOCAL_SHADOW_UNIT);
context.activeTexture(context.TEXTURE0);
}
// Programs and shaders that deferProgramLink started and finishConstruction has not yet taken over.
releasePendingConstruction() {
const context = this.context;
const started = [...Object.values(this.pendingConstruction?.pending ?? {}), ...(this.pendingEnvironmentPrograms?.values() ?? [])];
for (const { program, shaders } of started) {
// Reading the link status waits for a link still in flight; deleting a program mid-link leaves a GL error that the next renderer on this context sees (#74).
context.getProgramParameter(program, context.LINK_STATUS);
shaders.forEach((shader) => context.deleteShader(shader));
context.deleteProgram(program);
}
this.pendingConstruction = null;
this.pendingEnvironmentPrograms = null;
}
dispose() {
this.disposed = true;
this.releasePendingConstruction();
releaseStartedPrograms(this.context);
this.fogFieldTexture?.dispose();
this.releaseFrameTargets();
this.shadowCascades?.dispose(this.context, this.renderTargets);
viewTransformShader.dispose?.(this);
if (this.localShadowTexture) this.context.deleteTexture(this.localShadowTexture);
if (this.localShadowFramebuffer) this.context.deleteFramebuffer(this.localShadowFramebuffer);
if (this.placeholderShadowTexture) this.context.deleteTexture(this.placeholderShadowTexture);
if (this.tintFramebuffer) {
this.context.deleteTexture(this.tintTexture);
this.context.deleteFramebuffer(this.tintFramebuffer);
}
this.batches.forEach((batch) => {
this.context.deleteVertexArray(batch.vertexArray);
this.releaseLevelDraws(batch);
});
this.buffers.forEach((buffer) => this.context.deleteBuffer(buffer));
this.geometryBuffers?.clear();
this.context.deleteTexture(this.shadowTexture);
this.context.deleteFramebuffer(this.shadowFramebuffer);
this.context.deleteProgram(this.program);
if (this.liquidProgram) this.context.deleteProgram(this.liquidProgram);
this.context.deleteProgram(this.depthProgram);
if (this.postProgram) this.context.deleteProgram(this.postProgram);
// A program still linking must finish first: deleting it mid-link leaves a GL error that the next renderer on this context sees.
for (const variant of this.postVariants?.values() ?? []) this.context.deleteProgram(variant.pending ? this.backend.finishProgram(variant.pending) : variant.program);
if (this.skyProgram) this.context.deleteProgram(this.skyProgram);
if (this.bloomProgram) this.context.deleteProgram(this.bloomProgram);
if (this.occlusionProgram) this.context.deleteProgram(this.occlusionProgram);
this.passSupport?.dispose(this.context);
for (const stage of this.postStages ?? []) stage.dispose(this.context);
if (this.localVolumeComposite) requireFeatureCode('volumeFog').support.releaseLocalVolumeComposite(this, true);
if (this.environmentBackgroundProgram) this.context.deleteProgram(this.environmentBackgroundProgram);
this.environmentResources?.dispose();
for (const texture of this.textures.values()) this.context.deleteTexture(texture);
if (this.splatPlaceholder) requireSplatSupport().dispose(this);
this.textures.clear();
for (const cache of [this.skinTextures, this.influenceTextures, this.morphTextures]) {
for (const record of cache?.values() ?? []) this.context.deleteTexture(record.texture);
cache?.clear();
}
this.partLocations.clear();
this.updatePartIdentities?.clear();
this.updateSkins?.clear();
this.updateMorphs?.clear();
this.updateBatches?.clear();
}
}
// Glaze is the public name of the real-time renderer; CrucibleRenderer stays for existing code.
export { CrucibleRenderer as Glaze };
/** Deprecated: the old name of CrucibleRenderer, removed in the release after 0.20.0. */
export { CrucibleRenderer as Renderer67 };