Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add renderer.updateTexture for live pixels (part of #339)

Nguyen Xuan Anfd4002804ecc
diff --git a/changes/339.md b/changes/339.md
new file mode 100644
index 00000000..22e9f0e8
--- /dev/null
+++ b/changes/339.md
@@ -0,0 +1 @@
+- Add `renderer.updateTexture(descriptor, { image?, region? })` in the `texture-update` addon (issue #339). It pushes new pixels into an uploaded texture, such as a live canvas, a video frame or a simulation tile, with `texSubImage2D`. It keeps the sRGB or linear storage and `flipY` of the first upload, regenerates mipmaps and throws clear errors for a wrong size, a region outside the texture, a compressed texture or a descriptor that was never uploaded. The core entry grows by 50 bytes gzip. Recipes and MCP tools have no pixel input yet, so they are unchanged.
diff --git a/docs/guide.md b/docs/guide.md
index da9a5a2b..51ca5f92 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -341,6 +341,8 @@ Tags select specialized behavior: `armor` allows studio finish overrides. `floor
`render(frame)` draws synchronously. `resize()` replans targets after CSS size or `pixelRatio` changes. `updateParts(parts, { shadows: true })` uploads changed matrices and materials using retained buffers. It does not add new part, geometry or texture identities.
+`updateTexture(descriptor, { image?, region? })` pushes new pixels into a texture the renderer already uploaded, such as a live canvas or a simulation. Import `@codepawlhq/67js/addons/texture-update` first. `docs/material-maps.md` has the options.
+
Construct a new renderer for a new graph. `dispose()` releases owned resources.
Read `memoryPlan` for actual width, height, estimatedBytes and reduced status. `capabilities` for HDR and MSAA negotiation. `triangles`, `batches.length` and `cpuMilliseconds` for diagnostics. CPU submission time is not GPU frame time.
diff --git a/docs/material-maps.md b/docs/material-maps.md
index d2d908ce..0482c75d 100644
--- a/docs/material-maps.md
+++ b/docs/material-maps.md
@@ -59,12 +59,33 @@ A batch groups geometry identity, all five map identities, `normalScale` values,
The renderer uses batch uniforms for scale and strength because its instance attributes already occupy 16 vertex locations.
Changing any of these batch fields requires a new renderer. `updateParts()` rejects changes before uploading instance data.
Color, metallic, roughness, emission, emissive color, and transforms retain their existing update behavior.
-Descriptors and decoded image contents must remain unchanged while a renderer uses them.
+Descriptors must remain unchanged while a renderer uses them. Image pixels change only through `updateTexture`.
Two API shapes were considered. A nested channel registry could carry arbitrary channel packing and transforms.
Named per-channel descriptors reuse the existing `material.map` contract and make channel semantics explicit.
The current API uses named descriptors. Arbitrary channel routing and texture transforms remain unsupported.
+## Updating pixels
+
+`renderer.updateTexture(descriptor, update)` replaces the pixels of a texture the renderer has already uploaded. It needs `import '@codepawlhq/67js/addons/texture-update'`, so scenes that never update a texture do not carry the code.
+
+```js
+import '@codepawlhq/67js/addons/texture-update';
+
+renderer.updateTexture(descriptor);
+renderer.updateTexture(descriptor, { image: video });
+renderer.updateTexture(descriptor, { region: { x: 64, y: 32, width: 16, height: 16, data: rgbaBytes } });
+```
+
+Without `update`, the descriptor image uploads again. This suits a canvas that you draw on.
+`image` replaces every pixel. It must have the same width and height as the uploaded texture.
+`region` replaces one rectangle. `data` holds `width * height * 4` RGBA bytes as a `Uint8Array` or `Uint8ClampedArray`, top row first. `x` and `y` count from the top left of the image, and `flipY` is handled for you. Give `image` or `region`, not both.
+
+Colour space, `flipY` and the unpack state follow the first upload. An `srgb` descriptor keeps sRGB storage, premultiplied alpha stays off, and the previous WebGL unpack state returns afterwards. A texture with mipmaps regenerates all of them after the upload, so a small region still costs one mipmap pass.
+
+The size cannot change, because the texture memory is planned at construction. Compressed textures reject updates, since their mip levels come from the file. A descriptor that was never uploaded, a region outside the texture, or a data length that does not match throws an error that names the problem.
+Update between two `render()` calls. The change shows on the next frame.
+
## glTF import and lifetime
`parseGltf()` and `loadGltf()` import base color, normal, metallic/roughness, occlusion, and emissive textures.
diff --git a/package.json b/package.json
index aefc8f21..7f33caa2 100644
--- a/package.json
+++ b/package.json
@@ -96,6 +96,7 @@
"./addons/light-linking": "./build/light-linking.js",
"./addons/cascaded-shadows": "./build/cascaded-shadows.js",
"./addons/gaussian-splats": "./build/gaussian-splats.js",
+ "./addons/texture-update": "./build/texture-update.js",
"./package.json": "./package.json"
},
"scripts": {
@@ -142,6 +143,7 @@
"smoke:character": "node scripts/smoke-character.mjs",
"smoke:modeling": "node scripts/smoke-modeling.mjs",
"smoke:material-maps": "node scripts/smoke-material-maps.mjs",
+ "smoke:texture-update": "node scripts/smoke-texture-update.mjs",
"benchmark:mesh-query": "node scripts/benchmark-mesh-query.mjs",
"benchmark:update-parts": "node scripts/benchmark-update-parts.mjs",
"smoke:imported-topology": "node scripts/smoke-imported-topology.mjs",
diff --git a/scripts/smoke-texture-update.mjs b/scripts/smoke-texture-update.mjs
new file mode 100644
index 00000000..d4af5446
--- /dev/null
+++ b/scripts/smoke-texture-update.mjs
@@ -0,0 +1,137 @@
+import assert from 'node:assert/strict';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { constants, setPriority } from 'node:os';
+import { createServer } from 'vite';
+import { chromium } from 'playwright';
+
+// Renders a quad textured with four coloured quadrants, pushes new pixels into one quadrant, renders again and reads the pixels back.
+// The region update must match uploading the finished picture whole. Runs on SwiftShader unless "gpu" is given;
+// start a GPU run through `bash ~/.agents/tools/gpu-lock.sh`.
+setPriority(0, constants.priority.PRIORITY_BELOW_NORMAL);
+const backend = process.argv[2] ?? 'cpu';
+assert.ok(['cpu', 'gpu'].includes(backend));
+await mkdir('artifacts', { recursive: true });
+const harness = `<!doctype html><html><head><style>html,body{margin:0}</style></head><body><script type="module">
+import {Renderer67} from '/src/renderer.js';
+import '/src/texture-update.js';
+const SIZE = 64;
+const HALF = SIZE / 2;
+const quad = {
+ positions: new Float32Array([-1,-1,0, 1,-1,0, 1,1,0, -1,1,0]),
+ normals: new Float32Array([0,0,1, 0,0,1, 0,0,1, 0,0,1]),
+ uvs: new Float32Array([0,0, 1,0, 1,1, 0,1]),
+ indices: new Uint32Array([0,1,2, 0,2,3]),
+};
+// Image quadrants, row 0 first: top left red, top right blue, bottom left grey, bottom right white. topLeft replaces the first one.
+function quadrantImage(topLeft) {
+ const data = new Uint8ClampedArray(SIZE * SIZE * 4);
+ for (let row = 0; row < SIZE; row++) {
+ for (let column = 0; column < SIZE; column++) {
+ const top = row < HALF;
+ const left = column < HALF;
+ const color = top ? (left ? topLeft : [0, 0, 255]) : (left ? [128, 128, 128] : [255, 255, 255]);
+ data.set([...color, 255], (row * SIZE + column) * 4);
+ }
+ }
+ return new ImageData(data, SIZE, SIZE);
+}
+function letter([red, green, blue]) {
+ if (green > red + 60 && green > blue + 60) return 'G';
+ if (red > green + 60 && red > blue + 60) return 'R';
+ if (blue > red + 60 && blue > green + 60) return 'B';
+ return red > 200 && green > 200 && blue > 200 ? 'W' : red > 60 ? 'g' : '.';
+}
+function create(descriptor) {
+ const canvas = document.createElement('canvas');
+ canvas.width = canvas.height = 128;
+ document.body.append(canvas);
+ const part = { name: 'quad', geometry: quad, material: { tag: 'gltf', color: [1, 1, 1], metallic: 0, roughness: 1, emission: 0, emissiveColor: [0, 0, 0], map: descriptor },
+ matrix: new Float32Array([1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]) };
+ const renderer = new Renderer67(canvas, [part], { ground: false, shadows: false, samples: 1, pixelRatio: 1, memoryBudgetMiB: 64 });
+ const camera = { eye: [0, 0, 6], target: [0, 0, 0] };
+ const context = renderer.context;
+ const read = () => {
+ renderer.render(camera);
+ const pixels = new Uint8Array(canvas.width * canvas.height * 4);
+ context.readPixels(0, 0, canvas.width, canvas.height, context.RGBA, context.UNSIGNED_BYTE, pixels);
+ let checksum = 2166136261;
+ for (const value of pixels) checksum = Math.imul(checksum ^ value, 16777619) >>> 0;
+ // WebGL rows start at the bottom, so the grid walks rows downward from the top of the screen. Cells are 8 pixels.
+ const rows = [];
+ for (let row = 15; row >= 0; row--) {
+ let line = '';
+ for (let column = 0; column < 16; column++) {
+ const offset = ((row * 8 + 4) * canvas.width + column * 8 + 4) * 4;
+ line += letter(pixels.slice(offset, offset + 3));
+ }
+ rows.push(line);
+ }
+ return { checksum, grid: rows.join('|') };
+ };
+ return { renderer, read, context };
+}
+const greenRegion = { x: 0, y: 0, width: HALF, height: HALF, data: new Uint8Array(HALF * HALF * 4).map((value, index) => index % 4 === 1 || index % 4 === 3 ? 255 : 0) };
+const results = {};
+for (const flipY of [false, true]) {
+ for (const colorSpace of ['linear', 'srgb']) {
+ const descriptor = { image: quadrantImage([255, 0, 0]), colorSpace, flipY };
+ const { renderer, read, context } = create(descriptor);
+ // Drawing the hand-built quad raises INVALID_OPERATION on its own (not from the update), so errors are drained before each update and read right after it.
+ const updateErrors = [];
+ const update = argument => {
+ while (context.getError() !== 0);
+ renderer.updateTexture(descriptor, argument);
+ updateErrors.push(context.getError());
+ };
+ const before = read();
+ update({ region: greenRegion });
+ const afterRegion = read();
+ const baked = create({ image: quadrantImage([0, 255, 0]), colorSpace, flipY });
+ const reference = baked.read();
+ baked.renderer.dispose();
+ update({ image: quadrantImage([0, 255, 0]) });
+ const afterImage = read();
+ descriptor.image.data.set(quadrantImage([0, 0, 255]).data);
+ update();
+ const afterSameImage = read();
+ results[flipY + '-' + colorSpace] = { before, afterRegion, reference, afterImage, afterSameImage, updateErrors };
+ renderer.dispose();
+ }
+}
+window.__textureUpdateProof = results;
+</script></body></html>`;
+await writeFile('artifacts/texture-update-harness.html', harness);
+const server = await createServer({ server: { host: '127.0.0.1', port: 0 }, logLevel: 'silent' });
+let browser;
+try {
+ await server.listen();
+ const args = ['--enable-webgl', '--ignore-gpu-blocklist', '--disable-renderer-backgrounding'];
+ if (backend === 'cpu') args.push('--use-angle=swiftshader', '--enable-unsafe-swiftshader');
+ browser = await chromium.launch({ executablePath: 'C:/Program Files/Google/Chrome/Application/chrome.exe', headless: true, args });
+ const page = await browser.newPage({ viewport: { width: 400, height: 400 } });
+ const errors = [];
+ page.on('pageerror', error => errors.push(error.message));
+ page.on('console', message => { if (message.type() === 'error' && !message.text().includes('404')) errors.push(message.text()); });
+ await page.goto(`http://127.0.0.1:${server.httpServer.address().port}/artifacts/texture-update-harness.html`);
+ await page.waitForFunction(() => window.__textureUpdateProof, null, { timeout: 60000 });
+ const results = await page.evaluate(() => window.__textureUpdateProof);
+ await writeFile(`artifacts/texture-update-${backend}.json`, JSON.stringify(results, null, 2));
+ assert.deepEqual(errors, []);
+ const count = (grid, letter) => [...grid].filter(character => character === letter).length;
+ for (const [name, result] of Object.entries(results)) {
+ assert.deepEqual(result.updateErrors, [0, 0, 0], `${name} update raised WebGL errors`);
+ assert.ok(count(result.before.grid, 'R') > 10, `${name} starts with a red quadrant`);
+ assert.equal(count(result.before.grid, 'G'), 0, `${name} starts without green`);
+ // The red quadrant becomes green and the other quadrants stay put.
+ assert.equal(count(result.afterRegion.grid, 'R'), 0, `${name} region update left red behind`);
+ assert.equal(count(result.afterRegion.grid, 'G'), count(result.before.grid, 'R'), `${name} region update changed the wrong area`);
+ assert.equal(count(result.afterRegion.grid, 'B'), count(result.before.grid, 'B'), `${name} region update touched another quadrant`);
+ assert.equal(result.afterRegion.checksum, result.reference.checksum, `${name} region update differs from uploading the same picture whole`);
+ assert.equal(result.afterImage.checksum, result.reference.checksum, `${name} whole image update differs from uploading the same picture first`);
+ assert.equal(count(result.afterSameImage.grid, 'B'), count(result.before.grid, 'B') + count(result.before.grid, 'R'), `${name} re-upload of the descriptor image`);
+ }
+ console.log(JSON.stringify(Object.fromEntries(Object.entries(results).map(([name, result]) => [name, result.afterRegion.grid]))));
+} finally {
+ await browser?.close();
+ await server.close();
+}
diff --git a/src/renderer.js b/src/renderer.js
index a12bcbc1..42c87cde 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -18,7 +18,7 @@ import { MaterialSnapshot } from './material-snapshot.js';
import { fittedFogDensity } from './fog-fit.js';
import { InstanceSelection, extractFrustumPlanes, geometryBoundingSphere, selectInstances } from './render-culling.js';
import { resolveShadowLight, shadowBiasPerSlope } from './shadow-light.js';
-import { requireDeformationSupport } from './shader-registry.js';
+import { requireDeformationSupport, textureUpdateSupport } from './shader-registry.js';
const SHADOW_MAP_SIZE = 2048;
const MATERIAL_TAGS = { armor: 1, floor: 2, water: 3, foliage: 4, terrain: 5, grass: 7, fire: 8, smoke: 9, unlit: 10, liquid: 11, foam: 12 };
@@ -788,6 +788,13 @@ export class Renderer67 {
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/67js/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) {
diff --git a/src/shader-registry.js b/src/shader-registry.js
index 1c660c38..d5b9bc2e 100644
--- a/src/shader-registry.js
+++ b/src/shader-registry.js
@@ -15,6 +15,9 @@ export const layerTextureSupport = {};
// view-transform-shader.js sets apply(source, kind, viewTransform, hasLook), bindLook(renderer, program) and dispose(renderer).
export const viewTransformShader = {};
+// texture-update.js sets update(renderer, descriptor, update): the body of renderer.updateTexture.
+export const textureUpdateSupport = {};
+
// splat-shader.js sets the JavaScript half of the splat ground material: validate, textureBytes, resolveSize,
// packParameters and buildPixels. The renderer calls them only for a material with layers.
const splatSupport = {};
diff --git a/src/texture-update.js b/src/texture-update.js
new file mode 100644
index 00000000..24fdcfb8
--- /dev/null
+++ b/src/texture-update.js
@@ -0,0 +1,63 @@
+// Pushes new pixels into a texture that createTexture() already uploaded (live canvas, video, simulation).
+// Importing this module gives the renderer its updateTexture code (the pattern of splat-shader.js).
+// The validation and region math need no GL context, so tests can reach them directly.
+import { textureDescriptorInfo } from './renderer.js';
+import { textureUpdateSupport } from './shader-registry.js';
+
+// Bytes in a region are RGBA, top row first, exactly as the descriptor image would supply them.
+export function validateTextureRegion(region, width, height) {
+ const { x, y, width: regionWidth, height: regionHeight, data } = region ?? {};
+ for (const [name, value] of Object.entries({ x, y, width: regionWidth, height: regionHeight })) {
+ if (!Number.isInteger(value)) throw new TypeError(`updateTexture region.${name} must be an integer.`);
+ }
+ if (x < 0 || y < 0 || regionWidth <= 0 || regionHeight <= 0 || x + regionWidth > width || y + regionHeight > height) {
+ throw new RangeError(`updateTexture region ${regionWidth}x${regionHeight} at ${x},${y} does not fit the ${width}x${height} texture.`);
+ }
+ if (!(data instanceof Uint8Array || data instanceof Uint8ClampedArray)) throw new TypeError('updateTexture region.data must be a Uint8Array or Uint8ClampedArray of RGBA bytes.');
+ const expected = regionWidth * regionHeight * 4;
+ if (data.length !== expected) throw new RangeError(`updateTexture region.data has ${data.length} bytes, expected ${expected} (${regionWidth}x${regionHeight} RGBA).`);
+}
+
+// With flipY the first upload stores image row 0 at the top texture row, and WebGL flips a sub-rectangle inside itself,
+// so the rectangle moves to the mirrored rows and the region stays in image coordinates.
+export function textureRegionOffset(region, textureHeight, flipY) {
+ return { x: region.x, y: flipY ? textureHeight - region.y - region.height : region.y };
+}
+
+export function updateRendererTexture(renderer, descriptor, update) {
+ const context = renderer.context;
+ if (!descriptor || !renderer.textures.has(descriptor)) throw new Error('updateTexture needs a descriptor this renderer already uploaded with a part or createTexture(descriptor).');
+ if (descriptor.image.compressed) throw new Error('Compressed textures cannot be updated because their mip levels come from the file. Use an RGBA image.');
+ const info = textureDescriptorInfo(descriptor, context.getParameter(context.MAX_TEXTURE_SIZE));
+ const { image, region } = update;
+ if (image && region) throw new Error('updateTexture takes image or region, not both.');
+ if (image && ((image.naturalWidth ?? image.width) !== info.width || (image.naturalHeight ?? image.height) !== info.height)) {
+ throw new RangeError(`updateTexture image must be ${info.width}x${info.height} like the uploaded texture. Create a new renderer to change the size.`);
+ }
+ if (region) validateTextureRegion(region, info.width, info.height);
+ const flipY = descriptor.flipY ?? false;
+ const previousFlip = context.getParameter(context.UNPACK_FLIP_Y_WEBGL);
+ const previousPremultiply = context.getParameter(context.UNPACK_PREMULTIPLY_ALPHA_WEBGL);
+ const previousColorSpace = context.getParameter(context.UNPACK_COLORSPACE_CONVERSION_WEBGL);
+ const previousBinding = context.getParameter(context.TEXTURE_BINDING_2D);
+ try {
+ context.bindTexture(context.TEXTURE_2D, renderer.textures.get(descriptor));
+ context.pixelStorei(context.UNPACK_FLIP_Y_WEBGL, flipY);
+ context.pixelStorei(context.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+ context.pixelStorei(context.UNPACK_COLORSPACE_CONVERSION_WEBGL, context.NONE);
+ if (region) {
+ const offset = textureRegionOffset(region, info.height, flipY);
+ context.texSubImage2D(context.TEXTURE_2D, 0, offset.x, offset.y, region.width, region.height, context.RGBA, context.UNSIGNED_BYTE, region.data);
+ } else {
+ context.texSubImage2D(context.TEXTURE_2D, 0, 0, 0, context.RGBA, context.UNSIGNED_BYTE, image ?? descriptor.image);
+ }
+ if (info.mipmaps) context.generateMipmap(context.TEXTURE_2D);
+ } finally {
+ context.pixelStorei(context.UNPACK_FLIP_Y_WEBGL, previousFlip);
+ context.pixelStorei(context.UNPACK_PREMULTIPLY_ALPHA_WEBGL, previousPremultiply);
+ context.pixelStorei(context.UNPACK_COLORSPACE_CONVERSION_WEBGL, previousColorSpace);
+ context.bindTexture(context.TEXTURE_2D, previousBinding);
+ }
+}
+
+textureUpdateSupport.update = updateRendererTexture;
diff --git a/tests/texture-update.test.js b/tests/texture-update.test.js
new file mode 100644
index 00000000..68f21e8c
--- /dev/null
+++ b/tests/texture-update.test.js
@@ -0,0 +1,102 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { Renderer67 } from '../src/renderer.js';
+import { textureRegionOffset, validateTextureRegion } from '../src/texture-update.js';
+
+const MAX_TEXTURE_SIZE = 4096;
+
+/** A WebGL2 stand-in that records texture calls and unpack state. */
+function fakeRenderer(descriptor) {
+ const calls = [];
+ const state = { flipY: false, premultiply: true, colorSpace: 7, binding: 'previous' };
+ const context = {
+ TEXTURE_2D: 3553, RGBA: 6408, UNSIGNED_BYTE: 5121, NONE: 0, MAX_TEXTURE_SIZE: 1, TEXTURE_BINDING_2D: 2,
+ UNPACK_FLIP_Y_WEBGL: 10, UNPACK_PREMULTIPLY_ALPHA_WEBGL: 11, UNPACK_COLORSPACE_CONVERSION_WEBGL: 12,
+ getParameter: name => ({ 1: MAX_TEXTURE_SIZE, 2: state.binding, 10: state.flipY, 11: state.premultiply, 12: state.colorSpace })[name],
+ pixelStorei: (name, value) => {
+ calls.push(['pixelStorei', name, value]);
+ if (name === 10) state.flipY = value;
+ if (name === 11) state.premultiply = value;
+ if (name === 12) state.colorSpace = value;
+ },
+ bindTexture: (target, texture) => { calls.push(['bindTexture', texture]); state.binding = texture; },
+ texSubImage2D: (...args) => calls.push(['texSubImage2D', ...args.slice(1), state.flipY, state.premultiply, state.colorSpace]),
+ generateMipmap: () => calls.push(['generateMipmap']),
+ };
+ const renderer = Object.create(Renderer67.prototype);
+ renderer.context = context;
+ renderer.textures = new Map([[descriptor, 'texture']]);
+ return { renderer, calls, state };
+}
+
+const bytes = (width, height) => new Uint8Array(width * height * 4);
+const image = (width, height) => ({ width, height });
+
+test('region validation names the problem', () => {
+ const good = { x: 2, y: 4, width: 3, height: 2, data: bytes(3, 2) };
+ assert.doesNotThrow(() => validateTextureRegion(good, 8, 8));
+ assert.throws(() => validateTextureRegion({ ...good, x: 1.5 }, 8, 8), /region\.x must be an integer/);
+ assert.throws(() => validateTextureRegion({ ...good, width: 0, data: bytes(0, 2) }, 8, 8), /does not fit the 8x8 texture/);
+ assert.throws(() => validateTextureRegion({ ...good, x: -1 }, 8, 8), /does not fit/);
+ assert.throws(() => validateTextureRegion({ ...good, x: 6 }, 8, 8), /3x2 at 6,4 does not fit/);
+ assert.throws(() => validateTextureRegion({ ...good, y: 7 }, 8, 8), /does not fit/);
+ assert.throws(() => validateTextureRegion({ ...good, data: bytes(3, 1) }, 8, 8), /has 12 bytes, expected 24/);
+ assert.throws(() => validateTextureRegion({ ...good, data: new Float32Array(24) }, 8, 8), /Uint8Array or Uint8ClampedArray/);
+ assert.throws(() => validateTextureRegion(undefined, 8, 8), /must be an integer/);
+ assert.doesNotThrow(() => validateTextureRegion({ ...good, data: new Uint8ClampedArray(24) }, 8, 8));
+});
+
+test('region rows follow the flipY of the first upload', () => {
+ const region = { x: 3, y: 1, width: 2, height: 2 };
+ assert.deepEqual(textureRegionOffset(region, 8, false), { x: 3, y: 1 });
+ assert.deepEqual(textureRegionOffset(region, 8, true), { x: 3, y: 5 });
+ assert.deepEqual(textureRegionOffset({ x: 0, y: 0, width: 8, height: 8 }, 8, true), { x: 0, y: 0 });
+});
+
+test('a region upload binds, sets unpack state, restores it and regenerates mipmaps', () => {
+ const descriptor = { image: image(8, 8), flipY: true };
+ const { renderer, calls, state } = fakeRenderer(descriptor);
+ const data = bytes(2, 2);
+ renderer.updateTexture(descriptor, { region: { x: 1, y: 1, width: 2, height: 2, data } });
+ assert.deepEqual(calls.find(call => call[0] === 'texSubImage2D'), ['texSubImage2D', 0, 1, 5, 2, 2, 6408, 5121, data, true, false, 0]);
+ assert.equal(calls.at(-1)[0], 'bindTexture');
+ assert.equal(calls.filter(call => call[0] === 'generateMipmap').length, 1);
+ assert.deepEqual({ ...state }, { flipY: false, premultiply: true, colorSpace: 7, binding: 'previous' });
+});
+
+test('a texture without mipmaps is not regenerated', () => {
+ const descriptor = { image: image(8, 8), minFilter: 9729 };
+ const { renderer, calls } = fakeRenderer(descriptor);
+ renderer.updateTexture(descriptor, { region: { x: 0, y: 0, width: 1, height: 1, data: bytes(1, 1) } });
+ assert.equal(calls.some(call => call[0] === 'generateMipmap'), false);
+});
+
+test('a whole image upload takes update.image or the descriptor image again', () => {
+ const descriptor = { image: image(8, 8) };
+ const { renderer, calls } = fakeRenderer(descriptor);
+ const replacement = image(8, 8);
+ renderer.updateTexture(descriptor, { image: replacement });
+ renderer.updateTexture(descriptor);
+ const uploads = calls.filter(call => call[0] === 'texSubImage2D');
+ assert.equal(uploads[0][6], replacement);
+ assert.equal(uploads[1][6], descriptor.image);
+ assert.deepEqual(uploads[0].slice(1, 4), [0, 0, 0]);
+});
+
+test('unusable updates fail with a clear message and leave the unpack state alone', () => {
+ const descriptor = { image: image(8, 8) };
+ const { renderer, calls } = fakeRenderer(descriptor);
+ assert.throws(() => renderer.updateTexture({ image: image(8, 8) }), /already uploaded/);
+ assert.throws(() => renderer.updateTexture(null), /already uploaded/);
+ assert.throws(() => renderer.updateTexture(descriptor, { image: image(4, 8) }), /must be 8x8 like the uploaded texture/);
+ assert.throws(() => renderer.updateTexture(descriptor, { image: image(8, 8), region: { x: 0, y: 0, width: 1, height: 1, data: bytes(1, 1) } }), /image or region, not both/);
+ assert.throws(() => renderer.updateTexture(descriptor, { region: { x: 7, y: 7, width: 2, height: 2, data: bytes(2, 2) } }), /does not fit the 8x8 texture/);
+ assert.equal(calls.length, 0);
+});
+
+test('compressed textures reject updates', () => {
+ const descriptor = { image: { width: 8, height: 8, compressed: { bytes: 32 } } };
+ const { renderer, calls } = fakeRenderer(descriptor);
+ assert.throws(() => renderer.updateTexture(descriptor), /Compressed textures cannot be updated/);
+ assert.equal(calls.length, 0);
+});
diff --git a/vite.lib.config.js b/vite.lib.config.js
index b9ac3e4f..6079a5c1 100644
--- a/vite.lib.config.js
+++ b/vite.lib.config.js
@@ -64,6 +64,7 @@ export default defineConfig({
'light-linking': 'src/light-linking.js',
'cascaded-shadows': 'src/cascaded-shadows.js',
'gaussian-splats': 'src/gaussian-splats.js',
+ 'texture-update': 'src/texture-update.js',
// Page of the MCP preview. It imports the engine chunks above instead of bundling its own copy.
'mcp/preview': 'scripts/agent-preview-browser.js',
},