asset.h File Reference

Opt-in asset bundle convention — package tiles + palette (+ optional tilemap) into a typed value, load it with one function call. More...

#include <snes/types.h>
#include <snes/background.h>
#include <snes/dma.h>

Go to the source code of this file.

Classes
struct	BgAsset
	A full background bundle: tileset + tilemap + map size. More...
struct	GfxAsset
	A tileset bundle: graphics + palette + color depth. More...

Macros
#define	DECLARE_BG_ASSET(name, color_mode_, map_size_)
	Declare a static const BgAsset from gfx4snes-style symbol pairs.
#define	DECLARE_GFX_ASSET(name, color_mode_)
	Declare a static const GfxAsset from gfx4snes-style symbol pairs.

Functions
void	bgLoad (u8 bg, const BgAsset *asset, u8 palette_slot, u16 tiles_vram, u16 map_vram)
	Load a full background bundle — typed-value variant of BG_LOAD.
void	gfxLoad (u8 bg, const GfxAsset *asset, u8 palette_slot, u16 tiles_vram)
	Load a tileset (tiles + palette) and configure a BG's tile graphics pointer — typed-value variant of GFX_LOAD.

Detailed Description

Opt-in asset bundle convention — package tiles + palette (+ optional tilemap) into a typed value, load it with one function call.

One of the three "framework opt-ins" promised by PHILOSOPHY.md (alongside gameloop and scene). This module removes a recurring piece of SNES boilerplate: declaring six extern symbols (begin/end pairs for tiles, palette, tilemap), computing three sizes by subtraction at every call site, and threading them through an 8-parameter bgInitTileSet() followed by a separate dmaCopyVram() for the map.

Before

extern u8 tiles[],   tiles_end[];
extern u8 palette[], palette_end[];
extern u8 tilemap[], tilemap_end[];
 
bgSetMapPtr(0, 0x0000, SC_32x32);
bgInitTileSet(0, tiles, palette, 0,
              tiles_end - tiles,
              palette_end - palette,
              BG_16COLORS, 0x4000);
dmaCopyVram(tilemap, 0x0000, tilemap_end - tilemap);

After

// data.asm exports bg_tiles, bg_pal, bg_map (each with _end labels).
DECLARE_BG_ASSET(bg, BG_16COLORS, SC_32x32);
bgLoad(0, &bg, 0, 0x4000, 0x0000);

DECLARE_BG_ASSET is constructor sugar — it expands to the six extern declarations and a static const BgAsset initialised from those symbols. Users who want to instantiate the struct manually can do so; the macro is a convenience, the struct is the contract.

The macros expect the symbol naming convention <name>_tiles, <name>_pal, <name>_map plus their _end siblings. The user chooses the prefix once in their data.asm.

Why a typed value

The asset is a first-class value: pass it to a function, store an array of them as a level table indexed at runtime, swap assets at scene boundaries. Each callsite is one bgLoad/gfxLoad call, no positional-parameter shuffle.

What this module does NOT do

• It does not configure the background mode (setMode), the main screen mask (setMainScreen), or the screen brightness (setScreenOn). The caller still owns the high-level init order.
• It does not handle sprite asset bundles. Sprites have their own CGRAM offset (128) and OAM conventions; out of scope here.
• It does not handle the Tiled mapdata pipeline (tilesetdef, tilesetatt, large levels). Those still go through mapLoad().

Performance

gfxLoad and bgLoad are thin C wrappers over bgInitTileSet, dmaCopyVram, and bgSetMapPtr. The compiler emits one indirect load per struct field; on the order of 30 cycles of overhead per call. All real work is done by the underlying DMA, which is unchanged.

Modules required

asset (transitively pulls dma and background).

See also

background.h, dma.h

Macro Definition Documentation

DECLARE_BG_ASSET

#define DECLARE_BG_ASSET	(		name,
			color_mode_,
			map_size_ )

Value:

extern u8 name##_tiles[], name##_tiles_end[];                             \
extern u8 name##_pal[],   name##_pal_end[];                               \
extern u8 name##_map[],   name##_map_end[];                               \
static const BgAsset name = {                                             \
    .gfx = {                                                              \
        .tiles       = name##_tiles,                                      \
        .tiles_end   = name##_tiles_end,                                  \
        .palette     = name##_pal,                                        \
        .palette_end = name##_pal_end,                                    \
        .color_mode  = (color_mode_),                                     \
    },                                                                    \
    .tilemap     = name##_map,                                            \
    .tilemap_end = name##_map_end,                                        \
    .map_size    = (map_size_),                                           \
}

Declare a static const BgAsset from gfx4snes-style symbol pairs.

Same convention as DECLARE_GFX_ASSET, plus <name>_map / <name>_map_end for the tilemap blob.

DECLARE_BG_ASSET(scene, BG_16COLORS, SC_32x32);
bgLoad(0, &scene, 0, 0x4000, 0x0000);

DECLARE_GFX_ASSET

#define DECLARE_GFX_ASSET	(		name,
			color_mode_ )

Value:

extern u8 name##_tiles[], name##_tiles_end[];                             \
extern u8 name##_pal[],   name##_pal_end[];                               \
static const GfxAsset name = {                                            \
    .tiles       = name##_tiles,                                          \
    .tiles_end   = name##_tiles_end,                                      \
    .palette     = name##_pal,                                            \
    .palette_end = name##_pal_end,                                        \
    .color_mode  = (color_mode_),                                         \
}

Declare a static const GfxAsset from gfx4snes-style symbol pairs.

Expands to extern declarations for <name>_tiles/<name>_tiles_end and <name>_pal/<name>_pal_end, plus a static const GfxAsset populated with the right pointers and color mode.

DECLARE_GFX_ASSET(player, BG_16COLORS);
gfxLoad(0, &player, 0, 0x4000);

Function Documentation

bgLoad()

void bgLoad	(	u8	bg,
		const BgAsset *	asset,
		u8	palette_slot,
		u16	tiles_vram,
		u16	map_vram )

Load a full background bundle — typed-value variant of BG_LOAD.

Composes gfxLoad() with bgSetMapPtr() and a dmaCopyVram() of the tilemap. After the call the BG is fully addressable; the caller still controls when to enable it on the screen.

Parameters

bg	Background number 0-3.
asset	Bundle to load. Must be non-NULL.
palette_slot	Palette slot index (see gfxLoad).
tiles_vram	VRAM word address for the tile graphics.
map_vram	VRAM word address for the tilemap.

gfxLoad()

void gfxLoad	(	u8	bg,
		const GfxAsset *	asset,
		u8	palette_slot,
		u16	tiles_vram )

Load a tileset (tiles + palette) and configure a BG's tile graphics pointer — typed-value variant of GFX_LOAD.

Parameters

bg	Background number 0-3.
asset	Bundle to load. Must be non-NULL.
palette_slot	Palette slot index (0-7 for 16-color, etc.).
tiles_vram	VRAM word address for the tile graphics (4 KB aligned).