From 804067b9da7b8a5a9e2930d8be7fc60d3c19bfba Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sun, 8 Nov 2026 01:55:41 +0100 Subject: [PATCH] Footage cache (#3271): OpenEXR index, chunk reader and plane store exr_index: headers and offset tables only, kept per file; probe and the channel lists use it. exr_read: only the chunks a request needs, by offset table in file order, decompressed on the decode threads, only the requested channels converted; rows and levels in the API; cancellable. exr_planes: one store of decoded planes per file and level for the picture and the effects, single flight with merged channel sets and follow-up decodes of what is missing; replaces the pool's OpenEXR decode and the separate channel cache. Pixels as before. --- crates/media/src/exr_channels.rs | 997 ++------------------------- crates/media/src/exr_index.rs | 371 ++++++++++ crates/media/src/exr_planes.rs | 701 +++++++++++++++++++ crates/media/src/exr_planes/tests.rs | 439 ++++++++++++ crates/media/src/exr_read.rs | 331 +++++++++ crates/media/src/lib.rs | 3 + crates/media/src/pool.rs | 96 ++- crates/media/src/probe.rs | 8 +- 8 files changed, 1998 insertions(+), 948 deletions(-) create mode 100644 crates/media/src/exr_index.rs create mode 100644 crates/media/src/exr_planes.rs create mode 100644 crates/media/src/exr_planes/tests.rs create mode 100644 crates/media/src/exr_read.rs diff --git a/crates/media/src/exr_channels.rs b/crates/media/src/exr_channels.rs index 86aa6b9a9..1a2657ccc 100644 --- a/crates/media/src/exr_channels.rs +++ b/crates/media/src/exr_channels.rs @@ -7,31 +7,25 @@ //! `cryptomatte//name` and `cryptomatte//manifest` header attributes (the published //! Cryptomatte metadata convention: the manifest is a JSON object of name → hex hash). //! -//! Decoded files are kept in a small cache ([`CACHE_BUDGET`]) that the picture of an EXR -//! footage item shares with EXtractoR / Cryptomatte once an effect has read its channels -//! (#474); a file is decoded once however many callers ask for it at the same time. +//! The files are indexed from their headers ([`crate::exr_index`]), read chunk by chunk +//! ([`crate::exr_read`]) and their planes kept in the plane store ([`crate::exr_planes`]), +//! which the picture of an EXR footage item shares with EXtractoR / Cryptomatte (#474, #3271). +//! This module holds the naming and picture rules they share, and whole-file reads of bytes. -use std::collections::HashMap; -use std::sync::atomic::{AtomicU64, Ordering}; -use std::sync::{Arc, Mutex, OnceLock, PoisonError}; - -use effectcraft_raster::channels3d::{BACKGROUND_DEPTH, split_channel}; +use effectcraft_raster::channels3d::split_channel; use effectcraft_raster::{AuxChannels, Image}; -use effectcraft_render::reads::{ReadFile, ReadFiles}; -use exr::block::UncompressedBlock; -use exr::block::chunk::TileCoordinates; -use exr::image::read::image::ReadImage; -use exr::image::read::layers::{ChannelsReader, ReadAllLayers, ReadChannels}; -use exr::meta::attribute::SampleType; +use effectcraft_render::reads::FileStamp; use exr::meta::header::Header; use crate::convert::{AlphaOp, float_to_image}; +use crate::exr_index::ExrIndex; +use crate::exr_read::{ReadRequest, read_planes}; /// The largest display window decoded (16384²; vector footage and Continuously Rasterize /// stop at the same size). -const MAX_DISPLAY_PIXELS: usize = 1 << 28; +pub(crate) const MAX_DISPLAY_PIXELS: usize = 1 << 28; -fn is_depth(name: &str) -> bool { +pub(crate) fn is_depth(name: &str) -> bool { let last = name.rsplit('.').next().unwrap_or(name); last.eq_ignore_ascii_case("z") || name.to_ascii_lowercase().contains("depth") } @@ -39,7 +33,7 @@ fn is_depth(name: &str) -> bool { /// Full plane name of a channel in a part: `part.channel`, except that Blender 5 writes one part /// per pass whose channels already carry the full name (part `ViewLayer.Depth` holds /// `ViewLayer.Depth.Z`), which is kept as is instead of doubling the prefix. -fn channel_name(part: Option<&str>, channel: &str) -> String { +pub(crate) fn channel_name(part: Option<&str>, channel: &str) -> String { match part { Some(p) if channel.strip_prefix(p).is_some_and(|rest| rest.starts_with('.')) => channel.to_string(), Some(p) => format!("{p}.{channel}"), @@ -48,7 +42,7 @@ fn channel_name(part: Option<&str>, channel: &str) -> String { } /// The part name channels are prefixed with (`None`: unnamed). -fn part_name(header: &Header) -> Option { +pub(crate) fn part_name(header: &Header) -> Option { header.own_attributes.layer_name.as_ref().map(|t| t.to_string()).filter(|s| !s.is_empty()) } @@ -64,292 +58,61 @@ pub fn parse_manifest(json: &str) -> Vec<(String, u32)> { /// can't decompress (HTJ2K, OpenEXR 3.4's High-Throughput JPEG 2000): the decoders only said /// "no non-deep rgb channels" or showed a transparent frame (#482). `None` for other files. pub fn unsupported_compression(bytes: &[u8]) -> Option<&'static str> { - use exr::compression::Compression; let meta = exr::meta::MetaData::read_from_buffered(std::io::Cursor::new(bytes), false).ok()?; - meta.headers - .iter() - .any(|h| matches!(h.compression, Compression::HTJ2K32 | Compression::HTJ2K256)) - .then_some("OpenEXR HTJ2K compression isn't supported yet: re-save the file with ZIP, PIZ or DWAA compression") -} - -/// Which channels a decode keeps, by plane name, and the display window they are placed in -/// (the first part's, as the `exr` crate reports the image's). -struct Planes<'k> { - keep: &'k dyn Fn(&str) -> bool, - display: exr::meta::attribute::IntegerBounds, -} - -/// One part's kept channels while it is decoded: each line of samples goes straight into its -/// channel's display-window plane (no copy of the part's samples in their own type first). -struct PlanesReader { - /// Per channel of the part: its plane name, sample type and plane (`None`: not kept). - planes: Vec)>>, - /// The data window's position in the display window, and the data window's and display - /// window's sizes. - offset: (i64, i64), - layer: (usize, usize), - display: (usize, usize), - f16s: Vec, - u32s: Vec, - f32s: Vec, - /// The part's channel indices of exact `R`, `G`, `B` and `A`, when it has R, G and B. - rgb: Option<([usize; 3], Option)>, - /// The part's display window differs from the first part's. - own_display: bool, -} - -/// A decoded part: its kept planes (in channel order) and what [`PlanesReader`] found. -struct PartPlanes { - planes: Vec<(String, Vec)>, - /// Positions in `planes` of the part's R, G, B (and A) channels, when it has them and keeps - /// them all. - rgb: Option<([usize; 3], Option)>, - has_rgb: bool, - exact: bool, -} - -impl<'s> ReadChannels<'s> for Planes<'_> { - type Reader = PlanesReader; - - fn create_channels_reader(&'s self, header: &Header) -> exr::error::Result { - if header.deep { - return Err(exr::error::Error::NotSupported("deep data".into())); - } - let dw = self.display; - let display = (dw.size.0, dw.size.1); - // Each channel is a display-window plane: a 60000² window over a 1×1 data window was a - // multi-gigabyte allocation per channel (#2141). - let n = display.0.checked_mul(display.1).filter(|n| *n > 0 && *n <= MAX_DISPLAY_PIXELS).ok_or(exr::error::Error::Invalid("display window".into()))?; - let prefix = part_name(header); - let pos = header.own_attributes.layer_position; - let offset = (i64::from(pos.0) - i64::from(dw.position.0), i64::from(pos.1) - i64::from(dw.position.1)); - let planes = header - .channels - .list - .iter() - .map(|ch| { - let name = channel_name(prefix.as_deref(), &ch.name.to_string()); - let fill = if is_depth(&name) { BACKGROUND_DEPTH } else { 0.0 }; - (self.keep)(&name).then(|| (name, ch.sample_type, vec![fill; n])) - }) - .collect(); - let find = |c: &str| header.channels.find_index_of_channel(&exr::meta::attribute::Text::from(c)); - let rgb = match (find("R"), find("G"), find("B")) { - (Some(r), Some(g), Some(b)) => Some(([r, g, b], find("A"))), - _ => None, - }; - Ok(PlanesReader { - planes, - offset, - layer: (header.layer_size.0, header.layer_size.1), - display, - f16s: vec![], - u32s: vec![], - f32s: vec![], - rgb, - own_display: header.shared_attributes.display_window != dw, - }) - } -} - -impl ChannelsReader for PlanesReader { - type Channels = PartPlanes; - - fn filter_block(&self, tile: TileCoordinates) -> bool { - tile.is_largest_resolution_level() && self.planes.iter().any(Option::is_some) - } - - fn read_block(&mut self, header: &Header, block: UncompressedBlock) -> exr::error::UnitResult { - let ((lw, lh), (w, h)) = (self.layer, self.display); - for line in block.lines(&header.channels) { - let Some(Some((_, kind, plane))) = self.planes.get_mut(line.location.channel) else { continue }; - let (x0, y, count) = (line.location.position.0, line.location.position.1, line.location.sample_count); - // The samples of data-window row `y`, columns `x0..x0 + count`, at display row `ty` - // from display column `tx0`; clipped to the display window. - if y >= lh || x0.checked_add(count).is_none_or(|end| end > lw) { - continue; - } - let Some(ty) = usize::try_from(y as i64 + self.offset.1).ok().filter(|ty| *ty < h) else { continue }; - let tx0 = x0 as i64 + self.offset.0; - let skip = usize::try_from(-tx0).unwrap_or(0).min(count); - let tx = usize::try_from(tx0.max(0)).unwrap_or(usize::MAX); - let take = (count - skip).min(w.saturating_sub(tx)); - let start = ty.checked_mul(w).and_then(|row| row.checked_add(tx)); - let Some(dst) = start.filter(|_| take > 0).and_then(|s| plane.get_mut(s..s.checked_add(take)?)) else { continue }; - match kind { - SampleType::F16 => { - self.f16s.resize(count, exr::prelude::f16::ZERO); - line.read_samples_into_slice(&mut self.f16s)?; - for (d, s) in dst.iter_mut().zip(self.f16s.iter().skip(skip)) { - *d = s.to_f32(); - } - } - SampleType::F32 => { - self.f32s.resize(count, 0.0); - line.read_samples_into_slice(&mut self.f32s)?; - for (d, s) in dst.iter_mut().zip(self.f32s.iter().skip(skip)) { - *d = *s; - } - } - SampleType::U32 => { - self.u32s.resize(count, 0); - line.read_samples_into_slice(&mut self.u32s)?; - for (d, s) in dst.iter_mut().zip(self.u32s.iter().skip(skip)) { - *d = *s as f32; - } - } - } - } - Ok(()) - } - - fn into_channels(self) -> PartPlanes { - // Positions of the kept channels among the kept planes. - let mut at = vec![None; self.planes.len()]; - let mut planes = Vec::with_capacity(self.planes.len()); - for (i, p) in self.planes.into_iter().enumerate() { - if let Some((name, _, data)) = p { - if let Some(slot) = at.get_mut(i) { - *slot = Some(planes.len()); - } - planes.push((name, data)); - } - } - let kept = |i: usize| at.get(i).copied().flatten(); - let has_rgb = self.rgb.is_some(); - let rgb = self.rgb.and_then(|([r, g, b], a)| { - let a = match a { - Some(a) => Some(kept(a)?), - None => None, - }; - Some(([kept(r)?, kept(g)?, kept(b)?], a)) - }); - PartPlanes { planes, rgb, has_rgb, exact: !self.own_display } - } + crate::exr_index::unsupported(&meta) } /// How the `image` crate's OpenEXR decoder would show a file: the first part with exact `R`, `G` /// and `B` channels (alpha `A` when it has one, else opaque), placed in the display window with /// 0 outside the data window. #[derive(Clone, Copy, Debug, PartialEq)] -enum Rgb { +pub(crate) enum Rgb { /// No part has R, G and B: the decoder refuses the file (a multi-layer file, shown with /// [`layered_image`]'s rule). None, - /// The channels (indices in [`AuxChannels::channels`]) hold exactly what it would show. + /// The channels (indices into [`ExrIndex::channels`]) hold exactly what it would show. Planes([usize; 3], Option), /// The planes can't stand in for it (a depth-named channel, whose plane is filled with the /// background depth, or another display window): decode with the `image` crate. Unsupported, } -/// A decoded file: its channels and how its picture is made of them. -pub(crate) struct Decoded { - pub(crate) aux: Arc, - rgb: Rgb, +/// How many bytes of decoded planes the plane store keeps, like the frame cache's default +/// ([`crate::DEFAULT_BUDGET`]): two 2560×1440 files of 32 channels (470 MB each, as every plane +/// is f32). A soft bound: the newest file is kept whatever its size (so a frame's picture and its +/// effects share its decode), and files still in use are never dropped (planes an effect holds, +/// pictures waiting for their effects, decodes in progress), so memory can go above it while +/// they are. (Measured on such a sequence decoded one frame at a time: 1 GiB held peak memory +/// about 1 GB lower than 2 GiB, at the same speed.) +#[cfg(not(target_arch = "wasm32"))] +pub const CACHE_BUDGET: usize = 1 << 30; +#[cfg(target_arch = "wasm32")] +pub const CACHE_BUDGET: usize = 512 << 20; + +/// The index of an EXR file's bytes and the planes of `ids` (all when `None`). `None` when it is +/// not a readable EXR or the planes need too much memory. +fn read_bytes(bytes: &[u8], ids: Option>) -> Option<(ExrIndex, Vec, Vec>)> { + let mut src = std::io::Cursor::new(bytes); + let index = crate::exr_index::build(&mut src, bytes.len() as u64, FileStamp::Virtual).ok()?; + let ids = ids.unwrap_or_else(|| (0..index.channels.len()).collect()); + let (planes, _) = read_planes(&mut src, &index, &ReadRequest::full(ids.clone())); + Some((index, ids, planes.ok()?)) } -impl Decoded { - /// Bytes held (the planes; names and manifests are small). - fn bytes(&self) -> usize { - self.aux.channels.iter().map(|(n, p)| n.len() + std::mem::size_of_val(p.as_slice())).sum() - } -} - -/// The most bytes of planes one decode allocates (every kept channel is a display-window plane -/// of f32, allocated before any pixels are read): a header can ask for far more than the file -/// holds. -#[cfg(target_pointer_width = "64")] -const MAX_DECODE_BYTES: usize = 8 << 30; -#[cfg(not(target_pointer_width = "64"))] -const MAX_DECODE_BYTES: usize = 512 << 20; - -/// Why a file's channels weren't decoded. -#[derive(Debug, PartialEq)] -enum Refused { - /// Not a readable OpenEXR file. - Unreadable, - /// Its kept channels need more memory than [`MAX_DECODE_BYTES`] (the reason, to show). - TooLarge(String), -} - -/// Bytes the planes of the channels `keep` names would take (`None`: not a readable header). -fn planes_bytes(meta: &exr::meta::MetaData, keep: &dyn Fn(&str) -> bool) -> Option { - let dw = meta.headers.first()?.shared_attributes.display_window; - let n = dw.size.0.checked_mul(dw.size.1)?; - let mut kept = 0usize; - for header in meta.headers.iter() { - let prefix = part_name(header); - kept = kept.saturating_add(header.channels.list.iter().filter(|ch| keep(&channel_name(prefix.as_deref(), &ch.name.to_string()))).count()); - } - Some(n.saturating_mul(kept).saturating_mul(std::mem::size_of::())) -} - -/// Decode the channels of an EXR file's bytes that `keep` names (by plane name). -fn decode(bytes: &[u8], keep: &dyn Fn(&str) -> bool) -> Result { - let meta = exr::meta::MetaData::read_from_buffered(std::io::Cursor::new(bytes), false).map_err(|_| Refused::Unreadable)?; - let display = meta.headers.first().ok_or(Refused::Unreadable)?.shared_attributes.display_window; - let need = planes_bytes(&meta, keep).ok_or(Refused::Unreadable)?; - if need > MAX_DECODE_BYTES { - let gb = |b: usize| b as f64 / f64::from(1u32 << 30); - return Err(Refused::TooLarge(format!( - "its {}×{} OpenEXR channels need {:.1} GB of memory, more than the {:.1} GB one file may use", - display.size.0, - display.size.1, - gb(need), - gb(MAX_DECODE_BYTES) - ))); - } - let read = ReadImage::new(ReadAllLayers { read_channels: Planes { keep, display } }, |_| {}); - let img = read.from_buffered(std::io::Cursor::new(bytes)).map_err(|_| Refused::Unreadable)?; - let dw = img.attributes.display_window; - let mut aux = AuxChannels::new(dw.size.0 as u32, dw.size.1 as u32, 1.0); - let mut crypto: HashMap, Option)> = HashMap::new(); - let mut collect_meta = |other: &HashMap| { - for (k, v) in other { - let key = k.to_string(); - let Some(rest) = key.strip_prefix("cryptomatte/") else { continue }; - let Some((id, field)) = rest.split_once('/') else { continue }; - let exr::meta::attribute::AttributeValue::Text(t) = v else { continue }; - let e = crypto.entry(id.to_string()).or_default(); - match field { - "name" => e.0 = Some(t.to_string()), - "manifest" => e.1 = Some(t.to_string()), - _ => {} - } - } - }; - collect_meta(&img.attributes.other); - let mut rgb = Rgb::None; - for layer in img.layer_data { - collect_meta(&layer.attributes.other); - let part = layer.channel_data; - if rgb == Rgb::None && part.has_rgb { - let base = aux.channels.len(); - rgb = match part.rgb { - Some(([r, g, b], a)) if part.exact => { - let picked = [Some(r), Some(g), Some(b), a]; - let depth = picked.iter().flatten().any(|i| part.planes.get(*i).is_some_and(|(n, _)| is_depth(n))); - if depth { Rgb::Unsupported } else { Rgb::Planes([base + r, base + g, base + b], a.map(|a| base + a)) } - } - _ => Rgb::Unsupported, - }; - } - aux.channels.extend(part.planes); - } - for (_, (name, manifest)) in crypto { - if let (Some(n), Some(m)) = (name, manifest) { - aux.manifests.push((n, parse_manifest(&m))); - } - } - aux.manifests.sort(); - Ok(Decoded { aux: Arc::new(aux), rgb }) +/// The channels `ids` of `index` with their `planes` (as [`read_bytes`] reads them). +fn aux_of(index: &ExrIndex, ids: &[usize], planes: Vec>) -> AuxChannels { + let (w, h) = index.size(); + let mut aux = AuxChannels::new(w as u32, h as u32, 1.0); + aux.channels = ids.iter().zip(planes).filter_map(|(id, p)| Some((index.channels.get(*id)?.name.clone(), p))).collect(); + aux.manifests = index.names.manifests.clone(); + aux.aliases = index.names.aliases.clone(); + aux } /// Read all channels of an EXR file's bytes. `None` when it is not a readable EXR. pub fn read_exr_channels(bytes: &[u8]) -> Option { - let aux = decode(bytes, &|_| true).ok()?.aux; - Some(Arc::try_unwrap(aux).unwrap_or_else(|a| (*a).clone())) + let (index, ids, planes) = read_bytes(bytes, None)?; + Some(aux_of(&index, &ids, planes)) } /// Names of the beauty pass, most preferred first, matched against the last part of a layer's @@ -394,7 +157,7 @@ fn picture_layer<'a>(aux: &AuxChannels, layers: &[&'a str]) -> Option<&'a str> { /// The planes a multi-layer file's picture is made of (see [`layered_image`]): red, green, blue /// (one channel thrice for grey) and alpha, by name. Only the names of `aux` are read. -fn picture_names(aux: &AuxChannels) -> Option<([String; 3], Option)> { +pub(crate) fn picture_names(aux: &AuxChannels) -> Option<([String; 3], Option)> { let layers = aux.layers(); let colour = picture_layer(aux, &layers)?; let names = aux.layer_rgba(colour); @@ -405,32 +168,19 @@ fn picture_names(aux: &AuxChannels) -> Option<([String; 3], Option)> { Some(([pick(0), pick(1), pick(2)], a)) } -/// The channels of the picture of a multi-layer file and nothing else (names first from the -/// headers, then only those channels decoded; in a multi-part file the other parts' pixels are -/// not even decompressed), with the names of its planes. -fn picture_only(bytes: &[u8]) -> Result<(Decoded, [String; 3], Option), Refused> { - let meta = exr::meta::MetaData::read_from_buffered(std::io::Cursor::new(bytes), false).map_err(|_| Refused::Unreadable)?; - let mut names = AuxChannels::new(0, 0, 1.0); - for header in meta.headers.iter() { - let prefix = part_name(header); - names.channels.extend(header.channels.list.iter().map(|ch| (channel_name(prefix.as_deref(), &ch.name.to_string()), vec![]))); - } - let (rgb, a) = picture_names(&names).ok_or(Refused::Unreadable)?; - // Planes are looked up by name ignoring case, so every channel that could answer is kept. - let keep = |n: &str| rgb.iter().chain(&a).any(|k| k.eq_ignore_ascii_case(n)); - let decoded = decode(bytes, &keep)?; - Ok((decoded, rgb, a)) -} - /// The picture of a multi-layer OpenEXR file without an unnamed RGB layer (Blender's /// `ViewLayer.Combined.R`, the compositor's `Image.R`, Nuke's `beauty.R`, …), which the image /// decoder rejects. After Effects shows a file's main RGBA channels and leaves the other layers /// to EXtractoR; here that is the beauty pass by name (`BEAUTY`), else the first colour layer /// that is not a data pass (never Cryptomatte, depth or normals, #412), else the first channel /// as grey. Linear, straight RGBA as the file stores it. `None` when it is not a readable EXR. +/// Only the picture's channels are decoded (in a multi-part file the other parts aren't read). pub fn layered_image(bytes: &[u8]) -> Option { - let (d, rgb, a) = picture_only(bytes).ok()?; - let aux = &d.aux; + let mut src = std::io::Cursor::new(bytes); + let index = crate::exr_index::build(&mut src, bytes.len() as u64, FileStamp::Virtual).ok()?; + let (ids, rgb, a) = index.picture.clone()?; + let (planes, _) = read_planes(&mut src, &index, &ReadRequest::full(ids.clone())); + let aux = aux_of(&index, &ids, planes.ok()?); let [r, g, b] = [aux.get(&rgb[0])?, aux.get(&rgb[1])?, aux.get(&rgb[2])?]; let a = match &a { Some(n) => Some(aux.get(n)?), @@ -450,10 +200,20 @@ pub fn layered_image(bytes: &[u8]) -> Option { } } +/// The size and alpha of a layered file's picture ([`layered_image`]) from its headers alone +/// (import). `None` when it is not a readable EXR. +pub(crate) fn layered_size(bytes: &[u8]) -> Option<(u32, u32, bool)> { + let mut src = std::io::Cursor::new(bytes); + let index = crate::exr_index::build(&mut src, bytes.len() as u64, FileStamp::Virtual).ok()?; + let (_, _, a) = index.picture.as_ref()?; + let (w, h) = index.size(); + Some((w as u32, h as u32, a.is_some())) +} + /// The picture made of planes `rgb` and `a` (opaque without one) of `aux`, as /// [`crate::convert::dynamic_to_image`] makes it of the same values. `None` when a plane is /// missing or short. -fn planes_picture(aux: &AuxChannels, rgb: [&[f32]; 3], a: Option<&[f32]>, op: AlphaOp) -> Option { +pub(crate) fn planes_picture(aux: &AuxChannels, rgb: [&[f32]; 3], a: Option<&[f32]>, op: AlphaOp) -> Option { let n = (aux.width as usize).checked_mul(aux.height as usize)?; if rgb.iter().chain(&a).any(|p| p.len() < n) { return None; @@ -463,306 +223,14 @@ fn planes_picture(aux: &AuxChannels, rgb: [&[f32]; 3], a: Option<&[f32]>, op: Al Some(float_to_image(aux.width, aux.height, op, |i| [at(r, i), at(g, i), at(b, i), a.map_or(1.0, |a| at(a, i))])) } -/// The picture of a decoded file by [`layered_image`]'s rule. -fn layered_picture_of(aux: &AuxChannels, op: AlphaOp) -> Option { - let (rgb, a) = picture_names(aux)?; - let a = match &a { - Some(n) => Some(aux.get(n)?), - None => None, - }; - planes_picture(aux, [aux.get(&rgb[0])?, aux.get(&rgb[1])?, aux.get(&rgb[2])?], a, op) -} - -/// The picture of the multi-layer EXR at `path` ([`layered_image`]'s rule) as an [`Image`]: -/// from the channel cache when `shared` (an effect reads the footage's channels, so they are -/// decoded anyway), else of the picture's channels alone (also when the cache has no channels -/// for the file: a read that failed, or a broken part the picture doesn't use). `Err(Some(why))` -/// when the file is too large to decode, `Err(None)` when it isn't a readable multi-layer EXR. -pub(crate) fn layered_picture(path: &str, bytes: Arc<[u8]>, file: &ReadFile, op: AlphaOp, shared: bool) -> Result> { - if shared && let Some(d) = cache().get(path, Use::Picture, || read_as(file, bytes.clone())) { - return layered_picture_of(&d.aux, op).ok_or(None); - } - let (d, rgb, a) = picture_only(&bytes).map_err(|r| match r { - Refused::TooLarge(why) => Some(why), - Refused::Unreadable => None, - })?; - let aux = &d.aux; - let plane = |n: &str| aux.get(n).ok_or(None); - let a = match &a { - Some(n) => Some(plane(n)?), - None => None, - }; - planes_picture(aux, [plane(&rgb[0])?, plane(&rgb[1])?, plane(&rgb[2])?], a, op).ok_or(None) -} - -/// The picture of the EXR at `path` from the channel cache (#474: EXtractoR / Cryptomatte read -/// this footage's channels, so the picture shares their decode): what the `image` crate's -/// decoder shows for a file it reads, [`layered_image`]'s rule for one it refuses. `None` when -/// the planes can't stand in for the `image` crate's picture (decode with it), or the file is -/// not a readable EXR. -pub(crate) fn cached_picture(path: &str, bytes: Arc<[u8]>, file: &ReadFile, op: AlphaOp) -> Option { - let d = cache().get(path, Use::Picture, || read_as(file, bytes))?; - let aux = &d.aux; - match d.rgb { - Rgb::None => layered_picture_of(aux, op), - Rgb::Planes([r, g, b], a) => { - let plane = |i: usize| aux.channels.get(i).map(|(_, p)| p.as_slice()); - let a = match a { - Some(a) => Some(plane(a)?), - None => None, - }; - planes_picture(aux, [plane(r)?, plane(g)?, plane(b)?], a, op) - } - Rgb::Unsupported => None, - } -} - -/// How many bytes of decoded channels the cache keeps, like the frame cache's default -/// ([`crate::DEFAULT_BUDGET`]): two 2560×1440 files of 32 channels (470 MB each, as every plane -/// is f32). A soft bound: the newest file is kept whatever its size (so a frame's picture and its -/// effects share its decode), and files still in use are never dropped (planes an effect holds, -/// [`HELD_FILES`] pictures waiting for their effects, decodes in progress), so memory can go -/// above it while they are. (Measured on such a sequence decoded one frame at a time: 1 GiB held -/// peak memory about 1 GB lower than 2 GiB, at the same speed.) -#[cfg(not(target_arch = "wasm32"))] -pub const CACHE_BUDGET: usize = 1 << 30; -#[cfg(target_arch = "wasm32")] -pub const CACHE_BUDGET: usize = 512 << 20; - -/// At most this many files are cached (unreadable ones hold no bytes). -const CACHE_FILES: usize = 64; - -/// At most this many files whose picture was made of their planes are kept for their effects -/// (the renderer asks for a frame's picture, then its channels): about as many frames as are -/// rendered at once. The oldest stops being kept when another comes. -const HELD_FILES: usize = 4; - -/// A file's decode: done once, by the first caller; the others wait for it. With the files read -/// for it (see [`crate::reads`]), noted again on every hit. -type Slot = Arc>, ReadFiles)>>; - -/// Bytes the caller already read from `file`, given to the cache as read from it (so the entry -/// keeps the file's identity). -fn read_as(file: &ReadFile, bytes: Arc<[u8]>) -> Option> { - crate::reads::note(file.clone()); - Some(bytes) -} - -struct Entry { - path: String, - slot: Slot, - /// Bytes of the finished decode, or the planes it will allocate while it decodes. - bytes: usize, - /// When it was last asked for or finished decoding (a counter). - used: u64, -} - -impl Entry { - /// Dropping it would free nothing or lose a decode in progress: an effect (or a picture - /// waiting for its effects) still holds its planes, or it is decoding. - fn in_use(&self) -> bool { - match self.slot.get() { - None => true, - Some((None, _)) => false, - Some((Some(d), _)) => Arc::strong_count(d) > 1 || Arc::strong_count(&d.aux) > 1, - } - } -} - -struct State { - entries: Vec, - clock: u64, - /// Files whose picture was made of their planes and whose channels haven't been asked for - /// since, oldest first (at most [`HELD_FILES`]). - held: std::collections::VecDeque<(String, Arc)>, -} - -/// Who asks for a file's channels. -#[derive(Clone, Copy, PartialEq)] -pub(crate) enum Use { - /// The picture of a footage item whose effects read its channels next: kept for them. - Picture, - /// The channels themselves (EXtractoR, Cryptomatte, the 3D Channel effects). - Channels, -} - -/// Decoded EXR files by path, bounded by bytes, least recently used out first. -pub(crate) struct ChannelCache { - state: Mutex, - budget: usize, - /// Files decoded (for tests). - decodes: AtomicU64, -} - -/// Removes a decode's entry if the decode panics, so the file doesn't stay "decoding" (never -/// dropped, its estimated bytes counted) until someone asks for it again. -struct Abandon<'a> { - cache: &'a ChannelCache, - slot: &'a Slot, -} - -impl Drop for Abandon<'_> { - fn drop(&mut self) { - if std::thread::panicking() { - self.cache.lock().entries.retain(|e| !Arc::ptr_eq(&e.slot, self.slot)); - } - } -} - -impl ChannelCache { - pub(crate) const fn new(budget: usize) -> Self { - Self { state: Mutex::new(State { entries: Vec::new(), clock: 0, held: std::collections::VecDeque::new() }), budget, decodes: AtomicU64::new(0) } - } - - fn lock(&self) -> std::sync::MutexGuard<'_, State> { - self.state.lock().unwrap_or_else(PoisonError::into_inner) - } - - /// Set the bytes of the entry of `slot` (if it's still cached), mark it used now and drop - /// least recently used files until the rest fit the budget. - fn account(&self, slot: &Slot, bytes: usize) { - let mut state = self.lock(); - state.clock += 1; - let clock = state.clock; - // (gone when the file was forgotten meanwhile) Used as of now: a file asked for before - // another but decoded after it is not the older one. - if let Some(e) = state.entries.iter_mut().find(|e| Arc::ptr_eq(&e.slot, slot)) { - e.bytes = bytes; - e.used = clock; - } - Self::evict(&mut state.entries, self.budget, slot); - } - - /// The decoded file at `path`, read with `read` by the first caller; callers asking for the - /// same file meanwhile wait for that decode instead of decoding it again. - pub(crate) fn get(&self, path: &str, by: Use, read: impl FnOnce() -> Option>) -> Option> { - let slot = { - let mut state = self.lock(); - state.clock += 1; - let clock = state.clock; - match state.entries.iter_mut().find(|e| e.path == path) { - Some(e) => { - e.used = clock; - e.slot.clone() - } - None => { - let slot = Slot::default(); - state.entries.push(Entry { path: path.to_string(), slot: slot.clone(), bytes: 0, used: clock }); - slot - } - } - }; - let mut decoded_here = false; - // Waiting here can block a rayon worker (a footage decode thread, or a frame worker asking - // for channels): that is safe because the decode never waits on a rayon pool (the exr crate - // decompresses on a pool of its own and this thread only receives the blocks), so the - // decoding thread can't be waiting for this one. - let (v, files) = slot.get_or_init(|| { - decoded_here = true; - self.decodes.fetch_add(1, Ordering::Relaxed); - #[cfg(test)] - count_decode(true); - let _abandon = Abandon { cache: self, slot: &slot }; - let (bytes, files) = crate::reads::captured(read); - (bytes.and_then(|bytes| self.decode_file(path, &slot, &bytes)), files) - }); - // The file(s) the decode was made of, read now or for an earlier caller. - crate::reads::note_all(files); - let v = v.clone(); - if decoded_here { - self.account(&slot, v.as_ref().map_or(0, |d| d.bytes())); - } - let mut state = self.lock(); - match (by, &v) { - (Use::Picture, Some(d)) => { - if !state.held.iter().any(|(p, _)| p == path) { - state.held.push_back((path.to_string(), d.clone())); - if state.held.len() > HELD_FILES { - state.held.pop_front(); - } - } - } - (Use::Channels, _) => state.held.retain(|(p, _)| p != path), - (Use::Picture, None) => {} - } - drop(state); - v - } - - /// Decode the file at `path` whose bytes are `bytes` for `slot` (see [`ChannelCache::get`]). - fn decode_file(&self, path: &str, slot: &Slot, bytes: &[u8]) -> Option> { - // The planes it will allocate count against the budget while it decodes. - if let Ok(meta) = exr::meta::MetaData::read_from_buffered(std::io::Cursor::new(bytes), false) - && let Some(need) = planes_bytes(&meta, &|_| true) - { - self.account(slot, need.min(MAX_DECODE_BYTES)); - } - match decode(bytes, &|_| true) { - Ok(d) => Some(Arc::new(d)), - Err(Refused::TooLarge(why)) => { - log::warn!("media: {path}: {why}"); - None - } - Err(Refused::Unreadable) => None, - } - } - - /// Drop least recently used files not in use until the rest fit the budget, keeping `newest`. - fn evict(entries: &mut Vec, budget: usize, newest: &Slot) { - while entries.iter().map(|e| e.bytes).sum::() > budget || entries.len() > CACHE_FILES { - let oldest = entries.iter().enumerate().filter(|(_, e)| !Arc::ptr_eq(&e.slot, newest) && !e.in_use()).min_by_key(|(_, e)| e.used).map(|(i, _)| i); - let Some(i) = oldest else { break }; - entries.remove(i); - } - } - - pub(crate) fn forget(&self, path: &str) { - let mut state = self.lock(); - state.entries.retain(|e| e.path != path); - state.held.retain(|(p, _)| p != path); - } - - #[cfg(test)] - fn decodes(&self) -> u64 { - self.decodes.load(Ordering::Relaxed) - } - - #[cfg(test)] - fn cached(&self) -> Vec { - self.lock().entries.iter().map(|e| e.path.clone()).collect() - } -} - -fn cache() -> &'static ChannelCache { - static CACHE: ChannelCache = ChannelCache::new(CACHE_BUDGET); - &CACHE -} - -/// Drop the cached channels of `path` (the file changed on disk). -pub(crate) fn forget(path: &str) { - cache().forget(path); -} - -/// Stop keeping the decodes of the last pictures for their effects ([`HELD_FILES`]): which -/// footage effects read changed, so they may wait for effects that are gone. Their entries stay -/// cached as any other, least recently used out first. -pub(crate) fn release_held() { - cache().lock().held.clear(); -} - -/// Read (and cache, see [`CACHE_BUDGET`]) the channels of the EXR at `path` via `read`. -pub(crate) fn cached(path: &str, read: impl FnOnce() -> Option>) -> Option> { - cache().get(path, Use::Channels, read).map(|d| d.aux.clone()) -} - #[cfg(test)] thread_local! { /// Decodes of a still's pixels on this thread ([`count_decode`]): the `image` crate's, then - /// the channel cache's. + /// the plane store's. static DECODES: std::cell::Cell<[u64; 2]> = const { std::cell::Cell::new([0; 2]) }; } -/// Count a decode of a file's pixels on this thread (tests): by the channel cache (`channels`) +/// Count a decode of a file's pixels on this thread (tests): by the plane store (`channels`) /// or by the `image` crate. #[cfg(test)] pub(crate) fn count_decode(channels: bool) { @@ -774,7 +242,7 @@ pub(crate) fn count_decode(channels: bool) { } /// The decodes [`count_decode`] counted on this thread since the last call: by the `image` crate -/// and by the channel cache. +/// and by the plane store. #[cfg(test)] pub(crate) fn take_decodes() -> [u64; 2] { DECODES.with(|d| d.replace([0; 2])) @@ -803,6 +271,7 @@ pub(crate) fn add_decodes(n: [u64; 2]) { #[cfg(test)] mod tests { use super::*; + use effectcraft_raster::channels3d::BACKGROUND_DEPTH; /// An EXR file of `layers` (with their display window `display`). fn file(layers: Vec>>, display: exr::prelude::IntegerBounds) -> Vec { @@ -813,14 +282,6 @@ mod tests { bytes.into_inner() } - /// A single-part file of float channels named `names`, `w`×`h`, every sample `v`. - fn flat(names: &[&str], (w, h): (usize, usize), v: f32) -> Vec { - use exr::prelude::*; - let list: Vec> = names.iter().map(|n| AnyChannel::new(*n, FlatSamples::F32(vec![v; w * h]))).collect(); - let layer = Layer::new((w, h), LayerAttributes::default(), Encoding::FAST_LOSSLESS, AnyChannels::sort(list.into())); - file(vec![layer], IntegerBounds::from_dimensions((w, h))) - } - #[test] fn reads_layered_channels_and_cryptomatte_metadata() { use exr::prelude::*; @@ -888,153 +349,6 @@ mod tests { assert_eq!(read_exr_channels(&away).unwrap().get("G").unwrap(), [0.0; 6]); } - /// #474: concurrent requests for a file that isn't cached decode it once; the others wait - /// for that decode and share its planes. - #[test] - fn concurrent_requests_decode_a_file_once() { - let bytes: Arc<[u8]> = flat(&["R", "G", "B", "Z"], (64, 64), 0.5).into(); - let cache = ChannelCache::new(CACHE_BUDGET); - let reads = AtomicU64::new(0); - let barrier = std::sync::Barrier::new(8); - let got: Vec> = std::thread::scope(|s| { - let jobs: Vec<_> = (0..8) - .map(|_| { - s.spawn(|| { - barrier.wait(); - cache - .get("/474-concurrent.exr", Use::Channels, || { - reads.fetch_add(1, Ordering::Relaxed); - // Long enough for the others to arrive while this one decodes. - std::thread::sleep(std::time::Duration::from_millis(50)); - Some(bytes.clone()) - }) - .unwrap() - }) - }) - .collect(); - jobs.into_iter().map(|j| j.join().unwrap()).collect() - }); - assert_eq!(cache.decodes(), 1, "one decode"); - assert_eq!(reads.load(Ordering::Relaxed), 1, "the file is read once"); - assert!(got.iter().all(|d| Arc::ptr_eq(d, &got[0])), "every caller has the same planes"); - assert_eq!(got[0].aux.get("Z").and_then(|z| z.first()).copied(), Some(0.5)); - } - - /// #474: the cache is bounded by the bytes of its planes, least recently used out first; the - /// newest file stays even when it alone is over the budget, and unreadable files are cached - /// (as such) without counting bytes. - #[test] - fn cache_evicts_least_recently_used_by_bytes() { - // 4 float planes of 32×32: 16 KiB of samples (plus a few bytes of names) per file. - let bytes: Arc<[u8]> = flat(&["R", "G", "B", "A"], (32, 32), 0.25).into(); - let one = 4 * 32 * 32 * 4 + 4; - let cache = ChannelCache::new(2 * one); - let get = |p: &str| cache.get(p, Use::Channels, || Some(bytes.clone())).unwrap(); - assert_eq!(get("/a.exr").bytes(), one); - get("/b.exr"); - get("/a.exr"); // a is now more recent than b - get("/c.exr"); - assert_eq!(cache.cached(), ["/a.exr", "/c.exr"], "b was least recently used"); - assert_eq!(cache.decodes(), 3); - get("/a.exr"); - assert_eq!(cache.decodes(), 3, "a hit"); - // A file over the budget on its own is still kept while it is the newest. - let small = ChannelCache::new(one / 2); - assert!(small.get("/big.exr", Use::Channels, || Some(bytes.clone())).is_some()); - assert_eq!(small.cached(), ["/big.exr"]); - small.get("/big2.exr", Use::Channels, || Some(bytes.clone())); - assert_eq!(small.cached(), ["/big2.exr"]); - // An unreadable file is remembered (not read again) without bytes, and forgotten on request. - assert!(cache.get("/broken.exr", Use::Channels, || Some(Arc::from(&b"not an exr"[..]))).is_none()); - assert!(cache.get("/broken.exr", Use::Channels, || panic!("not read again")).is_none()); - cache.forget("/broken.exr"); - assert!(!cache.cached().contains(&"/broken.exr".to_string())); - // At most CACHE_FILES files, however small. - for i in 0..CACHE_FILES + 10 { - cache.get(&format!("/none{i}.exr"), Use::Channels, || None); - } - assert!(cache.cached().len() <= CACHE_FILES); - } - - /// #474: a file counts as used when its decode finishes: one asked for first but decoded - /// after another is the newer of the two, so concurrent frames don't evict each other's - /// files before their effects read them. - #[test] - fn a_file_is_used_as_of_its_decode() { - let bytes: Arc<[u8]> = flat(&["R", "G", "B", "A"], (32, 32), 0.25).into(); - let one = 4 * 32 * 32 * 4 + 4; - let cache = ChannelCache::new(2 * one); - cache.get("/first.exr", Use::Channels, || { - // Another frame's file is asked for and decoded while this one decodes. - cache.get("/second.exr", Use::Channels, || Some(bytes.clone())); - Some(bytes.clone()) - }); - cache.get("/third.exr", Use::Channels, || Some(bytes.clone())); - assert_eq!(cache.cached(), ["/first.exr", "/third.exr"], "the file decoded first went first"); - } - - /// #474: frames rendered at once (each asks for its picture, then its effects for the - /// channels while other frames decode) decode each file once, though the budget holds only - /// one: a picture's file is kept for its effects, and files in use are never dropped. - #[test] - fn concurrent_frames_decode_each_file_once() { - let bytes: Arc<[u8]> = flat(&["R", "G", "B", "Z"], (64, 64), 0.5).into(); - let cache = ChannelCache::new(4 * 64 * 64 * 4 + 4); - let (next, reads, frames) = (std::sync::atomic::AtomicUsize::new(0), AtomicU64::new(0), 24); - let read = || { - reads.fetch_add(1, Ordering::Relaxed); - Some(bytes.clone()) - }; - std::thread::scope(|s| { - for _ in 0..4 { - s.spawn(|| { - loop { - let i = next.fetch_add(1, Ordering::Relaxed); - if i >= frames { - break; - } - let path = format!("/474-frames/{i:04}.exr"); - drop(cache.get(&path, Use::Picture, read).unwrap()); - std::thread::sleep(std::time::Duration::from_millis(3)); - let aux = cache.get(&path, Use::Channels, read).unwrap(); - std::thread::sleep(std::time::Duration::from_millis(2)); - assert_eq!(aux.aux.get("Z").and_then(|z| z.first()).copied(), Some(0.5)); - } - }); - } - }); - assert_eq!(cache.decodes(), frames as u64, "one decode per frame"); - assert_eq!(reads.load(Ordering::Relaxed), frames as u64); - } - - /// #474: a decode that panics doesn't leave its file "decoding" in the cache (never dropped, - /// its planes counted): the entry goes, and the next request decodes the file. - #[test] - fn a_decode_that_panics_is_not_left_in_the_cache() { - let bytes: Arc<[u8]> = flat(&["R"], (8, 8), 1.0).into(); - let cache = ChannelCache::new(CACHE_BUDGET); - let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| cache.get("/474-panics.exr", Use::Channels, || panic!("the read failed")))); - assert!(r.is_err()); - assert!(cache.cached().is_empty()); - assert!(cache.get("/474-panics.exr", Use::Channels, || Some(bytes.clone())).is_some()); - assert_eq!(cache.cached(), ["/474-panics.exr"]); - } - - /// #474: the picture of a multi-layer file whose effects read its channels comes from the - /// cache, and from the picture's own channels when the cache has none for the file (a read - /// that failed, or a broken part the picture doesn't use). - #[test] - fn a_shared_picture_without_cached_channels_is_still_decoded() { - use effectcraft_project::Footage; - use effectcraft_render::FloatCurve; - let bytes: Arc<[u8]> = flat(&["Image.R", "Image.G", "Image.B", "depth.Z"], (4, 2), 0.5).into(); - let path = "/474-shared-fallback.exr"; - assert!(cache().get(path, Use::Channels, || None).is_none(), "a read that failed"); - let op = AlphaOp::of(&Footage::default(), FloatCurve::Linear); - let img = layered_picture(path, bytes, &ReadFile::new(path, effectcraft_render::reads::FileStamp::Virtual), op, true).unwrap(); - assert_eq!(img.get(1, 1), [0.5, 0.5, 0.5, 1.0]); - } - /// #474: a header asking for more plane memory than one decode may allocate (16384² display /// window, 40 channels: 43 GB) is refused with a reason before anything is allocated. #[test] @@ -1043,179 +357,20 @@ mod tests { let list: Vec> = (0..40).map(|i| AnyChannel::new(format!("pass{i:02}.Y").as_str(), FlatSamples::F32(vec![0.5]))).collect(); let layer = Layer::new((1, 1), LayerAttributes::default(), Encoding::FAST_LOSSLESS, AnyChannels::sort(list.into())); let bytes = file(vec![layer], IntegerBounds::new((0, 0), (16384, 16384))); - match decode(&bytes, &|_| true) { - Err(Refused::TooLarge(why)) => assert!(why.contains("16384×16384") && why.contains("GB"), "{why}"), - Err(Refused::Unreadable) => panic!("readable"), + let mut src = std::io::Cursor::new(bytes.as_slice()); + let index = crate::exr_index::build(&mut src, bytes.len() as u64, FileStamp::Virtual).unwrap(); + let all = ReadRequest::full((0..index.channels.len()).collect()); + match read_planes(&mut src, &index, &all).0 { + Err(crate::exr_read::ReadError::TooLarge(why)) => assert!(why.contains("16384×16384") && why.contains("GB"), "{why}"), + Err(e) => panic!("readable: {e:?}"), Ok(_) => panic!("refused"), } assert!(read_exr_channels(&bytes).is_none()); - assert!(cached("/474-too-large.exr", || Some(bytes.as_slice().into())).is_none()); - } - - /// #474: a file forgotten (changed on disk) while it decodes isn't cached under its path when - /// that decode finishes. - #[test] - fn a_file_forgotten_while_it_decodes_is_not_cached() { - let bytes: Arc<[u8]> = flat(&["R"], (8, 8), 1.0).into(); - let cache = ChannelCache::new(CACHE_BUDGET); - let d = cache.get("/changed.exr", Use::Channels, || { - cache.forget("/changed.exr"); - Some(bytes.clone()) - }); - assert!(d.is_some()); - assert!(cache.cached().is_empty()); - } - - /// #295: a multi-layer EXR whose colour is only in named layers (`diffuse.R`, as Blender and - /// Nuke write them) failed to import ("does not contain non-deep rgb channels"); it now - /// shows its colour layer and keeps every channel for EXtractoR. - /// #474: once an effect has read a footage item's channels, the picture of each later frame - /// shares one decode with them: the frame's decode is cached and the channels come from it - /// without reading the file again. - #[test] - fn picture_and_aux_channels_share_one_decode() { - use exr::prelude::*; - let (w, h) = (2usize, 2usize); - let frame = |v: f32| -> Arc<[u8]> { - let ch = |n: &str, v: f32| AnyChannel::new(n, FlatSamples::F32(vec![v; w * h])); - let channels = AnyChannels::sort(vec![ch("Image.R", 0.5), ch("Image.G", 0.5), ch("Image.B", 0.5), ch("GlossDir.R", v)].into()); - let image = Image::from_layer(Layer::new((w, h), LayerAttributes::default(), Encoding::FAST_LOSSLESS, channels)); - let mut bytes = std::io::Cursor::new(Vec::new()); - image.write().to_buffered(&mut bytes).unwrap(); - bytes.into_inner().into() - }; - let paths = ["/474-shared-decode_0001.exr", "/474-shared-decode_0002.exr"]; let pool = crate::MediaPool::new(); - pool.add_bytes(paths[0], frame(0.25)); - pool.add_bytes(paths[1], frame(0.75)); - let mut f = crate::probe_bytes(paths[0], frame(0.25)).unwrap(); - f.kind = effectcraft_project::FootageKind::Sequence; - f.sequence = paths.iter().map(|p| p.to_string()).collect(); - let t1 = f.frame_rate.tick_of(1); + pool.add_bytes("/474-too-large.exr", bytes.as_slice().into()); + let f = effectcraft_project::Footage { path: "/474-too-large.exr".into(), kind: effectcraft_project::FootageKind::Still, has_video: true, width: 16384, height: 16384, ..Default::default() }; use effectcraft_render::FootageSource; - // The first frame: the picture, then an effect reads the channels. - pool.frame_at(&f, effectcraft_time::Tick::ZERO).unwrap(); - let aux = pool.aux(effectcraft_project::ItemId(1), &f, effectcraft_time::Tick::ZERO).unwrap(); - assert_eq!(aux.get("GlossDir.R").and_then(|p| p.first()).copied(), Some(0.25)); - // The next frame's picture decodes the file into the cache, so its channels are not read. - let px = pool.frame_at(&f, t1).unwrap().get(0, 0); - let aux = cached(paths[1], || panic!("the frame's decode is reused, the file is not read again")).unwrap(); - assert_eq!(aux.get("GlossDir.R").and_then(|p| p.first()).copied(), Some(0.75)); - assert_eq!(px, pool.frame_at(&f, effectcraft_time::Tick::ZERO).unwrap().get(0, 0), "the same picture"); - } - - /// An EXR file with an unnamed RGB layer and a named `GlossDir.R` of `v` (2×2). - fn rgb_and_gloss(v: f32) -> Arc<[u8]> { - flat(&["R", "G", "B", "GlossDir.R"], (2, 2), v).into() - } - - /// #474: footage the project says effects read the channels of - /// ([`FootageSource::set_aux_footage`]) costs one decode from its first frame on: a single - /// still with EXtractoR decodes once. Without it the first frame decodes twice (the picture, - /// then the channels once `aux()` asks). - #[test] - fn given_aux_footage_decodes_once_from_the_first_frame() { - use effectcraft_render::FootageSource; - let (given, learned) = ("/474-given-still.exr", "/474-learned-still.exr"); - let pool = crate::MediaPool::new(); - let mut f = std::collections::HashMap::new(); - for p in [given, learned] { - pool.add_bytes(p, rgb_and_gloss(0.25)); - f.insert(p, crate::probe_bytes(p, rgb_and_gloss(0.25)).unwrap()); - } - pool.set_aux_footage(&[given.to_string()]); - take_decodes(); - let t = effectcraft_time::Tick::ZERO; - pool.frame_at(&f[given], t).unwrap(); - let aux = pool.aux(effectcraft_project::ItemId(1), &f[given], t).unwrap(); - assert_eq!(aux.get("GlossDir.R").and_then(|p| p.first()).copied(), Some(0.25)); - assert_eq!(take_decodes(), [0, 1], "the picture and the channels share one decode"); - // Learned only at the first `aux()`: the picture was decoded on its own before. - pool.frame_at(&f[learned], t).unwrap(); - pool.aux(effectcraft_project::ItemId(2), &f[learned], t).unwrap(); - assert_eq!(take_decodes(), [1, 1]); - } - - /// #474: once the project no longer names footage (its effect removed), later frames decode - /// only their picture again; what `aux()` learned is dropped with each new set too. - #[test] - fn a_new_aux_footage_set_returns_to_picture_only() { - use effectcraft_render::FootageSource; - let paths: Vec = (1..=4).map(|i| format!("/474-unset_{i:04}.exr")).collect(); - let pool = crate::MediaPool::new(); - for p in &paths { - pool.add_bytes(p, rgb_and_gloss(0.5)); - } - let mut f = crate::probe_bytes(&paths[0], rgb_and_gloss(0.5)).unwrap(); - f.kind = effectcraft_project::FootageKind::Sequence; - f.sequence = paths.clone(); - let at = |i: i64| f.frame_rate.tick_of(i); - // (counted on this thread, so other tests sharing the channel cache don't change them) - let frame = |i: i64| { - take_decodes(); - pool.frame_at(&f, at(i)).unwrap(); - take_decodes() - }; - pool.set_aux_footage(std::slice::from_ref(&f.path)); - assert_eq!(frame(0), [0, 1], "given: the picture comes from the channel decode"); - pool.set_aux_footage(&[]); - assert!(!cache().lock().held.iter().any(|(p, _)| *p == paths[0]), "no longer kept once no effect reads it"); - assert_eq!(frame(1), [1, 0], "no longer given: the picture alone"); - // Learned by `aux()`, then a new set without it: picture only again. - pool.aux(effectcraft_project::ItemId(1), &f, at(1)).unwrap(); - assert_eq!(frame(2), [0, 1], "learned"); - pool.set_aux_footage(&[]); - assert_eq!(frame(3), [1, 0], "a new set drops what was learned"); - } - - /// #474: the picture made of the cached planes of a file with exact R, G, B channels is the - /// `image` crate's, bit for bit (first such part, alpha or opaque, data window placed with 0 - /// around it), in every alpha interpretation and float curve. - #[test] - fn picture_from_planes_is_the_image_crates() { - use effectcraft_project::{AlphaMode, Footage}; - use effectcraft_render::FloatCurve; - use exr::prelude::*; - let half = |n: &str, v: f32, len: usize| AnyChannel::new(n, FlatSamples::F16((0..len).map(|i| f16::from_f32(v + i as f32 * 0.37 - 1.0)).collect())); - let float = |n: &str, v: f32, len: usize| AnyChannel::new(n, FlatSamples::F32((0..len).map(|i| ((i * 7) % 11) as f32 * v).collect())); - let part = |name: Option<&str>, pos: (i32, i32), size: (usize, usize), list: Vec>| { - let mut attrs = name.map_or_else(LayerAttributes::default, LayerAttributes::named); - attrs.layer_position = Vec2(pos.0, pos.1); - Layer::new(size, attrs, Encoding::SMALL_LOSSLESS, AnyChannels::sort(list.into())) - }; - let display = IntegerBounds::new((1, -1), (5, 4)); - let n = 20; - let files = [ - file( - vec![part(None, (1, -1), (5, 4), vec![half("R", 0.1, n), half("G", 0.2, n), half("B", 0.3, n), float("A", 0.1, n), float("Z", 2.0, n)])], - display, - ), - file(vec![part(None, (0, 0), (3, 2), vec![float("R", 0.4, 6), float("G", 0.5, 6), float("B", 0.6, 6), half("Image.R", 0.1, 6)])], display), - file( - vec![ - part(Some("diffuse"), (1, -1), (5, 4), vec![half("R", 0.1, n), half("G", 0.2, n), half("B", 0.3, n)]), - part(Some("beauty"), (2, 0), (2, 2), vec![half("R", 0.4, 4), half("G", 0.5, 4), half("B", 0.6, 4), half("A", 0.5, 4)]), - ], - display, - ), - ]; - let bits = |i: &effectcraft_raster::Image| i.data.iter().flat_map(|p| p.map(f32::to_bits)).collect::>(); - for (k, bytes) in files.iter().enumerate() { - let path = format!("/474-planes-{k}.exr"); - let d = cache().get(&path, Use::Channels, || Some(bytes.as_slice().into())).unwrap(); - assert!(matches!(d.rgb, Rgb::Planes(..)), "file {k}: {:?}", d.rgb); - let img = crate::probe::load_oriented(bytes, Some(image::ImageFormat::OpenExr)).unwrap(); - for alpha in [AlphaMode::Straight, AlphaMode::Premultiplied, AlphaMode::Ignore] { - for curve in [FloatCurve::Srgb, FloatCurve::Linear, FloatCurve::Gamma24] { - let op = AlphaOp::of(&Footage { alpha, premul_color: [0.2, 0.4, 0.6], ..Default::default() }, curve); - let want = crate::convert::dynamic_to_image(&img, op); - let got = cached_picture(&path, bytes.as_slice().into(), &ReadFile::new(path.as_str(), effectcraft_render::reads::FileStamp::Virtual), op) - .unwrap(); - assert_eq!((got.width, got.height), (want.width, want.height)); - assert_eq!(bits(&got), bits(&want), "file {k} {alpha:?} {curve:?}"); - } - } - } + assert!(pool.aux(effectcraft_project::ItemId(1), &f, effectcraft_time::Tick::ZERO).is_none()); } /// #2141: one pixel of data in a 60000² display window is refused, not allocated per channel. diff --git a/crates/media/src/exr_index.rs b/crates/media/src/exr_index.rs new file mode 100644 index 000000000..34facf7df --- /dev/null +++ b/crates/media/src/exr_index.rs @@ -0,0 +1,371 @@ +//! [`ExrIndex`]: what an OpenEXR file holds, read from its headers and offset tables only +//! (#3271): the parts, every channel by its plane name, where each chunk lies and which rows it +//! holds, the Cryptomatte manifests and the channels its picture is made of. +//! +//! An index is a few kilobytes and is kept per file ([`get`]): the channel popups, +//! `layer.channels`, the Cryptomatte layer lists, import and the planning of a read use it +//! and never decode pixels. The reader ([`crate::exr_read`]) fetches the chunks it lists. +//! +//! Everything is validated before anything is sized by it: the display window +//! ([`crate::exr_channels::MAX_DISPLAY_PIXELS`]), the chunk count (eight bytes of offset table +//! each, so never more than the file can hold), and every offset (inside the chunk area; a chunk +//! with a bad offset is never read). + +use std::collections::{HashMap, VecDeque}; +use std::io::{Read, Seek, SeekFrom}; +use std::sync::{Arc, Mutex, PoisonError}; + +use effectcraft_raster::AuxChannels; +use effectcraft_raster::channels3d::BACKGROUND_DEPTH; +use effectcraft_render::reads::FileStamp; +use exr::meta::MetaData; +use exr::meta::attribute::{AttributeValue, IntegerBounds, Text}; + +use crate::exr_channels::{MAX_DISPLAY_PIXELS, Rgb, channel_name, is_depth, parse_manifest, part_name, picture_names}; +use crate::exr_read::{ExrSource, ReadSeek}; + +/// One channel of the file, in file order (parts in order, each part's channels as its header +/// lists them): the order of [`AuxChannels::channels`] when every channel is read. +#[derive(Clone, Debug)] +pub(crate) struct IndexChannel { + /// The plane name (`part.channel`, see [`channel_name`]). + pub(crate) name: String, + /// Its part and its position in the part's channel list. + pub(crate) part: usize, + pub(crate) channel: usize, + /// The value outside the part's data window (the background depth for depth channels). + pub(crate) fill: f32, +} + +/// One chunk of a part, in offset-table order. +#[derive(Clone, Copy, Debug)] +pub(crate) struct IndexChunk { + /// Where it starts in the file, and how many bytes to read for it (0: its offset is not + /// valid, it is never read). + pub(crate) offset: u64, + pub(crate) len: u64, + /// Its first row in the part's data window and how many rows it holds. + pub(crate) y: i64, + pub(crate) rows: usize, + /// Of the full-resolution level (tiled files also store reduced levels). + pub(crate) largest: bool, +} + +/// One part of the file. +#[derive(Clone, Debug)] +pub(crate) struct IndexPart { + /// The part's data window position in the display window, and the data window's size. + pub(crate) offset: (i64, i64), + pub(crate) layer: (usize, usize), + pub(crate) chunks: Vec, +} + +/// What an OpenEXR file holds ([`get`]). +pub(crate) struct ExrIndex { + pub(crate) meta: MetaData, + /// The file's identity when indexed: a read of another identity indexes it again. + pub(crate) stamp: FileStamp, + /// The first part's display window: every plane covers it. + pub(crate) display: IntegerBounds, + pub(crate) parts: Vec, + pub(crate) channels: Vec, + /// How the `image` crate's decoder would show the file (indices into `channels`). + pub(crate) rgb: Rgb, + /// A file the decoder refuses ([`Rgb::None`]): the channels its picture is made of + /// ([`picture_names`]: red, green, blue and alpha by name) and every channel answering to + /// one of those names (lookups ignore case). + pub(crate) picture: Option<(Vec, [String; 3], Option)>, + /// The names only (planes empty), manifests and aliases: for the channel lists and for + /// resolving what effects declare. Never handed to an effect. + pub(crate) names: Arc, +} + +impl ExrIndex { + /// The display window's size. + pub(crate) fn size(&self) -> (usize, usize) { + (self.display.size.0, self.display.size.1) + } + + /// The channels the picture is made of: the image crate's choice ([`Rgb::Planes`]) or the + /// layered rule's. `None`: the planes can't make it (decode with the `image` crate). + pub(crate) fn picture_ids(&self) -> Option> { + match self.rgb { + Rgb::Planes([r, g, b], a) => Some([Some(r), Some(g), Some(b), a].into_iter().flatten().collect()), + Rgb::None => self.picture.as_ref().map(|(ids, _, _)| ids.clone()), + Rgb::Unsupported => None, + } + } + + /// The channels named `names` (exact plane names, each once, in file order). + pub(crate) fn ids_named<'a>(&self, names: impl IntoIterator) -> Vec { + let names: std::collections::HashSet<&str> = names.into_iter().collect(); + self.channels.iter().enumerate().filter(|(_, c)| names.contains(c.name.as_str())).map(|(i, _)| i).collect() + } +} + +/// Why a file has no index. +#[derive(Clone, Debug, PartialEq)] +pub(crate) enum IndexError { + /// Not an OpenEXR file this reader takes (decoders may still try the whole file). + Unreadable, + /// An OpenEXR file whose compression can't be decoded (the reason, to show). + Unsupported(&'static str), + /// The file can't be opened or read. + Io, +} + +/// Bytes counted as they are read (the offset tables start where the headers end). +struct Counted<'r> { + inner: &'r mut dyn ReadSeek, + read: u64, +} + +impl Read for Counted<'_> { + fn read(&mut self, buf: &mut [u8]) -> std::io::Result { + let n = self.inner.read(buf)?; + self.read = self.read.saturating_add(n as u64); + Ok(n) + } +} + +/// The headers of the file in `src` as the high-level reader takes them (headers read strictly, +/// then validated leniently: the files that opened before open now). +fn headers(src: &mut dyn ReadSeek) -> Result<(MetaData, u64), IndexError> { + let (strict, read) = { + let mut counted = Counted { inner: &mut *src, read: 0 }; + let strict = MetaData::read_from_buffered(&mut counted, true).and_then(|meta| MetaData::validate(&meta.headers, false).map(|_| meta)); + (strict, counted.read) + }; + match strict { + Ok(meta) => Ok((meta, read)), + Err(_) => { + // (an HTJ2K file fails here: say why) + src.seek(SeekFrom::Start(0)).map_err(|_| IndexError::Io)?; + match MetaData::read_from_buffered(&mut *src, false).ok().as_ref().and_then(unsupported) { + Some(why) => Err(IndexError::Unsupported(why)), + None => Err(IndexError::Unreadable), + } + } + } +} + +/// [`crate::exr_channels::unsupported_compression`] of parsed headers. +pub(crate) fn unsupported(meta: &MetaData) -> Option<&'static str> { + use exr::compression::Compression; + meta.headers + .iter() + .any(|h| matches!(h.compression, Compression::HTJ2K32 | Compression::HTJ2K256)) + .then_some("OpenEXR HTJ2K compression isn't supported yet: re-save the file with ZIP, PIZ or DWAA compression") +} + +/// Index the OpenEXR file in `src` (`len` bytes, identity `stamp`), reading its headers and +/// offset tables only. +pub(crate) fn build(src: &mut dyn ReadSeek, len: u64, stamp: FileStamp) -> Result { + src.seek(SeekFrom::Start(0)).map_err(|_| IndexError::Io)?; + let (meta, header_end) = headers(&mut *src)?; + if let Some(why) = unsupported(&meta) { + return Err(IndexError::Unsupported(why)); + } + let first = meta.headers.first().ok_or(IndexError::Unreadable)?; + // Deep data isn't read (the whole file was refused before). + if meta.headers.iter().any(|h| h.deep) { + return Err(IndexError::Unreadable); + } + let display = first.shared_attributes.display_window; + // Each plane covers the display window: a 60000² window over a 1×1 data window was a + // multi-gigabyte allocation per channel (#2141). + display.size.0.checked_mul(display.size.1).filter(|n| *n > 0 && *n <= MAX_DISPLAY_PIXELS).ok_or(IndexError::Unreadable)?; + // Eight bytes of offset table per chunk: a header can't claim more chunks than that. + let chunks: usize = meta.headers.iter().map(|h| h.chunk_count).fold(0, usize::saturating_add); + if (chunks as u64).saturating_mul(8) > len.saturating_sub(header_end) { + return Err(IndexError::Unreadable); + } + let tables = { + let mut counted = Counted { inner: &mut *src, read: 0 }; + let tables = MetaData::read_offset_tables(&mut exr::io::PeekRead::new(&mut counted), &meta.headers).map_err(|_| IndexError::Unreadable)?; + (tables, counted.read) + }; + let (tables, table_bytes) = tables; + let chunks_start = header_end.saturating_add(table_bytes); + // Where each chunk ends: at the next chunk's start, or at the end of the file. + let mut starts: Vec = tables.iter().flatten().copied().filter(|o| *o >= chunks_start && *o < len).collect(); + starts.sort_unstable(); + starts.dedup(); + let end_of = |offset: u64| match starts.binary_search(&offset) { + Ok(i) => starts.get(i + 1).copied().unwrap_or(len), + Err(_) => offset, + }; + let mut parts = Vec::with_capacity(meta.headers.len()); + for (pi, h) in meta.headers.iter().enumerate() { + let table = tables.get(pi).ok_or(IndexError::Unreadable)?; + // A chunk is at most its block's bytes plus its own small header (part number, position + // and sizes): never read more for one. + let most = (h.max_block_byte_size() as u64).saturating_add(64); + let mut list = Vec::with_capacity(h.chunk_count); + for (i, tile) in h.blocks_increasing_y_order().enumerate() { + let bounds = h.get_absolute_block_pixel_coordinates(tile.location).map_err(|_| IndexError::Unreadable)?; + let offset = table.get(i).copied().unwrap_or(0); + let valid = offset >= chunks_start && offset < len; + let bytes = if valid { end_of(offset).saturating_sub(offset).min(most) } else { 0 }; + list.push(IndexChunk { + offset, + len: bytes, + y: i64::from(bounds.position.1), + rows: bounds.size.1, + largest: tile.location.is_largest_resolution_level(), + }); + } + let pos = h.own_attributes.layer_position; + parts.push(IndexPart { + offset: (i64::from(pos.0) - i64::from(display.position.0), i64::from(pos.1) - i64::from(display.position.1)), + layer: (h.layer_size.0, h.layer_size.1), + chunks: list, + }); + } + let mut channels = vec![]; + let mut aliases = vec![]; + for (pi, h) in meta.headers.iter().enumerate() { + let prefix = part_name(h); + for (ci, ch) in h.channels.list.iter().enumerate() { + let stored = ch.name.to_string(); + let name = channel_name(prefix.as_deref(), &stored); + // A stored `layer.channel` name inside a part named otherwise is also found as stored + // (`Crypto_Material00.R` in part `Crypto_Material`); bare names (`R`) are not. + if prefix.is_some() && name != stored && stored.contains('.') { + aliases.push((stored, name.clone())); + } + let fill = if is_depth(&name) { BACKGROUND_DEPTH } else { 0.0 }; + channels.push(IndexChannel { name, part: pi, channel: ci, fill }); + } + } + let manifests = manifests(&meta); + let rgb = rgb_of(&meta, &channels); + let mut names = AuxChannels::new(display.size.0 as u32, display.size.1 as u32, 1.0); + names.channels = channels.iter().map(|c| (c.name.clone(), vec![])).collect(); + names.manifests = manifests; + names.aliases = aliases; + let picture = picture_names(&names).map(|(rgb, a)| { + // Planes are looked up by name ignoring case, so every channel that could answer is read. + let ids = channels + .iter() + .enumerate() + .filter(|(_, c)| rgb.iter().chain(&a).any(|k| k.eq_ignore_ascii_case(&c.name))) + .map(|(i, _)| i) + .collect(); + (ids, rgb, a) + }); + Ok(ExrIndex { meta, stamp, display, parts, channels, rgb, picture, names: Arc::new(names) }) +} + +/// The Cryptomatte manifests of the headers (`cryptomatte//name` and `…/manifest`), sorted. +fn manifests(meta: &MetaData) -> Vec<(String, Vec<(String, u32)>)> { + let mut crypto: HashMap, Option)> = HashMap::new(); + let mut collect = |other: &HashMap| { + for (k, v) in other { + let key = k.to_string(); + let Some(rest) = key.strip_prefix("cryptomatte/") else { continue }; + let Some((id, field)) = rest.split_once('/') else { continue }; + let AttributeValue::Text(t) = v else { continue }; + let e = crypto.entry(id.to_string()).or_default(); + match field { + "name" => e.0 = Some(t.to_string()), + "manifest" => e.1 = Some(t.to_string()), + _ => {} + } + } + }; + // (the image's attributes are the first part's shared ones, as the decoder reports them) + if let Some(first) = meta.headers.first() { + collect(&first.shared_attributes.other); + } + for h in meta.headers.iter() { + collect(&h.own_attributes.other); + } + let mut out: Vec<(String, Vec<(String, u32)>)> = + crypto.into_values().filter_map(|(name, manifest)| Some((name?, parse_manifest(&manifest?)))).collect(); + out.sort(); + out +} + +/// How the `image` crate's decoder would show the file: the first part with exact `R`, `G` and +/// `B` channels (alpha `A` when it has one), unless its planes can't stand in for it (a +/// depth-named channel, filled with the background depth outside the data window, or a part +/// with its own display window). +fn rgb_of(meta: &MetaData, channels: &[IndexChannel]) -> Rgb { + let Some(display) = meta.headers.first().map(|h| h.shared_attributes.display_window) else { return Rgb::None }; + for (pi, h) in meta.headers.iter().enumerate() { + let find = |c: &str| h.channels.find_index_of_channel(&Text::from(c)); + let (Some(r), Some(g), Some(b)) = (find("R"), find("G"), find("B")) else { continue }; + let id = |ci: usize| channels.iter().position(|c| c.part == pi && c.channel == ci); + let picked = [Some(r), Some(g), Some(b), find("A")]; + let ids: Vec> = picked.iter().map(|c| c.and_then(id)).collect(); + let (Some(Some(r)), Some(Some(g)), Some(Some(b))) = (ids.first(), ids.get(1), ids.get(2)) else { return Rgb::Unsupported }; + let a = ids.get(3).copied().flatten(); + let depth = [Some(*r), Some(*g), Some(*b), a].iter().flatten().any(|i| channels.get(*i).is_some_and(|c| is_depth(&c.name))); + if depth || h.shared_attributes.display_window != display { + return Rgb::Unsupported; + } + return Rgb::Planes([*r, *g, *b], a); + } + Rgb::None +} + +/// At most this many files are indexed (a few kilobytes each); the oldest goes first. +const INDEXED_FILES: usize = 4096; + +/// Indexed files by path. +struct Indexes { + map: HashMap>, + order: VecDeque, +} + +fn indexes() -> &'static Mutex { + static INDEXES: std::sync::OnceLock> = std::sync::OnceLock::new(); + INDEXES.get_or_init(|| Mutex::new(Indexes { map: HashMap::new(), order: VecDeque::new() })) +} + +fn lock() -> std::sync::MutexGuard<'static, Indexes> { + indexes().lock().unwrap_or_else(PoisonError::into_inner) +} + +/// Keep `index` as the index of `path`. +pub(crate) fn keep(path: &str, index: Arc) { + let mut ix = lock(); + if ix.map.insert(path.to_string(), index).is_none() { + ix.order.push_back(path.to_string()); + } + while ix.map.len() > INDEXED_FILES { + let Some(old) = ix.order.pop_front() else { break }; + ix.map.remove(&old); + } +} + +/// The index of the file at `path` (read from `source` the first time; kept until +/// [`forget`]). Header-only users take it as it is; a read checks the file's identity and +/// indexes it again when it changed. +pub(crate) fn get(path: &str, source: &ExrSource) -> Result, IndexError> { + if let Some(ix) = lock().map.get(path).cloned() { + return Ok(ix); + } + let mut opened = source.open().map_err(|e| { + log::debug!("media: {path}: {e}"); + IndexError::Io + })?; + let ix = Arc::new(build(&mut *opened.reader, opened.len, opened.stamp)?); + keep(path, ix.clone()); + Ok(ix) +} + +/// The index of `path` if it is kept. +#[cfg_attr(not(test), allow(dead_code))] +pub(crate) fn cached(path: &str) -> Option> { + lock().map.get(path).cloned() +} + +/// Drop the index of `path` (the file changed on disk). +pub(crate) fn forget(path: &str) { + let mut ix = lock(); + if ix.map.remove(path).is_some() { + ix.order.retain(|p| p != path); + } +} diff --git a/crates/media/src/exr_planes.rs b/crates/media/src/exr_planes.rs new file mode 100644 index 000000000..143ff2988 --- /dev/null +++ b/crates/media/src/exr_planes.rs @@ -0,0 +1,701 @@ +//! The plane store (#3271): decoded OpenEXR channel planes in RAM, one entry per (file, level), +//! shared by every consumer of a frame: the picture of a footage layer and the channels its +//! effects read (EXtractoR, Cryptomatte, the 3D Channel effects). It replaces the pool's own +//! OpenEXR decode and the separate channel cache of #474. +//! +//! - **Single flight.** One decode per entry at a time; requests for it wait instead of +//! decoding again. A request arriving before the decode has started reading adds its +//! channels to it; one arriving later waits, and if that decode doesn't cover it, the next +//! decode reads only the channels still missing. +//! - **Covered requests are served from the store**: an entry holds one set of planes (the +//! union of what was decoded, [`Batch`]), and any request for a subset gets it as it is. +//! - **Never on the wrong thread.** The decode runs on the footage decode threads +//! ([`crate::pool::decode_threads`]); a request on another thread hands it over and blocks +//! plainly. A thread running a decode never waits for another (rayon lets a thread waiting in +//! a parallel loop run other jobs, which could wait on that very decode): it decodes a copy. +//! - **Nothing made before a Reload is kept or served** ([`forget`]): a decode that started +//! before the file was forgotten keeps nothing, and the requests waiting for it ask again. +//! - Bounded by bytes ([`CACHE_BUDGET`]), least recently used out first; entries in use (planes +//! an effect holds, a decode in progress, the last pictures' planes kept for their effects, +//! [`HELD_FILES`]) are never dropped, and the newest stays even when it alone is over. + +use std::collections::{BTreeSet, VecDeque}; +use std::sync::{Arc, Condvar, Mutex, MutexGuard, PoisonError}; + +use effectcraft_raster::channels3d::AuxNeed; +use effectcraft_raster::{AuxChannels, Image}; +use effectcraft_render::reads::ReadFile; + +use crate::convert::AlphaOp; +use crate::exr_channels::{Rgb, planes_picture}; +use crate::exr_index::{self, ExrIndex, IndexError}; +use crate::exr_channels::CACHE_BUDGET; +use crate::exr_read::{ExrSource, ReadError, ReadRequest, read_planes}; + +/// At most this many entries are kept (unreadable files hold no bytes). +const CACHE_FILES: usize = 64; + +/// At most this many pictures' planes are kept for their effects (the renderer asks for a +/// frame's picture, then its channels): about as many frames as are rendered at once. +const HELD_FILES: usize = 4; + +/// How long a request waits for another's decode before it decodes a copy (a safety net for a +/// decode that hangs). +#[cfg(not(target_arch = "wasm32"))] +const WAIT_LIMIT: std::time::Duration = std::time::Duration::from_secs(10); + +/// How often a request asks again after a decode it waited for was called off or forgotten. +const RETRIES: u32 = 3; + +/// Decoded planes of a file: the union of the channels read so far. +pub(crate) struct Batch { + /// The index they were read with (channel ids are its). + pub(crate) index: Arc, + /// The channels held, in file order (parallel to `aux.channels`). + pub(crate) ids: Vec, + /// Every channel of the file. + pub(crate) all: bool, + pub(crate) aux: Arc, + /// The file as read. + pub(crate) file: ReadFile, +} + +impl Batch { + /// Bytes held (the planes; names and manifests are small). + fn bytes(&self) -> usize { + self.aux.channels.iter().map(|(n, p)| n.len() + std::mem::size_of_val(p.as_slice())).sum() + } + + /// The plane of channel `id`. + pub(crate) fn plane(&self, id: usize) -> Option<&[f32]> { + let at = self.ids.binary_search(&id).ok()?; + self.aux.channels.get(at).map(|(_, p)| p.as_slice()) + } + + /// It holds what `want` asks of the file `index` describes. + fn covers(&self, index: &Arc, want: &Want) -> bool { + Arc::ptr_eq(&self.index, index) && (self.all || (!want.all && want.ids.iter().all(|id| self.ids.binary_search(id).is_ok()))) + } +} + +/// The channels a request asks for. +#[derive(Clone, Debug, Default, PartialEq)] +pub(crate) struct Want { + /// Every channel. + pub(crate) all: bool, + pub(crate) ids: BTreeSet, +} + +impl Want { + fn add(&mut self, other: &Want) { + self.all |= other.all; + self.ids.extend(other.ids.iter().copied()); + } +} + +/// Who asks. +#[derive(Clone, Copy, Debug, PartialEq)] +pub(crate) enum Use { + /// The picture of a footage item whose effects read its channels next: kept for them. + Picture, + /// Anything else (the channels themselves, a picture alone). + Other, +} + +/// Why a request got no planes. +#[derive(Clone, Debug, PartialEq)] +pub(crate) enum Refused { + /// Not readable (remembered until the file is forgotten). + Unreadable, + /// More planes than one file may allocate (the reason; remembered). + TooLarge(String), + /// The request was called off. + Cancelled, + /// The file changed since it was indexed: index it again and ask again. + Changed, + /// The file was forgotten while it decoded: ask again. + Forgotten, +} + +/// A decode in progress: what it reads (until it starts reading) and its outcome. +struct Flight { + state: Mutex, + ready: Condvar, +} + +struct FlightState { + index: Arc, + want: Want, + /// Reading started: requests no longer add to `want`. + sealed: bool, + outcome: Option, Refused>>, +} + +impl Flight { + fn new(index: Arc, want: Want) -> Arc { + Arc::new(Flight { state: Mutex::new(FlightState { index, want, sealed: false, outcome: None }), ready: Condvar::new() }) + } + + fn state(&self) -> MutexGuard<'_, FlightState> { + self.state.lock().unwrap_or_else(PoisonError::into_inner) + } + + fn end(&self, outcome: Result, Refused>) { + self.state().outcome = Some(outcome); + self.ready.notify_all(); + } +} + +struct Entry { + path: String, + level: u32, + batch: Option>, + flight: Option>, + failed: Option, + bytes: usize, + /// When it was last asked for or finished decoding (a counter). + used: u64, +} + +impl Entry { + /// Dropping it would free nothing or lose work in progress: a decode runs, or planes are held. + fn in_use(&self) -> bool { + self.flight.is_some() || self.batch.as_ref().is_some_and(|b| Arc::strong_count(b) > 1 || Arc::strong_count(&b.aux) > 1) + } +} + +struct State { + entries: Vec, + clock: u64, + /// Pictures' planes kept for their effects, oldest first (at most [`HELD_FILES`]). + held: VecDeque<(String, Arc)>, +} + +/// The request decoding an entry: it stores the outcome and ends the flight, also when the decode +/// panics (then with an error), so no request waits for planes that never come and the entry +/// doesn't stay "decoding". +struct Owning<'a> { + store: &'a PlaneStore, + path: &'a str, + level: u32, + flight: &'a Arc, + ended: bool, +} + +impl Owning<'_> { + fn end(&mut self, outcome: Result, Refused>) -> Result, Refused> { + self.ended = true; + let outcome = self.store.finish(self.path, self.level, self.flight, outcome); + self.flight.end(outcome.clone()); + outcome + } +} + +impl Drop for Owning<'_> { + fn drop(&mut self) { + if !self.ended { + let _ = self.end(Err(Refused::Unreadable)); + } + } +} + +/// Decoded planes by (file, level), bounded by bytes. +pub(crate) struct PlaneStore { + state: Mutex, + budget: usize, +} + +thread_local! { + /// Store decodes running on this thread: such a thread doesn't wait for another decode. + static DECODING: std::cell::Cell = const { std::cell::Cell::new(0) }; +} + +/// Marks a store decode on this thread ([`DECODING`]) until dropped (also when it panics). +struct Decoding; + +impl Decoding { + fn new() -> Decoding { + DECODING.with(|n| n.set(n.get().saturating_add(1))); + Decoding + } +} + +impl Drop for Decoding { + fn drop(&mut self) { + DECODING.with(|n| n.set(n.get().saturating_sub(1))); + } +} + +/// What waiting for another request's decode ended with. +#[cfg_attr(target_arch = "wasm32", allow(dead_code))] +enum Waited { + Got(Result, Refused>), + /// This request was called off meanwhile. + Cancelled, + /// This thread may not wait, or waited too long: decode a copy. + No, +} + +/// One decode the store ran (tests and measurements): the channels read and what it cost. +#[cfg(test)] +#[derive(Clone, Debug)] +pub(crate) struct DecodeRecord { + pub(crate) channels: Vec, + pub(crate) stats: crate::exr_read::ReadStats, +} + +#[cfg(test)] +static DECODES: Mutex> = Mutex::new(Vec::new()); + +/// The decodes of `path` so far (tests; paths are unique per test). +#[cfg(test)] +pub(crate) fn decodes_of(path: &str) -> Vec { + DECODES.lock().unwrap_or_else(PoisonError::into_inner).iter().filter(|(p, _)| p == path).map(|(_, d)| d.clone()).collect() +} + +/// Runs before a decode reads its chunks, with the file's path (tests). +#[cfg(test)] +type Hook = Arc; +#[cfg(test)] +static BEFORE_READ: Mutex> = Mutex::new(None); + +#[cfg(test)] +pub(crate) fn set_before_read(hook: Option) { + *BEFORE_READ.lock().unwrap_or_else(PoisonError::into_inner) = hook; +} + +impl PlaneStore { + pub(crate) const fn new(budget: usize) -> PlaneStore { + PlaneStore { state: Mutex::new(State { entries: Vec::new(), clock: 0, held: VecDeque::new() }), budget } + } + + fn lock(&self) -> MutexGuard<'_, State> { + self.state.lock().unwrap_or_else(PoisonError::into_inner) + } + + /// The planes of `want` of the file at `path` (`index`, read from `source`): from the store, + /// from a decode in progress, or decoded now (only what the store doesn't hold yet). The + /// file it was read from is noted ([`crate::reads`]). + pub(crate) fn get(&self, path: &str, source: &ExrSource, index: &Arc, want: &Want, by: Use) -> Result, Refused> { + let level = 0; + let mut retries = 0; + loop { + let mut st = self.lock(); + st.clock += 1; + let clock = st.clock; + let at = match st.entries.iter().position(|e| e.path == path && e.level == level) { + Some(i) => i, + None => { + st.entries.push(Entry { path: path.to_string(), level, batch: None, flight: None, failed: None, bytes: 0, used: clock }); + st.entries.len() - 1 + } + }; + let Some(e) = st.entries.get_mut(at) else { return Err(Refused::Unreadable) }; + e.used = clock; + if let Some(f) = &e.failed { + return Err(f.clone()); + } + if let Some(b) = e.batch.clone().filter(|b| b.covers(index, want)) { + Self::hold(&mut st, path, &b, by); + drop(st); + crate::reads::note(b.file.clone()); + return Ok(b); + } + if let Some(flight) = e.flight.clone() { + { + let mut fs = flight.state(); + if !fs.sealed && Arc::ptr_eq(&fs.index, index) { + fs.want.add(want); + } + } + drop(st); + match self.wait(&flight) { + Waited::Got(Ok(b)) if b.covers(index, want) => { + crate::reads::note(b.file.clone()); + return Ok(b); + } + // Not all it asks for: ask again (the next decode reads what is missing). + Waited::Got(Ok(_)) => {} + Waited::Got(Err(Refused::Cancelled | Refused::Forgotten)) if retries < RETRIES => retries += 1, + Waited::Got(Err(e)) => return Err(e), + Waited::Cancelled => return Err(Refused::Cancelled), + // A copy, kept nowhere. + Waited::No => return run(path, source, &Flight::new(index.clone(), want.clone()), None), + } + continue; + } + // This request decodes: what it asks for, minus what the store holds. + let base = e.batch.clone().filter(|b| Arc::ptr_eq(&b.index, index)); + let flight = Flight::new(index.clone(), want.clone()); + e.flight = Some(flight.clone()); + drop(st); + #[cfg(test)] + crate::exr_channels::count_decode(true); + let mut owning = Owning { store: self, path, level, flight: &flight, ended: false }; + let outcome = run(path, source, &flight, base); + let outcome = owning.end(outcome); + match outcome { + Ok(b) if b.covers(index, want) => { + let mut st = self.lock(); + Self::hold(&mut st, path, &b, by); + drop(st); + crate::reads::note(b.file.clone()); + return Ok(b); + } + Ok(_) | Err(Refused::Forgotten) if retries < RETRIES => retries += 1, + Ok(_) | Err(Refused::Forgotten) => return Err(Refused::Cancelled), + Err(e) => return Err(e), + } + } + } + + /// Keep `b` for the effects of the picture asking (`Use::Picture`), or stop keeping the + /// file's planes once its channels are asked for. + fn hold(st: &mut State, path: &str, b: &Arc, by: Use) { + match by { + Use::Picture => { + if !st.held.iter().any(|(p, _)| p == path) { + st.held.push_back((path.to_string(), b.clone())); + if st.held.len() > HELD_FILES { + st.held.pop_front(); + } + } + } + Use::Other => st.held.retain(|(p, _)| p != path), + } + } + + /// Store the outcome of `flight`'s decode in its entry, unless the file was forgotten + /// meanwhile (then nothing made of it is kept or handed out); drop what doesn't fit. + fn finish(&self, path: &str, level: u32, flight: &Arc, outcome: Result, Refused>) -> Result, Refused> { + let mut st = self.lock(); + st.clock += 1; + let clock = st.clock; + let Some(e) = st.entries.iter_mut().find(|e| e.path == path && e.level == level && e.flight.as_ref().is_some_and(|f| Arc::ptr_eq(f, flight))) else { + return match outcome { + Err(Refused::Cancelled) => Err(Refused::Cancelled), + _ => Err(Refused::Forgotten), + }; + }; + e.flight = None; + e.used = clock; + match &outcome { + Ok(b) => { + e.bytes = b.bytes(); + e.batch = Some(b.clone()); + } + Err(Refused::Unreadable) => e.failed = Some(Refused::Unreadable), + Err(Refused::TooLarge(why)) => e.failed = Some(Refused::TooLarge(why.clone())), + // (the file changed: what is held is of the old one) + Err(Refused::Changed) => { + e.batch = None; + e.bytes = 0; + } + Err(Refused::Cancelled | Refused::Forgotten) => {} + } + Self::evict(&mut st, self.budget, path, level); + outcome + } + + /// Drop least recently used entries not in use until the rest fit the budget, keeping the + /// newest (`path` at `level`, just decoded) and the pictures' planes held for their effects. + fn evict(st: &mut State, budget: usize, path: &str, level: u32) { + loop { + if st.entries.iter().map(|e| e.bytes).fold(0usize, usize::saturating_add) <= budget && st.entries.len() <= CACHE_FILES { + break; + } + let held = &st.held; + let oldest = st + .entries + .iter() + .enumerate() + .filter(|(_, e)| !(e.path == path && e.level == level) && !e.in_use()) + .filter(|(_, e)| !e.batch.as_ref().is_some_and(|b| held.iter().any(|(_, h)| Arc::ptr_eq(h, b)))) + .min_by_key(|(_, e)| e.used) + .map(|(i, _)| i); + let Some(i) = oldest else { break }; + st.entries.remove(i); + } + } + + /// Wait for the outcome of another request's decode (`flight`). A thread running a store + /// decode doesn't wait (see the module notes); the time limit is a safety net. + #[cfg(not(target_arch = "wasm32"))] + fn wait(&self, flight: &Flight) -> Waited { + if DECODING.with(std::cell::Cell::get) > 0 { + return Waited::No; + } + let until = std::time::Instant::now() + WAIT_LIMIT; + let mut fs = flight.state(); + loop { + if let Some(o) = fs.outcome.as_ref() { + return Waited::Got(o.clone()); + } + if filmcraft_media::cancel::cancelled() { + return Waited::Cancelled; + } + let left = until.saturating_duration_since(std::time::Instant::now()); + if left.is_zero() { + log::warn!("media: OpenEXR planes took over {} s to decode on another thread; decoding a copy", WAIT_LIMIT.as_secs()); + return Waited::No; + } + fs = match flight.ready.wait_timeout(fs, left.min(std::time::Duration::from_millis(20))) { + Ok((g, _)) => g, + Err(p) => p.into_inner().0, + }; + } + } + + /// (A wasm32 build has one thread: a decode in flight is further down this thread's stack.) + #[cfg(target_arch = "wasm32")] + fn wait(&self, _flight: &Flight) -> Waited { + Waited::No + } + + /// Drop the planes of `path` (the file changed on disk); a decode of it in progress keeps + /// nothing. + pub(crate) fn forget(&self, path: &str) { + let mut st = self.lock(); + st.entries.retain(|e| e.path != path); + st.held.retain(|(p, _)| p != path); + } + + /// Stop keeping the last pictures' planes for their effects. + pub(crate) fn release_held(&self) { + self.lock().held.clear(); + } + + #[cfg(test)] + pub(crate) fn cached(&self) -> Vec { + self.lock().entries.iter().filter(|e| e.batch.is_some() || e.failed.is_some()).map(|e| e.path.clone()).collect() + } + + #[cfg(test)] + pub(crate) fn is_held(&self, path: &str) -> bool { + self.lock().held.iter().any(|(p, _)| p == path) + } +} + +/// Run `flight`'s decode on the footage decode threads (here when this is one of them, or +/// there are none) and block until it is done. +fn run(path: &str, source: &ExrSource, flight: &Arc, base: Option>) -> Result, Refused> { + #[cfg(not(target_arch = "wasm32"))] + if let Some(threads) = crate::pool::decode_threads() + && threads.current_thread_index().is_none() + { + let (tx, rx) = std::sync::mpsc::sync_channel(1); + let (path, source, flight) = (path.to_string(), source.clone(), flight.clone()); + // The request's cancel flag and decoding hints go with it. + let hints = filmcraft_media::cancel::Context::current(); + threads.spawn(move || { + let _ = tx.send(hints.run(|| decode(&path, &source, &flight, base))); + }); + // A plain block: this thread runs nothing else meanwhile. + return rx.recv().unwrap_or(Err(Refused::Unreadable)); + } + decode(path, source, flight, base) +} + +/// Decode what `flight` asks for and `base` doesn't hold, and make the union of both. +fn decode(path: &str, source: &ExrSource, flight: &Arc, base: Option>) -> Result, Refused> { + let _decoding = Decoding::new(); + let mut opened = source.open().map_err(|e| { + log::warn!("media: {path}: {e}"); + Refused::Unreadable + })?; + let index = flight.state().index.clone(); + if opened.stamp != index.stamp { + // The file changed since it was indexed. + let fresh = exr_index::build(&mut *opened.reader, opened.len, opened.stamp).map_err(|_| Refused::Unreadable)?; + exr_index::keep(path, Arc::new(fresh)); + return Err(Refused::Changed); + } + #[cfg(test)] + { + let hook = BEFORE_READ.lock().unwrap_or_else(PoisonError::into_inner).clone(); + if let Some(h) = hook { + h(path); + } + } + // From here on the request is fixed. + let want = { + let mut fs = flight.state(); + fs.sealed = true; + fs.want.clone() + }; + let wanted: Vec = if want.all { (0..index.channels.len()).collect() } else { want.ids.iter().copied().filter(|i| *i < index.channels.len()).collect() }; + let base = base.filter(|b| Arc::ptr_eq(&b.index, &index)); + let missing: Vec = wanted.iter().copied().filter(|id| !base.as_ref().is_some_and(|b| b.ids.binary_search(id).is_ok())).collect(); + let (planes, stats) = read_planes(&mut *opened.reader, &index, &ReadRequest::full(missing.clone())); + #[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() }, + )); + #[cfg(not(test))] + let _ = &stats; + let planes = planes.map_err(|e| match e { + ReadError::Cancelled => Refused::Cancelled, + ReadError::TooLarge(why) => { + log::warn!("media: {path}: {why}"); + Refused::TooLarge(why) + } + ReadError::Unreadable(why) => { + log::warn!("media: {path}: {why}"); + Refused::Unreadable + } + })?; + // The union, in file order: the planes held and the ones just read. + let mut new: Vec<(usize, Vec)> = missing.into_iter().zip(planes).collect(); + if let Some(b) = &base { + for (at, id) in b.ids.iter().enumerate() { + if let Some((_, p)) = b.aux.channels.get(at) { + new.push((*id, p.clone())); + } + } + } + new.sort_by_key(|(id, _)| *id); + new.dedup_by_key(|(id, _)| *id); + let all = new.len() == index.channels.len(); + let (w, h) = index.size(); + let mut aux = AuxChannels::new(w as u32, h as u32, 1.0); + aux.manifests = index.names.manifests.clone(); + aux.aliases = index.names.aliases.clone(); + if !all { + aux.listed = index.channels.iter().map(|c| c.name.clone()).collect(); + } + let ids: Vec = 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) })) +} + +fn store() -> &'static PlaneStore { + static STORE: PlaneStore = PlaneStore::new(CACHE_BUDGET); + &STORE +} + +/// Is `path` an OpenEXR file by name (the store reads those; other files, and files named so +/// that aren't OpenEXR, go the `image` crate's way). +pub(crate) fn is_exr(path: &str) -> bool { + path.to_ascii_lowercase().ends_with(".exr") +} + +/// The index of `path`, and the store's verdict on an unreadable one. +fn index_of(path: &str, source: &ExrSource) -> Result, IndexError> { + exr_index::get(path, source) +} + +/// The ids `need` reads of the file `index` describes (`None`: all). +fn need_ids(index: &ExrIndex, need: &AuxNeed) -> Option> { + let names = need.resolve(&index.names)?; + Some(index.ids_named(names.iter().map(String::as_str)).into_iter().collect()) +} + +/// The outcome of [`picture`]. +pub(crate) enum Picture { + Done(Result), + Cancelled, + /// Not for the planes (an `image` crate picture, or not an OpenEXR this reader takes): + /// decode the whole file with the `image` crate. + Legacy, +} + +/// The picture of the OpenEXR at `path` made of its planes: the channels the `image` crate's +/// decoder would show, or a multi-layer file's colour layer (see +/// [`crate::exr_channels::layered_image`]). With `extra` (an effect reads the footage's +/// channels) those channels are read in the same pass and kept for the effects. +pub(crate) fn picture(path: &str, source: &ExrSource, op: AlphaOp, extra: Option<&AuxNeed>) -> Picture { + for _ in 0..2 { + let index = match index_of(path, source) { + Ok(ix) => ix, + Err(IndexError::Unsupported(why)) => return Picture::Done(Err(why.to_string())), + Err(_) => return Picture::Legacy, + }; + let Some(ids) = index.picture_ids() else { return Picture::Legacy }; + let mut want = Want { all: false, ids: ids.into_iter().collect() }; + if let Some(need) = extra { + match need_ids(&index, need) { + Some(more) => want.ids.extend(more), + None => want.all = true, + } + } + let by = if extra.is_some() { Use::Picture } else { Use::Other }; + let batch = match store().get(path, source, &index, &want, by) { + Ok(b) => b, + Err(Refused::Changed) => continue, + Err(Refused::Cancelled | Refused::Forgotten) => return Picture::Cancelled, + Err(Refused::TooLarge(why)) => return Picture::Done(Err(why)), + Err(Refused::Unreadable) => return Picture::Legacy, + }; + let aux = &batch.aux; + let img = match index.rgb { + Rgb::Planes([r, g, b], a) => { + let a = match a { + Some(a) => batch.plane(a).map(Some), + None => Some(None), + }; + match (batch.plane(r), batch.plane(g), batch.plane(b), a) { + (Some(r), Some(g), Some(b), Some(a)) => planes_picture(aux, [r, g, b], a, op), + _ => None, + } + } + Rgb::None => index.picture.as_ref().and_then(|(_, rgb, a)| { + let a = match a { + Some(n) => Some(aux.get(n)?), + None => None, + }; + planes_picture(aux, [aux.get(&rgb[0])?, aux.get(&rgb[1])?, aux.get(&rgb[2])?], a, op) + }), + Rgb::Unsupported => None, + }; + return match img { + Some(img) => Picture::Done(Ok(img)), + None => Picture::Legacy, + }; + } + Picture::Legacy +} + +/// The channels `need` reads of the OpenEXR at `path` (all for [`AuxNeed::All`]), from the +/// store. `None` when it isn't a readable OpenEXR (or the request was called off). +pub(crate) fn aux(path: &str, source: &ExrSource, need: &AuxNeed) -> Option> { + for _ in 0..2 { + let index = index_of(path, source).ok()?; + let want = match need_ids(&index, need) { + Some(ids) => Want { all: false, ids }, + None => Want { all: true, ids: BTreeSet::new() }, + }; + match store().get(path, source, &index, &want, Use::Other) { + Ok(b) => return Some(b.aux.clone()), + Err(Refused::Changed) => continue, + Err(_) => return None, + } + } + None +} + +/// The channel names (planes empty), manifests and aliases of the OpenEXR at `path`, from its +/// headers alone. Never handed to an effect. +pub(crate) fn names(path: &str, source: &ExrSource) -> Option> { + index_of(path, source).ok().map(|ix| ix.names.clone()) +} + +/// Drop what is kept of `path`: its index and planes. +pub(crate) fn forget(path: &str) { + exr_index::forget(path); + store().forget(path); +} + +/// Stop keeping the last pictures' planes for their effects (which footage effects read changed). +pub(crate) fn release_held() { + store().release_held(); +} + +/// The store all footage shares (tests). +#[cfg(test)] +pub(crate) fn shared() -> &'static PlaneStore { + store() +} + +#[cfg(test)] +mod tests; diff --git a/crates/media/src/exr_planes/tests.rs b/crates/media/src/exr_planes/tests.rs new file mode 100644 index 000000000..350b48a62 --- /dev/null +++ b/crates/media/src/exr_planes/tests.rs @@ -0,0 +1,439 @@ +//! The OpenEXR index, reader and plane store (#3271) on synthetic files written here. + +use std::sync::atomic::{AtomicU64, Ordering}; + +use effectcraft_project::{Footage, ItemId}; +use effectcraft_raster::channels3d::{AuxLookup, AuxNeed}; +use effectcraft_render::reads::FileStamp; +use effectcraft_render::{FloatCurve, FootageSource}; +use effectcraft_time::Tick; +use exr::prelude::{AnyChannel, AnyChannels, Blocks, Compression, Encoding, FlatSamples, ImageAttributes, IntegerBounds, Layer, LayerAttributes, LineOrder, WritableImage, f16}; + +use super::*; +use crate::exr_read::ExrSource; + +/// A deterministic sample for pixel `i` of channel `c` (an `A` channel gets 0..=1). +fn value(i: usize, c: usize, alpha: bool) -> f32 { + if alpha { ((i * 3 + c) % 11) as f32 / 10.0 } else { ((i * 7 + c * 29) % 97) as f32 / 40.0 - 0.3 } +} + +/// A part named `name` (`None`: unnamed) of `channels` ((name, half)) over `size`, compressed +/// with `compression` in scan lines. +fn part(name: Option<&str>, channels: &[(&str, bool)], size: (usize, usize), compression: Compression) -> Layer> { + let n = size.0 * size.1; + let list: Vec> = channels + .iter() + .enumerate() + .map(|(c, (ch, half))| { + let alpha = ch.rsplit('.').next().is_some_and(|l| l == "A"); + let samples = if *half { + FlatSamples::F16((0..n).map(|i| f16::from_f32(value(i, c, alpha))).collect()) + } else { + FlatSamples::F32((0..n).map(|i| value(i, c, alpha)).collect()) + }; + AnyChannel::new(*ch, samples) + }) + .collect(); + let mut attrs = name.map_or_else(LayerAttributes::default, LayerAttributes::named); + if name == Some("Crypto_Material") { + attrs.other.insert(exr::prelude::Text::from("cryptomatte/abc1234/name"), exr::prelude::AttributeValue::Text(exr::prelude::Text::from("Crypto_Material"))); + attrs.other.insert( + exr::prelude::Text::from("cryptomatte/abc1234/manifest"), + exr::prelude::AttributeValue::Text(exr::prelude::Text::from(r#"{"bunny":"13851a76"}"#)), + ); + } + let encoding = Encoding { compression, blocks: Blocks::ScanLines, line_order: LineOrder::Increasing }; + Layer::new(size, attrs, encoding, AnyChannels::sort(list.into())) +} + +/// The bytes of a file of `parts` over a display window of `size`. +fn write(parts: Vec>>, size: (usize, usize)) -> Vec { + let image = exr::prelude::Image::from_layers(ImageAttributes::new(IntegerBounds::from_dimensions(size)), parts); + let mut bytes = std::io::Cursor::new(Vec::new()); + image.write().non_parallel().to_buffered(&mut bytes).unwrap(); + bytes.into_inner() +} + +const SIZE: (usize, usize) = (64, 64); +const RGBA: [(&str, bool); 4] = [("R", true), ("G", true), ("B", true), ("A", true)]; +const CRYPTO: [(&str, bool); 4] = [("Crypto_Material00.R", false), ("Crypto_Material00.G", false), ("Crypto_Material00.B", false), ("Crypto_Material00.A", false)]; + +/// A multi-part file as renderers write one part per pass: the beauty, a Cryptomatte layer whose +/// channels keep their full names, and depth; one scan line per chunk. +fn multipart() -> Vec { + write( + vec![ + part(Some("beauty"), &RGBA, SIZE, Compression::ZIP1), + part(Some("Crypto_Material"), &CRYPTO, SIZE, Compression::ZIP1), + part(Some("depth"), &[("Z", false)], SIZE, Compression::ZIP1), + ], + SIZE, + ) +} + +/// A single-part ZIPS file with a picture and many passes: every chunk holds every channel. +fn single_part_zips() -> Vec { + let mut list: Vec<(String, bool)> = RGBA.iter().map(|(n, h)| (n.to_string(), *h)).collect(); + for pass in ["diffuse", "specular", "normal", "emit"] { + list.extend(["R", "G", "B"].map(|c| (format!("{pass}.{c}"), true))); + } + list.extend(["R", "G", "B", "A"].map(|c| (format!("CryptoObject00.{c}"), false))); + let names: Vec<(&str, bool)> = list.iter().map(|(n, h)| (n.as_str(), *h)).collect(); + write(vec![part(None, &names, SIZE, Compression::ZIP1)], SIZE) +} + +/// `bytes` written to a temporary file named after `name` (removed by [`Temp`]). +struct Temp(std::path::PathBuf); + +impl Temp { + fn new(name: &str, bytes: &[u8]) -> Temp { + let path = std::env::temp_dir().join(format!("ec-3271-{}-{name}.exr", std::process::id())); + std::fs::write(&path, bytes).unwrap(); + Temp(path) + } + fn path(&self) -> String { + self.0.to_string_lossy().to_string() + } +} + +impl Drop for Temp { + fn drop(&mut self) { + let _ = std::fs::remove_file(&self.0); + } +} + +fn bits(img: &Image) -> Vec { + img.data.iter().flat_map(|p| p.map(f32::to_bits)).collect() +} + +/// The picture the `image` crate's decoder shows of `bytes`, converted as the pool converts it. +fn image_crates(bytes: &[u8], f: &Footage) -> Image { + let img = crate::probe::load_oriented(bytes, Some(image::ImageFormat::OpenExr)).unwrap(); + crate::convert::dynamic_to_image(&img, AlphaOp::of(f, FloatCurve::Srgb)) +} + +/// The chunks a decode fetched in all. +fn chunks(r: &DecodeRecord) -> usize { + r.stats.chunks.iter().sum() +} + +/// #3271: the picture of a multi-part file reads the beauty part's chunks and nothing else, +/// converts only its channels, and is the `image` crate's picture bit for bit. +#[test] +fn a_picture_reads_only_its_part() { + let bytes = multipart(); + let file = Temp::new("picture-part", &bytes); + let path = file.path(); + let f = crate::probe(&file.0).unwrap(); + let pool = crate::MediaPool::new(); + let img = pool.frame_at(&f, Tick::ZERO).unwrap(); + assert_eq!(bits(&img), bits(&image_crates(&bytes, &f)), "the image crate's picture"); + let d = decodes_of(&path); + assert_eq!(d.len(), 1, "{d:?}"); + assert_eq!(d[0].channels, ["beauty.A", "beauty.B", "beauty.G", "beauty.R"]); + assert_eq!(d[0].stats.chunks, [SIZE.1, 0, 0], "only the beauty part's chunks"); + assert!(d[0].stats.bytes * 2 < bytes.len() as u64, "{} of {} bytes", d[0].stats.bytes, bytes.len()); +} + +/// #3271: EXtractoR reading 3 channels of a multi-part file reads only their part and converts +/// only those channels; the stored names find them (`Crypto_Material00.R` in part +/// `Crypto_Material`), and the manifest and layer resolve as the file names them. +#[test] +fn three_aux_channels_read_only_their_part() { + let bytes = multipart(); + let file = Temp::new("aux-part", &bytes); + let path = file.path(); + let f = crate::probe(&file.0).unwrap(); + let pool = crate::MediaPool::new(); + let need = AuxNeed::Lookups(["Crypto_Material00.R", "Crypto_Material00.G", "Crypto_Material00.B"].map(|n| AuxLookup::Name(n.into())).to_vec()); + let aux = pool.aux_for(ItemId(1), &f, Tick::ZERO, &need).unwrap(); + let d = decodes_of(&path); + assert_eq!(d.len(), 1); + assert_eq!(d[0].channels.len(), 3, "{:?}", d[0].channels); + assert_eq!(d[0].stats.chunks, [0, SIZE.1, 0], "only the Cryptomatte part's chunks"); + let r = aux.get("Crypto_Material00.R").unwrap(); + assert_eq!(r.len(), SIZE.0 * SIZE.1); + assert_eq!(r.get(5).copied(), Some(value(5, 0, false))); + assert!(aux.get("Crypto_Material00.A").is_none(), "not read"); + assert!(aux.listed.iter().any(|n| n == "depth.Z"), "every name listed"); +} + +/// #3271: lookups by the name a multi-part file stores a channel under work on all channels too +/// (EXtractoR's `Crypto_Material00.R`, Cryptomatte's Layer Name `Crypto_Material`), while the +/// channel list keeps showing `Crypto_Material.Crypto_Material00.R`. +#[test] +fn multipart_channels_are_found_by_their_stored_names() { + let bytes = multipart(); + let path = "/3271-stored-names.exr"; + let pool = crate::MediaPool::new(); + pool.add_bytes(path, bytes.as_slice().into()); + let f = crate::probe_bytes(path, bytes.as_slice().into()).unwrap(); + let aux = pool.aux(ItemId(1), &f, Tick::ZERO).unwrap(); + assert!(aux.names().contains(&"Crypto_Material.Crypto_Material00.R"), "{:?}", aux.names()); + assert!(aux.get("Crypto_Material00.R").is_some()); + let layer = effectcraft_raster::channels3d::crypto_layer_named(&aux, "Crypto_Material", 0).unwrap(); + assert_eq!(layer, "Crypto_Material.Crypto_Material"); + assert_eq!(aux.crypto_rank_planes(&layer).len(), 2); + assert_eq!(aux.manifest(&layer).map(<[_]>::len), Some(1)); + // The names alone, from the headers. + let names = pool.aux_names(ItemId(1), &f, Tick::ZERO).unwrap(); + assert_eq!(names.names(), aux.names()); + assert!(names.channels.iter().all(|(_, p)| p.is_empty()), "no pixels decoded"); +} + +/// #3271: footage whose effects read 3 channels decodes its picture with them in one pass: one +/// read of the file's chunks, one decode, for the picture and the effect. +#[test] +fn picture_and_aux_share_one_read_and_one_decode() { + let bytes = single_part_zips(); + let file = Temp::new("one-decode", &bytes); + let path = file.path(); + let f = crate::probe(&file.0).unwrap(); + let pool = crate::MediaPool::new(); + let need = AuxNeed::Lookups(vec![AuxLookup::Name("normal.R".into()), AuxLookup::Crypto { name: String::new(), index: 0 }]); + pool.set_aux_footage(std::slice::from_ref(&f.path)); + pool.set_aux_needs(&[(f.path.clone(), need.clone())]); + let img = pool.frame_at(&f, Tick::ZERO).unwrap(); + let aux = pool.aux_for(ItemId(1), &f, Tick::ZERO, &need).unwrap(); + let d = decodes_of(&path); + assert_eq!(d.len(), 1, "one decode: {d:?}"); + assert_eq!(chunks(&d[0]), SIZE.1, "each chunk read once"); + assert_eq!(d[0].channels.len(), 4 + 1 + 4, "the picture's, normal.R and the rank planes: {:?}", d[0].channels); + assert!(aux.get("normal.R").is_some() && aux.crypto_rank_planes("CryptoObject").len() == 2); + assert_eq!(bits(&img), bits(&image_crates(&bytes, &f))); +} + +/// The index and an in-memory source of `bytes`. +fn indexed(bytes: &[u8]) -> (Arc, std::io::Cursor>) { + let mut src = std::io::Cursor::new(bytes.to_vec()); + let ix = crate::exr_index::build(&mut src, bytes.len() as u64, FileStamp::Virtual).unwrap(); + (Arc::new(ix), src) +} + +/// #3271: a row range decompresses only the chunks holding those rows: with one scan line per +/// chunk (ZIPS) exactly those lines, with 16 (ZIP) the chunks around them; a reduced level +/// skips every other line on ZIPS. The rows read are the full read's, the rest is fill. +#[test] +fn rows_and_levels_skip_lines() { + for (compression, lines) in [(Compression::ZIP1, 10), (Compression::ZIP16, 32)] { + let bytes = write(vec![part(None, &RGBA, (32, 64), compression)], (32, 64)); + let (ix, mut src) = indexed(&bytes); + let all = ReadRequest::full(vec![0, 1, 2, 3]); + let (full, full_stats) = crate::exr_read::read_planes(&mut src, &ix, &all); + let full = full.unwrap(); + assert_eq!(full_stats.lines, 64); + let band = ReadRequest { rows: Some(10..20), ..all.clone() }; + let (got, stats) = crate::exr_read::read_planes(&mut src, &ix, &band); + let got = got.unwrap(); + assert_eq!(stats.lines, lines, "{compression:?}"); + for (g, f) in got.iter().zip(&full) { + for y in 0..64 { + let row = |p: &Vec| p[y * 32..(y + 1) * 32].to_vec(); + if (10..20).contains(&y) { + assert_eq!(row(g), row(f), "row {y}"); + } else { + assert!(row(g).iter().all(|v| *v == 0.0), "row {y} not read"); + } + } + } + } + // Half resolution on ZIPS: half the lines, every other row and column of the full read. + let bytes = write(vec![part(None, &RGBA, (32, 64), Compression::ZIP1)], (32, 64)); + let (ix, mut src) = indexed(&bytes); + let (full, _) = crate::exr_read::read_planes(&mut src, &ix, &ReadRequest::full(vec![3])); + let (half, stats) = crate::exr_read::read_planes(&mut src, &ix, &ReadRequest { level: 1, ..ReadRequest::full(vec![3]) }); + let (full, half) = (full.unwrap(), half.unwrap()); + assert_eq!(stats.lines, 32); + assert_eq!(crate::exr_read::level_size((32, 64), 1), (16, 32)); + for y in 0..32 { + for x in 0..16 { + assert_eq!(half[0][y * 16 + x].to_bits(), full[0][y * 2 * 32 + x * 2].to_bits(), "({x}, {y})"); + } + } +} + +/// #474: requests for a file at the same time decode it once; the others wait for that decode +/// and share its planes. +#[test] +fn concurrent_requests_decode_a_file_once() { + let bytes: Arc<[u8]> = single_part_zips().into(); + let path = "/3271-concurrent.exr"; + let source = ExrSource::Bytes(bytes.clone()); + let store = PlaneStore::new(CACHE_BUDGET); + let index = crate::exr_index::get(path, &source).unwrap(); + let barrier = std::sync::Barrier::new(8); + let got: Vec> = std::thread::scope(|s| { + let jobs: Vec<_> = (0..8) + .map(|_| { + s.spawn(|| { + barrier.wait(); + store.get(path, &source, &index, &Want { all: true, ids: Default::default() }, Use::Other).unwrap() + }) + }) + .collect(); + jobs.into_iter().map(|j| j.join().unwrap()).collect() + }); + assert!(got.iter().all(|b| Arc::ptr_eq(b, &got[0])), "every caller has the same planes"); + assert_eq!(decodes_of(path).len(), 1, "one decode"); +} + +/// #3271: a request for channels a decode in progress doesn't read waits for it, then decodes +/// only what is still missing; the planes it gets hold both. +#[test] +fn a_request_not_covered_decodes_only_what_is_missing() { + let bytes: Arc<[u8]> = single_part_zips().into(); + let path = "/3271-follow-up.exr"; + let source = ExrSource::Bytes(bytes); + let store = PlaneStore::new(CACHE_BUDGET); + let index = crate::exr_index::get(path, &source).unwrap(); + let picture: BTreeSet = index.picture_ids().unwrap().into_iter().collect(); + let normal: BTreeSet = index.ids_named(["normal.R", "normal.G"]).into_iter().collect(); + store.get(path, &source, &index, &Want { all: false, ids: picture.clone() }, Use::Other).unwrap(); + let b = store.get(path, &source, &index, &Want { all: false, ids: normal.clone() }, Use::Other).unwrap(); + let d = decodes_of(path); + assert_eq!(d.len(), 2); + assert_eq!(d[1].channels, ["normal.G", "normal.R"], "only the missing channels"); + assert!(picture.iter().chain(&normal).all(|id| b.plane(*id).is_some()), "both"); + // Covered now: no decode. + store.get(path, &source, &index, &Want { all: false, ids: picture }, Use::Other).unwrap(); + assert_eq!(decodes_of(path).len(), 2); +} + +/// #474: the store is bounded by bytes, least recently used out first; the newest file stays +/// even when it alone is over the budget, and unreadable files are remembered without bytes +/// (not read again) until forgotten. +#[test] +fn the_store_evicts_least_recently_used_by_bytes() { + let bytes: Arc<[u8]> = write(vec![part(None, &RGBA, (32, 32), Compression::ZIP1)], (32, 32)).into(); + let one = 4 * (32 * 32 * 4 + 1); + let store = PlaneStore::new(2 * one); + let all = Want { all: true, ids: Default::default() }; + let get = |p: &str| { + let source = ExrSource::Bytes(bytes.clone()); + let index = crate::exr_index::get(p, &source).unwrap(); + store.get(p, &source, &index, &all, Use::Other).map(|_| ()) + }; + get("/3271-evict-a.exr").unwrap(); + get("/3271-evict-b.exr").unwrap(); + get("/3271-evict-a.exr").unwrap(); // a is now more recent than b + get("/3271-evict-c.exr").unwrap(); + assert_eq!(store.cached(), ["/3271-evict-a.exr", "/3271-evict-c.exr"], "b was least recently used"); + let small = PlaneStore::new(one / 2); + for p in ["/3271-evict-big.exr", "/3271-evict-big2.exr"] { + let source = ExrSource::Bytes(bytes.clone()); + let index = crate::exr_index::get(p, &source).unwrap(); + assert!(small.get(p, &source, &index, &all, Use::Other).is_ok()); + assert_eq!(small.cached(), [p], "the newest stays"); + } + // An unreadable file (its chunk table points past the end): remembered, not read again. + let mut broken = bytes.to_vec(); + broken.truncate(broken.len() - 64); + let source = ExrSource::Bytes(broken.into()); + let path = "/3271-evict-broken.exr"; + let index = crate::exr_index::get(path, &source).unwrap(); + assert!(store.get(path, &source, &index, &all, Use::Other).is_err()); + assert!(store.get(path, &source, &index, &all, Use::Other).is_err()); + assert_eq!(decodes_of(path).len(), 1, "not read again"); + store.forget(path); + assert!(!store.cached().contains(&path.to_string())); +} + +/// #474 / #3191: a file forgotten (Reload Footage) while it decodes keeps nothing of that decode, +/// and the request asks again: no planes made before the reload are kept or served. +#[test] +fn a_file_forgotten_while_it_decodes_is_not_kept() { + let bytes: Arc<[u8]> = write(vec![part(None, &RGBA, (8, 8), Compression::ZIP1)], (8, 8)).into(); + let path = "/3271-forgotten.exr"; + let source = ExrSource::Bytes(bytes); + let store = Arc::new(PlaneStore::new(CACHE_BUDGET)); + let index = crate::exr_index::get(path, &source).unwrap(); + let forgot = Arc::new(AtomicU64::new(0)); + { + let (store, forgot) = (store.clone(), forgot.clone()); + set_before_read(Some(Arc::new(move |p: &str| { + if p == "/3271-forgotten.exr" && forgot.fetch_add(1, Ordering::SeqCst) == 0 { + store.forget(p); + } + }))); + } + let got = store.get(path, &source, &index, &Want { all: true, ids: Default::default() }, Use::Other); + set_before_read(None); + assert!(got.is_ok()); + assert_eq!(decodes_of(path).len(), 2, "decoded again after the reload"); + assert_eq!(store.cached(), [path], "only the second decode is kept"); +} + +/// #474: the planes of a picture whose effects read the footage's channels are kept for them +/// (the renderer asks for the picture, then the channels) until the channels are asked for. +#[test] +fn a_pictures_planes_are_held_for_its_effects() { + let bytes: Arc<[u8]> = single_part_zips().into(); + let path = "/3271-held.exr"; + let source = ExrSource::Bytes(bytes); + let store = PlaneStore::new(1); + let index = crate::exr_index::get(path, &source).unwrap(); + let all = Want { all: true, ids: Default::default() }; + drop(store.get(path, &source, &index, &all, Use::Picture).unwrap()); + assert!(store.is_held(path)); + drop(store.get(path, &source, &index, &all, Use::Other).unwrap()); + assert!(!store.is_held(path), "the channels were asked for"); + assert_eq!(decodes_of(path).len(), 1); +} + +/// #474: footage the project says effects read the channels of decodes once from its first frame +/// (the picture with the channels). Learned only when `aux()` first asks, the picture was read +/// alone before, and the channels then read only what it didn't. +#[test] +fn given_aux_footage_decodes_once_from_the_first_frame() { + use crate::exr_channels::take_decodes; + let bytes: Arc<[u8]> = single_part_zips().into(); + let (given, learned) = ("/3271-given.exr", "/3271-learned.exr"); + let pool = crate::MediaPool::new(); + let mut f = std::collections::HashMap::new(); + for p in [given, learned] { + pool.add_bytes(p, bytes.clone()); + f.insert(p, crate::probe_bytes(p, bytes.clone()).unwrap()); + } + pool.set_aux_footage(&[given.to_string()]); + take_decodes(); + pool.frame_at(&f[given], Tick::ZERO).unwrap(); + assert!(pool.aux(ItemId(1), &f[given], Tick::ZERO).unwrap().get("diffuse.R").is_some()); + assert_eq!(take_decodes(), [0, 1], "the picture and the channels share one decode"); + pool.frame_at(&f[learned], Tick::ZERO).unwrap(); + pool.aux(ItemId(2), &f[learned], Tick::ZERO).unwrap(); + assert_eq!(take_decodes(), [0, 2]); + let d = decodes_of(learned); + assert_eq!(d[0].channels.len(), 4, "the picture alone"); + assert_eq!(d[1].channels.len() + 4, crate::exr_index::cached(learned).unwrap().channels.len(), "the rest"); +} + +/// #474: the picture made of the planes of a file with exact R, G, B channels is the `image` +/// crate's, bit for bit (first such part, alpha or opaque, data window placed with 0 around it), +/// in every alpha interpretation and float curve. +#[test] +fn picture_from_planes_is_the_image_crates() { + use effectcraft_project::AlphaMode; + let display = (5usize, 4usize); + let files = [ + write(vec![part(None, &[("R", true), ("G", true), ("B", true), ("A", false), ("Z", false)], display, Compression::ZIP16)], display), + write(vec![part(None, &[("R", false), ("G", false), ("B", false), ("Image.R", true)], display, Compression::RLE)], display), + write( + vec![part(Some("diffuse"), &[("R", true), ("G", true), ("B", true)], display, Compression::ZIP1), part(Some("beauty"), &RGBA, display, Compression::PIZ)], + display, + ), + ]; + for (k, bytes) in files.iter().enumerate() { + let path = format!("/3271-planes-{k}.exr"); + let source = ExrSource::Bytes(bytes.as_slice().into()); + assert!(matches!(crate::exr_index::get(&path, &source).unwrap().rgb, Rgb::Planes(..)), "file {k}"); + let img = crate::probe::load_oriented(bytes, Some(image::ImageFormat::OpenExr)).unwrap(); + for alpha in [AlphaMode::Straight, AlphaMode::Premultiplied, AlphaMode::Ignore] { + for curve in [FloatCurve::Srgb, FloatCurve::Linear, FloatCurve::Gamma24] { + let op = AlphaOp::of(&Footage { alpha, premul_color: [0.2, 0.4, 0.6], ..Default::default() }, curve); + let want = crate::convert::dynamic_to_image(&img, op); + let Picture::Done(Ok(got)) = picture(&path, &source, op, None) else { panic!("file {k}: a picture") }; + assert_eq!(bits(&got), bits(&want), "file {k} {alpha:?} {curve:?}"); + } + } + } +} diff --git a/crates/media/src/exr_read.rs b/crates/media/src/exr_read.rs new file mode 100644 index 000000000..f280c5542 --- /dev/null +++ b/crates/media/src/exr_read.rs @@ -0,0 +1,331 @@ +//! The OpenEXR reader (#3271): only the chunks a request needs, fetched by the offset table in +//! file order (part by part as the file stores them), decompressed with the `exr` crate's block +//! API on the thread pool the caller runs on (the footage decode threads), and only the +//! requested channels converted, straight into their display-window planes. +//! +//! - **No whole-file read.** A request reads the headers it is given ([`ExrIndex`]) and then +//! exactly the bytes of the chunks it needs; a multi-part file's other parts are never read. +//! - **Rows and levels.** A request names display rows and a level (every 2^level-th row and +//! column). With one scan line per chunk (NONE, RLE, ZIPS) a chunk is a line and the lines not +//! needed are not read or decompressed; with larger chunks (ZIP, PIZ, DWA, tiles) whole chunks +//! are skipped and the rows within a chunk are only skipped when converting. +//! - **Cancellable** between batches of chunks ([`filmcraft_media::cancel::cancelled`]). +//! - **Bit-identical** to the high-level reader: the same decompression, and each line placed +//! as `exr_channels`' planes reader placed it (clipped to the display window, the fill value +//! outside the data window, `u32` samples as `f32`). + +use std::io::{Read, Seek, SeekFrom}; +use std::ops::Range; +use std::sync::Arc; + +use effectcraft_render::reads::FileStamp; +use exr::block::UncompressedBlock; +use exr::block::chunk::Chunk; +use exr::meta::attribute::SampleType; +use rayon::prelude::*; + +use crate::exr_index::ExrIndex; + +/// A source to read an OpenEXR file from: in-memory bytes or a file on disk. +pub(crate) trait ReadSeek: Read + Seek + Send {} +impl ReadSeek for T {} + +/// Where an OpenEXR file's bytes come from. +#[derive(Clone, Debug)] +pub(crate) enum ExrSource { + /// Registered in memory (`MediaPool::add_bytes`, web builds, tests). + Bytes(Arc<[u8]>), + /// A file, opened for each read and read in place. + File(std::path::PathBuf), +} + +/// An opened [`ExrSource`]. +pub(crate) struct Opened { + pub(crate) reader: Box, + pub(crate) len: u64, + pub(crate) stamp: FileStamp, +} + +impl ExrSource { + /// Open it: a file only when it is a regular file (a project can name `/dev/zero` or a FIFO, + /// #2134), with its identity from the open file. + pub(crate) fn open(&self) -> std::io::Result { + match self { + ExrSource::Bytes(b) => Ok(Opened { len: b.len() as u64, reader: Box::new(std::io::Cursor::new(b.clone())), stamp: FileStamp::Virtual }), + ExrSource::File(path) => { + #[cfg(test)] + crate::count_open(path); + let file = std::fs::File::open(path)?; + let meta = file.metadata()?; + if !meta.is_file() { + return Err(std::io::Error::new(std::io::ErrorKind::InvalidInput, format!("{} is not a file", path.display()))); + } + Ok(Opened { len: meta.len(), stamp: FileStamp::of_metadata(&meta), reader: Box::new(file) }) + } + } + } +} + +/// What to read: channels (indices into [`ExrIndex::channels`]), display rows, and a level. +#[derive(Clone, Debug)] +pub(crate) struct ReadRequest { + pub(crate) channels: Vec, + /// Rows of the display window (full resolution); `None`: all. + pub(crate) rows: Option>, + /// Every 2^level-th row and column of the display window (0: full resolution). + pub(crate) level: u32, +} + +impl ReadRequest { + /// Every row of `channels` at full resolution. + pub(crate) fn full(channels: Vec) -> ReadRequest { + ReadRequest { channels, rows: None, level: 0 } + } +} + +/// What a read did, for measurements and tests. +#[derive(Clone, Debug, Default, PartialEq)] +pub(crate) struct ReadStats { + /// Chunks fetched, per part. + pub(crate) chunks: Vec, + /// Bytes of chunks read from the source. + pub(crate) bytes: u64, + /// Scan lines decompressed (rows of the chunks fetched). + pub(crate) lines: usize, +} + +/// Why a read gave no planes. +#[derive(Clone, Debug, PartialEq)] +pub(crate) enum ReadError { + /// A chunk can't be read or decompressed. + Unreadable(String), + /// The planes need more memory than one read may allocate (the reason, to show). + TooLarge(String), + /// The request was called off. + Cancelled, +} + +/// The most bytes of planes one read allocates (every requested channel is a display-window +/// plane of f32): a header can ask for far more than the file holds. +#[cfg(target_pointer_width = "64")] +pub(crate) const MAX_DECODE_BYTES: usize = 8 << 30; +#[cfg(not(target_pointer_width = "64"))] +pub(crate) const MAX_DECODE_BYTES: usize = 512 << 20; + +/// At most this many chunks, or bytes of them, are read before they are decompressed (and the +/// request is checked for being called off). +const BATCH_CHUNKS: usize = 256; +const BATCH_BYTES: u64 = 64 << 20; + +/// Samples of one line placed in a plane. +struct Placed { + /// The requested channel's position in the request. + slot: usize, + /// The first sample's index in the plane. + start: usize, + values: Vec, +} + +/// The size of the planes of a read at `level` of a `w` × `h` display window. +pub(crate) fn level_size((w, h): (usize, usize), level: u32) -> (usize, usize) { + let stride = 1usize << level.min(16); + (w.div_ceil(stride), h.div_ceil(stride)) +} + +/// Read `req` from `src` (the file `index` describes): one plane per requested channel, in +/// request order, covering the display window at the request's level (the channel's fill value +/// where the file has no samples or the request no rows). +pub(crate) fn read_planes(src: &mut dyn ReadSeek, index: &ExrIndex, req: &ReadRequest) -> (Result>, ReadError>, ReadStats) { + let mut stats = ReadStats { chunks: vec![0; index.parts.len()], ..Default::default() }; + let planes = read_into(src, index, req, &mut stats); + (planes, stats) +} + +fn read_into(src: &mut dyn ReadSeek, index: &ExrIndex, req: &ReadRequest, stats: &mut ReadStats) -> Result>, ReadError> { + let level = req.level.min(16); + let stride = 1i64 << level; + let (w, h) = index.size(); + let (ow, oh) = level_size((w, h), level); + let n = ow.checked_mul(oh).ok_or_else(|| ReadError::Unreadable("display window".into()))?; + let need = n.saturating_mul(req.channels.len()).saturating_mul(std::mem::size_of::()); + if need > MAX_DECODE_BYTES { + let gb = |b: usize| b as f64 / f64::from(1u32 << 30); + return Err(ReadError::TooLarge(format!( + "its {}×{} OpenEXR channels need {:.1} GB of memory, more than the {:.1} GB one file may use", + w, + h, + gb(need), + gb(MAX_DECODE_BYTES) + ))); + } + // Per part: the plane slot of each of its channels (`None`: not requested). + let mut slots: Vec>> = index.meta.headers.iter().map(|h| vec![None; h.channels.list.len()]).collect(); + let mut planes = Vec::with_capacity(req.channels.len()); + for (slot, id) in req.channels.iter().enumerate() { + let c = index.channels.get(*id).ok_or_else(|| ReadError::Unreadable("no such channel".into()))?; + if let Some(s) = slots.get_mut(c.part).and_then(|p| p.get_mut(c.channel)) { + *s = Some(slot); + } + planes.push(vec![c.fill; n]); + } + let rows = req.rows.clone().unwrap_or(0..h as i64); + let (r0, r1) = (rows.start.max(0), rows.end.min(h as i64)); + // A display row is read: in the rows, on the level's grid. + let wanted = move |ty: i64| ty >= r0 && ty < r1 && ty.rem_euclid(stride) == 0; + // A chunk holding display rows `a..b` has a row read. + let any_wanted = move |a: i64, b: i64| { + let first = a.max(r0); + let first = first + (stride - first.rem_euclid(stride)) % stride; + first < b.min(r1) + }; + // The chunks to read, in file order. + let mut jobs: Vec<(usize, u64, u64)> = vec![]; + for (pi, part) in index.parts.iter().enumerate() { + if !slots.get(pi).is_some_and(|s| s.iter().any(Option::is_some)) { + continue; + } + for c in &part.chunks { + let ty0 = c.y.saturating_add(part.offset.1); + if !c.largest || !any_wanted(ty0, ty0.saturating_add(c.rows as i64)) { + continue; + } + if c.len == 0 { + return Err(ReadError::Unreadable("a chunk offset outside the file".into())); + } + jobs.push((pi, c.offset, c.len)); + } + } + jobs.sort_by_key(|(_, offset, _)| *offset); + let geometry = Geometry { size: (w, h), out: (ow, oh), stride, wanted: &wanted }; + let mut pos: Option = None; + let mut rest = jobs.as_slice(); + while !rest.is_empty() { + if filmcraft_media::cancel::cancelled() { + return Err(ReadError::Cancelled); + } + // A batch: up to BATCH_CHUNKS chunks or BATCH_BYTES bytes (at least one chunk). + let mut take = 0; + let mut bytes = 0u64; + while let Some((_, _, len)) = rest.get(take) { + if take > 0 && (take >= BATCH_CHUNKS || bytes.saturating_add(*len) > BATCH_BYTES) { + break; + } + bytes = bytes.saturating_add(*len); + take += 1; + } + let (batch, more) = rest.split_at(take.min(rest.len())); + rest = more; + // Raw bytes on this thread, in file order (one seek per gap). + let mut raw = Vec::with_capacity(batch.len()); + for (pi, offset, len) in batch { + if pos != Some(*offset) { + src.seek(SeekFrom::Start(*offset)).map_err(|e| ReadError::Unreadable(e.to_string()))?; + } + let size = usize::try_from(*len).map_err(|_| ReadError::Unreadable("chunk size".into()))?; + let mut buf = Vec::new(); + buf.try_reserve_exact(size).map_err(|e| ReadError::Unreadable(e.to_string()))?; + (&mut *src).take(*len).read_to_end(&mut buf).map_err(|e| ReadError::Unreadable(e.to_string()))?; + pos = Some(offset.saturating_add(buf.len() as u64)); + stats.bytes = stats.bytes.saturating_add(buf.len() as u64); + if let Some(c) = stats.chunks.get_mut(*pi) { + *c += 1; + } + raw.push((*pi, buf)); + } + // Decompressed and converted on this pool's threads, placed here. + let done: Vec, usize), String>> = + raw.into_par_iter().map(|(pi, buf)| chunk_lines(index, pi, &buf, slots.get(pi).map_or(&[][..], Vec::as_slice), &geometry)).collect(); + for d in done { + let (placed, lines) = d.map_err(ReadError::Unreadable)?; + stats.lines = stats.lines.saturating_add(lines); + for p in placed { + let end = p.start.saturating_add(p.values.len()); + if let Some(dst) = planes.get_mut(p.slot).and_then(|pl| pl.get_mut(p.start..end)) { + dst.copy_from_slice(&p.values); + } + } + } + } + Ok(planes) +} + +/// The planes' geometry for [`chunk_lines`]. +struct Geometry<'w> { + /// The display window's size, and the planes' (at the level). + size: (usize, usize), + out: (usize, usize), + stride: i64, + wanted: &'w (dyn Fn(i64) -> bool + Sync), +} + +/// Decompress the chunk `buf` of part `pi` and convert the lines of the requested channels +/// (`slots`: each channel's plane slot): the samples to place, and the scan lines decompressed. +/// A chunk that names another part than its offset-table slot's is not placed. +fn chunk_lines(index: &ExrIndex, pi: usize, buf: &[u8], slots: &[Option], g: &Geometry) -> Result<(Vec, usize), String> { + let meta = &index.meta; + let mut read = buf; + let chunk = Chunk::read(&mut read, meta).map_err(|e| e.to_string())?; + if chunk.layer_index != pi { + return Ok((vec![], 0)); + } + let block = UncompressedBlock::decompress_chunk(chunk, meta, false).map_err(|e| e.to_string())?; + let (Some(header), Some(part)) = (meta.headers.get(pi), index.parts.get(pi)) else { return Ok((vec![], 0)) }; + let lines = block.index.pixel_size.1; + let ((lw, lh), (w, h)) = (part.layer, g.size); + let (ow, _) = g.out; + let mut out = vec![]; + let (mut f16s, mut f32s, mut u32s) = (vec![], vec![], vec![]); + for line in block.lines(&header.channels) { + let Some(Some(slot)) = slots.get(line.location.channel).copied() else { continue }; + let Some(kind) = header.channels.list.get(line.location.channel).map(|c| c.sample_type) else { continue }; + let (x0, y, count) = (line.location.position.0, line.location.position.1, line.location.sample_count); + // The samples of data-window row `y`, columns `x0..x0 + count`, at display row `ty` + // from display column `tx0`; clipped to the display window. + if y >= lh || x0.checked_add(count).is_none_or(|end| end > lw) { + continue; + } + let Some(ty) = usize::try_from(y as i64 + part.offset.1).ok().filter(|ty| *ty < h) else { continue }; + if !(g.wanted)(ty as i64) { + continue; + } + let tx0 = x0 as i64 + part.offset.0; + let skip = usize::try_from(-tx0).unwrap_or(0).min(count); + let tx = usize::try_from(tx0.max(0)).unwrap_or(usize::MAX); + let take = (count - skip).min(w.saturating_sub(tx)); + if take == 0 { + continue; + } + let samples: Vec = match kind { + SampleType::F16 => { + f16s.resize(count, exr::prelude::f16::ZERO); + line.read_samples_into_slice(&mut f16s).map_err(|e| e.to_string())?; + f16s.iter().skip(skip).take(take).map(|s| s.to_f32()).collect() + } + SampleType::F32 => { + f32s.resize(count, 0.0); + line.read_samples_into_slice(&mut f32s).map_err(|e| e.to_string())?; + f32s.iter().skip(skip).take(take).copied().collect() + } + SampleType::U32 => { + u32s.resize(count, 0); + line.read_samples_into_slice(&mut u32s).map_err(|e| e.to_string())?; + u32s.iter().skip(skip).take(take).map(|s| *s as f32).collect() + } + }; + if g.stride == 1 { + let Some(start) = ty.checked_mul(w).and_then(|row| row.checked_add(tx)) else { continue }; + out.push(Placed { slot, start, values: samples }); + continue; + } + // A reduced level: every stride-th column of the row, on the level's grid. + let stride = g.stride as usize; + let first = tx.div_ceil(stride) * stride; + let values: Vec = samples.iter().enumerate().filter(|(j, _)| (tx + j) % stride == 0).map(|(_, v)| *v).collect(); + if values.is_empty() { + continue; + } + let Some(start) = (ty / stride).checked_mul(ow).and_then(|row| row.checked_add(first / stride)) else { continue }; + out.push(Placed { slot, start, values }); + } + Ok((out, lines)) +} diff --git a/crates/media/src/lib.rs b/crates/media/src/lib.rs index f8fe58b2c..bed310b5f 100644 --- a/crates/media/src/lib.rs +++ b/crates/media/src/lib.rs @@ -20,6 +20,9 @@ mod convert; pub mod downmix; mod dpx; pub mod exr_channels; +mod exr_index; +mod exr_planes; +mod exr_read; mod gif_anim; mod layered; pub use layered::vector_doc; diff --git a/crates/media/src/pool.rs b/crates/media/src/pool.rs index b7598e53f..117ad439f 100644 --- a/crates/media/src/pool.rs +++ b/crates/media/src/pool.rs @@ -7,6 +7,7 @@ use std::sync::{Arc, Condvar, Mutex, OnceLock}; use effectcraft_project::{AlphaMode, Footage, FootageKind, ItemId}; use effectcraft_raster::{Image, Px}; +use effectcraft_raster::channels3d::AuxNeed; use effectcraft_render::reads::{FileStamp, ReadFile, ReadFiles, ReadLog}; use effectcraft_render::{FloatCurve, FootageSource}; use effectcraft_time::{FrameRate, TICKS_PER_SECOND, Tick}; @@ -316,7 +317,7 @@ impl Drop for Decoding { /// frame job that waits on it. The decode's own parallel work runs on these threads, which /// never wait for a picture. #[cfg(not(target_arch = "wasm32"))] -fn decode_threads() -> Option<&'static rayon::ThreadPool> { +pub(crate) fn decode_threads() -> Option<&'static rayon::ThreadPool> { static THREADS: OnceLock> = OnceLock::new(); THREADS .get_or_init(|| { @@ -436,12 +437,21 @@ struct AuxFootage { /// Read through [`FootageSource::aux`] but not given (a reader the project doesn't name, or /// a source that never gives a set). Cleared with each new set. learned: HashSet, + /// What the effects reading each footage's channels read of them + /// ([`FootageSource::set_aux_needs`], #3271); a footage read without one reads them all. + needs: HashMap, } impl AuxFootage { fn contains(&self, path: &str) -> bool { self.given.contains(path) || self.learned.contains(path) } + + /// The channels to read with the picture of footage `path`: what its effects read, all of + /// them when they didn't say, none (`None`) when no effect reads them. + fn plan(&self, path: &str) -> Option { + self.contains(path).then(|| self.needs.get(path).cloned().unwrap_or_default()) + } } /// Decodes footage for the renderer: stills, image sequences and movies (FilmCraft codecs), plus @@ -621,7 +631,7 @@ impl MediaPool { c.generation = c.generation.wrapping_add(1); c.last.remove(path); drop(c); - crate::exr_channels::forget(path); + crate::exr_planes::forget(path); } /// Provide the contents of `path` from memory (used instead of the file system; web builds). @@ -871,6 +881,14 @@ impl Inner { bytes } + /// Where the OpenEXR file at `path` is read from: registered bytes, else the file. + fn exr_source(&self, path: &str) -> crate::exr_read::ExrSource { + match lock(&self.files).get(path) { + Some(b) => crate::exr_read::ExrSource::Bytes(b.clone()), + None => crate::exr_read::ExrSource::File(std::path::PathBuf::from(path)), + } + } + /// The bytes of the file at `path` and its identity as read ([`FileStamp::Missing`] when it /// can't be read), not noted. fn read_file(&self, path: &str) -> (Result>, ReadFile) { @@ -1281,8 +1299,21 @@ impl Inner { if &**path == PLACEHOLDER { return Ok(colour_bars(footage.width, footage.height)); } + // OpenEXR: the picture's channels from the plane store, read chunk by chunk (#3271), with + // the channels effects read when they read this footage's (#474). + if crate::exr_planes::is_exr(path) { + use crate::exr_planes::Picture; + let extra = lock(&self.aux_footage).plan(&footage.path); + match crate::exr_planes::picture(path, &self.exr_source(path), op, extra.as_ref()) { + Picture::Done(Ok(img)) => return Ok(img), + Picture::Done(Err(why)) => return Err(MediaError::Decode(format!("{path}: {why}"))), + Picture::Cancelled => return Err(MediaError::Cancelled), + // (the `image` crate decodes the whole file) + Picture::Legacy => {} + } + } let (bytes, file) = self.read_file(path); - reads::note(file.clone()); + reads::note(file); let bytes = bytes?; if let Some(img) = crate::dpx::decode(path, &bytes)? { return Ok(dynamic_to_image(&img, op)); @@ -1297,21 +1328,15 @@ impl Inner { { return Err(MediaError::Decode(format!("{path}: {why}"))); } - // An effect reads this footage's channels: the picture is made of the same decode (#474). - let shared = lock(&self.aux_footage).contains(&footage.path); - if shared - && path.to_ascii_lowercase().ends_with(".exr") - && let Some(img) = crate::exr_channels::cached_picture(path, bytes.clone(), &file, op) - { - return Ok(img); - } #[cfg(test)] crate::exr_channels::count_decode(false); match crate::probe::load_oriented(&bytes, crate::still_format(path, &bytes)) { Ok(img) => Ok(dynamic_to_image(&img, op)), // A multi-layer OpenEXR file without an unnamed RGB layer: its colour layer. - Err(e) => crate::exr_channels::layered_picture(path, bytes, &file, op, shared) - .map_err(|why| MediaError::Decode(format!("{path}: {}", why.unwrap_or_else(|| e.to_string())))), + Err(e) => match crate::exr_channels::layered_image(&bytes) { + Some(img) => Ok(dynamic_to_image(&img, op)), + None => Err(MediaError::Decode(format!("{path}: {e}"))), + }, } } @@ -1350,6 +1375,20 @@ impl Inner { } } +impl MediaPool { + /// The OpenEXR file holding the channels of `footage` at `t` (a still or a sequence frame). + fn aux_path(&self, footage: &Footage, t: Tick) -> Option> { + if footage.missing || !footage.has_video { + return None; + } + let loc = Inner::locate(footage, t, FloatCurve::Srgb); + if loc.media_t.is_some() || !crate::exr_planes::is_exr(&loc.key.path) { + return None; + } + Some(loc.key.path) + } +} + impl FootageSource for MediaPool { fn set_conform_folder(&self, folder: Option) { MediaPool::set_conform_folder(self, folder); @@ -1414,21 +1453,32 @@ impl FootageSource for MediaPool { let given: HashSet = paths.iter().cloned().collect(); let mut wanted = lock(&self.inner.aux_footage); if given != wanted.given || !wanted.learned.is_empty() { - crate::exr_channels::release_held(); + crate::exr_planes::release_held(); } wanted.given = given; wanted.learned.clear(); } - fn aux(&self, _item: ItemId, footage: &Footage, t: Tick) -> Option> { - if footage.missing || !footage.has_video { - return None; + fn set_aux_needs(&self, needs: &[(String, AuxNeed)]) { + let mut wanted = lock(&self.inner.aux_footage); + let needs: HashMap = needs.iter().cloned().collect(); + if needs != wanted.needs { + crate::exr_planes::release_held(); } - let loc = Inner::locate(footage, t, FloatCurve::Srgb); - if loc.media_t.is_some() || !loc.key.path.to_ascii_lowercase().ends_with(".exr") { - return None; - } - let path = loc.key.path.clone(); + wanted.needs = needs; + } + + fn aux(&self, item: ItemId, footage: &Footage, t: Tick) -> Option> { + self.aux_for(item, footage, t, &AuxNeed::All) + } + + fn aux_names(&self, _item: ItemId, footage: &Footage, t: Tick) -> Option> { + let path = self.aux_path(footage, t)?; + crate::exr_planes::names(&path, &self.inner.exr_source(&path)) + } + + fn aux_for(&self, _item: ItemId, footage: &Footage, t: Tick, need: &AuxNeed) -> Option> { + let path = self.aux_path(footage, t)?; { let mut wanted = lock(&self.inner.aux_footage); if !wanted.contains(&footage.path) { @@ -1439,7 +1489,7 @@ impl FootageSource for MediaPool { wanted.learned.insert(footage.path.clone()); } } - crate::exr_channels::cached(&path, || self.inner.read(&path).ok()) + crate::exr_planes::aux(&path, &self.inner.exr_source(&path), need) } fn audio(&self, _item: ItemId, footage: &Footage, t: Tick, frames: usize, rate: u32) -> Option> { diff --git a/crates/media/src/probe.rs b/crates/media/src/probe.rs index 1fc945aa1..b12cb2c1c 100644 --- a/crates/media/src/probe.rs +++ b/crates/media/src/probe.rs @@ -266,10 +266,10 @@ fn probe_still_bytes(path: &str, bytes: &[u8], fmt: image::ImageFormat) -> Resul (w, h, dec.color_type().has_alpha()) } Err(e) => { - // A multi-layer OpenEXR file without an unnamed RGB layer. - let img = (fmt == image::ImageFormat::OpenExr).then(|| crate::exr_channels::layered_image(bytes)).flatten(); - let img = img.ok_or_else(|| MediaError::Decode(format!("{path}: {e}")))?; - (img.width(), img.height(), img.color().has_alpha()) + // A multi-layer OpenEXR file without an unnamed RGB layer: its picture's size and + // alpha from the headers alone (#3271), no pixels decoded. + let size = (fmt == image::ImageFormat::OpenExr).then(|| crate::exr_channels::layered_size(bytes)).flatten(); + size.ok_or_else(|| MediaError::Decode(format!("{path}: {e}")))? } }; Ok(still_footage(path, w, h, fmt, has_alpha))