[ox] Add Project Structure section to docs
All checks were successful
Build / build (push) Successful in 2m36s

This commit is contained in:
Gary Talent 2024-10-04 01:15:17 -05:00
parent ea9f50de8d
commit 3271a37115

36
deps/ox/ox-docs.md vendored
View File

@ -1,17 +1,33 @@
# Ox Docs
## Project Structure
All components have a platform indicator next to them:
(OB) - OS, Bare Metal
(-B) - Bare Metal
(O-) - OS
* Ox - Library of things useful for portable bare metal and userland code. Not really that external...
* clargs - Command Line Args processing (OB)
* claw - Reads and writes Metal or Organic Claw with header to indicate which
* event - Qt-like signal system (OB)
* fs - file system (OB)
* logconn - connects logging to Bullock (O-)
* mc - Metal Claw serialization, builds on model (OB)
* oc - Organic Claw serialization (wrapper around JsonCpp), builds on model (O-)
* model - Data structure modelling (OB)
* preloader - library for handling preloading of data (OB)
* std - Standard-ish Library with a lot missing and some things added (OB)
## Systems
### Error Handling
The GBA build has exceptions disabled.
Instead of throwing exceptions, all engine code must return ```ox::Error```s.
For the sake of consistency, try to stick to ```ox::Error``` in non-engine code
as well, but non-engine code is free to use exceptions when they make sense.
Nostalgia and Ox both use ```ox::Error``` to report errors. ```ox::Error``` is
a struct that has overloaded operators to behave like an integer error code,
plus some extra fields to enhance debuggability.
Ox provides ```ox::Error``` to report errors.
```ox::Error``` is a struct that has overloaded operators to behave like an
integer error code, plus some extra fields to enhance debuggability.
If instantiated through the ```OxError(x)``` macro, it will also include the
file and line of the error.
The ```OxError(x)``` macro should only be used for the initial instantiation of
@ -87,9 +103,6 @@ back up the call stack, ```oxReturnError```, ```oxThrowError```, and
```oxReturnError``` is by far the more helpful of the two.
```oxReturnError``` will return an ```ox::Error``` if it is not 0 and
```oxThrowError``` will throw an ```ox::Error``` if it is not 0.
Because exceptions are disabled for GBA builds and thus cannot be used in the
engine, ```oxThrowError``` is only really useful at the boundary between
engine libraries and Nostalgia Studio.
Since ```ox::Error``` is always nodiscard, you must do something with them.
In rare cases, you may not have anything you can do with them or you may know
@ -370,9 +383,6 @@ That reads:
* Type ID is net.drinkingtea.nostalgia.core.NostalgiaPalette
* Type version is 1
Except when the data is exported for loading on the GBA, Claw is always used as
a wrapper around the bare formats.
#### Metal Claw Example
##### Read