Skip to main content

alpha2_extensions/
api.rs

1//! The provider contract: probe reports, frame requests, and frames.
2
3use std::fmt;
4use std::sync::Arc;
5
6use alpha2_model::{LinearPrimaries, ProviderSource};
7use alpha2_time::{FrameRate, MediaTime};
8use serde::Serialize;
9
10/// Frame delays at or below this are shown for [`NORMALIZED_DELAY_MS`] and reported. This
11/// catches GIF delays of 0 and 1 hundredths while 60 fps (16 or 17 ms) plays as declared.
12pub const MAX_NORMALIZED_DELAY_MS: u32 = 10;
13/// What a delay of [`MAX_NORMALIZED_DELAY_MS`] or less becomes.
14pub const NORMALIZED_DELAY_MS: u32 = 100;
15
16/// A format a provider reads.
17#[derive(Copy, Clone, Debug, Eq, PartialEq, Serialize)]
18#[serde(rename_all = "snake_case")]
19#[non_exhaustive]
20pub enum Format {
21    /// A static SVG document.
22    Svg,
23    /// A GIF.
24    Gif,
25    /// An APNG.
26    Apng,
27    /// An animated WebP.
28    Webp,
29    /// A numbered PNG sequence.
30    PngSequence,
31    /// A Lottie JSON animation.
32    Lottie,
33    /// A dotLottie package of one or more Lottie animations.
34    DotLottie,
35    /// A still OpenEXR image.
36    Exr,
37    /// A numbered OpenEXR sequence.
38    ExrSequence,
39}
40
41/// When a source's frames are shown, in source time.
42#[derive(Clone, Debug, PartialEq, Serialize)]
43#[serde(tag = "kind", rename_all = "snake_case")]
44#[non_exhaustive]
45pub enum Timing {
46    /// One picture, whatever the time.
47    Static,
48    /// Frames shown for their own durations, in ticks, one after another.
49    Frames {
50        /// Each frame's duration, already normalized.
51        durations: Vec<i64>,
52    },
53    /// Frames at a fixed rate.
54    Rate {
55        /// The rate.
56        rate: FrameRate,
57        /// How many frames.
58        frames: usize,
59    },
60}
61
62impl Timing {
63    /// How long one cycle lasts, or `None` for a static picture.
64    #[must_use]
65    pub fn duration(&self) -> Option<MediaTime> {
66        match self {
67            Self::Static => None,
68            Self::Frames { durations } => Some(MediaTime::from_ticks(durations.iter().sum())),
69            Self::Rate { rate, frames } => Some(frame_start(*rate, *frames)),
70        }
71    }
72
73    /// How many frames there are.
74    #[must_use]
75    pub fn frame_count(&self) -> usize {
76        match self {
77            Self::Static => 1,
78            Self::Frames { durations } => durations.len(),
79            Self::Rate { frames, .. } => *frames,
80        }
81    }
82
83    /// The frame shown at `time` and the source time it covers. Times outside the source clamp to
84    /// the first or last frame; looping is the clip's job.
85    #[must_use]
86    pub fn frame_at(&self, time: MediaTime) -> (usize, MediaTime, Option<MediaTime>) {
87        let ticks = time.ticks();
88        match self {
89            Self::Static => (0, MediaTime::from_ticks(i64::MIN), None),
90            Self::Frames { durations } => {
91                let mut start = 0_i64;
92                for (index, duration) in durations.iter().enumerate() {
93                    let end = start + duration;
94                    if ticks < end || index + 1 == durations.len() {
95                        let first = if index == 0 { i64::MIN } else { start };
96                        let last =
97                            (index + 1 < durations.len()).then(|| MediaTime::from_ticks(end));
98                        return (index, MediaTime::from_ticks(first), last);
99                    }
100                    start = end;
101                }
102                (0, MediaTime::from_ticks(i64::MIN), None)
103            }
104            Self::Rate { rate, frames } => {
105                let index = rate
106                    .frame_at_or_before(time)
107                    .map_or(usize::MAX, |index| {
108                        usize::try_from(index.max(0)).unwrap_or(usize::MAX)
109                    })
110                    .min(frames - 1);
111                let first = if index == 0 {
112                    MediaTime::from_ticks(i64::MIN)
113                } else {
114                    frame_start(*rate, index)
115                };
116                let last = (index + 1 < *frames).then(|| frame_start(*rate, index + 1));
117                (index, first, last)
118            }
119        }
120    }
121}
122
123/// Uses the engine's [`FrameRate::frame_start`] boundary, so a source at the project's rate shows
124/// frame `k` at output frame `k`.
125fn frame_start(rate: FrameRate, index: usize) -> MediaTime {
126    i64::try_from(index)
127        .ok()
128        .and_then(|index| rate.frame_start(index))
129        .unwrap_or(MediaTime::from_ticks(i64::MAX))
130}
131
132/// Something a provider did that the user should know about.
133#[derive(Clone, Debug, Eq, PartialEq, Serialize)]
134#[serde(tag = "kind", rename_all = "snake_case")]
135#[non_exhaustive]
136pub enum Diagnostic {
137    /// A frame's delay was [`MAX_NORMALIZED_DELAY_MS`] or less and is shown for
138    /// [`NORMALIZED_DELAY_MS`].
139    NormalizedDelay {
140        /// The frame's index.
141        frame: usize,
142        /// Its declared delay, in milliseconds.
143        declared_ms: u32,
144    },
145    /// Text names a font no registered font provides; it is not drawn.
146    MissingFont {
147        /// The font families the text asks for.
148        families: String,
149    },
150    /// A referenced image is not registered or is too large; it is not drawn.
151    MissingImage {
152        /// The reference.
153        href: String,
154    },
155    /// A feature the provider does not draw; it is left out, never silently approximated.
156    UnsupportedFeature {
157        /// What it is.
158        feature: String,
159        /// Where it first appears (a JSON pointer).
160        path: String,
161        /// How many places use it.
162        count: usize,
163    },
164    /// A referenced image is registered but cannot be decoded; it is not drawn.
165    UnreadableImage {
166        /// The reference.
167        href: String,
168        /// Why it cannot be drawn.
169        reason: String,
170    },
171    /// A package item that does not open; the other items can still be chosen.
172    UnreadableItem {
173        /// The item.
174        item: String,
175        /// Why it does not open.
176        reason: String,
177    },
178    /// Samples that were NaN or infinite; each is shown as `0`.
179    NonFiniteSamples {
180        /// How many.
181        count: usize,
182    },
183    /// Finite 32-bit float samples beyond the half-float range; each is clamped to it.
184    OutOfHalfRange {
185        /// How many.
186        count: usize,
187    },
188    /// Channels stored as 32-bit floats are shown at half-float precision.
189    ReducedPrecision,
190}
191
192/// The primaries of linear-light media and where they came from.
193#[derive(Clone, Debug, PartialEq, Serialize)]
194#[non_exhaustive]
195pub struct LinearColor {
196    /// The named primaries the chromaticities are, if any.
197    pub primaries: Option<LinearPrimaries>,
198    /// The red, green, blue, and white chromaticities, CIE 1931 `[x, y]`.
199    pub chromaticities: [[f32; 2]; 4],
200    /// Where they come from.
201    pub origin: ColorOrigin,
202}
203
204/// Where a source's color description comes from.
205#[derive(Copy, Clone, Debug, Eq, PartialEq, Serialize)]
206#[serde(rename_all = "snake_case")]
207pub enum ColorOrigin {
208    /// The file declares it.
209    File,
210    /// The file does not say and the format defines a default.
211    FormatDefault,
212    /// The project says so, overriding the file.
213    Project,
214}
215
216/// What probing a file finds.
217#[derive(Clone, Debug, PartialEq, Serialize)]
218#[non_exhaustive]
219pub struct ProbeReport {
220    /// The format.
221    pub format: Format,
222    /// The canvas width, in pixels.
223    pub width: u32,
224    /// The canvas height, in pixels.
225    pub height: u32,
226    /// When its frames are shown.
227    pub timing: Timing,
228    /// Plays the file asks for (`0` for forever), or `None` if unstated. Only a hint for import.
229    pub loop_count: Option<u32>,
230    /// The items a package holds, such as a dotLottie's animations; empty for a single item.
231    pub items: Vec<String>,
232    /// The package item described: the one opened, or for a probe the first that opens. `None`
233    /// for a single item.
234    pub item: Option<String>,
235    /// The color of linear-light media; `None` for sRGB media.
236    pub color: Option<LinearColor>,
237    /// What the user should know.
238    pub diagnostics: Vec<Diagnostic>,
239}
240
241/// A frame's tightly packed pixels, in the source's precision. Shared with the source's cache,
242/// so repeated frames cost no copy.
243#[derive(Clone, Debug, PartialEq, Eq)]
244#[non_exhaustive]
245pub enum FramePixels {
246    /// Premultiplied, sRGB-encoded RGBA8.
247    Rgba8(Arc<[u8]>),
248    /// Premultiplied linear-light RGBA as IEEE 754 half-float bits, BT.709 primaries, `1.0` at
249    /// SDR white; values outside `0.0..=1.0` are kept.
250    LinearF16(Arc<[u16]>),
251}
252
253impl FramePixels {
254    /// The bytes the pixels take.
255    #[must_use]
256    pub fn byte_len(&self) -> usize {
257        match self {
258            Self::Rgba8(pixels) => pixels.len(),
259            Self::LinearF16(halves) => halves.len() * 2,
260        }
261    }
262
263    /// The RGBA8 pixels, or `None` for another precision.
264    #[must_use]
265    pub fn rgba8(&self) -> Option<&[u8]> {
266        match self {
267            Self::Rgba8(pixels) => Some(pixels),
268            Self::LinearF16(_) => None,
269        }
270    }
271
272    /// The linear half-float pixels, or `None` for another precision.
273    #[must_use]
274    pub fn linear_f16(&self) -> Option<&[u16]> {
275        match self {
276            Self::LinearF16(halves) => Some(halves),
277            Self::Rgba8(_) => None,
278        }
279    }
280}
281
282/// One frame of a source.
283#[derive(Clone, Debug, PartialEq, Eq)]
284#[non_exhaustive]
285pub struct VisualFrame {
286    /// Width in pixels.
287    pub width: u32,
288    /// Height in pixels.
289    pub height: u32,
290    /// The pixels.
291    pub pixels: FramePixels,
292    /// Which of the source's frames this is.
293    pub index: usize,
294    /// The first source time it is shown at (`i64::MIN` ticks for the first frame).
295    pub start: MediaTime,
296    /// The first source time it is no longer shown at, or `None` for the last frame.
297    pub end: Option<MediaTime>,
298    /// Per-frame diagnostics, such as non-finite samples in one frame of a sequence.
299    pub diagnostics: Vec<Diagnostic>,
300}
301
302/// Why a provider could not answer.
303#[derive(Clone, Debug, PartialEq, Eq)]
304#[non_exhaustive]
305pub enum ExtensionError {
306    /// No provider reads these bytes, or the requested provider is not in this build.
307    Unsupported(String),
308    /// The bytes are not a well-formed file of the format.
309    Malformed(String),
310    /// The file is larger than a provider opens.
311    Budget(String),
312    /// A resource the source needs is not registered.
313    MissingResource(String),
314    /// The media is not what the project says it is.
315    Mismatch(String),
316}
317
318impl fmt::Display for ExtensionError {
319    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
320        match self {
321            Self::Unsupported(message) => write!(formatter, "unsupported: {message}"),
322            Self::Malformed(message) => write!(formatter, "malformed: {message}"),
323            Self::Budget(message) => write!(formatter, "too large: {message}"),
324            Self::MissingResource(locator) => write!(formatter, "missing resource {locator}"),
325            Self::Mismatch(message) => write!(formatter, "mismatch: {message}"),
326        }
327    }
328}
329
330impl std::error::Error for ExtensionError {}
331
332/// Supplies bytes a source needs besides its own (sequence frames, SVG fonts and images).
333/// Parsers may call it from other threads, hence `Send + Sync`.
334pub trait ResourceResolver: Send + Sync {
335    /// The bytes registered under `locator`.
336    ///
337    /// # Errors
338    /// [`ExtensionError::MissingResource`] when none are registered.
339    fn bytes(&self, locator: &str) -> Result<Arc<[u8]>, ExtensionError>;
340
341    /// Every registered font file, for documents that draw text.
342    fn fonts(&self) -> Vec<Arc<[u8]>> {
343        Vec::new()
344    }
345}
346
347/// A resolver a source may keep, such as an image sequence that reads frames on demand.
348pub type SharedResolver = Arc<dyn ResourceResolver>;
349
350/// A resolver with nothing registered.
351pub struct NoResources;
352
353impl ResourceResolver for NoResources {
354    fn bytes(&self, locator: &str) -> Result<Arc<[u8]>, ExtensionError> {
355        Err(ExtensionError::MissingResource(locator.to_owned()))
356    }
357}
358
359/// A source a provider opened: asked for frames by source time.
360pub trait VisualSource: Send {
361    /// What the file is.
362    fn report(&self) -> &ProbeReport;
363
364    /// The frame shown at `time`. Vector sources rasterize to fit within `fit` (width, height),
365    /// keeping aspect; raster sources use their own size.
366    ///
367    /// # Errors
368    /// If the frame cannot be produced.
369    fn render(&mut self, time: MediaTime, fit: (u32, u32)) -> Result<VisualFrame, ExtensionError>;
370
371    /// Locators rendering at `time` will read that the source does not already hold.
372    fn needs(&self, _time: MediaTime) -> Vec<String> {
373        Vec::new()
374    }
375
376    /// Bytes the source holds between renders (cached frames, images, and file bytes).
377    fn resident_bytes(&self) -> usize;
378
379    /// Another independently positioned reader sharing this source's decoded data and frame
380    /// budget. `None` when any time is equally cheap to draw, so the host can share the source.
381    fn reader(&self) -> Option<Box<dyn VisualSource>> {
382        None
383    }
384
385    /// The part of [`Self::resident_bytes`] shared with [`Self::reader`] readers, counted once.
386    fn shared_bytes(&self) -> usize {
387        0
388    }
389}
390
391/// Reads one family of formats.
392pub trait VisualProvider: Send + Sync {
393    /// The provider's name, for diagnostics.
394    fn name(&self) -> &'static str;
395
396    /// What `bytes` are, or `None` when they are not this provider's.
397    ///
398    /// # Errors
399    /// If bytes that look like this provider's format cannot be read.
400    fn probe(&self, bytes: &[u8]) -> Option<Result<ProbeReport, ExtensionError>>;
401
402    /// Opens `bytes` as the project's `source`, applying its settings. Open runs the same
403    /// signature checks as [`Self::probe`], so callers need not probe first.
404    ///
405    /// # Errors
406    /// [`ExtensionError::Mismatch`] for bytes that are not this provider's, or why they cannot be
407    /// opened.
408    fn open(
409        &self,
410        bytes: Arc<[u8]>,
411        source: &ProviderSource,
412        resolver: &dyn ResourceResolver,
413    ) -> Result<Box<dyn VisualSource>, ExtensionError>;
414}
415
416/// Premultiplies straight RGBA8 in place, rounding to nearest.
417pub fn premultiply(pixels: &mut [u8]) {
418    for pixel in pixels.as_chunks_mut::<4>().0 {
419        let alpha = u16::from(pixel[3]);
420        if alpha == 255 {
421            continue;
422        }
423        for channel in &mut pixel[..3] {
424            *channel = u8::try_from((u16::from(*channel) * alpha + 127) / 255).unwrap_or(255);
425        }
426    }
427}