Skip to content

armgit / 67.js

Public Imported from GitHub
0

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.md
new file mode 100644
index 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.md
index 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 ownership
diff --git a/src/renderer.js b/src/renderer.js
index 8c305be8..cd27410e 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -45,6 +45,28 @@ const MAP_FLAGS = ['hasBaseMap', 'hasNormalMap', 'hasMetallicRoughnessMap', 'has
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;
+// 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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();
+ }
+});