EffectCraft: An open-source motion graphics and compositing tool written by scratch in pure Rust
Review fixes: the environment shadow follows the tinted radiance (#2436)
Z Usera8cba23edc11
diff --git a/crates/render/src/three_d/adv/scene.rs b/crates/render/src/three_d/adv/scene.rsindex ce572aaef..dfd35b048 100644--- a/crates/render/src/three_d/adv/scene.rs+++ b/crates/render/src/three_d/adv/scene.rs@@ -819,23 +819,27 @@ pub fn irradiance_map(sw: u32, sh: u32, src: &[[f32; 4]], w: u32, h: u32) -> Vecout}-/// The environment image's dominant direction and key strength: the radiance-weighted mean-/// texel direction (solid-angle weighted, rotation applied), or `([0; 3], 0.0)` when the image-/// is directionless (a uniform environment cancels to zero, and opposing bright regions that-/// cancel leave no mean either). The mean of a single bright spot+/// The environment image's dominant direction and key strength: the mean texel direction+/// weighted by the radiance the light actually emits — solid-angle weighted, rotation applied,+/// each texel's channels scaled by `tint` (the light's colour, `[1; 3]` for a white one) — or+/// `([0; 3], 0.0)` when that radiance is directionless (a uniform environment cancels to zero,+/// and opposing bright regions that cancel leave no mean either — though a chromatic one need+/// not stay directionless once tinted: a red light over equally bright red and blue opposite+/// regions removes the blue pull and points at the red one). The mean of a single bright spot/// on black points straight at it; a gradient points somewhere between its ends. The returned/// key fraction is the mean vector's length over the radiance weight — how directional the/// image is, 0 (uniform) to ~1 (a lone spot) — and is the most of its light an Environment/// light's shadow can remove.-pub(crate) fn dominant_direction(w: u32, h: u32, d: &[[f32; 4]], rot: f32) -> ([f32; 3], f32) {+pub(crate) fn dominant_direction(w: u32, h: u32, d: &[[f32; 4]], tint: [f32; 3], rot: f32) -> ([f32; 3], f32) {use super::shade::equirect_dir;let (mut x, mut y, mut z) = (0.0f32, 0.0f32, 0.0f32);let mut weight = 0.0f32;for (i, p) in d.iter().enumerate() {let (tx, ty) = ((i % w as usize) as u32, (i / w as usize) as u32);let (u, v) = ((tx as f32 + 0.5) / w as f32, (ty as f32 + 0.5) / h as f32);- // Luminance × solid angle (∝ sin θ).- let lum = (p[0] + p[1] + p[2]) * (v * std::f32::consts::PI).sin();+ // Tinted radiance × solid angle (∝ sin θ): the shadow must follow the light the+ // environment emits, not the raw texels.+ let lum = (p[0] * tint[0] + p[1] * tint[1] + p[2] * tint[2]) * (v * std::f32::consts::PI).sin();let dir = equirect_dir(u, v, rot);x += dir[0] * lum;y += dir[1] * lum;@@ -863,9 +867,16 @@ pub(crate) fn add_environment(shadow_darkness: f64,shadow_diffusion: f64,) {+ // Intensity × colour folded into the radiance (one scalar on the GPU): tint the texels.+ // A white (or off) light leaves them as they are.+ let k = (intensity[0] + intensity[1] + intensity[2]) / 3.0;+ let tint = if k > 0.0 && (intensity[0] != intensity[1] || intensity[1] != intensity[2]) { intensity.map(|c| c / k) } else { [1.0, 1.0, 1.0] };// The shadow direction and key strength from the full-resolution image, before the mip- // chain averages it — only a shadow-casting light reads them, so only one pays for the pass.- let (sun, key) = if casts_shadows { dominant_direction(w, h, &data, rotation) } else { ([0.0; 3], 0.0) };+ // chain averages it — only a shadow-casting light reads them, so only one pays for the+ // pass — and weighted by the tint, so the shadow follows the radiance the light emits:+ // opposing chromatic regions that cancel untinted need not cancel once the colour removes+ // one of them (a red light over equally bright red and blue sides shadows from the red).+ let (sun, key) = if casts_shadows { dominant_direction(w, h, &data, tint, rotation) } else { ([0.0; 3], 0.0) };// Radiance level 0 at most 1024 wide.let (mut w, mut h, mut d) = (w, h, data);while w > 1024 {@@ -888,10 +899,7 @@ pub(crate) fn add_environment(let (sw, sh, sd) = small.unwrap_or((w, h, d));let irr = irradiance_map(sw, sh, &sd, 32, 16);let ii = b.texture_from(32, 16, [0, 1], irr.into_iter()) as u32;- // Intensity × colour folded into the radiance (one scalar on the GPU): tint the texels.- let k = (intensity[0] + intensity[1] + intensity[2]) / 3.0;- if k > 0.0 && (intensity[0] != intensity[1] || intensity[1] != intensity[2]) {- let tint = intensity.map(|c| c / k);+ if tint != [1.0, 1.0, 1.0] {for t in first..=ii {let ti = b.s.textures[t as usize];for p in &mut b.s.texels[ti.offset as usize..(ti.offset + ti.width * ti.height) as usize] {diff --git a/crates/render/src/three_d/adv/tests.rs b/crates/render/src/three_d/adv/tests.rsindex fd3c615ea..3f97615f9 100644--- a/crates/render/src/three_d/adv/tests.rs+++ b/crates/render/src/three_d/adv/tests.rs@@ -74,9 +74,9 @@ fn constant_environment_has_constant_irradiance() {#[test]fn a_non_finite_environment_has_no_sun_direction() {let nan = vec![[f32::NAN; 4]; 8 * 4];- assert_eq!(dominant_direction(8, 4, &nan, 0.0), ([0.0; 3], 0.0));+ assert_eq!(dominant_direction(8, 4, &nan, [1.0; 3], 0.0), ([0.0; 3], 0.0));let inf = vec![[f32::INFINITY, 0.0, 0.0, 1.0]; 8 * 4];- assert_eq!(dominant_direction(8, 4, &inf, 0.0), ([0.0; 3], 0.0));+ assert_eq!(dominant_direction(8, 4, &inf, [1.0; 3], 0.0), ([0.0; 3], 0.0));}/// The key fraction: a uniform image is directionless (key 0), a lone bright spot on black is@@ -85,13 +85,13 @@ fn a_non_finite_environment_has_no_sun_direction() {#[test]fn environment_key_strength_tracks_directionality() {let uniform = vec![[0.5f32, 0.5, 0.5, 1.0]; 8 * 4];- assert_eq!(dominant_direction(8, 4, &uniform, 0.0).1, 0.0);+ assert_eq!(dominant_direction(8, 4, &uniform, [1.0; 3], 0.0).1, 0.0);let mut spot = vec![[0.0f32; 4]; 64 * 32];spot[16 * 64 + 32] = [1.0, 1.0, 1.0, 1.0];- let (_, key) = dominant_direction(64, 32, &spot, 0.0);+ let (_, key) = dominant_direction(64, 32, &spot, [1.0; 3], 0.0);assert!(key > 0.95, "a lone spot is almost fully directional: {key}");let (w, h, d) = scene::default_environment();- let (_, key) = dominant_direction(w, h, &d, 0.0);+ let (_, key) = dominant_direction(w, h, &d, [1.0; 3], 0.0);assert!((0.35..0.55).contains(&key), "the default studio is a broad key with fill: {key}");}@@ -110,18 +110,47 @@ fn opposing_bright_regions_cancel_to_no_shadow() {let (a, b) = ((15 * w + 16) as usize, (16 * w + 48) as usize);opposed[a] = [1.0, 1.0, 1.0, 1.0];opposed[b] = [1.0, 1.0, 1.0, 1.0];- assert_eq!(dominant_direction(w, h, &opposed, 0.0), ([0.0; 3], 0.0));+ assert_eq!(dominant_direction(w, h, &opposed, [1.0; 3], 0.0), ([0.0; 3], 0.0));// One side twice as bright: the mean points at the brighter spot with its share of the// weight (key = 1/3 — two parts against one).let mut tilted = opposed.clone();tilted[a] = [2.0, 2.0, 2.0, 1.0];- let (sun, key) = dominant_direction(w, h, &tilted, 0.0);+ let (sun, key) = dominant_direction(w, h, &tilted, [1.0; 3], 0.0);assert!(sun != [0.0; 3] && key > 0.3, "the brighter side wins: {sun:?} key {key}");let want = shade::equirect_dir(16.5 / 64.0, 15.5 / 32.0, 0.0);let dot = sun[0] * want[0] + sun[1] * want[1] + sun[2] * want[2];assert!(dot > 0.999, "the sun points at the brighter spot: {sun:?} vs {want:?}");}+/// #2436 review: the sun follows the tinted radiance, not the raw texels — equally bright red+/// and blue regions on exactly opposite texels cancel to a white light (no shadow), but the+/// red light's tint removes the blue side's pull, so the mean points straight at the red one+/// (a blue light, at the blue one): the shadow lands where the emitted light comes from.+#[test]+fn a_coloured_light_shadows_from_the_region_it_tints() {+ let (w, h) = (64u32, 32u32);+ let mut opposed = vec![[0.0f32; 4]; (w * h) as usize];+ // Rows 15 and 16 mirror about the equator, columns 16 and 48 half a width apart: the two+ // texel-centre directions are exactly opposite — equal solid-angle weight, opposite pull.+ let (a, b) = ((15 * w + 16) as usize, (16 * w + 48) as usize);+ opposed[a] = [1.0, 0.0, 0.0, 1.0];+ opposed[b] = [0.0, 0.0, 1.0, 1.0];+ // To a white light the channel sums are equal: they cancel, no shadow.+ assert_eq!(dominant_direction(w, h, &opposed, [1.0; 3], 0.0), ([0.0; 3], 0.0));+ // A red light's tint zeroes the blue texel's weight: the red one becomes a lone spot.+ // (Any positive scale of the tint — the normalised [3, 0, 0] included — points the same+ // way; only the channel ratios matter.)+ let (sun, key) = dominant_direction(w, h, &opposed, [1.0, 0.0, 0.0], 0.0);+ let want = shade::equirect_dir(16.5 / 64.0, 15.5 / 32.0, 0.0);+ let dot = sun[0] * want[0] + sun[1] * want[1] + sun[2] * want[2];+ assert!(dot > 0.999 && key > 0.95, "the red side wins: {sun:?} key {key}");+ // A blue light points at the blue one instead.+ let (sun, _) = dominant_direction(w, h, &opposed, [0.0, 0.0, 1.0], 0.0);+ let want = shade::equirect_dir(48.5 / 64.0, 16.5 / 32.0, 0.0);+ let dot = sun[0] * want[0] + sun[1] * want[1] + sun[2] * want[2];+ assert!(dot > 0.999, "the blue side wins: {sun:?}");+}+#[test]fn equirect_round_trip_and_env_brdf() {for (u, v) in [(0.1f32, 0.2f32), (0.5, 0.5), (0.9, 0.7)] {@@ -596,6 +625,83 @@ fn a_uniform_environment_casts_no_shadow() {assert_eq!(casting.data, off.data, "a directionless image casts no shadow");}+/// #2436 review: a chromatic environment under a coloured light — equally bright red and blue+/// regions on exactly opposite sides of the image cancel to a white light (it casts no+/// shadow), but the red Environment light's tint removes the blue region's pull, so the red+/// one becomes the key and casts the shadow the user asked for, from the red side.+#[test]+fn a_red_light_shadows_from_the_red_region_of_a_chromatic_environment() {+ let (mut p, cid) = project(200, 150);+ // The floor facing the camera, a sphere in front of it casting shadows only.+ add(&mut p, cid, LayerSource::Primitive { kind: PrimitiveKind::Plane }, |l| {+ set(l, "geometryOptions/width", Value::Scalar(400.0));+ set(l, "geometryOptions/height", Value::Scalar(400.0));+ set(l, "transform/position", Value::Vec3([100.0, 75.0, 110.0]));+ set(l, "materialOptions/baseColor", Value::Color([1.0, 1.0, 1.0, 1.0]));+ });+ add(&mut p, cid, LayerSource::Primitive { kind: PrimitiveKind::Sphere }, |l| {+ set(l, "geometryOptions/radius", Value::Scalar(30.0));+ set(l, "transform/position", Value::Vec3([100.0, 75.0, 50.0]));+ set(l, "materialOptions/castsShadows", Value::Enum(2));+ });+ // The Environment Layer: a black background with a red square and an equally bright blue+ // one at exactly antipodal image positions (the blue is the point mirror of the red through+ // the antipodal map x -> x + w/2, y -> h - y: centres (14.5, 44.5) and (114.5, 105.5) in a+ // 200x150 image, 20x20 each) — equal solid-angle weight, opposite pull. The red sits up,+ // left and toward the camera; the blue down, right and away from it.+ add(&mut p, cid, LayerSource::Shape, |l| {+ l.environment = true;+ let mut next = 10_000u64;+ let ids = &mut build::Ids(&mut next);+ // Contents stack like the AE timeline — the first group is on top — so the background+ // goes in last, under the red and blue squares (and its full-comp rect keeps the+ // layer buffer full-size: a shape layer's buffer otherwise crops to its content).+ let red_rect = build::shape_rect(ids, [20.0, 20.0], [-85.5, -30.5], 0.0);+ let red_fill = build::shape_fill(ids, [1.0, 0.0, 0.0, 1.0]);+ let red = build::shape_group(ids, "Red", vec![red_rect, red_fill]);+ let blue_rect = build::shape_rect(ids, [20.0, 20.0], [14.5, 30.5], 0.0);+ let blue_fill = build::shape_fill(ids, [0.0, 0.0, 1.0, 1.0]);+ let blue = build::shape_group(ids, "Blue", vec![blue_rect, blue_fill]);+ let bg_rect = build::shape_rect(ids, [200.0, 150.0], [0.0, 0.0], 0.0);+ let bg_fill = build::shape_fill(ids, [0.0, 0.0, 0.0, 1.0]);+ let bg = build::shape_group(ids, "BG", vec![bg_rect, bg_fill]);+ for g in [red, blue, bg] {+ l.props.sub_mut("contents").unwrap().children.push(g.into());+ }+ });+ // A white light over the chromatic image: the regions cancel — Cast Shadows changes+ // nothing, exactly like a directionless image.+ add(&mut p, cid, LayerSource::Light { kind: LightKind::Environment }, |l| {+ set(l, "lightOptions/castsShadows", Value::Bool(true));+ });+ let white_casting = render(&p, cid);+ let comp = p.comp_mut(cid).unwrap();+ set(comp.layers.iter_mut().find(|l| l.is_light()).unwrap(), "lightOptions/castsShadows", Value::Bool(false));+ let white_off = render(&p, cid);+ assert_eq!(white_casting.data, white_off.data, "a white light sees no dominant region in the opposed red and blue");+ // The red light: the tint removes the blue region, the red one shadows the sphere onto the+ // floor below and right of it (the shadow falls opposite the red region).+ let comp = p.comp_mut(cid).unwrap();+ let light = comp.layers.iter_mut().find(|l| l.is_light()).unwrap();+ set(light, "lightOptions/color", Value::Color([1.0, 0.0, 0.0, 1.0]));+ set(light, "lightOptions/castsShadows", Value::Bool(true));+ let img = render(&p, cid);+ let chan = |img: &crate::Image, x: usize, y: usize| img.data[y * 200 + x][0];+ let side = chan(&img, 25, 75);+ let (mut core, mut cx) = (f32::INFINITY, 0usize);+ for y in 100..150 {+ for x in 60..170 {+ if chan(&img, x, y) < core {+ core = chan(&img, x, y);+ cx = x;+ }+ }+ }+ assert!(side > 0.1, "the floor is lit red: {side}");+ assert!(core < side * 0.65, "the red region shadows the sphere onto the floor: {core} vs {side} at x {cx}");+ assert!(cx > 100, "the shadow is opposite the red region (right of the sphere): {cx}");+}+/// #2436: the default environment (no Source, no Environment Layer) is a dim studio — a mean/// of 0.3, not the 1.0 that would act like a 100 % white Ambient light and wash the scene out/// (After Effects' default does not) — and directional: its dominant region points up and@@ -613,7 +719,7 @@ fn default_environment_keeps_the_level_and_points_up() {weight += sa;}assert!((mean / weight - 0.3).abs() < 0.01, "dim studio mean: {}", mean / weight);- let (sun, key) = dominant_direction(w, h, &d, 0.0);+ let (sun, key) = dominant_direction(w, h, &d, [1.0; 3], 0.0);assert!(sun[1] < -0.5, "the key is up: {sun:?}");assert!(sun[2] < -0.3, "the key is toward the camera: {sun:?}");assert!(sun[0].abs() < 0.1, "symmetric left-right: {sun:?}");diff --git a/docs/agents.md b/docs/agents.mdindex 42e16c3ca..9effdf18a 100644--- a/docs/agents.md+++ b/docs/agents.md@@ -221,7 +221,10 @@ Things that tripped up a long agent-driven session (a multi-scene 3D piece builtlike the other lights: Cast Shadows shades the scene from the image's dominant bright region(the default environment's key, or a source image's brightest area; an image without asufficiently strong dominant direction has none — a uniform one, or opposing bright regions- that cancel — so it casts no shadow) — occluding only that key's share of the light, so the+ that cancel — so it casts no shadow) — the region weighted by the light's colour, so a+ coloured light shadows from the regions it actually lights (opposing red and blue regions+ cancel to a white light, but a red light's shadow comes from the red one) — occluding only+ that key's share of the light, so theshadow stays partial like After Effects' area-light shadows, and soft by default (a penumbraof at least 8 pixels or four map texels, plus Shadow Diffusion). It only lightsAdvanced 3D comps, so creating one (or changing a light's type to Environment) switches adiff --git a/docs/architecture.md b/docs/architecture.mdindex 76f4c6a84..105eb8736 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -165,7 +165,9 @@ mip chain with the split-sum environment BRDF fit), and percentage-closer-filter(spot: perspective, parallel: orthographic over the scene, point: six cube faces, environment:one orthographic from the image's dominant bright region — none only when the image lacks asufficiently strong dominant direction (a uniform one, or opposing bright regions that-cancel) — occluding only the image's directional key fraction of+cancel) — the region weighted by the light's colour, so a coloured light shadows from the+regions it actually lights (opposing red and blue regions cancel to a white light, but a red+light's shadow comes from the red one) — occluding only the image's directional key fraction ofthe light, so the shadow stays partial like After Effects' area-light shadows, with a softdefault penumbra of at least eight pixels or four map texels). A Source or Environment Layerthat fails to render — a deleted layer, missing footage — lights nothing: no silent fallback