3D engine that AI agents drive
Bound pixel count and dispatch size, validate maxSeconds and reject non-number options (#894)
Nguyen Xuan An82ce9ca5a7ca
diff --git a/packages/render-native/index.mjs b/packages/render-native/index.mjsindex 174624f6..8c02fefc 100644--- a/packages/render-native/index.mjs+++ b/packages/render-native/index.mjs@@ -13,6 +13,8 @@ import {buildNativeInputV2,packMaterialRecordV2,upgradeNativeInputV1ToV2,+ validateImagePixelCount,+ validateMaxSeconds,validatePackOptions,} from './pack-input-v2.mjs';@@ -129,6 +131,8 @@ export function probeCyclesLobe(options = {}) {if (!Number.isInteger(width) || width < 1 || width > 16384 || !Number.isInteger(height) || height < 1 || height > 16384) {throw new RangeError(`probeCyclesLobe requires integer \`width\` and \`height\` in [1, 16384]; got width=${width}, height=${height}.`);}+ validateImagePixelCount(width, height, 'probeCyclesLobe');+ validateMaxSeconds(options.maxSeconds, 'probeCyclesLobe');const wo = options.wo ?? [0, 0, 1];if (!Array.isArray(wo) && !ArrayBuffer.isView(wo) || wo.length !== 3) {throw new TypeError('probeCyclesLobe option `wo` must hold 3 numbers.');@@ -178,6 +182,7 @@ export function probeCyclesLobe(options = {}) {* `buildNativeTexelInput`.*/export function traceNativeTexels(input, texels, { samples, maxSeconds }) {+ validateMaxSeconds(maxSeconds, 'traceNativeTexels');return loadAddon().traceTexels(input, texels, { samples, maxSeconds });}diff --git a/packages/render-native/pack-input-v2.mjs b/packages/render-native/pack-input-v2.mjsindex 5a1a6148..fa7e2dcf 100644--- a/packages/render-native/pack-input-v2.mjs+++ b/packages/render-native/pack-input-v2.mjs@@ -1434,8 +1434,52 @@ function packEnvironmentTexelsV2(environment, options = {}) {};}+// The accumulation buffer holds 64 bytes per pixel and the device caps one storage buffer at 1 GiB.+export const MAX_TRACE_PIXELS = 2 ** 24;+// The most path samples (pixels times samplesPerDispatch) one dispatch may hold; it equals what the automatic batch picks at+// the largest image (16 samples of 4096 x 4096), so a dispatch finishes well inside the GPU watchdog time.+export const MAX_PATH_SAMPLES_PER_DISPATCH = 2 ** 28;++function requireNumberType(value, name, callerName) {+ if (typeof value !== 'number') {+ const received = value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;+ throw new TypeError(`${callerName}: \`${name}\` must be a number; got ${received}. Pass a number, not a string, boolean or array.`);+ }+}++/** Rejects a `maxSeconds` that is not a finite number greater than zero; `undefined` means no time limit. */+export function validateMaxSeconds(maxSeconds, callerName) {+ if (maxSeconds === undefined) {+ return;+ }+ requireNumberType(maxSeconds, 'maxSeconds', callerName);+ if (!Number.isFinite(maxSeconds) || maxSeconds <= 0) {+ throw new RangeError(`${callerName}: \`maxSeconds\` must be a finite number greater than 0; got ${maxSeconds}.`);+ }+}++/** Rejects an image whose accumulation buffer would not fit one storage buffer on the device. */+export function validateImagePixelCount(width, height, callerName) {+ if (width * height > MAX_TRACE_PIXELS) {+ throw new RangeError(+ `${callerName}: \`width\` times \`height\` must be at most ${MAX_TRACE_PIXELS} pixels (4096 x 4096) so the accumulation buffer fits the device limit; got ${width} x ${height} = ${width * height}. Lower the resolution.`+ );+ }+}++/** Rejects a dispatch of `samplesPerDispatch` samples over `width * height` pixels that is too long for one GPU submission. */+export function validateDispatchSize(width, height, samplesPerDispatch, callerName) {+ if (width * height * samplesPerDispatch > MAX_PATH_SAMPLES_PER_DISPATCH) {+ const largestAllowed = Math.max(1, Math.floor(MAX_PATH_SAMPLES_PER_DISPATCH / (width * height)));+ throw new RangeError(+ `${callerName}: \`samplesPerDispatch\` times \`width\` times \`height\` must be at most ${MAX_PATH_SAMPLES_PER_DISPATCH} path samples per dispatch; got ${samplesPerDispatch} x ${width} x ${height} = ${samplesPerDispatch * width * height}. Pass \`samplesPerDispatch\` of ${largestAllowed} or less.`+ );+ }+}+function requireFiniteIntegerInRange(value, name, min, max, callerName) {- const n = Number(value);+ requireNumberType(value, name, callerName);+ const n = value;if (!Number.isFinite(n)) {throw new RangeError(`${callerName}: \`${name}\` must be a finite integer in [${min}, ${max}]; got ${value === null ? 'null' : JSON.stringify(value)}.`@@ -1480,6 +1524,13 @@ export function validatePackOptions(options, callerName, requireDimensionsAndSam}// samplesPerDispatch is optional (undefined means "let the addon choose"); only validate when provided.requireFiniteIntegerInRangeIfPresent(samplesPerDispatch, 'samplesPerDispatch', 1, 65536, callerName);+ validateMaxSeconds(options.maxSeconds, callerName);+ if (width !== undefined && height !== undefined) {+ validateImagePixelCount(width, height, callerName);+ if (samplesPerDispatch !== undefined) {+ validateDispatchSize(width, height, samplesPerDispatch, callerName);+ }+ }// Bounce limits — each is optional; when provided must be a finite integer in [0, 1024].const bounceFields = [diff --git a/tests/native-pack-v2.test.js b/tests/native-pack-v2.test.jsindex b2cd38f7..e0f1053f 100644--- a/tests/native-pack-v2.test.js+++ b/tests/native-pack-v2.test.js@@ -13,6 +13,7 @@ import {traceNative,upgradeNativeInputV1ToV2,} from '../packages/render-native/index.mjs';+import { validatePackOptions } from '../packages/render-native/pack-input-v2.mjs';import { createEnvironmentMap } from '../src/hdri.js';import { createCamera } from '../src/path-tracer.js';import * as pack from '../src/path-tracer-gpu-pack.js';@@ -600,7 +601,9 @@ test('buildNativeInputV2 rejects non-finite, non-integer, out-of-range width andassert.throws(() => build({ height: 99999 }), /height/, 'height 99999');// Exact bounds passassert.doesNotThrow(() => build({ width: 1, height: 1 }), 'min bounds');- assert.doesNotThrow(() => build({ width: 16384, height: 16384 }), 'max bounds');+ assert.doesNotThrow(() => build({ width: 4096, height: 4096 }), 'max pixel count');+ assert.doesNotThrow(() => build({ width: 16384, height: 1 }), 'max width');+ assert.throws(() => build({ width: 16384, height: 16384 }), /pixels/, 'over the pixel limit');});// ---------------------------------------------------------------------------@@ -717,3 +720,57 @@ test('traceNative and probeCyclesLobe validate options at the public boundary evassert.throws(() => traceNative(v2Input, { height: 8, samples: 1, kernel: 'cycles' }), /width/);assert.throws(() => probeCyclesLobe({ width: 16385, height: 8 }), /16384/);});++// ---------------------------------------------------------------------------+// Boundary validation: pixel count, dispatch size, maxSeconds and number types+// ---------------------------------------------------------------------------++test('traceNative bounds the pixel count by the accumulation buffer and states the largest size', () => {+ const minimalScene = buildTraceScene([{ name: 'q', geometry: quadGeometry(0), material: { color: [0.5, 0.5, 0.5] } }], {});+ const camera = createCamera({ eye: [0, 0, 3], target: [0, 0, 0], fov: 50 }, 8, 8);+ const v2Input = buildNativeInputV2(minimalScene, camera, { width: 8, height: 8, samples: 1 });+ const trace = (width, height) => traceNative(v2Input, { width, height, samples: 1, kernel: 'cycles' });++ assert.throws(() => trace(16384, 16384), (error) => error instanceof RangeError && /16777216 pixels \(4096 x 4096\)/.test(error.message));+ assert.throws(() => trace(4097, 4096), RangeError);+ assert.throws(() => probeCyclesLobe({ width: 16384, height: 16384 }), /16777216 pixels/);+ // The exact limits pass validation.+ assert.doesNotThrow(() => validatePackOptions({ width: 4096, height: 4096, samples: 1 }, 'traceNative', true));+ assert.doesNotThrow(() => validatePackOptions({ width: 16384, height: 1, samples: 1 }, 'traceNative', true));+});++test('traceNative bounds samplesPerDispatch times pixel count and says what to pass', () => {+ const options = { width: 4096, height: 4096, samples: 64 };+ assert.doesNotThrow(() => validatePackOptions({ ...options, samplesPerDispatch: 16 }, 'traceNative', true));+ assert.throws(+ () => validatePackOptions({ ...options, samplesPerDispatch: 17 }, 'traceNative', true),+ (error) => error instanceof RangeError && /268435456 path samples per dispatch/.test(error.message) && /16 or less/.test(error.message),+ );+ assert.doesNotThrow(() => validatePackOptions({ width: 8, height: 8, samples: 1, samplesPerDispatch: 65536 }, 'traceNative', true));+});++test('traceNative validates maxSeconds when given', () => {+ const base = { width: 8, height: 8, samples: 1 };+ assert.doesNotThrow(() => validatePackOptions({ ...base, maxSeconds: undefined }, 'traceNative', true));+ assert.doesNotThrow(() => validatePackOptions({ ...base, maxSeconds: 0.5 }, 'traceNative', true));+ for (const invalid of [0, -1, NaN, Infinity, -Infinity]) {+ assert.throws(() => validatePackOptions({ ...base, maxSeconds: invalid }, 'traceNative', true), /maxSeconds/, `maxSeconds ${invalid}`);+ }+ for (const invalid of ['5', true, [5], null, {}]) {+ assert.throws(() => validatePackOptions({ ...base, maxSeconds: invalid }, 'traceNative', true), TypeError, `maxSeconds ${JSON.stringify(invalid)}`);+ }+ assert.throws(() => probeCyclesLobe({ width: 8, height: 8, maxSeconds: 0 }), /maxSeconds/);+});++test('pack options reject strings, booleans, arrays and null instead of coercing them', () => {+ const base = { width: 8, height: 8, samples: 1 };+ for (const field of ['width', 'height', 'samples', 'samplesPerDispatch', 'bounces', 'minBounceRr']) {+ for (const invalid of ['8', true, [8], null]) {+ assert.throws(+ () => validatePackOptions({ ...base, [field]: invalid }, 'traceNative', true),+ (error) => error instanceof TypeError && error.message.includes(field) && /must be a number/.test(error.message),+ `${field} ${JSON.stringify(invalid)}`,+ );+ }+ }+});