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)
	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, const u8 *tileSource, const u8 *tilePalette, u8 paletteEntry, u16 tileSize, u16 paletteSize, u16 colorMode, u16 vramAddr)
	Initialize tileset with tiles and palette.
void	bgInitTileSetData (u8 bgNumber, const 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 )

Value:

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,
		const u8 *	tileSource,
		const 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 WORD address for tiles, a multiple of 0x1000 words (see bgSetGfxPtr())

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,
		const 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, a multiple of 0x1000 words (the register holds vramAddr >> 12; lower bits are dropped silently). Said "multiple of 0x2000" until 2026-09-20 — that is the same step counted in bytes.

// 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, a multiple of 0x400 words (2 KB of VRAM): BGnSC holds the base in those units (until 2026-10-04 this line said "1KB aligned")
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): the tilemap pixel row shown on the first picture line. The lib writes y - 1 to BGnVOFS because the PPU never outputs scanline 0 (see KNOWN_LIMITATIONS, "Vertical scroll is off by one"); code that writes BGnVOFS itself (HDMA tables) must apply the -1 on its own. Exception: BG3 (bg = 2) in Modes 2, 4 and 6 is the offset-per-tile table, and its y is written raw — y / 8 is the table row the PPU reads first.

Note

A layer number of 4 or more is ignored, here and in bgSetScrollX() and bgSetScrollY().

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

See also

Measured frame costs — what this call costs per frame in five real scenes.

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