diff --git a/Cargo.lock b/Cargo.lock index 1d5c223cf..c462980f1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1451,6 +1451,14 @@ dependencies = [ "encoding_rs", ] +[[package]] +name = "craft-color" +version = "0.1.0" +dependencies = [ + "proptest", + "serde", +] + [[package]] name = "craft-control-protocol" version = "0.1.0" @@ -1868,6 +1876,16 @@ dependencies = [ "sha2 0.10.9", ] +[[package]] +name = "craft-frame" +version = "0.1.0" +dependencies = [ + "craft-color", + "craft-time", + "rayon", + "serde", +] + [[package]] name = "craft-gainmap" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index f1a09e32a..beec53ea3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -50,6 +50,8 @@ craft-captions = { path = "crates/captions" } craft-cfb = { path = "crates/cfb" } craft-codepage = { path = "crates/codepage" } craft-cms = { path = "crates/cms" } +craft-color = { path = "crates/color" } +craft-frame = { path = "crates/frame" } craft-crs = { path = "crates/crs" } craft-crw = { path = "crates/crw" } craft-csv = { path = "crates/csv" } diff --git a/crates/color/Cargo.toml b/crates/color/Cargo.toml new file mode 100644 index 000000000..44578baed --- /dev/null +++ b/crates/color/Cargo.toml @@ -0,0 +1,17 @@ +[package] +name = "craft-color" +description = "Colour tags, Y'CbCr matrices, transfer functions and HDR static metadata for compositor and display frames" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +serde = { workspace = true } + +[dev-dependencies] +proptest = { workspace = true } diff --git a/crates/color/src/lib.rs b/crates/color/src/lib.rs new file mode 100644 index 000000000..5bf6426b8 --- /dev/null +++ b/crates/color/src/lib.rs @@ -0,0 +1,411 @@ +//! Colour tags and the conversions compositor and display frames need. +//! +//! This is the slim colour-metadata layer used by craft-frame and by media +//! `MediaInfo`: [`ColorInfo`] (matrix, transfer, primaries, range), [`HdrMetadata`], Y'CbCr +//! matrices, transfer functions, and a few helpers (sRGB tables, HSL, hex). It is not a +//! colour-managed pipeline: LUTs, camera log, grade and tone mapping stay out. +//! +//! Came from FilmCraft's `filmcraft-color` (the metadata and transfer part of that crate). +//! Distinct from `craft-video`'s decoder colour tags (`ColorTags` in #1231 / #1768). + +#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))] + +use serde::{Deserialize, Serialize}; +use std::sync::OnceLock; + +/// HDR reference white in cd/m² (ITU-R BT.2408). +pub const REFERENCE_WHITE_NITS: f64 = 203.0; + +/// YUV ↔ RGB matrix coefficients. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub enum Matrix { + Bt601, + #[default] + Bt709, + Bt2020Ncl, +} + +impl Matrix { + /// (Kr, Kb) luma coefficients. + pub fn kr_kb(self) -> (f32, f32) { + match self { + Matrix::Bt601 => (0.299, 0.114), + Matrix::Bt709 => (0.2126, 0.0722), + Matrix::Bt2020Ncl => (0.2627, 0.0593), + } + } + /// From an ISO/IEC 23091-2 `matrix_coefficients` code. + pub fn from_code(c: u8) -> Option { + match c { + 1 => Some(Matrix::Bt709), + 5 | 6 => Some(Matrix::Bt601), + 9 | 10 => Some(Matrix::Bt2020Ncl), + _ => None, + } + } +} + +/// Transfer characteristics. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub enum Transfer { + /// BT.709 / BT.1886 display (pure 2.4 gamma is what NLEs use for display-referred decode). + #[default] + Bt709, + Srgb, + Linear, + /// SMPTE ST 2084. + Pq, + /// ARIB STD-B67. + Hlg, +} + +impl Transfer { + /// From an ISO/IEC 23091-2 `transfer_characteristics` code. + pub fn from_code(c: u8) -> Option { + match c { + 1 | 6 | 14 | 15 => Some(Transfer::Bt709), + 13 => Some(Transfer::Srgb), + 8 => Some(Transfer::Linear), + 16 => Some(Transfer::Pq), + 18 => Some(Transfer::Hlg), + _ => None, + } + } +} + +/// Chromaticity primaries. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub enum Primaries { + #[default] + Bt709, + Bt601_625, + Bt601_525, + Bt2020, + P3D65, +} + +/// Quantisation range of integer Y'CbCr samples. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub enum Range { + /// 16–235 (8-bit) "video" range. + #[default] + Limited, + Full, +} + +/// Colour metadata attached to a compositor or display frame. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub struct ColorInfo { + pub matrix: Matrix, + pub transfer: Transfer, + pub primaries: Primaries, + pub range: Range, +} + +impl ColorInfo { + pub const SRGB_FULL: ColorInfo = ColorInfo { matrix: Matrix::Bt709, transfer: Transfer::Srgb, primaries: Primaries::Bt709, range: Range::Full }; + pub const REC709: ColorInfo = ColorInfo { matrix: Matrix::Bt709, transfer: Transfer::Bt709, primaries: Primaries::Bt709, range: Range::Limited }; +} + +/// HDR static metadata of a stream: SMPTE ST 2086 mastering display luminance and the CTA-861.3 +/// content light levels (MaxCLL / MaxFALL), in cd/m². Read from `mdcv` / `clli` (MP4 / MOV) and +/// Matroska `MasteringMetadata` / `MaxCLL` / `MaxFALL`. +#[derive(Clone, Copy, Debug, Default, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct HdrMetadata { + pub mastering_max_nits: Option, + pub mastering_min_nits: Option, + pub max_cll: Option, + pub max_fall: Option, +} + +impl HdrMetadata { + /// The content's peak for tone mapping: MaxCLL when signalled (the brightest pixel actually + /// in the content), else the mastering display's peak; `None` when neither is (0 means + /// unknown in both). Never below HDR reference white. + pub fn peak_nits(&self) -> Option { + let known = |v: Option| v.filter(|n| *n > 0.0); + let p = match (known(self.max_cll), known(self.mastering_max_nits)) { + (Some(c), Some(m)) => c.min(m), + (Some(c), None) => c, + (None, m) => m?, + }; + Some(p.clamp(REFERENCE_WHITE_NITS as f32, 10_000.0)) + } +} + +/// Convert normalised Y'CbCr (Y in 0..1, Cb/Cr in -0.5..0.5) to non-linear R'G'B'. +#[inline] +pub fn ycbcr_to_rgb(y: f32, cb: f32, cr: f32, m: Matrix) -> [f32; 3] { + let (kr, kb) = m.kr_kb(); + let kg = 1.0 - kr - kb; + let r = y + 2.0 * (1.0 - kr) * cr; + let b = y + 2.0 * (1.0 - kb) * cb; + let g = (y - kr * r - kb * b) / kg; + [r, g, b] +} + +/// Convert non-linear R'G'B' to normalised Y'CbCr. +#[inline] +pub fn rgb_to_ycbcr(r: f32, g: f32, b: f32, m: Matrix) -> [f32; 3] { + let (kr, kb) = m.kr_kb(); + let kg = 1.0 - kr - kb; + let y = kr * r + kg * g + kb * b; + [y, (b - y) / (2.0 * (1.0 - kb)), (r - y) / (2.0 * (1.0 - kr))] +} + +/// Normalise an integer luma code value to 0..1 given bit depth and range. +#[inline] +pub fn normalize_y(v: u32, bits: u32, range: Range) -> f32 { + let scale = (1u32 << (bits - 8)) as f32; + match range { + Range::Limited => (v as f32 - 16.0 * scale) / (219.0 * scale), + Range::Full => v as f32 / ((1u32 << bits) - 1) as f32, + } +} + +/// Normalise an integer chroma code value to −0.5..0.5 given bit depth and range. +#[inline] +pub fn normalize_c(v: u32, bits: u32, range: Range) -> f32 { + let scale = (1u32 << (bits - 8)) as f32; + match range { + Range::Limited => (v as f32 - 128.0 * scale) / (224.0 * scale), + Range::Full => (v as f32 - (1u32 << (bits - 1)) as f32) / ((1u32 << bits) - 1) as f32, + } +} + +/// sRGB electro-optical transfer (encoded → linear). +#[inline] +pub fn srgb_to_linear(v: f32) -> f32 { + if v <= 0.04045 { v / 12.92 } else { ((v + 0.055) / 1.055).powf(2.4) } +} + +/// sRGB inverse EOTF (linear → encoded). +#[inline] +pub fn linear_to_srgb(v: f32) -> f32 { + if v <= 0.003_130_8 { v * 12.92 } else { 1.055 * v.powf(1.0 / 2.4) - 0.055 } +} + +/// Encoded → linear for a transfer function (display-referred; PQ normalised to 100 nits = 1.0). +pub fn to_linear(v: f32, t: Transfer) -> f32 { + match t { + Transfer::Srgb => srgb_to_linear(v), + // Rec.709 is treated as display gamma 2.4; the sRGB curve is visually identical for + // previews and keeps round-trips exact. + Transfer::Bt709 => srgb_to_linear(v), + Transfer::Linear => v, + Transfer::Pq => pq_eotf(v) * 100.0, + Transfer::Hlg => hlg_inverse_oetf(v), + } +} + +/// Linear → encoded for a transfer function (the inverse of [`to_linear`]). +pub fn from_linear(v: f32, t: Transfer) -> f32 { + match t { + Transfer::Srgb | Transfer::Bt709 => linear_to_srgb(v), + Transfer::Linear => v, + Transfer::Pq => pq_inverse_eotf(v / 100.0), + Transfer::Hlg => hlg_oetf(v), + } +} + +/// SMPTE ST 2084 EOTF, output normalised to 10 000 nits = 1.0. +pub fn pq_eotf(e: f32) -> f32 { + let (m1, m2) = (0.159_301_76_f32, 78.84375_f32); + let (c1, c2, c3) = (0.835_937_5_f32, 18.851_563_f32, 18.6875_f32); + let p = e.max(0.0).powf(1.0 / m2); + ((p - c1).max(0.0) / (c2 - c3 * p)).powf(1.0 / m1) +} + +/// Inverse of [`pq_eotf`]. +pub fn pq_inverse_eotf(y: f32) -> f32 { + let (m1, m2) = (0.159_301_76_f32, 78.84375_f32); + let (c1, c2, c3) = (0.835_937_5_f32, 18.851_563_f32, 18.6875_f32); + let p = y.max(0.0).powf(m1); + ((c1 + c2 * p) / (1.0 + c3 * p)).powf(m2) +} + +/// ARIB STD-B67 HLG OETF. +pub fn hlg_oetf(l: f32) -> f32 { + let (a, b, c) = (0.178_832_77_f32, 0.284_668_92_f32, 0.559_910_7_f32); + if l <= 1.0 / 12.0 { (3.0 * l.max(0.0)).sqrt() } else { a * (12.0 * l - b).ln() + c } +} + +/// Inverse of [`hlg_oetf`]. +pub fn hlg_inverse_oetf(e: f32) -> f32 { + let (a, b, c) = (0.178_832_77_f32, 0.284_668_92_f32, 0.559_910_7_f32); + if e <= 0.5 { e * e / 3.0 } else { (((e - c) / a).exp() + b) / 12.0 } +} + +/// 256-entry table: sRGB-encoded u8 → linear f32. +pub fn srgb_u8_to_linear_table() -> &'static [f32; 256] { + static T: OnceLock<[f32; 256]> = OnceLock::new(); + T.get_or_init(|| std::array::from_fn(|i| srgb_to_linear(i as f32 / 255.0))) +} + +/// 4096-entry table: linear (0..1, quantised to 12 bits) → sRGB-encoded u8. +pub fn linear_to_srgb_u8_table() -> &'static [u8; 4096] { + static T: OnceLock<[u8; 4096]> = OnceLock::new(); + T.get_or_init(|| std::array::from_fn(|i| (linear_to_srgb(i as f32 / 4095.0) * 255.0 + 0.5).clamp(0.0, 255.0) as u8)) +} + +/// Linear 0..1 to an sRGB-encoded u8, via [`linear_to_srgb_u8_table`]. +#[inline] +pub fn linear_to_srgb_u8(v: f32) -> u8 { + let i = (v.clamp(0.0, 1.0) * 4095.0 + 0.5) as usize; + linear_to_srgb_u8_table()[i] +} + +/// Rec.709 luma of a linear or encoded RGB triple. +#[inline] +pub fn luma709(r: f32, g: f32, b: f32) -> f32 { + 0.2126 * r + 0.7152 * g + 0.0722 * b +} + +/// RGB (0..1) → HSL (h in 0..1). +pub fn rgb_to_hsl(r: f32, g: f32, b: f32) -> [f32; 3] { + let max = r.max(g).max(b); + let min = r.min(g).min(b); + let l = (max + min) / 2.0; + if (max - min).abs() < 1e-7 { + return [0.0, 0.0, l]; + } + let d = max - min; + let s = if l > 0.5 { d / (2.0 - max - min) } else { d / (max + min) }; + let h = if max == r { + (g - b) / d + if g < b { 6.0 } else { 0.0 } + } else if max == g { + (b - r) / d + 2.0 + } else { + (r - g) / d + 4.0 + }; + [h / 6.0, s, l] +} + +/// Inverse of [`rgb_to_hsl`]. +pub fn hsl_to_rgb(h: f32, s: f32, l: f32) -> [f32; 3] { + if s <= 0.0 { + return [l, l, l]; + } + let q = if l < 0.5 { l * (1.0 + s) } else { l + s - l * s }; + let p = 2.0 * l - q; + let f = |mut t: f32| { + t = t.rem_euclid(1.0); + if t < 1.0 / 6.0 { + p + (q - p) * 6.0 * t + } else if t < 0.5 { + q + } else if t < 2.0 / 3.0 { + p + (q - p) * (2.0 / 3.0 - t) * 6.0 + } else { + p + } + }; + [f(h + 1.0 / 3.0), f(h), f(h - 1.0 / 3.0)] +} + +/// Parse `#rrggbb` / `#rrggbbaa` into 0..1 floats. +pub fn parse_hex(s: &str) -> Option<[f32; 4]> { + let s = s.trim(); + let s = s.strip_prefix('#').unwrap_or(s); + if !s.bytes().all(|b| b.is_ascii_hexdigit()) { + return None; + } + let b = |i: usize| u8::from_str_radix(s.get(i..i + 2)?, 16).ok().map(|v| v as f32 / 255.0); + match s.len() { + 6 => Some([b(0)?, b(2)?, b(4)?, 1.0]), + 8 => Some([b(0)?, b(2)?, b(4)?, b(6)?]), + _ => None, + } +} + +/// The inverse of [`parse_hex`], lowercase, omitting alpha when it is 1. +pub fn to_hex(c: [f32; 4]) -> String { + let q = |v: f32| (v.clamp(0.0, 1.0) * 255.0).round() as u8; + if c[3] >= 0.999 { + format!("#{:02x}{:02x}{:02x}", q(c[0]), q(c[1]), q(c[2])) + } else { + format!("#{:02x}{:02x}{:02x}{:02x}", q(c[0]), q(c[1]), q(c[2]), q(c[3])) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parse_hex_rejects_signs() { + assert_eq!(parse_hex("#+f+f+f"), None); + assert_eq!(parse_hex("#-f-f-f"), None); + assert_eq!(parse_hex("##0f0f0f"), None); + assert_eq!(parse_hex("#0f0f0"), None); + assert!(parse_hex("#0f0f0f").is_some()); + assert!(parse_hex("0f0f0f80").is_some()); + } + + #[test] + fn ycbcr_roundtrip() { + for m in [Matrix::Bt601, Matrix::Bt709, Matrix::Bt2020Ncl] { + let rgb = [0.8, 0.3, 0.1]; + let y = rgb_to_ycbcr(rgb[0], rgb[1], rgb[2], m); + let back = ycbcr_to_rgb(y[0], y[1], y[2], m); + for k in 0..3 { + assert!((rgb[k] - back[k]).abs() < 1e-5); + } + } + } + + #[test] + fn limited_range_levels() { + assert_eq!(normalize_y(16, 8, Range::Limited), 0.0); + assert_eq!(normalize_y(235, 8, Range::Limited), 1.0); + assert_eq!(normalize_y(940, 10, Range::Limited), 1.0); + assert_eq!(normalize_c(128, 8, Range::Limited), 0.0); + } + + #[test] + fn transfer_roundtrips() { + for t in [Transfer::Srgb, Transfer::Pq, Transfer::Hlg, Transfer::Linear] { + for v in [0.0, 0.1, 0.5, 0.9] { + let l = to_linear(v, t); + assert!((from_linear(l, t) - v).abs() < 1e-3, "{t:?} {v}"); + } + } + assert_eq!(linear_to_srgb_u8(1.0), 255); + assert_eq!(linear_to_srgb_u8(0.0), 0); + assert_eq!(linear_to_srgb_u8(srgb_u8_to_linear_table()[128]), 128); + } + + #[test] + fn hsl_roundtrip() { + let c = [0.2, 0.6, 0.9]; + let h = rgb_to_hsl(c[0], c[1], c[2]); + let b = hsl_to_rgb(h[0], h[1], h[2]); + for k in 0..3 { + assert!((c[k] - b[k]).abs() < 1e-5); + } + } + + #[test] + fn hex() { + assert_eq!(parse_hex("#ff8000"), Some([1.0, 128.0 / 255.0, 0.0, 1.0])); + assert_eq!(to_hex([1.0, 0.0, 0.0, 1.0]), "#ff0000"); + } + + #[test] + fn hdr_peak_nits() { + assert_eq!(HdrMetadata::default().peak_nits(), None); + assert_eq!(HdrMetadata { max_cll: Some(1000.0), mastering_max_nits: Some(4000.0), ..HdrMetadata::default() }.peak_nits(), Some(1000.0)); + assert_eq!(HdrMetadata { max_cll: Some(0.0), mastering_max_nits: Some(400.0), ..HdrMetadata::default() }.peak_nits(), Some(400.0)); + // never below reference white + assert_eq!(HdrMetadata { max_cll: Some(100.0), ..HdrMetadata::default() }.peak_nits(), Some(REFERENCE_WHITE_NITS as f32)); + } + + #[test] + fn codes() { + assert_eq!(Matrix::from_code(1), Some(Matrix::Bt709)); + assert_eq!(Matrix::from_code(6), Some(Matrix::Bt601)); + assert_eq!(Transfer::from_code(16), Some(Transfer::Pq)); + assert_eq!(Transfer::from_code(99), None); + } +} diff --git a/crates/frame/Cargo.toml b/crates/frame/Cargo.toml new file mode 100644 index 000000000..f74bf9365 --- /dev/null +++ b/crates/frame/Cargo.toml @@ -0,0 +1,17 @@ +[package] +name = "craft-frame" +description = "Compositor and display VideoFrame (RGBA and planar Y'CbCr) with ColorInfo, distinct from craft-video decoder pictures" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +craft-color = { workspace = true } +craft-time = { workspace = true } +rayon = { workspace = true } +serde = { workspace = true } diff --git a/crates/frame/src/lib.rs b/crates/frame/src/lib.rs new file mode 100644 index 000000000..2a7c82d1a --- /dev/null +++ b/crates/frame/src/lib.rs @@ -0,0 +1,376 @@ +//! Compositor and display video frames. +//! +//! [`VideoFrame`] is a picture the compositor, monitors and export share: planar Y'CbCr (8 or +//! 16-bit) from a decoder, sRGB-encoded RGBA8 from stills, or linear premultiplied RGBA f32 in the +//! compositor. Pixel data is `Arc`-shared so caches can hold frames for free. Colour is explicit +//! ([`craft_color::ColorInfo`]); time is a [`craft_time::Tick`]. +//! +//! This is **not** the decoder-output picture type in `craft-video` (`craft_video::frame::VideoFrame` +//! in #1231 / #1768), which is a planar codec frame (per-plane bit depth, field order, colour +//! tags as H.273 codes). This type is the one `MediaSource::video_frame` returns. +//! +//! Came from FilmCraft's `filmcraft-frame` (the picture type and display conversions; the frame +//! pool and audio buffer stay out — audio is [`craft_audio::AudioBuffer`]). + +#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable))] + +use std::sync::Arc; + +use craft_color::{ + ColorInfo, Matrix, Range, Transfer, linear_to_srgb_u8, normalize_c, normalize_y, srgb_u8_to_linear_table, to_linear, ycbcr_to_rgb, +}; +use craft_time::Tick; +use rayon::prelude::*; +use serde::{Deserialize, Serialize}; + +/// Chroma subsampling of planar Y'CbCr. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, Serialize, Deserialize)] +pub enum Chroma { + C420, + C422, + C444, +} + +impl Chroma { + /// (horizontal shift, vertical shift) + pub fn shifts(self) -> (u32, u32) { + match self { + Chroma::C420 => (1, 1), + Chroma::C422 => (1, 0), + Chroma::C444 => (0, 0), + } + } + /// A short 4:2:0 / 4:2:2 / 4:4:4 label. + pub fn label(self) -> &'static str { + match self { + Chroma::C420 => "4:2:0", + Chroma::C422 => "4:2:2", + Chroma::C444 => "4:4:4", + } + } +} + +/// Pixel storage of a [`VideoFrame`]. +#[derive(Clone, Debug)] +pub enum PixelData { + /// Straight-alpha, sRGB/709-encoded RGBA, 8 bits per channel. + Rgba8(Arc>), + /// Premultiplied, linear-light RGBA f32 (compositor working format). + RgbaF32(Arc>), + /// 8-bit planar Y'CbCr (optionally with an alpha plane). + Yuv8 { planes: [Arc>; 3], chroma: Chroma, alpha: Option>> }, + /// 9–16-bit planar Y'CbCr stored in u16 (`bits` significant bits). + Yuv16 { planes: [Arc>; 3], chroma: Chroma, bits: u32, alpha: Option>> }, +} + +/// A compositor or display picture. Pixel buffers are `Arc`-shared. +#[derive(Clone, Debug)] +pub struct VideoFrame { + pub width: u32, + pub height: u32, + pub data: PixelData, + pub color: ColorInfo, + /// Pixel aspect ratio (num, den). + pub par: (u32, u32), + /// Presentation time in media time (informational). + pub pts: Tick, +} + +/// A rectangle of pixels: `x`, `y` is its top-left corner. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub struct Region { + pub x: usize, + pub y: usize, + pub w: usize, + pub h: usize, +} + +impl Region { + pub fn is_empty(&self) -> bool { + self.w == 0 || self.h == 0 + } + /// This rectangle cut to a `w`×`h` picture (empty when it lies outside). + pub fn clip(self, w: usize, h: usize) -> Region { + let x = self.x.min(w); + let y = self.y.min(h); + Region { x, y, w: self.w.min(w - x), h: self.h.min(h - y) } + } + /// Whether this rectangle is the whole `w`×`h` picture. + pub fn is_full(&self, w: usize, h: usize) -> bool { + (self.x, self.y, self.w, self.h) == (0, 0, w, h) + } +} + +impl VideoFrame { + /// An sRGB-full, 1:1, zero-pts RGBA8 frame. `data` is `width × height × 4` bytes. + pub fn rgba8(width: u32, height: u32, data: Vec) -> Self { + debug_assert_eq!(data.len(), (width * height * 4) as usize); + Self { width, height, data: PixelData::Rgba8(Arc::new(data)), color: ColorInfo::SRGB_FULL, par: (1, 1), pts: Tick::ZERO } + } + + /// A linear premultiplied RGBA f32 frame, sRGB-full tags, 1:1, zero pts. + pub fn rgba_f32(width: u32, height: u32, data: Vec) -> Self { + debug_assert_eq!(data.len(), (width * height * 4) as usize); + Self { width, height, data: PixelData::RgbaF32(Arc::new(data)), color: ColorInfo::SRGB_FULL, par: (1, 1), pts: Tick::ZERO } + } + + /// A transparent linear RGBA f32 frame of the given size. + pub fn transparent_f32(width: u32, height: u32) -> Self { + Self::rgba_f32(width, height, vec![0.0; (width * height * 4) as usize]) + } + + /// Sets the presentation timestamp and returns the frame. + pub fn with_pts(mut self, pts: Tick) -> Self { + self.pts = pts; + self + } + + /// A short format label for UI and logs. + pub fn format_label(&self) -> String { + match &self.data { + PixelData::Rgba8(_) => "RGBA 8-bit".into(), + PixelData::RgbaF32(_) => "RGBA 32-bit float".into(), + PixelData::Yuv8 { chroma, .. } => format!("YUV {} 8-bit", chroma.label()), + PixelData::Yuv16 { chroma, bits, .. } => format!("YUV {} {bits}-bit", chroma.label()), + } + } + + /// Approximate memory footprint in bytes (for caches). + pub fn byte_size(&self) -> usize { + match &self.data { + PixelData::Rgba8(d) => d.len(), + PixelData::RgbaF32(d) => d.len() * 4, + PixelData::Yuv8 { planes, alpha, .. } => planes.iter().map(|p| p.len()).sum::() + alpha.as_ref().map_or(0, |a| a.len()), + PixelData::Yuv16 { planes, alpha, .. } => (planes.iter().map(|p| p.len()).sum::() + alpha.as_ref().map_or(0, |a| a.len())) * 2, + } + } + + /// Premultiplied linear-light RGBA f32, one pixel per source pixel, row-major, 4 samples each. + pub fn to_linear_f32(&self) -> Vec { + let (w, h) = (self.width as usize, self.height as usize); + let mut out = vec![0.0; w.saturating_mul(h).saturating_mul(4)]; + if w == 0 || h == 0 { + return out; + } + match &self.data { + PixelData::RgbaF32(d) => { + let n = out.len().min(d.len()); + out[..n].copy_from_slice(&d[..n]); + } + PixelData::Rgba8(d) => { + let lut = srgb_u8_to_linear_table(); + for (o, s) in out.as_chunks_mut::<4>().0.iter_mut().zip(d.as_chunks::<4>().0) { + let a = s[3] as f32 / 255.0; + o[0] = lut[s[0] as usize] * a; + o[1] = lut[s[1] as usize] * a; + o[2] = lut[s[2] as usize] * a; + o[3] = a; + } + } + PixelData::Yuv8 { planes, chroma, alpha } => { + let (sx, sy) = chroma.shifts(); + let cw = w.div_ceil(1 << sx); + let info = self.color; + let lin: Vec = (0..4096).map(|i| to_linear(i as f32 / 4095.0, info.transfer)).collect(); + let q = |v: f32| lin[(v.clamp(0.0, 1.0) * 4095.0 + 0.5) as usize]; + let ytab: Vec = (0..256).map(|v| normalize_y(v, 8, info.range)).collect(); + let ctab: Vec = (0..256).map(|v| normalize_c(v, 8, info.range)).collect(); + let rgb_of = |y: usize, x: usize| { + let yy = ytab[planes[0][y * w + x] as usize]; + let u = ctab[planes[1][(y >> sy) * cw + (x >> sx)] as usize]; + let v = ctab[planes[2][(y >> sy) * cw + (x >> sx)] as usize]; + let rgb = ycbcr_to_rgb(yy, u, v, info.matrix); + let a = alpha.as_ref().map_or(1.0, |al| al[y * w + x] as f32 / 255.0); + [q(rgb[0]) * a, q(rgb[1]) * a, q(rgb[2]) * a, a] + }; + for y in 0..h { + for x in 0..w { + let o = (y * w + x) * 4; + out[o..o + 4].copy_from_slice(&rgb_of(y, x)); + } + } + } + PixelData::Yuv16 { planes, chroma, bits, alpha } => { + let (sx, sy) = chroma.shifts(); + let cw = w.div_ceil(1 << sx); + let info = self.color; + let bits = *bits; + let amax = ((1u32 << bits) - 1) as f32; + let lin: Vec = (0..4096).map(|i| to_linear(i as f32 / 4095.0, info.transfer)).collect(); + let q = |v: f32| lin[(v.clamp(0.0, 1.0) * 4095.0 + 0.5) as usize]; + for y in 0..h { + for x in 0..w { + let yy = normalize_y(planes[0][y * w + x] as u32, bits, info.range); + let u = normalize_c(planes[1][(y >> sy) * cw + (x >> sx)] as u32, bits, info.range); + let v = normalize_c(planes[2][(y >> sy) * cw + (x >> sx)] as u32, bits, info.range); + let rgb = ycbcr_to_rgb(yy, u, v, info.matrix); + let a = alpha.as_ref().map_or(1.0, |al| al[y * w + x] as f32 / amax); + let o = (y * w + x) * 4; + out[o] = q(rgb[0]) * a; + out[o + 1] = q(rgb[1]) * a; + out[o + 2] = q(rgb[2]) * a; + out[o + 3] = a; + } + } + } + } + out + } + + /// Convert to straight-alpha sRGB RGBA8 for display (fast path for 8-bit Rec.709/sRGB Y'CbCr + /// without alpha, and a copy for RGBA8). + pub fn to_rgba8(&self) -> Vec { + let (w, h) = (self.width as usize, self.height as usize); + match &self.data { + PixelData::Rgba8(d) => d.as_ref().clone(), + PixelData::Yuv8 { planes, chroma, alpha: None } if matches!(self.color.transfer, Transfer::Bt709 | Transfer::Srgb) => { + let (sx, sy) = chroma.shifts(); + let cw = w.div_ceil(1 << sx); + let (kr, kb) = self.color.matrix.kr_kb(); + let kg = 1.0 - kr - kb; + let (ys, yo, cs) = match self.color.range { + Range::Limited => (255.0 / 219.0, 16.0, 255.0 / 224.0), + Range::Full => (1.0, 0.0, 1.0), + }; + let (crr, cbb) = (2.0 * (1.0 - kr) * cs, 2.0 * (1.0 - kb) * cs); + let (cgr, cgb) = (crr * kr / kg, cbb * kb / kg); + let mut out = vec![0u8; w * h * 4]; + out.par_chunks_mut(w * 4).enumerate().for_each(|(y, row)| { + let cy = y >> sy; + let yrow = &planes[0][y * w..y * w + w]; + let urow = &planes[1][cy * cw..cy * cw + cw]; + let vrow = &planes[2][cy * cw..cy * cw + cw]; + for x in 0..w { + let yy = (yrow[x] as f32 - yo) * ys; + let u = urow[x >> sx] as f32 - 128.0; + let v = vrow[x >> sx] as f32 - 128.0; + let o = &mut row[x * 4..x * 4 + 4]; + o[0] = (yy + crr * v).round().clamp(0.0, 255.0) as u8; + o[1] = (yy - cgr * v - cgb * u).round().clamp(0.0, 255.0) as u8; + o[2] = (yy + cbb * u).round().clamp(0.0, 255.0) as u8; + o[3] = 255; + } + }); + out + } + _ => { + let lin = self.to_linear_f32(); + let mut out = vec![0u8; w * h * 4]; + out.par_chunks_mut(w * 4).zip(lin.par_chunks(w * 4)).for_each(|(o, s)| linear_premul_to_srgb8(s, o)); + out + } + } + } + + /// Luma plane (8-bit, for scopes and thumbnails). Y'CbCr 8-bit returns the Y plane; others go + /// through [`Self::to_rgba8`] and Rec.709 luma of the encoded RGB. + pub fn luma8(&self) -> Vec { + match &self.data { + PixelData::Yuv8 { planes, .. } => planes[0].as_ref().clone(), + _ => self + .to_rgba8() + .as_chunks::<4>() + .0 + .iter() + .map(|p| (0.2126 * p[0] as f32 + 0.7152 * p[1] as f32 + 0.0722 * p[2] as f32) as u8) + .collect(), + } + } +} + +/// Convert a row of premultiplied linear f32 RGBA into straight sRGB RGBA8. +pub fn linear_premul_to_srgb8(src: &[f32], dst: &mut [u8]) { + for (s, o) in src.as_chunks::<4>().0.iter().zip(dst.as_chunks_mut::<4>().0) { + let a = s[3].clamp(0.0, 1.0); + if a <= 0.0 { + o.copy_from_slice(&[0, 0, 0, 0]); + continue; + } + let inv = 1.0 / a; + o[0] = linear_to_srgb_u8(s[0] * inv); + o[1] = linear_to_srgb_u8(s[1] * inv); + o[2] = linear_to_srgb_u8(s[2] * inv); + o[3] = (a * 255.0 + 0.5) as u8; + } +} + +/// Matrix used when a decoder does not signal one: BT.601 for SD, BT.709 otherwise (common practice). +pub fn default_matrix(width: u32, height: u32) -> Matrix { + if width <= 1024 && height <= 576 { Matrix::Bt601 } else { Matrix::Bt709 } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rgba8_roundtrips_through_to_rgba8() { + let px = vec![10u8, 20, 30, 255, 0, 0, 0, 0]; + let f = VideoFrame::rgba8(2, 1, px.clone()).with_pts(Tick(42)); + assert_eq!(f.pts, Tick(42)); + assert_eq!(f.to_rgba8(), px); + assert_eq!(f.format_label(), "RGBA 8-bit"); + assert_eq!(f.byte_size(), 8); + assert_eq!(f.color, ColorInfo::SRGB_FULL); + } + + #[test] + fn rgba8_to_linear_premultiplies() { + // 50% red, 50% alpha, sRGB encoded. Linear of 128/255, times 0.5 alpha. + let f = VideoFrame::rgba8(1, 1, vec![128, 0, 0, 128]); + let lin = f.to_linear_f32(); + let a = 128.0 / 255.0; + let r = srgb_u8_to_linear_table()[128] * a; + assert!((lin[0] - r).abs() < 1e-6); + assert_eq!(lin[1], 0.0); + assert!((lin[3] - a).abs() < 1e-6); + let back = f.to_rgba8(); + assert_eq!(back[0], 128); + assert_eq!(back[3], 128); + } + + #[test] + fn limited_709_gray_yuv8_is_near_neutral() { + // Limited-range mid gray: Y=126 (~0.5), Cb=Cr=128. + let y = Arc::new(vec![126u8; 4]); + let c = Arc::new(vec![128u8; 4]); + let f = VideoFrame { + width: 2, + height: 2, + data: PixelData::Yuv8 { planes: [y, c.clone(), c], chroma: Chroma::C444, alpha: None }, + color: ColorInfo::REC709, + par: (1, 1), + pts: Tick::ZERO, + }; + let rgba = f.to_rgba8(); + for p in rgba.as_chunks::<4>().0 { + assert!((p[0] as i16 - p[1] as i16).abs() <= 1, "{p:?}"); + assert!((p[1] as i16 - p[2] as i16).abs() <= 1, "{p:?}"); + assert!(p[0] > 90 && p[0] < 160, "{p:?}"); + assert_eq!(p[3], 255); + } + assert_eq!(f.luma8(), vec![126, 126, 126, 126]); + assert_eq!(f.format_label(), "YUV 4:4:4 8-bit"); + } + + #[test] + fn default_matrix_is_601_for_sd_and_709_otherwise() { + assert_eq!(default_matrix(720, 576), Matrix::Bt601); + assert_eq!(default_matrix(1920, 1080), Matrix::Bt709); + } + + #[test] + fn region_clip() { + let r = Region { x: 8, y: 8, w: 16, h: 16 }.clip(10, 10); + assert_eq!(r, Region { x: 8, y: 8, w: 2, h: 2 }); + assert!(Region { x: 20, y: 0, w: 4, h: 4 }.clip(10, 10).is_empty()); + assert!(Region { x: 0, y: 0, w: 10, h: 10 }.is_full(10, 10)); + } + + #[test] + fn transparent_float_encodes_as_zero_rgba8() { + let f = VideoFrame::transparent_f32(2, 1); + assert_eq!(f.to_rgba8(), vec![0; 8]); + assert_eq!(f.byte_size(), 32); // 2 pixels × 4 f32 channels × 4 bytes + } +}