3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Refuse an infinite adaptive target, huge texture sizes and an infinite budget hint (#2465)
Nguyen Xuan Ancd3007ce533f
diff --git a/changes/2465.md b/changes/2465.mdnew file mode 100644index 00000000..0f3b4ff7--- /dev/null+++ b/changes/2465.md@@ -0,0 +1 @@+- `AdaptiveResolution`, `estimateTextureBytes` and the budget error refuse an infinite target, huge texture sizes and an infinite suggested budget (#2465, #2466, #2467)diff --git a/changes/2465.size.md b/changes/2465.size.mdnew file mode 100644index 00000000..66b0cf0f--- /dev/null+++ b/changes/2465.size.md@@ -0,0 +1,3 @@+- goal:lit-box: three input checks add 13 bytes gzip; each one stops a silent no-op or an advice no caller can follow+- goal:gltf-box: the same checks add 9 bytes gzip+- goal:agent-scene: the same checks add 1 byte gzipdiff --git a/docs/culling-lod.md b/docs/culling-lod.mdindex d98aead6..a47ded96 100644--- a/docs/culling-lod.md+++ b/docs/culling-lod.md@@ -44,7 +44,7 @@ The selection is a pure function of the geometry, the instance matrices, the cam`createGpuTimer(context)` from `src/adaptive-quality.js` wraps `EXT_disjoint_timer_query_webgl2` (it returns `null` without the extension). Pass the function itself as the `createGpuTimer` option of `CrucibleRenderer` and the renderer times each frame. A result arrives a few frames late, so `renderer.gpuMilliseconds` holds the latest finished one, or `null` after a disjoint measurement. Without the option nothing is timed and the timer code is not bundled.-`createAdaptiveResolution({ exporting: false, targetMilliseconds, minimumScale, step, window, raiseBelow })` from `src/adaptive-quality.js` returns a controller. Feed it one frame time per frame with `update(milliseconds)` and multiply the pixel ratio by the scale it returns. It lowers the scale by one `step` when the average of `window` frames is over the target, raises it only after a whole window under `raiseBelow` of the target (default 0.6, above 0 and at most 1; anything else throws), and never goes below `minimumScale` (default 0.5). `createAdaptiveResolution({ exporting: true })` throws: exports keep full quality, and the live viewer in `src/main.js` builds a controller only when its `export` parameter is not `1`.+`createAdaptiveResolution({ exporting: false, targetMilliseconds, minimumScale, step, window, raiseBelow })` from `src/adaptive-quality.js` returns a controller. Feed it one frame time per frame with `update(milliseconds)` and multiply the pixel ratio by the scale it returns. It lowers the scale by one `step` when the average of `window` frames is over the target, raises it only after a whole window under `raiseBelow` of the target (default 0.6, above 0 and at most 1; anything else throws), and `targetMilliseconds` must be finite and above 0, and never goes below `minimumScale` (default 0.5). `createAdaptiveResolution({ exporting: true })` throws: exports keep full quality, and the live viewer in `src/main.js` builds a controller only when its `export` parameter is not `1`.## Measureddiff --git a/docs/guide.md b/docs/guide.mdindex aca8192b..70bcac43 100644--- a/docs/guide.md+++ b/docs/guide.md@@ -79,7 +79,7 @@ Core exports are available from `crucible`:| EFFECT_PRESETS, resolveEffects | Named looks and validated effect settings || createAnimationClip, sampleAnimationClip, createAnimationPlayer | Validate tracks, sample time and bind part animation |-`planRenderSize` accepts width, height, pixelRatio, samples, memoryBudgetMiB, geometryBytes, textureBytes, hdr, bloom, shadowResolution and maximumSize. It returns actual dimensions, estimatedBytes and reduced status. `estimateFrameBytes(width, height, samples, shadowResolution, { hdr, bloom })` estimates target storage. Neither function measures total VRAM.+`planRenderSize` accepts width, height, pixelRatio, samples, memoryBudgetMiB, geometryBytes, textureBytes, hdr, bloom, shadowResolution and maximumSize. It returns actual dimensions, estimatedBytes and reduced status. `estimateFrameBytes(width, height, samples, shadowResolution, { hdr, bloom })` estimates target storage. `estimateTextureBytes(width, height)` takes whole sizes from 1 to 65536. Neither function measures total VRAM.`crucible/addons/model`: createModel. `crucible/addons/nature`: createNatureWorld. `crucible/addons/motion`: createMotionScene.diff --git a/src/adaptive-quality.js b/src/adaptive-quality.jsindex 9c7c0927..ddea44fe 100644--- a/src/adaptive-quality.js+++ b/src/adaptive-quality.js@@ -60,7 +60,7 @@ export function createGpuTimer(context) {*/export class AdaptiveResolution {constructor({ targetMilliseconds = 1000 / 60, minimumScale = 0.5, step = 0.125, window = 20, raiseBelow = 0.6 } = {}) {- if (!(targetMilliseconds > 0)) throw new RangeError('targetMilliseconds must be above 0.');+ if (!(targetMilliseconds > 0 && targetMilliseconds < Infinity)) throw new RangeError('targetMilliseconds must be above 0 and finite.');if (!(minimumScale > 0) || minimumScale > 1) throw new RangeError('minimumScale must be above 0 and at most 1.');if (!(step > 0) || step >= 1) throw new RangeError('step must be above 0 and below 1.');if (!Number.isInteger(window) || window < 1) throw new RangeError('window must be a whole number of frames.');diff --git a/src/budget.js b/src/budget.jsindex c0661140..9e1e4923 100644--- a/src/budget.js+++ b/src/budget.js@@ -8,7 +8,7 @@ export function memoryBudgetError(geometry, textures, frame, memoryBudgetMiB, {const mebibytes = bytes => (bytes / MEBIBYTE).toFixed(1);const requiredMiB = Math.ceil((geometry + textures + frame) / MEBIBYTE);const counted = `Memory budget cannot hold geometry ${mebibytes(geometry)} MiB, textures ${mebibytes(textures)} MiB and frame ${mebibytes(frame)} MiB, over memoryBudgetMiB ${memoryBudgetMiB}.`;- if (requiredMiB > maximumMemoryBudgetMiB) {+ if (!(requiredMiB < Infinity) || requiredMiB > maximumMemoryBudgetMiB) {return new RangeError(`${counted} It needs ${requiredMiB} MiB, more than the ${maximumMemoryBudgetMiB} MiB largest budget this runtime accepts. Fix: reduce the textures, the geometry, the frame size, or turn off HDR or bloom.`);}return new RangeError(`${counted} Fix: pass { memoryBudgetMiB: ${requiredMiB} }.`);@@ -22,7 +22,7 @@ export const RENDER_PRESETS = Object.freeze({});export function estimateTextureBytes(width, height, { mipmaps = true } = {}) {- if (!Number.isInteger(width) || !Number.isInteger(height) || width <= 0 || height <= 0) throw new Error('Texture dimensions must be positive integers.');+ if (!(width > 0 && height > 0 && width <= 65536 && height <= 65536 && Number.isInteger(width) && Number.isInteger(height))) throw new Error('Texture size must be an integer from 1 to 65536.');let bytes = 0;do {bytes += width * height * 4;@@ -53,9 +53,9 @@ export function planRenderSize({ width, height, pixelRatio = 1, samples = 4, memfor (const value of [width, height, pixelRatio, samples, memoryBudgetMiB, maximumSize]) {if (!Number.isFinite(value) || value <= 0) throw new Error('Render dimensions, sample count and budget must be positive finite numbers.');}- if (geometryBytes < 0 || !Number.isFinite(geometryBytes)) throw new Error('Geometry memory must be a nonnegative finite number.');- if (textureBytes < 0 || !Number.isFinite(textureBytes)) throw new Error('Texture memory must be a nonnegative finite number.');- if (!Number.isFinite(shadowResolution) || shadowResolution < 0) throw new Error('Shadow resolution must be nonnegative and finite.');+ for (const value of [geometryBytes, textureBytes, shadowResolution]) {+ if (!(value >= 0 && value < Infinity)) throw new Error('Memory bytes and shadow resolution must be finite and 0 or more.');+ }const available = memoryBudgetMiB * MEBIBYTE - geometryBytes - textureBytes - shadowResolution ** 2 * 4;const bytesPerPixel = (hdr ? 12 : 8) * Math.max(1, samples) + (hdr ? 24 : 20) + (bloom ? hdr ? 4 : 2 : 0) + (depth ? 4 : 0);// The suggested budget fits the full requested frame, not only the minimum target.diff --git a/tests/adaptive-quality.test.js b/tests/adaptive-quality.test.jsindex c63fef4f..d3ec2a1f 100644--- a/tests/adaptive-quality.test.js+++ b/tests/adaptive-quality.test.js@@ -79,3 +79,9 @@ test('a raise threshold that can never be met is refused instead of pinning theassert.throws(() => new AdaptiveResolution({ raiseBelow }), /raiseBelow/, `raiseBelow ${raiseBelow}`);}});++test('a non-finite target is refused instead of freezing the scale', async () => {+ for (const targetMilliseconds of [Infinity, Number.NaN]) {+ assert.throws(() => new AdaptiveResolution({ targetMilliseconds }), /targetMilliseconds/);+ }+});diff --git a/tests/budget.test.js b/tests/budget.test.jsindex dca04897..8cf8d126 100644--- a/tests/budget.test.js+++ b/tests/budget.test.js@@ -20,7 +20,7 @@ test('HDR, two half-resolution bloom targets and cached texture mipmaps fit insiassert.equal(plan.estimatedBytes, estimateFrameBytes(plan.width, plan.height, 4, 2048, { hdr: true, bloom: true }) + textureBytes);assert.ok(estimateFrameBytes(100, 101, 4, 0, { hdr: true, bloom: true }) > estimateFrameBytes(100, 101, 4, 0));assert.throws(() => planRenderSize({ width: 640, height: 360, textureBytes: 200 * 1024 ** 2, memoryBudgetMiB: 128 }), /cannot hold/);- assert.throws(() => estimateTextureBytes(-1, 32), /positive/);+ assert.throws(() => estimateTextureBytes(-1, 32), /integer from 1/);});test('presets fit their budget and device texture limits', () => {@@ -91,3 +91,12 @@ test('a budget error never advises a value above the largest budget the runtime});assert.throws(() => planRenderSize({ ...scene, geometryBytes: 0, textureBytes: 200 * 1024 ** 2, width: 640, height: 360, maximumMemoryBudgetMiB: 384 }), /Fix: pass \{ memoryBudgetMiB: \d+ \}/);});++test('texture dimensions past the bound are refused instead of returning Infinity', () => {+ assert.throws(() => estimateTextureBytes(1e300, 1e300), /estimateTextureBytes: width was 1e\+300/);+ assert.throws(() => estimateTextureBytes(64, 2 ** 40), /integer from 1/);+});++test('an unfixable memory budget error never suggests an infinite budget', () => {+ assert.throws(() => planRenderSize({ width: 100, height: 100, shadowResolution: 1e200 }), error => error instanceof RangeError && !/Infinity }/.test(error.message) && /reduce/.test(error.message));+});