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}