Jazz2::AssetPacker::Mpeg1Encoder class

Encodes planar YUV 4:2:0 frames into an MPEG-1 video elementary stream (.m1v).

The Nintendo 64 plays full-motion video with libdragon's port of pl_mpeg, which reads a bare MPEG-1 video stream. This encoder writes one without any external tool, so it runs wherever the asset packer does, including its WebAssembly build. Every decision is made in integer arithmetic, so the same input gives the same bytes on every platform and compiler.

The stream is made of closed groups of pictures, one I-picture followed by P-pictures, with the sequence header repeated before each group and the default quantizer matrices. B-pictures are not used: the cinematics are animated on twos, so every other frame repeats the previous one and costs next to nothing as a P-picture, while B-pictures would only stretch the distance the other P-pictures predict over. A group ends early at a scene cut, or runs a little longer to end at one that follows closely.

The rate control encodes about ten seconds ahead and gives every group the quantizer that would put the groups written so far and the ones ahead exactly on target, so the quality stays even across the sequence and the target bitrate is met over all of it rather than per group. Those frames are held in memory meanwhile.

A decoder that only keeps up with a limited bitrate, like the console's, can be given it as a peak: no run of pictures then takes more than the buffer plus the peak bitrate over its duration (the leaky bucket of MPEG's video buffering verifier), and a picture that would is encoded again with a coarser quantizer. The rate control counts such a picture as the bits it would have taken, so what it saves goes to the groups around it.

Two quirks of libdragon's decoder are taken care of: its RSP path halves negative odd motion vectors the other way than the standard when it predicts chroma, so such vectors are only used where both roundings predict the same pixels, and it cannot decode the last few bytes of a file, so the stream ends with padding.

Public types

struct Options
Encoding parameters.
struct Statistics
Statistics of the stream written so far.

Constructors, destructors, conversion operators

Mpeg1Encoder()
~Mpeg1Encoder()
Mpeg1Encoder(const Mpeg1Encoder&) deleted

Public functions

auto operator=(const Mpeg1Encoder&) -> Mpeg1Encoder& deleted
auto Begin(const Options& options, std::vector<std::uint8_t>& output) -> bool
Starts a new stream.
auto EncodeFrame(const std::uint8_t* y, const std::uint8_t* u, const std::uint8_t* v, std::vector<std::uint8_t>& output) -> bool
Adds one frame.
auto End(std::vector<std::uint8_t>& output) -> bool
Encodes the frames still held and finishes the stream with a sequence_end_code.
auto GetStatistics() const -> const Statistics&
Returns statistics of the stream written so far.

Function documentation

bool Jazz2::AssetPacker::Mpeg1Encoder::Begin(const Options& options, std::vector<std::uint8_t>& output)

Starts a new stream.

Parameters
options
output Receives the bytes of the stream as they become available
Returns false if the options cannot be encoded - an odd or too large size, or a frame rate MPEG-1 lacks

bool Jazz2::AssetPacker::Mpeg1Encoder::EncodeFrame(const std::uint8_t* y, const std::uint8_t* u, const std::uint8_t* v, std::vector<std::uint8_t>& output)

Adds one frame.

The planes are limited-range BT.601 (Y 16-235, chroma 16-240), tightly packed: y is Width by Height, u (Cb) and v (Cr) are half of that in both directions. Frames are held for the rate control's lookahead, so output only grows now and then, by a group of pictures at a time.