3D engine that AI agents drive
Slice accessor copy, geometry conversion, HDRI rows and the sky prefilter so large worlds stop blocking the page (Part of #ISSUE)
Nguyen Xuan An6667611c3569
diff --git a/changes/ISSUE-hero-jank.md b/changes/ISSUE-hero-jank.mdindex 42efa845..ff8c0905 100644--- a/changes/ISSUE-hero-jank.md+++ b/changes/ISSUE-hero-jank.md@@ -1 +1,2 @@- A renderer built with `deferProgramLink: true` links its shaders without freezing the page: await `renderer.programsReady()`; `shaderFeatureRepresentatives(parts)` picks the few parts that compile the program a whole scene needs, and `groupParts` builds each material key once; `await renderer.prepareFrame(frame)` then draws the first frame while the canvas is hidden without blocking on the post, liquid, occlusion and reversed-depth programs a first draw links (#ISSUE)+- `loadGltf` copies accessors and converts geometry in slices of about 8 ms, and `loadHdri` decodes a Radiance map a row at a time with a yield between slices, so a large model or sky no longer blocks the page in one piece; the sync `readAccessor` and `parseRadianceHdr` stay, and the output is byte for byte the same (#ISSUE)diff --git a/changes/ISSUE-hero-jank.size.md b/changes/ISSUE-hero-jank.size.mdindex 074c81ab..c27f48d1 100644--- a/changes/ISSUE-hero-jank.size.md+++ b/changes/ISSUE-hero-jank.size.md@@ -14,3 +14,6 @@- entry:user-pass: compileProgram carries the prepare-time wait (about 200 bytes) so the first draw of a hidden scene never blocks on this program- entry:reversed-depth: compileProgram carries the prepare-time wait (about 200 bytes) so the first draw of a hidden scene never blocks on this program- entry:liquid-shader: compileProgram carries the prepare-time wait (about 200 bytes) so the first draw of a hidden scene never blocks on this program+- entry:hdri: the sliced Radiance decode and the stepped sky prefilter (generators with a checkpoint between rows and GL steps) cost 298 bytes gzip, for a measured drop in first live frame on the home hero loop from 1.7 to 2.2 s down to 1.4 to 1.6 s+- entry:gltf: sliced accessor copy and geometry conversion, 826 bytes gzip, so a large model converts in 8 ms slices instead of one block+- entry:core: the shared slicer, sliced prefilter steps and renderer hook, 1115 bytes gzipdiff --git a/src/cooperative.js b/src/cooperative.jsnew file mode 100644index 00000000..58423b6e--- /dev/null+++ b/src/cooperative.js@@ -0,0 +1,28 @@+// One clock for every slicer: whichever job yielded last has given the page its turn, so two jobs that run one after the other+// in the same task share one slice instead of each spending its own.+let lastYieldAt = performance.now();++/** Hands the thread back so the page can draw and handle input between the slices of a long job. */+export async function yieldToPage() {+ await (globalThis.scheduler?.yield ? globalThis.scheduler.yield() : new Promise(resolve => setTimeout(resolve, 0)));+ lastYieldAt = performance.now();+}++/** Elements a loop handles between two checks of the clock. A multiple of 3 and 4, so vec3 and vec4 data never splits an item. */+export const CHUNK_ELEMENTS = 49152;++/** Returns `checkpoint()`: it yields to the page once more than `sliceMilliseconds` have passed since anything last yielded, else it returns at once. */+export function createSlicer(sliceMilliseconds = 8) {+ return async function checkpoint() {+ if (performance.now() - lastYieldAt <= sliceMilliseconds) return;+ await yieldToPage();+ };+}++/** Calls `visit(from, to)` over [0, length) in chunks of CHUNK_ELEMENTS, with a checkpoint after each. */+export async function forEachChunk(length, checkpoint, visit) {+ for (let from = 0; from < length; from += CHUNK_ELEMENTS) {+ visit(from, Math.min(from + CHUNK_ELEMENTS, length));+ await checkpoint();+ }+}diff --git a/src/environment.js b/src/environment.jsindex da0f5399..422cd22f 100644--- a/src/environment.js+++ b/src/environment.js@@ -87,7 +87,10 @@ function sphericalHarmonicBasis(x, y, z) {// Returns 27 floats (9 RGB triples) with basis constants and the Lambert kernel folded in,// so evaluateIrradiance(coefficients, normal) is the diffuse radiance for a white surface.-export function computeIrradianceCoefficients(map) {+const IRRADIANCE_ROWS_PER_STEP = 32;++// One step per few rows of the map, so a caller can hand the thread back between steps.+function* irradianceSteps(map) {assertEnvironmentMap(map);const { width, height, channels, data } = map;const columnSine = new Float64Array(width);@@ -114,6 +117,7 @@ export function computeIrradianceCoefficients(map) {sums[term * 3 + 2] += data[offset + 2] * termWeight;}}+ if (row % IRRADIANCE_ROWS_PER_STEP === IRRADIANCE_ROWS_PER_STEP - 1) yield;}const coefficients = new Float32Array(27);for (let term = 0; term < 9; term++) {@@ -124,6 +128,27 @@ export function computeIrradianceCoefficients(map) {return coefficients;}+export function computeIrradianceCoefficients(map) {+ return runToEnd(irradianceSteps(map));+}++/** Runs a step generator to its end without pausing and returns its result. */+function runToEnd(steps) {+ let step = steps.next();+ while (!step.done) step = steps.next();+ return step.value;+}++/** Awaits `checkpoint()` after every step of a generator and returns its result. */+export async function runInSlices(steps, checkpoint) {+ let step = steps.next();+ while (!step.done) {+ await checkpoint();+ step = steps.next();+ }+ return step.value;+}+export function evaluateIrradiance(coefficients, normal) {const [x, y, z] = normal;const basis = sphericalHarmonicBasis(x, y, z);@@ -134,11 +159,14 @@ export function evaluateIrradiance(coefficients, normal) {return result.map(value => Math.max(value, 0));}-function paddedHalfFloatSource(map) {- const pixelCount = map.width * map.height;+// Rows of the map as RGBA floats clamped to the half-float range, so a large map goes to the GPU a strip at a time.+const UPLOAD_ROWS_PER_STEP = 64;++function paddedHalfFloatRows(map, firstRow, rowCount) {+ const pixelCount = map.width * rowCount;const padded = new Float32Array(pixelCount * 4);for (let pixel = 0; pixel < pixelCount; pixel++) {- const source = pixel * map.channels;+ const source = (firstRow * map.width + pixel) * map.channels;const target = pixel * 4;padded[target] = Math.min(Math.max(map.data[source], 0), HALF_FLOAT_MAXIMUM);padded[target + 1] = Math.min(Math.max(map.data[source + 1], 0), HALF_FLOAT_MAXIMUM);@@ -290,15 +318,29 @@ function drawIntoLevel(context, framebuffer, texture, level, width, height) {}// Prefilters once at load: GGX-convolved equirect mip chain (level = roughness), split-sum BRDF lookup and L2 spherical harmonics.-export function createEnvironmentResources(context, map, { compileProgram, fullscreenVertex }) {+export function createEnvironmentResources(context, map, programs) {+ return runToEnd(environmentResourceSteps(context, map, programs));+}++/** The same resources, built a step at a time (upload, mipmaps, each roughness level, the lookup table, the irradiance) so a caller can draw frames between steps. */+export function createEnvironmentResourcesInSlices(context, map, programs, checkpoint) {+ return runInSlices(environmentResourceSteps(context, map, programs), checkpoint);+}++function* environmentResourceSteps(context, map, { compileProgram, fullscreenVertex }) {assertEnvironmentMap(map);if (!context.getExtension('EXT_color_buffer_float')) throw new Error('Environment maps require EXT_color_buffer_float.');const started = performance.now();const layout = environmentSpecularLayout(map);const sourceLevelCount = Math.floor(Math.log2(Math.max(map.width, map.height))) + 1;const sourceTexture = createHalfFloatTexture(context, context.RGBA16F, sourceLevelCount, map.width, map.height, { wrapHorizontally: true });- context.texSubImage2D(context.TEXTURE_2D, 0, 0, 0, map.width, map.height, context.RGBA, context.FLOAT, paddedHalfFloatSource(map));+ for (let firstRow = 0; firstRow < map.height; firstRow += UPLOAD_ROWS_PER_STEP) {+ const rowCount = Math.min(UPLOAD_ROWS_PER_STEP, map.height - firstRow);+ context.texSubImage2D(context.TEXTURE_2D, 0, 0, firstRow, map.width, rowCount, context.RGBA, context.FLOAT, paddedHalfFloatRows(map, firstRow, rowCount));+ yield;+ }context.generateMipmap(context.TEXTURE_2D);+ yield;const specularTexture = createHalfFloatTexture(context, context.RGBA16F, layout.levelCount, layout.width, layout.height, { wrapHorizontally: true });const brdfTexture = createHalfFloatTexture(context, context.RG16F, 1, ENVIRONMENT_BRDF_SIZE, ENVIRONMENT_BRDF_SIZE, { wrapHorizontally: false });const framebuffer = context.createFramebuffer();@@ -320,6 +362,7 @@ export function createEnvironmentResources(context, map, { compileProgram, fullscontext.uniform1f(roughnessUniform, level / Math.max(1, layout.levelCount - 1));context.uniform1f(levelOffsetUniform, Math.max(0, Math.log2(map.width / layout.levels[level].width)));drawIntoLevel(context, framebuffer, specularTexture, level, layout.levels[level].width, layout.levels[level].height);+ yield;}context.useProgram(brdfProgram);drawIntoLevel(context, framebuffer, brdfTexture, 0, ENVIRONMENT_BRDF_SIZE, ENVIRONMENT_BRDF_SIZE);@@ -329,6 +372,8 @@ export function createEnvironmentResources(context, map, { compileProgram, fullscontext.deleteProgram(brdfProgram);context.deleteTexture(sourceTexture);context.finish();+ yield;+ const irradiance = yield* irradianceSteps(map.irradianceSource ?? map);return {data: map.data,irradianceSource: map.irradianceSource,@@ -336,7 +381,7 @@ export function createEnvironmentResources(context, map, { compileProgram, fullsbrdfTexture,levelCount: layout.levelCount,bytes: layout.bytes,- irradiance: computeIrradianceCoefficients(map.irradianceSource ?? map),+ irradiance,prefilterMilliseconds: performance.now() - started,dispose() {context.deleteTexture(specularTexture);@@ -353,6 +398,7 @@ registerEnvironmentSupport({assertMap: assertEnvironmentMap,estimateBytes: estimateEnvironmentBytes,createResources: createEnvironmentResources,+ createResourcesInSlices: createEnvironmentResourcesInSlices,prefilterFragment: environmentPrefilterFragment,brdfFragment: environmentBrdfFragment,backgroundFragment: environmentBackgroundFragment,diff --git a/src/gltf-accessors.js b/src/gltf-accessors.jsindex df856088..4688a837 100644--- a/src/gltf-accessors.js+++ b/src/gltf-accessors.js@@ -1,3 +1,5 @@+import { forEachChunk } from './cooperative.js';+export const COMPONENT_TYPES = {5120: Int8Array,5121: Uint8Array,@@ -9,15 +11,27 @@ export const COMPONENT_TYPES = {const COMPONENT_COUNTS = { SCALAR: 1, VEC2: 2, VEC3: 3, VEC4: 4, MAT2: 4, MAT3: 9, MAT4: 16 };const NORMALIZATION_DIVISORS = { 5120: 127, 5121: 255, 5122: 32767, 5123: 65535 };+function fillFloats(attribute, values, divisor, from, to) {+ for (let index = from; index < to; index++) {+ const value = attribute.array[index];+ values[index] = divisor === 1 ? value : Math.max(value / divisor, -1);+ }+}+/** Float values of an attribute, with normalized integers scaled into zero to one or minus one to one. */export function attributeFloats(attribute) {+ const length = attribute.count * attribute.itemSize;+ const values = new Float32Array(length);+ fillFloats(attribute, values, attribute.normalized ? NORMALIZATION_DIVISORS[attribute.componentType] : 1, 0, length);+ return values;+}++/** The same values as attributeFloats, converted a chunk at a time with `checkpoint()` between chunks so a large attribute does not block the page. */+export async function attributeFloatsInSlices(attribute, checkpoint) {const length = attribute.count * attribute.itemSize;const values = new Float32Array(length);const divisor = attribute.normalized ? NORMALIZATION_DIVISORS[attribute.componentType] : 1;- for (let index = 0; index < length; index++) {- const value = attribute.array[index];- values[index] = divisor === 1 ? value : Math.max(value / divisor, -1);- }+ await forEachChunk(length, checkpoint, (from, to) => fillFloats(attribute, values, divisor, from, to));return values;}@@ -25,15 +39,37 @@ function elementBytesOf(accessor) {return COMPONENT_TYPES[accessor.componentType].BYTES_PER_ELEMENT * COMPONENT_COUNTS[accessor.type];}-function copyElements(source, offset, stride, count, elementBytes) {+function checkElementsFit(source, offset, stride, count, elementBytes) {if (count > 0 && offset + (count - 1) * stride + elementBytes > source.length) {throw new Error('glTF accessor exceeds its buffer view.');}- const packed = new Uint8Array(count * elementBytes);- for (let element = 0; element < count; element++) {+}++// Tightly packed elements are one block of bytes. Uint8Array.prototype.slice copies even when `source` is a Node Buffer, whose own slice is a view.+function copyTightly(source, offset, count, elementBytes) {+ return Uint8Array.prototype.slice.call(source, offset, offset + count * elementBytes);+}++function copyStridedRange(source, offset, stride, elementBytes, packed, from, to) {+ for (let element = from; element < to; element++) {const start = offset + element * stride;packed.set(source.subarray(start, start + elementBytes), element * elementBytes);}+}++function copyElements(source, offset, stride, count, elementBytes) {+ checkElementsFit(source, offset, stride, count, elementBytes);+ if (stride === elementBytes) return copyTightly(source, offset, count, elementBytes);+ const packed = new Uint8Array(count * elementBytes);+ copyStridedRange(source, offset, stride, elementBytes, packed, 0, count);+ return packed;+}++async function copyElementsInSlices(source, offset, stride, count, elementBytes, checkpoint) {+ checkElementsFit(source, offset, stride, count, elementBytes);+ if (stride === elementBytes) return copyTightly(source, offset, count, elementBytes);+ const packed = new Uint8Array(count * elementBytes);+ await forEachChunk(count, checkpoint, (from, to) => copyStridedRange(source, offset, stride, elementBytes, packed, from, to));return packed;}@@ -69,25 +105,41 @@ export function createAccessorReader(document, bufferBytes, meshoptDecoder) {return viewCache.get(index);}- function readAccessor(index) {+ function planAccessor(index) {const accessor = document.accessors?.[index];if (!accessor) throw new Error('Invalid glTF accessor index.');const ArrayType = COMPONENT_TYPES[accessor.componentType];if (!ArrayType) throw new Error('Unsupported glTF accessor component type.');- const itemSize = COMPONENT_COUNTS[accessor.type];const elementBytes = elementBytesOf(accessor);- let packed;- if (accessor.bufferView === undefined) {- packed = new Uint8Array(accessor.count * elementBytes);- } else {- const stride = document.bufferViews[accessor.bufferView].byteStride || elementBytes;- packed = copyElements(viewBytes(accessor.bufferView), accessor.byteOffset ?? 0, stride, accessor.count, elementBytes);- }+ const stride = accessor.bufferView === undefined ? 0 : document.bufferViews[accessor.bufferView].byteStride || elementBytes;+ return { accessor, ArrayType, itemSize: COMPONENT_COUNTS[accessor.type], elementBytes, stride };+ }++ function finishAccessor({ accessor, ArrayType, itemSize }, packed) {const array = new ArrayType(packed.buffer);if (accessor.sparse) applySparse(accessor, array, itemSize);return { array, itemSize, count: accessor.count, normalized: accessor.normalized === true, componentType: accessor.componentType };}+ function readAccessor(index) {+ const plan = planAccessor(index);+ const { accessor, elementBytes, stride } = plan;+ const packed = accessor.bufferView === undefined+ ? new Uint8Array(accessor.count * elementBytes)+ : copyElements(viewBytes(accessor.bufferView), accessor.byteOffset ?? 0, stride, accessor.count, elementBytes);+ return finishAccessor(plan, packed);+ }++ /** The same accessor as readAccessor, copied a chunk at a time with `checkpoint()` between chunks. */+ async function readAccessorInSlices(index, checkpoint) {+ const plan = planAccessor(index);+ const { accessor, elementBytes, stride } = plan;+ const packed = accessor.bufferView === undefined+ ? new Uint8Array(accessor.count * elementBytes)+ : await copyElementsInSlices(viewBytes(accessor.bufferView), accessor.byteOffset ?? 0, stride, accessor.count, elementBytes, checkpoint);+ return finishAccessor(plan, packed);+ }+function applySparse(accessor, array, itemSize) {const { count, indices, values } = accessor.sparse;const IndexType = COMPONENT_TYPES[indices.componentType];@@ -103,5 +155,5 @@ export function createAccessorReader(document, bufferBytes, meshoptDecoder) {}}- return { prepare, readAccessor, viewBytes };+ return { prepare, readAccessor, readAccessorInSlices, viewBytes };}diff --git a/src/gltf-decode.js b/src/gltf-decode.jsindex 87ff446f..b7087c2e 100644--- a/src/gltf-decode.js+++ b/src/gltf-decode.js@@ -1,4 +1,5 @@import { mat4 } from 'gl-matrix';+import { createSlicer } from './cooperative.js';import { COMPONENT_TYPES, attributeFloats, createAccessorReader } from './gltf-accessors.js';import { createClips } from './gltf-animation.js';import { layerTextureReferences } from './gltf-layers.js';@@ -138,6 +139,7 @@ export async function decodeGltf({ document, glbBinary, resourceBytes, decoders,return index === 0 ? glbBinary : null;}+ const checkpoint = createSlicer();const reader = createAccessorReader(document, bufferBytes, decoders.meshopt);await reader.prepare();@@ -295,11 +297,11 @@ export async function decodeGltf({ document, glbBinary, resourceBytes, decoders,if (!decoded) throw new Error(`Draco geometry is missing ${semantic}.`);attributes[name] = decodedAttribute(decoded, document.accessors[accessorIndex]?.normalized === true);} else {- attributes[name] = reader.readAccessor(accessorIndex);+ attributes[name] = await reader.readAccessorInSlices(accessorIndex, checkpoint);}}let index = null;- if (primitive.indices !== undefined) index = dracoGeometry ? decodedAttribute(dracoGeometry.getIndex()) : reader.readAccessor(primitive.indices);+ if (primitive.indices !== undefined) index = dracoGeometry ? decodedAttribute(dracoGeometry.getIndex()) : await reader.readAccessorInSlices(primitive.indices, checkpoint);const targets = primitive.targets ?? [];const source = {uuid: key,diff --git a/src/gltf.js b/src/gltf.jsindex af7f4a9d..dbdf9a23 100644--- a/src/gltf.js+++ b/src/gltf.js@@ -1,7 +1,8 @@import { mat4 } from 'gl-matrix';import { applyClip } from './gltf-animation.js';import { GLTF_LAYER_EXTENSIONS, layerTextureReferences, materialLayersFromGltf } from './gltf-layers.js';-import { attributeFloats } from './gltf-accessors.js';+import { attributeFloatsInSlices } from './gltf-accessors.js';+import { createSlicer, forEachChunk } from './cooperative.js';import { describeCompressedImage } from './compressed-texture.js';export { ktx2WorkerConfigFor } from './compressed-texture.js';import { decodeGltf, isLinePrimitive, overLimit, textureSourceIndex, throwOverruns, unusablePrimitives } from './gltf-decode.js';@@ -38,7 +39,6 @@ const LAYER_SHADER_EXTENSIONS = Object.freeze(['KHR_materials_anisotropy', 'KHR_// The shader code for anisotropy, iridescence and transmission is not in the core bundle; a file that uses one brings it in.const CONVERSION_SLICE_MILLISECONDS = 8;-const yieldToPage = () => (globalThis.scheduler?.yield ? globalThis.scheduler.yield() : new Promise(resolve => setTimeout(resolve, 0)));async function loadLayerShadersFor(document) {const usesLayerShaders = (document.materials ?? []).some(material => LAYER_SHADER_EXTENSIONS.some(extension => material?.extensions?.[extension]) || layerTextureReferences(material).length > 0 || materialUvTransforms(material ?? {}).normalRelative);@@ -799,23 +799,29 @@ function planTextureScaling(imageDefinitions, imageSizes, maxTexturePixels, coloreturn { targetByImageIndex, scaledTextures };}-function copyAttribute(attribute, size) {+async function copyAttribute(attribute, size, checkpoint) {if (attribute.itemSize !== size) throw new Error(`Expected a ${size}-component mesh attribute.`);- const values = attributeFloats(attribute);- if (!values.every(Number.isFinite)) throw new Error('Mesh attributes must contain finite values.');+ const values = await attributeFloatsInSlices(attribute, checkpoint);+ let allFinite = true;+ await forEachChunk(values.length, checkpoint, (from, to) => {+ for (let index = from; index < to; index++) allFinite &&= Number.isFinite(values[index]);+ });+ if (!allFinite) throw new Error('Mesh attributes must contain finite values.');return values;}/** Like copyAttribute, but a NaN or Infinity becomes 0 and is reported through `onNonFinite(count)` instead of refusing the file. */-function copyAttributeZeroingNonFinite(attribute, size, onNonFinite) {+async function copyAttributeZeroingNonFinite(attribute, size, onNonFinite, checkpoint) {if (attribute.itemSize !== size) throw new Error(`Expected a ${size}-component mesh attribute.`);- const values = attributeFloats(attribute);+ const values = await attributeFloatsInSlices(attribute, checkpoint);let nonFiniteCount = 0;- for (let index = 0; index < values.length; index++) {- if (Number.isFinite(values[index])) continue;- values[index] = 0;- nonFiniteCount++;- }+ await forEachChunk(values.length, checkpoint, (from, to) => {+ for (let index = from; index < to; index++) {+ if (Number.isFinite(values[index])) continue;+ values[index] = 0;+ nonFiniteCount++;+ }+ });if (nonFiniteCount) onNonFinite(nonFiniteCount);return values;}@@ -878,34 +884,38 @@ function hasTriangleWithArea(positions, indices) {return false;}-function convertGeometry(source, primitive, secondUvSet, onIgnoredVertexAlpha, onRepair) {+async function convertGeometry(source, primitive, secondUvSet, onIgnoredVertexAlpha, onRepair, checkpoint) {const { position, normal, uv, uv1, color, skinIndex, skinWeight } = source.attributes;const zeroedBy = label => count => onRepair(`${count} non-finite ${label} value(s) were set to 0`);- const positions = copyAttributeZeroingNonFinite(position, 3, zeroedBy('POSITION'));+ const positions = await copyAttributeZeroingNonFinite(position, 3, zeroedBy('POSITION'), checkpoint);const indices = new Uint32Array(source.index?.count ?? position.count);- for (let index = 0; index < indices.length; index++) {- const value = source.index ? source.index.array[index] : index;- if (!Number.isInteger(value) || value < 0 || value >= position.count) throw new UnusablePrimitiveError('an index is out of range of its POSITION accessor');- indices[index] = value;- }+ await forEachChunk(indices.length, checkpoint, (from, to) => {+ for (let index = from; index < to; index++) {+ const value = source.index ? source.index.array[index] : index;+ if (!Number.isInteger(value) || value < 0 || value >= position.count) throw new UnusablePrimitiveError('an index is out of range of its POSITION accessor');+ indices[index] = value;+ }+ });if (normal && normal.count !== position.count) throw new Error('NORMAL and POSITION counts must match.');if (!hasTriangleWithArea(positions, indices)) throw new UnusablePrimitiveError('every triangle has zero area');- const normals = normal ? copyAttribute(normal, 3) : computeVertexNormals(positions, indices);+ const normals = normal ? await copyAttribute(normal, 3, checkpoint) : computeVertexNormals(positions, indices);const geometry = { positions, normals, indices };const repairedNormals = [];- for (let offset = 0; offset < normals.length; offset += 3) {- const length = Math.hypot(...normals.subarray(offset, offset + 3));- if (length < 1e-8 && !normal) {- // A vertex that no triangle with area touches has no generated normal; it draws nothing, so any unit vector will do.- normals[offset + 1] = 1;- continue;- }- if (length < 1e-8) {- repairedNormals.push(offset);- continue;+ await forEachChunk(normals.length, checkpoint, (from, to) => {+ for (let offset = from; offset < to; offset += 3) {+ const length = Math.hypot(normals[offset], normals[offset + 1], normals[offset + 2]);+ if (length < 1e-8 && !normal) {+ // A vertex that no triangle with area touches has no generated normal; it draws nothing, so any unit vector will do.+ normals[offset + 1] = 1;+ continue;+ }+ if (length < 1e-8) {+ repairedNormals.push(offset);+ continue;+ }+ for (let axis = 0; axis < 3; axis++) normals[offset + axis] /= length;}- for (let axis = 0; axis < 3; axis++) normals[offset + axis] /= length;- }+ });if (repairedNormals.length) {// An authored normal of zero length cannot light anything: use the face normal of the triangles at that vertex, or up.const faceNormals = computeVertexNormals(positions, indices);@@ -916,28 +926,29 @@ function convertGeometry(source, primitive, secondUvSet, onIgnoredVertexAlpha, oonRepair(`${repairedNormals.length} vertex normal(s) had zero length and were rebuilt from the triangles`);}if (primitive.targets?.length) {- geometry.morphTargets = primitive.targets.map((target, index) => {+ geometry.morphTargets = [];+ for (const [index, target] of primitive.targets.entries()) {const channels = {};- if (target.POSITION !== undefined) channels.positions = copyAttributeZeroingNonFinite(source.morphPositions[index], 3, zeroedBy('morph POSITION'));- if (target.NORMAL !== undefined && normal) channels.normals = copyAttribute(source.morphNormals[index], 3);+ if (target.POSITION !== undefined) channels.positions = await copyAttributeZeroingNonFinite(source.morphPositions[index], 3, zeroedBy('morph POSITION'), checkpoint);+ if (target.NORMAL !== undefined && normal) channels.normals = await copyAttribute(source.morphNormals[index], 3, checkpoint);// Without a base NORMAL the authored deltas have nothing to add to: derive them from the morphed positions.if (!normal && channels.positions) channels.normals = computeMorphNormalDeltas(positions, indices, normals, channels.positions);- return channels;- });+ geometry.morphTargets.push(channels);+ }if (!normal && geometry.morphTargets.some(channels => channels.normals)) {onRepair('it has morph targets but no base NORMAL; base and per-target normals are generated from the triangles');}}if (uv && uv.count !== position.count) throw new Error('TEXCOORD_0 and POSITION counts must match.');- if (uv) geometry.uvs = copyAttribute(uv, 2);+ if (uv) geometry.uvs = await copyAttribute(uv, 2, checkpoint);// The renderer's second UV set is geometry.lightUvs, the one light maps use.if (secondUvSet) {if (!uv1 || uv1.count !== position.count) throw new Error('TEXCOORD_1 and POSITION counts must match.');- geometry.lightUvs = copyAttribute(uv1, 2);+ geometry.lightUvs = await copyAttribute(uv1, 2, checkpoint);}- if (color) geometry.colors = convertVertexColors(color, position.count, onIgnoredVertexAlpha);- if (skinIndex) geometry.skinIndices = new Uint16Array(copyAttribute(skinIndex, 4));- if (skinWeight) geometry.skinWeights = copyAttribute(skinWeight, 4);+ if (color) geometry.colors = await convertVertexColors(color, position.count, onIgnoredVertexAlpha, checkpoint);+ if (skinIndex) geometry.skinIndices = new Uint16Array(await copyAttribute(skinIndex, 4, checkpoint));+ if (skinWeight) geometry.skinWeights = await copyAttribute(skinWeight, 4, checkpoint);return geometry;}@@ -1110,11 +1121,11 @@ function worldMatrixOf(node, instanceMatrix, target) {}/** Keeps the RGB of COLOR_0. The alpha of an RGBA attribute is dropped, and onIgnoredVertexAlpha hears of it when it is below one. */-function convertVertexColors(attribute, vertexCount, onIgnoredVertexAlpha) {+async function convertVertexColors(attribute, vertexCount, onIgnoredVertexAlpha, checkpoint) {if (attribute.count !== vertexCount || ![3, 4].includes(attribute.itemSize)) {throw new Error('COLOR_0 requires matching RGB or RGBA vertex values.');}- const values = copyAttribute(attribute, attribute.itemSize);+ const values = await copyAttribute(attribute, attribute.itemSize, checkpoint);const colors = new Float32Array(vertexCount * 3);let alphaBelowOne = false;for (let vertex = 0; vertex < vertexCount; vertex++) {@@ -1274,7 +1285,8 @@ export async function parseGltf(data, options = {}) {const pendingNodeMatrix = new Float32Array(16);const keyedNodeIndices = nodesKeyedInClips(document);let actualVertices = 0;- const visitNode = node => {+ const checkpoint = createSlicer(CONVERSION_SLICE_MILLISECONDS);+ const visitNode = async node => {nodes.push(node);const sourceNodeIndex = node.association?.nodes;if (sourceNodeIndex !== undefined && document.nodes?.[sourceNodeIndex]?.extensions?.KHR_lights_punctual) {@@ -1313,7 +1325,7 @@ export async function parseGltf(data, options = {}) {const warning = `Repaired ${primitiveLabel(document, association.meshes, association.primitives)}: ${reason}.`;if (!warnings.includes(warning)) warnings.push(warning);};- const converted = convertGeometry(node.geometry, primitive, secondUvSet, () => meshNamesWithIgnoredAlpha.add(node.name), onRepair);+ const converted = await convertGeometry(node.geometry, primitive, secondUvSet, () => meshNamesWithIgnoredAlpha.add(node.name), onRepair, checkpoint);if (converted.uvs) bakeUvTransform(converted.uvs, uvTransform);geometries.set(geometryKey, converted);} catch (error) {@@ -1367,13 +1379,9 @@ export async function parseGltf(data, options = {}) {// Converting a large scene is one long block; handing the thread back every few milliseconds keeps the page responding. Same nodes, same order.const traversed = [];gltf.scene.traverse(node => traversed.push(node));- let sliceStart = performance.now();for (const node of traversed) {- visitNode(node);- if (performance.now() - sliceStart > CONVERSION_SLICE_MILLISECONDS) {- await yieldToPage();- sliceStart = performance.now();- }+ await visitNode(node);+ await checkpoint();}const toleratedNodes = Object.assign(new Set(), { collecting: true });validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, toleratedNodes);diff --git a/src/hdri.js b/src/hdri.jsindex 9ff2310b..cceee1b7 100644--- a/src/hdri.js+++ b/src/hdri.js@@ -1,3 +1,4 @@+import { createSlicer } from './cooperative.js';import { createEnvironmentMap, MAXIMUM_ENVIRONMENT_SIZE } from './environment.js';const MAXIMUM_FILE_BYTES = 256 * 1024 ** 2;@@ -67,8 +68,8 @@ function startsRunLengthScanline(bytes, position, width) {&& ((bytes[position + 2] << 8) | bytes[position + 3]) === width;}-// Parses Radiance RGBE (.hdr) data into linear RGB floats, top row first.-export function parseRadianceHdr(buffer) {+// Decodes one scanline per step, so a caller can run it to the end at once or hand the thread back between rows.+function* decodeRadianceRows(buffer) {const bytes = buffer instanceof Uint8Array ? buffer : new Uint8Array(buffer);if (bytes.length > MAXIMUM_FILE_BYTES) throw new RangeError('Radiance HDR file is larger than 256 MiB.');const { width, height, dataStart } = parseHeader(bytes);@@ -92,15 +93,35 @@ export function parseRadianceHdr(buffer) {data[target + 1] = scanline[column * 4 + 1] * scale;data[target + 2] = scanline[column * 4 + 2] * scale;}+ yield row;}return { width, height, data };}+// Parses Radiance RGBE (.hdr) data into linear RGB floats, top row first.+export function parseRadianceHdr(buffer) {+ const rows = decodeRadianceRows(buffer);+ let step = rows.next();+ while (!step.done) step = rows.next();+ return step.value;+}++// The same result as parseRadianceHdr, with `checkpoint()` awaited between rows so a large map does not block the page.+export async function parseRadianceHdrInSlices(buffer, checkpoint) {+ const rows = decodeRadianceRows(buffer);+ let step = rows.next();+ while (!step.done) {+ await checkpoint();+ step = rows.next();+ }+ return step.value;+}+// Fetches a .hdr file (for example a 1k or 2k Poly Haven HDRI) and returns an environment map descriptor.export async function loadHdri(url, { intensity, rotation, showBackground, backgroundBlur, signal, fetchImplementation = globalThis.fetch } = {}) {const response = await fetchImplementation(url, { signal });if (!response.ok) throw new Error(`HDRI download failed: HTTP ${response.status}.`);- const parsed = parseRadianceHdr(await response.arrayBuffer());+ const parsed = await parseRadianceHdrInSlices(await response.arrayBuffer(), createSlicer());return createEnvironmentMap({ ...parsed, intensity, rotation, showBackground, backgroundBlur });}diff --git a/src/hero-lab/loop/world.js b/src/hero-lab/loop/world.jsindex d3fbfdce..8fc7ae6a 100644--- a/src/hero-lab/loop/world.js+++ b/src/hero-lab/loop/world.js@@ -9,13 +9,14 @@ import { createCascadedShadows } from '../../cascaded-shadows.js';import { applyWaterReflection, attachWaterReflection } from '../../water-reflection.js';import { readPartRanks } from '../../showcase-download.js';import { prepareEffects } from './effects.js';+import { createSlicer, yieldToPage } from '../../cooperative.js';// The water mirror is off in the loop: once the camera moves between two draws the port world drew only its sky (the same happens// on hero-b.html?scene=port when the camera is set by hand; with the mirror off every pose draws). Turn it on again when that is fixed.const WATER_MIRROR_ENABLED = false;// Lets the page draw and handle input between the phases of a build, so one phase never queues behind another.-const yieldToMain = () => (globalThis.scheduler?.yield ? globalThis.scheduler.yield() : new Promise(resolve => setTimeout(resolve, 0)));+const yieldToMain = yieldToPage;async function fetchBlob(url) {const response = await fetch(url);@@ -131,6 +132,7 @@ export async function buildWorld(download, canvas, overrides = {}) {...overrides,pixelRatio: Math.min(devicePixelRatio, 1.25),deferProgramLink: true,+ deferEnvironmentPrefilter: true,...effects?.rendererOptions,...(options.shadowCascades ? { shadowCascades: createCascadedShadows(options.shadowCascades) } : {}),environment: { ...options.environment, map: environmentMap, ...(effects?.volumeFog ? { volumeFog: effects.volumeFog } : {}) },@@ -142,6 +144,9 @@ export async function buildWorld(download, canvas, overrides = {}) {lap('uploadMs');await renderer.programsReady();lap('linkMs');+ // The sky prefilter runs a few milliseconds at a time on this world's own context, before any frame draws on it.+ await renderer.prepareEnvironmentInSlices(environmentMap, createSlicer(SLICE_MILLISECONDS));+ lap('environmentMs');await replacePartsInSlices(renderer, whole.parts);const detachReflection = attachWaterReflection(renderer, whole.surface);lap('rendererMs');diff --git a/src/renderer.js b/src/renderer.jsindex 6c0756d6..83015187 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -564,7 +564,7 @@ function allFinite(values) {}export class Renderer67 {- constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, hdr = false, 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', deferProgramLink = false } = {}) {+ constructor(canvas, parts, { batching = true, pixelRatio = 1.5, benchmark = false, world = false, ground = true, transparent = false, samples = 4, hdr = false, 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', deferProgramLink = false, deferEnvironmentPrefilter = false } = {}) {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.@@ -743,6 +743,7 @@ export class Renderer67 {// 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();}@@ -1817,7 +1818,7 @@ export class Renderer67 {context.uniform1i(this.liquidUniforms.environmentSpecular, ENVIRONMENT_SPECULAR_UNIT);}this.bindEnvironmentTextures(this.whiteTexture, this.whiteTexture);- if (!this.benchmark && map) this.prepareEnvironment(map);+ if (!this.benchmark && map && !this.deferEnvironmentPrefilter) this.prepareEnvironment(map);}bindEnvironmentTextures(specularTexture, brdfTexture) {@@ -1841,6 +1842,22 @@ export class Renderer67 {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;diff --git a/tests/cooperative-loading.test.js b/tests/cooperative-loading.test.jsnew file mode 100644index 00000000..bbf7981d--- /dev/null+++ b/tests/cooperative-loading.test.js@@ -0,0 +1,173 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { CHUNK_ELEMENTS, createSlicer, forEachChunk } from '../src/cooperative.js';+import { attributeFloats, attributeFloatsInSlices, createAccessorReader } from '../src/gltf-accessors.js';+import { parseRadianceHdr, parseRadianceHdrInSlices } from '../src/hdri.js';++function countingCheckpoint() {+ const checkpoint = async () => { checkpoint.calls++; };+ checkpoint.calls = 0;+ return checkpoint;+}++test('a slicer returns at once inside its slice and yields after it', async () => {+ let yields = 0;+ const original = globalThis.scheduler;+ globalThis.scheduler = { yield: async () => { yields++; } };+ try {+ await createSlicer(60000)();+ assert.equal(yields, 0);+ const alwaysDue = createSlicer(-1);+ await alwaysDue();+ await alwaysDue();+ assert.equal(yields, 2);+ } finally {+ if (original) globalThis.scheduler = original;+ else delete globalThis.scheduler;+ }+});++test('forEachChunk covers every element once and checks the clock after each chunk', async () => {+ const checkpoint = countingCheckpoint();+ const length = CHUNK_ELEMENTS * 2 + 5;+ const seen = new Uint8Array(length);+ await forEachChunk(length, checkpoint, (from, to) => {+ for (let index = from; index < to; index++) seen[index]++;+ });+ assert.ok(seen.every(count => count === 1));+ assert.equal(checkpoint.calls, 3);+});++test('attributeFloatsInSlices matches attributeFloats for normalized and plain data, in several chunks', async () => {+ const count = CHUNK_ELEMENTS + 100;+ const array = new Uint8Array(count * 3).map((_, index) => index % 256);+ for (const normalized of [true, false]) {+ const attribute = { array, count, itemSize: 3, normalized, componentType: 5121 };+ const checkpoint = countingCheckpoint();+ assert.deepEqual(await attributeFloatsInSlices(attribute, checkpoint), attributeFloats(attribute));+ assert.ok(checkpoint.calls > 1);+ }+});++function accessorDocument() {+ return {+ buffers: [{ byteLength: 0 }],+ bufferViews: [+ { buffer: 0, byteOffset: 0, byteLength: 24 },+ { buffer: 0, byteOffset: 24, byteLength: 40, byteStride: 20 },+ ],+ accessors: [+ { bufferView: 0, componentType: 5126, count: 2, type: 'VEC3' },+ { bufferView: 1, componentType: 5126, count: 2, type: 'VEC3' },+ { bufferView: 0, componentType: 5126, count: 6, type: 'SCALAR', sparse: { count: 1, indices: { bufferView: 0, componentType: 5125, byteOffset: 0 }, values: { bufferView: 0, byteOffset: 4 } } },+ { componentType: 5126, count: 3, type: 'VEC2' },+ ],+ };+}++function accessorBytes() {+ const bytes = new Uint8Array(64);+ const view = new DataView(bytes.buffer);+ for (let value = 0; value < 6; value++) view.setFloat32(value * 4, value + 0.5, true);+ view.setUint32(0, 1, true);+ for (let value = 0; value < 5; value++) view.setFloat32(24 + value * 4, 10 + value, true);+ for (let value = 0; value < 5; value++) view.setFloat32(44 + value * 4, 20 + value, true);+ return bytes;+}++test('readAccessorInSlices returns the same accessor as readAccessor for tight, strided, sparse and empty views', async () => {+ const sources = [accessorBytes(), Buffer.from(accessorBytes())];+ for (const source of sources) {+ const reader = createAccessorReader(accessorDocument(), () => source);+ for (let index = 0; index < 4; index++) {+ const expected = reader.readAccessor(index);+ const actual = await reader.readAccessorInSlices(index, countingCheckpoint());+ assert.deepEqual(actual, expected, `accessor ${index}`);+ }+ }+});++test('a tightly packed accessor is copied, not viewed, so changing it leaves the file bytes alone', async () => {+ const source = Buffer.from(accessorBytes());+ const reader = createAccessorReader(accessorDocument(), () => source);+ const before = Buffer.from(source);+ const accessor = await reader.readAccessorInSlices(0, countingCheckpoint());+ accessor.array.fill(0);+ assert.deepEqual(source, before);+});++test('a strided accessor is copied in chunks with a checkpoint between them', async () => {+ const count = CHUNK_ELEMENTS * 2 + 1;+ const source = new Uint8Array(count * 8);+ source.forEach((_, index) => { source[index] = index % 251; });+ const document = {+ buffers: [{ byteLength: source.length }],+ bufferViews: [{ buffer: 0, byteLength: source.length, byteStride: 8 }],+ accessors: [{ bufferView: 0, componentType: 5123, count, type: 'VEC2' }],+ };+ const reader = createAccessorReader(document, () => source);+ const checkpoint = countingCheckpoint();+ assert.deepEqual(await reader.readAccessorInSlices(0, checkpoint), reader.readAccessor(0));+ assert.equal(checkpoint.calls, 3);+});++test('an accessor that overruns its buffer view is refused by the sliced reader too', async () => {+ const document = accessorDocument();+ document.accessors[0].count = 100;+ const reader = createAccessorReader(document, () => accessorBytes());+ await assert.rejects(reader.readAccessorInSlices(0, countingCheckpoint()), /exceeds its buffer view/);+});++function radianceBytes(width, height) {+ const header = new TextEncoder().encode(`#?RADIANCE\nFORMAT=32-bit_rle_rgbe\n\n-Y ${height} +X ${width}\n`);+ const pixels = new Uint8Array(width * height * 4).map((_, index) => (index % 4 === 3 ? 128 + (index % 7) : (index * 13) % 256));+ const bytes = new Uint8Array(header.length + pixels.length);+ bytes.set(header);+ bytes.set(pixels, header.length);+ return bytes;+}++test('parseRadianceHdrInSlices matches parseRadianceHdr and checks the clock once per row', async () => {+ const bytes = radianceBytes(4, 6);+ const checkpoint = countingCheckpoint();+ assert.deepEqual(await parseRadianceHdrInSlices(bytes, checkpoint), parseRadianceHdr(bytes));+ assert.equal(checkpoint.calls, 6);+});++test('parseRadianceHdrInSlices refuses a bad header with the same error', async () => {+ await assert.rejects(parseRadianceHdrInSlices(new TextEncoder().encode('#?RADIANCE\nFORMAT=other\n\n'), countingCheckpoint()), /Unsupported Radiance HDR format/);+ assert.throws(() => parseRadianceHdr(new TextEncoder().encode('#?RADIANCE\nFORMAT=other\n\n')), /Unsupported Radiance HDR format/);+});++function recordingContext(calls) {+ const constants = { FRAMEBUFFER_COMPLETE: 36053, TEXTURE_2D: 3553 };+ return new Proxy({}, {+ get(_, name) {+ if (name in constants) return constants[name];+ if (name === 'getExtension') return () => ({});+ if (name === 'checkFramebufferStatus') return () => constants.FRAMEBUFFER_COMPLETE;+ return (...callArguments) => {+ calls.push(`${String(name)}(${callArguments.filter(value => typeof value === 'number').join(',')})`);+ return {};+ };+ },+ });+}++test('the sliced environment prefilter issues the same GL calls as the one-piece build and checks the clock between steps', async () => {+ const { createEnvironmentMap, createEnvironmentResources, createEnvironmentResourcesInSlices } = await import('../src/environment.js');+ const width = 64;+ const height = 32;+ const data = new Float32Array(width * height * 3).map((_, index) => (index % 11) / 3);+ const map = createEnvironmentMap({ width, height, data });+ const programs = { compileProgram: () => ({}), fullscreenVertex: '' };+ const wholeCalls = [];+ const slicedCalls = [];+ const whole = createEnvironmentResources(recordingContext(wholeCalls), map, programs);+ const checkpoint = countingCheckpoint();+ const sliced = await createEnvironmentResourcesInSlices(recordingContext(slicedCalls), map, programs, checkpoint);+ assert.deepEqual(slicedCalls, wholeCalls);+ assert.deepEqual(sliced.irradiance, whole.irradiance);+ assert.equal(sliced.levelCount, whole.levelCount);+ assert.ok(checkpoint.calls >= 3 + whole.levelCount, `expected a checkpoint per step, got ${checkpoint.calls}`);+});