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}