backend-infra-engineer: Pre-0.2.2 snapshot (2023)

docs/compression.md

@@ -0,0 +1,67 @@
+# LC_LZ2 Compression
+
+The compression algorithm has multiple implementations with varying levels of quality, based primarily on the implementations made in skarsnik/sneshacking, Zarby89/ZScreamDungeon and ZCompress with optimizations made for C++.
+
+## Key Definitions
+
+### Constants and Macros:
+- `BUILD_HEADER(command, length)`: Macro to build a header from a command and a length.
+- Command Constants: Constants to represent different commands like `kCommandDirectCopy`, `kCommandByteFill`, etc.
+- Length and Mode Constants: Such as `kMaxLengthNormalHeader`, `kNintendoMode1`, etc.
+
+### Data Structures:
+
+#### 1. CompressionCommand:
+   - **arguments**: 2D array representing the command arguments for each possible command.
+   - **cmd_size**: Array storing the size of each possible command.
+   - **data_size**: Array storing the size of the data processed by each possible command.
+
+#### 2. CompressionPiece:
+   - **command**: Represents the compression command.
+   - **length**: Length of the compressed data piece.
+   - **argument_length**: Length of the argument.
+   - **argument**: Argument as a string.
+   - **next**: Pointer to the next compression piece.
+
+#### 3. CompressionContext (for Compression V3):
+   - Contains vectors to store raw and compressed data, compression pieces, and compression string.
+   - Various counters and flags for compression control.
+   - Current compression command details.
+
+## Compression Functions
+
+### Version 1:
+- **Byte Repeat**: `CheckByteRepeat`
+- **Word Repeat**: `CheckWordRepeat`
+- **Increasing Byte**: `CheckIncByte`
+- **Intra Copy**: `CheckIntraCopy`
+- **Validation and Alternatives**: `ValidateForByteGain` & `CompressionCommandAlternative`
+
+### Version 2:
+- **Byte Repeat**: `CheckByteRepeatV2`
+- **Word Repeat**: `CheckWordRepeatV2`
+- **Increasing Byte**: `CheckIncByteV2`
+- **Intra Copy**: `CheckIntraCopyV2`
+- **Validation and Alternatives**: `ValidateForByteGainV2` & `CompressionCommandAlternativeV2`
+
+### Version 3:
+Using `CompressionContext` to handle compression.
+- **Initialization**: `InitializeCompression`
+- **Command Checks**: Such as `CheckByteRepeatV3`
+- **Determining Best Compression**: `DetermineBestCompression`
+- **Handling Direct Copy**: `HandleDirectCopy`
+- **Adding Compression to Chain**: `AddCompressionToChain`
+
+## Decompression Functions:
+- `SetBuffer`: Prepares a buffer from data.
+- `memfill`: Fills memory.
+- **Decompression**: Such as `DecompressV2`, `DecompressGraphics`, and `DecompressOverworld`.
+
+## Utility Functions:
+- **Printing**: Such as `PrintCompressionPiece` and `PrintCompressionChain`.
+- **Compression String Creation**: `CreateCompressionString`
+- **Compression Result Validation**: Such as `ValidateCompressionResult` and its V3 variant.
+- **Compression Piece Manipulation**: Like `SplitCompressionPiece` and its V3 variant.
+
+## Final Notes
+The YAZE's LC_LZ2 compression scheme provides three versions of compression methodologies with comprehensive support for various commands and modes. It ensures versatility and adaptability for different compression needs.