psx_fmv/lib.rs
1// SPDX-License-Identifier: GPL-2.0-or-later
2//! FMV playback building blocks for PS1 guests.
3//!
4//! A movie is a `.STR` file: 2048-byte sectors, each carrying a 32-byte
5//! chunk header and 2016 bytes of one frame's compressed bitstream (the
6//! "BS" format). Playing one is a pipeline:
7//!
8//! 1. CD sectors stream in (the caller owns the drive; see the
9//! `hello-fmv` example) and [`stream::FrameAssembler`] stitches a frame's
10//! chunks back together.
11//! 2. [`bitstream::decode_frame`] runs the variable-length decode on the CPU,
12//! turning the bitstream into the MDEC's run-length halfwords.
13//! 3. [`mdec::Mdec`], the driver that owns the MDEC's DMA channels, feeds
14//! those to the MDEC over DMA0 and pulls decoded 16-pixel-wide columns back
15//! over DMA1 for upload to VRAM.
16//!
17//! Everything but [`mdec`] is plain logic, built and tested on the host; the
18//! driver only touches a register when one of its methods runs.
19//!
20//! A game that only wants to play a movie calls [`player::play`] (guest only),
21//! which runs all three stages overlapped and shows the result; the
22//! `hello-fmv` example is the simpler, sector-checking test player.
23//!
24//! Bitstream versions 1 and 2 (the same coding) are decoded; v3 differs in the DC
25//! coding and is rejected with [`bitstream::DecodeError::Version`].
26//!
27//! The encoder is `psxavenc` (zlib license), run as a host build tool:
28//! `psxavenc -t strv -v v2 -s 320x240 -r 15 -x 2 in.mp4 out.str`.
29
30#![no_std]
31
32#[doc(alias = "BS")]
33pub mod bitstream;
34pub mod idct;
35pub mod iso;
36pub mod mdec;
37#[cfg(target_arch = "mips")]
38pub mod player;
39pub mod rle;
40#[doc(alias = "STR")]
41pub mod stream;