Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Map only rayVisibility to ray bits, refuse hidden emitters and keep fallbacks quiet (#1054)

Nguyen Xuan An8eba8ac4be34
diff --git a/bench/cycles-parity/pane-shadow-visibility.mjs b/bench/cycles-parity/pane-shadow-visibility.mjs
index 02ed2291..9c3a68e4 100644
--- a/bench/cycles-parity/pane-shadow-visibility.mjs
+++ b/bench/cycles-parity/pane-shadow-visibility.mjs
@@ -1,5 +1,5 @@
// A small room lit only by the sky through a window with a glass pane, traced by the native "cycles" kernel with the pane
-// blocking shadow rays (the default) and with `castShadow: false` (#1054). For each setting it renders 64 and 512 spp and a
+// blocking shadow rays (the default) and with `rayVisibility: { shadow: false }` (#1054). For each setting it renders 64 and 512 spp and a
// 4096 spp reference of the same setting, and writes the mean radiance, the relMSE against that reference and a side-by-side image.
//
// node bench/cycles-parity/pane-shadow-visibility.mjs <output directory>
@@ -106,7 +106,7 @@ function toPpmPanel(panels) {
const outputDirectory = resolve(process.argv[2] ?? 'artifacts/pane-shadow-visibility');
mkdirSync(outputDirectory, { recursive: true });
-const settings = { 'pane blocks shadow rays': {}, 'pane with castShadow false': { castShadow: false } };
+const settings = { 'pane blocks shadow rays': {}, 'pane with shadow rays off': { rayVisibility: { shadow: false } } };
// The sun is a small bright source that only a shadow ray can find, so the sky-only room tests the soft light and the sun room the hard one.
const suns = {
'sky only': { keyColor: [0, 0, 0], lightDirection: [0, 1, 0] },
diff --git a/changes/1054.md b/changes/1054.md
index 15f4ba34..33195dad 100644
--- a/changes/1054.md
+++ b/changes/1054.md
@@ -1 +1 @@
-- A part takes `rayVisibility: { camera, diffuse, glossy, transmission, shadow }` and `castShadow: false` now hides it from shadow rays in the native path tracer, so a glazed window no longer blocks the sun and sky (#1054)
+- A part takes `rayVisibility: { camera, diffuse, glossy, transmission, shadow, volumeScatter }` to hide itself from ray kinds in the native path tracer, so a glazed window can stop blocking the sun and sky (#1054)
diff --git a/docs/path-tracer.md b/docs/path-tracer.md
index 2ce4f3cc..be60ffa6 100644
--- a/docs/path-tracer.md
+++ b/docs/path-tracer.md
@@ -69,9 +69,11 @@ Also checked before any ray is traced: samples times pixels times bounces at mos
- Texture mip levels are opt in on the `cycles` kernel: pass `textureMips: true` to the packer (or `mips: true` on one texture) and every linearly filtered texture, RGBA8, sRGB and float, stores a mip chain after level 0 (level 1 integrates the level 0 reconstruction, the rest are 2 x 2 boxes); the kernel then keeps a ray cone per path and reads the level a hit asks for, blended between two levels. Blender Cycles reads level 0 only, so the default stays level 0 and an existing scene packs and renders byte for byte as before. The pool check counts the levels (a third more texels). The estimate, its limits and the measured error of a minified checker are in `docs/cycles-parity.md` ("Texture mip levels").
- When the instanced packer refuses a scene (copies of an emissive mesh that emit different triangles, a singular matrix), the job exports it flattened as before and the report says `instancing: "flattened"` and `instancingReason`. A scene that fails to export no longer marks the native tracer unusable for the process; only a tracer or adapter failure does.
- A part with `shadowOnly: true` becomes an instance that camera rays skip (visibility bits for every other ray kind stay set). An instance whose material differs from the first copy's emits light by its own material: a copy made emissive by its material is sampled as a light, and a copy made non-emissive is not. Triangles of a shared mesh that are emissive keep one `local_emissive_offset` for all copies, so a copy scaled to a size that drops an emissive triangle the other copies keep is refused with its index.
-- Ray visibility (#1054): a part takes `rayVisibility: { camera, diffuse, glossy, transmission, shadow, volumeScatter }`, booleans where `false` hides the part from that ray kind, and `castShadow: false` means `rayVisibility.shadow: false`. The names and the bit layout (1, 2, 4, 8, 16, 32) are those of the FORMAT-v2 instance table and of the Cycles `visible_*` object settings the parity bench sets. `buildTraceScene` validates the field at the public boundary (an unknown ray kind, a non-boolean value, `castShadow: false` with `rayVisibility.shadow: true`, or `shadowOnly` with shadow rays off throws and says what to pass) and returns it as `instances[i].visibilityFlags` for an instanced scene and as `partRayVisibility` (one byte per part) for a flattened one; the job packers write both into the instance table. A pane with `castShadow: false` lets the sun and sky be sampled through a window, where the shadow rays would otherwise hit the glass and all the light arrives by refraction (much more noise); the pane still shows and refracts for camera and bounce rays. A scene where no part sets either field packs byte for byte as before.
- - Only the `cycles` kernel reads it. A flattened scene with a part that sets it cannot be written as v1 tables: `buildNativeInput`, a light bake and a job on the `legacy` kernel throw instead of ignoring it. The CPU tracer, the WebGPU and WebGL tracers and the rasteriser ignore `rayVisibility` as before (the rasteriser already honours `castShadow`). The MCP scene tools do not expose `rayVisibility`; `castShadow: false` on a part reaches the native tracer through them.
- - Not done: a Cycles-style option that lets shadow rays through thin clear glass by itself. Set `castShadow: false` on the pane.
+- Ray visibility (#1054): a part takes `rayVisibility: { camera, diffuse, glossy, transmission, shadow, volumeScatter }`, booleans where `false` hides the part from that ray kind. The names and the bit layout (1, 2, 4, 8, 16, 32) are those of the FORMAT-v2 instance table and of the Cycles `visible_*` object settings the parity bench sets. `buildTraceScene` validates the field at the public boundary (an unknown ray kind, a non-boolean value, `shadowOnly` with `shadow: false`, or an emitter hidden from bounce rays throws and says what to pass) and returns it as `instances[i].visibilityFlags` for an instanced scene and as `partRayVisibility` (one byte per part) for a flattened one; the job packers write both into the instance table. A pane with `rayVisibility: { shadow: false }` lets the sun and sky be sampled through a window, where the shadow rays would otherwise hit the glass; the pane still shows and refracts for camera and bounce rays. A scene where no part hides from a ray kind (no field, `{}` or all `true`) packs byte for byte as before.
+ - `castShadow` is deliberately not mapped: library code sets `castShadow: false` as a raster optimisation (grass, litter, whitewater, windows, gulls), so honouring it would change how existing scenes path trace. The native tracer ignores it as before; only `rayVisibility` sets the bits.
+ - An emissive part (`material.emission > 0`) may hide from `camera`, `shadow` and `volumeScatter` rays but not from `diffuse`, `glossy` or `transmission`: the kernel samples an emitter by next-event estimation with a multiple-importance weight below 1 and weights its bounce hits to match, so culling those hits would lose part of its light (up to about half). `buildTraceScene` refuses that combination. Blender Cycles behaviour for such an emitter was not checked here; refusing is the safe choice until a parity run says what Cycles does.
+ - Only the `cycles` kernel reads it. `buildNativeInput` (the v1 tables of the `legacy` kernel) and a job on the `legacy` kernel throw when a flattened scene hides a part from a ray kind. The v1 fallback of a `cycles` job (after a FORMAT-v2 material build fails) and light bakes draw without the visibility; the job report then says `rayVisibility: "ignored"` with `rayVisibilityReason`, as `materialsReason` does for the materials. The CPU tracer, the WebGPU and WebGL tracers and the rasteriser ignore `rayVisibility` as before. The MCP scene tools do not expose `rayVisibility`.
+ - Not done: a Cycles-style option that lets shadow rays through thin clear glass by itself. Set `rayVisibility: { shadow: false }` on the pane.
A part whose matrix mirrors (negative determinant) is flattened with its vertex normals kept outward and the last two corners of each triangle swapped, so the cross-product normal of every triangle points outward too. The native `cycles` kernel derives its geometric normal from that winding, and an instanced mirrored part reaches the same result through its negative-scale flag; a scene without a mirrored part is unchanged byte for byte.
diff --git a/packages/render-native/pack-input.mjs b/packages/render-native/pack-input.mjs
index 33a3216c..bc258de3 100644
--- a/packages/render-native/pack-input.mjs
+++ b/packages/render-native/pack-input.mjs
@@ -52,12 +52,12 @@ function writeParameters(scene, camera, options, lightCount, atlasWidth, subsurf
*/
export function buildNativeInput(scene, camera, options, pack) {
if (scene.partRayVisibility) {
- throw new TypeError('A part sets rayVisibility or castShadow: false, which the v1 tables cannot carry. Pack the scene for kernel "cycles" with buildFlattenedJobNativeInput (or build it with { instancing: true } and use buildJobNativeInput), or drop the part setting.');
+ throw new TypeError('A part sets rayVisibility to hide from a ray kind, which the v1 tables of kernel "legacy" cannot carry. Pack the scene for kernel "cycles" with buildFlattenedJobNativeInput (or build it with { instancing: true } and use buildJobNativeInput), or drop the rayVisibility of the part.');
}
return buildNativeV1Tables(scene, camera, options, pack);
}
-/** The v1 tables of a flattened scene without the refusal above: for a caller that reads `scene.partRayVisibility` itself. */
+/** The v1 tables of a flattened scene without the refusal above, which leave `scene.partRayVisibility` out: a light bake, and a job that reads it itself. */
export function buildNativeV1Tables(scene, camera, options, pack) {
if (scene.instances) {
throw new TypeError('buildNativeInput packs flattened scenes for kernel "legacy" and cannot read instances: build the scene without { instancing: true }, or pack it with buildNativeInputV2 and trace with kernel "cycles".');
@@ -109,11 +109,12 @@ const NO_CAMERA = { eye: [0, 0, 0], forward: [0, 0, -1], right: [1, 0, 0], above
/**
* The tables of a light bake: the scene without a camera, with the texel count and the sample count in the parameter block.
- * `options` holds `texelCount`, `samples`, `bounces`, `seed` and `fireflyClamp`; `pack` is as for `buildNativeInput`.
+ * `options` holds `texelCount`, `samples`, `bounces`, `seed` and `fireflyClamp`; `pack` is as for `buildNativeInput`. A bake ignores
+ * a part's `rayVisibility`: its v1 tables carry no visibility.
*/
export function buildNativeTexelInput(scene, options, pack) {
// The bake's `bounces` counts the leg that leaves the texel; the kernel counts the bounces after its first hit.
- const input = buildNativeInput(scene, NO_CAMERA, { ...options, bounces: options.bounces - 1, width: options.texelCount, height: 1 }, pack);
+ const input = buildNativeV1Tables(scene, NO_CAMERA, { ...options, bounces: options.bounces - 1, width: options.texelCount, height: 1 }, pack);
const words = new Uint32Array(input.parameters.buffer, input.parameters.byteOffset, input.parameters.byteLength / 4);
words[TEXEL_SAMPLES_WORD] = options.samples;
return input;
diff --git a/scripts/native-bake-page.js b/scripts/native-bake-page.js
index 1bdeca21..ba884a62 100644
--- a/scripts/native-bake-page.js
+++ b/scripts/native-bake-page.js
@@ -79,13 +79,14 @@ export function exportNativeSceneTables({ parts, environment, camera, options, k
materialsReason = error.message;
}
}
- if (traceScene.partRayVisibility) {
- const why = materialsReason ?? 'the kernel is not "cycles"';
- throw new TypeError(`A part sets rayVisibility or castShadow: false, which only the "cycles" kernel with FORMAT-v2 tables can carry, and this scene would be exported as v1 tables (${why}). Use kernel "cycles", or drop the part setting.`);
+ if (traceScene.partRayVisibility && !wholeMaterials) {
+ throw new TypeError('A part sets rayVisibility to hide from a ray kind, which only the "cycles" kernel can carry. Use kernel "cycles", or drop the rayVisibility of the part.');
}
- const input = buildNativeInput(traceScene, camera, options, pack);
+ // The v1 tables of the "cycles" job fallback cannot carry visibility: the scene is drawn without it, and the report says so.
+ const visibilityNote = traceScene.partRayVisibility ? { rayVisibility: 'ignored', rayVisibilityReason: materialsReason } : {};
+ const input = buildNativeInput({ ...traceScene, partRayVisibility: null }, camera, options, pack);
return { tables: encodeNativeTables(input), triangleCount: input.triangleCount, triangles: traceScene.indices.length / 3, wholeMaterials: false,
- ...(materialsReason === undefined ? {} : { materialsReason }), ...instancingNote };
+ ...(materialsReason === undefined ? {} : { materialsReason }), ...visibilityNote, ...instancingNote };
}
function floatsFromBase64(data) {
diff --git a/src/path-tracer-scene.js b/src/path-tracer-scene.js
index f2359464..97813b7e 100644
--- a/src/path-tracer-scene.js
+++ b/src/path-tracer-scene.js
@@ -387,8 +387,8 @@ function rayKindBit(kind, value, label) {
/**
* The FORMAT-v2 visibility bits of one part: `rayVisibility: { camera, diffuse, glossy, transmission, shadow, volumeScatter }`
- * (a kind set to false hides the part from those rays), `castShadow: false` as shadow off, and `shadowOnly` as camera off.
- * A part that sets none of them gets 63, every ray kind.
+ * (a kind set to false hides the part from those rays) and `shadowOnly` as camera off. `castShadow` is a raster flag that
+ * library code sets by default, so it never reaches these bits. A part that hides from nothing gets 63, every ray kind.
*/
export function partRayVisibilityFlags(part, index = 0) {
const label = describePart(part, index);
@@ -400,29 +400,39 @@ export function partRayVisibilityFlags(part, index = 0) {
if (value === false) flags &= ~bit;
}
}
- if (part.castShadow === false) {
- if (part.rayVisibility?.shadow === true) {
- throw new TypeError(`${label} sets castShadow: false and rayVisibility.shadow: true, which disagree: drop one of them.`);
- }
- flags &= ~RAY_VISIBILITY_BITS.shadow;
- }
+ requireEmitterStaysVisibleToBounces(part, flags, label);
if (part.shadowOnly === true) {
if ((flags & RAY_VISIBILITY_BITS.shadow) === 0) {
- throw new TypeError(`${label} sets shadowOnly with shadow rays off (castShadow: false or rayVisibility.shadow: false), which would hide it from every ray: keep shadow rays on, or drop shadowOnly.`);
+ throw new TypeError(`${label} sets shadowOnly with rayVisibility.shadow: false, which would hide it from every ray: keep shadow rays on, or drop shadowOnly.`);
}
flags &= ~RAY_VISIBILITY_BITS.camera;
}
return flags;
}
-function requestsRayVisibility(part) {
- return part.rayVisibility !== undefined || part.castShadow === false;
+const BOUNCE_RAY_BITS = RAY_VISIBILITY_BITS.diffuse | RAY_VISIBILITY_BITS.glossy | RAY_VISIBILITY_BITS.transmission;
+
+/**
+ * The kernel samples an emissive mesh by next-event estimation with a multiple-importance weight below 1 and weights its
+ * bounce hits to match. Hiding the emitter from a bounce ray culls those hits while the sampled share stays, so part of its
+ * light would vanish. Camera, shadow and volume rays do not take part in that weighting, so those stay allowed.
+ */
+function requireEmitterStaysVisibleToBounces(part, flags, label) {
+ if ((flags & BOUNCE_RAY_BITS) === BOUNCE_RAY_BITS) return;
+ if (!(part.material?.emission > 0)) return;
+ throw new TypeError(`${label} emits light and sets rayVisibility.diffuse, glossy or transmission to false, which would drop part of its light. Hide an emitter with camera: false or shadow: false instead, or keep diffuse, glossy and transmission true.`);
+}
+
+// True when the part's rayVisibility turns at least one ray kind off; an empty object or all true is the default.
+function hidesFromSomeRay(part) {
+ return part.rayVisibility !== undefined && Object.values(part.rayVisibility).includes(false);
}
-// One byte per part for a flattened scene, or null when no part asks for a ray visibility (shadowOnly alone keeps its own path).
+// One byte per part for a flattened scene, or null when no part hides from a ray kind (shadowOnly alone keeps its own path).
function flattenedRayVisibility(parts) {
- if (!parts.some(requestsRayVisibility)) return null;
- return Uint8Array.from(parts, (part, index) => partRayVisibilityFlags(part, index));
+ const flags = parts.map((part, index) => partRayVisibilityFlags(part, index));
+ if (!parts.some(hidesFromSomeRay)) return null;
+ return Uint8Array.from(flags);
}
/**
diff --git a/tests/part-ray-visibility.test.js b/tests/part-ray-visibility.test.js
index e820e852..62ddb1a1 100644
--- a/tests/part-ray-visibility.test.js
+++ b/tests/part-ray-visibility.test.js
@@ -53,10 +53,10 @@ test('the bits are the FORMAT-v2 instance visibility layout', () => {
assert.deepEqual({ ...RAY_VISIBILITY_BITS }, { camera: 1, diffuse: 2, glossy: 4, transmission: 8, shadow: 16, volumeScatter: 32 });
});
-test('a part maps rayVisibility, castShadow false and shadowOnly to visibility bits', () => {
+test('a part maps rayVisibility and shadowOnly to visibility bits', () => {
assert.equal(partRayVisibilityFlags({}), ALL_RAY_KINDS);
- assert.equal(partRayVisibilityFlags({ castShadow: true, rayVisibility: { shadow: true } }), ALL_RAY_KINDS);
- assert.equal(partRayVisibilityFlags({ castShadow: false }), SHADOW_OFF);
+ assert.equal(partRayVisibilityFlags({ rayVisibility: {} }), ALL_RAY_KINDS);
+ assert.equal(partRayVisibilityFlags({ rayVisibility: { shadow: true, camera: true } }), ALL_RAY_KINDS);
assert.equal(partRayVisibilityFlags({ rayVisibility: { shadow: false } }), SHADOW_OFF);
assert.equal(partRayVisibilityFlags({ rayVisibility: { camera: false, glossy: false } }), ALL_RAY_KINDS & ~1 & ~4);
assert.equal(partRayVisibilityFlags({ rayVisibility: { diffuse: false, transmission: false, volumeScatter: false } }), 1 | 4 | 16);
@@ -64,13 +64,38 @@ test('a part maps rayVisibility, castShadow false and shadowOnly to visibility b
assert.equal(partRayVisibilityFlags({ shadowOnly: true, rayVisibility: { glossy: false } }), 62 & ~4);
});
+test('castShadow never reaches the ray visibility, because library code sets it as a raster default', () => {
+ assert.equal(partRayVisibilityFlags({ castShadow: false }), ALL_RAY_KINDS);
+ const castingOff = [uniquePart('a', 0, { castShadow: false }), uniquePart('b', 2, { castShadow: false, shadowOnly: true })];
+ assert.equal(buildTraceScene(castingOff, environment).partRayVisibility, null);
+ const instanced = buildTraceScene([sharedPart('a', 0, { castShadow: false }), sharedPart('b', 2)], environment, { instancing: true });
+ assert.equal(instanced.instances.some(instance => 'visibilityFlags' in instance), false);
+ const plainFlattened = [uniquePart('a', 0), uniquePart('b', 2, { shadowOnly: true })];
+ assert.equal(digestOfTables(exportedVisibility(castingOff, false).exported), digestOfTables(exportedVisibility(plainFlattened, false).exported));
+ const plainShared = [sharedPart('a', 0), sharedPart('b', 2)];
+ const castingOffShared = plainShared.map(part => ({ ...part, castShadow: false }));
+ assert.equal(digestOfTables(exportedVisibility(castingOffShared, true).exported), digestOfTables(exportedVisibility(plainShared, true).exported));
+});
+
test('a bad rayVisibility says what to pass', () => {
assert.throws(() => partRayVisibilityFlags({ name: 'pane', rayVisibility: 'shadow' }), /part "pane" rayVisibility must be an object such as \{ shadow: false \}/);
assert.throws(() => partRayVisibilityFlags({ rayVisibility: [] }), /part 0 rayVisibility must be an object/);
assert.throws(() => partRayVisibilityFlags({ name: 'pane', rayVisibility: { refraction: false } }), /unknown ray kind "refraction": use camera, diffuse, glossy, transmission, shadow, volumeScatter/);
assert.throws(() => partRayVisibilityFlags({ name: 'pane', rayVisibility: { shadow: 0 } }), /rayVisibility\.shadow must be true or false, got 0/);
- assert.throws(() => partRayVisibilityFlags({ name: 'pane', castShadow: false, rayVisibility: { shadow: true } }), /castShadow: false and rayVisibility\.shadow: true, which disagree/);
- assert.throws(() => partRayVisibilityFlags({ name: 'ghost', shadowOnly: true, castShadow: false }), /shadowOnly with shadow rays off/);
+ assert.throws(() => partRayVisibilityFlags({ name: 'ghost', shadowOnly: true, rayVisibility: { shadow: false } }), /shadowOnly with rayVisibility\.shadow: false/);
+});
+
+test('an emitter may hide from camera, shadow and volume rays but not from bounce rays, which would drop part of its light', () => {
+ const lamp = { tag: 'surface', color: [1, 0.8, 0.6], emission: 4, roughness: 1 };
+ assert.equal(partRayVisibilityFlags({ material: lamp, rayVisibility: { camera: false } }), ALL_RAY_KINDS & ~1);
+ assert.equal(partRayVisibilityFlags({ material: lamp, rayVisibility: { shadow: false, volumeScatter: false } }), ALL_RAY_KINDS & ~16 & ~32);
+ for (const kind of ['diffuse', 'glossy', 'transmission']) {
+ assert.throws(() => partRayVisibilityFlags({ name: 'lamp', material: lamp, rayVisibility: { [kind]: false } }), /part "lamp" emits light and sets rayVisibility\.diffuse, glossy or transmission to false/);
+ }
+ assert.equal(partRayVisibilityFlags({ material: surface, rayVisibility: { diffuse: false } }), ALL_RAY_KINDS & ~2, 'a part that does not emit may hide from bounce rays');
+ const parts = [uniquePart('wall', 0), uniquePart('lamp', 2, { material: lamp, rayVisibility: { glossy: false } })];
+ assert.throws(() => buildTraceScene(parts, environment), /part "lamp" emits light/);
+ assert.throws(() => buildTraceScene(parts.map(part => ({ ...part, geometry: sharedBox })), environment, { instancing: true }), /part "lamp" emits light/);
});
test('buildTraceScene refuses a bad rayVisibility on both scene shapes', () => {
@@ -80,21 +105,30 @@ test('buildTraceScene refuses a bad rayVisibility on both scene shapes', () => {
assert.throws(() => buildTraceScene(instanced, environment, { instancing: true }), /unknown ray kind "bogus"/);
});
-test('an instanced scene carries visibility only on the parts that ask for it', () => {
- const scene = buildTraceScene([sharedPart('plain', 0), sharedPart('pane', 2, { castShadow: false }), sharedPart('glow', 4, { rayVisibility: { camera: false, shadow: false } })], environment, { instancing: true });
+test('an instanced scene carries visibility only on the parts that hide from a ray kind', () => {
+ const parts = [
+ sharedPart('plain', 0),
+ sharedPart('pane', 2, { rayVisibility: { shadow: false } }),
+ sharedPart('glow', 4, { rayVisibility: { camera: false, shadow: false } }),
+ sharedPart('empty', 6, { rayVisibility: {} }),
+ ];
+ const scene = buildTraceScene(parts, environment, { instancing: true });
assert.equal('visibilityFlags' in scene.instances[0], false, 'a default part adds no field');
assert.equal(scene.instances[1].visibilityFlags, SHADOW_OFF);
assert.equal(scene.instances[2].visibilityFlags, ALL_RAY_KINDS & ~1 & ~16);
+ assert.equal('visibilityFlags' in scene.instances[3], false, 'an empty rayVisibility is the default');
});
-test('a flattened scene carries one visibility byte per part, or none when no part asks', () => {
+test('a flattened scene carries one visibility byte per part, or none when no part hides from a ray kind', () => {
assert.equal(buildTraceScene([uniquePart('a', 0), uniquePart('b', 2, { shadowOnly: true })], environment).partRayVisibility, null);
- const scene = buildTraceScene([uniquePart('a', 0), uniquePart('b', 2, { castShadow: false }), uniquePart('c', 4, { shadowOnly: true, rayVisibility: { glossy: false } })], environment);
- assert.deepEqual([...scene.partRayVisibility], [ALL_RAY_KINDS, SHADOW_OFF, 62 & ~4]);
+ const hidingNothing = [uniquePart('a', 0, { rayVisibility: {} }), uniquePart('b', 2, { rayVisibility: { shadow: true, camera: true } })];
+ assert.equal(buildTraceScene(hidingNothing, environment).partRayVisibility, null);
+ const hiding = [uniquePart('a', 0), uniquePart('b', 2, { rayVisibility: { shadow: false } }), uniquePart('c', 4, { shadowOnly: true, rayVisibility: { glossy: false } })];
+ assert.deepEqual([...buildTraceScene(hiding, environment).partRayVisibility], [ALL_RAY_KINDS, SHADOW_OFF, 62 & ~4]);
});
test('a native render job packs the visibility of an instanced scene into the instance table', () => {
- const parts = [sharedPart('wall', 0), sharedPart('pane', 2, { castShadow: false }), sharedPart('wall2', 4)];
+ const parts = [sharedPart('wall', 0), sharedPart('pane', 2, { rayVisibility: { shadow: false } }), sharedPart('wall2', 4)];
const { exported, flags } = exportedVisibility(parts, true);
assert.equal(exported.instances, 3, 'the copies stay instances');
assert.deepEqual(flags, [ALL_RAY_KINDS, SHADOW_OFF, ALL_RAY_KINDS]);
@@ -107,30 +141,50 @@ test('a native render job packs the visibility of a flattened scene into the ins
assert.deepEqual(flags, [ALL_RAY_KINDS, SHADOW_OFF, 62]);
});
-test('scenes that ask for no visibility export the same tables whether or not shadowOnly is the only flag', () => {
+test('scenes whose rayVisibility hides nothing export the same tables as scenes without it', () => {
const plain = [uniquePart('wall', 0), uniquePart('lamp', 4, { shadowOnly: true })];
- const withDefaults = [uniquePart('wall', 0, { rayVisibility: {}, castShadow: true }), uniquePart('lamp', 4, { shadowOnly: true, rayVisibility: {} })];
+ const withDefaults = [uniquePart('wall', 0, { rayVisibility: {} }), uniquePart('lamp', 4, { shadowOnly: true, rayVisibility: { shadow: true } })];
assert.equal(digestOfTables(exportedVisibility(withDefaults, false).exported), digestOfTables(exportedVisibility(plain, false).exported));
const sharedPlain = [sharedPart('a', 0), sharedPart('b', 2, { shadowOnly: true })];
- const sharedDefaults = [sharedPart('a', 0, { rayVisibility: {} }), sharedPart('b', 2, { shadowOnly: true, rayVisibility: {} })];
+ const sharedDefaults = [sharedPart('a', 0, { rayVisibility: {} }), sharedPart('b', 2, { shadowOnly: true, rayVisibility: { camera: true } })];
assert.equal(digestOfTables(exportedVisibility(sharedDefaults, true).exported), digestOfTables(exportedVisibility(sharedPlain, true).exported));
});
-test('the v1 tables and a light bake refuse a flattened scene with part visibility instead of ignoring it', () => {
- const scene = buildTraceScene([uniquePart('wall', 0), uniquePart('pane', 2, { castShadow: false })], environment);
- assert.throws(() => buildNativeInput(scene, camera, options, pack), /cannot carry.*kernel "cycles"/);
- assert.throws(() => buildNativeTexelInput(scene, { texelCount: 4, samples: 4, bounces: 2, seed: 1 }, pack), /cannot carry/);
+function withoutRayVisibility(parts) {
+ return parts.map(({ rayVisibility, ...part }) => part);
+}
+
+test('the v1 tables of the legacy kernel refuse a hidden ray kind, and a light bake leaves it out', () => {
+ const hiding = [uniquePart('wall', 0), uniquePart('pane', 2, { rayVisibility: { shadow: false } })];
+ const scene = buildTraceScene(hiding, environment);
+ assert.throws(() => buildNativeInput(scene, camera, options, pack), /v1 tables of kernel "legacy" cannot carry.*kernel "cycles"/);
+ const bakeOptions = { texelCount: 4, samples: 4, bounces: 2, seed: 1 };
+ const plainScene = buildTraceScene(withoutRayVisibility(hiding), environment);
+ assert.deepEqual(buildNativeTexelInput(scene, bakeOptions, pack), buildNativeTexelInput(plainScene, bakeOptions, pack));
});
-test('a job on the legacy kernel refuses part visibility', () => {
- const parts = [uniquePart('wall', 0), uniquePart('pane', 2, { castShadow: false })];
+test('a job on the legacy kernel refuses a hidden ray kind', () => {
+ const parts = [uniquePart('wall', 0), uniquePart('pane', 2, { rayVisibility: { shadow: false } })];
assert.throws(
() => exportNativeSceneTables({ parts, environment, camera, options, kernel: 'legacy', instancing: false, modules }),
- /only the "cycles" kernel with FORMAT-v2 tables can carry/,
+ /only the "cycles" kernel can carry/,
);
});
-// The sun is a delta light: only a shadow ray can reach it, so a glass pane over the floor leaves the floor dark until the pane stops blocking shadow rays.
+test('the v1 fallback of a cycles job draws without the visibility and reports why', () => {
+ const parts = [uniquePart('wall', 0), uniquePart('pane', 2, { rayVisibility: { shadow: false } })];
+ const failingModules = { ...modules, buildFlattenedJobNativeInput: () => { throw new Error('forced material failure'); } };
+ const exported = exportNativeSceneTables({ parts, environment, camera, options, kernel: 'cycles', instancing: false, modules: failingModules });
+ assert.equal(exported.wholeMaterials, false);
+ assert.equal(exported.materialsReason, 'forced material failure');
+ assert.equal(exported.rayVisibility, 'ignored');
+ assert.equal(exported.rayVisibilityReason, 'forced material failure');
+ const withoutSetting = exportNativeSceneTables({ parts: withoutRayVisibility(parts), environment, camera, options, kernel: 'cycles', instancing: false, modules: failingModules });
+ assert.deepEqual(exported.tables, withoutSetting.tables);
+});
+
+// The sun is a delta light: only a shadow ray can reach it. Measured on the native kernel, the mean of the top-down picture
+// is about 5.6 with the clear pane blocking shadow rays (the floor is dimmer, not black) and about 9.3 once it does not.
const skipWithoutAddon = findNativeAddon() === null ? 'the native addon is not built' : false;
const SIZE = 16;
const sunEnvironment = { keyColor: [3, 3, 3], lightDirection: [0, 1, 0] };
@@ -165,12 +219,10 @@ for (const [shape, instancing, geometryFor] of [
['flattened', false, () => box(0, 1)],
['instanced', true, () => sharedBox],
]) {
- test(`the native cycles kernel lights the floor through a ${shape} pane with castShadow false`, { skip: skipWithoutAddon }, () => {
+ test(`the native cycles kernel lights the floor through a ${shape} pane with rayVisibility shadow false`, { skip: skipWithoutAddon }, () => {
const blocked = floorBrightness(paneOverFloor({}, geometryFor), instancing);
- const lit = floorBrightness(paneOverFloor({ castShadow: false }, geometryFor), instancing);
- const viaRayVisibility = floorBrightness(paneOverFloor({ rayVisibility: { shadow: false } }, geometryFor), instancing);
- // Measured on the native kernel: the mean of the pane-over-floor picture is 5.59 blocked and 9.30 with the pane out of the shadow rays' way.
+ const lit = floorBrightness(paneOverFloor({ rayVisibility: { shadow: false } }, geometryFor), instancing);
assert.ok(lit > blocked * 1.3, `shadow rays that pass the pane reach the sun: ${lit} against ${blocked}`);
- assert.ok(Math.abs(viaRayVisibility - lit) < lit * 0.01, `castShadow false and rayVisibility.shadow false are the same setting: ${viaRayVisibility} against ${lit}`);
+ assert.ok(lit - blocked > 2, `the sun reaches the floor through the pane: ${lit} less ${blocked}`);
});
}