Module yaz0

Adds support for the Yaz0 compression format used for first-party N64, GameCube, Wii, Wii U, and Switch games.

Because the Yaz0 format is so lightweight, this module is designed to not have any persistence. It takes in data, and will return the de/compressed data contained inside.

Format

The Yaz0 format is part of the Lempel-Ziv family of algorithms, which use a “sliding window” to allow for copying repetitive data from previously in the output buffer. The input stream consists of lookback+length pairs, unique bytes to copy, and “flag bytes” which determine which of the two operations to do.

Header

The header is as follows, in big-endian format:

Offset	Field	Type	Notes
0x0	Magic number	u8[4]	Unique identifier (“Yaz0”) to let us know we’re reading a Yaz0-compressed file.
0x4	Output size	u32	The size of the decompressed data, needed for the output buffer.
0x8	Alignment	u32	Specifies the alignment needed for the output buffer. Non-zero starting with Wii U.
0xC	Padding	u8[4]	Alignment to a 0x10 byte boundary. Always 0.

Decompression

The decompression algorithm is as follows, ran in a loop until you write enough bytes to fill the output buffer:

• Read one byte from the input, which is 8 flag bits from high to low.
• For each flag bit, if it is a 1, copy one byte from the input to the output.
• If it is a 0, copy bytes from earlier in the output buffer:
  • Read two bytes from the input.
  • Get the first nibble (code >> 12). If it is 0, read one more byte and add 18 (0x12). Otherwise, add 2 to the nibble. Use that as the number of bytes to copy.
  • Add 1 to the lower nibbles (code & 0xFFF) and treat that as how far back in the buffer to read, from the current position.
  • Note that the count can overlap with the destination, and needs to be copied one byte at a time for correct behavior.
  • Copy that amount of bytes from the lookback position to the current position.

Usage

This module offers the following functionality:

Decompression

• decompress_from_path: Provide a path, get decompressed data back
• decompress_from: Provide the input data, get decompressed data back
• decompress: Provide the input data and output buffer, run the decompression algorithm

Compression

• compress_from_path: Provide a path, get compressed data back
• compress_from: Provide the input data, get compressed data back
• compress_n64: Provide the input data and output buffer, run the compression (older matching algorithm)

Utilities

• read_header: Returns the header information for a given Yaz0 file
• worst_possible_size: Calculates the worst possible compression size for a given filesize

Structs

Header

See the module header for more information.

Yaz0

Utility struct for handling Yaz0 compression.

Enums

CompressionAlgo

All supported Yaz0 compression algorithms

Error

Error conditions for when reading/writing Yaz0 files