1use std::sync::Arc;
7use std::sync::atomic::{AtomicBool, Ordering};
8use std::{error::Error, fmt};
9
10use alpha2_time::{FrameRate, MediaTime};
11
12use crate::{ColorMetadata, SourceId};
13
14#[derive(Copy, Clone, Debug, Eq, PartialEq)]
16pub struct Rect {
17 pub x: u32,
19 pub y: u32,
21 pub width: u32,
23 pub height: u32,
25}
26
27#[derive(Copy, Clone, Debug, Default, Eq, Hash, PartialEq)]
32pub enum Rotation {
33 #[default]
35 Deg0,
36 Deg90,
38 Deg180,
40 Deg270,
42}
43
44impl Rotation {
45 #[must_use]
47 pub const fn quarter_turns(self) -> u32 {
48 match self {
49 Self::Deg0 => 0,
50 Self::Deg90 => 1,
51 Self::Deg180 => 2,
52 Self::Deg270 => 3,
53 }
54 }
55
56 #[must_use]
58 pub const fn from_quarter_turns(quarter_turns: i32) -> Self {
59 match quarter_turns.rem_euclid(4) {
60 0 => Self::Deg0,
61 1 => Self::Deg90,
62 2 => Self::Deg180,
63 _ => Self::Deg270,
64 }
65 }
66
67 #[must_use]
69 pub const fn swaps_axes(self) -> bool {
70 matches!(self, Self::Deg90 | Self::Deg270)
71 }
72}
73
74#[derive(Copy, Clone, Debug, Default, Eq, Hash, PartialEq)]
81pub struct Orientation {
82 pub rotation: Rotation,
84 pub mirror: bool,
86}
87
88impl Orientation {
89 pub const UPRIGHT: Self = Self {
91 rotation: Rotation::Deg0,
92 mirror: false,
93 };
94
95 #[must_use]
97 pub const fn rotated(rotation: Rotation) -> Self {
98 Self {
99 rotation,
100 mirror: false,
101 }
102 }
103
104 #[must_use]
106 pub const fn from_exif(value: u16) -> Option<Self> {
107 let (rotation, mirror) = match value {
108 1 => (Rotation::Deg0, false),
109 2 => (Rotation::Deg0, true),
110 3 => (Rotation::Deg180, false),
111 4 => (Rotation::Deg180, true),
112 5 => (Rotation::Deg270, true),
113 6 => (Rotation::Deg90, false),
114 7 => (Rotation::Deg90, true),
115 8 => (Rotation::Deg270, false),
116 _ => return None,
117 };
118 Some(Self { rotation, mirror })
119 }
120
121 #[must_use]
123 pub const fn is_upright(self) -> bool {
124 matches!(self.rotation, Rotation::Deg0) && !self.mirror
125 }
126
127 #[must_use]
129 pub const fn displayed_size(self, width: u32, height: u32) -> (u32, u32) {
130 if self.rotation.swaps_axes() {
131 (height, width)
132 } else {
133 (width, height)
134 }
135 }
136}
137
138#[derive(Copy, Clone, Debug, Eq, PartialEq)]
140pub struct SampleAspectRatio {
141 pub num: u32,
143 pub den: u32,
145}
146
147impl Default for SampleAspectRatio {
148 fn default() -> Self {
149 Self { num: 1, den: 1 }
150 }
151}
152
153impl SampleAspectRatio {
154 #[must_use]
157 pub fn new(num: u64, den: u64) -> Option<Self> {
158 if num == 0 || den == 0 {
159 return None;
160 }
161 let divisor = greatest_common_divisor(num, den);
162 Some(Self {
163 num: u32::try_from(num / divisor).ok()?,
164 den: u32::try_from(den / divisor).ok()?,
165 })
166 }
167
168 #[must_use]
175 pub fn of_display(visible: (u32, u32), displayed: (u32, u32)) -> Option<Self> {
176 let [
177 visible_width,
178 visible_height,
179 displayed_width,
180 displayed_height,
181 ] = [visible.0, visible.1, displayed.0, displayed.1].map(u128::from);
182 if visible_width == 0
183 || visible_height == 0
184 || displayed_width == 0
185 || displayed_height == 0
186 {
187 return None;
188 }
189 let slack = |shown: u128, stored: u128| u128::from(shown != stored);
191 let width_slack = slack(displayed_width, visible_width);
192 let height_slack = slack(displayed_height, visible_height);
193 let low = (
196 (2 * displayed_width - width_slack) * visible_height,
197 (2 * displayed_height + height_slack) * visible_width,
198 );
199 let high = (
200 (2 * displayed_width + width_slack) * visible_height,
201 (2 * displayed_height - height_slack) * visible_width,
202 );
203 let (num, den) = simplest_fraction_between(low, high)?;
204 Self::new(u64::try_from(num).ok()?, u64::try_from(den).ok()?)
205 }
206
207 #[must_use]
210 pub fn square_pixel_size(self, width: u32, height: u32) -> (u32, u32) {
211 let stretch = |side: u32, by: u32, of: u32| {
212 let scaled =
213 (u64::from(side) * u64::from(by) * 2 + u64::from(of)) / (2 * u64::from(of));
214 u32::try_from(scaled).unwrap_or(u32::MAX)
215 };
216 if self.num == 0 || self.den == 0 {
217 return (width, height);
218 }
219 match self.num.cmp(&self.den) {
220 std::cmp::Ordering::Greater => (stretch(width, self.num, self.den), height),
221 std::cmp::Ordering::Less => (width, stretch(height, self.den, self.num)),
222 std::cmp::Ordering::Equal => (width, height),
223 }
224 }
225}
226
227fn simplest_fraction_between(low: (u128, u128), high: (u128, u128)) -> Option<(u128, u128)> {
229 let ((low_num, low_den), (high_num, high_den)) = (low, high);
230 if low_den == 0 || high_den == 0 || low_num * high_den > high_num * low_den {
231 return None;
232 }
233 let whole = low_num / low_den;
234 if whole * low_den == low_num {
235 return Some((whole, 1));
236 }
237 if (whole + 1) * high_den <= high_num {
238 return Some((whole + 1, 1));
239 }
240 let (num, den) = simplest_fraction_between(
243 (high_den, high_num - whole * high_den),
244 (low_den, low_num - whole * low_den),
245 )?;
246 Some((whole * num + den, num))
247}
248
249fn greatest_common_divisor(mut a: u64, mut b: u64) -> u64 {
250 while b != 0 {
251 (a, b) = (b, a % b);
252 }
253 a
254}
255
256#[derive(Copy, Clone, Debug, Eq, PartialEq)]
262#[non_exhaustive]
263pub enum PixelFormat {
264 Yuv(YuvFormat),
266 Rgba8,
268 LinearRgbaF16,
272}
273
274#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
281pub struct YuvFormat {
282 pub chroma_shift_x: u8,
284 pub chroma_shift_y: u8,
286 pub bit_depth: u8,
288 pub interleaved_chroma: bool,
290 pub msb_aligned: bool,
293 pub alpha: bool,
295}
296
297impl YuvFormat {
298 pub const I420: Self = Self::planar(1, 1, 8);
300 pub const NV12: Self = Self {
302 interleaved_chroma: true,
303 ..Self::I420
304 };
305 pub const P010: Self = Self {
307 bit_depth: 10,
308 msb_aligned: true,
309 ..Self::NV12
310 };
311
312 #[must_use]
314 pub const fn planar(chroma_shift_x: u8, chroma_shift_y: u8, bit_depth: u8) -> Self {
315 Self {
316 chroma_shift_x,
317 chroma_shift_y,
318 bit_depth,
319 interleaved_chroma: false,
320 msb_aligned: false,
321 alpha: false,
322 }
323 }
324
325 #[must_use]
327 pub const fn with_alpha(self) -> Self {
328 Self {
329 alpha: true,
330 ..self
331 }
332 }
333
334 #[must_use]
337 pub const fn is_supported(self) -> bool {
338 self.bit_depth >= 8
339 && self.bit_depth <= 16
340 && self.chroma_shift_x <= 2
341 && self.chroma_shift_y <= 2
342 && (!self.msb_aligned || self.bit_depth > 8)
343 }
344
345 #[must_use]
347 pub const fn bytes_per_sample(self) -> u32 {
348 if self.bit_depth > 8 { 2 } else { 1 }
349 }
350
351 #[must_use]
353 pub const fn plane_count(self) -> usize {
354 self.color_plane_count() + if self.alpha { 1 } else { 0 }
355 }
356
357 #[must_use]
359 pub const fn color_plane_count(self) -> usize {
360 if self.interleaved_chroma { 2 } else { 3 }
361 }
362
363 #[must_use]
365 pub const fn chroma_size(self, width: u32, height: u32) -> (u32, u32) {
366 (
367 width.div_ceil(1 << self.chroma_shift_x),
368 height.div_ceil(1 << self.chroma_shift_y),
369 )
370 }
371}
372
373#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
375pub enum ChromaLocation {
376 #[default]
378 Unspecified,
379 Left,
381 Center,
383 TopLeft,
385}
386
387impl ChromaLocation {
388 #[must_use]
392 pub const fn resolved_for(self, format: YuvFormat) -> Self {
393 match self {
394 Self::Unspecified if format.chroma_shift_x > 0 && format.chroma_shift_y == 0 => {
395 Self::Left
396 }
397 other => other,
398 }
399 }
400}
401
402#[derive(Clone, Debug, Eq, PartialEq)]
406pub struct Plane {
407 pub bytes: bytes::Bytes,
409 pub stride: u32,
411 pub width: u32,
413 pub height: u32,
415}
416
417pub const MAX_FRAME_DIMENSION: u32 = 16_384;
419pub const MAX_FRAME_PIXELS: u64 = 67_108_864;
421
422#[must_use]
425pub const fn frame_size_supported(width: u32, height: u32) -> bool {
426 width <= MAX_FRAME_DIMENSION
427 && height <= MAX_FRAME_DIMENSION
428 && (width as u64) * (height as u64) <= MAX_FRAME_PIXELS
429}
430
431#[derive(Clone, Debug, PartialEq)]
433pub struct DecodedVideoFrame {
434 pub pts: MediaTime,
436 pub dts: Option<MediaTime>,
438 pub duration: Option<MediaTime>,
440 pub visible_rect: Rect,
442 pub sample_aspect_ratio: SampleAspectRatio,
444 pub orientation: Orientation,
446 pub pixel_format: PixelFormat,
448 pub chroma_location: ChromaLocation,
450 pub color: Option<ColorMetadata>,
453 pub planes: Vec<Plane>,
455}
456
457pub const MAX_AUDIO_CHANNELS: usize = 24;
460
461#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
466pub enum Speaker {
467 FrontLeft,
469 FrontRight,
471 FrontCenter,
473 LowFrequency,
475 BackLeft,
477 BackRight,
479 FrontLeftOfCenter,
481 FrontRightOfCenter,
483 BackCenter,
485 SideLeft,
487 SideRight,
489 TopCenter,
491 TopFrontLeft,
493 TopFrontCenter,
495 TopFrontRight,
497 TopBackLeft,
499 TopBackCenter,
501 TopBackRight,
503 DownmixLeft,
505 DownmixRight,
507 WideLeft,
509 WideRight,
511 SurroundDirectLeft,
513 SurroundDirectRight,
515 LowFrequency2,
517 TopSideLeft,
519 TopSideRight,
521 BottomFrontCenter,
523 BottomFrontLeft,
525 BottomFrontRight,
527 SideSurroundLeft,
529 SideSurroundRight,
531 TopSurroundLeft,
533 TopSurroundRight,
535 BinauralLeft,
537 BinauralRight,
539 Unnamed,
542}
543
544impl Speaker {
545 const TABLE: [(Self, &'static str, u32); 37] = [
548 (Self::FrontLeft, "FL", 0),
549 (Self::FrontRight, "FR", 1),
550 (Self::FrontCenter, "FC", 2),
551 (Self::LowFrequency, "LFE", 3),
552 (Self::BackLeft, "BL", 4),
553 (Self::BackRight, "BR", 5),
554 (Self::FrontLeftOfCenter, "FLC", 6),
555 (Self::FrontRightOfCenter, "FRC", 7),
556 (Self::BackCenter, "BC", 8),
557 (Self::SideLeft, "SL", 9),
558 (Self::SideRight, "SR", 10),
559 (Self::TopCenter, "TC", 11),
560 (Self::TopFrontLeft, "TFL", 12),
561 (Self::TopFrontCenter, "TFC", 13),
562 (Self::TopFrontRight, "TFR", 14),
563 (Self::TopBackLeft, "TBL", 15),
564 (Self::TopBackCenter, "TBC", 16),
565 (Self::TopBackRight, "TBR", 17),
566 (Self::DownmixLeft, "DL", 29),
567 (Self::DownmixRight, "DR", 30),
568 (Self::WideLeft, "WL", 31),
569 (Self::WideRight, "WR", 32),
570 (Self::SurroundDirectLeft, "SDL", 33),
571 (Self::SurroundDirectRight, "SDR", 34),
572 (Self::LowFrequency2, "LFE2", 35),
573 (Self::TopSideLeft, "TSL", 36),
574 (Self::TopSideRight, "TSR", 37),
575 (Self::BottomFrontCenter, "BFC", 38),
576 (Self::BottomFrontLeft, "BFL", 39),
577 (Self::BottomFrontRight, "BFR", 40),
578 (Self::SideSurroundLeft, "SSL", 41),
579 (Self::SideSurroundRight, "SSR", 42),
580 (Self::TopSurroundLeft, "TTL", 43),
581 (Self::TopSurroundRight, "TTR", 44),
582 (Self::BinauralLeft, "BIL", 61),
583 (Self::BinauralRight, "BIR", 62),
584 (Self::Unnamed, "UNK", 0x300),
585 ];
586
587 #[must_use]
589 pub fn name(self) -> &'static str {
590 Self::TABLE
591 .iter()
592 .find(|(speaker, _, _)| *speaker == self)
593 .map_or("UNK", |(_, name, _)| name)
594 }
595
596 #[must_use]
598 pub fn from_name(name: &str) -> Option<Self> {
599 Self::TABLE
600 .iter()
601 .find(|(_, known, _)| *known == name)
602 .map(|(speaker, _, _)| *speaker)
603 }
604
605 #[must_use]
607 pub fn ffmpeg_channel(self) -> u32 {
608 Self::TABLE
609 .iter()
610 .find(|(speaker, _, _)| *speaker == self)
611 .map_or(0x300, |(_, _, channel)| *channel)
612 }
613
614 #[must_use]
617 pub fn from_ffmpeg_channel(channel: i64) -> Self {
618 Self::TABLE
619 .iter()
620 .find(|(_, _, number)| i64::from(*number) == channel)
621 .map_or(Self::Unnamed, |(speaker, _, _)| *speaker)
622 }
623}
624
625#[derive(Copy, Clone, Eq, Hash, PartialEq)]
630pub struct SpeakerLayout {
631 speakers: [Speaker; MAX_AUDIO_CHANNELS],
632 count: u8,
633}
634
635impl std::fmt::Debug for SpeakerLayout {
636 fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
637 formatter
638 .debug_list()
639 .entries(self.speakers().iter().map(|speaker| speaker.name()))
640 .finish()
641 }
642}
643
644impl SpeakerLayout {
645 pub const MONO: Self = Self::fixed(&[Speaker::FrontCenter]);
647 pub const STEREO: Self = Self::fixed(&[Speaker::FrontLeft, Speaker::FrontRight]);
649
650 const fn fixed(speakers: &[Speaker]) -> Self {
651 let mut layout = [Speaker::Unnamed; MAX_AUDIO_CHANNELS];
652 let mut index = 0;
653 while index < speakers.len() {
654 layout[index] = speakers[index];
655 index += 1;
656 }
657 #[allow(clippy::cast_possible_truncation)]
658 Self {
659 speakers: layout,
660 count: speakers.len() as u8,
661 }
662 }
663
664 #[must_use]
667 pub fn new(speakers: &[Speaker]) -> Option<Self> {
668 if speakers.is_empty() || speakers.len() > MAX_AUDIO_CHANNELS {
669 return None;
670 }
671 let mut layout = Self {
672 speakers: [Speaker::Unnamed; MAX_AUDIO_CHANNELS],
673 count: u8::try_from(speakers.len()).ok()?,
674 };
675 layout.speakers[..speakers.len()].copy_from_slice(speakers);
676 Some(layout)
677 }
678
679 #[must_use]
684 pub fn default_for(channels: usize) -> Option<Self> {
685 const SEVEN_ONE: u64 = 0x63f;
687 let mask: u64 = match channels {
688 1 => 0x4,
689 2 => 0x3,
690 3 => 0xb,
691 4 => 0x107,
692 5 => 0x37,
693 6 => 0x3f,
694 7 => 0x70f,
695 10 => 0x2_d60f,
696 12 => 0x2_d63f,
697 14 => 0x2_d6ff,
698 16 => 0x30_0002_d6ff,
699 24 => 0x1f8_0003_ffff,
700 8..=MAX_AUDIO_CHANNELS => SEVEN_ONE,
701 _ => return None,
702 };
703 let mut layout = Self::of_mask(mask)?;
704 layout.count = u8::try_from(channels).ok()?;
706 Some(layout)
707 }
708
709 fn of_mask(mask: u64) -> Option<Self> {
711 let speakers = (0..64_i64)
712 .filter(|bit| mask & (1 << bit) != 0)
713 .map(Speaker::from_ffmpeg_channel)
714 .collect::<Vec<_>>();
715 Self::new(&speakers)
716 }
717
718 #[must_use]
721 pub fn declared_or_default(speakers: &[Speaker]) -> Option<(Self, bool)> {
722 if speakers.iter().all(|speaker| *speaker == Speaker::Unnamed) {
723 return Self::default_for(speakers.len()).map(|layout| (layout, true));
724 }
725 Self::new(speakers).map(|layout| (layout, false))
726 }
727
728 #[must_use]
730 pub fn speakers(&self) -> &[Speaker] {
731 &self.speakers[..usize::from(self.count)]
732 }
733
734 #[must_use]
736 pub fn channels(&self) -> usize {
737 usize::from(self.count)
738 }
739
740 #[must_use]
743 pub fn describe(&self) -> String {
744 self.speakers()
745 .iter()
746 .map(|speaker| speaker.name())
747 .collect::<Vec<_>>()
748 .join("+")
749 }
750}
751
752#[derive(Clone, Debug, PartialEq)]
761pub struct AudioBlock {
762 pub start_sample: i64,
764 pub sample_rate: u32,
766 pub speakers: SpeakerLayout,
768 pub channels: Vec<Vec<f32>>,
770}
771
772impl AudioBlock {
773 #[must_use]
775 pub fn frames(&self) -> usize {
776 self.channels.first().map_or(0, Vec::len)
777 }
778
779 #[must_use]
781 pub fn end_sample(&self) -> i64 {
782 self.start_sample
783 .saturating_add(i64::try_from(self.frames()).unwrap_or(i64::MAX))
784 }
785
786 #[must_use]
788 pub fn start_time(&self) -> MediaTime {
789 MediaTime::from_ticks(sample_ticks_floor(self.start_sample, self.sample_rate))
790 }
791}
792
793#[must_use]
795pub fn sample_ticks_floor(sample: i64, sample_rate: u32) -> i64 {
796 let ticks = (i128::from(sample) * i128::from(alpha2_time::TICKS_PER_SECOND))
797 .div_euclid(i128::from(sample_rate.max(1)));
798 i64::try_from(ticks).unwrap_or(if ticks < 0 { i64::MIN } else { i64::MAX })
799}
800
801#[derive(Copy, Clone, Debug, Eq, PartialEq)]
803pub enum RasterColorSpace {
804 Srgb,
806 LinearSrgb,
808}
809
810#[derive(Copy, Clone, Debug, Eq, PartialEq)]
812pub enum Premultiplication {
813 Premultiplied,
815 Straight,
817 Opaque,
819}
820
821#[derive(Clone, Debug, Eq, PartialEq)]
823pub struct HostTexture {
824 pub content_version: u64,
826 pub width: u32,
828 pub height: u32,
830 pub premultiplication: Premultiplication,
832 pub color_space: RasterColorSpace,
834}
835
836#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
838pub enum TextAlign {
839 #[default]
841 Start,
842 Center,
844 End,
846}
847
848#[derive(Copy, Clone, Debug, Default, Eq, PartialEq)]
850pub enum EmojiPolicy {
851 #[default]
854 Color,
855 Monochrome,
858 Replace,
861}
862
863#[derive(Clone, Debug, PartialEq)]
868pub struct TextTexture {
869 pub texture: HostTexture,
871 pub layout_x: f32,
874 pub layout_y: f32,
876 pub layout_width: f32,
878 pub layout_height: f32,
880 pub first_baseline: f32,
882 pub ascent: f32,
884 pub descent: f32,
886 pub line_count: u32,
888}
889
890impl TextTexture {
891 #[must_use]
893 pub fn is_valid(&self) -> bool {
894 self.texture.width > 0
895 && self.texture.height > 0
896 && self.line_count > 0
897 && [
898 self.layout_x,
899 self.layout_y,
900 self.layout_width,
901 self.layout_height,
902 self.first_baseline,
903 self.ascent,
904 self.descent,
905 ]
906 .into_iter()
907 .all(|value| value.is_finite() && value >= 0.0)
908 && self.first_baseline <= self.layout_height
909 && f64::from(self.layout_x) + f64::from(self.layout_width)
910 <= f64::from(self.texture.width)
911 && f64::from(self.layout_y) + f64::from(self.layout_height)
912 <= f64::from(self.texture.height)
913 }
914}
915
916#[derive(Clone, Debug, PartialEq)]
918pub struct HostTexturePixels {
919 pub texture: HostTexture,
921 pub rgba8: Vec<u8>,
923}
924
925impl HostTexturePixels {
926 #[must_use]
928 pub fn is_valid(&self) -> bool {
929 usize::try_from(self.texture.width)
930 .ok()
931 .and_then(|width| {
932 usize::try_from(self.texture.height)
933 .ok()
934 .and_then(|height| width.checked_mul(height))
935 })
936 .and_then(|pixels| pixels.checked_mul(4))
937 == Some(self.rgba8.len())
938 }
939}
940
941#[derive(Copy, Clone, Debug, Eq, PartialEq)]
943pub enum StreamKind {
944 Video,
946 Audio,
948}
949
950#[derive(Clone, Debug, PartialEq)]
952pub struct StreamInfo {
953 pub index: usize,
955 pub kind: StreamKind,
957 pub codec: String,
959 pub duration: Option<MediaTime>,
961 pub dimensions: Option<(u32, u32)>,
963 pub frame_rate: Option<FrameRate>,
965 pub sample_rate: Option<u32>,
967 pub channels: Option<u32>,
969 pub orientation: Orientation,
971 pub sample_aspect_ratio: SampleAspectRatio,
973 pub color: Option<ColorMetadata>,
975 pub frame_bytes: Option<u64>,
978 pub alpha: Option<SourceAlpha>,
980 pub language: Option<String>,
982 pub title: Option<String>,
984}
985
986#[derive(Copy, Clone, Debug, Eq, PartialEq)]
988pub enum SourceAlpha {
989 Vp9SideData,
992 HevcAuxiliaryLayer,
995 Planar,
997}
998
999impl SourceAlpha {
1000 #[must_use]
1002 pub const fn as_str(self) -> &'static str {
1003 match self {
1004 Self::Vp9SideData => "vp9-side-data",
1005 Self::HevcAuxiliaryLayer => "hevc-auxiliary-layer",
1006 Self::Planar => "planar",
1007 }
1008 }
1009}
1010
1011#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1013pub enum DecodeRequestKind {
1014 Prefetch,
1016 Seek,
1018 Evicted,
1020 DeviceRecovery,
1022}
1023
1024#[derive(Clone, Debug, Eq, PartialEq)]
1026pub struct DecodeRequest {
1027 pub source: SourceId,
1029 pub time: MediaTime,
1031 pub kind: DecodeRequestKind,
1033 pub generation: u64,
1035}
1036
1037#[derive(Clone, Debug, PartialEq)]
1039pub struct DecodeResult {
1040 pub request: DecodeRequest,
1042 pub event: DecodeEvent,
1044}
1045
1046#[derive(Clone, Debug, PartialEq)]
1048pub enum DecodeEvent {
1049 Video(DecodedVideoFrame),
1051 Audio(AudioBlock),
1053 Retry,
1055 EndOfStream,
1057}
1058
1059#[derive(Clone, Debug, Default)]
1061pub struct CancelToken(Arc<AtomicBool>);
1062
1063impl CancelToken {
1064 pub fn cancel(&self) {
1066 self.0.store(true, Ordering::Release);
1067 }
1068
1069 #[must_use]
1071 pub fn is_cancelled(&self) -> bool {
1072 self.0.load(Ordering::Acquire)
1073 }
1074}
1075
1076pub const GPU_TIMEOUT_MESSAGE: &str = "GPU work did not complete within the wait timeout";
1079
1080#[derive(Copy, Clone, Debug, Eq, PartialEq)]
1083#[non_exhaustive]
1084pub enum GpuFault {
1085 DeviceLost,
1087 DeviceHung,
1089 DeviceMemory,
1091 HostMemory,
1093 Timeout,
1095}
1096
1097impl GpuFault {
1098 #[must_use]
1100 pub const fn as_str(self) -> &'static str {
1101 match self {
1102 Self::DeviceLost => "device-lost",
1103 Self::DeviceHung => "device-hung",
1104 Self::DeviceMemory => "device-memory",
1105 Self::HostMemory => "host-memory",
1106 Self::Timeout => "timeout",
1107 }
1108 }
1109}
1110
1111#[derive(Clone, Debug, Eq, PartialEq)]
1116#[non_exhaustive]
1117pub enum DecodeError {
1118 Cancelled,
1120 OutOfRange,
1122 Unsupported(String),
1124 Adapter(String),
1126 Gpu {
1128 fault: GpuFault,
1130 message: String,
1132 },
1133}
1134
1135#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
1137pub enum OpenFailureKind {
1138 Absent,
1140 Busy,
1143 Unsuitable,
1145 Unknown,
1147}
1148
1149impl OpenFailureKind {
1150 #[must_use]
1152 pub const fn as_str(self) -> &'static str {
1153 match self {
1154 Self::Absent => "absent",
1155 Self::Busy => "busy",
1156 Self::Unsuitable => "unsuitable",
1157 Self::Unknown => "unknown",
1158 }
1159 }
1160}
1161
1162#[derive(Clone, Debug, Eq, PartialEq)]
1164pub struct EncoderRefusal {
1165 pub encoder: String,
1167 pub hardware_accelerated: bool,
1169 pub kind: OpenFailureKind,
1171 pub reason: String,
1173}
1174
1175impl DecodeError {
1176 #[must_use]
1178 pub const fn is_fatal(&self) -> bool {
1179 matches!(
1180 self,
1181 Self::Unsupported(_) | Self::Adapter(_) | Self::Gpu { .. }
1182 )
1183 }
1184}
1185
1186impl fmt::Display for DecodeError {
1187 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1188 match self {
1189 Self::Cancelled => formatter.write_str("decode was cancelled"),
1190 Self::OutOfRange => formatter.write_str("decode request is out of range"),
1191 Self::Unsupported(message) => write!(formatter, "unsupported media: {message}"),
1192 Self::Adapter(message) | Self::Gpu { message, .. } => {
1193 write!(formatter, "decoder adapter failed: {message}")
1194 }
1195 }
1196 }
1197}
1198
1199impl Error for DecodeError {}
1200
1201pub trait Decoder {
1203 fn streams(&self) -> &[StreamInfo];
1205 fn flush(&mut self) -> Result<(), DecodeError>;
1210 fn seek(
1222 &mut self,
1223 request: DecodeRequest,
1224 cancel: &CancelToken,
1225 ) -> Result<DecodeResult, DecodeError>;
1226 fn decode_next(&mut self, cancel: &CancelToken) -> Result<DecodeEvent, DecodeError>;
1231}
1232
1233#[derive(Clone, Copy, Debug, PartialEq)]
1235pub struct AudioSpan<'a> {
1236 pub block: &'a AudioBlock,
1238 pub starts_source: bool,
1240 pub ends_source: bool,
1242}
1243
1244impl<'a> AudioSpan<'a> {
1245 #[must_use]
1247 pub const fn whole(block: &'a AudioBlock) -> Self {
1248 Self {
1249 block,
1250 starts_source: true,
1251 ends_source: true,
1252 }
1253 }
1254
1255 #[must_use]
1258 pub fn covers(&self, start: i64, end: i64) -> bool {
1259 (self.starts_source || self.block.start_sample <= start)
1260 && (self.ends_source || self.block.end_sample() >= end)
1261 }
1262}
1263
1264pub trait AudioBlockProvider {
1266 fn block(
1277 &self,
1278 source: &SourceId,
1279 stream: Option<u32>,
1280 start_sample: i64,
1281 frames: usize,
1282 ) -> Option<AudioSpan<'_>>;
1283}
1284
1285pub trait AudioBlockSink {
1287 fn write_audio(&mut self, block: &AudioBlock, cancel: &CancelToken) -> Result<(), EncodeError>;
1293
1294 fn finish_audio(&mut self, cancel: &CancelToken) -> Result<(), EncodeError>;
1300
1301 fn abort_audio(&mut self) -> Result<(), EncodeError>;
1306}
1307
1308#[derive(Clone, Debug, PartialEq)]
1310pub enum EncodeEvent {
1311 Video(DecodedVideoFrame),
1313 Audio(AudioBlock),
1315}
1316
1317#[derive(Clone, Debug, Eq, PartialEq)]
1319#[non_exhaustive]
1320pub enum EncodeError {
1321 Cancelled,
1323 InvalidTimestamp,
1325 Adapter(String),
1327 Output(String),
1329 OutputInUse(String),
1332 Publish {
1335 message: String,
1337 kept: Option<std::path::PathBuf>,
1339 },
1340 EncoderRejected {
1342 encoder: String,
1344 frame: u64,
1346 message: String,
1348 },
1349 Gpu {
1351 fault: GpuFault,
1353 message: String,
1355 },
1356 EncodersRefused {
1358 message: String,
1360 refusals: Vec<EncoderRefusal>,
1362 },
1363}
1364
1365impl EncodeError {
1366 #[must_use]
1368 pub fn gpu_timeout(what: impl fmt::Display) -> Self {
1369 Self::Gpu {
1370 fault: GpuFault::Timeout,
1371 message: format!("{what}: {GPU_TIMEOUT_MESSAGE}"),
1372 }
1373 }
1374}
1375
1376impl fmt::Display for EncodeError {
1377 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1378 match self {
1379 Self::Cancelled => formatter.write_str("encode was cancelled"),
1380 Self::InvalidTimestamp => formatter.write_str("encode timestamp is invalid"),
1381 Self::Adapter(message)
1382 | Self::Gpu { message, .. }
1383 | Self::EncodersRefused { message, .. } => {
1384 write!(formatter, "encoder adapter failed: {message}")
1385 }
1386 Self::EncoderRejected { message, .. } => formatter.write_str(message),
1387 Self::Output(message) | Self::OutputInUse(message) => {
1388 write!(formatter, "cannot create the output: {message}")
1389 }
1390 Self::Publish {
1391 message,
1392 kept: Some(kept),
1393 } => write!(
1394 formatter,
1395 "cannot publish the output: {message}; the finished render is kept at {}",
1396 kept.display()
1397 ),
1398 Self::Publish {
1399 message,
1400 kept: None,
1401 } => write!(
1402 formatter,
1403 "cannot publish the output: {message}; the finished render could not be kept"
1404 ),
1405 }
1406 }
1407}
1408
1409impl Error for EncodeError {}
1410
1411pub trait EncodeSink {
1413 fn write(&mut self, event: EncodeEvent, cancel: &CancelToken) -> Result<(), EncodeError>;
1418 fn finish(&mut self, cancel: &CancelToken) -> Result<(), EncodeError>;
1423 fn abort(&mut self) -> Result<(), EncodeError>;
1428}
1429
1430#[cfg(test)]
1431mod tests {
1432 use super::SampleAspectRatio;
1433
1434 #[test]
1435 fn a_pixel_aspect_ratio_is_kept_in_lowest_terms_and_shows_as_a_browser_shows_it() {
1436 let ratio = |num, den| SampleAspectRatio { num, den };
1437 assert_eq!(SampleAspectRatio::new(8, 6), Some(ratio(4, 3)));
1438 assert_eq!(SampleAspectRatio::new(0, 1), None);
1439 assert_eq!(SampleAspectRatio::new(1, 0), None);
1440 assert_eq!(SampleAspectRatio::new(u64::from(u32::MAX) + 1, 1), None);
1441 let shown = |visible, displayed| SampleAspectRatio::of_display(visible, displayed);
1443 assert_eq!(shown((128, 96), (171, 96)), Some(ratio(4, 3)));
1444 assert_eq!(shown((96, 128), (96, 171)), Some(ratio(3, 4)));
1445 assert_eq!(shown((720, 576), (1024, 576)), Some(ratio(64, 45)));
1446 assert_eq!(shown((720, 480), (655, 480)), Some(ratio(10, 11)));
1447 assert_eq!(shown((720, 480), (720, 524)), Some(ratio(11, 12)));
1448 assert_eq!(shown((1440, 1080), (1920, 1080)), Some(ratio(4, 3)));
1449 assert_eq!(shown((128, 96), (128, 96)), Some(ratio(1, 1)));
1450 for (visible, displayed) in [
1452 ((128, 96), (170, 96)),
1453 ((1000, 999), (1777, 999)),
1454 ((3, 2), (5, 2)),
1455 ] {
1456 let found = shown(visible, displayed).expect("a ratio");
1457 assert_eq!(
1458 found.square_pixel_size(visible.0, visible.1),
1459 displayed,
1460 "{visible:?} {displayed:?}"
1461 );
1462 }
1463 assert_eq!(shown((0, 96), (171, 96)), None);
1464 assert_eq!(ratio(4, 3).square_pixel_size(128, 96), (171, 96));
1466 assert_eq!(ratio(64, 45).square_pixel_size(720, 576), (1024, 576));
1467 assert_eq!(ratio(3, 4).square_pixel_size(96, 128), (96, 171));
1468 assert_eq!(ratio(1, 1).square_pixel_size(65, 49), (65, 49));
1469 assert_eq!(ratio(3, 2).square_pixel_size(3, 7), (5, 7));
1471 }
1472
1473 use super::*;
1474
1475 #[test]
1476 fn a_frame_size_is_bounded_on_each_side_and_in_area() {
1477 assert!(frame_size_supported(16_384, 4_096));
1478 assert!(frame_size_supported(8_192, 8_192));
1479 assert!(!frame_size_supported(8_193, 8_192));
1480 assert!(!frame_size_supported(16_385, 1));
1481 assert!(!frame_size_supported(1, 16_385));
1482 assert!(!frame_size_supported(u32::MAX, u32::MAX));
1483 }
1484
1485 #[test]
1486 fn cancellation_is_shared_and_monotonic() {
1487 let token = CancelToken::default();
1488 let other = token.clone();
1489 assert!(!other.is_cancelled());
1490 token.cancel();
1491 assert!(other.is_cancelled());
1492 }
1493
1494 #[test]
1495 fn a_layout_names_each_plane_by_ffmpegs_channel_names() {
1496 let lcr = SpeakerLayout::new(&[
1497 Speaker::FrontCenter,
1498 Speaker::FrontLeft,
1499 Speaker::FrontRight,
1500 ])
1501 .expect("layout");
1502 assert_eq!(lcr.channels(), 3);
1503 assert_eq!(lcr.describe(), "FC+FL+FR");
1504 assert_eq!(format!("{lcr:?}"), r#"["FC", "FL", "FR"]"#);
1505 for (speaker, name, channel) in Speaker::TABLE {
1506 assert_eq!(speaker.name(), name);
1507 assert_eq!(Speaker::from_name(name), Some(speaker));
1508 assert_eq!(speaker.ffmpeg_channel(), channel);
1509 assert_eq!(Speaker::from_ffmpeg_channel(i64::from(channel)), speaker);
1510 }
1511 for channel in [-1, 18, 0x200, 0x400, 0x401, 0x7ff, 1_000] {
1513 assert_eq!(Speaker::from_ffmpeg_channel(channel), Speaker::Unnamed);
1514 }
1515 assert_eq!(Speaker::from_name("front left"), None);
1516 assert!(SpeakerLayout::new(&[]).is_none());
1517 assert!(SpeakerLayout::new(&[Speaker::FrontLeft; MAX_AUDIO_CHANNELS + 1]).is_none());
1518 }
1519
1520 #[test]
1521 fn a_source_that_declares_no_speaker_has_ffmpegs_default_for_its_count() {
1522 let names = |channels| {
1523 SpeakerLayout::default_for(channels)
1524 .expect("a default")
1525 .describe()
1526 };
1527 assert_eq!(names(1), "FC");
1528 assert_eq!(names(3), "FL+FR+LFE");
1529 assert_eq!(names(4), "FL+FR+FC+BC");
1530 assert_eq!(names(8), "FL+FR+FC+LFE+BL+BR+SL+SR");
1531 assert_eq!(names(9), "FL+FR+FC+LFE+BL+BR+SL+SR+UNK");
1532 assert_eq!(names(10), "FL+FR+FC+LFE+SL+SR+TFL+TFR+TBL+TBR");
1533 assert_eq!(SpeakerLayout::default_for(24).expect("22.2").channels(), 24);
1534 assert!(SpeakerLayout::default_for(0).is_none());
1535 assert!(SpeakerLayout::default_for(MAX_AUDIO_CHANNELS + 1).is_none());
1536 let unnamed = [Speaker::Unnamed; 2];
1537 assert_eq!(
1538 SpeakerLayout::declared_or_default(&unnamed),
1539 Some((SpeakerLayout::default_for(2).expect("stereo"), true))
1540 );
1541 let partly = [Speaker::FrontCenter, Speaker::Unnamed];
1542 assert_eq!(
1543 SpeakerLayout::declared_or_default(&partly),
1544 Some((SpeakerLayout::new(&partly).expect("layout"), false))
1545 );
1546 }
1547
1548 #[test]
1549 fn a_span_covers_a_request_only_where_it_holds_samples_or_knows_silence() {
1550 let block = AudioBlock {
1551 start_sample: 100,
1552 sample_rate: 48_000,
1553 speakers: SpeakerLayout::default_for(1).expect("mono"),
1554 channels: vec![vec![0.5; 50]],
1555 };
1556 let partial = AudioSpan {
1557 block: &block,
1558 starts_source: false,
1559 ends_source: false,
1560 };
1561 assert!(partial.covers(100, 150));
1562 assert!(partial.covers(120, 130));
1563 assert!(!partial.covers(99, 150), "a sample before the block");
1564 assert!(!partial.covers(100, 151), "a sample after the block");
1565 let starts = AudioSpan {
1566 starts_source: true,
1567 ..partial
1568 };
1569 assert!(starts.covers(0, 150));
1570 assert!(!starts.covers(0, 151));
1571 assert!(AudioSpan::whole(&block).covers(-5, 1_000));
1572 }
1573
1574 #[test]
1575 fn text_descriptor_and_generic_pixels_validate_without_compositor_types() {
1576 let texture = HostTexture {
1577 content_version: 2,
1578 width: 4,
1579 height: 3,
1580 premultiplication: Premultiplication::Premultiplied,
1581 color_space: RasterColorSpace::Srgb,
1582 };
1583 let text = TextTexture {
1584 texture: texture.clone(),
1585 layout_x: 0.0,
1586 layout_y: 0.0,
1587 layout_width: 4.0,
1588 layout_height: 3.0,
1589 first_baseline: 2.0,
1590 ascent: 2.0,
1591 descent: 1.0,
1592 line_count: 1,
1593 };
1594 assert!(text.is_valid());
1595 assert!(
1596 HostTexturePixels {
1597 texture,
1598 rgba8: vec![0; 4 * 3 * 4],
1599 }
1600 .is_valid()
1601 );
1602 }
1603}