scawful/yaze
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update infrastructure doc and add compression doc

Browse Source
This commit is contained in:
scawful
2023-10-20 04:22:28 -04:00
parent d9331dfc3a
commit 3a4ae7c270
3 changed files with 162 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

67
docs/compression.md Normal file
View File

@@ -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.

103
docs/infrastructure.md
View File

@@ -2,33 +2,110 @@
For developers to reference. 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 ## Main Components
- `app` Namespace: Represents the GUI editor YAZE. - `app` Namespace: Represents the GUI editor YAZE.
- `cli` Namespace: Represents the command line interface Z3ED. - `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**: - **Core Namespace**:
- Contains fundamental functionalities. - 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**: - **Editor Namespace**:
- Represents the GUI view. - Editors are responsible for representing the GUI view and handling user input.
- Contains a class holding objects such as `zelda3::Overworld` and `gfx::Bitmap` for rendering and user input handling. - 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**: - **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**: - **Gui Namespace**:
- Manages GUI elements. - 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**: - **Zelda3 Namespace**:
- Holds business logic specific to Zelda3. - 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 ## Z3ED cli

10
docs/macos-build.md
View File

@@ -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 - Clang 15.0.1 x86_64-apple-darrwin22.5.0
SDL2 Source v2.26.5 - SDL2 Source v2.26.5
Removed snes_spc - Removed snes_spc
Removed asar_static - Removed asar_static