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