background.h File Reference

SNES Background Layer Management. More...

#include <snes/types.h>

Go to the source code of this file.

Macros
#define	BG_16COLORS   16
#define	BG_256COLORS   256
#define	BG_4COLORS   4
#define	BG_4COLORS0   1
#define	BG_MAP_32x32   0
#define	BG_MAP_32x64   2
#define	BG_MAP_64x32   1
#define	BG_MAP_64x64   3
#define	bgClearTilemap(vramAddr, fillTile, sizeBytes)    dmaFillVRAM((u16)(fillTile), (u16)(vramAddr), (u16)(sizeBytes))
	Fill a tilemap region in VRAM with a single tile entry.
#define	SC_32x32   BG_MAP_32x32
#define	SC_32x64   BG_MAP_32x64
#define	SC_64x32   BG_MAP_64x32
#define	SC_64x64   BG_MAP_64x64

Functions
u16	bgGetScrollX (u8 bg)
	Get current horizontal scroll position (from shadow)
u16	bgGetScrollY (u8 bg)
	Get current vertical scroll position (from shadow)
void	bgInit (u8 bg)
	Initialize background layer to defaults.
void	bgInitTileSet (u8 bgNumber, u8 *tileSource, u8 *tilePalette, u8 paletteEntry, u16 tileSize, u16 paletteSize, u16 colorMode, u16 vramAddr)
	Initialize tileset with tiles and palette.
void	bgInitTileSetData (u8 bgNumber, u8 *tileSource, u16 tileSize, u16 vramAddr)
	Load tile graphics only (no palette)
void	bgSetGfxPtr (u8 bg, u16 vramAddr)
	Set background tile graphics address.
void	bgSetMapPtr (u8 bg, u16 vramAddr, u8 mapSize)
	Set background tilemap address and size.
void	bgSetScroll (u8 bg, u16 x, u16 y)
	Set background scroll position.
void	bgSetScrollX (u8 bg, u16 x)
	Set horizontal scroll only.
void	bgSetScrollY (u8 bg, u16 y)
	Set vertical scroll only.

Detailed Description

SNES Background Layer Management.

Functions for configuring and scrolling background layers.

Overview

The SNES has up to 4 background layers (BG1-BG4), though not all modes support all layers. Use these functions to configure tilemap addresses, tile graphics addresses, and scroll positions.

Author

OpenSNES Team

Copyright

MIT License

Macro Definition Documentation

bgClearTilemap

#define bgClearTilemap	(		vramAddr,
			fillTile,
			sizeBytes
	)		dmaFillVRAM((u16)(fillTile), (u16)(vramAddr), (u16)(sizeBytes))

Fill a tilemap region in VRAM with a single tile entry.

Clears or fills a background tilemap. Thin wrapper around dmaFillVRAM() with tilemap-focused naming.

Parameters

vramAddr	VRAM word address of the tilemap
fillTile	Tile entry to fill with (includes palette/priority bits)
sizeBytes	Size of the tilemap in bytes (e.g., 2048 for 32x32)

// Clear BG1 tilemap (32x32 = 2048 bytes) with tile 0
bgClearTilemap(0x0400, 0x0000, 2048);
 
// Fill with a specific tile entry (palette 2, tile 5)
bgClearTilemap(0x0400, 0x1005, 2048);

Function Documentation

bgGetScrollX()

u16 bgGetScrollX

(

u8

bg

)

Get current horizontal scroll position (from shadow)

Parameters

bg	Background number (0-3)

Returns

Horizontal scroll value last set by bgSetScroll/bgSetScrollX

bgGetScrollY()

u16 bgGetScrollY

(

u8

bg

)

Get current vertical scroll position (from shadow)

Parameters

bg	Background number (0-3)

Returns

Vertical scroll value last set by bgSetScroll/bgSetScrollY

bgInit()

void bgInit

(

u8

bg

)

Initialize background layer to defaults.

Resets scroll to (0,0) for the specified background.

Parameters

bg	Background number (0-3)

bgInitTileSet()

void bgInitTileSet	(	u8	bgNumber,
		u8 *	tileSource,
		u8 *	tilePalette,
		u8	paletteEntry,
		u16	tileSize,
		u16	paletteSize,
		u16	colorMode,
		u16	vramAddr
	)

Initialize tileset with tiles and palette.

Loads tile graphics to VRAM and palette to CGRAM, and configures the background's tile graphics pointer.

Parameters

bgNumber	Background number (0-3)
tileSource	Address of tile graphics data
tilePalette	Address of palette data
paletteEntry	Palette slot (0-7 for 16-color, 0 for 256-color)
tileSize	Size of tile data in bytes
paletteSize	Size of palette data in bytes
colorMode	Color mode (BG_4COLORS, BG_16COLORS, BG_256COLORS)
vramAddr	VRAM address for tiles (must be 4KB aligned)

extern char tiles[], tiles_end[];
extern char palette[];
bgInitTileSet(0, tiles, palette, 0, tiles_end - tiles, 32, BG_16COLORS, 0x2000);

bgInitTileSetData()

void bgInitTileSetData	(	u8	bgNumber,
		u8 *	tileSource,
		u16	tileSize,
		u16	vramAddr
	)

Load tile graphics only (no palette)

Parameters

bgNumber	Background number (0-3, or 0xFF to skip gfx pointer setup)
tileSource	Address of tile graphics data
tileSize	Size of tile data in bytes
vramAddr	VRAM address for tiles

bgSetGfxPtr()

void bgSetGfxPtr	(	u8	bg,
		u16	vramAddr
	)

Set background tile graphics address.

Configures where the background's tile graphics (CHR) are located in VRAM.

Parameters

bg	Background number (0-3)
vramAddr	VRAM word address (must be 8KB aligned, i.e., multiple of 0x2000)

// Set BG1 tiles at VRAM $2000
bgSetGfxPtr(0, 0x2000);

Note

BG1/BG2 share one register, BG3/BG4 share another. Setting one does not affect the other in the pair.

bgSetMapPtr()

void bgSetMapPtr	(	u8	bg,
		u16	vramAddr,
		u8	mapSize
	)

Set background tilemap address and size.

Configures where the background's tilemap data is located in VRAM and the map size (number of screens).

Parameters

bg	Background number (0-3)
vramAddr	VRAM word address (must be 1KB aligned, i.e., multiple of 0x400)
mapSize	Map size (BG_MAP_32x32, BG_MAP_64x32, BG_MAP_32x64, or BG_MAP_64x64)

// Set BG1 tilemap at VRAM $0000, 32x32 size
bgSetMapPtr(0, 0x0000, BG_MAP_32x32);
 
// Set BG2 tilemap at VRAM $0800, 64x32 size
bgSetMapPtr(1, 0x0800, BG_MAP_64x32);

bgSetScroll()

void bgSetScroll	(	u8	bg,
		u16	x,
		u16	y
	)

Set background scroll position.

Parameters

bg	Background number (0-3 for BG1-BG4)
x	Horizontal scroll (0-1023)
y	Vertical scroll (0-1023)

// Scroll BG1 right by 10 pixels
bgSetScroll(0, scrollX, 0);

bgSetScrollX()

void bgSetScrollX	(	u8	bg,
		u16	x
	)

Set horizontal scroll only.

Parameters

bg	Background number (0-3)
x	Horizontal scroll

bgSetScrollY()

void bgSetScrollY	(	u8	bg,
		u16	y
	)

Set vertical scroll only.

Parameters

bg	Background number (0-3)
y	Vertical scroll