FilmCraft: An open-source, nonlinear video editor written by scratch in pure Rust
//! VC-3 decoding (SMPTE ST 2019-1 §8).
use crate::bits::Reader;
use crate::dct::idct8x8;
use crate::header::{self, FieldCode, FrameHeader, SCAN_INDEX_OFFSET};
use crate::tables::{AMP_EOB, AMP_FINDEX, AMP_FRUN, CidInfo, VlcSet, ZIGZAG, cid_info, vlc};
use crate::{ChromaFormat, Error, Frame, Interlace, Result};
/// Decoder options.
#[derive(Debug, Clone, Copy)]
pub struct DecodeOptions {
/// Decode macroblock scan lines in parallel (needs the `threads` feature).
pub threads: bool,
/// Use the standard's integer inverse quantisation (equation 8.1) instead of the
/// ffmpeg-compatible reconstruction (default false; see the README).
pub spec_dequant: bool,
}
impl Default for DecodeOptions {
fn default() -> Self {
DecodeOptions { threads: true, spec_dequant: false }
}
}
/// Parse the header of the first coding unit of a frame.
pub fn probe(data: &[u8]) -> Result<FrameHeader> {
header::parse(data)
}
/// Decode one compressed frame (one or two coding units).
pub fn decode_frame(data: &[u8]) -> Result<Frame> {
decode_frame_with(data, &DecodeOptions::default())
}
/// Decode one compressed frame with options.
pub fn decode_frame_with(data: &[u8], opts: &DecodeOptions) -> Result<Frame> {
let h1 = header::parse(data)?;
let field_coded = h1.interlaced && !h1.frame_encoding;
if !field_coded {
let planes = decode_unit(&h1, data, opts)?;
let mut f = Frame::new_like(&h1, h1.width, h1.lines);
f.interlace = if h1.interlaced { Interlace::TopFieldFirst } else { Interlace::Progressive };
planes.copy_into(&mut f, 0, 1);
return Ok(f);
}
// field encoding: two coding units, field 1 (top) then field 2
let off = second_unit_offset(&h1, data)?;
let h2 = header::parse(&data[off..])?;
if h2.cid != h1.cid || h2.width != h1.width || h2.lines != h1.lines || h2.chroma != h1.chroma || h2.alpha != h1.alpha {
return Err(Error::Invalid("field coding units differ"));
}
let (p1, p2) = if opts.threads {
join(|| decode_unit(&h1, &data[..off], opts), || decode_unit(&h2, &data[off..], opts))
} else {
(decode_unit(&h1, &data[..off], opts), decode_unit(&h2, &data[off..], opts))
};
let (top, bottom) = if h1.field == FieldCode::Field2 { (p2?, p1?) } else { (p1?, p2?) };
// Both field payloads must be valid before committing the full-frame
// allocation; a damaged header alone must not allocate an output picture.
let mut f = Frame::new_like(&h1, h1.width, h1.lines * 2);
f.interlace = Interlace::TopFieldFirst;
top.copy_into(&mut f, 0, 2);
bottom.copy_into(&mut f, 1, 2);
Ok(f)
}
#[cfg(feature = "threads")]
fn join<A: Send, B: Send>(a: impl FnOnce() -> A + Send, b: impl FnOnce() -> B + Send) -> (A, B) {
rayon::join(a, b)
}
#[cfg(not(feature = "threads"))]
fn join<A, B>(a: impl FnOnce() -> A, b: impl FnOnce() -> B) -> (A, B) {
(a(), b())
}
/// Byte offset of the second coding unit of a field-coded frame.
fn second_unit_offset(h: &FrameHeader, data: &[u8]) -> Result<usize> {
if let Some(sz) = h.coding_unit_size() {
let sz = sz as usize;
if data.len() >= sz + 0x280 && data[sz..sz + 4] == data[0..4] && data[sz + 4] == data[4] {
return Ok(sz);
}
}
// VBR (or unexpected size): find the next header prefix after the first unit's scan lines
let prefix = &data[0..5];
let start = h.header_size as usize;
data[start..]
.windows(5)
.position(|w| w == prefix)
.map(|p| p + start)
.filter(|&p| header::parse(&data[p..]).is_ok())
.ok_or(Error::Invalid("second field coding unit not found"))
}
/// Decoded planes of one coding unit at the coded (macroblock-aligned) size.
struct CodedPlanes {
/// Y / Cb / Cr / A (or R / G / B / A).
planes: [Vec<u16>; 4],
strides: [usize; 4],
/// An RGB-signalled stream whose macroblocks are all coded as Y'CbCr.
ycbcr: bool,
}
impl CodedPlanes {
/// Crop into `f`, writing coded line `i` to frame line `first + i·step`.
fn copy_into(&self, f: &mut Frame, first: usize, step: usize) {
if self.ycbcr {
f.rgb = false;
}
let cw = f.chroma_width() as usize;
let w = f.width as usize;
let ch = f.chroma_height() as usize;
let h = f.height as usize;
let cfirst = first;
let mut targets: Vec<(&mut Vec<u16>, usize, usize, usize, usize)> =
vec![(&mut f.y, w, h, first, 0), (&mut f.cb, cw, ch, cfirst, 1), (&mut f.cr, cw, ch, cfirst, 2)];
if let Some(a) = f.alpha.as_mut() {
targets.push((a, w, h, first, 3));
}
for (dst, pw, ph, first, pi) in targets {
let src = &self.planes[pi];
let ss = self.strides[pi];
let mut line = 0;
let mut y = first;
while y < ph {
let s = &src[line * ss..line * ss + pw];
dst[y * pw..y * pw + pw].copy_from_slice(s);
line += 1;
y += step;
}
}
}
}
/// Block layout entry: plane, x offset and y offset (0 or 8) inside the macroblock.
type BlockPos = (u8, u8, u8);
const LAYOUT_422: [BlockPos; 8] = [(0, 0, 0), (0, 8, 0), (1, 0, 0), (2, 0, 0), (0, 0, 8), (0, 8, 8), (1, 0, 8), (2, 0, 8)];
const LAYOUT_420: [BlockPos; 6] = [(0, 0, 0), (0, 8, 0), (1, 0, 0), (2, 0, 0), (0, 0, 8), (0, 8, 8)];
const LAYOUT_444: [BlockPos; 12] =
[(0, 0, 0), (0, 8, 0), (1, 0, 0), (1, 8, 0), (2, 0, 0), (2, 8, 0), (0, 0, 8), (0, 8, 8), (1, 0, 8), (1, 8, 8), (2, 0, 8), (2, 8, 8)];
const LAYOUT_ALPHA: [BlockPos; 4] = [(3, 0, 0), (3, 8, 0), (3, 0, 8), (3, 8, 8)];
/// Per-coding-unit decoding context.
struct Ctx<'a> {
h: &'a FrameHeader,
info: &'static CidInfo,
vlc: &'static VlcSet,
nw: usize,
layout: &'static [BlockPos],
/// Plane macroblock sizes (width, height) for Y/Cb/Cr/A.
mb_size: [(usize, usize); 4],
strides: [usize; 4],
p_bits: u32,
p_shift: u32,
p_half: u32,
spec_dequant: bool,
/// `1 / (4p)`
inv_4p: f32,
/// IDCT output scale (4 at 12 bits, see README) and level offset.
scale: f32,
mid: f32,
max: f32,
}
fn decode_unit(h: &FrameHeader, data: &[u8], opts: &DecodeOptions) -> Result<CodedPlanes> {
let info = cid_info(h.cid).ok_or(Error::UnknownCid(h.cid))?;
let nw = h.mb_width() as usize;
let ns = h.mb_rows as usize;
let (layout, cmb): (&'static [BlockPos], (usize, usize)) = match h.chroma {
ChromaFormat::Yuv422 => (&LAYOUT_422, (8, 16)),
ChromaFormat::Yuv420 => (&LAYOUT_420, (8, 8)),
ChromaFormat::Yuv444 => (&LAYOUT_444, (16, 16)),
};
let mb_size = [(16, 16), cmb, cmb, (16, 16)];
let strides = [nw * 16, nw * cmb.0, nw * cmb.0, nw * 16];
let ctx = Ctx {
h,
info,
vlc: vlc(info.vlc),
nw,
layout,
mb_size,
strides,
p_bits: if h.bit_depth == 8 { 4 } else { 6 },
p_shift: info.p.trailing_zeros(),
p_half: info.p / 2,
spec_dequant: opts.spec_dequant,
inv_4p: 1.0 / (4 * info.p) as f32,
scale: if h.bit_depth == 12 { 4.0 } else { 1.0 },
mid: (1u32 << (h.bit_depth - 1)) as f32,
max: ((1u32 << h.bit_depth) - 1) as f32,
};
// scan line byte ranges
let hs = h.header_size as usize;
let mut starts = Vec::with_capacity(ns);
for s in 0..ns {
let o = SCAN_INDEX_OFFSET + 4 * s;
let idx = u32::from_be_bytes([data[o], data[o + 1], data[o + 2], data[o + 3]]) as usize;
let st = hs.checked_add(idx).filter(|&v| v < data.len()).ok_or(Error::Truncated)?;
starts.push(st);
}
let ranges: Vec<(usize, usize)> = (0..ns)
.map(|s| {
let st = starts[s];
let end = starts.get(s + 1).copied().filter(|&e| e > st).unwrap_or(data.len());
(st, end)
})
.collect();
let alpha = h.alpha;
let mut planes: [Vec<u16>; 4] = [
vec![0; strides[0] * 16 * ns],
vec![0; strides[1] * cmb.1 * ns],
vec![0; strides[2] * cmb.1 * ns],
if alpha { vec![0; strides[3] * 16 * ns] } else { Vec::new() },
];
let [py, pcb, pcr, pa] = &mut planes;
let band = [strides[0] * 16, strides[1] * cmb.1, strides[2] * cmb.1, strides[3] * 16];
let mut alpha_bands: Vec<&mut [u16]> = if alpha { pa.chunks_mut(band[3]).collect() } else { (0..ns).map(|_| &mut [][..]).collect() };
let rows: Vec<(usize, &mut [u16], &mut [u16], &mut [u16], &mut [u16])> = py
.chunks_mut(band[0])
.zip(pcb.chunks_mut(band[1]))
.zip(pcr.chunks_mut(band[2]))
.zip(alpha_bands.drain(..))
.enumerate()
.map(|(i, (((y, cb), cr), a))| (i, y, cb, cr, a))
.collect();
let run = |(i, y, cb, cr, a): (usize, &mut [u16], &mut [u16], &mut [u16], &mut [u16])| -> Result<Vec<bool>> {
let (st, end) = ranges[i];
decode_row(&ctx, &data[st..end], [y, cb, cr, a]).map_err(|e| match e {
Error::Row(_) => Error::Row(i),
e => e,
})
};
#[cfg(feature = "threads")]
let acf: Vec<Vec<bool>> = if opts.threads {
use rayon::prelude::*;
rows.into_par_iter().map(run).collect::<Result<_>>()?
} else {
rows.into_iter().map(run).collect::<Result<_>>()?
};
#[cfg(not(feature = "threads"))]
let acf: Vec<Vec<bool>> = {
let _ = opts;
rows.into_iter().map(run).collect::<Result<_>>()?
};
// RGB streams (CLF = 1) choose RGB or Y'CbCr per macroblock (ACF). A stream whose
// macroblocks are all Y'CbCr is returned as Y'CbCr 4:4:4; mixed streams are converted to RGB
// macroblock by macroblock (ConvertMacroblockColor, 8.1.1).
let n_acf: usize = acf.iter().map(|r| r.iter().filter(|&&a| a).count()).sum();
let ycbcr = h.rgb_planes() && n_acf == nw * ns;
if h.rgb_planes() && n_acf > 0 && !ycbcr && h.color_volume != crate::ColorVolume::OutOfBand {
let [py, pcb, pcr, _] = &mut planes;
for (s, row) in acf.iter().enumerate() {
for (mb, &a) in row.iter().enumerate() {
if a {
let o = s * band[0];
convert_mb_to_rgb(&ctx, [&mut py[o..o + band[0]], &mut pcb[o..o + band[0]], &mut pcr[o..o + band[0]]], mb);
}
}
}
}
Ok(CodedPlanes { planes, strides, ycbcr })
}
/// Decode one macroblock scan line into the 16-line bands of each plane.
fn decode_row(ctx: &Ctx, data: &[u8], bands: [&mut [u16]; 4]) -> Result<Vec<bool>> {
let h = ctx.h;
let mut r = Reader::new(data);
// DC predictors: Y/Ch1, Cb, Cr, R, G, B, A
let mut pred = [0i32; 7];
let rgb = h.rgb_planes();
let mff_cid = ctx.info.cid == 1260;
let mut block = [0f32; 64];
let mut acfs = Vec::new();
for mb in 0..ctx.nw {
let (qsf, flag, mff) = if mff_cid {
let mff = r.read(1) == 1;
(r.read(10), r.read(1) == 1, mff)
} else {
(r.read(11), r.read(1) == 1, false)
};
let acf = rgb && flag;
let wq = scaled_weights(ctx.info.weights, qsf);
for &(plane, xo, yo) in ctx.layout {
let comp = plane as usize;
let slot = if rgb && !acf { 3 + comp } else { comp };
let w = &wq[(comp != 0) as usize];
decode_block(ctx, &mut r, &mut pred[slot], w, &mut block)?;
store(ctx, bands[comp], BlockPosition { plane: comp, macroblock: mb, x_offset: xo as usize, y_offset: yo as usize, field: mff }, &mut block);
}
if rgb {
acfs.push(acf);
}
if r.overrun() {
return Err(Error::Row(0));
}
}
if h.alpha {
if h.lossless_alpha {
for mb in 0..ctx.nw {
decode_rle_alpha(ctx, &mut r, bands[3], mb)?;
}
} else {
for mb in 0..ctx.nw {
let qsf = if mff_cid {
r.read(1);
let q = r.read(10);
r.read(1);
q
} else {
let q = r.read(11);
r.read(1);
q
};
let wq = scaled_weights(ctx.info.weights, qsf);
for &(plane, xo, yo) in &LAYOUT_ALPHA {
decode_block(ctx, &mut r, &mut pred[6], &wq[0], &mut block)?;
store(
ctx,
bands[3],
BlockPosition { plane: plane as usize, macroblock: mb, x_offset: xo as usize, y_offset: yo as usize, field: false },
&mut block,
);
}
}
}
if r.overrun() {
return Err(Error::Row(0));
}
}
Ok(acfs)
}
/// `W(u,v)·qsf` for every AC raster position (index 0 unused), luma and chroma.
#[inline]
fn scaled_weights(w: &[[u8; 63]; 2], qsf: u32) -> [[(u32, u32); 64]; 2] {
let mut out = [[(0u32, 0u32); 64]; 2];
for c in 0..2 {
for i in 0..63 {
let wi = w[c][i] as u32;
out[c][i + 1] = (wi * qsf, wi);
}
}
out
}
/// Decode one DCT block into dequantised coefficients (raster order).
#[inline]
fn decode_block(ctx: &Ctx, r: &mut Reader, pred: &mut i32, wq: &[(u32, u32); 64], block: &mut [f32; 64]) -> Result<()> {
let v = ctx.vlc;
*block = [0.0; 64];
// DC (8.2.4)
let eta = r.vlc(&v.dc);
let eps = if eta == 0 {
0
} else {
let rho = r.read(eta) as i32;
if rho >= 1 << (eta - 1) { rho } else { rho + 1 - (1 << eta) }
};
let dc = pred.wrapping_add(eps);
*pred = dc;
block[0] = dc as f32;
// AC (8.2.5)
let mut pos = 0usize;
loop {
let s = r.vlc(&v.amp);
if s & AMP_EOB != 0 {
break;
}
let neg = r.read(1) == 1;
let mut a = s & 0xff;
if s & AMP_FINDEX != 0 {
a += r.read(ctx.p_bits) * 64;
}
pos += 1;
if s & AMP_FRUN != 0 {
pos += r.vlc(&v.run) as usize;
}
if pos > 63 {
return Err(Error::Row(0));
}
let z = ZIGZAG[pos] as usize;
let (wqs, w) = wq[z];
// inverse quantisation (8.2.7)
// Reconstruction at (|X̂| + 3/4)·W·qsf/p, as ffmpeg's decoder does (see README); the
// standard's equation 8.1 rounds to an integer near (|X̂| + 1/2)·W·qsf/p.
let mag = if ctx.spec_dequant {
let add = if w != ctx.info.p { ctx.p_half } else { 0 };
((a as u64 * wqs as u64 + (wqs >> 1) as u64 + add as u64) >> ctx.p_shift) as f32
} else {
((4 * a as u64 + 3) * wqs as u64) as f32 * ctx.inv_4p
};
block[z] = if neg { -mag } else { mag };
}
Ok(())
}
/// IDCT a block and store it (with level adjustment and clipping) into a plane band.
struct BlockPosition {
plane: usize,
macroblock: usize,
x_offset: usize,
y_offset: usize,
field: bool,
}
#[inline]
fn store(ctx: &Ctx, band: &mut [u16], position: BlockPosition, block: &mut [f32; 64]) {
idct8x8(block);
let BlockPosition { plane, macroblock, x_offset, y_offset, field } = position;
let stride = ctx.strides[plane];
let x0 = macroblock * ctx.mb_size[plane].0 + x_offset;
let (first, step) = if field { (y_offset / 8, 2) } else { (y_offset, 1) };
let (scale, mid, max) = (ctx.scale, ctx.mid + 0.5, ctx.max);
for j in 0..8 {
let row = &mut band[(first + j * step) * stride + x0..][..8];
let src = &block[j * 8..j * 8 + 8];
for i in 0..8 {
row[i] = (src[i] * scale + mid).floor().clamp(0.0, max) as u16;
}
}
}
/// `ConvertMacroblockColor` (8.1.1): BT.709 Y′CbCr → R′G′B′ on the quantised (video-range)
/// signals, in place over the macroblock's three planes.
fn convert_mb_to_rgb(ctx: &Ctx, bands: [&mut [u16]; 3], mb: usize) {
let stride = ctx.strides[0];
let s = (1u32 << (ctx.h.bit_depth - 8)) as f32;
let (kr, kb) = match ctx.h.color_volume {
crate::ColorVolume::Bt709 => (0.2126f32, 0.0722f32),
_ => (0.2627, 0.0593),
};
let kg = 1.0 - kr - kb;
let c = 219.0 / 224.0;
for y in 0..16 {
for x in 0..16 {
let i = y * stride + mb * 16 + x;
let yy = bands[0][i] as f32;
let cb = bands[1][i] as f32 - 128.0 * s;
let cr = bands[2][i] as f32 - 128.0 * s;
let r = yy + 2.0 * (1.0 - kr) * c * cr;
let b = yy + 2.0 * (1.0 - kb) * c * cb;
let g = (yy - kr * r - kb * b) / kg;
// RGB planes are stored in coded channel order G, B, R
bands[0][i] = (g + 0.5).floor().clamp(0.0, ctx.max) as u16;
bands[1][i] = (b + 0.5).floor().clamp(0.0, ctx.max) as u16;
bands[2][i] = (r + 0.5).floor().clamp(0.0, ctx.max) as u16;
}
}
}
/// Lossless (differential RLE) alpha macroblock (§7.3.1.2, §8.3).
fn decode_rle_alpha(ctx: &Ctx, r: &mut Reader, band: &mut [u16], mb: usize) -> Result<()> {
let d = ctx.h.bit_depth as u32;
let mask = (1u32 << d) - 1;
let stride = ctx.strides[3];
let pos = |count: usize| {
let y = count / 16;
let x = if y.is_multiple_of(2) { count % 16 } else { 15 - count % 16 };
y * stride + mb * 16 + x
};
// RL = 1: RLE coded; RL = 0: 256 raw samples (§7.3.1.2 prose; see README)
let rl = r.read(4) & 1;
if rl == 0 {
for count in 0..256 {
band[pos(count)] = r.read(d) as u16;
}
return Ok(());
}
let rice = d / 2 - 2;
let (mut d1, mut d2) = (mask >> 1, mask >> 1);
let mut count = 0usize;
while count < 256 {
let p = r.read(1);
// Elias gamma
let mut n = 0;
while r.read(1) == 0 {
n += 1;
if n > 8 || r.overrun() {
return Err(Error::Row(0));
}
}
let nrl = (1usize << n) + r.read(n) as usize;
let dcw = if r.read(1) == 1 {
let mut q = 0u32;
while r.read(1) == 1 {
q += 1;
if q > 1 << d || r.overrun() {
return Err(Error::Row(0));
}
}
(q << rice) + r.read(rice)
} else {
r.read(d)
};
let diff = if dcw & 1 == 1 { mask.wrapping_sub(dcw >> 1) } else { dcw >> 1 };
if count + nrl > 256 {
return Err(Error::Row(0));
}
for _ in 0..nrl {
let v = if p == 1 { (2 * d1).wrapping_sub(d2).wrapping_add(diff) & mask } else { d1.wrapping_add(diff) & mask };
band[pos(count)] = v as u16;
d2 = d1;
d1 = v;
count += 1;
}
}
Ok(())
}