Modules | Files
Asset Subsystem

Interfaces for loading assets from ROM or other supports. More...


 DragonFS filesystem implementation and newlib hooks.


file  asset.h
 Asset Subsystem.

Detailed Description

Interfaces for loading assets from ROM or other supports.

The asset subsystem is in charge of loading assets. Typically, assets will be loaded from ROM, but other options might be possible (like SD cards).

Asset filenames are always prefixed with a filesystem identifier which has a syntax similar to an URL. For instance, to load a file from ROM through the DragonFS filesystem, use a filename like "rom:/myfile.txt".

While it is possible to simply open asset files using fopen, which supports the filesystem prefix as well, the asset subsystem provides a few helpers around asset compression.

Assets can be optionally compressed using the mkasset tool. Asset compression is done on a per-file basis (similar to how "gzip" works), and decompression is transparent to the user. The asset subsystem will automatically detect a compressed file and decompress it during loading.

The main functions for loading assets are asset_load and asset_fopen. asset_load loads the entire file into memory in one go, and it is useful for small files or in general files that has to fully keep in RAM as-is. The asset is transparently decompressed if needed.

Some files might require parsing during loading, and in that case, asset_fopen is provided. It returns a FILE* so that any kind of file operation can be performed on it, with transparent decompression. Since it is not possible to seek in a compressed file, the FILE* returned by asset_fopen will assert on seek, even if the file is not compressed (so that the user code will be ready for adding compression at any time).

If you know that the file will never be compressed and you absolutely need to freely seek, simply use the standard fopen() function.

Asset compression

To compress your own data files, you can use the mkasset tool.

There are currently two compression levels:

To minimize text siz and RAM usage, only the decompression code for level 1 is compiled by default. If you need to use level 2, you must call asset_init_compression(2).