Repository navigation
Compression
This page describes how libdragon achieves data compression in general for different type of assets (executables, graphics, audio). It gives some general guidance and explains the rationale of the various defaults.
Libdragon ships with three different data compression algorithms, generically identified by level numbers from 1 to 3 (with "level 0" sometimes being used to refer to "no compression"). Increasing the level means slower compression during builds, slower decompressions at runtime, but more compression ratio.
The actual algorithm behind each level is considered an implementation detail; as new algorithms are tested on N64, libdragon can change the algorithms at any point, even in the stable branch (that is, a change of compression algorithm is not considered a breaking change). It is thus important that compression of data happens during build, and compressed data is not committed to the game repository: such pre-compressed, committed data might in fact turn out to be unusable with future libdragon versions.
- Level 1: this is fastest compression level. The ratio is not great (normally worse than gzip, just to give a ballpark) but it is so fast at decompressing that it achieves an important property: data compressed at level 1 is faster at loading and decompressing, than loading uncompressed data. This surprising result happens because the time saved by loading data fewer bytes from ROM is enough to counterbalance the time spent in decompressing the data. This property has been proven true with so many different kind of data, that can be considered true for all data. Currently, the algorithm used is LZ4 by Yann Collet.
-
Level 2: this is a good intermediate compression level. The ratio is quite good (better than
gzip -9in most cases), but it is still decently fast at decompressing.
| Level | Ratio | Ratio vs gzip | Load+Decomp speed | Notes |
|---|---|---|---|---|
| 1 | 20% | +2% | 100 KiB/s | Faster than uncompressed, used by default on everything |
| 2 | 30% | +10% | 200 KiB/s | Good for assets loaded during level changes; might not be fast enough for data streamed during game |
| 3 | 50% | +40% | 30 KiB/s | Loading is very slow; good for assets loaded very rarely like error screen, or for situations where loading time is not a huge issue |