From 8a3b15d41b679f1f033be3ef27acec3c6e03ca48 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sun, 8 Nov 2026 03:00:29 +0100 Subject: [PATCH] Footage cache (#3271): decoded OpenEXR channels persist in the disk cache A plane kind in the disk cache (planes/): named f32 planes, bit-exact, keyed by the source file's path and identity, the channel set, the level and the rows; listing their source file, so a changed file or Reload Footage drops them (the sweep covers planes). The plane store reads them before decoding and queues what it decoded (encoded on the writer thread, refused when the disk has no room or the file was dropped since the decode began). The footage source gets the disk cache with set_disk_cache. --- apps/effectcraft-web/src/diskcache.rs | 4 + crates/automation/src/confine.rs | 4 + .../engine/src/settings/session_settings.rs | 4 + crates/media/src/exr_planes.rs | 66 ++++++-- crates/media/src/exr_planes/tests.rs | 32 ++++ crates/media/src/pool.rs | 4 + crates/render/src/disk_cache.rs | 152 +++++++++++++++++- crates/render/src/footage.rs | 7 + 8 files changed, 260 insertions(+), 13 deletions(-) diff --git a/apps/effectcraft-web/src/diskcache.rs b/apps/effectcraft-web/src/diskcache.rs index 72e9a9e11..6c2c93a8b 100644 --- a/apps/effectcraft-web/src/diskcache.rs +++ b/apps/effectcraft-web/src/diskcache.rs @@ -116,6 +116,7 @@ pub(crate) fn name_of(kind: Kind, key: u128) -> String { Kind::Frame => disk_cache::entry_name(key), Kind::Layer => format!("layers/{}", disk_cache::entry_name(key)), Kind::Matte => format!("mattes/{}", disk_cache::entry_name(key)), + Kind::Plane => format!("planes/{}", disk_cache::entry_name(key)), } } @@ -126,6 +127,9 @@ fn parse_name(name: &str) -> Option<(Kind, u128)> { if let Some(n) = name.strip_prefix("mattes/") { return Some((Kind::Matte, disk_cache::parse_entry_name(n)?)); } + if let Some(n) = name.strip_prefix("planes/") { + return Some((Kind::Plane, disk_cache::parse_entry_name(n)?)); + } Some((Kind::Frame, disk_cache::parse_entry_name(name)?)) } diff --git a/crates/automation/src/confine.rs b/crates/automation/src/confine.rs index 8ecb31019..e408ff276 100644 --- a/crates/automation/src/confine.rs +++ b/crates/automation/src/confine.rs @@ -401,6 +401,10 @@ impl FootageSource for ConfinedFootage { fn set_aux_footage(&self, paths: &[String]) { self.inner.set_aux_footage(paths) } + /// Forwards the disk cache to the inner source. + fn set_disk_cache(&self, cache: Option>) { + self.inner.set_disk_cache(cache) + } /// Forwards what effects read of each auxiliary footage to the inner source. fn set_aux_needs(&self, needs: &[(String, effectcraft_engine::raster::channels3d::AuxNeed)]) { self.inner.set_aux_needs(needs) diff --git a/crates/engine/src/settings/session_settings.rs b/crates/engine/src/settings/session_settings.rs index 8ade9f8a3..65bf5a0be 100644 --- a/crates/engine/src/settings/session_settings.rs +++ b/crates/engine/src/settings/session_settings.rs @@ -130,6 +130,7 @@ impl Session { self.disk_cache = None; self.disk_watch = Default::default(); self.layer_cache.set_disk(None); + self.footage.set_disk_cache(None); return; }; // Tests: the Roto/Object Matte segment store below is one per process, so a test that @@ -154,6 +155,7 @@ impl Session { self.disk_cache = None; self.disk_watch = Default::default(); self.layer_cache.set_disk(None); + self.footage.set_disk_cache(None); return; } }, @@ -169,6 +171,8 @@ impl Session { // Used at once (no file is looked at first: each entry checks the source files it lists // when it is read, #3184). self.layer_cache.set_disk(Some(dc.clone())); + // Decoded footage channels (OpenEXR planes) persist there too (#3271). + self.footage.set_disk_cache(Some(dc.clone())); // Roto Brush / Object Matte segmentations persist there too (held weakly: switching the // disk cache off drops it). let store: std::sync::Arc = dc.clone(); diff --git a/crates/media/src/exr_planes.rs b/crates/media/src/exr_planes.rs index 0a66ac4ce..15591495b 100644 --- a/crates/media/src/exr_planes.rs +++ b/crates/media/src/exr_planes.rs @@ -275,6 +275,8 @@ enum Waited { pub(crate) struct DecodeRecord { pub(crate) channels: Vec, pub(crate) stats: crate::exr_read::ReadStats, + /// Read from the disk cache, not from the file. + pub(crate) from_disk: bool, } #[cfg(test)] @@ -635,16 +637,33 @@ fn decode(path: &str, source: &ExrSource, flight: &Arc, base: Option = wanted.iter().copied().filter(|id| !base.as_ref().is_some_and(|b| b.ids.binary_search(id).is_ok())).collect(); - let request = ReadRequest { max_bytes: cap_of(path), ..ReadRequest::full(missing.clone()) }; - let (planes, stats) = read_planes(&mut *opened.reader, &index, &request); + let names: Vec = missing.iter().filter_map(|i| index.channels.get(*i)).map(|c| c.name.clone()).collect(); + // The disk tier first (#3271): what an earlier session or a decode RAM let go of kept. + let disk = disk_cache().filter(|_| !missing.is_empty() && unique(&names)); + let since = disk.as_ref().map_or(0, |d| d.drop_generation()); + let key = { + let refs: Vec<&str> = names.iter().map(String::as_str).collect(); + effectcraft_render::disk_cache::plane_key(path, &opened.stamp, &refs, 0, None) + }; + let (w, h) = index.size(); + let kept = disk.as_ref().and_then(|d| d.get_planes(key, None)).map(|(p, _)| p).filter(|p| { + (p.width as usize, p.height as usize) == (w, h) + && p.planes.len() == names.len() + && p.planes.iter().zip(&names).all(|((n, v), want)| n == want && v.len() == w * h) + }); + let from_disk = kept.is_some(); + let (planes, stats) = match kept { + Some(p) => (Ok(p.planes.into_iter().map(|(_, v)| v).collect()), Default::default()), + None => { + let request = ReadRequest { max_bytes: cap_of(path), ..ReadRequest::full(missing.clone()) }; + read_planes(&mut *opened.reader, &index, &request) + } + }; #[cfg(test)] - DECODES.lock().unwrap_or_else(PoisonError::into_inner).push(( - path.to_string(), - DecodeRecord { channels: missing.iter().filter_map(|i| index.channels.get(*i)).map(|c| c.name.clone()).collect(), stats: stats.clone() }, - )); + DECODES.lock().unwrap_or_else(PoisonError::into_inner).push((path.to_string(), DecodeRecord { channels: names.clone(), stats: stats.clone(), from_disk })); #[cfg(not(test))] let _ = &stats; - let planes = planes.map_err(|e| match e { + let planes: Vec> = planes.map_err(|e| match e { ReadError::Cancelled => Refused::Cancelled, // (a read that failed just now: the next request reads again) ReadError::Io(why) => { @@ -672,7 +691,6 @@ fn decode(path: &str, source: &ExrSource, flight: &Arc, base: Option, base: Option = new.iter().map(|(id, _)| *id).collect(); aux.channels = new.into_iter().filter_map(|(id, p)| Some((index.channels.get(id)?.name.clone(), p))).collect(); - Ok(Arc::new(Batch { index, ids, all, aux: Arc::new(aux), file: ReadFile::new(path, opened.stamp) })) + let file = ReadFile::new(path, opened.stamp); + let batch = Arc::new(Batch { index, ids, all, aux: Arc::new(aux), file: file.clone() }); + // Kept on disk for the next time (encoded on the disk cache's writer thread; a file from + // memory, which can't be checked later, isn't). + if let Some(d) = disk.filter(|_| !from_disk) { + let mut read = effectcraft_render::reads::ReadFiles::default(); + read.add(file); + if let Some(entry) = effectcraft_render::disk_cache::EntryFiles::of(&read, None) { + d.put_planes(key, &batch.aux, names, &entry, since); + } + } + Ok(batch) +} + +/// Every name once (a plane entry is read back by name). +fn unique(names: &[String]) -> bool { + let set: std::collections::HashSet<&String> = names.iter().collect(); + set.len() == names.len() +} + +/// The disk cache decoded planes are kept in ([`set_disk_cache`]). +static DISK: Mutex>> = Mutex::new(None); + +/// Keep decoded planes in `cache` too (`None`: no disk tier), #3271. Held weakly: switching the +/// disk cache off drops it. +pub(crate) fn set_disk_cache(cache: Option<&Arc>) { + *DISK.lock().unwrap_or_else(PoisonError::into_inner) = cache.map(Arc::downgrade); +} + +fn disk_cache() -> Option> { + DISK.lock().unwrap_or_else(PoisonError::into_inner).as_ref().and_then(std::sync::Weak::upgrade) } fn store() -> &'static PlaneStore { diff --git a/crates/media/src/exr_planes/tests.rs b/crates/media/src/exr_planes/tests.rs index 90f33ea39..1edf62c99 100644 --- a/crates/media/src/exr_planes/tests.rs +++ b/crates/media/src/exr_planes/tests.rs @@ -821,3 +821,35 @@ fn a_new_frame_opens_its_file_once() { assert_eq!(decodes_of(&f.path).len(), 1); let _ = std::fs::remove_dir_all(&dir); } + +/// #3271: decoded channels are kept in the disk cache: once RAM has let them go they are read +/// back from there, bit for bit (Cryptomatte IDs included), instead of decoding the file; Reload +/// Footage drops them. +#[test] +fn decoded_planes_are_kept_on_disk_and_read_back_exactly() { + use effectcraft_render::disk_cache::{DiskCache, Kind}; + let dir = std::env::temp_dir().join(format!("ec-3271-disk-planes-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let file = dir.join("crypto_0001.exr"); + std::fs::write(&file, multipart()).unwrap(); + let dc = DiskCache::open(dir.join("cache"), 1 << 30).unwrap(); + set_disk_cache(Some(&dc)); + let f = crate::probe(&file).unwrap(); + let pool = crate::MediaPool::new(); + let first = pool.aux(ItemId(1), &f, Tick::ZERO).unwrap(); + dc.flush(); + assert_eq!(dc.keys(Kind::Plane).len(), 1, "{:?}", dc.stats()); + forget(&f.path); + let again = pool.aux(ItemId(1), &f, Tick::ZERO).unwrap(); + let bits = |a: &AuxChannels| a.channels.iter().map(|(n, p)| (n.clone(), p.iter().map(|v| v.to_bits()).collect::>())).collect::>(); + assert_eq!(bits(&again), bits(&first), "bit for bit"); + // Reload Footage: the entry goes, the file is decoded again. + dc.drop_files([f.path.clone()]); + dc.flush(); + forget(&f.path); + pool.aux(ItemId(1), &f, Tick::ZERO).unwrap(); + set_disk_cache(None); + let from_disk: Vec = decodes_of(&f.path).iter().map(|d| d.from_disk).collect(); + assert_eq!(from_disk, [false, true, false]); + let _ = std::fs::remove_dir_all(&dir); +} diff --git a/crates/media/src/pool.rs b/crates/media/src/pool.rs index 5fe227b0c..a8987ae4d 100644 --- a/crates/media/src/pool.rs +++ b/crates/media/src/pool.rs @@ -1464,6 +1464,10 @@ impl FootageSource for MediaPool { wanted.learned.clear(); } + fn set_disk_cache(&self, cache: Option>) { + crate::exr_planes::set_disk_cache(cache.as_ref()); + } + fn set_aux_needs(&self, needs: &[(String, AuxNeed)]) { let mut wanted = lock(&self.inner.aux_footage); let needs: HashMap = needs.iter().cloned().collect(); diff --git a/crates/render/src/disk_cache.rs b/crates/render/src/disk_cache.rs index 314c492b5..fa97cea52 100644 --- a/crates/render/src/disk_cache.rs +++ b/crates/render/src/disk_cache.rs @@ -65,6 +65,9 @@ pub enum Kind { Layer, /// A Roto Brush / Object Matte segmentation. Matte, + /// Decoded footage channels (an OpenEXR frame's planes, #3271): read instead of decoding + /// the file again, after RAM let them go or in the next session. + Plane, } impl Kind { @@ -74,6 +77,7 @@ impl Kind { Kind::Frame => "frames", Kind::Layer => "layers", Kind::Matte => "mattes", + Kind::Plane => "planes", } } fn tag(self) -> u8 { @@ -81,6 +85,7 @@ impl Kind { Kind::Frame => 1, Kind::Layer => 2, Kind::Matte => 3, + Kind::Plane => 4, } } } @@ -112,6 +117,45 @@ const FORMAT_F16_FILES: u8 = 3; /// Layer entries: their source files ([`EntryFiles`]), then the buffer. The format before it /// (0, without files) reads as a miss and is deleted. const FORMAT_LAYER_FILES: u8 = 4; +/// Plane entries: their source file ([`EntryFiles`]), then named `f32` planes ([`DiskPlanes`]). +const FORMAT_PLANES_FILES: u8 = 5; + +/// Decoded footage channels as a plane entry holds them (#3271): named `f32` planes of +/// `width` × `height`, bit-exact (Cryptomatte IDs are float bit patterns). +#[derive(Clone, Debug, Default, PartialEq)] +pub struct DiskPlanes { + pub width: u32, + pub height: u32, + pub planes: Vec<(String, Vec)>, +} + +/// The most planes and pixels a plane entry holds (a damaged entry can't ask for more). +const MAX_ENTRY_PLANES: usize = 4096; +const MAX_ENTRY_PIXELS: usize = 1 << 28; + +/// The disk key of decoded footage channels: the source file's path and identity as read, the +/// channel names (in the order stored), the level and the rows read (`None`: all). +pub fn plane_key(path: &str, stamp: &crate::reads::FileStamp, channels: &[&str], level: u32, rows: Option<(i64, i64)>) -> u128 { + let mut h = Hash128::default(); + h.write(b"planes-v1"); + h.write(path.as_bytes()); + h.write(format!("{stamp:?}").as_bytes()); + h.write_u64(channels.len() as u64); + for c in channels { + h.write_u64(c.len() as u64); + h.write(c.as_bytes()); + } + h.write_u64(u64::from(level)); + match rows { + Some((a, b)) => { + h.write_u64(1); + h.write_u64(a as u64); + h.write_u64(b as u64); + } + None => h.write_u64(0), + } + h.finish() +} /// Counters for tests, the Info panel and `cache.diskStats`. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] @@ -280,6 +324,8 @@ enum Payload { /// An 8-bit or half-float frame (width, height, pixels) and its source files. Frame8(u32, u32, Vec, EntryFiles), FrameF16(u32, u32, Vec, EntryFiles), + /// The planes named (in order) of decoded footage channels, and their source file. + Planes(Arc, Vec, EntryFiles), } #[cfg(test)] @@ -306,6 +352,7 @@ impl Payload { Payload::Layer(buf, files) => with_files(&files, encode_layer(&buf)), Payload::Frame8(w, h, rgba, files) => with_files(&files, encode_frame(w, h, &rgba)), Payload::FrameF16(w, h, rgba, files) => with_files(&files, encode_frame_f16(w, h, &rgba)), + Payload::Planes(aux, names, files) => with_files(&files, encode_planes(&aux, &names)), } } @@ -317,6 +364,7 @@ impl Payload { Payload::Layer(buf, _) => buf.img.data.len().saturating_mul(16), Payload::Frame8(_, _, p, _) => p.len(), Payload::FrameF16(_, _, p, _) => p.len().saturating_mul(2), + Payload::Planes(aux, names, _) => (aux.width as usize).saturating_mul(aux.height as usize).saturating_mul(4).saturating_mul(names.len()), } } @@ -548,7 +596,7 @@ impl DiskCache { /// Rebuild the index from the folder (oldest files first). pub fn rescan(&self) { let mut found: Vec<(std::time::SystemTime, Kind, u128, u64)> = vec![]; - for kind in [Kind::Frame, Kind::Layer, Kind::Matte] { + for kind in [Kind::Frame, Kind::Layer, Kind::Matte, Kind::Plane] { let Ok(shards) = std::fs::read_dir(self.dir.join(kind.dir())) else { continue }; for shard in shards.flatten() { let Ok(files) = std::fs::read_dir(shard.path()) else { continue }; @@ -695,7 +743,7 @@ impl DiskCache { if let Ok(mut g) = self.index.lock() { g.clear(); } - for kind in [Kind::Frame, Kind::Layer, Kind::Matte] { + for kind in [Kind::Frame, Kind::Layer, Kind::Matte, Kind::Plane] { let _ = std::fs::remove_dir_all(self.dir.join(kind.dir())); } } @@ -1020,7 +1068,7 @@ impl DiskCache { /// end their drop. fn sweep(&self, paths: &[Arc]) { let set: std::collections::HashSet<&str> = paths.iter().map(|p| &**p).collect(); - for kind in [Kind::Frame, Kind::Layer] { + for kind in [Kind::Frame, Kind::Layer, Kind::Plane] { for key in self.keys(kind) { if self.entry_files(kind, key).is_some_and(|f| f.files().iter().any(|f| set.contains(&*f.path))) { self.discard(kind, key); @@ -1047,7 +1095,7 @@ impl DiskCache { let parse = |d: &[u8]| { let format = *d.get(5)?; let ours = d.get(..4)? == MAGIC && *d.get(4)? == kind.tag(); - if !ours || !matches!(format, FORMAT_RGBA8_FILES | FORMAT_F16_FILES | FORMAT_LAYER_FILES) { + if !ours || !matches!(format, FORMAT_RGBA8_FILES | FORMAT_F16_FILES | FORMAT_LAYER_FILES | FORMAT_PLANES_FILES) { return None; } EntryFiles::decode(d.get(8..)?).map(|(files, _)| files) @@ -1179,6 +1227,26 @@ impl DiskCache { } } + /// Decoded footage channels ([`plane_key`]) whose source file is unchanged, with that file, + /// as [`DiskCache::get_checked`] (#3271). `virtual_id` names files served from memory. + pub fn get_planes(&self, key: u128, virtual_id: Option>) -> Option<(DiskPlanes, ReadFiles)> { + self.get_checked(Kind::Plane, key, FORMAT_PLANES_FILES, virtual_id, decode_planes) + } + + /// Queue decoded footage channels for writing: the planes of `aux` named `names` (in that + /// order, as [`plane_key`] names them), with the source file they were read from. Encoded on + /// the writer thread (a reference to the planes, no copy). Refused when there is no room, the + /// file can't be checked later, or it was dropped after `since`. + pub fn put_planes(&self, key: u128, aux: &Arc, names: Vec, files: &EntryFiles, since: u64) -> bool { + if self.contains(Kind::Plane, key) { + return true; + } + if names.is_empty() || !self.accepts_writes() { + return false; + } + self.enqueue_format(Kind::Plane, key, FORMAT_PLANES_FILES, Payload::Planes(aux.clone(), names, files.clone()), Some((files, since))) + } + /// A segmentation (chain key, scale) written by [`DiskCache::put_seg`]. pub fn get_seg(&self, key: u64, scale: f64) -> Option { let p = self.read(Kind::Matte, seg_key(key, scale))?; @@ -1475,6 +1543,82 @@ fn decode_frame_f16(p: &[u8]) -> Option { Some(FrameF16 { width: w, height: h, rgba }) } +/// A plane entry's pixels: width, height, the plane count, each plane's name (length and UTF-8 +/// bytes) and type (2: `f32`), then every plane's bytes shuffled into byte planes (plane by plane, +/// the first bytes of its floats, then the second…), LZ4-compressed. Planes of `aux` named +/// `names` that it doesn't hold, or holds at another size, are written as zeros. +fn encode_planes(aux: &effectcraft_raster::AuxChannels, names: &[String]) -> Vec { + let (w, h) = (aux.width, aux.height); + let n = (w as usize).saturating_mul(h as usize); + let mut out = Vec::with_capacity(64); + out.extend_from_slice(&w.to_le_bytes()); + out.extend_from_slice(&h.to_le_bytes()); + out.extend_from_slice(&(names.len() as u32).to_le_bytes()); + for name in names { + let bytes = name.as_bytes(); + out.extend_from_slice(&(bytes.len().min(u16::MAX as usize) as u16).to_le_bytes()); + out.extend_from_slice(bytes.get(..bytes.len().min(u16::MAX as usize)).unwrap_or_default()); + out.push(2); + } + let mut shuffled = vec![0u8; n.saturating_mul(4).saturating_mul(names.len())]; + for (k, name) in names.iter().enumerate() { + let Some(plane) = aux.channels.iter().find(|(c, _)| c == name).map(|(_, p)| p).filter(|p| p.len() == n) else { continue }; + let base = k * n * 4; + for (i, v) in plane.iter().enumerate() { + let b = v.to_bits().to_le_bytes(); + for (byte, value) in b.iter().enumerate() { + if let Some(o) = shuffled.get_mut(base + byte * n + i) { + *o = *value; + } + } + } + } + out.extend_from_slice(&lz4_flex::compress_prepend_size(&shuffled)); + out +} + +/// The planes of a plane entry's pixels ([`encode_planes`]); `None` when damaged. +fn decode_planes(p: &[u8]) -> Option { + let u32_at = |at: usize| Some(u32::from_le_bytes(p.get(at..at + 4)?.try_into().ok()?)); + let (w, h, count) = (u32_at(0)?, u32_at(4)?, u32_at(8)? as usize); + let n = (w as usize).checked_mul(h as usize).filter(|n| *n <= MAX_ENTRY_PIXELS)?; + if count > MAX_ENTRY_PLANES { + return None; + } + let mut at = 12; + let mut names = Vec::with_capacity(count); + for _ in 0..count { + let len = u16::from_le_bytes(p.get(at..at + 2)?.try_into().ok()?) as usize; + let name = std::str::from_utf8(p.get(at + 2..at + 2 + len)?).ok()?.to_string(); + if *p.get(at + 2 + len)? != 2 { + return None; + } + names.push(name); + at += 3 + len; + } + let body = p.get(at..)?; + // (the size the compressed block says must be the planes': nothing larger is allocated) + let want = n.checked_mul(4)?.checked_mul(count)?; + if u32::from_le_bytes(body.get(..4)?.try_into().ok()?) as usize != want { + return None; + } + let shuffled = lz4_flex::decompress_size_prepended(body).ok()?; + if shuffled.len() != want { + return None; + } + let mut planes = Vec::with_capacity(count); + for (k, name) in names.into_iter().enumerate() { + let base = k * n * 4; + let mut plane = Vec::with_capacity(n); + for i in 0..n { + let b = [*shuffled.get(base + i)?, *shuffled.get(base + n + i)?, *shuffled.get(base + 2 * n + i)?, *shuffled.get(base + 3 * n + i)?]; + plane.push(f32::from_bits(u32::from_le_bytes(b))); + } + planes.push((name, plane)); + } + Some(DiskPlanes { width: w, height: h, planes }) +} + fn encode_layer(b: &Buf) -> Vec { let (w, h) = (b.img.width, b.img.height); let n = b.img.data.len(); diff --git a/crates/render/src/footage.rs b/crates/render/src/footage.rs index 842f2007a..d525c4f8b 100644 --- a/crates/render/src/footage.rs +++ b/crates/render/src/footage.rs @@ -78,6 +78,10 @@ pub trait FootageSource: Send + Sync { /// given before: the picture of such footage is then decoded together with those channels /// only. A file not named here reads every channel. Sources that don't care ignore it. fn set_aux_needs(&self, _needs: &[(String, effectcraft_raster::channels3d::AuxNeed)]) {} + /// The disk cache (Settings ▸ Media & Disk Cache), `None` when it is off: sources that + /// decode costly footage keep what they decoded there too (#3271: OpenEXR channels). + /// Sources without such a tier ignore it. + fn set_disk_cache(&self, _cache: Option>) {} /// The parsed 3D model of a [`effectcraft_project::FootageKind::Model`] item (Advanced 3D). fn model(&self, _item: ItemId, _footage: &Footage) -> Option> { None @@ -215,6 +219,9 @@ impl FootageSource for CancellableFootage<'_> { fn set_aux_needs(&self, needs: &[(String, effectcraft_raster::channels3d::AuxNeed)]) { self.inner.set_aux_needs(needs) } + fn set_disk_cache(&self, cache: Option>) { + self.inner.set_disk_cache(cache) + } fn model(&self, item: ItemId, footage: &Footage) -> Option> { self.inner.model(item, footage) }