====== Generated Asset Macros ======

The GameTank SDK uses generated header files for providing references to imported game assets.

===== Asset Bank Headers =====

Every subfolder of the ''assets'' folder in the project root will have a corresponding header file created under ''src/gen/assets'' after running ''make'' or ''make import''.

These header files will contain a handful of macros for each file in that assets subfolder. These macros are generated from the filename and parent folder name as follows:

<code>
ASSET__{dir name}__{file name without extension}_{extension}
or
ASSET__{dir name}__{file name without extension}_{extension}_{suffix}
</code>

The version without ''_suffix'' is a reference that can be passed into functions expecting consecutive pointer and bank number arguments.

The versions with ''_suffix'' are used to give specific generated properties used to reference the asset:

''_ptr'' gives the address where the asset can be found when its bank is active

''_bank'' gives the number of the ROM bank where the asset data resides

''_ID'' gives the index of the asset within its respective Extension Table (see below)

''_size'' if present gives the size of the original unconverted file (so it's mainly useful when the file is a binary copied straight into the ROM, such as .bin or .sfx)

==== Example ====
<code>
play_song(ASSET__audio__gameloop_mid, REPEAT_LOOP);
</code>
Here, ''play_song'' actually takes three arguments and ''%%ASSET__audio__gameloop_mid%%'' provides the first two. The macro resolves to ''%%ASSET__audio__gameloop_mid_ptr, ASSET__audio__gameloop_mid_bank%%'' and saves you a lot of typing.

===== Extension Tables =====

In addition to the header files for each asset folder, the assets are also indexed by their file extension so that some functions can refer to them by a numeric ID. This means that each file extension present under the ''assets'' folder will get a pair of arrays defined in ''assets_index.h'':

<code>
extern const void* ASSET__{extension}_ptr_table[]; //Table of pointers to asset data

extern const unsigned char ASSET__{extension}_bank_table[]; //Table of asset bank numbers
</code>

Of special note are the tables for ''.bmp'' and ''.sfx'' which will be created even if they are empty. These are used by SDK functions so they need to always be defined.

These tables make it possible to pass a reference to an asset by a single byte argument instead of three bytes of argument. This helps avoid invoking the C soft stack and increases performance.