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
VQAwithFramesandAudioChunks: the high-level API above.Chunks: the zero-copy chunk walk underneath, for consumers that want to walk the container themselves.VQA::chunkswalks a movie’s chunks,Chunk::sub_chunksthe chunks nested in one, andVQAHeader::parseandFrameInfo::from_rawdecode the header and the frame index.FrameDecoder: the stateful codebook/palette/frame assembler drivingFrames.audio: the IMA ADPCM and Westwood ADPCM decoders behindSND2andSND1sound chunks.lcw: LCW (“Format80”) decompression, used by every*Zchunk.
§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
SND2sound chunks (decompressandCodecState) and Westwood’s own ADPCM behindSND1ones (westwood). - lcw
- LCW (“Format80”) decompression, the scheme behind every
*Zchunk in a VQA file (CBFZ, CBPZ, CPLZ, VPTZ, VPRZ).
Structs§
- Audio
Chunks - Iterator over a movie’s soundtrack, one sound chunk at a time: each item
holds one
SND?chunk’s samples, interleaved signed 16-bit asVQA::decode_audioreturns 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::offsetandError::frame). - Frame
- One decoded video frame.
- Frame
Decoder - Stateful decoder for a movie’s video stream.
- Frame
Info - Position of one frame’s data, decoded from a FINF entry.
- Frame
Ref - A decoded frame borrowed from the
FrameDecoderthat produced it: aFramewithout 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
VQHDheader describing the whole movie.
Enums§
- Error
Kind - What kind of
Errorhappened. - Frame
Pixels - A frame’s pixel data, row-major.
- Frame
Pixels Ref - A borrowed frame’s pixel data, row-major; see
FramePixels. - Limit
- The sanity limit an
ErrorKind::TooLargeerror exceeds. - VQAVersion
- The format version stored in the header.
- Video
Error - How the video data in an
ErrorKind::Videoerror is malformed.