From c3464f640fa367c5a6a9e60fe5ade2497e48a623 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sun, 8 Nov 2026 13:24:22 +0100 Subject: [PATCH] Footage cache (#3271): channel selection is static, and only the channels picked are read The parameters that pick which channels or Cryptomatte layer an effect reads (EXtractoR's Red/Green/Blue/Alpha, Cryptomatte's Layer and Layer Name, 3D Channel Extract's 3D Channel, ID Matte's Aux. Channel and Use Coverage, IDentifier's Channel Type) are static, as in After Effects where they have no stopwatch: no keyframes, no expression (prop.addKey, prop.toggleKey, prop.toggleAnimation and prop.setExpression refuse; prop.set changes the value). A document or an import that animated one keeps its first value and says so (a toast on open, a loss on .aep import). With that, what a frame reads is known from the values alone: the 'all channels' fallbacks for moving parameters and for effects that don't declare are gone (every channel effect declares; a test holds them to it), and a layer whose effects read no channels asks for none. Tests: the parameters refuse keys and expressions and the need is exactly the channel picked; a keyed channel selection opens static with its first value and is reported (both fail on the old code); the migration keeps the first key's value. --- crates/aep/src/import/effects.rs | 9 ++++ crates/effects/src/channel3d.rs | 36 +++++++++++++ crates/effects/src/lib.rs | 6 ++- crates/effects/src/migrate.rs | 47 +++++++++++++++++ crates/engine/src/cmd/effect.rs | 7 ++- crates/engine/src/cmd/prop.rs | 15 +++++- crates/engine/src/session/edit.rs | 19 +++++-- crates/engine/src/session/render.rs | 20 ++++---- crates/engine/src/tests/aux_footage.rs | 71 ++++++++++++++++++++++++++ crates/render/src/accel.rs | 8 +-- docs/effects.md | 2 + docs/footage.md | 20 ++++++-- 12 files changed, 231 insertions(+), 29 deletions(-) diff --git a/crates/aep/src/import/effects.rs b/crates/aep/src/import/effects.rs index b097c3600..1e89d916a 100644 --- a/crates/aep/src/import/effects.rs +++ b/crates/aep/src/import/effects.rs @@ -122,6 +122,15 @@ pub(crate) fn import_effects<'f, 'a>( import_param(&fx, map, p, cx, &shown, ParamOut { group: &mut group, refs: &mut *refs, col: &mut *col }); } } + // Channel selection is static, as in After Effects (which can't animate it either): a + // key or an expression there can't come from After Effects; defensively, the first + // value is kept and the rest reported. + for name in effectcraft_effects::migrate::static_channel_params(spec, &mut group) { + col.lose( + LossCategory::Effects, + format!("{}: '{}' effect '{shown}': keyframes or an expression on the channel selection {name} are not imported (it can't be animated), first value used", cx.comp, cx.layer), + ); + } col.imported.effects = col.imported.effects.saturating_add(1); target.children.push(Node::Group(group)); } diff --git a/crates/effects/src/channel3d.rs b/crates/effects/src/channel3d.rs index b822ca717..9fe5fb055 100644 --- a/crates/effects/src/channel3d.rs +++ b/crates/effects/src/channel3d.rs @@ -43,6 +43,22 @@ const READS_AUX: [&str; 8] = [ "ec.3d.identifier", ]; +/// The parameters that pick which channels or which Cryptomatte layer an effect reads. They +/// can't be animated (no stopwatch, no keyframes, no expression), as in After Effects: the +/// channels a frame needs are known before it renders, from these values alone (#3271). +const CHANNEL_PARAMS: [(&str, &[&str]); 5] = [ + ("ec.3d.channelextract", &["channel"]), + ("ec.3d.cryptomatte", &["layer", "layerName"]), + ("ec.3d.extractor", &["red", "green", "blue", "alpha"]), + ("ec.3d.idmatte", &["auxChannel", "useCoverage"]), + ("ec.3d.identifier", &["channelType"]), +]; + +/// Does parameter `param` of effect `effect` pick the channels it reads ([`CHANNEL_PARAMS`])? +pub fn selects_channels(effect: &str, param: &str) -> bool { + CHANNEL_PARAMS.iter().any(|(e, ps)| *e == effect && ps.contains(¶m)) +} + /// Does effect `id` read its layer's auxiliary channels ([`crate::EffectHost::aux`])? The media /// layer then decodes the footage's picture together with its channels (#474). pub fn reads_aux(id: &str) -> bool { @@ -88,6 +104,12 @@ pub fn aux_needs(id: &str, params: &crate::Params) -> Option> { }) } +/// [`aux_needs`] as an [`AuxNeed`]: what effect `id` reads, nothing for an effect that reads no +/// channels (every effect that does declares its lookups; a test holds them to it). +pub fn aux_need(id: &str, params: &crate::Params) -> effectcraft_raster::channels3d::AuxNeed { + effectcraft_raster::channels3d::AuxNeed::Lookups(aux_needs(id, params).unwrap_or_default()) +} + /// How far effect `id` with `params` reaches around a pixel of its layer (layer pixels), for /// reading only the footage rows a region of interest shows (#3271): `Some(0)` for effects whose /// pixel depends on that pixel alone, `None` for every other (it may read anywhere). @@ -793,3 +815,17 @@ pub fn specs() -> Vec { #[cfg(test)] mod tests; + +#[cfg(test)] +mod aux_need_tests { + /// #3271: every effect that reads its layer's channels says which (else a frame would read + /// all of them, or none). + #[test] + fn every_channel_effect_declares_what_it_reads() { + for id in super::READS_AUX { + let spec = crate::find(id).expect("an effect"); + let params = crate::Params { values: spec.params.iter().map(|p| (p.id.to_string(), p.default.clone())).collect() }; + assert!(super::aux_needs(id, ¶ms).is_some(), "{id}"); + } + } +} diff --git a/crates/effects/src/lib.rs b/crates/effects/src/lib.rs index 5e5a97343..864d72417 100644 --- a/crates/effects/src/lib.rs +++ b/crates/effects/src/lib.rs @@ -116,8 +116,8 @@ pub use time_fx::{PixelMotion, TimewarpPlan, TwStep, pmb_plan, posterized_time, pub use ocio::color_stabilizer_maps; // GPU effects, part B (3D Channel, Immersive Video, colour management, simulation render passes). pub use channel3d::{ - CRYPTO_LAYERS, CryptoAux, MATTE_ONLY_IN_ALPHA, aux_needs, aux_point, crypto_aux_image, crypto_aux_image_with, crypto_layer_choices, crypto_layer_menu, - crypto_layer_name, crypto_layer_named, id_color, matte_only_px, pixel_margin, reads_aux, selection_hashes, + CRYPTO_LAYERS, CryptoAux, MATTE_ONLY_IN_ALPHA, aux_need, aux_needs, aux_point, crypto_aux_image, crypto_aux_image_with, crypto_layer_choices, + crypto_layer_menu, crypto_layer_name, crypto_layer_named, id_color, matte_only_px, pixel_margin, reads_aux, selection_hashes, }; pub use ocio::{ColorOp, Straight, Tf, color_program}; pub use sim::{Acc, Blob, Bubble, Post, Shape, Sprite, SpritePlan, Tint, bubble_list, bubble_sample_bounds, drizzle_drops, mercury_blobs, sprite_plan}; @@ -835,6 +835,8 @@ pub fn instantiate(spec: &EffectSpec, ids: &mut Ids, instance_name: &str, layer_ if matches!(ps.ui, ParamUi::Checkbox | ParamUi::Popup { .. } | ParamUi::Layer) { pr.hold_only = true; } + // (the channels an effect reads: not animatable, as in After Effects) + pr.static_only = channel3d::selects_channels(spec.id, ps.id); match path.and_then(|path| nested_group(&mut g, ids, path)) { Some(sub) => sub.children.push(pr.into()), None => g.children.push(pr.into()), diff --git a/crates/effects/src/migrate.rs b/crates/effects/src/migrate.rs index 59daca49d..fadcf301d 100644 --- a/crates/effects/src/migrate.rs +++ b/crates/effects/src/migrate.rs @@ -348,6 +348,29 @@ pub fn upgrade_instance(spec: &EffectSpec, g: &mut PropGroup, ids: &mut Ids, lay *g != before } +/// Make the channel-selection parameters of the saved instance `g` of `spec` static +/// ([`crate::channel3d::selects_channels`]: not animatable, as in After Effects). Keyframes or an +/// expression on one (a project from before, or an import) are dropped: it keeps the value of +/// its first keyframe (else its static value). Returns the names of the parameters that lost +/// their animation. +pub fn static_channel_params(spec: &EffectSpec, g: &mut PropGroup) -> Vec { + let mut lost = vec![]; + for ps in spec.params.iter().filter(|ps| crate::channel3d::selects_channels(spec.id, ps.id)) { + let Some(pr) = prop_at(g, ps.id) else { continue }; + pr.static_only = true; + if pr.keys.is_empty() && pr.expr.is_none() { + continue; + } + if let Some(first) = pr.keys.first() { + pr.value = first.value.clone(); + } + pr.keys.clear(); + pr.expr = None; + lost.push(pr.name.clone()); + } + lost +} + /// The spec id of the parameter that an instance of `spec` saved at `id` (`a/b/param`) is now: /// `id` itself when the spec still has it, the new id of a renamed parameter /// ([`PARAM_ID_ALIASES`]), or the twirl-down path of a top-level parameter that moved into a @@ -484,6 +507,30 @@ mod tests { use super::*; use crate::{find, instantiate}; + /// #3271: an import or an older document with a keyed or scripted channel selection + /// (Cryptomatte's Layer) keeps the first key's value, static, and names what it lost. + #[test] + fn channel_selection_becomes_static() { + let spec = find("ec.3d.cryptomatte").unwrap(); + let mut next = 1; + let mut g = instantiate(spec, &mut Ids(&mut next), "Cryptomatte", [100.0, 50.0]); + assert!(static_channel_params(spec, &mut g).is_empty(), "a fresh instance loses nothing"); + let pr = g.get_mut("layer").unwrap(); + assert!(pr.static_only, "no stopwatch"); + pr.static_only = false; + // (keys at 0 s and 1 s) + let first = effectcraft_keyframe::Keyframe::new(Default::default(), Value::Enum(2)); + let mut second = effectcraft_keyframe::Keyframe::new(Default::default(), Value::Enum(0)); + second.time.0 = 254_016_000_000; + pr.keys = vec![first, second]; + g.get_mut("layerName").unwrap().expr = Some(effectcraft_project::Expression { text: "'CryptoObject'".into(), enabled: true }); + assert_eq!(static_channel_params(spec, &mut g), ["Layer", "Layer Name"]); + let pr = g.get_mut("layer").unwrap(); + assert!(pr.static_only && pr.keys.is_empty()); + assert_eq!(pr.value, Value::Enum(2)); + assert!(g.get_mut("layerName").unwrap().expr.is_none()); + } + #[test] fn upgrade_is_a_no_op_on_fresh_instances() { let mut next = 1; diff --git a/crates/engine/src/cmd/effect.rs b/crates/engine/src/cmd/effect.rs index 103146556..ee6483058 100644 --- a/crates/engine/src/cmd/effect.rs +++ b/crates/engine/src/cmd/effect.rs @@ -522,11 +522,10 @@ impl CryptoProbe { let params = effectcraft_effects::flatten_params(g, &mut |pr| ctx.value(layer, pr)); // The channels the layer's effects read and this effect's (it may be switched off). let own = match &g.kind { - effectcraft_project::GroupKind::Effect { effect } => effectcraft_effects::aux_needs(effect, ¶ms), - _ => None, + effectcraft_project::GroupKind::Effect { effect } => effectcraft_effects::aux_need(effect, ¶ms), + _ => effectcraft_raster::channels3d::AuxNeed::Lookups(vec![]), }; - let need = - r.layer_aux_need(&ctx, layer).union(own.map_or(effectcraft_raster::channels3d::AuxNeed::All, effectcraft_raster::channels3d::AuxNeed::Lookups)); + let need = r.layer_aux_need(&ctx, layer).union(own); let aux = r.layer_aux_with(&ctx, layer, &need).ok_or(NO_CRYPTO)?; if !live() { return Ok(None); diff --git a/crates/engine/src/cmd/prop.rs b/crates/engine/src/cmd/prop.rs index b23e73575..a76888520 100644 --- a/crates/engine/src/cmd/prop.rs +++ b/crates/engine/src/cmd/prop.rs @@ -461,7 +461,7 @@ fn toggle_key_selected(s: &mut Session, p: &Value) -> Result { let want = added.as_bool().unwrap_or(true); for (olid, ouid) in twins { let _ = with_prop(s, "Add/Remove Keyframe", None, cid, olid, ouid, |pr, lt| { - if key_at(&pr.keys, lt).is_some() != want { + if !pr.static_only && key_at(&pr.keys, lt).is_some() != want { toggle_key_at(pr, lt); } Ok(()) @@ -589,6 +589,9 @@ fn add_key(s: &mut Session, p: &Value) -> Result { let at = snapped_key_time(s, cid, lid, p, "prop.addKey")?; let value = p.get("value").cloned(); let count = with_prop(s, "Add Keyframe", None, cid, lid, uid, |pr, lt| { + if pr.static_only { + return Err(bad("prop.addKey", "this property can't be animated")); + } let t = at.unwrap_or(lt); let cur = pr.value_at(t); let v = match &value { @@ -611,7 +614,12 @@ fn add_key(s: &mut Session, p: &Value) -> Result { fn toggle_key(s: &mut Session, p: &Value) -> Result { let (cid, lid, uid) = prop_ref(s, p, "prop.toggleKey")?; - with_prop(s, "Add/Remove Keyframe", None, cid, lid, uid, |pr, lt| Ok(json!(toggle_key_at(pr, lt)))) + with_prop(s, "Add/Remove Keyframe", None, cid, lid, uid, |pr, lt| { + if pr.static_only { + return Err(bad("prop.toggleKey", "this property can't be animated")); + } + Ok(json!(toggle_key_at(pr, lt))) + }) } /// Add a keyframe at layer time `lt` (true), or remove the one there (false). @@ -723,6 +731,9 @@ fn set_expr(s: &mut Session, p: &Value) -> Result { let mut changed_types = vec![]; for (((cid, lid, uid), def), time) in targets.iter().zip(&defs).zip(×) { let pr = layer_mut(proj, *cid, *lid)?.props.find_mut(*uid).ok_or_else(|| bad(C, "property vanished"))?; + if pr.static_only && text.as_deref().is_some_and(|t| !t.trim().is_empty()) { + return Err(bad(C, format!("{} can't have an expression", pr.name))); + } apply_expr(pr, &text, enabled, def); out.push(json!(pr.expr.as_ref().map(|e| e.text.clone()))); if pr.match_id == "type" { diff --git a/crates/engine/src/session/edit.rs b/crates/engine/src/session/edit.rs index 3870e6ebd..60e60ae5b 100644 --- a/crates/engine/src/session/edit.rs +++ b/crates/engine/src/session/edit.rs @@ -208,7 +208,7 @@ impl Session { self.drop_tasks(); self.script_ui.project_epoch = self.script_ui.project_epoch.wrapping_add(1); p.fix_next_id(); - upgrade_effects(&mut p); + let lost = upgrade_effects(&mut p); // The media layer keys decoded frames by path: files of the new project may have changed // since an earlier project decoded them (#1070). for it in p.items.values() { @@ -226,6 +226,12 @@ impl Session { self.path = path; self.bump(); self.mark_saved(); + // (channel selection can't be animated, as in After Effects: a document that animated it + // keeps its first value; said once, not as an error) + if !lost.is_empty() { + log::warn!("channel selection is static: keyframes or expressions dropped on {}", lost.join("; ")); + self.toast(format!("Channel selection can't be animated: kept the first value of {}", lost.join(", "))); + } let first = self.project.comps().next().map(|(id, _)| *id); if let Some(c) = first { self.open_comp(c); @@ -239,8 +245,11 @@ impl Session { /// [`effectcraft_project::SCHEMA_EFFECT_SPACE`] into effect space /// ([`effectcraft_effects::migrate::to_effect_space`]). Shape path operations get the /// properties added since ([`effectcraft_project::build::upgrade_shape_contents`]). Stamps the -/// current schema. -pub fn upgrade_effects(p: &mut Project) { +/// current schema. Channel-selection parameters are made static +/// ([`effectcraft_effects::migrate::static_channel_params`]); returns what lost its animation +/// (`Layer: Effect: Parameter`). +pub fn upgrade_effects(p: &mut Project) -> Vec { + let mut lost = vec![]; let to_effect_space = p.schema < effectcraft_project::SCHEMA_EFFECT_SPACE; // Effect bounds per layer: (size, top-left in layer coordinates). let mut bounds = std::collections::HashMap::new(); @@ -274,10 +283,14 @@ pub fn upgrade_effects(p: &mut Project) { if to_effect_space { effectcraft_effects::migrate::to_effect_space(spec, g, size, d, &clone_d); } + for name in effectcraft_effects::migrate::static_channel_params(spec, g) { + lost.push(format!("{}: {}: {name}", l.name, g.name)); + } } } } } p.next_id = next; p.schema = effectcraft_project::SCHEMA_VERSION; + lost } diff --git a/crates/engine/src/session/render.rs b/crates/engine/src/session/render.rs index dccafa070..4e17a669a 100644 --- a/crates/engine/src/session/render.rs +++ b/crates/engine/src/session/render.rs @@ -197,9 +197,8 @@ impl Session { /// What the effects of [`aux_footage`]'s layers read of each file's channels (#3271), by /// [`effectcraft_project::Footage::path`], sorted: the union of what each enabled effect reading -/// them declares ([`effectcraft_effects::aux_needs`]) with its parameters' values. An effect that -/// doesn't declare, or whose parameters change over time (keyframes, an expression), reads all -/// channels. Several layers of one file add up. +/// them declares ([`effectcraft_effects::aux_needs`]) with its parameters' values (channel +/// selection is static, as in After Effects). Several layers of one file add up. pub(crate) fn aux_needs(project: &effectcraft_project::Project) -> Vec<(String, effectcraft_raster::channels3d::AuxNeed)> { use effectcraft_project::{GroupKind, ItemKind, LayerSource}; use effectcraft_raster::channels3d::AuxNeed; @@ -215,12 +214,15 @@ pub(crate) fn aux_needs(project: &effectcraft_project::Project) -> Vec<(String, if !effectcraft_effects::reads_aux(effect) { continue; } - let need = if commands::moves(g, None) { - AuxNeed::All - } else { - let params = effectcraft_effects::flatten_params(g, &mut |p| p.value.clone()); - effectcraft_effects::aux_needs(effect, ¶ms).map_or(AuxNeed::All, AuxNeed::Lookups) - }; + // Channel selection is static (as in After Effects): the values say what is read. A + // parameter that moves anyway (it can't, see `static_channel_params`) is read at its + // static value. + if commands::moves(g, None) { + static SAID: std::sync::Once = std::sync::Once::new(); + SAID.call_once(|| log::warn!("an effect reading footage channels has animated parameters; its channels are read at their static values")); + } + let params = effectcraft_effects::flatten_params(g, &mut |p| p.value.clone()); + let need = effectcraft_effects::aux_need(effect, ¶ms); let merged = match out.remove(&f.path) { Some(e) => e.union(need), None => need, diff --git a/crates/engine/src/tests/aux_footage.rs b/crates/engine/src/tests/aux_footage.rs index 01c3c1c96..5149fa8e8 100644 --- a/crates/engine/src/tests/aux_footage.rs +++ b/crates/engine/src/tests/aux_footage.rs @@ -18,6 +18,7 @@ use crate::render::{FootageSource, RenderOpts}; struct Recorder { sets: Mutex>>, at_first_frame: Mutex>>>, + needs: Mutex>, } impl Recorder { @@ -37,6 +38,9 @@ impl FootageSource for Recorder { fn set_aux_footage(&self, paths: &[String]) { self.sets.lock().unwrap().push(paths.to_vec()); } + fn set_aux_needs(&self, needs: &[(String, effectcraft_raster::channels3d::AuxNeed)]) { + *self.needs.lock().unwrap() = needs.to_vec(); + } } struct Probe; @@ -198,3 +202,70 @@ fn a_watch_folder_render_gives_the_host_set_back() { s.execute("file.watchFolder", json!({"stop": true})).unwrap(); let _ = std::fs::remove_dir_all(&dir); } + +/// #3271: the parameters that pick the channels an effect reads can't be animated, as in After +/// Effects (no stopwatch there either): a keyframe or an expression is refused, the value still +/// changes; what a frame reads is exactly the channels picked. +#[test] +fn channel_selection_is_static_and_says_what_is_read() { + use effectcraft_raster::channels3d::{AuxLookup, AuxNeed}; + let rec = Arc::new(Recorder::default()); + let mut s = session(&rec); + let item = import(&mut s, "/renders/static.exr"); + let l = add_layer(&mut s, &item); + s.execute_checked("effect.apply", json!({"effect": "EXtractoR", "layers": [l]})).unwrap(); + let red = "effects/#1/red"; + let prop = |s: &Session, path: &str| { + let c = s.active_comp().unwrap(); + c.layer(effectcraft_project::LayerId(l)).unwrap().props.prop(path).unwrap().clone() + }; + assert!(prop(&s, red).static_only, "no stopwatch"); + assert!(s.execute_checked("prop.addKey", json!({"layer": l, "path": red})).is_err(), "no keyframe"); + assert!(s.execute_checked("prop.toggleKey", json!({"layer": l, "path": red})).is_err(), "no keyframe"); + assert!(s.execute_checked("prop.toggleAnimation", json!({"layer": l, "path": red})).is_err(), "no stopwatch"); + assert!(s.execute_checked("prop.setExpression", json!({"layer": l, "path": red, "expression": "'Z'"})).is_err(), "no expression"); + assert!(prop(&s, red).keys.is_empty() && prop(&s, red).expr.is_none()); + // The value changes; the channels read are exactly those picked. + s.execute_checked("prop.set", json!({"layer": l, "path": red, "value": "Z"})).unwrap(); + for c in ["green", "blue", "alpha"] { + s.execute_checked("prop.set", json!({"layer": l, "path": format!("effects/#1/{c}"), "value": ""})).unwrap(); + } + assert_eq!(prop(&s, red).value, effectcraft_keyframe::Value::Str("Z".into())); + let needs = rec.needs.lock().unwrap().clone(); + assert_eq!(needs, [("/renders/static.exr".to_string(), AuxNeed::Lookups(vec![AuxLookup::Name("Z".into())]))]); +} + +/// #3271: a document that animated a channel selection (it can't come from After Effects, nor +/// from EffectCraft now) opens with the first key's value as the static one, its keys and +/// expression dropped, and says so. +#[test] +fn a_keyed_channel_selection_opens_static() { + use effectcraft_keyframe::{Keyframe, Value as K}; + let rec = Arc::new(Recorder::default()); + let mut s = session(&rec); + let item = import(&mut s, "/renders/keyed.exr"); + let l = add_layer(&mut s, &item); + s.execute_checked("effect.apply", json!({"effect": "EXtractoR", "layers": [l]})).unwrap(); + let cid = s.active_comp_id().unwrap(); + { + let p = Arc::make_mut(&mut s.project); + let pr = p.comp_mut(cid).unwrap().layer_mut(effectcraft_project::LayerId(l)).unwrap().props.prop_mut("effects/#1/red").unwrap(); + // (as a document from before) + pr.static_only = false; + pr.keys = vec![Keyframe::new(Tick::ZERO, K::Str("Z".into())), Keyframe::new(Tick::from_seconds_f64(1.0), K::Str("N.X".into()))]; + } + let dir = std::env::temp_dir().join(format!("ec-3271-static-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let path = dir.join("keyed.ecproj"); + s.execute_checked("file.saveAs", json!({"path": path.to_string_lossy()})).unwrap(); + let mut o = session(&rec); + o.drain_events(); + o.execute_checked("file.open", json!({"path": path.to_string_lossy()})).unwrap(); + let c = o.active_comp().unwrap(); + let pr = c.layer(effectcraft_project::LayerId(l)).unwrap().props.prop("effects/#1/red").unwrap(); + assert!(pr.static_only && pr.keys.is_empty() && pr.expr.is_none()); + assert_eq!(pr.value, K::Str("Z".into()), "the first key's value"); + let said = o.drain_events().into_iter().any(|e| matches!(e, crate::Event::Toast { message, .. } if message.contains("Channel selection"))); + assert!(said, "the loss is reported"); + let _ = std::fs::remove_dir_all(&dir); +} diff --git a/crates/render/src/accel.rs b/crates/render/src/accel.rs index 06d204a1a..8cce02067 100644 --- a/crates/render/src/accel.rs +++ b/crates/render/src/accel.rs @@ -253,8 +253,8 @@ impl<'a> Renderer<'a> { } /// What the enabled effects of `layer` read of its auxiliary channels at the context time - /// ([`effectcraft_effects::aux_needs`], #3271): the union of their lookups, or all channels - /// when one doesn't say (or none reads them). + /// ([`effectcraft_effects::aux_needs`], #3271): the union of their lookups (none when no + /// effect reads them). pub fn layer_aux_need(&self, ctx: &EvalCtx, layer: &Layer) -> effectcraft_raster::channels3d::AuxNeed { use effectcraft_raster::channels3d::AuxNeed; let mut need: Option = None; @@ -264,13 +264,13 @@ impl<'a> Renderer<'a> { continue; } let params = effectcraft_effects::flatten_params(g, &mut |pr| ctx.value(layer, pr)); - let one = effectcraft_effects::aux_needs(effect, ¶ms).map_or(AuxNeed::All, AuxNeed::Lookups); + let one = effectcraft_effects::aux_need(effect, ¶ms); need = Some(match need { Some(n) => n.union(one), None => one, }); } - need.unwrap_or_default() + need.unwrap_or(AuxNeed::Lookups(vec![])) } /// Evaluation context of comp `comp_id` at comp time `t`. diff --git a/docs/effects.md b/docs/effects.md index d9f726481..96893fe4e 100644 --- a/docs/effects.md +++ b/docs/effects.md @@ -13,6 +13,8 @@ Effects are addressed by id (`ec..`) or display name in commands ## 3D Channel +The parameters that pick which channels or Cryptomatte layer an effect reads are not animatable, as in After Effects (see [footage](footage.md)). + | Effect | Id | Params | GPU | 32 | Status | |---|---|---:|:-:|:-:|---| | 3D Channel Extract | `ec.3d.channelextract` | 6 | GPU | 32 | Implemented | diff --git a/docs/footage.md b/docs/footage.md index 7841dc84c..55da1f772 100644 --- a/docs/footage.md +++ b/docs/footage.md @@ -123,11 +123,21 @@ vectors, positions and IDs are never the picture. EXtractoR reads every other la Footage on its own keeps only the channels of its picture (a single-part file still decompresses all of its pixels to read them). Once an effect reads an item's channels (EXtractoR, Cryptomatte, the 3D Channel effects), each frame, the first included, is decoded -once for the picture and the effects together, and kept for a while: about 1 GB of decoded -channels (512 MB in the browser), a soft bound, as the newest file and files still in use -stay whatever their size. Several frames asking for the same file at once wait for one -decode. Once no enabled effect reads the item any more, its frames go back to the picture's -channels alone. +once for the picture and the effects together, and only the channels the effects pick are +read (EXtractoR's channel names, Cryptomatte's layer, the 3D Channel effects' channel popups). +The decoded channels are kept for a while, in the Footage Frame Cache together with the +decoded frames (the least recently used frame or channel set goes first; in the browser the +channels take at most 512 MB), a soft bound, as the newest file and files still in use stay +whatever their size. The picture is kept once, converted: its own R, G, B and A planes are +not kept beside it, unless an effect names one of them. Several frames asking for the same +file at once wait for one decode. Once no enabled effect reads the item any more, its frames +go back to the picture's channels alone. + +The parameters that pick channels (EXtractoR's Red, Green, Blue and Alpha, Cryptomatte's Layer +and Layer Name, 3D Channel Extract's 3D Channel, ID Matte's Aux. Channel and Use Coverage, +IDentifier's Channel Type) can't be animated, as in After Effects, where they have no +stopwatch either: they take no keyframes and no expression. A document that animated one +opens with its first value. The Cryptomatte effect keys objects by their Cryptomatte ID passes, with the names from the file's manifest. Pick them with the eyedropper next to its Selection, then click in the