3D engine that AI agents drive
Group only appended parts in sliced replaceParts and upload large textures in bands (#779)
Nguyen Xuan Ancb2e56a71941
diff --git a/changes/779-incremental-grouping.md b/changes/779-incremental-grouping.mdnew file mode 100644index 00000000..382dd832--- /dev/null+++ b/changes/779-incremental-grouping.md@@ -0,0 +1,2 @@+- `replaceParts(parts, { retainedUnchanged: true })` groups only the parts appended since the last call when a world grows by whole geometries, so loading a large world in slices no longer regroups the whole prefix on every call (#779)+- An unflipped texture image over 1,048,576 pixels uploads in row bands of at most that size instead of one `texImage2D`; the pixels are identical (#779)diff --git a/docs/gltf.md b/docs/gltf.mdindex a270050a..5c29cf4b 100644--- a/docs/gltf.md+++ b/docs/gltf.md@@ -115,6 +115,8 @@ renderer.replaceParts(asset.parts);`programsReady()` polls `KHR_parallel_shader_compile` and then finishes construction; a renderer made with `deferProgramLink` must not render before it resolves.`await renderer.prepareFrame(frame)` is the matching last step before a hidden renderer is shown: it draws `frame` once without freezing the page for the programs a first draw links (the post pass of a fog or sky frame, liquids, ambient occlusion, the reversed-depth copy). A draw that meets a program the driver is still building stops, the page waits in short timers, and the draw runs again until one completes; it resolves `true`. After `timeoutMilliseconds` (6000 by default) it draws the frame in one block and resolves `false`, so a slow driver costs a stall, never a hang. Start the next scene's `prepareFrame` while the current scene plays and begin the fade when it resolves.Starting on `shaderFeatureRepresentatives` matters: a scene whose first parts lack a feature recompiles the program inside `replaceParts`, which blocks again.+When a world arrives in growing prefixes that end on a geometry boundary, call `renderer.replaceParts(prefix, { retainedUnchanged: true })`: only the parts appended since the last call are grouped and checked, and the batches built before are kept as they are. A prefix that changes, reorders or removes earlier parts, or an appended part that shares a geometry with them, groups the whole list as before. Measured on 100,000 parts of 2,000 geometries in 20 prefixes, the grouping step took 1.5 to 2.9 s in total and 134 to 303 ms at worst without it, and 0.16 to 0.30 s in total and 11 to 23 ms at worst with it.+A texture image over 1,048,576 pixels (more than 4 MiB of RGBA) that is not flipped on upload goes to the GPU in row bands of at most that size, so no single `texImage2D` stalls the driver; the result equals one upload. A flipped image stays one upload.## Animation and ownershipdiff --git a/src/renderer.js b/src/renderer.jsindex 8c305be8..cd27410e 100644--- a/src/renderer.js+++ b/src/renderer.js@@ -45,6 +45,28 @@ const MAP_FLAGS = ['hasBaseMap', 'hasNormalMap', 'hasMetallicRoughnessMap', 'hasconst 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;+// One texImage2D of a large image stalls the driver for tens of milliseconds, so an image over this many pixels goes up in bands.+export const MAX_UPLOAD_PIXELS = 1 << 20;++/** Uploads `image` to the bound TEXTURE_2D. An unflipped image over MAX_UPLOAD_PIXELS goes up in row bands of at most that size; the pixels are the same. */+export function uploadImage(context, image, width, height, internalFormat, flipY) {+ // Browsers disagree on whether a flip applies before or after the skipped rows, so a flipped image stays one upload.+ if (flipY || width * height <= MAX_UPLOAD_PIXELS) {+ context.texImage2D(context.TEXTURE_2D, 0, internalFormat, context.RGBA, context.UNSIGNED_BYTE, image);+ return;+ }+ context.texImage2D(context.TEXTURE_2D, 0, internalFormat, width, height, 0, context.RGBA, context.UNSIGNED_BYTE, null);+ const bandRows = Math.max(1, Math.floor(MAX_UPLOAD_PIXELS / width));+ try {+ for (let firstRow = 0; firstRow < height; firstRow += bandRows) {+ const rows = Math.min(bandRows, height - firstRow);+ context.pixelStorei(context.UNPACK_SKIP_ROWS, firstRow);+ context.texSubImage2D(context.TEXTURE_2D, 0, 0, firstRow, width, rows, context.RGBA, context.UNSIGNED_BYTE, image);+ }+ } finally {+ context.pixelStorei(context.UNPACK_SKIP_ROWS, 0);+ }+}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.@@ -499,6 +521,25 @@ export function groupParts(parts, batching = true) {return batches;}+/**+ * Groups a world that grows by whole geometries, as replaceParts({ retainedUnchanged: true }) receives it in slices.+ * When `parts` starts with the parts of `previous` and no appended part shares a geometry with them, the earlier batches+ * are exactly what groupParts would build again, so only the appended parts are grouped and validated.+ * Anything else groups the whole list. Returns the batches and the state to pass on the next call.+ */+export function groupPartsIncrementally(previous, parts, batching = true) {+ const startsWithPrevious = Boolean(previous) && batching && previous.parts.length <= parts.length &&+ previous.parts.every((part, index) => part === parts[index]);+ const appended = startsWithPrevious ? parts.slice(previous.parts.length) : null;+ if (appended && appended.every(part => !previous.geometries.has(part.geometry))) {+ for (const part of appended) previous.geometries.add(part.geometry);+ const batches = [...previous.batches, ...groupParts(appended, batching)];+ return { batches, state: { parts: parts.slice(), geometries: previous.geometries, batches } };+ }+ const batches = groupParts(parts, batching);+ return { batches, state: { parts: parts.slice(), geometries: new Set(parts.map(part => part.geometry)), batches } };+}+export function textureDescriptorInfo(map, maximumSize = Infinity) {const width = map.image?.naturalWidth ?? map.image?.width;const height = map.image?.naturalHeight ?? map.image?.height;@@ -982,7 +1023,7 @@ export class Renderer67 {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);+ else uploadImage(context, map.image, info.width, info.height, map.colorSpace === 'linear' ? context.RGBA8 : context.SRGB8_ALPHA8, map.flipY ?? false);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);@@ -1276,7 +1317,16 @@ export class Renderer67 {const renderParts = this.groundPart ? [...parts, this.groundPart] : parts;this.fitParts = renderParts;this.fitBounds = undefined;- const groups = groupParts(renderParts, this.batching);+ let groups;+ if (retainedUnchanged) {+ // A world that grows in slices groups only the slice that arrived; the floor is one more batch of its own geometry.+ const grouped = groupPartsIncrementally(this.incrementalGrouping, parts, this.batching);+ this.incrementalGrouping = grouped.state;+ groups = this.groundPart ? [...grouped.batches, ...groupParts([this.groundPart], this.batching)] : grouped.batches;+ } else {+ this.incrementalGrouping = null;+ groups = groupParts(renderParts, this.batching);+ }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) {diff --git a/tests/incremental-grouping.test.js b/tests/incremental-grouping.test.jsnew file mode 100644index 00000000..bc9e3704--- /dev/null+++ b/tests/incremental-grouping.test.js@@ -0,0 +1,54 @@+import assert from 'node:assert/strict';+import test from 'node:test';+import { groupParts, groupPartsIncrementally } from '../src/renderer.js';++const identity = () => new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);+const makeGeometry = () => ({+ positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),+ indices: new Uint32Array([0, 1, 2]),+});+const materials = [0, 1, 2].map(index => ({ color: [index / 3, 0.5, 0.5], metallic: 0, roughness: 0.5, emission: 0 }));+const geometries = Array.from({ length: 6 }, makeGeometry);+const makePart = (index, geometry) => ({ name: `part ${index}`, geometry, matrix: identity(), material: materials[index % materials.length] });+const worldParts = Array.from({ length: 30 }, (_, index) => makePart(index, geometries[Math.floor(index / 5)]));++const sameBatches = (left, right) => left.length === right.length && left.every((batch, index) => batch.length === right[index].length && batch.every((part, position) => part === right[index][position]));++test('growing a world by whole geometries groups exactly as groupParts does', () => {+ let state = null;+ for (let end = 5; end <= worldParts.length; end += 5) {+ const prefix = worldParts.slice(0, end);+ const grouped = groupPartsIncrementally(state, prefix);+ assert.ok(sameBatches(grouped.batches, groupParts(prefix)), `prefix of ${end} parts`);+ state = grouped.state;+ }+});++test('a slice that shares a geometry with earlier parts falls back to grouping everything', () => {+ const first = worldParts.slice(0, 10);+ const grouped = groupPartsIncrementally(null, first);+ const sharing = [...first, makePart(100, geometries[0])];+ const next = groupPartsIncrementally(grouped.state, sharing);+ assert.ok(sameBatches(next.batches, groupParts(sharing)));+});++test('removed or reordered parts fall back to grouping everything', () => {+ const grouped = groupPartsIncrementally(null, worldParts.slice(0, 15));+ const reordered = [worldParts[1], worldParts[0], ...worldParts.slice(2, 20)];+ assert.ok(sameBatches(groupPartsIncrementally(grouped.state, reordered).batches, groupParts(reordered)));+ const shorter = worldParts.slice(0, 5);+ assert.ok(sameBatches(groupPartsIncrementally(grouped.state, shorter).batches, groupParts(shorter)));+});++test('without batching every part keeps its own group', () => {+ const grouped = groupPartsIncrementally(null, worldParts.slice(0, 10), false);+ const next = groupPartsIncrementally(grouped.state, worldParts.slice(0, 20), false);+ assert.ok(sameBatches(next.batches, groupParts(worldParts.slice(0, 20), false)));+});++test('an invalid appended part still throws', () => {+ const grouped = groupPartsIncrementally(null, worldParts.slice(0, 5));+ const broken = { ...makePart(200, geometries[5]), matrix: new Float32Array(3) };+ assert.throws(() => groupPartsIncrementally(grouped.state, [...worldParts.slice(0, 5), broken]));+});diff --git a/tests/texture-upload-bands.test.js b/tests/texture-upload-bands.test.jsnew file mode 100644index 00000000..49e8a320--- /dev/null+++ b/tests/texture-upload-bands.test.js@@ -0,0 +1,152 @@+// A large texture goes up in bounded row bands, and the pixels equal a single upload (issue 779).+// The pixel check runs in headless Chrome (SwiftShader) from the Vite dev server and skips when Chrome cannot start.+import test from 'node:test';+import assert from 'node:assert/strict';+import { spawn } from 'node:child_process';+import { freePort } from './helpers/free-port.js';+import { MAX_UPLOAD_PIXELS, uploadImage } from '../src/renderer.js';++function recordingContext() {+ const calls = [];+ const context = {+ TEXTURE_2D: 3553, RGBA: 6408, UNSIGNED_BYTE: 5121, RGBA8: 32856, UNPACK_SKIP_ROWS: 3314,+ texImage2D: (...args) => calls.push(['texImage2D', ...args]),+ texSubImage2D: (...args) => calls.push(['texSubImage2D', ...args]),+ pixelStorei: (name, value) => calls.push(['pixelStorei', name, value]),+ };+ return { context, calls };+}++test('an image within the limit goes up in one call', () => {+ const { context, calls } = recordingContext();+ uploadImage(context, {}, 1024, 1024, context.RGBA8, false);+ assert.equal(calls.length, 1);+ assert.equal(calls[0][0], 'texImage2D');+});++test('a larger image goes up in bands that each stay within the limit and cover every row once', () => {+ const { context, calls } = recordingContext();+ const width = 3000;+ const height = 1500;+ uploadImage(context, {}, width, height, context.RGBA8, false);+ const bands = calls.filter(call => call[0] === 'texSubImage2D');+ assert.ok(bands.length > 1);+ let nextRow = 0;+ for (const [, , , , destinationRow, bandWidth, rows] of bands) {+ assert.equal(destinationRow, nextRow);+ assert.equal(bandWidth, width);+ assert.ok(bandWidth * rows <= MAX_UPLOAD_PIXELS);+ nextRow += rows;+ }+ assert.equal(nextRow, height);+ assert.equal(calls.at(-1)[2], 0, 'the skip-rows state is restored');+});++test('a flipped image stays one upload', () => {+ const { context, calls } = recordingContext();+ uploadImage(context, {}, 2000, 1000, context.RGBA8, true);+ assert.deepEqual(calls.map(call => call[0]), ['texImage2D']);+});++async function startServer(port) {+ const server = spawn(process.execPath, ['node_modules/vite/bin/vite.js', '--host', '127.0.0.1', '--port', String(port), '--strictPort'], { windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });+ await new Promise((resolve, reject) => {+ const timeout = setTimeout(() => reject(new Error('The dev server did not start.')), 30000);+ server.stdout.on('data', (data) => {+ if (/ready in/.test(data.toString())) {+ clearTimeout(timeout);+ resolve();+ }+ });+ server.on('exit', (code) => {+ clearTimeout(timeout);+ reject(new Error(`The dev server exited ${code}.`));+ });+ });+ return server;+}++async function differingBytes(page) {+ const task = async () => {+ const { box } = await import('/src/geometry.js');+ const { Renderer67, MAX_UPLOAD_PIXELS: limit } = await import('/src/renderer.js');+ const canvas = document.createElement('canvas');+ canvas.width = 64;+ canvas.height = 64;+ document.body.append(canvas);+ const part = { name: 'p', geometry: box(0, 1), matrix: new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]), material: { tag: 'surface', color: [1, 1, 1], metallic: 0, roughness: 0.5, emission: 0 } };+ const renderer = new Renderer67(canvas, [part], { ground: false, samples: 1, pixelRatio: 1 });+ const gl = renderer.context;+ const width = 1280;+ const height = Math.ceil(limit / width) * 2 + 7;+ const source = document.createElement('canvas');+ source.width = width;+ source.height = height;+ const sourceContext = source.getContext('2d');+ const imageData = sourceContext.createImageData(width, height);+ for (let row = 0; row < height; row++) {+ for (let column = 0; column < width; column++) {+ const offset = (row * width + column) * 4;+ imageData.data.set([column % 251, row % 241, (column + row) % 239, 255], offset);+ }+ }+ sourceContext.putImageData(imageData, 0, 0);+ const read = (texture) => {+ const framebuffer = gl.createFramebuffer();+ gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);+ gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);+ const pixels = new Uint8Array(width * height * 4);+ gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);+ gl.bindFramebuffer(gl.FRAMEBUFFER, null);+ gl.deleteFramebuffer(framebuffer);+ return pixels;+ };+ const results = {};+ for (const flipY of [false, true]) {+ const banded = renderer.createTexture({ image: source, colorSpace: 'linear', flipY, minFilter: 9729 });+ const whole = gl.createTexture();+ gl.bindTexture(gl.TEXTURE_2D, whole);+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, flipY);+ gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, gl.RGBA, gl.UNSIGNED_BYTE, source);+ gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);+ const bandedPixels = read(banded);+ const wholePixels = read(whole);+ let differing = 0;+ for (let index = 0; index < bandedPixels.length; index++) if (bandedPixels[index] !== wholePixels[index]) differing++;+ results[flipY ? 'flipped' : 'upright'] = { differing, bytes: bandedPixels.length, error: gl.getError() };+ }+ return results;+ };+ return page.evaluate(task);+}++test('banded upload gives the same pixels as one upload, upright, and flipped stays whole', async (context) => {+ let chromium;+ try {+ ({ chromium } = await import('playwright'));+ } catch {+ context.skip('playwright is not installed');+ return;+ }+ const port = await freePort();+ const server = await startServer(port);+ let browser;+ try {+ try {+ browser = await chromium.launch({ headless: true, args: ['--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--enable-webgl', '--ignore-gpu-blocklist'] });+ } catch (error) {+ context.skip(`Chrome did not start: ${error.message.split('\n')[0]}`);+ return;+ }+ const page = await browser.newPage({ viewport: { width: 128, height: 128 } });+ await page.goto(`http://127.0.0.1:${port}/`);+ const results = await differingBytes(page);+ for (const [name, result] of Object.entries(results)) {+ assert.equal(result.error, 0, `${name} upload raised a GL error`);+ assert.equal(result.differing, 0, `${name}: ${result.differing} of ${result.bytes} bytes differ`);+ }+ } finally {+ await browser?.close();+ server.kill();+ }+});