diff --git a/docs/compression.md b/docs/compression.md new file mode 100644 index 00000000..0a380eb7 --- /dev/null +++ b/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. diff --git a/docs/infrastructure.md b/docs/infrastructure.md index aa8befc0..527022af 100644 --- a/docs/infrastructure.md +++ b/docs/infrastructure.md @@ -2,33 +2,110 @@ For developers to reference. -## Directory Structure - -- **.github/workflows**: Contains workflow configuration for running yaze_test. -- **assets**: Hosts assets like fonts. -- **cmake**: Contains CMake configurations. -- **docs**: Stores documentation. -- **src**: Source files. -- **test**: Contains test files and configurations. - ## Main Components - `app` Namespace: Represents the GUI editor YAZE. - `cli` Namespace: Represents the command line interface Z3ED. -## YAZE app +## Directory Structure + +- **.github/workflows**: Contains `yaze_test` workflow config. +- **assets**: Hosts assets like fonts. +- **cmake**: Contains CMake configurations. +- **docs**: Contains documentation for users and developers. + - [Getting Started](./getting-started.md) + - [LC_LZ2 Compression](./compression.md) +- **src**: Contains source files. + - **lib**: Contains git submodule dependencies. +- **test**: Contains test files and configurations. + +## App Organization - **Core Namespace**: - Contains fundamental functionalities. + - [Common](../src/core/common.h) + - [Constants](../src/core/constants.h) + - [Controller](../src/core/controller.h) + - [Editor](../src/core/editor.h) + - [Emulator](../src/core/emulator.h) + - [Pipeline](../src/core/pipeline.h) - **Editor Namespace**: - - Represents the GUI view. - - Contains a class holding objects such as `zelda3::Overworld` and `gfx::Bitmap` for rendering and user input handling. + - Editors are responsible for representing the GUI view and handling user input. + - These classes are all controlled by [MasterEditor](../src/app/editor/master_editor.h) + - [AssemblyEditor](../src/app/editor/assembly_editor.h) + - [DungeonEditor](../src/app/editor/dungeon_editor.h) + - [GraphicsEditor](../src/app/editor/graphics_editor.h) + - [MusicEditor](../src/app/editor/music_editor.h) + - [OverworldEditor](../src/app/editor/overworld_editor.h) + - [ScreenEditor](../src/app/editor/screen_editor.h) + - [SpriteEditor](../src/app/editor/sprite_editor.h) +- **Emu Namespace**: + - Contains business logic for `core::emulator` + - [Audio](../src/emu/audio/) + - [Debug](../src/emu/debug/) + - [Memory](../src/emu/memory/) + - [Video](../src/emu/video/) - **Gfx Namespace**: - - Handles graphics-related tasks. + - Handles graphics related tasks. + - [Bitmap](../src/gfx/bitmap.h) + - [Compression](../src/gfx/compression.h) + - [SCAD Format](../src/gfx/scad_format.h) + - [SNES Palette](../src/gfx/snes_palette.h) + - [SNES Tile](../src/gfx/snes_tile.h) - **Gui Namespace**: - Manages GUI elements. + - [Canvas](../src/gui/canvas.h) + - [Color](../src/gui/color.h) + - [Icons](../src/gui/icons.h) + - [Input](../src/gui/input.h) + - [Style](../src/gui/style.h) + - [Widgets](../src/gui/widgets.h) - **Zelda3 Namespace**: - Holds business logic specific to Zelda3. + - [Dungeon](../src/zelda3/dungeon/) + - [Music](../src/zelda3/music/) + - [Screen](../src/zelda3/screen/) + - [Sprite](../src/zelda3/sprite/) + - [OverworldMap](../src/zelda3/overworld_map.h) + - [Overworld](../src/zelda3/overworld.h) + +### Flow of Control + +- [app/yaze.cc](../src/app/yaze.cc) + - Initializes `absl::FailureSignalHandler` for stack tracing. + - Runs the `core::Controller` loop. +- [app/core/controller.cc](../src/app/core/controller.cc) + - Initializes SDLRenderer and SDLWindow + - Initializes ImGui, fonts, themes, and clipboard. + - Handles user input from keyboard and mouse. + - Updates `editor::MasterEditor`. + - Renders the output to the screen. + - Handles the teardown of SDL and ImGui resources. + - [app/editor/master_editor.cc](../src/app/editor/master_editor.cc) + - Handles the main menu bar. + - File + - Edit + - View + - Help + - Handles `absl::Status` errors as popups delivered to the user. + - Update all the editors in a tab view. + - [app/editor/assembly_editor.cc](../src/app/editor/assembly_editor.cc) + - [app/editor/dungeon_editor.cc](../src/app/editor/dungeon_editor.cc) + - [app/editor/graphics_editor.cc](../src/app/editor/graphics_editor.cc) + - [app/editor/music_editor.cc](../src/app/editor/music_editor.cc) + - [app/editor/overworld_editor.cc](../src/app/editor/overworld_editor.cc) + - [app/editor/screen_editor.cc](../src/app/editor/screen_editor.cc) + - [app/editor/sprite_editor.cc](../src/app/editor/sprite_editor.cc) + +## Bitmap + +Located in [app/gfx/bitmap.cc](../src/app/gfx/bitmap.cc) + +- **Initialization**: Offers multiple constructors to create bitmaps using different data types. +- **Palette Application**: Provides grayscale palettes and can convert `SNESPalette` to `SDL_Palette`. +- **Texture Handling**: Can create and update textures based on SDL surfaces. +- **SDL Surface Management**: Allows for the creation, modification, and saving of SDL surfaces. +- **Memory Management**: Uses smart pointers for efficient memory utilization and cleanup. ## Z3ED cli diff --git a/docs/macos-build.md b/docs/macos-build.md index b929dfa1..7cce401b 100644 --- a/docs/macos-build.md +++ b/docs/macos-build.md @@ -1,6 +1,6 @@ -Taking note of this because of how stupid it is. +# macOS Build Settings -Clang 15.0.1 x86_64-apple-darrwin22.5.0 -SDL2 Source v2.26.5 -Removed snes_spc -Removed asar_static \ No newline at end of file +- Clang 15.0.1 x86_64-apple-darrwin22.5.0 +- SDL2 Source v2.26.5 +- Removed snes_spc +- Removed asar_static \ No newline at end of file