665bfac0b339
raster_clip.rs
//! #1388: 3D text and shape layers rasterise only the part of the layer the output shows. Where
//! the whole raster fits its pixel budget the frame is identical to rasterising the whole layer;
//! close to the camera the raster stays small instead of growing to ~16 million pixels.
use effectcraft_color::Label;
use effectcraft_keyframe::{TextDoc, Value};
use effectcraft_project::build::{self, Ids};
use effectcraft_project::{Comp, ItemId, ItemKind, Layer, LayerSource, Project};
use effectcraft_time::{FrameRate, Tick};
use crate::{NoFootage, RenderOpts, Renderer};
const W: u32 = 400;
const H: u32 = 300;
/// The default camera's distance to the z = 0 plane.
fn zoom() -> f64 {
W as f64 * 50.0 / 36.0
}
fn setup() -> (Project, ItemId, Comp) {
let mut p = Project::default();
p.settings.bit_depth = effectcraft_project::BitDepth::Bpc32;
let comp = Comp::new(W, H, FrameRate::FPS_30, Tick::from_seconds_f64(1.0));
let cid = p.add_item("Comp", Label::Sandstone, None, ItemKind::Comp(comp.clone().into()));
(p, cid, comp)
}
fn set(l: &mut Layer, path: &str, v: Value) {
l.props.prop_mut(path).unwrap_or_else(|| panic!("no {path}")).value = v;
}
/// A 3D text layer at `pos`, turned `rot_y` degrees about Y.
fn text3(p: &mut Project, comp: &Comp, pos: [f64; 3], rot_y: f64) -> Layer {
let mut l = build::layer(p, comp, "Text", LayerSource::Text, (W, H), None);
l.props.prop_mut("text/sourceText").unwrap().value = Value::Text(Box::new(TextDoc { text: "NEAR CAMERA TEXT".into(), size: 60.0, ..Default::default() }));
l.switches.three_d = true;
set(&mut l, "transform/position", Value::Vec3(pos));
set(&mut l, "transform/rotationY", Value::Scalar(rot_y));
l
}
/// A 3D shape layer (a 300×120 rectangle with a stroke) at `pos`.
fn shape3(p: &mut Project, comp: &Comp, pos: [f64; 3]) -> Layer {
let mut l = build::layer(p, comp, "Shape", LayerSource::Shape, (W, H), None);
let mut next = p.next_id;
{
let mut ids = Ids(&mut next);
let r = build::shape_rect(&mut ids, [300.0, 120.0], [0.0, 0.0], 0.0);
let f = build::shape_fill(&mut ids, [0.9, 0.4, 0.1, 1.0]);
let s = build::shape_stroke(&mut ids, [1.0, 1.0, 1.0, 1.0], 6.0);
let g = build::shape_group(&mut ids, "Box", vec![r, f, s]);
l.props.sub_mut("contents").unwrap().children.push(g.into());
}
p.next_id = next;
l.switches.three_d = true;
set(&mut l, "transform/position", Value::Vec3(pos));
l
}
fn scene(l: impl FnOnce(&mut Project, &Comp) -> Layer) -> (Project, ItemId) {
let (mut p, cid, comp) = setup();
let layer = l(&mut p, &comp);
p.comp_mut(cid).unwrap().layers.push(layer);
(p, cid)
}
fn frame(p: &Project, cid: ItemId, whole: bool) -> effectcraft_raster::Image {
let mut r = Renderer::new(p, &NoFootage, RenderOpts::default());
r.whole_raster = whole;
r.comp_frame(cid, Tick::ZERO)
}
/// Pixels of the layer's processed buffer.
fn raster_px(p: &Project, cid: ItemId, whole: bool) -> u64 {
let mut r = Renderer::new(p, &NoFootage, RenderOpts::default());
r.whole_raster = whole;
let c = p.comp(cid).unwrap();
let ctx = r.eval_ctx(cid, Tick::ZERO).unwrap();
let b = r.layer_buf(&ctx, &c.layers[0]).unwrap();
b.img.width as u64 * b.img.height as u64
}
#[test]
fn the_visible_part_renders_the_same_frame_as_the_whole_layer() {
let cx = W as f64 / 2.0;
let cy = H as f64 / 2.0;
let cases: Vec<(&str, (Project, ItemId))> = vec![
("far", scene(|p, c| text3(p, c, [cx, cy, 300.0], 0.0))),
("in the frame plane", scene(|p, c| text3(p, c, [cx, cy, 0.0], 0.0))),
("past the frame edge", scene(|p, c| text3(p, c, [60.0, cy, -200.0], 0.0))),
("turned", scene(|p, c| text3(p, c, [cx, cy, -150.0], 55.0))),
("close to the camera", scene(|p, c| text3(p, c, [cx, cy, -zoom() + 40.0], 0.0))),
("partly behind the camera", scene(|p, c| text3(p, c, [cx, cy, -zoom() + 30.0], 80.0))),
("behind the camera", scene(|p, c| text3(p, c, [cx, cy, -zoom() - 200.0], 0.0))),
("shape", scene(|p, c| shape3(p, c, [cx + 150.0, cy, -250.0]))),
];
for (label, (p, cid)) in &cases {
let clipped = frame(p, *cid, false);
let whole = frame(p, *cid, true);
assert_eq!(clipped.data, whole.data, "{label}");
}
}
/// Close to the camera only part of the text shows: its raster is a fraction of the whole one
/// (millions of pixels), and the frame still shows text.
#[test]
fn text_close_to_the_camera_rasterises_what_shows() {
let (p, cid) = scene(|p, c| text3(p, c, [W as f64 / 2.0, H as f64 / 2.0, -zoom() + 40.0], 0.0));
let clipped = raster_px(&p, cid, false);
let whole = raster_px(&p, cid, true);
assert!(whole > 5_000_000, "the whole raster is huge ({whole} px)");
eprintln!("near camera: {clipped} px rasterised, {whole} px whole");
assert!(clipped * 10 < whole, "{clipped} px of {whole}");
let img = frame(&p, cid, false);
let covered = img.data.iter().filter(|px| px[3] > 0.5).count();
assert!(covered > (W * H / 20) as usize, "text shows ({covered} px)");
// Behind the camera there is nothing to rasterise.
let (p, cid) = scene(|p, c| text3(p, c, [W as f64 / 2.0, H as f64 / 2.0, -zoom() - 200.0], 0.0));
assert!(raster_px(&p, cid, false) <= 1);
}
/// The #1388 case at full size: 200 pt text in a 1920 × 1080 comp, close to the camera. Rasterised
/// whole it fills the ~16 million pixel cap; clipped, it stays within a few frames' worth of pixels
/// (and the text still shows).
#[test]
fn hd_text_close_to_the_camera_stays_within_a_few_frames() {
let mut p = Project::default();
let comp = Comp::new(1920, 1080, FrameRate::FPS_30, Tick::from_seconds_f64(1.0));
let cid = p.add_item("Comp", Label::Sandstone, None, ItemKind::Comp(comp.clone().into()));
let mut l = build::layer(&mut p, &comp, "Text", LayerSource::Text, (1920, 1080), None);
l.props.prop_mut("text/sourceText").unwrap().value = Value::Text(Box::new(TextDoc { text: "NEAR CAMERA".into(), size: 200.0, ..Default::default() }));
l.switches.three_d = true;
set(&mut l, "transform/position", Value::Vec3([960.0, 540.0, -1920.0 * 50.0 / 36.0 + 60.0]));
p.comp_mut(cid).unwrap().layers.push(l);
let (clipped, whole) = (raster_px(&p, cid, false), raster_px(&p, cid, true));
eprintln!("HD near camera: {clipped} px rasterised, {whole} px whole");
assert!(whole > 12_000_000, "{whole}");
assert!(clipped <= 4 * 1920 * 1080, "{clipped} px");
assert!(frame(&p, cid, false).data.iter().any(|px| px[3] > 0.5), "the text shows");
}
/// A slow move of the layer against the camera (a camera move does the same) keeps the part
/// rasterised within the same grid cells for several frames: they reuse the cached raster instead
/// of drawing the text again each frame.
#[test]
fn a_slow_move_reuses_the_clipped_raster() {
let cache = crate::LayerCache::default();
let at = |x: f64| {
let (p, cid) = scene(|p, c| text3(p, c, [x, H as f64 / 2.0, -zoom() + 40.0], 0.0));
let mut r = Renderer::new(&p, &NoFootage, RenderOpts::default());
r.cache = Some(&cache);
r.comp_frame(cid, Tick::ZERO);
};
at(W as f64 / 2.0);
let misses = cache.stats().misses;
// 16 frames, a quarter of a layer pixel apart (here about three output pixels).
for i in 1..=16 {
at(W as f64 / 2.0 + i as f64 * 0.25);
}
let rasters = cache.stats().misses - misses;
assert!(rasters <= 2, "{rasters} new rasters over 16 frames");
}
/// One keyframed motion: (seconds, value) pairs.
type Keys<'a> = &'a [(f64, [f64; 3])];
fn keyed(l: &mut Layer, path: &str, keys: Keys) {
l.props.prop_mut(path).unwrap_or_else(|| panic!("no {path}")).keys =
keys.iter().map(|(t, v)| effectcraft_keyframe::Keyframe::new(Tick::from_seconds_f64(*t), Value::Vec3(*v))).collect();
}
/// A camera keyed through `pos` / `poi`, and the text keyed through `text_pos` (and turning about
/// Y through `text_rot`): every frame of a second, rendered with the clipped raster and a layer
/// cache shared across the frames, matches rasterising the whole layer without a cache (or differs
/// by an anti-aliasing sub-sample or two on a few edge pixels) — except where the whole raster is held at
/// its pixel cap (softer than the clipped one, which isn't): there the text shows and the clipped
/// raster stays small.
fn moving(label: &str, pos: Keys, poi: Keys, text_pos: Keys, text_rot: &[(f64, f64)]) {
let (mut p, cid, comp) = setup();
let mut text = text3(&mut p, &comp, [W as f64 / 2.0, H as f64 / 2.0, 0.0], 0.0);
if !text_pos.is_empty() {
keyed(&mut text, "transform/position", text_pos);
}
if !text_rot.is_empty() {
text.props.prop_mut("transform/rotationY").unwrap().keys =
text_rot.iter().map(|(t, v)| effectcraft_keyframe::Keyframe::new(Tick::from_seconds_f64(*t), Value::Scalar(*v))).collect();
}
let mut cam = build::layer(&mut p, &comp, "Camera", LayerSource::Camera, (W, H), None);
set(&mut cam, "cameraOptions/zoom", Value::Scalar(zoom()));
keyed(&mut cam, "transform/position", pos);
keyed(&mut cam, "transform/poi", poi);
p.comp_mut(cid).unwrap().layers = vec![cam, text].into();
let cache = crate::LayerCache::default();
let (mut exact, mut near, mut capped) = (0, 0, 0);
for f in 0..30 {
let t = Tick::from_seconds_f64(f as f64 / 30.0);
let mut clipped = Renderer::new(&p, &NoFootage, RenderOpts::default());
clipped.cache = Some(&cache);
let mut whole = Renderer::new(&p, &NoFootage, RenderOpts::default());
whole.whole_raster = true;
let ctx = whole.eval_ctx(cid, t).unwrap();
let layer = &p.comp(cid).unwrap().layers[1];
let a = clipped.comp_frame(cid, t);
if clipped.raster_scale(&ctx, layer) == whole.raster_scale(&ctx, layer) {
let b = whole.comp_frame(cid, t);
if a.data == b.data {
exact += 1;
} else {
// The clipped raster places the glyphs at other coordinates (smaller ones: the whole
// raster can be thousands of pixels wide), and tiny-skia transforms them in f32: its
// 4 × 4 anti-aliasing may land a sub-sample or two differently on a few edge pixels.
let (n, worst) = a.data.iter().zip(&b.data).fold((0usize, 0.0f32), |(n, w), (p, q)| {
let d = (0..4).map(|i| (p[i] - q[i]).abs()).fold(0.0f32, f32::max);
(n + usize::from(d > 0.0), w.max(d))
});
assert!(worst <= 2.0 / 16.0 + 1e-4 && n * 1000 <= (W * H) as usize, "{label}: frame {f}: {n} px differ, by up to {worst}");
near += 1;
}
} else {
// Held at the cap whole: the clipped raster is sharper, and small.
let buf = clipped.layer_buf(&ctx, layer).unwrap();
assert!(buf.img.width as u64 * buf.img.height as u64 <= 16_500_000, "{label}: frame {f}");
let shows = |img: &effectcraft_raster::Image| img.data.iter().filter(|px| px[3] > 0.5).count();
let (sa, sb) = (shows(&a), shows(&whole.comp_frame(cid, t)));
// The same text shows (or none, the camera past it); coverage within a few percent.
assert!(sa.abs_diff(sb) * 50 <= sb.max(1) + 50, "{label}: frame {f}: {sa} px of text, {sb} rasterised whole");
capped += 1;
}
}
eprintln!("{label}: {exact} frames identical, {near} within anti-aliasing noise, {capped} sharper than the capped whole raster");
assert!(exact + near >= 10, "{label}: {exact} identical, {near} close, {capped} at the cap");
}
#[test]
fn a_camera_moving_any_way_renders_every_frame_as_the_whole_layer() {
let (cx, cy, z) = (W as f64 / 2.0, H as f64 / 2.0, -zoom());
let still = [(0.0, [cx, cy, 0.0])];
// In towards the text, through it and past it; and back out.
moving("dolly in through the text", &[(0.0, [cx, cy, 2.0 * z]), (1.0, [cx, cy, 150.0])], &[(0.0, [cx, cy, 400.0]), (1.0, [cx, cy, 700.0])], &[], &[]);
moving("dolly out", &[(0.0, [cx, cy, -60.0]), (1.0, [cx, cy, 3.0 * z])], &still, &[], &[]);
// Sideways and up and down close to the text, so it leaves the frame on both sides.
moving(
"pan x",
&[(0.0, [cx - 500.0, cy, -120.0]), (1.0, [cx + 500.0, cy, -120.0])],
&[(0.0, [cx - 500.0, cy, 0.0]), (1.0, [cx + 500.0, cy, 0.0])],
&[],
&[],
);
moving("pan y", &[(0.0, [cx, cy - 300.0, -90.0]), (1.0, [cx, cy + 300.0, -90.0])], &[(0.0, [cx, cy - 300.0, 0.0]), (1.0, [cx, cy + 300.0, 0.0])], &[], &[]);
// Around the text, close, looking at it.
let orbit: Vec<(f64, [f64; 3])> = (0..=8)
.map(|i| {
let a = i as f64 / 8.0 * std::f64::consts::TAU * 0.4 - 0.8;
(i as f64 / 8.0, [cx + 150.0 * a.sin(), cy, -150.0 * a.cos()])
})
.collect();
moving("orbit", &orbit, &still, &[], &[]);
// The text moves instead: towards the camera, past it, and across.
moving(
"text towards and past the camera",
&[(0.0, [cx, cy, z])],
&still,
&[(0.0, [cx + 200.0, cy - 80.0, 400.0]), (1.0, [cx - 150.0, cy + 60.0, z - 100.0])],
&[],
);
// Turning close to the camera.
moving("text turning near the camera", &[(0.0, [cx, cy, z])], &still, &[(0.0, [cx, cy, z + 70.0])], &[(0.0, -70.0), (1.0, 70.0)]);
}
/// Reads of a layer in its own space get the whole layer, not the part the frame shows: an effect
/// taking another layer as a parameter (Set Matte, stretched to fit, from hidden text close to the
/// camera), and the source the motion tracker analyses.
#[test]
fn layer_space_reads_get_the_whole_layer() {
let (mut p, cid, comp) = setup();
let mut text = text3(&mut p, &comp, [W as f64 / 2.0, H as f64 / 2.0, -zoom() + 40.0], 0.0);
text.switches.video = false;
let text_id = text.id;
let sid =
p.add_item("Solid", Label::Red, None, ItemKind::Solid(effectcraft_project::Solid { color: [0.2, 0.6, 1.0], width: W, height: H, pixel_aspect: 1.0 }));
let mut solid = build::layer(&mut p, &comp, "Solid", LayerSource::Solid { item: sid }, (W, H), None);
let spec = effectcraft_effects::find("ec.channel.setmatte").unwrap();
let mut next = p.next_id;
let mut g = effectcraft_effects::instantiate(spec, &mut Ids(&mut next), spec.name, [W as f64, H as f64]);
p.next_id = next;
g.prop_mut("takeMatteFromLayer").unwrap().value = Value::Layer(Some(text_id.0));
solid.props.sub_mut("effects").unwrap().children.push(g.into());
p.comp_mut(cid).unwrap().layers = vec![text, solid].into();
assert_eq!(frame(&p, cid, false).data, frame(&p, cid, true).data, "Set Matte from the text");
let r = Renderer::new(&p, &NoFootage, RenderOpts::default());
let ctx = r.eval_ctx(cid, Tick::ZERO).unwrap();
let layer = &p.comp(cid).unwrap().layers[0];
let mut whole = Renderer::new(&p, &NoFootage, RenderOpts::default());
whole.whole_raster = true;
assert_eq!(r.layer_source(&ctx, layer).unwrap().img, whole.layer_source(&ctx, layer).unwrap().img, "the tracker's source");
}
/// A layer whose pixels outside the frame can matter (an effect here) is rasterised whole.
#[test]
fn layers_with_effects_rasterise_whole() {
let (mut p, cid) = scene(|p, c| text3(p, c, [W as f64 / 2.0, H as f64 / 2.0, -zoom() + 40.0], 0.0));
let spec = effectcraft_effects::find("ec.blur.gaussian").unwrap();
let mut next = p.next_id;
let g = effectcraft_effects::instantiate(spec, &mut Ids(&mut next), spec.name, [W as f64, H as f64]);
p.next_id = next;
p.comp_mut(cid).unwrap().layers[0].props.sub_mut("effects").unwrap().children.push(g.into());
assert_eq!(raster_px(&p, cid, false), raster_px(&p, cid, true));
}
/// The Layer panel and analysis tools consume layer-space inputs, even with no effects.
#[test]
fn layer_panel_input_reads_the_whole_layer_behind_the_camera() {
let (p, cid) = scene(|p, c| shape3(p, c, [W as f64 / 2.0, H as f64 / 2.0, -zoom() - 200.0]));
let r = Renderer::new(&p, &NoFootage, RenderOpts::default());
let ctx = r.eval_ctx(cid, Tick::ZERO).unwrap();
let layer = &p.comp(cid).unwrap().layers[0];
let mut whole = Renderer::new(&p, &NoFootage, RenderOpts::default());
whole.whole_raster = true;
let expected = whole.layer_input(&ctx, layer, 0).unwrap();
assert!(expected.img.data.iter().any(|pixel| pixel[3] > 0.5));
assert_eq!(r.layer_input(&ctx, layer, 0).unwrap().img, expected.img);
}
#[test]
fn fine_clip_cells_have_distinct_cache_keys() {
let a = kurbo::Rect::new(0.0, 0.0, 1.0 / 128.0, 1.0 / 128.0);
let b = kurbo::Rect::new(1.0 / 128.0, 0.0, 2.0 / 128.0, 1.0 / 128.0);
let key = |clip| crate::pipeline::raster_clip_key(42, clip);
// All three clips rounded to identical coordinates in the old 1/16-unit key.
assert_ne!(key(a), key(b));
assert_ne!(key(a), key(kurbo::Rect::ZERO));
assert_ne!(key(b), key(kurbo::Rect::ZERO));
}
/// Text animator Blur reads beyond the fixed anti-aliasing padding of a clipped window.
#[test]
fn animated_text_blur_keeps_offscreen_glyph_pixels_while_panning() {
let (mut p, cid) = scene(|p, c| text3(p, c, [W as f64 / 2.0, H as f64 / 2.0, -zoom() + 40.0], 0.0));
let mut next = p.next_id;
let mut ids = Ids(&mut next);
let props = build::text_anim_props(&mut ids, "blur", false);
let mut animator = build::text_animator(&mut ids, "Blur", props);
animator.prop_mut("properties/blur").unwrap().value = Value::Vec2([40.0, 40.0]);
p.next_id = next;
p.comp_mut(cid).unwrap().layers[0].props.group_mut("text/animators").unwrap().children.push(animator.into());
let opts = RenderOpts { scale: 0.125, ..Default::default() };
let cache = crate::LayerCache::default();
for dx in [-10.0, 0.0, 10.0] {
set(&mut p.comp_mut(cid).unwrap().layers[0], "transform/position", Value::Vec3([W as f64 / 2.0 + dx, H as f64 / 2.0, -zoom() + 40.0]));
let mut r = Renderer::new(&p, &NoFootage, opts);
r.cache = Some(&cache);
let ctx = r.eval_ctx(cid, Tick::ZERO).unwrap();
let layer = &p.comp(cid).unwrap().layers[0];
assert!(r.raster_clip(&ctx, layer).is_none(), "animator blur needs off-window pixels");
let mut whole = Renderer::new(&p, &NoFootage, opts);
whole.whole_raster = true;
assert_eq!(r.comp_frame(cid, Tick::ZERO).data, whole.comp_frame(cid, Tick::ZERO).data);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.