665bfac0b339
exr_channels.rs
//! Auxiliary channels from multi-layer OpenEXR files (depth, object / material IDs, normals,
//! Cryptomatte, …) for the 3D Channel effects, read through the shared `craft-exr` decoder.
//!
//! Every channel of every layer becomes a plane named `layer.channel` (or just `channel` for
//! the unnamed layer), placed in the display window (pixels outside a layer's data window are
//! 0, or the background depth for depth channels). Cryptomatte manifests come from the
//! `cryptomatte/<key>/name` and `cryptomatte/<key>/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.
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::{AuxChannels, Image};
use effectcraft_render::reads::{ReadFile, ReadFiles};
use crate::convert::{AlphaOp, float_to_image};
/// The largest display window decoded (16384²; vector footage and Continuously Rasterize
/// stop at the same size).
const MAX_DISPLAY_PIXELS: usize = 1 << 28;
// Channel naming and the Cryptomatte manifest are `craft-exr`'s.
use craft_exr::channels::{is_depth, part_channel_name as channel_name};
pub use craft_exr::cryptomatte::parse_manifest;
/// Why an OpenEXR file's pixels can't be decoded when its headers name a compression this build
/// 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> {
let mut limits = craft_exr::decode::Limits::default();
limits.max_pixels = u64::MAX;
limits.max_bytes = u64::MAX;
craft_exr::decode::parts(bytes, &limits)
.ok()?
.iter()
.any(|part| matches!(part.compression.as_str(), "HTJ2K32" | "HTJ2K256"))
.then_some("OpenEXR HTJ2K compression isn't supported yet: re-save the file with ZIP, PIZ or DWAA compression")
}
/// 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 {
/// 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.
Planes([usize; 3], Option<usize>),
/// 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<AuxChannels>,
rgb: Rgb,
}
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 selected channels occupy in each part's own display window. The channel cache
/// reserves this before decoding so concurrent imports cannot exceed its soft budget.
fn planes_bytes(infos: &[craft_exr::decode::PartInfo], keep: &dyn Fn(&str) -> bool) -> Option<usize> {
infos.first()?;
let total = infos.iter().try_fold(0u64, |total, part| {
let count = part.channels.iter().filter(|channel| keep(&channel_name(part.name.as_deref(), &channel.name))).count() as u64;
if count == 0 {
return Some(total);
}
let pixels = u64::from(part.display_window.width).checked_mul(u64::from(part.display_window.height))?;
total.checked_add(pixels.checked_mul(count)?.checked_mul(4)?)
})?;
usize::try_from(total).ok()
}
/// Decode selected EXR channels through craft-exr, which places each selected block directly
/// into its bounded display-window plane.
fn decode(bytes: &[u8], keep: &dyn Fn(&str) -> bool) -> Result<Decoded, Refused> {
use craft_exr::decode::{self, Error as ExrError, Limits};
let mut limits = Limits::default();
limits.max_pixels = MAX_DISPLAY_PIXELS as u64;
limits.max_bytes = MAX_DECODE_BYTES as u64;
// Header-only checks must not charge channels this caller does not decode. The shared display
// decoder independently checks the exact selected display planes before allocating them. It
// also bounds a selected part's data window across all of its channels (decoded blocks carry
// every channel before the unused ones are dropped), so a part whose full channel set exceeds
// `max_bytes` is refused even when the kept planes alone would fit.
let mut header_limits = limits;
header_limits.max_width = u32::MAX;
header_limits.max_height = u32::MAX;
header_limits.max_pixels = u64::MAX;
header_limits.max_bytes = u64::MAX;
let infos = decode::parts(bytes, &header_limits).map_err(|e| match e {
ExrError::LimitExceeded(message) => Refused::TooLarge(message),
_ => Refused::Unreadable,
})?;
let display = infos.first().ok_or(Refused::Unreadable)?.display_window;
let needed = planes_bytes(&infos, keep).filter(|bytes| *bytes > 0).ok_or(Refused::Unreadable)?;
if needed > MAX_DECODE_BYTES {
let gb = |b: u64| 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.width,
display.height,
gb(needed as u64),
gb(MAX_DECODE_BYTES as u64),
)));
}
let mut aux = AuxChannels::new(display.width, display.height, 1.0);
let mut crypto: HashMap<String, (Option<String>, Option<String>)> = HashMap::new();
let mut rgb = Rgb::None;
for info in infos {
for (key, value) in &info.text_attributes {
let Some(rest) = key.strip_prefix("cryptomatte/") else { continue };
let Some((id, field)) = rest.split_once('/') else { continue };
let entry = crypto.entry(id.to_string()).or_default();
match field {
"name" => entry.0 = Some(value.clone()),
"manifest" => entry.1 = Some(value.clone()),
_ => {}
}
}
let prefix = info.name.as_deref();
let exact = info.display_window == display;
let rgb_indices = ["R", "G", "B"].map(|wanted| info.channels.iter().position(|channel| channel.name == wanted));
let has_rgb = rgb_indices.iter().all(Option::is_some);
let alpha_index = info.channels.iter().position(|channel| channel.name == "A");
// Metadata above still belongs to the file, but an ignored part must not allocate or
// impose its pixel/deep-data limits on the selected picture channels.
if !info.channels.iter().any(|channel| keep(&channel_name(prefix, &channel.name))) {
if rgb == Rgb::None && has_rgb {
rgb = Rgb::Unsupported;
}
continue;
}
let mut part = decode::decode_display_part(
bytes,
info.index,
keep,
&|name| {
if is_depth(name) { BACKGROUND_DEPTH } else { 0.0 }
},
&limits,
)
.map_err(|error| match error {
ExrError::LimitExceeded(message) => Refused::TooLarge(message),
_ => Refused::Unreadable,
})?;
if rgb == Rgb::None && has_rgb {
let base = aux.channels.len();
let locate = |raw: usize| {
let name = channel_name(prefix, &info.channels.get(raw)?.name);
part.channels.iter().position(|channel| channel.name == name)
};
rgb = match (rgb_indices[0].and_then(locate), rgb_indices[1].and_then(locate), rgb_indices[2].and_then(locate)) {
(Some(r), Some(g), Some(b)) if exact => {
let a = alpha_index.and_then(locate);
let depth =
[Some(r), Some(g), Some(b), a].into_iter().flatten().any(|i| part.channels.get(i).is_some_and(|channel| is_depth(&channel.name)));
if depth { Rgb::Unsupported } else { Rgb::Planes([base + r, base + g, base + b], a.map(|i| base + i)) }
}
_ => Rgb::Unsupported,
};
}
aux.channels.extend(part.channels.drain(..).map(|channel| (channel.name, channel.samples)));
}
for (_, (name, manifest)) in crypto {
if let (Some(name), Some(manifest)) = (name, manifest) {
aux.manifests.push((name, parse_manifest(&manifest)));
}
}
aux.manifests.sort();
Ok(Decoded { aux: Arc::new(aux), rgb })
}
/// 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<AuxChannels> {
let aux = decode(bytes, &|_| true).ok()?.aux;
Some(Arc::try_unwrap(aux).unwrap_or_else(|a| (*a).clone()))
}
/// Names of the beauty pass, most preferred first, matched against the last part of a layer's
/// name (Blender's `ViewLayer.Combined` is `Combined`): Blender's Combined pass and its
/// compositor's File Output default `Image`, the beauty / rgba / rgb / color of Nuke, Arnold and
/// V-Ray.
const BEAUTY: [&str; 7] = ["combined", "beauty", "image", "rgba", "rgb", "color", "colour"];
/// A data pass, never the picture: Cryptomatte (`CryptoMaterial00`), depth, mist, normals,
/// motion vectors, positions, UVs and object / material indices.
fn is_data_layer(layer: &str) -> bool {
let last = layer.rsplit('.').next().unwrap_or(layer).to_ascii_lowercase();
last.starts_with("crypto")
|| ["z", "uv", "id", "mist", "indexob", "indexma"].contains(&last.as_str())
|| ["depth", "normal", "vector", "position", "velocity", "motion", "objectid", "materialid"].iter().any(|k| last.contains(k))
}
/// The layer whose colour a multi-layer file shows (see [`layered_image`]).
fn picture_layer<'a>(aux: &AuxChannels, layers: &[&'a str]) -> Option<&'a str> {
// Colour layers: three different channels (not one channel, such as depth, shown in all).
let rgb: Vec<&str> = layers
.iter()
.copied()
.filter(|l| {
let [r, g, b, _] = aux.layer_rgba(l);
!r.is_empty() && !g.is_empty() && !b.is_empty() && r != g
})
.collect();
let last = |l: &str| l.rsplit('.').next().unwrap_or(l).to_ascii_lowercase();
let pictures = || rgb.iter().filter(|l| !is_data_layer(l));
// The unnamed layer (plain R, G, B), then the beauty pass by name.
rgb.iter()
.find(|l| l.is_empty())
.or_else(|| BEAUTY.iter().find_map(|k| rgb.iter().find(|l| last(l) == *k)))
.or_else(|| pictures().find(|l| ["combined", "beauty"].iter().any(|k| last(l).contains(k))))
.or_else(|| pictures().next())
.or_else(|| layers.iter().find(|l| !is_data_layer(l)))
.or_else(|| rgb.first())
.or_else(|| layers.first())
.copied()
}
/// 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<String>)> {
let layers = aux.layers();
let colour = picture_layer(aux, &layers)?;
let names = aux.layer_rgba(colour);
// A layer without R, G and B channels shows its first channel as grey.
let first = aux.names().into_iter().find(|n| split_channel(n).0 == colour).unwrap_or_default();
let pick = |k: usize| names.get(k).map(String::as_str).filter(|n| !n.is_empty()).unwrap_or(first).to_string();
let a = names.get(3).filter(|n| !n.is_empty() && aux.get(n).is_some()).cloned();
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<String>), Refused> {
let mut limits = craft_exr::decode::Limits::default();
limits.max_width = u32::MAX;
limits.max_height = u32::MAX;
limits.max_pixels = u64::MAX;
limits.max_bytes = u64::MAX;
let meta = craft_exr::decode::parts(bytes, &limits).map_err(|_| Refused::Unreadable)?;
let mut names = AuxChannels::new(0, 0, 1.0);
for part in meta {
let prefix = part.name.as_deref();
names.channels.extend(part.channels.iter().map(|ch| (channel_name(prefix, &ch.name), 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.
pub fn layered_image(bytes: &[u8]) -> Option<image::DynamicImage> {
let (d, rgb, a) = picture_only(bytes).ok()?;
let aux = &d.aux;
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)?),
None => None,
};
let n = (aux.width as usize).checked_mul(aux.height as usize)?;
let mut data = Vec::with_capacity(n.checked_mul(4)?);
for i in 0..n {
data.extend([r.get(i)?, g.get(i)?, b.get(i)?].map(|v| *v));
if let Some(a) = a {
data.push(*a.get(i)?);
}
}
match a {
Some(_) => image::Rgba32FImage::from_raw(aux.width, aux.height, data).map(image::DynamicImage::ImageRgba32F),
None => image::Rgb32FImage::from_raw(aux.width, aux.height, data).map(image::DynamicImage::ImageRgb32F),
}
}
/// 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<Image> {
let n = (aux.width as usize).checked_mul(aux.height as usize)?;
if rgb.iter().chain(&a).any(|p| p.len() < n) {
return None;
}
let [r, g, b] = rgb;
let at = |p: &[f32], i: usize| p.get(i).copied().unwrap_or(0.0);
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<Image> {
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<Image, Option<String>> {
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<Image> {
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<OnceLock<(Option<Arc<Decoded>>, 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<Arc<[u8]>> {
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, someone is using the slot, or it is decoding.
fn in_use(&self) -> bool {
// `get_or_init` hands an active caller a borrow of the OnceLock value before that caller
// can clone the decoded Arc. Keep the entry while any caller still holds this slot, or a
// concurrent account/eviction can remove it in that gap and make the next request decode
// the same file again.
if Arc::strong_count(&self.slot) > 1 {
return true;
}
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<Entry>,
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<Decoded>)>,
}
/// 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<State>,
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<Arc<[u8]>>) -> Option<Arc<Decoded>> {
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 (which `Inner::frame_at` avoids for frames): that
// is safe because the decode never waits on rayon's global 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<Arc<Decoded>> {
// The planes it will allocate count against the budget while it decodes.
let mut limits = craft_exr::decode::Limits::default();
limits.max_width = u32::MAX;
limits.max_height = u32::MAX;
limits.max_pixels = u64::MAX;
limits.max_bytes = u64::MAX;
if let Ok(infos) = craft_exr::decode::parts(bytes, &limits)
&& let Some(need) = planes_bytes(&infos, &|_| 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<Entry>, budget: usize, newest: &Slot) {
while entries.iter().map(|e| e.bytes).sum::<usize>() > 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<String> {
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<Arc<[u8]>>) -> Option<Arc<AuxChannels>> {
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.
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`)
/// or by the `image` crate.
#[cfg(test)]
pub(crate) fn count_decode(channels: bool) {
DECODES.with(|d| {
let mut n = d.get();
n[usize::from(channels)] += 1;
d.set(n);
});
}
/// The decodes [`count_decode`] counted on this thread since the last call: by the `image` crate
/// and by the channel cache.
#[cfg(test)]
pub(crate) fn take_decodes() -> [u64; 2] {
DECODES.with(|d| d.replace([0; 2]))
}
#[cfg(test)]
mod tests {
use super::*;
/// An EXR file of `layers` (with their display window `display`).
fn file(layers: Vec<exr::prelude::Layer<exr::prelude::AnyChannels<exr::prelude::FlatSamples>>>, display: exr::prelude::IntegerBounds) -> Vec<u8> {
use exr::prelude::*;
let image = Image::from_layers(ImageAttributes::new(display), layers);
let mut bytes = std::io::Cursor::new(Vec::new());
image.write().to_buffered(&mut bytes).unwrap();
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<u8> {
use exr::prelude::*;
let list: Vec<AnyChannel<FlatSamples>> = 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::*;
let (w, h) = (4usize, 2usize);
let z: Vec<f32> = (0..w * h).map(|i| i as f32 * 10.0).collect();
let id: Vec<f32> = (0..w * h).map(|i| (i % 2) as f32 + 1.0).collect();
let r: Vec<f32> = vec![0.5; w * h];
let channels = AnyChannels::sort(
vec![
AnyChannel::new("R", FlatSamples::F32(r)),
AnyChannel::new("Z", FlatSamples::F32(z.clone())),
AnyChannel::new("ObjectID", FlatSamples::F32(id.clone())),
]
.into(),
);
let mut layer = Layer::new((w, h), LayerAttributes::named("depth"), Encoding::FAST_LOSSLESS, channels);
layer.attributes.other.insert(Text::from("cryptomatte/abc1234/name"), AttributeValue::Text(Text::from("CryptoObject")));
layer
.attributes
.other
.insert(Text::from("cryptomatte/abc1234/manifest"), AttributeValue::Text(Text::from(r#"{"bunny":"13851a76","floor":"0a1b2c3d"}"#)));
let image = Image::from_layer(layer);
let mut bytes = std::io::Cursor::new(Vec::new());
image.write().to_buffered(&mut bytes).unwrap();
let aux = read_exr_channels(bytes.get_ref()).unwrap();
assert_eq!((aux.width, aux.height), (4, 2));
assert_eq!(aux.get("depth.Z").unwrap(), z.as_slice());
assert_eq!(aux.depth().unwrap(), z.as_slice());
assert_eq!(aux.object_id().unwrap(), id.as_slice());
assert_eq!(aux.manifests, vec![("CryptoObject".to_string(), vec![("bunny".to_string(), 0x1385_1a76), ("floor".to_string(), 0x0a1b_2c3d)])]);
assert!(read_exr_channels(b"not an exr").is_none());
}
/// #474: each line of samples goes straight into its display-window plane: a data window
/// inside the display window is placed with the fill around it (the background depth for
/// depth), one partly outside is clipped, never out of bounds; half and uint samples are
/// converted as the file stores them.
#[test]
fn channels_are_placed_in_the_display_window() {
use exr::prelude::*;
let half = |x: f32| f16::from_f32(x);
let part = |pos: (i32, i32), size: (usize, usize), list: Vec<AnyChannel<FlatSamples>>| {
let attrs = LayerAttributes { layer_position: Vec2(pos.0, pos.1), ..Default::default() };
Layer::new(size, attrs, Encoding::FAST_LOSSLESS, AnyChannels::sort(list.into()))
};
let display = IntegerBounds::from_dimensions((3, 2));
// A 2×1 data window at (1, 1).
let inside = file(
vec![part(
(1, 1),
(2, 1),
vec![AnyChannel::new("G", FlatSamples::F16(vec![half(1.0), half(2.0)])), AnyChannel::new("Z", FlatSamples::U32(vec![7, 8]))],
)],
display,
);
let aux = read_exr_channels(&inside).unwrap();
assert_eq!(aux.get("G").unwrap(), [0.0, 0.0, 0.0, 0.0, 1.0, 2.0]);
let bg = BACKGROUND_DEPTH;
assert_eq!(aux.get("Z").unwrap(), [bg, bg, bg, bg, 7.0, 8.0]);
// A 2×2 data window at (2, -1): only its bottom-left sample lands at (2, 0).
let off = file(vec![part((2, -1), (2, 2), vec![AnyChannel::new("G", FlatSamples::F32(vec![1.0, 2.0, 3.0, 4.0]))])], display);
assert_eq!(read_exr_channels(&off).unwrap().get("G").unwrap(), [0.0, 0.0, 3.0, 0.0, 0.0, 0.0]);
// Entirely outside: all fill.
let away = file(vec![part((-5, 0), (2, 2), vec![AnyChannel::new("G", FlatSamples::F32(vec![1.0; 4]))])], display);
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<Arc<Decoded>> = 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);
}
#[test]
fn cache_does_not_evict_a_slot_while_a_caller_is_using_it() {
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(one);
drop(cache.get("/active.exr", Use::Channels, || Some(bytes.clone())));
let active_slot = cache.lock().entries.iter().find(|entry| entry.path == "/active.exr").unwrap().slot.clone();
drop(cache.get("/next.exr", Use::Channels, || Some(bytes.clone())));
assert!(cache.cached().contains(&"/active.exr".to_string()), "an active caller pins the slot");
drop(active_slot);
drop(cache.get("/newest.exr", Use::Channels, || Some(bytes.clone())));
assert!(!cache.cached().contains(&"/active.exr".to_string()), "an idle slot is eligible for eviction");
}
/// #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]
fn a_header_asking_for_too_much_memory_is_refused() {
use exr::prelude::*;
let list: Vec<AnyChannel<FlatSamples>> = (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"),
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);
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<String> = (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<AnyChannel<FlatSamples>>| {
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::<Vec<_>>();
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:?}");
}
}
}
}
/// #2141: one pixel of data in a 60000² display window is refused, not allocated per channel.
#[test]
fn a_huge_display_window_is_refused_not_allocated() {
use exr::prelude::*;
let channels = AnyChannels::sort(vec![AnyChannel::new("R", FlatSamples::F32(vec![0.5]))].into());
let mut image = Image::from_layer(Layer::new((1, 1), LayerAttributes::default(), Encoding::FAST_LOSSLESS, channels));
image.attributes.display_window = IntegerBounds::new((0, 0), (60000, 60000));
let mut bytes = std::io::Cursor::new(Vec::new());
image.write().to_buffered(&mut bytes).unwrap();
assert!(read_exr_channels(&bytes.into_inner()).is_none());
}
#[test]
fn layered_exr_without_an_unnamed_rgb_layer_imports() {
use exr::prelude::*;
let (w, h) = (4usize, 2usize);
let ch = |n: &str, v: f32| AnyChannel::new(n, FlatSamples::F32(vec![v; w * h]));
let channels = AnyChannels::sort(vec![ch("diffuse.R", 1.0), ch("diffuse.G", 0.2), ch("diffuse.B", 0.0), ch("depth.Z", 7.0)].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();
let b: Arc<[u8]> = bytes.into_inner().into();
let f = crate::probe_bytes("/layers.exr", b.clone()).unwrap();
assert_eq!((f.width, f.height, f.alpha), (4, 2, effectcraft_project::AlphaMode::Ignore));
let pool = crate::MediaPool::new();
pool.add_bytes("/layers.exr", b.clone());
let px = pool.frame_at(&f, effectcraft_time::Tick::ZERO).unwrap().get(1, 1);
assert!((px[0] - 1.0).abs() < 1e-4 && px[1] > 0.3 && px[1] < 0.6 && px[2] < 1e-4 && px[3] == 1.0, "diffuse, sRGB-encoded: {px:?}");
let aux = read_exr_channels(&b).unwrap();
assert_eq!(aux.layers(), ["depth", "diffuse"]);
assert_eq!(aux.layer_rgba("diffuse"), ["diffuse.R", "diffuse.G", "diffuse.B", ""].map(String::from));
}
/// #481: Blender 5 writes one part per pass, its channels keeping the full pass name
/// (`ViewLayer.Depth.Z` in part `ViewLayer.Depth`); the name was doubled and the depth and
/// Cryptomatte ranks were not found.
#[test]
fn part_name_is_not_doubled_when_channels_carry_it() {
assert_eq!(channel_name(Some("ViewLayer.Depth"), "ViewLayer.Depth.Z"), "ViewLayer.Depth.Z");
assert_eq!(channel_name(Some("depth"), "Z"), "depth.Z");
assert_eq!(channel_name(Some("depth"), "depthZ"), "depth.depthZ");
assert_eq!(channel_name(None, "R"), "R");
assert_eq!(channel_name(None, "ViewLayer.Depth.Z"), "ViewLayer.Depth.Z");
}
#[test]
fn blender5_multipart_file_keeps_pass_names() {
use exr::prelude::*;
let (w, h) = (2usize, 2usize);
let part = |name: &str, chans: &[&str], v: f32| {
let list: Vec<AnyChannel<FlatSamples>> = chans.iter().map(|c| AnyChannel::new(*c, FlatSamples::F32(vec![v; w * h]))).collect();
Layer::new((w, h), LayerAttributes::named(name), Encoding::FAST_LOSSLESS, AnyChannels::sort(list.into()))
};
let layers =
vec![part("ViewLayer.Depth", &["ViewLayer.Depth.Z"], 4.0), part("ViewLayer.Combined", &["ViewLayer.Combined.R", "ViewLayer.Combined.G"], 0.5)];
let image = Image::from_layers(ImageAttributes::with_size((w, h)), layers);
let mut bytes = std::io::Cursor::new(Vec::new());
image.write().to_buffered(&mut bytes).unwrap();
let aux = read_exr_channels(bytes.get_ref()).unwrap();
assert_eq!(aux.get("ViewLayer.Depth.Z").unwrap(), [4.0; 4].as_slice());
assert!(aux.get("ViewLayer.Depth.ViewLayer.Depth.Z").is_none());
assert!(aux.get("ViewLayer.Combined.R").is_some());
}
#[test]
fn multipart_fallback_filters_channels_and_reserves_display_planes() {
use exr::prelude::*;
let part = |name: &str, pos: (i32, i32), size: (usize, usize), channels: Vec<AnyChannel<FlatSamples>>| {
let attrs = LayerAttributes { layer_name: Some(Text::from(name)), layer_position: Vec2(pos.0, pos.1), ..Default::default() };
Layer::new(size, attrs, Encoding::FAST_LOSSLESS, AnyChannels::sort(channels.into()))
};
let (w, h) = (2usize, 1usize);
let bytes = file(
vec![
part("Depth", (0, 0), (1, 1), vec![AnyChannel::new("Z", FlatSamples::F32(vec![7.0]))]),
part(
"Beauty",
(1, 1),
(w, h),
vec![
AnyChannel::new("R", FlatSamples::F32(vec![0.1; w * h])),
AnyChannel::new("G", FlatSamples::F32(vec![0.2; w * h])),
AnyChannel::new("B", FlatSamples::F32(vec![0.3; w * h])),
],
),
],
IntegerBounds::from_dimensions((3, 2)),
);
let mut limits = craft_exr::decode::Limits::default();
limits.max_width = u32::MAX;
limits.max_height = u32::MAX;
limits.max_pixels = u64::MAX;
limits.max_bytes = u64::MAX;
let parts = craft_exr::decode::parts(&bytes, &limits).unwrap();
assert_eq!(planes_bytes(&parts, &|name| name == "Beauty.R"), Some(3 * 2 * 4));
assert_eq!(planes_bytes(&parts, &|_| false), Some(0));
// Different display windows must not reserve every part at the first part's size.
let mut varied = parts.clone();
varied[0].display_window.width = 1;
varied[0].display_window.height = 1;
varied[1].display_window.width = 10;
varied[1].display_window.height = 20;
assert_eq!(planes_bytes(&varied, &|_| true), Some(4 + 10 * 20 * 3 * 4));
assert_eq!(planes_bytes(&varied, &|name| name == "Beauty.R"), Some(10 * 20 * 4));
varied[1].display_window.width = u32::MAX;
varied[1].display_window.height = u32::MAX;
assert_eq!(planes_bytes(&varied, &|_| true), None);
assert_eq!(planes_bytes(&varied, &|name| name == "Depth.Z"), Some(4));
// Skipping the RGB part preserves the first-RGB fallback state and depth samples.
let depth = decode(&bytes, &|name| name == "Depth.Z").unwrap();
assert_eq!(depth.rgb, Rgb::Unsupported);
assert_eq!(depth.aux.channels.len(), 1);
assert_eq!(depth.aux.get("Depth.Z").unwrap()[0], 7.0);
let selected = decode(&bytes, &|name| name == "Beauty.R").unwrap();
assert_eq!(selected.aux.channels.iter().map(|(name, _)| name.as_str()).collect::<Vec<_>>(), ["Beauty.R"]);
assert_eq!(selected.aux.get("Beauty.R").unwrap(), [0.0, 0.0, 0.0, 0.0, 0.1, 0.1]);
// The old app decoder selected the named beauty part when the first part was depth-only,
// and placed its data into the shared display window; retain that layered-picture result.
let image = layered_image(&bytes).unwrap().to_rgba32f();
assert_eq!(image.get_pixel(1, 1).0, [0.1, 0.2, 0.3, 1.0]);
assert_eq!(image.get_pixel(0, 0).0, [0.0, 0.0, 0.0, 1.0]);
}
/// Straight RGBA of [`layered_image`] at pixel 0 for a file of single-value channels.
fn picture<S: AsRef<str>>(channels: &[(S, f32)]) -> Vec<f32> {
use exr::prelude::*;
let (w, h) = (2usize, 2usize);
let list: Vec<AnyChannel<FlatSamples>> = channels.iter().map(|(n, v)| AnyChannel::new(n.as_ref(), FlatSamples::F32(vec![*v; w * h]))).collect();
let image = Image::from_layer(Layer::new((w, h), LayerAttributes::default(), Encoding::FAST_LOSSLESS, AnyChannels::sort(list.into())));
let mut bytes = std::io::Cursor::new(Vec::new());
image.write().to_buffered(&mut bytes).unwrap();
let img = layered_image(bytes.get_ref()).unwrap().to_rgba32f();
img.get_pixel(0, 0).0.to_vec()
}
/// #412: a Blender compositor File Output (multilayer) names its beauty pass `Image`, and its
/// Cryptomatte layers (lowercase `r, g, b, a`) sort first. The picture was CryptoMaterial00;
/// it is the Image layer, and data passes are never the picture.
#[test]
fn layered_exr_shows_the_beauty_pass_not_cryptomatte() {
let mut blender = vec![];
for layer in ["CryptoMaterial00", "CryptoMaterial01", "CryptoMaterial02"] {
blender.extend(["r", "g", "b", "a"].map(|c| (format!("{layer}.{c}"), 0.9)));
}
for (layer, v) in [("GlossCol", 0.3), ("GlossDir", 0.4), ("Image", 0.5), ("VolDir", 0.6)] {
blender.extend(["R", "G", "B", "A"].map(|c| (format!("{layer}.{c}"), v)));
}
blender.push(("Mist.Z".into(), 0.7));
assert_eq!(picture(&blender), [0.5; 4], "the Image layer");
// Blender's render-layer names and Nuke's beauty.
assert_eq!(
picture(&[
("ViewLayer.CryptoObject00.r", 0.9),
("ViewLayer.CryptoObject00.g", 0.9),
("ViewLayer.CryptoObject00.b", 0.9),
("ViewLayer.Combined.R", 0.2),
("ViewLayer.Combined.G", 0.2),
("ViewLayer.Combined.B", 0.2)
]),
[0.2, 0.2, 0.2, 1.0]
);
// No beauty name: the first colour layer that isn't a data pass.
let no_beauty: Vec<(String, f32)> = blender.iter().filter(|(n, _)| !n.starts_with("Image")).cloned().collect();
assert_eq!(picture(&no_beauty), [0.3; 4], "GlossCol, not Cryptomatte");
// Only data and a grey pass: the grey pass, not depth.
assert_eq!(picture(&[("Depth.Z", 9.0), ("AO.Y", 0.25)]), [0.25, 0.25, 0.25, 1.0]);
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.