backgrounds#

This module makes it possible to work with “background” assets, each of which consists of tile image data, tile map, and palette data.

Tutorial#

To add a new background asset in your game.

Create a 256x256 image:

Save it to backgrounds/planet.png.
Add a line to your project’s backgrounds.nims:
```
# ...

bg "planet.png", kind = bkReg4bpp, flags = { bfScreenblock }
```
A handle called bgPlanet will be created for use in your code.

Import natu/backgrounds in your game and load the new asset like so:

import natu/[video, backgrounds]

# Use a BG Control register to select a charblock and screenblock:
bgcnt[0].init(cbb = 0, sbb = 31)

# Load the tiles, map and palette into memory:
bgcnt[0].load(bgPlanet)

# Show the background:
dispcnt.init(layers = {lBg0})

Background Config Files#

proc bg(name: string, kind: BgKind, palOffset = 0, tileOffset = 0, flags: set[BgFlag] = {}, regions: openArray[BgRegion] = @[])#

Specify an image to be converted to a background.

Name:

Path to PNG file.

Kind:

The kind of BG data that the PNG should be converted to.

bkReg4bpp:: Regular background, 16 colors per-tile.
bkReg8bpp:: Regular background, 256 colors.
bkAff:: Affine background, 256 colors.

PalOffset:

Number of 16-color palettes to shift the map entries by. This also determines to which location the palette data will be copied when calling load in your game code.

TileOffset:

Number of tiles to shift the map entries by. This also determines to which location the tile image data will be copied when calling load in your game code.

Flags:

Various options that affect conversion:

bfScreenblock:: For non-affine BGs, arrange the map data into blocks of 32x32 tiles.
bfBlankTile:: First tile in the tileset will be empty. This is recommended for transparent BGs, but note that the blank tile will not be offset by the tileOffset.

Warning

This behaviour is flawed and will probably change in a future version. Ensuring the first tile in the tileset is blank vs. stripping the blank tile so that tile index 0 can be shared between multiple tilesets, should become two separate flags I guess.
bfAutoPal:: For 4bpp BGs, attempt to build a set of 16-color palettes from the image. If this flag is omitted, the PNG’s own palette will be strictly followed, and each 8x8 tile in the image must only refer to colors from a single group of 16.

Regions:

Types#

type BgKind = enum#

type BgFlag = enum#

template kind(bg: Background): BgKind#

template flags(bg: Background): set[BgFlag]#

template palOffset(bg: Background): int#

template tileOffset(bg: Background): int#

template is8bpp(bg: Background): bool#

BG Loading Procedures#

template load(bgcnt: BgCnt, bg: Background)#

Load a background by copying its tiles, map, and palette into memory.

The locations are determined by the supplied BG control register.

Parameters:

Bgcnt:: A BG control register value which determines where to copy the tiles and map.
Bg:: The asset to be loaded.

Example:

bgcnt[0].init(cbb = 0, sbb = 28)    # init BG, set img/map destination
bgcnt[0].load(bgConstructionYard)   # copy img, map and pal
dispcnt.bg0 = true                  # show BG

proc loadTiles(bg: Background, dest: pointer)#

Copy a background’s tile image data to some location in memory.

Bg:: The background asset to use.
Dest:: The location to copy the tileset to.

If your BG asset has a tileOffset specified, be sure to add that to the destination before calling this.

proc loadMap(bg: Background, dest: pointer)#

Copy a background’s map data to some location in memory.

Parameters:

Bg:: The background asset to use.
Dest:: The location to copy the map data to.

proc loadPal(bg: Background, dest: pointer)#

Copy a background’s palette to some location in memory.

Bg:: The background asset to use.
Dest:: The location to copy the palette to.