backgrounds¶

This module makes it possible to work with “background” assets, each of which consists of tile image data, tile map data, 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
Arrange the map data into blocks of 32x32 tiles (for non-affine BGs only!)
bfBlankTile
First tile in the tileset will be empty. (Uuuuhhh avoid this one for now.)

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:

An array of rectangular areas of the map to be exempt from tile deduplication & flipping. Tiles touching a region are guaranteed to be unique and arranged in a predictable order, allowing you to render text onto them with tte (Tonc Text Engine).

Each element is a tuple of the form (layout, x1, y1, x2, y2), where layout is either Chr4c or Chr4r (see surfaces for explanation), and the coordinates are measured in pixels and are inclusive.

Types¶

type BgKind = enum¶

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

type BgFlag = enum¶

bfScreenblock
bfBlankTile
bfAutoPal

type BgData = object¶

Field	Type
`kind`	BgKind
`w`	int
`h`	int
`imgWords`	uint16
`mapWords`	uint16
`palHalfwords`	uint16
`palOffset`	uint16
`tileOffset`	uint16
`flags`	set[BgFlag]
`regions`	seq[BgRegion]
`tileComp`	CompressionKind
`mapComp`	CompressionKind

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 asset by copying its tiles, map, and palette into memory.

Note

The palette will be copied into bgPalBuf starting at a palette slot determined by the BG asset’s palOffset parameter set in the BG config file.

You must call flushPals to copy the colors from the buffer into actual PAL RAM.

Bgcnt:: A BG control register value which determines where in VRAM 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

# later, during VBlank:
flushPals()

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.

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.

proc loadPal(bg: Background, palId: range[0..15])¶

Copy a background’s palette into buffered palette memory.

Bg:: The background asset to use.
PalId:: The palette will be copied to this location in bgPalBuf.