Skip to content

3D engine that AI agents drive

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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 gzip
diff --git a/docs/culling-lod.md b/docs/culling-lod.md
index 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`.
## Measured
diff --git a/docs/guide.md b/docs/guide.md
index 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.js
index 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.js
index 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, mem
for (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.js
index 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 the
assert.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.js
index 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 insi
assert.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));
+});