# Libdragon overlays

## Overlays

With overlays, we refer to the practice of dynamically loading/unloading portions of code/data at runtime. This is similar to the concept of DLLs or shared libraries (.so) on modern PCs.

The main goal of using overlays is to save RDRAM: by dynamically loading a portion of code only when required, we can spare the RAM to hold that only until and as long as it's necessary.

## Differences from libultra

First thing to notice is that libdragon overlays are generally less useful than in libultra. This is because in libdragon, data assets like models, textures are dynamically loaded from the filesystem into the heap, so if you go from stage1 to stage2, it's pretty normal that the various assets in stage1 gets unloaded, the memory freed (via `free()`), and then assets for stage2 are loaded again (`fopen()`, `malloc()`). This is similar on how a PC game would do.

Viceversa, in libultra/nusys, assets are normally part of the data segment of the binary (eg: the overlay) because there is no filesystem nor heap by default. So switching overlays is important to save memory even just to load different models or textures in different moments of the game.

In other words, overlays in libdragon are only about saving the amount of *code* that is kept into the RDRAM. In addition of code, this actually also applies to data/bss, but again, in the data segment there will be no audio/graphics assets whatsoever, so in general the impact is lower.

## Usecases

### "Stage" overlays

A game has three overlays: menu, stage1, stage2. It wants to switch between these overlays depending on the moment. We call this scenario "stage overlays" because each overlay represents a different "moment" of the game flow and they get loaded in some sequence, one at a time.

Obviously, there's lot of common code/data between them (libdragon itself, but also maybe part of the game engine) that needs to be handled somehow.

It's important also to notice that the game might want to have graphics/music going on while it switches from menu to stage1, so this can hardly involve a full system reset.

### "Actor" overlays

A game might want to have one overlay for each actor of the game, which contains the required AI for that actor. You can think of having a `class Actor` and then several implementations derived from it, and you want to keep each implementation in a different overlay, so that you free RDRAM from hundreds of AI scripts/logic that you don't need at any given time.

The overlay might work by calling game engine functions, so it will have to somehow "binds back" to exported functions in the main game code (simple case: the overlay needs `timer_ticks()` but the `timer_ticks()` implementation is in the main binary together with the reset of libdragon).

## How a ROM with overlays is structured

To create code that goes into an overlay, it is sufficient to write standard C/C++ code and simply link it into the overlay [TBD: build instructions]. The C code meant to go into an overlay has no particular limits or differences comapred to the C code that goes into the main application. In particular, it can still access all of libdragon or any other public function in the main application.

Overlays are compiled into binary modules with extension `uso`. Overlays are never automatically loaded by libdragon but must be loaded manually from the main application.

The API to handle overlays is the standard POSIX one: you can use `ovl = dlopen("rom:/actor.uso")` to load an overlay into RDRAM and then `dlsym(ovl, "createActor")` to fetch the pointer to a publicly exported function.

Notice that the build system will also create a `.sym` file for each overlay. For instance, in the filesystem, next to `actor.uso`, you should see also `actor.uso.sym`. This is the symbol file used by the backtracing engine to provide correct names of functions. It can be safely removed from final builds.

## Build steps

This section describes in detail the various build steps required