craft-video: Hap video decoder and encoder (#1519) (#1911)

This commit is contained in:
el-j authored and GitHub committed 2026-11-16 21:30:00 -05:00
1 parent 76902ae85e
commit 5ea29f8f05
7 files changed
+1260

No files matched your search

+6
View File
@@ -36,6 +36,8 @@ mpeg4 = ["mpeg4-encode"]
mpeg4-encode = ["craft-media/bitstream"]
# FFV1 lossless video (RFC 9043): version 3, range coder, decoder and encoder.
ffv1 = []
# Hap (Vidvox): decoder and encoder, with Snappy and chunked second stages.
hap = []
# Motion JPEG: a frame-level decoder and encoder over `craft-jpeg`.
mjpeg = ["dep:craft-jpeg"]
# Apple ProRes (SMPTE RDD 36): decoder and encoder.
@@ -75,6 +77,10 @@ craft-media-testkit = { workspace = true }
# The AVI muxer, for the MPEG-4 Part 2 encoder's end-to-end test.
craft-media = { workspace = true, features = ["avi"] }
[[test]]
name = "hap"
required-features = ["hap"]
[[test]]
name = "mjpeg"
required-features = ["mjpeg"]
+1
View File
@@ -23,6 +23,7 @@ No codec feature is on by default.
| `vp8` | `vp8` | VP8 (RFC 6386): decoder |
| `mpeg2` | [`mpeg2`](src/mpeg2/README.md) | MPEG-2 video (ITU-T H.262) and MPEG-1 video (ISO/IEC 11172-2): decoder (`mpeg2-decode` alone); MPEG-2 encoder with I, P and B pictures (`mpeg2-encode`, which also turns on the decoder) |
| `mpeg4` | [`mpeg4`](src/mpeg4/README.md) | MPEG-4 Part 2 video (ISO/IEC 14496-2, the Xvid/DivX format): Simple profile encoder (`mpeg4-encode`) |
| `hap` | `hap` | Vidvox Hap: Hap, Hap Alpha, Hap Q, Hap Q Alpha and Hap Alpha-Only, decoder and encoder, with the Snappy and chunked second stages. DXT1, DXT5, scaled YCoCg-DXT5 and BC4 pictures decode in software; BC7 (Hap R) and BC6 (Hap HDR) frames are read and their blocks returned but not decoded to pictures. |
| `mjpeg` | `mjpeg` | Motion JPEG: a decoder (baseline, extended and progressive Huffman JPEG; the Annex K tables for AVI `MJPG` packets that have none) and a baseline encoder, both over `craft-jpeg`. No two-field (MJPEG-A/B) packets and no lossless JPEG. |
| `prores` | `prores` | Apple ProRes (SMPTE RDD 36): decoder and encoder |
| `h264` | [`h264`](src/h264/decode/README.md) | ITU-T H.264 / AVC: decoder (`h264-decode` alone) and encoder (`h264-encode` alone) |
+220
View File
@@ -0,0 +1,220 @@
//! The block-compressed texture formats Hap carries: DXT1 (BC1), DXT5 (BC3) and RGTC1 (BC4), with
//! the scaled YCoCg colour transform of Hap Q. Blocks are 4x4 pixels, 8 bytes (DXT1, BC4) or 16
//! bytes (DXT5). The decoders give RGBA and the encoders are range-fit block compressors: the
//! two endpoints are the extremes of the block's colours (or alphas) and each pixel takes the
//! nearest of the palette those endpoints make.
/// A 4x4 block of RGBA pixels, row-major.
pub(super) type Block = [[u8; 4]; 16];
// The 5- and 6-bit endpoint channels widened to 8 bits as ffmpeg widens them (observed: its decoder
// is the reference for Hap pictures): about `v * 255 / 31` and `v * 255 / 63`, rounded, in fixed point.
fn expand5(v: u16) -> u8 {
((u32::from(v) * 263 + 16) >> 5) as u8
}
fn expand6(v: u16) -> u8 {
((u32::from(v) * 259 + 32) >> 6) as u8
}
fn rgb565(c: u16) -> [u8; 3] {
[expand5((c >> 11) & 31), expand6((c >> 5) & 63), expand5(c & 31)]
}
/// The four colours of a colour block. With `always_four` (the colour half of a DXT5 block) two
/// colours are interpolated at thirds between the endpoints; in DXT1 that is so only when the first
/// endpoint is above the second, and otherwise one colour is the half and one is black.
fn palette(c0: u16, c1: u16, always_four: bool) -> [[u8; 3]; 4] {
let (a, b) = (rgb565(c0), rgb565(c1));
let mix = |wa: u32, wb: u32, d: u32| -> [u8; 3] { std::array::from_fn(|i| ((wa * u32::from(a[i]) + wb * u32::from(b[i])) / d) as u8) };
if always_four || c0 > c1 { [a, b, mix(2, 1, 3), mix(1, 2, 3)] } else { [a, b, mix(1, 1, 2), [0; 3]] }
}
/// Decode a DXT1 colour block (8 bytes) into the RGB of 16 pixels.
pub(super) fn decode_color(block: &[u8], always_four: bool) -> [[u8; 3]; 16] {
let c0 = u16::from_le_bytes([block[0], block[1]]);
let c1 = u16::from_le_bytes([block[2], block[3]]);
let pal = palette(c0, c1, always_four);
let bits = u32::from_le_bytes([block[4], block[5], block[6], block[7]]);
std::array::from_fn(|i| pal[((bits >> (2 * i)) & 3) as usize])
}
/// The eight alphas of a BC4 / DXT5 alpha block, from its two endpoints.
fn alpha_palette(a0: u8, a1: u8) -> [u8; 8] {
let (x, y) = (u32::from(a0), u32::from(a1));
let mut p = [a0, a1, 0, 0, 0, 0, 0, 0];
if a0 > a1 {
for i in 2..8u32 {
p[i as usize] = (((8 - i) * x + (i - 1) * y) / 7) as u8;
}
} else {
for i in 2..6u32 {
p[i as usize] = (((6 - i) * x + (i - 1) * y) / 5) as u8;
}
p[6] = 0;
p[7] = 255;
}
p
}
/// Decode a BC4 / DXT5 alpha block (8 bytes) into 16 alphas.
pub(super) fn decode_alpha(block: &[u8]) -> [u8; 16] {
let pal = alpha_palette(block[0], block[1]);
let mut bits = 0u64;
for (i, &b) in block[2..8].iter().enumerate() {
bits |= u64::from(b) << (8 * i);
}
std::array::from_fn(|i| pal[((bits >> (3 * i)) & 7) as usize])
}
pub(super) fn decode_dxt1(block: &[u8]) -> Block {
let c = decode_color(block, false);
std::array::from_fn(|i| [c[i][0], c[i][1], c[i][2], 255])
}
pub(super) fn decode_dxt5(block: &[u8]) -> Block {
let a = decode_alpha(&block[..8]);
let c = decode_color(&block[8..16], true);
std::array::from_fn(|i| [c[i][0], c[i][1], c[i][2], a[i]])
}
/// Scaled YCoCg-DXT5 (Hap Q): the colour block holds Co, Cg and a scale in the red, green and blue
/// channels, the alpha block holds Y.
pub(super) fn decode_ycocg(block: &[u8]) -> Block {
let y = decode_alpha(&block[..8]);
let c = decode_color(&block[8..16], true);
std::array::from_fn(|i| {
let s = i32::from(c[i][2] >> 3) + 1;
let co = i32::from(c[i][0]) - 128;
let cg = i32::from(c[i][1]) - 128;
let y = i32::from(y[i]);
let (co, cg) = (co / s, cg / s);
let r = y + co - cg;
let g = y + cg;
let b = y - co - cg;
[r.clamp(0, 255) as u8, g.clamp(0, 255) as u8, b.clamp(0, 255) as u8, 255]
})
}
/// Decode a BC4 block (8 bytes) as an alpha mask.
pub(super) fn decode_bc4(block: &[u8]) -> [u8; 16] {
decode_alpha(block)
}
// ----------------------------------------------------------------------------------- encoders
fn pack565(c: [u8; 3]) -> u16 {
let r = (u16::from(c[0]) * 31 + 127) / 255;
let g = (u16::from(c[1]) * 63 + 127) / 255;
let b = (u16::from(c[2]) * 31 + 127) / 255;
(r << 11) | (g << 5) | b
}
fn dist(a: [u8; 3], b: [u8; 3]) -> u32 {
(0..3).map(|i| (i32::from(a[i]) - i32::from(b[i])).pow(2) as u32).sum()
}
/// Encode 16 RGB pixels as a DXT1 colour block.
pub(super) fn encode_color(px: &[[u8; 3]; 16], always_four: bool) -> [u8; 8] {
let mut lo = [255u8; 3];
let mut hi = [0u8; 3];
for p in px {
for i in 0..3 {
lo[i] = lo[i].min(p[i]);
hi[i] = hi[i].max(p[i]);
}
}
// Pull the endpoints in a little: the extremes of a box are rarely colours of the block.
for i in 0..3 {
let inset = (hi[i] - lo[i]) >> 4;
lo[i] += inset;
hi[i] -= inset;
}
let (mut c0, mut c1) = (pack565(hi), pack565(lo));
if c0 < c1 {
std::mem::swap(&mut c0, &mut c1);
}
let mut out = [0u8; 8];
out[..2].copy_from_slice(&c0.to_le_bytes());
out[2..4].copy_from_slice(&c1.to_le_bytes());
if c0 == c1 {
return out; // every index 0
}
let pal = palette(c0, c1, always_four);
let mut bits = 0u32;
for (i, p) in px.iter().enumerate() {
let best = (0..4).min_by_key(|&k| dist(*p, pal[k])).unwrap_or(0);
bits |= (best as u32) << (2 * i);
}
out[4..].copy_from_slice(&bits.to_le_bytes());
out
}
/// Encode 16 alphas as a BC4 / DXT5 alpha block.
pub(super) fn encode_alpha(a: &[u8; 16]) -> [u8; 8] {
let hi = a.iter().copied().max().unwrap_or(0);
let lo = a.iter().copied().min().unwrap_or(0);
let mut out = [0u8; 8];
out[0] = hi;
out[1] = lo;
if hi == lo {
return out;
}
let pal = alpha_palette(hi, lo);
let mut bits = 0u64;
for (i, &v) in a.iter().enumerate() {
let best = (0..8).min_by_key(|&k| (i32::from(v) - i32::from(pal[k])).abs()).unwrap_or(0);
bits |= (best as u64) << (3 * i);
}
for (i, b) in out[2..].iter_mut().enumerate() {
*b = (bits >> (8 * i)) as u8;
}
out
}
fn rgb_of(block: &Block) -> [[u8; 3]; 16] {
std::array::from_fn(|i| [block[i][0], block[i][1], block[i][2]])
}
pub(super) fn encode_dxt1(block: &Block) -> [u8; 8] {
encode_color(&rgb_of(block), false)
}
pub(super) fn encode_dxt5(block: &Block) -> [u8; 16] {
let a = encode_alpha(&std::array::from_fn(|i| block[i][3]));
let c = encode_color(&rgb_of(block), true);
let mut out = [0u8; 16];
out[..8].copy_from_slice(&a);
out[8..].copy_from_slice(&c);
out
}
pub(super) fn encode_bc4(block: &Block) -> [u8; 8] {
encode_alpha(&std::array::from_fn(|i| block[i][3]))
}
/// Encode a block as scaled YCoCg-DXT5.
pub(super) fn encode_ycocg(block: &Block) -> [u8; 16] {
// Co = (R - B) / 2, Cg = (2G - R - B) / 4, Y = (R + 2G + B) / 4, all in 8 bits.
let co2: [i32; 16] = std::array::from_fn(|i| i32::from(block[i][0]) - i32::from(block[i][2]));
let cg4: [i32; 16] = std::array::from_fn(|i| 2 * i32::from(block[i][1]) - i32::from(block[i][0]) - i32::from(block[i][2]));
let m2 = co2.iter().map(|v| v.abs()).max().unwrap_or(0); // twice the largest Co
let m4 = cg4.iter().map(|v| v.abs()).max().unwrap_or(0); // four times the largest Cg
let mag = (m2 / 2).max(m4 / 4);
let s: i32 = if mag <= 31 {
4
} else if mag <= 63 {
2
} else {
1
};
let colors: [[u8; 3]; 16] = std::array::from_fn(|i| {
let co = (128 + ((co2[i] * s + 1) >> 1)).clamp(0, 255) as u8;
let cg = (128 + ((cg4[i] * s + 2) >> 2)).clamp(0, 255) as u8;
[co, cg, ((s - 1) * 8) as u8]
});
let y: [u8; 16] = std::array::from_fn(|i| ((i32::from(block[i][0]) + 2 * i32::from(block[i][1]) + i32::from(block[i][2]) + 2) >> 2) as u8);
let mut out = [0u8; 16];
out[..8].copy_from_slice(&encode_alpha(&y));
out[8..].copy_from_slice(&encode_color(&colors, true));
out
}
+481
View File
@@ -0,0 +1,481 @@
//! Hap video (Vidvox Hap): frames of GPU block-compressed textures, with an optional Snappy
//! second stage, written from the public Hap specification, the Snappy format description and
//! the S3TC / RGTC block formats.
//!
//! A Hap frame is one top-level section: a header (3-byte little-endian size and a type byte, or a
//! zero size and an 8-byte header with a 4-byte size) and its data. The type byte names the
//! texture format (low nibble) and the second-stage compressor (high nibble: none, Snappy, or
//! "chunked", where a table says how the texture is cut into chunks and how each is compressed).
//! A frame of type `0x0D` holds two such sections, the scaled YCoCg and alpha textures of Hap Q
//! Alpha.
//!
//! - [`Decoder`] reads frames. [`Decoder::decode_textures`] gives the block data as stored, ready
//! for upload to a GPU; [`Decoder::decode_rgba`] decodes DXT1, DXT5, scaled YCoCg-DXT5 (Hap Q),
//! Hap Q Alpha and the alpha-only format to RGBA pictures in software. BC7 (Hap R) and BC6
//! (Hap HDR) frames are read, and their blocks returned, but not decoded to pictures.
//! - [`Encoder`] writes Hap, Hap Alpha, Hap Q, Hap Q Alpha and Hap Alpha-Only frames, optionally
//! Snappy-compressed and cut into chunks.
//!
//! The block compressors are range fits, not the slowest-and-best search a GPU-texture tool does:
//! the result is correct and decodes anywhere, but a little coarser than an exhaustive encoder's.
//! Decoding checks every size against the frame's dimensions before allocating, and a damaged frame
//! is an error, never a panic.
mod dxt;
mod snappy;
use crate::budget::DECODE_MEMORY_BUDGET;
/// Codec errors.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// The frame is damaged or not Hap.
#[error("invalid Hap frame: {0}")]
Invalid(String),
/// A valid frame this module does not decode to pictures.
#[error("unsupported Hap feature: {0}")]
Unsupported(String),
/// The dimensions or settings given cannot be used.
#[error("invalid Hap parameters: {0}")]
Input(String),
}
/// `Result` of this module.
pub type Result<T> = std::result::Result<T, Error>;
/// The largest width or height, in pixels.
pub const MAX_DIMENSION: u32 = 32768;
/// The texture formats a Hap frame can hold.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum TextureFormat {
/// RGB, DXT1 / BC1: 8 bytes per 4x4 block.
Dxt1,
/// RGBA, DXT5 / BC3: 16 bytes per block.
Dxt5,
/// Scaled YCoCg in DXT5 / BC3 (Hap Q): 16 bytes per block.
YcocgDxt5,
/// Alpha only, RGTC1 / BC4: 8 bytes per block.
Bc4Alpha,
/// RGBA, BPTC / BC7 (Hap R): 16 bytes per block.
Bc7,
/// Unsigned float RGB, BC6H (Hap HDR): 16 bytes per block.
Bc6Unsigned,
/// Signed float RGB, BC6H: 16 bytes per block.
Bc6Signed,
}
impl TextureFormat {
const fn nibble(self) -> u8 {
match self {
Self::Dxt1 => 0xB,
Self::Dxt5 => 0xE,
Self::YcocgDxt5 => 0xF,
Self::Bc4Alpha => 0x1,
Self::Bc7 => 0xC,
Self::Bc6Unsigned => 0x2,
Self::Bc6Signed => 0x3,
}
}
fn from_nibble(n: u8) -> Option<Self> {
Some(match n {
0xB => Self::Dxt1,
0xE => Self::Dxt5,
0xF => Self::YcocgDxt5,
0x1 => Self::Bc4Alpha,
0xC => Self::Bc7,
0x2 => Self::Bc6Unsigned,
0x3 => Self::Bc6Signed,
_ => return None,
})
}
/// Bytes of one 4x4 block.
#[must_use]
pub const fn block_bytes(self) -> usize {
match self {
Self::Dxt1 | Self::Bc4Alpha => 8,
_ => 16,
}
}
}
/// One texture of a frame: the block data as a GPU takes it (rows of 4x4 blocks, top to bottom,
/// the size rounded up to whole blocks).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Texture {
pub format: TextureFormat,
pub data: Vec<u8>,
}
/// A decoded picture: RGBA, 8 bits per channel, rows top to bottom.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Image {
pub width: u32,
pub height: u32,
pub rgba: Vec<u8>,
}
fn check_dimensions(width: u32, height: u32) -> Result<()> {
if width == 0 || height == 0 || width > MAX_DIMENSION || height > MAX_DIMENSION {
return Err(Error::Input(format!("{width}x{height} is not a size from 1 to {MAX_DIMENSION} pixels a side")));
}
if u64::from(width) * u64::from(height) * 4 > DECODE_MEMORY_BUDGET / 4 {
return Err(Error::Input(format!("{width}x{height} is above the memory budget")));
}
Ok(())
}
fn blocks(width: u32, height: u32) -> (usize, usize) {
(width.div_ceil(4) as usize, height.div_ceil(4) as usize)
}
fn texture_bytes(format: TextureFormat, width: u32, height: u32) -> usize {
let (bx, by) = blocks(width, height);
bx * by * format.block_bytes()
}
// ------------------------------------------------------------------------------------ sections
/// Split a section off the front of `data`: its type, its payload and what follows it.
fn section(data: &[u8]) -> Result<(u8, &[u8], &[u8])> {
let bad = || Error::Invalid("section header or size out of range".into());
let head = data.get(..4).ok_or_else(bad)?;
let (mut size, mut start) = (usize::from(head[0]) | usize::from(head[1]) << 8 | usize::from(head[2]) << 16, 4usize);
if size == 0 {
let ext = data.get(4..8).ok_or_else(bad)?;
size = u32::from_le_bytes([ext[0], ext[1], ext[2], ext[3]]) as usize;
start = 8;
}
let end = start.checked_add(size).ok_or_else(bad)?;
let payload = data.get(start..end).ok_or_else(bad)?;
Ok((head[3], payload, &data[end..]))
}
fn write_section(out: &mut Vec<u8>, kind: u8, payload: &[u8]) {
if payload.len() < 1 << 24 && !payload.is_empty() {
out.extend_from_slice(&[payload.len() as u8, (payload.len() >> 8) as u8, (payload.len() >> 16) as u8, kind]);
} else {
out.extend_from_slice(&[0, 0, 0, kind]);
out.extend_from_slice(&(payload.len() as u32).to_le_bytes());
}
out.extend_from_slice(payload);
}
const SECTION_MULTIPLE: u8 = 0x0D;
const SECTION_INSTRUCTIONS: u8 = 0x01;
const SECTION_COMPRESSORS: u8 = 0x02;
const SECTION_SIZES: u8 = 0x03;
const SECTION_OFFSETS: u8 = 0x04;
const CHUNK_NONE: u8 = 0x0A;
const CHUNK_SNAPPY: u8 = 0x0B;
/// The uncompressed length a Snappy stream declares.
fn snappy_len(src: &[u8]) -> Option<usize> {
let (mut len, mut shift) = (0u64, 0u32);
for &b in src.iter().take(5) {
len |= u64::from(b & 0x7F) << shift;
if b & 0x80 == 0 {
return usize::try_from(len).ok();
}
shift += 7;
}
None
}
/// Decode one texture section holding `expected` bytes of the given format; returns the texture
/// and the bytes after the section.
fn decode_section(data: &[u8], width: u32, height: u32) -> Result<(Texture, &[u8])> {
let (kind, payload, rest) = section(data)?;
let format = TextureFormat::from_nibble(kind & 0x0F).ok_or_else(|| Error::Unsupported(format!("texture type {:#04x}", kind)))?;
let expected = texture_bytes(format, width, height);
let bytes = match kind >> 4 {
0xA => {
if payload.len() != expected {
return Err(Error::Invalid(format!("texture of {} bytes, expected {expected}", payload.len())));
}
payload.to_vec()
}
0xB => snappy::decompress(payload, expected)?,
0xC => decode_chunks(payload, expected)?,
_ => return Err(Error::Unsupported(format!("second-stage compressor in type {:#04x}", kind))),
};
Ok((Texture { format, data: bytes }, rest))
}
fn decode_chunks(payload: &[u8], expected: usize) -> Result<Vec<u8>> {
let bad = |m: &str| Error::Invalid(format!("decode instructions: {m}"));
let (kind, instructions, data) = section(payload)?;
if kind != SECTION_INSTRUCTIONS {
return Err(bad("not a decode instructions container"));
}
let (mut compressors, mut sizes, mut offsets) = (None, None, None);
let mut rest = instructions;
while !rest.is_empty() {
let (k, body, next) = section(rest)?;
match k {
SECTION_COMPRESSORS => compressors = Some(body),
SECTION_SIZES => sizes = Some(body),
SECTION_OFFSETS => offsets = Some(body),
_ => {} // unknown sub-sections are skipped
}
rest = next;
}
let (compressors, sizes) = compressors.zip(sizes).ok_or_else(|| bad("missing the compressor or size table"))?;
let count = compressors.len();
if sizes.len() != count * 4 || offsets.is_some_and(|o| o.len() != count * 4) {
return Err(bad("the tables differ in length"));
}
let word = |t: &[u8], i: usize| u32::from_le_bytes([t[4 * i], t[4 * i + 1], t[4 * i + 2], t[4 * i + 3]]) as usize;
let mut out = Vec::with_capacity(expected);
let mut running = 0usize;
for (i, &compressor) in compressors.iter().enumerate() {
let size = word(sizes, i);
let offset = offsets.map_or(running, |o| word(o, i));
running = offset.checked_add(size).ok_or_else(|| bad("chunk out of range"))?;
let chunk = data.get(offset..running).ok_or_else(|| bad("chunk out of range"))?;
match compressor {
CHUNK_NONE => {
if out.len() + chunk.len() > expected {
return Err(bad("chunks exceed the texture"));
}
out.extend_from_slice(chunk);
}
CHUNK_SNAPPY => {
let n = snappy_len(chunk).ok_or_else(|| bad("damaged Snappy chunk"))?;
if out.len() + n > expected {
return Err(bad("chunks exceed the texture"));
}
out.extend_from_slice(&snappy::decompress(chunk, n)?);
}
other => return Err(Error::Unsupported(format!("chunk compressor {other:#04x}"))),
}
}
if out.len() != expected {
return Err(bad("chunks do not fill the texture"));
}
Ok(out)
}
// ------------------------------------------------------------------------------------ decoder
/// A Hap decoder for frames of one size. Every frame is independent.
#[derive(Debug, Clone)]
pub struct Decoder {
width: u32,
height: u32,
}
impl Decoder {
/// A decoder for `width` x `height` frames.
pub fn new(width: u32, height: u32) -> Result<Self> {
check_dimensions(width, height)?;
Ok(Self { width, height })
}
/// The textures of one frame, as stored: one, or two for Hap Q Alpha.
pub fn decode_textures(&self, frame: &[u8]) -> Result<Vec<Texture>> {
let (kind, payload, _) = section(frame)?;
if kind != SECTION_MULTIPLE {
return Ok(vec![decode_section(frame, self.width, self.height)?.0]);
}
let mut textures = Vec::new();
let mut rest = payload;
while !rest.is_empty() {
if textures.len() == 2 {
return Err(Error::Invalid("more than two images".into()));
}
let (t, next) = decode_section(rest, self.width, self.height)?;
textures.push(t);
rest = next;
}
if textures.is_empty() {
return Err(Error::Invalid("no images".into()));
}
Ok(textures)
}
/// Decode one frame to an RGBA picture.
pub fn decode_rgba(&self, frame: &[u8]) -> Result<Image> {
let textures = self.decode_textures(frame)?;
let formats: Vec<TextureFormat> = textures.iter().map(|t| t.format).collect();
let (w, h) = (self.width as usize, self.height as usize);
let mut rgba = vec![0u8; w * h * 4];
let (bx, by) = blocks(self.width, self.height);
let alpha_tex = match formats.as_slice() {
[TextureFormat::YcocgDxt5, TextureFormat::Bc4Alpha] => textures.get(1),
[TextureFormat::Dxt1] | [TextureFormat::Dxt5] | [TextureFormat::YcocgDxt5] | [TextureFormat::Bc4Alpha] => None,
[TextureFormat::Bc7 | TextureFormat::Bc6Unsigned | TextureFormat::Bc6Signed] => {
return Err(Error::Unsupported("BC7 and BC6H textures are not decoded to pictures".into()));
}
_ => return Err(Error::Unsupported("this combination of textures".into())),
};
let main = &textures[0];
let bb = main.format.block_bytes();
for j in 0..by {
for i in 0..bx {
let at = (j * bx + i) * bb;
let block = &main.data[at..at + bb];
let mut px = match main.format {
TextureFormat::Dxt1 => dxt::decode_dxt1(block),
TextureFormat::Dxt5 => dxt::decode_dxt5(block),
TextureFormat::YcocgDxt5 => dxt::decode_ycocg(block),
_ => {
let a = dxt::decode_bc4(block);
std::array::from_fn(|k| [255, 255, 255, a[k]])
}
};
if let Some(t) = alpha_tex {
let a = dxt::decode_bc4(&t.data[(j * bx + i) * 8..(j * bx + i) * 8 + 8]);
for (p, a) in px.iter_mut().zip(a) {
p[3] = a;
}
}
for (k, p) in px.iter().enumerate() {
let (x, y) = (i * 4 + k % 4, j * 4 + k / 4);
if x < w && y < h {
rgba[(y * w + x) * 4..(y * w + x) * 4 + 4].copy_from_slice(p);
}
}
}
}
Ok(Image { width: self.width, height: self.height, rgba })
}
}
// ------------------------------------------------------------------------------------ encoder
/// The Hap variants the encoder writes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Variant {
/// Hap: RGB in DXT1 (`Hap1`).
Hap,
/// Hap Alpha: RGBA in DXT5 (`Hap5`).
HapAlpha,
/// Hap Q: scaled YCoCg in DXT5 (`HapY`), higher quality, no alpha.
HapQ,
/// Hap Q Alpha: scaled YCoCg plus a BC4 alpha texture (`HapM`).
HapQAlpha,
/// Hap Alpha-Only: BC4 alpha (`HapA`).
HapAlphaOnly,
}
impl Variant {
/// The codec's FourCC.
#[must_use]
pub const fn fourcc(self) -> [u8; 4] {
match self {
Self::Hap => *b"Hap1",
Self::HapAlpha => *b"Hap5",
Self::HapQ => *b"HapY",
Self::HapQAlpha => *b"HapM",
Self::HapAlphaOnly => *b"HapA",
}
}
}
/// A Hap encoder for frames of one size and variant.
#[derive(Debug, Clone)]
pub struct Encoder {
width: u32,
height: u32,
variant: Variant,
snappy: bool,
chunks: usize,
}
impl Encoder {
/// An encoder with no second stage and no chunks.
pub fn new(width: u32, height: u32, variant: Variant) -> Result<Self> {
check_dimensions(width, height)?;
Ok(Self { width, height, variant, snappy: false, chunks: 1 })
}
/// Compress the textures with Snappy.
#[must_use]
pub fn with_snappy(mut self, on: bool) -> Self {
self.snappy = on;
self
}
/// Cut each texture into `n` chunks (at least 1), which a decoder can decompress in parallel.
#[must_use]
pub fn with_chunks(mut self, n: usize) -> Self {
self.chunks = n.clamp(1, 4096);
self
}
/// Encode one RGBA picture (`width * height * 4` bytes) as a Hap frame.
pub fn encode_rgba(&self, rgba: &[u8]) -> Result<Vec<u8>> {
let (w, h) = (self.width as usize, self.height as usize);
if rgba.len() != w * h * 4 {
return Err(Error::Input(format!("{} bytes of pixels for {w}x{h}", rgba.len())));
}
let (bx, by) = blocks(self.width, self.height);
let block_at = |i: usize, j: usize| -> dxt::Block {
std::array::from_fn(|k| {
// Pixels past the edge repeat the last row and column.
let (x, y) = ((i * 4 + k % 4).min(w - 1), (j * 4 + k / 4).min(h - 1));
let p = (y * w + x) * 4;
[rgba[p], rgba[p + 1], rgba[p + 2], rgba[p + 3]]
})
};
let build = |format: TextureFormat, f: &dyn Fn(&dxt::Block) -> Vec<u8>| -> Texture {
let mut data = Vec::with_capacity(bx * by * format.block_bytes());
for j in 0..by {
for i in 0..bx {
data.extend_from_slice(&f(&block_at(i, j)));
}
}
Texture { format, data }
};
let mut out = Vec::new();
match self.variant {
Variant::Hap => self.write_texture(&mut out, &build(TextureFormat::Dxt1, &|b| dxt::encode_dxt1(b).to_vec())),
Variant::HapAlpha => self.write_texture(&mut out, &build(TextureFormat::Dxt5, &|b| dxt::encode_dxt5(b).to_vec())),
Variant::HapQ => self.write_texture(&mut out, &build(TextureFormat::YcocgDxt5, &|b| dxt::encode_ycocg(b).to_vec())),
Variant::HapAlphaOnly => self.write_texture(&mut out, &build(TextureFormat::Bc4Alpha, &|b| dxt::encode_bc4(b).to_vec())),
Variant::HapQAlpha => {
let mut inner = Vec::new();
self.write_texture(&mut inner, &build(TextureFormat::YcocgDxt5, &|b| dxt::encode_ycocg(b).to_vec()));
self.write_texture(&mut inner, &build(TextureFormat::Bc4Alpha, &|b| dxt::encode_bc4(b).to_vec()));
write_section(&mut out, SECTION_MULTIPLE, &inner);
}
}
Ok(out)
}
fn write_texture(&self, out: &mut Vec<u8>, t: &Texture) {
let nibble = t.format.nibble();
if self.chunks <= 1 {
if self.snappy {
write_section(out, 0xB0 | nibble, &snappy::compress(&t.data));
} else {
write_section(out, 0xA0 | nibble, &t.data);
}
return;
}
// Chunks of whole blocks, as even as they go.
let bb = t.format.block_bytes();
let total_blocks = t.data.len() / bb;
let n = self.chunks.min(total_blocks).max(1);
let (mut compressors, mut sizes, mut data) = (Vec::new(), Vec::new(), Vec::new());
for c in 0..n {
let (from, to) = (c * total_blocks / n * bb, (c + 1) * total_blocks / n * bb);
let raw = &t.data[from..to];
let packed = if self.snappy { Some(snappy::compress(raw)).filter(|p| p.len() < raw.len()) } else { None };
let (kind, body) = packed.as_deref().map_or((CHUNK_NONE, raw), |p| (CHUNK_SNAPPY, p));
compressors.push(kind);
sizes.extend_from_slice(&(body.len() as u32).to_le_bytes());
data.extend_from_slice(body);
}
let mut instructions = Vec::new();
write_section(&mut instructions, SECTION_COMPRESSORS, &compressors);
write_section(&mut instructions, SECTION_SIZES, &sizes);
let mut payload = Vec::new();
write_section(&mut payload, SECTION_INSTRUCTIONS, &instructions);
payload.extend_from_slice(&data);
write_section(out, 0xC0 | nibble, &payload);
}
}
+233
View File
@@ -0,0 +1,233 @@
//! Snappy raw (unframed) compression, written from the public Snappy format description: a varint
//! of the uncompressed length, then literal and copy elements. Hap uses it as the second-stage
//! compressor of its texture data.
use super::Error;
/// Decompress `src`, which must expand to exactly `expected` bytes. The length in the preamble is
/// checked before anything is allocated, so a hostile stream cannot ask for more than `expected`.
pub(super) fn decompress(src: &[u8], expected: usize) -> Result<Vec<u8>, Error> {
let bad = || Error::Invalid("Snappy data is damaged".into());
// The varint preamble.
let (mut len, mut shift, mut pos) = (0u64, 0u32, 0usize);
loop {
let b = *src.get(pos).ok_or_else(bad)?;
pos += 1;
len |= u64::from(b & 0x7F) << shift;
if b & 0x80 == 0 {
break;
}
shift += 7;
if shift > 28 {
return Err(bad());
}
}
if len != expected as u64 {
return Err(Error::Invalid(format!("Snappy data expands to {len} bytes, expected {expected}")));
}
let mut out: Vec<u8> = Vec::with_capacity(expected);
while pos < src.len() {
let tag = src[pos];
pos += 1;
match tag & 3 {
0 => {
let mut n = usize::from(tag >> 2);
if n >= 60 {
let extra = n - 59;
let bytes = src.get(pos..pos + extra).ok_or_else(bad)?;
n = bytes.iter().rev().fold(0usize, |a, &b| (a << 8) | usize::from(b));
pos += extra;
}
n += 1;
let lit = src.get(pos..pos.checked_add(n).ok_or_else(bad)?).ok_or_else(bad)?;
if out.len() + n > expected {
return Err(bad());
}
out.extend_from_slice(lit);
pos += n;
}
kind => {
let (n, offset) = match kind {
1 => {
let b = *src.get(pos).ok_or_else(bad)?;
pos += 1;
(4 + usize::from((tag >> 2) & 7), (usize::from(tag >> 5) << 8) | usize::from(b))
}
2 => {
let b = src.get(pos..pos + 2).ok_or_else(bad)?;
pos += 2;
(usize::from(tag >> 2) + 1, usize::from(u16::from_le_bytes([b[0], b[1]])))
}
_ => {
let b = src.get(pos..pos + 4).ok_or_else(bad)?;
pos += 4;
(usize::from(tag >> 2) + 1, u32::from_le_bytes([b[0], b[1], b[2], b[3]]) as usize)
}
};
if offset == 0 || offset > out.len() || out.len() + n > expected {
return Err(bad());
}
// Copies may overlap their own output, so go byte by byte.
let start = out.len() - offset;
for i in 0..n {
let b = out[start + i];
out.push(b);
}
}
}
}
if out.len() != expected {
return Err(bad());
}
Ok(out)
}
fn push_literal(out: &mut Vec<u8>, lit: &[u8]) {
let mut rest = lit;
while !rest.is_empty() {
let n = rest.len().min(1 << 24);
let (now, later) = rest.split_at(n);
let m = n - 1;
if m < 60 {
out.push((m as u8) << 2);
} else if m < 1 << 8 {
out.extend_from_slice(&[60 << 2, m as u8]);
} else if m < 1 << 16 {
out.extend_from_slice(&[61 << 2, m as u8, (m >> 8) as u8]);
} else {
out.extend_from_slice(&[62 << 2, m as u8, (m >> 8) as u8, (m >> 16) as u8]);
}
out.extend_from_slice(now);
rest = later;
}
}
fn push_copy(out: &mut Vec<u8>, offset: usize, mut len: usize) {
while len > 0 {
// Copies of 4 to 11 bytes at offsets below 2048 take two bytes; the rest take three.
let n = if len >= 68 {
64
} else if len > 64 {
60
} else {
len
};
if (4..=11).contains(&n) && offset < 2048 {
out.push(1 | (((n - 4) as u8) << 2) | (((offset >> 8) as u8) << 5));
out.push(offset as u8);
} else {
out.push(2 | (((n - 1) as u8) << 2));
out.extend_from_slice(&(offset as u16).to_le_bytes());
}
len -= n;
}
}
/// Compress `src` into a Snappy stream: greedy matching over a hash of four bytes, offsets up to
/// 64 KiB.
pub(super) fn compress(src: &[u8]) -> Vec<u8> {
let mut out = Vec::with_capacity(src.len() / 2 + 16);
let mut n = src.len();
loop {
let b = (n & 0x7F) as u8;
n >>= 7;
if n == 0 {
out.push(b);
break;
}
out.push(b | 0x80);
}
const BITS: u32 = 15;
let mut table = vec![usize::MAX; 1 << BITS];
let hash = |i: usize| -> usize {
let v = u32::from_le_bytes([src[i], src[i + 1], src[i + 2], src[i + 3]]);
(v.wrapping_mul(0x1E35_A7BD) >> (32 - BITS)) as usize
};
let (mut i, mut lit_start) = (0usize, 0usize);
while i + 4 <= src.len() {
let h = hash(i);
let cand = table[h];
table[h] = i;
if cand != usize::MAX && i - cand <= 65535 && src[cand..cand + 4] == src[i..i + 4] {
let mut len = 4;
while i + len < src.len() && src[cand + len] == src[i + len] {
len += 1;
}
push_literal(&mut out, &src[lit_start..i]);
push_copy(&mut out, i - cand, len);
i += len;
lit_start = i;
} else {
i += 1;
}
}
push_literal(&mut out, &src[lit_start..]);
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn round_trips_assorted_data() {
let mut seed = 1u32;
let mut noise = Vec::new();
for _ in 0..5000 {
seed ^= seed << 13;
seed ^= seed >> 17;
seed ^= seed << 5;
noise.push(seed as u8);
}
let cases: Vec<Vec<u8>> = vec![
vec![],
vec![7],
vec![1, 2, 3],
vec![0; 100_000],
(0..70_000u32).map(|i| (i % 251) as u8).collect(),
noise.clone(),
[noise.clone(), noise].concat(),
b"abcabcabcabcabcabcabcabcabcabcabcabcabcabcabc".repeat(20),
];
for data in cases {
let packed = compress(&data);
assert_eq!(decompress(&packed, data.len()).expect("decompress"), data, "len {}", data.len());
}
}
#[test]
fn repetitive_data_gets_smaller() {
assert!(compress(&vec![5u8; 50_000]).len() < 3_000);
}
#[test]
fn decodes_the_format_description_forms() {
// A literal, then a 1-byte-offset copy that overlaps its own output.
let s = [9, 0x0C, b'a', b'b', b'c', b'd', 0b0000_0101, 4];
// "abcd" + copy len 4+... : length field (5>>2)&7 = 1 -> 5 bytes, offset 4 -> total 9.
assert_eq!(decompress(&s, 9).expect("decode"), b"abcdabcda");
// A literal of 61 bytes uses the extra-length form.
let mut s = vec![61, 60 << 2, 60];
s.extend_from_slice(&[3; 61]);
assert_eq!(decompress(&s, 61).expect("decode"), vec![3; 61]);
}
#[test]
fn hostile_streams_are_errors() {
// Wrong length in the preamble.
assert!(decompress(&[5, 0x00, b'x'], 10).is_err());
// Copy before any output.
assert!(decompress(&[4, 0b0000_0001, 1], 4).is_err());
// Offset of zero.
assert!(decompress(&[8, 0x0C, b'a', b'b', b'c', b'd', 0b0000_0001, 0], 8).is_err());
// Literal longer than the stream.
assert!(decompress(&[4, 0x0C, b'a'], 4).is_err());
// Overlong varint.
assert!(decompress(&[0x80, 0x80, 0x80, 0x80, 0x80, 0x01], 0).is_err());
// Output past the stated length.
assert!(decompress(&[2, 0x0C, b'a', b'b', b'c', b'd'], 2).is_err());
// Too short.
assert!(decompress(&[4, 0x00, b'a'], 4).is_err());
assert!(decompress(&[], 0).is_err());
}
}
+4
View File
@@ -11,6 +11,7 @@
//! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder (`mpeg2-decode`) and MPEG-2 I/P/B encoder (`mpeg2-encode`) |
//! | `mpeg4` | [`mpeg4`] | MPEG-4 Part 2 video (ISO/IEC 14496-2, Xvid/DivX): Simple profile encoder (`mpeg4-encode`) |
//! | `ffv1` | [`ffv1`] | FFV1 lossless video (RFC 9043): version 3, range coder, decoder and encoder |
//! | `hap` | [`hap`] | Vidvox Hap, Hap Alpha, Hap Q, Hap Q Alpha, Hap Alpha-Only: decoder and encoder |
//! | `mjpeg` | [`mjpeg`] | Motion JPEG: frame-level decoder and baseline encoder over `craft-jpeg` |
//! | `prores` | [`prores`] | Apple ProRes (SMPTE RDD 36): decoder and encoder |
//! | `h264` | [`h264`] | ITU-T H.264 / AVC: decoder (`h264-decode`) and encoder (`h264-encode`) |
@@ -46,6 +47,9 @@ pub mod mpeg4;
#[cfg(feature = "ffv1")]
pub mod ffv1;
#[cfg(feature = "hap")]
pub mod hap;
#[cfg(feature = "mjpeg")]
pub mod mjpeg;
+315
View File
@@ -0,0 +1,315 @@
//! Hap tests: round trips, chunking, hostile input, and ffmpeg's decoder as the reference (oracle;
//! skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). ffmpeg has no
//! Hap encoder here, so the oracle is one-way: it decodes the frames our encoder writes, in an AVI
//! file, to the pictures our decoder returns.
use craft_media::avi::{AviWriter, MuxOptions, StreamSpec, VideoSpec};
use craft_video::hap::{Decoder, Encoder, Error, Image, TextureFormat, Variant};
use std::path::Path;
use std::process::Command;
fn xorshift(seed: &mut u32) -> u32 {
*seed ^= *seed << 13;
*seed ^= *seed >> 17;
*seed ^= *seed << 5;
*seed
}
/// A picture of smooth gradients, hard edges, noise, flat areas and a soft alpha ramp.
fn picture(w: u32, h: u32, salt: u32) -> Vec<u8> {
let mut seed = 0x9E37_79B9u32 ^ salt;
let mut out = Vec::new();
for y in 0..h {
for x in 0..w {
let (r, g, b) = match (y / 13 + x / 29) % 4 {
0 => ((x * 3 + salt) as u8, (y * 4) as u8, ((x + y) * 2) as u8),
1 => (xorshift(&mut seed) as u8, xorshift(&mut seed) as u8, xorshift(&mut seed) as u8),
2 => (200, 40, 90),
_ => (if (x / 3) % 2 == 0 { 255 } else { 0 }, 128, if (y / 3) % 2 == 0 { 255 } else { 0 }),
};
out.extend_from_slice(&[r, g, b, (x * 255 / w.max(1)) as u8]);
}
}
out
}
/// Gradients, edges and flat areas, with no noise, the kind of picture block compression suits.
fn smooth(w: u32, h: u32) -> Vec<u8> {
let mut out = Vec::new();
for y in 0..h {
for x in 0..w {
let (r, g, b) = match (y / 16 + x / 24) % 3 {
0 => ((x * 255 / w.max(1)) as u8, (y * 255 / h.max(1)) as u8, 128),
1 => (230, 60, 20),
_ => (if (x / 8) % 2 == 0 { 250 } else { 10 }, 120, 40),
};
out.extend_from_slice(&[r, g, b, (x * 255 / w.max(1)) as u8]);
}
}
out
}
fn psnr(a: &[u8], b: &[u8], channels: usize) -> f64 {
let (mut err, mut n) = (0f64, 0f64);
for (p, q) in a.chunks(4).zip(b.chunks(4)) {
for c in 0..channels {
err += (f64::from(p[c]) - f64::from(q[c])).powi(2);
n += 1.0;
}
}
if err == 0.0 { 99.0 } else { 10.0 * (255.0 * 255.0 * n / err).log10() }
}
const VARIANTS: [Variant; 5] = [Variant::Hap, Variant::HapAlpha, Variant::HapQ, Variant::HapQAlpha, Variant::HapAlphaOnly];
fn channels(v: Variant) -> usize {
match v {
Variant::HapAlpha | Variant::HapQAlpha => 4,
_ => 3,
}
}
#[test]
fn every_variant_round_trips_at_good_quality() {
for (w, h) in [(64u32, 48u32), (130, 70), (4, 4), (1, 1), (17, 5)] {
let src = smooth(w, h);
for v in VARIANTS {
for (snappy, chunks) in [(false, 1usize), (true, 1), (false, 3), (true, 4)] {
let enc = Encoder::new(w, h, v).expect("encoder").with_snappy(snappy).with_chunks(chunks);
let frame = enc.encode_rgba(&src).expect("encode");
let img = Decoder::new(w, h).expect("decoder").decode_rgba(&frame).expect("decode");
assert_eq!((img.width, img.height, img.rgba.len()), (w, h, (w * h * 4) as usize));
if v == Variant::HapAlphaOnly {
let (a, b): (Vec<u8>, Vec<u8>) = (src.chunks(4).map(|p| p[3]).collect(), img.rgba.chunks(4).map(|p| p[3]).collect());
let worst = a.iter().zip(&b).map(|(x, y)| x.abs_diff(*y)).max().unwrap_or(0);
assert!(worst <= 16, "{v:?} {w}x{h}: alpha off by {worst}");
} else if w >= 16 && h >= 16 {
let q = psnr(&src, &img.rgba, channels(v).min(3));
assert!(q > 30.0, "{v:?} {w}x{h} snappy={snappy} chunks={chunks}: {q:.1} dB");
}
}
}
}
}
#[test]
fn snappy_and_chunks_do_not_change_the_pixels() {
let (w, h) = (96, 64);
let src = picture(w, h, 3);
for v in VARIANTS {
let want = Decoder::new(w, h).expect("d").decode_rgba(&Encoder::new(w, h, v).expect("e").encode_rgba(&src).expect("enc")).expect("dec");
for (snappy, chunks) in [(true, 1usize), (false, 5), (true, 7), (true, 600)] {
let frame = Encoder::new(w, h, v).expect("e").with_snappy(snappy).with_chunks(chunks).encode_rgba(&src).expect("enc");
let got = Decoder::new(w, h).expect("d").decode_rgba(&frame).expect("dec");
assert_eq!(got, want, "{v:?} snappy={snappy} chunks={chunks}");
}
}
}
#[test]
fn flat_colours_are_exact_in_rgb_variants() {
let (w, h) = (32, 32);
for v in [Variant::Hap, Variant::HapAlpha, Variant::HapQ, Variant::HapQAlpha] {
for rgb in [[0u8, 0, 0], [255, 255, 255], [255, 0, 0], [0, 255, 0], [0, 0, 255], [8, 16, 24]] {
let src: Vec<u8> = (0..w * h).flat_map(|_| [rgb[0], rgb[1], rgb[2], 255]).collect();
let frame = Encoder::new(w, h, v).expect("e").encode_rgba(&src).expect("enc");
let img = Decoder::new(w, h).expect("d").decode_rgba(&frame).expect("dec");
let worst = src.iter().zip(&img.rgba).map(|(a, b)| a.abs_diff(*b)).max().unwrap_or(0);
// 565 endpoints and the YCoCg round trip put a flat colour within a few levels.
assert!(worst <= 8, "{v:?} {rgb:?}: off by {worst}");
}
}
}
#[test]
fn textures_come_back_as_stored() {
let src = picture(64, 32, 1);
let frame = Encoder::new(64, 32, Variant::HapQAlpha).expect("e").with_snappy(true).encode_rgba(&src).expect("enc");
let t = Decoder::new(64, 32).expect("d").decode_textures(&frame).expect("textures");
assert_eq!(t.len(), 2);
assert_eq!((t[0].format, t[0].data.len()), (TextureFormat::YcocgDxt5, 16 * 8 * 16));
assert_eq!((t[1].format, t[1].data.len()), (TextureFormat::Bc4Alpha, 16 * 8 * 8));
assert_eq!(Variant::HapQAlpha.fourcc(), *b"HapM");
}
#[test]
fn offsets_table_and_unknown_sections_are_honoured() {
// A chunked frame built by hand: two chunks, stored out of order through an offset table, and
// a sub-section of an unknown type that must be skipped.
let tex: Vec<u8> = (0..16 * 8).map(|i| i as u8).collect(); // 16 DXT1 blocks = 16x16 pixels
let sect = |kind: u8, p: &[u8]| {
let mut v = vec![p.len() as u8, (p.len() >> 8) as u8, (p.len() >> 16) as u8, kind];
v.extend_from_slice(p);
v
};
let (first, second) = tex.split_at(64);
let data = [second, first].concat(); // second half stored first
let mut ins = sect(0x02, &[0x0A, 0x0A]);
ins.extend(sect(0x7F, b"junk"));
ins.extend(sect(0x03, &[[64u32, 64].map(u32::to_le_bytes)].concat().concat()));
ins.extend(sect(0x04, &[[64u32, 0].map(u32::to_le_bytes)].concat().concat()));
let mut payload = sect(0x01, &ins);
payload.extend_from_slice(&data);
let frame = sect(0xCB, &payload);
let t = Decoder::new(16, 16).expect("d").decode_textures(&frame).expect("textures");
assert_eq!(t[0].data, tex);
}
#[test]
fn big_sections_use_the_long_header() {
// 1024 x 1024 DXT5 is 1 MiB; at 4096 x 4096 a section tops 16 MiB and needs the 8-byte header.
let (w, h) = (4096u32, 4096u32);
let src = vec![77u8; (w * h * 4) as usize];
let frame = Encoder::new(w, h, Variant::HapAlpha).expect("e").encode_rgba(&src).expect("enc");
assert_eq!(&frame[..3], &[0, 0, 0]);
assert_eq!(frame[3], 0xAE);
let t = Decoder::new(w, h).expect("d").decode_textures(&frame).expect("textures");
assert_eq!(t[0].data.len(), 1024 * 1024 * 16);
}
#[test]
fn bad_parameters_are_errors() {
assert!(matches!(Decoder::new(0, 10), Err(Error::Input(_))));
assert!(matches!(Decoder::new(40_000, 10), Err(Error::Input(_))));
assert!(matches!(Encoder::new(10, 0, Variant::Hap), Err(Error::Input(_))));
assert!(matches!(Encoder::new(32768, 32768, Variant::Hap), Err(Error::Input(_))));
let e = Encoder::new(8, 8, Variant::Hap).expect("e");
assert!(matches!(e.encode_rgba(&[0; 10]), Err(Error::Input(_))));
}
#[test]
fn hostile_frames_are_errors_not_panics() {
let (w, h) = (32, 32);
let d = Decoder::new(w, h).expect("d");
let src = picture(w, h, 9);
let good = Encoder::new(w, h, Variant::HapQAlpha).expect("e").with_snappy(true).with_chunks(3).encode_rgba(&src).expect("enc");
assert!(d.decode_rgba(&good).is_ok());
// Every truncation.
for n in 0..good.len() {
assert!(d.decode_rgba(&good[..n]).is_err(), "truncated to {n}");
}
// Every single-byte corruption must be handled, with an error or a picture.
let mut seed = 3u32;
for _ in 0..3000 {
let mut bad = good.clone();
let i = xorshift(&mut seed) as usize % bad.len();
bad[i] = xorshift(&mut seed) as u8;
let _ = d.decode_rgba(&bad);
}
// Random bytes with plausible headers.
for kind in [0xAB, 0xBB, 0xCB, 0xAE, 0xBF, 0xCF, 0xA1, 0xB1, 0xC1, 0x0D, 0xAC, 0xA2, 0x00, 0xFF] {
for len in [0usize, 1, 3, 4, 8, 100] {
let mut f = vec![len as u8, 0, 0, kind];
f.extend((0..len).map(|_| xorshift(&mut seed) as u8));
let _ = d.decode_textures(&f);
let _ = d.decode_rgba(&f);
}
}
// Sizes that overflow or lie.
assert!(d.decode_rgba(&[0, 0, 0, 0xAB, 0xFF, 0xFF, 0xFF, 0xFF]).is_err());
assert!(d.decode_rgba(&[0xFF, 0xFF, 0xFF, 0xAB]).is_err());
assert!(d.decode_rgba(&[]).is_err());
// BC7 frames are read but not turned into pictures.
let mut bc7 = vec![0, 4, 0, 0xAC];
bc7.extend(vec![0u8; 1024]);
assert!(d.decode_textures(&bc7).is_ok());
assert!(matches!(d.decode_rgba(&bc7), Err(Error::Unsupported(_))));
}
fn ffmpeg_pictures(ffmpeg: &Path, avi: &Path, pix_fmt: &str) -> Vec<u8> {
let out = Command::new(ffmpeg)
.args(["-hide_banner", "-nostdin", "-v", "error", "-i"])
.arg(avi)
.args(["-f", "rawvideo", "-pix_fmt", pix_fmt, "-"])
.output()
.expect("run ffmpeg");
assert!(out.status.success(), "ffmpeg failed on {}: {}", avi.display(), String::from_utf8_lossy(&out.stderr));
out.stdout
}
fn avi_of(fourcc: [u8; 4], w: u32, h: u32, frames: &[Vec<u8>]) -> Vec<u8> {
let spec = VideoSpec::new(fourcc, w, h, 25, 1);
let mut mux = AviWriter::new(std::io::Cursor::new(Vec::new()), vec![StreamSpec::Video(spec)], MuxOptions::default()).expect("writer");
for f in frames {
mux.write_chunk(0, f, true).expect("chunk");
}
mux.finish().expect("finish").into_inner()
}
#[test]
fn ffmpeg_decodes_our_frames_to_our_pictures() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("hap");
let mut worst_overall = 0u8;
for (w, h) in [(64u32, 48u32), (130, 70), (36, 20)] {
for v in VARIANTS {
for (snappy, chunks) in [(false, 1usize), (true, 1), (true, 4), (false, 3)] {
let enc = Encoder::new(w, h, v).expect("e").with_snappy(snappy).with_chunks(chunks);
let dec = Decoder::new(w, h).expect("d");
let pics: Vec<Image> = (0..3).map(|i| dec.decode_rgba(&enc.encode_rgba(&picture(w, h, i)).expect("enc")).expect("dec")).collect();
let frames: Vec<Vec<u8>> = (0..3).map(|i| enc.encode_rgba(&picture(w, h, i)).expect("enc")).collect();
let name = format!("{}_{w}x{h}_{}_{chunks}.avi", String::from_utf8_lossy(&v.fourcc()), u8::from(snappy));
let file = dir.join(&name);
std::fs::write(&file, avi_of(v.fourcc(), w, h, &frames)).expect("write fixture");
let theirs = ffmpeg_pictures(&ffmpeg, &file, "rgba");
let n = (w * h * 4) as usize;
assert_eq!(theirs.len(), 3 * n, "{name}: ffmpeg returned {} bytes", theirs.len());
for (i, pic) in pics.iter().enumerate() {
let t = &theirs[i * n..(i + 1) * n];
let worst = if v == Variant::HapAlphaOnly {
// ffmpeg decodes the alpha-only format to a grey picture.
pic.rgba.chunks(4).zip(t.chunks(4)).map(|(a, b)| a[3].abs_diff(b[0])).max().unwrap_or(0)
} else {
// Hap1 and HapY have no alpha: compare colour only.
let c = channels(v);
pic.rgba.chunks(4).zip(t.chunks(4)).flat_map(|(a, b)| (0..c).map(move |k| a[k].abs_diff(b[k]))).max().unwrap_or(0)
};
worst_overall = worst_overall.max(worst);
assert!(worst == 0, "{name} frame {i}: ffmpeg differs from us by up to {worst}");
}
}
}
}
eprintln!("worst difference from ffmpeg: {worst_overall}");
}
/// Arbitrary texture bytes, not only what our encoder writes, decode to what ffmpeg decodes: this
/// covers every endpoint order, palette index and YCoCg scale a block can hold.
#[test]
fn ffmpeg_decodes_arbitrary_blocks_to_our_pictures() {
let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return };
let dir = craft_media_testkit::fixture_subdir("hap");
let mut seed = 0xDEAD_BEEFu32;
let (w, h) = (64u32, 64u32);
let blocks = (w / 4 * (h / 4)) as usize;
for (v, kind, block_bytes) in
[(Variant::Hap, 0xABu8, 8usize), (Variant::HapAlpha, 0xAE, 16), (Variant::HapQ, 0xAF, 16), (Variant::HapAlphaOnly, 0xA1, 8)]
{
let dec = Decoder::new(w, h).expect("d");
let frames: Vec<Vec<u8>> = (0..20)
.map(|_| {
let n = blocks * block_bytes;
let mut f = vec![n as u8, (n >> 8) as u8, (n >> 16) as u8, kind];
f.extend((0..n).map(|_| xorshift(&mut seed) as u8));
f
})
.collect();
let file = dir.join(format!("random_{}.avi", String::from_utf8_lossy(&v.fourcc())));
std::fs::write(&file, avi_of(v.fourcc(), w, h, &frames)).expect("write fixture");
let theirs = ffmpeg_pictures(&ffmpeg, &file, "rgba");
let n = (w * h * 4) as usize;
assert_eq!(theirs.len(), frames.len() * n);
for (i, f) in frames.iter().enumerate() {
let ours = dec.decode_rgba(f).expect("decode");
let t = &theirs[i * n..(i + 1) * n];
let same = if v == Variant::HapAlphaOnly {
ours.rgba.chunks(4).zip(t.chunks(4)).all(|(a, b)| a[3] == b[0])
} else if v == Variant::HapAlpha {
ours.rgba == t
} else {
ours.rgba.chunks(4).zip(t.chunks(4)).all(|(a, b)| a[..3] == b[..3])
};
assert!(same, "{v:?} random frame {i} differs from ffmpeg");
}
}
}