Skip to main content

Crate vqa

Crate vqa 

Source
Expand description

A parser and decoder for Westwood Studios’ VQA (Vector Quantized Animation) format, the full-motion-video format of Westwood’s 90s games (Command & Conquer, Red Alert, Lands of Lore, Dune 2000, Blade Runner, Tiberian Sun, Nox).

§Quick start

VQA parses the container once, then hands out decoded video frames and audio samples:

use vqa::VQA;

let data = std::fs::read("movie.vqa")?;
let vqa = VQA::parse(&data)?;

let header = &vqa.header;
println!(
    "{}x{}, {} frames at {} fps",
    header.width, header.height, header.num_frames, header.frame_rate
);

// The video, frame by frame
for frame in vqa.frames()? {
    let rgb = frame?.to_rgb888(); // packed RGB bytes, row-major
}

// The soundtrack, as interleaved signed 16-bit PCM
if header.has_sound() {
    let samples = vqa.decode_audio()?;
}

Each frame the iterator yields is a copy of the decoder’s own. A loop that is done with each frame before asking for the next can borrow it instead with Frames::next_ref, and convert it into one reused buffer:

let mut frames = vqa.frames()?;
let mut rgb = Vec::new();
while let Some(frame) = frames.next_ref() {
    let frame = frame?;
    rgb.resize(frame.width * frame.height * 3, 0);
    frame.write_rgb888(&mut rgb);
}

VQA::decode_audio fails on the first malformed chunk. To play a damaged or cut-off movie as far as it goes, decode the soundtrack chunk by chunk with VQA::audio_chunks, which yields the sound before the damage, and frames with Frames, which stops at the first bad one.

Runnable examples exercise the same API: player plays a movie (video in a window, soundtrack on the default audio device), dump_frames writes every video frame out as PPM, and bench times the decoder and hashes its output.

§Layers

§Format support

All three container versions (v1-v3) parse. Video decoding covers both the 8-bit palettized scheme (VPT? pointer tables) and the HiColor 15-bit scheme (VPTR/VPRZ command streams, including the Blade Runner alpha-skip commands). Audio decoding covers IMA ADPCM (SND2), Westwood ADPCM (SND1, in early 8-bit-audio movies), and raw PCM (SND0).

Malformed input fails with an Error rather than panicking, and allocation sizes taken from the file are capped, so the crate is safe to run on untrusted data (it ships cargo-fuzz targets). An error says what went wrong (Error::kind) and, where known, where: the frame, the chunk, and the chunk’s byte offset in the file.

The doc/ directory of the repository carries the format references this crate is written against: vqa.txt for v1/v2 and hc-vqa.txt for the HiColor scheme.

§Performance

Drawing 8-bit frames and converting HiColor frames to RGB use SIMD, chosen at run time on x86 (AVX-512, AVX2, SSE4.2 or SSE2), and NEON on 64-bit ARM. WebAssembly has no run-time detection: build with -C target-feature=+simd128, or those paths fall back to scalar code, which on wasm32 draws 8-bit frames 2.6 times as slowly and converts HiColor frames three times as slowly.

Modules§

audio
Audio decoding: the IMA ADPCM codec behind SND2 sound chunks (decompress and CodecState) and Westwood’s own ADPCM behind SND1 ones (westwood).
lcw
LCW (“Format80”) decompression, the scheme behind every *Z chunk in a VQA file (CBFZ, CBPZ, CPLZ, VPTZ, VPRZ).

Structs§

AudioChunks
Iterator over a movie’s soundtrack, one sound chunk at a time: each item holds one SND? chunk’s samples, interleaved signed 16-bit as VQA::decode_audio returns them.
Chunk
One chunk: its ID, where it starts, and its payload, borrowed from the input.
Chunks
Iterator over consecutive chunks, such as the body of a movie (VQA::chunks) or the payload of a container chunk (Chunk::sub_chunks).
Error
An error decoding a movie: what went wrong (Error::kind) and, when known, where (Error::chunk, Error::offset and Error::frame).
Frame
One decoded video frame.
FrameDecoder
Stateful decoder for a movie’s video stream.
FrameInfo
Position of one frame’s data, decoded from a FINF entry.
FrameRef
A decoded frame borrowed from the FrameDecoder that produced it: a Frame without the copy, valid until the decoder moves on to the next frame.
Frames
Iterator over a movie’s decoded video frames. Every VQFR chunk (or VQFK, a key frame) yields one frame, as does every pointer table of the older layout that has frame sub-chunks at the top level; VQFL codebook refreshes and the CINF codebook schedule are applied transparently.
VQA
A parsed VQA movie, borrowing the file’s bytes.
VQAHeader
The fixed 42-byte VQHD header describing the whole movie.

Enums§

ErrorKind
What kind of Error happened.
FramePixels
A frame’s pixel data, row-major.
FramePixelsRef
A borrowed frame’s pixel data, row-major; see FramePixels.
Limit
The sanity limit an ErrorKind::TooLarge error exceeds.
VQAVersion
The format version stored in the header.
VideoError
How the video data in an ErrorKind::Video error is malformed.