Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add area-shapes and transparent-shadow reference scenes for disk and ellipse lights, spread and alpha shadows (#894)

Nguyen Xuan Ana117c11b78c0
diff --git a/bench/cycles-parity/cook-only-fields.mjs b/bench/cycles-parity/cook-only-fields.mjs
new file mode 100644
index 00000000..c8dc9dde
--- /dev/null
+++ b/bench/cycles-parity/cook-only-fields.mjs
@@ -0,0 +1,43 @@
+// Scene description fields that only the Cook `cycles` kernel (and Cycles, through render-cycles.py) read:
+// area light `shape` ('rectangle', 'disk' or 'ellipse') and `spread` (radians, 0.0001 to pi),
+// material `alphaMode: 'blend'` with `opacity` below 1 (a transparent shadow, as a Principled alpha below 1 in Cycles).
+// The rasterizer, the legacy kernel and the core bundle ignore them, so they are copied onto the trace scene here.
+export const AREA_LIGHT_SHAPES = ['rectangle', 'disk', 'ellipse'];
+
+function checkedShape(shape, label) {
+ if (!AREA_LIGHT_SHAPES.includes(shape)) {
+ throw new RangeError(`${label} shape must be one of ${AREA_LIGHT_SHAPES.join(', ')}, got ${JSON.stringify(shape)}.`);
+ }
+ return shape;
+}
+
+function checkedSpread(spread, label) {
+ if (typeof spread !== 'number' || !Number.isFinite(spread) || spread < 0.0001 || spread > Math.PI) {
+ throw new RangeError(`${label} spread must be between 0.0001 and pi radians, got ${spread}.`);
+ }
+ return spread;
+}
+
+export function applyCookOnlyFields(traceScene, parts, environment) {
+ const areaLights = environment.areaLights ?? [];
+ traceScene.lights.areas.forEach((resolvedLight, index) => {
+ const label = `Area light ${index}`;
+ const sourceLight = areaLights[index] ?? {};
+ if (sourceLight.shape !== undefined) {
+ resolvedLight.shape = checkedShape(sourceLight.shape, label);
+ }
+ if (sourceLight.spread !== undefined) {
+ resolvedLight.spread = checkedSpread(sourceLight.spread, label);
+ }
+ });
+ traceScene.materials.forEach((resolvedMaterial, index) => {
+ const sourceMaterial = parts[index]?.material ?? {};
+ const opacity = sourceMaterial.opacity;
+ const isBlended = sourceMaterial.alphaMode === 'blend' && opacity >= 0 && opacity < 1;
+ if (isBlended && !(resolvedMaterial.alphaCutoff > 0)) {
+ resolvedMaterial.alphaMode = 'blend';
+ resolvedMaterial.opacity = opacity;
+ }
+ });
+ return traceScene;
+}
diff --git a/bench/cycles-parity/render-cycles.py b/bench/cycles-parity/render-cycles.py
index d60bd158..5c7f2ce5 100644
--- a/bench/cycles-parity/render-cycles.py
+++ b/bench/cycles-parity/render-cycles.py
@@ -253,6 +253,8 @@ def build_blender_material(material_name, material_entry, has_vertex_colors, ima
principled_node.inputs["Transmission Weight"].default_value = 1.0
principled_node.inputs["IOR"].default_value = material_entry["liquid"]["ior"]
configure_principled_layers(material, principled_node, material_entry)
+ if material_entry.get("alphaMode") == "blend" and 0.0 <= material_entry.get("opacity", 1.0) < 1.0:
+ principled_node.inputs["Alpha"].default_value = material_entry["opacity"]
if material_entry.get("emission", 0.0) > 0.0:
emission_color = material_entry.get("emissiveColor", material_entry["color"])
set_linear_rgba_socket(principled_node.inputs["Emission Color"], emission_color)
@@ -352,9 +354,13 @@ def add_area_light(scene, light_index, area_entry):
light_data = bpy.data.lights.new(f"Area-{light_index}", "AREA")
light_data.energy = area_entry["intensity"] * WATTS_PER_AREA_INTENSITY
light_data.color = area_entry["color"]
- light_data.shape = "RECTANGLE"
+ shape_name = area_entry.get("shape", "rectangle")
+ light_data.shape = {"rectangle": "RECTANGLE", "disk": "DISK", "ellipse": "ELLIPSE"}[shape_name]
light_data.size = area_entry["width"]
- light_data.size_y = area_entry["height"]
+ if shape_name != "disk":
+ light_data.size_y = area_entry["height"]
+ if "spread" in area_entry:
+ light_data.spread = area_entry["spread"]
area_object = bpy.data.objects.new(f"Area-{light_index}", light_data)
area_object.location = convert_position_to_blender(area_entry["position"])
normal_vector = Vector(convert_position_to_blender(area_entry["direction"])).normalized()
diff --git a/bench/cycles-parity/trace-scene-many-lights.mjs b/bench/cycles-parity/trace-scene-many-lights.mjs
index e9b779de..624473e7 100644
--- a/bench/cycles-parity/trace-scene-many-lights.mjs
+++ b/bench/cycles-parity/trace-scene-many-lights.mjs
@@ -2,6 +2,7 @@
// The parity harness has no light links, so a scene with more lights is built in chunks of that size and the light lists are joined.
// Every joined light gets bit -1, which the native packer reads as "all groups", so no two lights share a link bit.
import { buildTraceScene, MAX_TRACE_LIGHTS } from '../../src/path-tracer-scene.js';
+import { applyCookOnlyFields } from './cook-only-fields.mjs';
const UNLINKED_LIGHT_BIT = -1;
@@ -28,7 +29,7 @@ function unlinkedLights(lights) {
export function buildTraceSceneWithManyLights(parts, environment) {
const analyticLights = listAnalyticLights(environment);
if (analyticLights.length <= MAX_TRACE_LIGHTS) {
- return buildTraceScene(parts, environment);
+ return applyCookOnlyFields(buildTraceScene(parts, environment), parts, environment);
}
const points = [];
const spots = [];
@@ -42,5 +43,5 @@ export function buildTraceSceneWithManyLights(parts, environment) {
}
const traceScene = buildTraceScene(parts, { ...environment, pointLights: [], spotLights: [], areaLights: [] });
traceScene.lights = { sun: traceScene.lights.sun, points, spots, areas };
- return traceScene;
+ return applyCookOnlyFields(traceScene, parts, environment);
}
diff --git a/bench/reference/scenes.js b/bench/reference/scenes.js
index 3851c0bb..367789e9 100644
--- a/bench/reference/scenes.js
+++ b/bench/reference/scenes.js
@@ -996,6 +996,57 @@ export const REFERENCE_SCENES = {
};
},
+ // Issue #894: a disk, an ellipse with spread and a square with spread over glossy and rough surfaces. Only the Cook `cycles` kernel
+ // and Cycles read `shape` and `spread`; the rasterizer and the legacy kernel draw rectangles.
+ async 'area-shapes'() {
+ const lighting = constantLighting(0.01);
+ const cube = box(0, 1);
+ const parts = [
+ part('stage-floor', cube, [0, -0.05, 0], [10, 0.1, 10], { color: [0.6, 0.55, 0.5], roughness: 0.35 }),
+ part('stage-back', cube, [0, 1.5, -3.05], [10, 3.2, 0.1], { color: [0.7, 0.68, 0.62], roughness: 0.9 }),
+ part('column', cube, [-1.2, 0.75, -1.2], [0.4, 1.5, 0.4], { color: [0.6, 0.6, 0.65], roughness: 0.5 }),
+ part('ball', sphere(48, 32), [0.5, 0.5, -0.6], [0.5, 0.5, 0.5], { color: [0.8, 0.25, 0.2], roughness: 0.25 }),
+ part('block', cube, [1.7, 0.3, -1.4], [0.6, 0.6, 0.6], { color: [0.2, 0.45, 0.75], roughness: 0.6 }),
+ ];
+ const areaLights = [
+ { position: [-1.8, 2.6, 0.4], direction: [0.5, -1, -0.2], width: 0.9, height: 0.9, shape: 'disk', color: [1, 0.9, 0.8], intensity: 8 },
+ { position: [1.8, 2.4, 0.3], direction: [-0.4, -1, -0.1], up: [0, 0, 1], width: 1.6, height: 0.6, shape: 'ellipse', spread: 1.2, color: [0.8, 0.9, 1], intensity: 10 },
+ { position: [0, 3, -1.4], direction: [0, -1, 0.3], up: [0, 0, 1], width: 1.2, height: 1.2, spread: 0.9, color: [1, 1, 1], intensity: 10 },
+ ];
+ return {
+ parts, blenderWorld: lighting.blenderWorld,
+ environment: environment(lighting, { areaLights }),
+ camera: { eye: [0, 1.8, 4.5], target: [0, 0.7, -1], up: [0, 1, 0], fov: 50, near: 0.05, far: 50 },
+ };
+ },
+
+ // Issue #894: two blended panes (opacity 0.4 and 0.75) between the lights and the floor. Shadow rays pass through them with
+ // 1 - opacity of the light left, as Cycles does for a Principled alpha below 1.
+ async 'transparent-shadow'() {
+ const lighting = constantLighting(0.01);
+ const cube = box(0, 1);
+ const pane = opacity => ({ color: [0.9, 0.5, 0.3], roughness: 0.4, alphaMode: 'blend', opacity });
+ const parts = [
+ part('stage-floor', cube, [0, -0.05, 0], [10, 0.1, 10], { color: [0.6, 0.55, 0.5], roughness: 0.7 }),
+ part('stage-back', cube, [0, 1.5, -3.05], [10, 3.2, 0.1], { color: [0.7, 0.68, 0.62], roughness: 0.9 }),
+ part('ball', sphere(48, 32), [0, 0.5, -0.8], [0.5, 0.5, 0.5], { color: [0.3, 0.55, 0.8], roughness: 0.5 }),
+ part('pane-faint', cube, [-1.1, 1.6, 0.2], [1.2, 0.03, 1.2], pane(0.4)),
+ part('pane-dense', cube, [1.1, 1.6, 0.2], [1.2, 0.03, 1.2], pane(0.75)),
+ ];
+ const pointLights = [
+ { position: [-1.1, 3.2, 0.2], color: [1, 0.95, 0.85], intensity: 30, radius: 0.1, castShadow: true },
+ { position: [1.1, 3.2, 0.2], color: [0.85, 0.92, 1], intensity: 30, radius: 0.1, castShadow: true },
+ ];
+ const areaLights = [
+ { position: [0, 3, -1.6], direction: [0, -1, 0.3], up: [0, 0, 1], width: 1.5, height: 0.8, color: [1, 1, 1], intensity: 4 },
+ ];
+ return {
+ parts, blenderWorld: lighting.blenderWorld,
+ environment: environment(lighting, { pointLights, areaLights }),
+ camera: { eye: [0, 1.8, 4.5], target: [0, 0.7, -0.5], up: [0, 1, 0], fov: 50, near: 0.05, far: 50 },
+ };
+ },
+
// Issue #623: a 36 m corridor with 24 lamps (16 point, 8 spot) along the ceiling and nothing else lighting it, so most lamps are far from
// any point and a light tree has something to choose. The lamps do not cast shadow maps (the rasterizer's atlas holds 24 tiles); the path tracer and Cycles shadow every light.
async 'many-lights'() {
diff --git a/changes/894-remaining.md b/changes/894-remaining.md
new file mode 100644
index 00000000..238ab4fb
--- /dev/null
+++ b/changes/894-remaining.md
@@ -0,0 +1 @@
+- The Cook `cycles` kernel reads area light `shape` (disk, ellipse) and `spread` and a blended material's `opacity` (transparent shadows) from the parity scene description, with two new reference scenes (#894)
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index 1d490507..8152ae37 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -526,3 +526,14 @@ uv run --no-project --with numpy --with psutil python bench/cycles-parity/run-m0
```
`bench/cycles-parity/make-many-lights-scene.mjs <scene.json> <out.json> --count 500` writes a copy of an exported scene with that many small point lights, and `bench/cycles-parity/measure-sampler-noise.py <scene.json> <outDir> --compare sampler|light-tree` measures relMSE per sample count for `white` against `sobol-burley`, or for `uniform` against `tree`, against a high-sample reference with its own seed.
+
+## Area light shapes, spread and transparent shadows (#894)
+
+The `cycles` kernel already had disk and ellipse area lights (`lgt_sample_area_light` and the emitter-hit branch in `lights.wgsl`, translated from `kernel/light/area.h`), the spread attenuation (`area_light_spread_attenuation`) and transparent shadow rays (`int_trace_shadow` in `integrator.wgsl`, after `kernel/integrator/shade_shadow.h`). They were packed (`tests/native-pack-v2.test.js`) but no scene description could reach them and no Cycles reference exercised them. This change lets the parity harness reach them and adds the scenes `[source]`:
+
+- A reference scene's area light takes `shape` (`rectangle`, the default, `disk` or `ellipse`) and `spread` (radians, `0.0001` to pi, pi is the default). `width` and `height` are the two axes; a disk is an ellipse, so give it a `height` equal to its `width` (the diameter), as Blender does. A material with `alphaMode: 'blend'` and `opacity` below 1 is a blended material: shadow rays through it keep `1 - opacity` of the light, like a Principled alpha below 1 in Cycles; without `alphaMode: 'blend'`, `opacity` is ignored as before. [`bench/cycles-parity/cook-only-fields.mjs`](../bench/cycles-parity/cook-only-fields.mjs) copies these onto the trace scene (and rejects a bad shape or spread with the allowed values in the message), so the core bundle, the rasterizer and the legacy kernel are untouched and ignore them.
+- `render-cycles.py` builds the same shapes, spread and alpha in Blender.
+- Reference scenes `area-shapes` (a disk, an ellipse with spread 1.2 and a square with spread 0.9 over a glossy floor, a ball, a column and a block) and `transparent-shadow` (two blended panes of opacity 0.4 and 0.75 under two sphere lights and a rectangle light) are in `bench/reference/scenes.js`. They are not in `run-m1-parity.py`'s default list: pass `--scenes area-shapes,transparent-shadow` once their Cycles references exist.
+- `tests/cycles-area-shapes-parity.test.js` checks the packed light types, the spread terms, the radiance per area, the blended material records and that opaque materials and rectangle lights resolve as before.
+
+Not measured: no Cycles reference exists for these two scenes yet and Cook has not been compared with Cycles on them. The Modal workspace stopped with "exceeded its spend limit" when the run was started, so the 4096 spp references (seeds 1 and 2), the Cook runs and the lit-interior re-render are still to do. The Modal function that does all of that in one container is `finish_894_parity` in the harness outside the repository; `render-cycles.py --samples 4096 --seed 1|2` and `trace-native.mjs --kernel cycles --samples 4096` are the commands it runs. Until then these features are implemented and unit-tested, not proven against Cycles.
diff --git a/tests/cycles-area-shapes-parity.test.js b/tests/cycles-area-shapes-parity.test.js
new file mode 100644
index 00000000..90c876b8
--- /dev/null
+++ b/tests/cycles-area-shapes-parity.test.js
@@ -0,0 +1,91 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createCamera } from '../src/path-tracer.js';
+import * as packModule from '../src/path-tracer-gpu-pack.js';
+import { buildTraceScene } from '../src/path-tracer-scene.js';
+import { buildNativeInputV2, STRUCT_STRIDES_V2 } from '../packages/render-native/index.mjs';
+import { loadReferenceScene } from '../bench/cycles-parity/scene-bridge.mjs';
+import { applyCookOnlyFields } from '../bench/cycles-parity/cook-only-fields.mjs';
+import { buildTraceSceneWithManyLights } from '../bench/cycles-parity/trace-scene-many-lights.mjs';
+
+const LIGHT_TYPE_AREA_RECT = 2;
+const LIGHT_TYPE_AREA_DISK = 3;
+const ALPHA_MODE_BLEND = 2;
+const MATERIAL_FLAG_TRANSPARENT_SHADOW = 4;
+
+function viewRecord(bytes, stride, index) {
+ const offset = bytes.byteOffset + index * stride;
+ return { f32: new Float32Array(bytes.buffer, offset, stride / 4), u32: new Uint32Array(bytes.buffer, offset, stride / 4) };
+}
+
+async function packReferenceScene(sceneId) {
+ const { traceSource } = await loadReferenceScene(sceneId);
+ const traceScene = buildTraceSceneWithManyLights(traceSource.parts, traceSource.environment);
+ const camera = createCamera(traceSource.camera, 32, 18);
+ const nativeInput = buildNativeInputV2(traceScene, camera, { width: 32, height: 18, bounces: 8, seed: 1, parts: traceSource.parts }, packModule);
+ return { traceSource, traceScene, nativeInput };
+}
+
+const triangle = {
+ positions: new Float32Array([0, 0, 0, 1, 0, 0, 0, 1, 0]),
+ normals: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
+ indices: new Uint32Array([0, 1, 2]),
+};
+const identity = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+const rectangleLight = { position: [0, 2, 0], direction: [0, -1, 0], width: 1, height: 1, color: [1, 1, 1], intensity: 1 };
+
+test('area-shapes packs a disk, an ellipse with spread and a rectangle with spread', async () => {
+ const { traceSource, traceScene, nativeInput } = await packReferenceScene('area-shapes');
+ assert.deepEqual(traceScene.lights.areas.map(light => light.shape), ['disk', 'ellipse', undefined]);
+ assert.equal(nativeInput.lightCount, 3);
+ const [disk, ellipse, rectangle] = [0, 1, 2].map(index => viewRecord(nativeInput.lights, STRUCT_STRIDES_V2.light, index));
+ assert.equal(disk.u32[3], LIGHT_TYPE_AREA_DISK);
+ assert.equal(ellipse.u32[3], LIGHT_TYPE_AREA_DISK);
+ assert.equal(rectangle.u32[3], LIGHT_TYPE_AREA_RECT);
+ assert.equal(disk.f32[22], 0, 'no spread given: tan_half_spread stays 0');
+ const ellipseSpread = traceSource.environment.areaLights[1].spread;
+ const halfSpread = ellipseSpread / 2;
+ assert.ok(Math.abs(ellipse.f32[22] - Math.tan(halfSpread)) < 1e-6);
+ assert.ok(Math.abs(ellipse.f32[23] - 1 / (Math.tan(halfSpread) - halfSpread)) < 1e-4);
+ assert.ok(rectangle.f32[22] > 0 && rectangle.f32[23] > 0);
+ // Radiance is intensity over the emitting area, which for a disk or an ellipse is pi / 4 of its bounding box.
+ const diskArea = Math.PI * 0.25 * 0.9 * 0.9;
+ assert.ok(Math.abs(disk.f32[4] - (1.0 * 8) / diskArea) < 1e-3);
+ const ellipseArea = Math.PI * 0.25 * 1.6 * 0.6;
+ assert.ok(Math.abs(ellipse.f32[5] - (0.9 * 10) / ellipseArea) < 1e-3);
+});
+
+test('transparent-shadow packs blended panes that let shadow rays through', async () => {
+ const { traceScene, nativeInput } = await packReferenceScene('transparent-shadow');
+ const blended = traceScene.materials.filter(material => material.alphaMode === 'blend');
+ assert.deepEqual(blended.map(material => material.opacity).sort(), [0.4, 0.75]);
+ const records = Array.from({ length: nativeInput.materialCount }, (_, index) => viewRecord(nativeInput.materials, STRUCT_STRIDES_V2.material, index));
+ const blendRecords = records.filter(record => record.u32[49] === ALPHA_MODE_BLEND);
+ assert.equal(blendRecords.length, 2);
+ for (const record of blendRecords) {
+ assert.ok(record.f32[14] === Math.fround(0.4) || record.f32[14] === Math.fround(0.75));
+ assert.equal(record.u32[48] & MATERIAL_FLAG_TRANSPARENT_SHADOW, MATERIAL_FLAG_TRANSPARENT_SHADOW);
+ }
+});
+
+test('opacity without alphaMode blend and rectangle lights without a shape are left as they were', () => {
+ const environment = { world: true, pointLights: [], spotLights: [], areaLights: [rectangleLight] };
+ const parts = [{ name: 'a', geometry: triangle, matrix: identity, material: { color: [1, 1, 1], opacity: 0.5 } }];
+ const scene = applyCookOnlyFields(buildTraceScene(parts, environment), parts, environment);
+ assert.equal('alphaMode' in scene.materials[0], false);
+ assert.equal('opacity' in scene.materials[0], false);
+ assert.equal('shape' in scene.lights.areas[0], false);
+ assert.equal('spread' in scene.lights.areas[0], false);
+});
+
+test('an area light shape or spread outside the allowed values is an error that names the options', () => {
+ const parts = [{ name: 'a', geometry: triangle, matrix: identity, material: { color: [1, 1, 1] } }];
+ const build = light => {
+ const environment = { world: true, pointLights: [], spotLights: [], areaLights: [light] };
+ return applyCookOnlyFields(buildTraceScene(parts, environment), parts, environment);
+ };
+ assert.throws(() => build({ ...rectangleLight, shape: 'triangle' }), /rectangle, disk, ellipse/);
+ assert.throws(() => build({ ...rectangleLight, spread: 4 }), /spread must be between/);
+ assert.throws(() => build({ ...rectangleLight, spread: 0 }), /spread must be between/);
+ assert.doesNotThrow(() => build({ ...rectangleLight, shape: 'ellipse', spread: Math.PI / 2 }));
+});