Skip to main content

alpha2_extensions/
sequence.rs

1//! PNG or OpenEXR stills played in order at a fixed rate.
2//!
3//! Frames are read through the resolver when shown, and only recently decoded frames are kept,
4//! within a byte budget. Every frame must match the first frame's format and size, and OpenEXR
5//! frames all use the first frame's (or the project's) color.
6
7use std::collections::VecDeque;
8use std::sync::Arc;
9
10use alpha2_model::{LinearPrimaries, MissingFrames};
11use alpha2_time::{FrameRate, MediaTime};
12
13use crate::api::{
14    Diagnostic, ExtensionError, Format, FramePixels, LinearColor, ProbeReport, SharedResolver,
15    Timing, VisualFrame, VisualSource, premultiply,
16};
17use crate::budget::{DEFAULT_FRAME_BUDGET, check_canvas};
18use crate::raster::decode_png;
19
20/// Opens an image sequence of `frames` in play order (`None` for a gap). Only the first frame is
21/// read here; `primaries` overrides OpenEXR color.
22///
23/// # Errors
24/// If the first frame cannot be read or the settings are incoherent.
25pub fn open_sequence(
26    frames: &[Option<String>],
27    rate: FrameRate,
28    missing: MissingFrames,
29    primaries: Option<LinearPrimaries>,
30    resolver: SharedResolver,
31) -> Result<Box<dyn VisualSource>, ExtensionError> {
32    open_within(
33        frames,
34        rate,
35        missing,
36        primaries,
37        resolver,
38        DEFAULT_FRAME_BUDGET,
39    )
40}
41
42/// [`open_sequence`] keeping at most `budget` decoded bytes, plus the frame last shown.
43pub(crate) fn open_within(
44    frames: &[Option<String>],
45    rate: FrameRate,
46    missing: MissingFrames,
47    primaries: Option<LinearPrimaries>,
48    resolver: SharedResolver,
49    budget: usize,
50) -> Result<Box<dyn VisualSource>, ExtensionError> {
51    let first = frames
52        .first()
53        .and_then(Option::as_ref)
54        .ok_or_else(|| ExtensionError::Malformed("the sequence's first frame is missing".into()))?;
55    if missing == MissingFrames::Reject && frames.iter().any(Option::is_none) {
56        return Err(ExtensionError::Mismatch(
57            "the sequence has a gap and refuses missing frames".into(),
58        ));
59    }
60    let first = decode(&resolver.bytes(first)?, None, primaries)?;
61    if first.color.is_none() && primaries.is_some() {
62        return Err(ExtensionError::Mismatch(
63            "primaries apply to OpenEXR frames, and these are PNGs".into(),
64        ));
65    }
66    check_canvas(first.width, first.height)?;
67    let report = ProbeReport {
68        format: first.format,
69        width: first.width,
70        height: first.height,
71        timing: Timing::Rate {
72            rate,
73            frames: frames.len(),
74        },
75        loop_count: None,
76        items: Vec::new(),
77        item: None,
78        color: first.color.clone(),
79        diagnostics: first.diagnostics.clone(),
80    };
81    let mut source = SequenceSource {
82        frames: frames.to_vec(),
83        resolver,
84        missing,
85        report,
86        kept: VecDeque::new(),
87        kept_bytes: 0,
88        budget,
89    };
90    source.keep(0, Arc::new(first));
91    Ok(Box::new(source))
92}
93
94struct Decoded {
95    format: Format,
96    width: u32,
97    height: u32,
98    pixels: FramePixels,
99    /// The color an OpenEXR frame was read in.
100    color: Option<LinearColor>,
101    diagnostics: Vec<Diagnostic>,
102}
103
104impl Decoded {
105    fn bytes(&self) -> usize {
106        match &self.pixels {
107            FramePixels::Rgba8(pixels) => pixels.len(),
108            FramePixels::LinearF16(pixels) => pixels.len() * 2,
109        }
110    }
111}
112
113/// Decodes a PNG or OpenEXR frame. OpenEXR color is `color`, else `primaries`, else declared.
114fn decode(
115    bytes: &[u8],
116    color: Option<&LinearColor>,
117    primaries: Option<LinearPrimaries>,
118) -> Result<Decoded, ExtensionError> {
119    #[cfg(feature = "exr")]
120    if crate::exr::is_exr(bytes) {
121        let color = color
122            .cloned()
123            .or_else(|| primaries.map(crate::exr::project_color));
124        let image = crate::exr::decode_exr(bytes, color)?;
125        return Ok(Decoded {
126            format: Format::ExrSequence,
127            width: image.width,
128            height: image.height,
129            pixels: FramePixels::LinearF16(image.pixels.into()),
130            color: Some(image.color),
131            diagnostics: image.diagnostics,
132        });
133    }
134    let _ = (color, primaries);
135    if bytes.starts_with(&[0x76, 0x2f, 0x31, 0x01]) {
136        return Err(ExtensionError::Unsupported(
137            "this build reads no OpenEXR frames".into(),
138        ));
139    }
140    let (width, height, mut pixels) = decode_png(bytes)?;
141    premultiply(&mut pixels);
142    Ok(Decoded {
143        format: Format::PngSequence,
144        width,
145        height,
146        pixels: FramePixels::Rgba8(pixels.into()),
147        color: None,
148        diagnostics: Vec::new(),
149    })
150}
151
152struct SequenceSource {
153    /// `None` for a gap.
154    frames: Vec<Option<String>>,
155    resolver: SharedResolver,
156    missing: MissingFrames,
157    report: ProbeReport,
158    /// Recently decoded frames by index, newest last.
159    kept: VecDeque<(usize, Arc<Decoded>)>,
160    kept_bytes: usize,
161    /// The newest frame is kept whatever its size.
162    budget: usize,
163}
164
165impl SequenceSource {
166    /// Index, start, end, and the index whose picture is shown at `time` (a held gap shows the
167    /// nearest earlier present frame).
168    fn shown(&self, time: MediaTime) -> (usize, MediaTime, Option<MediaTime>, usize) {
169        let (index, start, end) = self.report.timing.frame_at(time);
170        let shown = match self.missing {
171            MissingFrames::Hold => (0..=index)
172                .rev()
173                .find(|at| self.frames[*at].is_some())
174                .unwrap_or(0),
175            MissingFrames::Blank | MissingFrames::Reject => index,
176        };
177        (index, start, end, shown)
178    }
179
180    fn keep(&mut self, index: usize, decoded: Arc<Decoded>) {
181        self.kept_bytes += decoded.bytes();
182        self.kept.push_back((index, decoded));
183        while self.kept.len() > 1 && self.kept_bytes > self.budget {
184            if let Some((_, oldest)) = self.kept.pop_front() {
185                self.kept_bytes -= oldest.bytes();
186            }
187        }
188    }
189
190    fn decoded(&mut self, index: usize) -> Result<Arc<Decoded>, ExtensionError> {
191        if let Some((_, decoded)) = self.kept.iter().find(|(kept, _)| *kept == index) {
192            return Ok(Arc::clone(decoded));
193        }
194        let (width, height) = (self.report.width, self.report.height);
195        let decoded = if let Some(locator) = &self.frames[index] {
196            let decoded = decode(
197                &self.resolver.bytes(locator)?,
198                self.report.color.as_ref(),
199                None,
200            )?;
201            if decoded.format != self.report.format {
202                return Err(ExtensionError::Mismatch(format!(
203                    "frame {index} is not in the first frame's format"
204                )));
205            }
206            if (decoded.width, decoded.height) != (width, height) {
207                return Err(ExtensionError::Mismatch(format!(
208                    "frame {index} is {}x{}; the sequence is {width}x{height}",
209                    decoded.width, decoded.height
210                )));
211            }
212            decoded
213        } else {
214            let samples = width as usize * height as usize * 4;
215            Decoded {
216                format: self.report.format,
217                width,
218                height,
219                pixels: if self.report.color.is_some() {
220                    FramePixels::LinearF16(vec![0; samples].into())
221                } else {
222                    FramePixels::Rgba8(vec![0; samples].into())
223                },
224                color: self.report.color.clone(),
225                diagnostics: Vec::new(),
226            }
227        };
228        let decoded = Arc::new(decoded);
229        self.keep(index, Arc::clone(&decoded));
230        Ok(decoded)
231    }
232}
233
234impl VisualSource for SequenceSource {
235    fn report(&self) -> &ProbeReport {
236        &self.report
237    }
238
239    fn render(&mut self, time: MediaTime, _fit: (u32, u32)) -> Result<VisualFrame, ExtensionError> {
240        let (index, start, end, shown) = self.shown(time);
241        let decoded = self.decoded(shown)?;
242        Ok(VisualFrame {
243            width: self.report.width,
244            height: self.report.height,
245            pixels: decoded.pixels.clone(),
246            index,
247            start,
248            end,
249            diagnostics: decoded.diagnostics.clone(),
250        })
251    }
252
253    fn needs(&self, time: MediaTime) -> Vec<String> {
254        let (.., shown) = self.shown(time);
255        if self.kept.iter().any(|(kept, _)| *kept == shown) {
256            return Vec::new();
257        }
258        self.frames[shown].iter().cloned().collect()
259    }
260
261    fn resident_bytes(&self) -> usize {
262        self.kept_bytes
263    }
264}