Add craft-color and craft-frame for compositor pictures

craft-color holds ColorInfo, HdrMetadata, Y'CbCr matrices, transfer
functions and the small helpers display conversion needs. It is not a
colour-managed pipeline (no LUTs, log, grade or tone mapping).

craft-frame holds VideoFrame, PixelData, Chroma and Region: the
compositor and display picture type MediaSource will return. It is
distinct from craft-video's decoder-output VideoFrame (#1231 / #1768).

Came from the metadata and picture parts of filmcraft-color and
filmcraft-frame. Part of #778 and effectcraft#781.
This commit is contained in:
FredApps
2026-11-16 14:58:59 +01:00
parent e836b6fd89
commit f71eeae5fa
6 changed files with 841 additions and 0 deletions
Generated
+18
View File
@@ -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"
+2
View File
@@ -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" }
+17
View File
@@ -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 }
+411
View File
@@ -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<Matrix> {
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<Transfer> {
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<f32>,
pub mastering_min_nits: Option<f32>,
pub max_cll: Option<f32>,
pub max_fall: Option<f32>,
}
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<f32> {
let known = |v: Option<f32>| 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);
}
}
+17
View File
@@ -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 }
+376
View File
@@ -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<Vec<u8>>),
/// Premultiplied, linear-light RGBA f32 (compositor working format).
RgbaF32(Arc<Vec<f32>>),
/// 8-bit planar Y'CbCr (optionally with an alpha plane).
Yuv8 { planes: [Arc<Vec<u8>>; 3], chroma: Chroma, alpha: Option<Arc<Vec<u8>>> },
/// 9–16-bit planar Y'CbCr stored in u16 (`bits` significant bits).
Yuv16 { planes: [Arc<Vec<u16>>; 3], chroma: Chroma, bits: u32, alpha: Option<Arc<Vec<u16>>> },
}
/// 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<u8>) -> 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<f32>) -> 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::<usize>() + alpha.as_ref().map_or(0, |a| a.len()),
PixelData::Yuv16 { planes, alpha, .. } => (planes.iter().map(|p| p.len()).sum::<usize>() + 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<f32> {
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<f32> = (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<f32> = (0..256).map(|v| normalize_y(v, 8, info.range)).collect();
let ctab: Vec<f32> = (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<f32> = (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<u8> {
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<u8> {
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
}
}