backend-infra-engineer: Pre-0.2.2 2024 Q4 snapshot
This commit is contained in:
scawful
@@ -1,140 +1,86 @@
|
||||
# YAZE Infrastructure Overview
|
||||
# Infrastructure Overview
|
||||
|
||||
For developers to reference.
|
||||
|
||||
The goal of yaze is to build a cross platform editor for the Legend of Zelda: A Link to the Past. The project is built using C++20, SDL2, and ImGui. The project is built using CMake and is designed to be modular and extensible. The project is designed to be built on Windows, macOS, iOS, and Linux.
|
||||
|
||||
## Targets
|
||||
|
||||
- **yaze**: Desktop application for Windows/macOS/Linux
|
||||
- **z3ed**: Command Line Interface
|
||||
- **yaze_c**: C Library
|
||||
- **yaze_py**: Python Module
|
||||
- **yaze_test**: Unit test executable
|
||||
- **yaze_ios**: iOS application
|
||||
|
||||
## Directory Structure
|
||||
|
||||
- **.github/workflows**: Contains `yaze_test` workflow config.
|
||||
- **assets**: Hosts assets like fonts.
|
||||
- **assets**: Hosts assets like fonts, icons, assembly source, etc.
|
||||
- **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.
|
||||
- **app**: Contains the GUI editor `yaze`
|
||||
- **cli**: Contains the command line interface `z3ed`
|
||||
- **lib**: Contains git submodule dependencies.
|
||||
- Abseil-cpp
|
||||
- Asar
|
||||
- ImGui
|
||||
- ImGuiFileDialog
|
||||
- ImGuiColorTextEdit
|
||||
- imgui_memory_editor
|
||||
- SDL2
|
||||
- **test**: Contains testing interface `yaze_test`
|
||||
- **app**: Contains the GUI editor `yaze`
|
||||
- **app/emu**: Contains a standalone Snes emulator application `yaze_emu`
|
||||
- **cli**: Contains the command line interface `z3ed`
|
||||
- **incl**: Contains the data headers for `yaze_c`
|
||||
- **ios**: Contains the iOS application `yaze_ios`
|
||||
- **lib**: Contains the dependencies as git submodules
|
||||
- **py**: Contains the Python module `yaze_py`
|
||||
- **test**: Contains testing interface `yaze_test`
|
||||
- **win32**: Contains Windows resource file and icon
|
||||
|
||||
### Flow of Control
|
||||
## Dependencies
|
||||
|
||||
- [app/yaze.cc](../src/app/yaze.cc)
|
||||
See [build-instructions.md](docs/build-instructions.md) for more information.
|
||||
|
||||
- **SDL2**: Graphics library
|
||||
- **ImGui**: GUI library
|
||||
- **Abseil**: C++ library
|
||||
- **libpng**: Image library
|
||||
- **Boost**: Python library
|
||||
|
||||
## Flow of Control
|
||||
|
||||
- app/yaze.cc
|
||||
- Initializes `absl::FailureSignalHandler` for stack tracing.
|
||||
- Runs the `core::Controller` loop.
|
||||
- [app/core/controller.cc](../src/app/core/controller.cc)
|
||||
- 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
|
||||
- Open - [app::ROM::LoadFromFile](../src/app/rom.cc#l=90)
|
||||
- Save - [app::ROM::SaveToFile](../src/app/rom.cc#l=301)
|
||||
- Edit
|
||||
- View
|
||||
- Emulator
|
||||
- HEX Editor
|
||||
- ASM Editor
|
||||
- Palette Editor
|
||||
- Memory Viewer
|
||||
- ImGui Demo
|
||||
- GUI Tools
|
||||
- Runtime Metrics
|
||||
- Style Editor
|
||||
- Help
|
||||
- app/editor/editor_manager.cc
|
||||
- Handles the main menu bar
|
||||
- Handles `absl::Status` errors as popups delivered to the user.
|
||||
- Dispatches messages to the various editors.
|
||||
- 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)
|
||||
- app/editor/code/assembly_editor.cc
|
||||
- app/editor/dungeon/dungeon_editor.cc
|
||||
- app/editor/graphics/graphics_editor.cc
|
||||
- app/editor/graphics/gfx_group_editor.cc
|
||||
- app/editor/graphics/palette_editor.cc
|
||||
- app/editor/graphics/tile16_editor.cc
|
||||
- app/editor/message/message_editor.cc
|
||||
- app/editor/music/music_editor.cc
|
||||
- app/editor/overworld/overworld_editor.cc
|
||||
- app/editor/graphics/screen_editor.cc
|
||||
- app/editor/sprite/sprite_editor.cc
|
||||
- app/editor/system/settings_editor.cc
|
||||
|
||||
## ROM
|
||||
- [app/rom.cc](../src/app/rom.cc)
|
||||
- [app/rom.h](../src/app/rom.h)
|
||||
---
|
||||
## Rom
|
||||
|
||||
This `ROM` class provides methods to manipulate and access data from a ROM.
|
||||
- app/rom.cc
|
||||
- app/rom.h
|
||||
|
||||
- **Key Methods**:
|
||||
- `Load2BppGraphics()`: Loads 2BPP graphics data from specified sheets.
|
||||
- `LoadAllGraphicsData()`: Loads all graphics data, both compressed and uncompressed, converting where necessary.
|
||||
- `LoadFromFile(const absl::string_view& filename, bool z3_load)`: Loads ROM data from a file. It also handles headers and Zelda 3 specific data if requested.
|
||||
- `LoadFromPointer(uchar* data, size_t length)`: Loads ROM data from a provided pointer.
|
||||
- `LoadFromBytes(const Bytes& data)`: Loads ROM data from bytes.
|
||||
- `LoadAllPalettes()`: Loads all color palettes used in the ROM. This includes palettes for various elements like sprites, shields, swords, etc.
|
||||
- `UpdatePaletteColor(...)`: Updates a specific color within a named palette group.
|
||||
The Rom class provides methods to manipulate and access data from a ROM.
|
||||
|
||||
- **Internal Data Structures**:
|
||||
- `rom_data_`: A container that holds the ROM data.
|
||||
- `graphics_bin_`: Holds the graphics data.
|
||||
- `palette_groups_`: A map containing various palette groups, each having its own set of color palettes.
|
||||
|
||||
- **Special Notes**:
|
||||
- The class interacts with various external functionalities, such as decompression algorithms (`gfx::DecompressV2`) and color conversion (`gfx::SnesTo8bppSheet`).
|
||||
- Headers in the ROM data, if present, are identified and removed.
|
||||
- Specific Zelda 3 data can be loaded if specified.
|
||||
- Palettes are categorized into multiple groups (e.g., `ow_main`, `ow_aux`, `hud`, etc.) and loaded accordingly.
|
||||
Currently implemented as a singleton with SharedRom which is not great but has helped with development velocity. Potential room for improvement is to refactor the editors to take the ROM as a parameter.
|
||||
|
||||
## Bitmap
|
||||
|
||||
- [app/gfx/bitmap.cc](../src/app/gfx/bitmap.cc)
|
||||
- [app/gfx/bitmap.h](../src/app/gfx/bitmap.cc)
|
||||
---
|
||||
- app/gfx/bitmap.cc
|
||||
- app/gfx/bitmap.h
|
||||
|
||||
This class is responsible for creating, managing, and manipulating bitmap data, which can be displayed on the screen using the ImGui library.
|
||||
This class is responsible for creating, managing, and manipulating bitmap data, which can be displayed on the screen using SDL2 Textures and the ImGui draw list. It also provides functions for exporting these bitmaps to the clipboard in PNG format using libpng.
|
||||
|
||||
### Key Attributes:
|
||||
|
||||
1. **Width, Height, Depth, and Data Size**: These represent the dimensions and data size of the bitmap.
|
||||
2. **Pixel Data**: Points to the raw data of the bitmap.
|
||||
3. **Texture and Surface**: Use SDL to manage the graphical representation of the bitmap data. Both these attributes have custom deleters, ensuring proper resource management.
|
||||
|
||||
### Main Functions:
|
||||
|
||||
1. **Constructors**: Multiple constructors allow for different ways to create a Bitmap instance, like specifying width, height, depth, and data.
|
||||
2. **Create**: This set of overloaded functions provides ways to create a bitmap from different data sources.
|
||||
3. **CreateFromSurface**: Allows for the creation of a bitmap from an SDL_Surface.
|
||||
4. **Apply**: Changes the bitmap's data to a new set of Bytes.
|
||||
5. **Texture Operations**:
|
||||
- **CreateTexture**: Creates an SDL_Texture from the bitmap's data for rendering.
|
||||
- **UpdateTexture**: Updates the SDL_Texture with the latest bitmap data.
|
||||
6. **SaveSurfaceToFile**: Saves the SDL_Surface to a file.
|
||||
7. **SetSurface**: Assigns a new SDL_Surface to the bitmap.
|
||||
8. **Palette Functions**:
|
||||
- **ApplyPalette (Overloaded)**: This allows for the application of a SNESPalette or a standard SDL_Color palette to the bitmap.
|
||||
9. **WriteToPixel**: Directly writes a value to a specified position in the pixel data.
|
||||
|
||||
## Z3ED cli
|
||||
|
||||
| Command | Arg | Params | Status |
|
||||
|---------|-----|--------|--------|
|
||||
| Apply BPS Patch | -a | rom_file bps_file | In progress |
|
||||
| Create BPS Patch | -c | bps_file src_file modified_file | Not started |
|
||||
| Open ROM | -o | rom_file | Complete |
|
||||
| Backup ROM | -b | rom_file [new_file] | In progress |
|
||||
| Expand ROM | -x | rom_file file_size | Not started |
|
||||
| Transfer Tile16 | -t | src_rom dest_rom tile32_id_list(csv) | Complete |
|
||||
| Export Graphics | -e | rom_file bin_file | In progress |
|
||||
| Import Graphics | -i | bin_file rom_file | Not started |
|
||||
| SNES to PC Address | -s | address | Complete |
|
||||
| PC to SNES Address | -p | address | Complete |
|
||||
|
||||
|
||||
## Further Development Ideas
|
||||
- Extend `zelda3` namespace with additional functionalities.
|
||||
- Optimize program performance.
|
||||
- Introduce new features in the GUI editor.
|
||||
|
||||
Reference in New Issue
Block a user