nds background defines and functionality. More...

#include <nds/ndstypes.h>
#include <nds/arm9/video.h>
#include <nds/arm9/sassert.h>
#include <nds/memory.h>
#include <nds/dma.h>

Data Structures
struct	bg_attribute
	register overlay for background attribute registers More...

struct	bg_scroll
	register overlay for scroll registers More...

struct	bg_transform
	register overlay for affine matrix registers More...

struct	TileMapEntry16
	Overlay for 16-bit tile map entries. More...

struct	TileMapEntry8
	Overlay for 8-bit tile map entries. More...

Macros
#define	BACKGROUND (((bg_attribute )0x04000008))
	Overlay for main screen background attributes. Setting the properties of this struct directly sets background registers.

#define	BACKGROUND_SUB (((bg_attribute )0x04001008))
	Overlay for sub screen background attributes. Setting the properties of this struct directly sets background registers.

#define	BG_BMP_BASE(base) ((base) << MAP_BASE_SHIFT)
	Macro to set the graphics base in background control.

#define	BG_BMP_RAM(base) ((u16)(((base)0x4000) + 0x06000000))
	A macro which returns a u16* pointer to background graphics memory ram (Main Engine)

#define	BG_BMP_RAM_SUB(base) ((u16)(((base)0x4000) + 0x06200000))
	A macro which returns a u16* pointer to background graphics ram (Sub Engine)

#define	BG_MAP_BASE(base) ((base) << MAP_BASE_SHIFT)
	Macro to set the map base in background control.

#define	BG_MAP_RAM(base) ((u16)(((base)0x800) + 0x06000000))
	A macro which returns a u16* pointer to background map ram (Main Engine)

#define	BG_MAP_RAM_SUB(base) ((u16)(((base)0x800) + 0x06200000))
	A macro which returns a u16* pointer to background map ram (Sub Engine)

#define	BG_OFFSET ((bg_scroll *)(0x04000010))
	Overlay for main screen background scroll registers. Setting the properties of this struct directly sets background registers.

#define	BG_OFFSET_SUB ((bg_scroll *)(0x04001010))
	Overlay for sub screen background scroll registers. Setting the properties of this struct directly sets background registers.

#define	BG_PRIORITY(n) (n)
	Macro to set the priority in background control.

#define	BG_TILE_BASE(base) ((base) << TILE_BASE_SHIFT)
	Macro to set the tile base in background control.

#define	BG_TILE_RAM(base) ((u16)(((base)0x4000) + 0x06000000))
	A macro which returns a u16* pointer to background tile ram (Main Engine)

#define	BG_TILE_RAM_SUB(base) ((u16)(((base)0x4000) + 0x06200000))
	A macro which returns a u16* pointer to background tile ram (Sub Engine)

#define	BGCTRL ( (vu16*)0x4000008)
	Access to all Main screen background control registers via: BGCTRL[x] GBATEK Reference

#define	BGCTRL_SUB ( (vu16*)0x4001008)
	Access to all Sub screen background control registers via: BGCTRL[x] GBATEK Reference

#define	MAP_BASE_SHIFT 8
	The shift to apply to map base when storing it in a background control register.

#define	REG_BG0CNT ((vu16)0x4000008)
	Background 0 Control register (main engine) GBATEK Reference

#define	REG_BG0CNT_SUB ((vu16)0x4001008)
	Background 0 Control register (sub engine) GBATEK Reference

#define	REG_BG0HOFS ((vu16)0x4000010)
	Background 0 horizontal scroll register (main engine)

#define	REG_BG0HOFS_SUB ((vu16)0x4001010)
	Background 0 horizontal scroll register (sub engine)

#define	REG_BG0VOFS ((vu16)0x4000012)
	Background 0 vertical scroll register (main engine)

#define	REG_BG0VOFS_SUB ((vu16)0x4001012)
	Background 0 vertical scroll register (sub engine)

#define	REG_BG1CNT ((vu16)0x400000A)
	Background 1 Control register (main engine) GBATEK Reference

#define	REG_BG1CNT_SUB ((vu16)0x400100A)
	Background 1 Control register (sub engine) GBATEK Reference

#define	REG_BG1HOFS ((vu16)0x4000014)
	Background 1 horizontal scroll register (main engine)

#define	REG_BG1HOFS_SUB ((vu16)0x4001014)
	Background 1 horizontal scroll register (sub engine)

#define	REG_BG1VOFS ((vu16)0x4000016)
	Background 1 vertical scroll register (main engine)

#define	REG_BG1VOFS_SUB ((vu16)0x4001016)
	Background 1 vertical scroll register (sub engine)

#define	REG_BG2CNT ((vu16)0x400000C)
	Background 2 Control register (main engine) GBATEK Reference

#define	REG_BG2CNT_SUB ((vu16)0x400100C)
	Background 2 Control register (sub engine) GBATEK Reference

#define	REG_BG2HOFS ((vu16)0x4000018)
	Background 2 horizontal scroll register (main engine)

#define	REG_BG2HOFS_SUB ((vu16)0x4001018)
	Background 2 horizontal scroll register (sub engine)

#define	REG_BG2PA ((vs16)0x4000020)
	Background 2 Affine transform (main engine)

#define	REG_BG2PA_SUB ((vs16)0x4001020)
	Background 2 Affine transform (sub engine)

#define	REG_BG2PB ((vs16)0x4000022)
	Background 2 Affine transform (main engine)

#define	REG_BG2PB_SUB ((vs16)0x4001022)
	Background 2 Affine transform (sub engine)

#define	REG_BG2PC ((vs16)0x4000024)
	Background 2 Affine transform (main engine)

#define	REG_BG2PC_SUB ((vs16)0x4001024)
	Background 2 Affine transform (sub engine)

#define	REG_BG2PD ((vs16)0x4000026)
	Background 2 Affine transform (main engine)

#define	REG_BG2PD_SUB ((vs16)0x4001026)
	Background 2 Affine transform (sub engine)

#define	REG_BG2VOFS ((vu16)0x400001A)
	Background 2 vertical scroll register (main engine)

#define	REG_BG2VOFS_SUB ((vu16)0x400101A)
	Background 2 vertical scroll register (sub engine)

#define	REG_BG2X ((vs32)0x4000028)
	Background 2 Screen Offset (main engine)

#define	REG_BG2X_SUB ((vs32)0x4001028)
	Background 2 Screen Offset (sub engine)

#define	REG_BG2Y ((vs32)0x400002C)
	Background 2 Screen Offset (main engine)

#define	REG_BG2Y_SUB ((vs32)0x400102C)
	Background 2 Screen Offset (sub engine)

#define	REG_BG3CNT ((vu16)0x400000E)
	Background 3 Control register (main engine) GBATEK Reference

#define	REG_BG3CNT_SUB ((vu16)0x400100E)
	Background 3 Control register (sub engine) GBATEK Reference

#define	REG_BG3HOFS ((vu16)0x400001C)
	Background 3 horizontal scroll register (main engine)

#define	REG_BG3HOFS_SUB ((vu16)0x400101C)
	Background 3 horizontal scroll register (sub engine)

#define	REG_BG3PA ((vs16)0x4000030)
	Background 3 Affine transform (main engine)

#define	REG_BG3PA_SUB ((vs16)0x4001030)
	Background 3 Affine transform (sub engine)

#define	REG_BG3PB ((vs16)0x4000032)
	Background 3 Affine transform (main engine)

#define	REG_BG3PB_SUB ((vs16)0x4001032)
	Background 3 Affine transform (sub engine)

#define	REG_BG3PC ((vs16)0x4000034)
	Background 3 Affine transform (main engine)

#define	REG_BG3PC_SUB ((vs16)0x4001034)
	Background 3 Affine transform (sub engine)

#define	REG_BG3PD ((vs16)0x4000036)
	Background 3 Affine transform (main engine)

#define	REG_BG3PD_SUB ((vs16)0x4001036)
	Background 3 Affine transform (sub engine)

#define	REG_BG3VOFS ((vu16)0x400001E)
	Background 3 vertical scroll register (main engine)

#define	REG_BG3VOFS_SUB ((vu16)0x400101E)
	Background 3 vertical scroll register (sub engine)

#define	REG_BG3X ((vs32)0x4000038)
	Background 3 Screen Offset (main engine)

#define	REG_BG3X_SUB ((vs32)0x4001038)
	Background 3 Screen Offset (sub engine)

#define	REG_BG3Y ((vs32)0x400003C)
	Background 3 Screen Offset (main engine)

#define	REG_BG3Y_SUB ((vs32)0x400103C)
	Background 3 Screen Offset (sub engine)

#define	TILE_BASE_SHIFT 2
	The shift to apply to tile base when storing it in a background control register.

#define	TILE_FLIP_H BIT(10)
	The horizontal flip bit for a 16 bit tile index.

#define	TILE_FLIP_V BIT(11)
	The vertical flip bit for a 16 bit tile index.

#define	TILE_PALETTE(n) ((n)<<12)
	Macro to set the palette entry of a 16 bit tile index.

Typedefs
typedef struct bg_attribute	bg_attribute
	register overlay for background attribute registers

typedef struct bg_scroll	bg_scroll
	register overlay for scroll registers

typedef struct bg_transform	bg_transform
	register overlay for affine matrix registers

typedef struct TileMapEntry16	TileMapEntry16
	Overlay for 16-bit tile map entries.

typedef struct TileMapEntry8	TileMapEntry8
	Overlay for 8-bit tile map entries.

Enumerations

Functions
static void	bgClearControlBits (int id, u16 bits)
	Clears the specified bits from the backgrounds control register. More...

static void	bgExtPaletteDisable (void)
	Disable extended palettes. More...

static void	bgExtPaletteDisableSub (void)
	Disable extended palettes. More...

static void	bgExtPaletteEnable (void)
	Enable extended palettes. More...

static void	bgExtPaletteEnableSub (void)
	Enable extended palettes. More...

static u16 *	bgGetGfxPtr (int id)
	Gets a pointer to the background graphics. More...

static int	bgGetMapBase (int id)
	Gets the current map base for the supplied background. More...

static u16 *	bgGetMapPtr (int id)
	Gets a pointer to the background map. More...

static int	bgGetPriority (int id)
	Gets the background priority. More...

static int	bgGetTileBase (int id)
	Gets the background tile base. More...

static void	bgHide (int id)
	Hides the current background via the display control register. More...

static int	bgInit (int layer, BgType type, BgSize size, int mapBase, int tileBase)
	Initializes a background on the main display Sets up background control register with specified settings and defaults to 256 color mode for tiled backgrounds. Sets the rotation/scale attributes for rot/ex rot backgrounds to 1:1 scale and 0 angle of rotation. More...

static int	bgInitSub (int layer, BgType type, BgSize size, int mapBase, int tileBase)
	Initializes a background on the sub display Sets up background control register with specified settings and defaults to 256 color mode for tiled backgrounds. Sets the rotation/scale attributes for rot/ex rot backgrounds to 1:1 scale and 0 angle of rotation. More...

static void	bgMosaicDisable (int id)
	Disables mosaic on the specified background. More...

static void	bgMosaicEnable (int id)
	Enables mosaic on the specified background. More...

static void	bgRotate (int id, int angle)
	Rotates the background counter clockwise by the specified angle. (this rotation is cumulative) More...

static void	bgScroll (int id, int dx, int dy)
	Scrolls the background by the specified relative values. More...

static void	bgScrollf (int id, s32 dx, s32 dy)
	Scrolls the background by the specified relative values (fixed point) More...

static void	bgSet (int id, int angle, s32 sx, s32 sy, s32 scrollX, s32 scrollY, s32 rotCenterX, s32 rotCenterY)
	Sets the rotation and scale of the background and update background control registers. More...

static void	bgSetAffineMatrixScroll (int id, int hdx, int vdx, int hdy, int vdy, int scrollx, int scrolly)
	directly sets the affine matrix and scroll registers of a background. More...

static void	bgSetCenter (int id, int x, int y)
	Sets the center of rotation for the supplied background. More...

static void	bgSetCenterf (int id, s32 x, s32 y)
	Sets the center of rotation for the supplied background (fixed point) More...

static vuint16 *	bgSetControlBits (int id, u16 bits)
	allows direct access to background control for the chosen layer, returns a pointer to the current control bits More...

static void	bgSetMapBase (int id, unsigned int base)
	Sets the background map base. More...

static void	bgSetMosaic (unsigned int dx, unsigned int dy)
	Sets the horizontal and vertical mosaic values for all backgrounds. More...

static void	bgSetMosaicSub (unsigned int dx, unsigned int dy)
	Sets the horizontal and vertical mosaic values for all backgrounds (Sub Display) More...

static void	bgSetPriority (int id, unsigned int priority)
	Sets the background priority. More...

static void	bgSetRotate (int id, int angle)
	Sets the rotation angle of the specified background and updates the transform matrix. More...

static void	bgSetRotateScale (int id, int angle, s32 sx, s32 sy)
	Sets the rotation and scale of the background and update background control registers. More...

static void	bgSetScale (int id, s32 sx, s32 sy)
	Sets the scale of the specified background. More...

static void	bgSetScroll (int id, int x, int y)
	Sets the scroll hardware to the specified location. More...

static void	bgSetScrollf (int id, s32 x, s32 y)
	Sets the scroll hardware to the specified location (fixed point) More...

static void	bgSetTileBase (int id, unsigned int base)
	Sets the background map base. More...

static void	bgShow (int id)
	Shows the current background via the display control register. More...

void	bgUpdate (void)
	Must be called once per frame to update scroll/scale/and rotation of backgrounds.

static void	bgWrapOff (int id)
	turns wrap off for a background. has no effect on text backgrounds, which are always wrapped. More...

static void	bgWrapOn (int id)
	turns wrap on for a background. has no effect on text backgrounds, which are always wrapped. More...

Detailed Description

nds background defines and functionality.

Background control is provided via an API or Direct register access. Usually these methods can be mixed. However, scrolling, scaling, and rotation will have unexpected results if API and Direct Register access is mixed. Effort is being directed at ensuring the API can access all hardware features without limitation.

The DS contains two separate hardware 2D cores responsible for rendering 2D backgrounds. The definitions below outline the libnds api for utilizing these backgrounds.

The background engine provides basic initialization and management of the 8 2D backgrounds available on the DS. Other than initialization and hardware limitations background control is identical on both main and sub screens.

The following modes of operation are allowed:

Main 2D engine
______________________________
|Mode | BG0 | BG1 | BG2 |BG3 |           T = Text
|  0  |  T  |  T  |  T  |  T |           R = Rotation
|  1  |  T  |  T  |  T  |  R |           E = Extended Rotation
|  2  |  T  |  T  |  R  |  R |           L = Large Bitmap background
|  3  |  T  |  T  |  T  |  E |
|  4  |  T  |  T  |  R  |  E |
|  5  |  T  |  T  |  E  |  E |
|  6  |     |  L  |     |    |
-----------------------------

Sub 2D engine
______________________________
|Mode | BG0 | BG1 | BG2 |BG3 |
|  0  |  T  |  T  |  T  |  T |
|  1  |  T  |  T  |  T  |  R |
|  2  |  T  |  T  |  R  |  R |
|  3  |  T  |  T  |  T  |  E |
|  4  |  T  |  T  |  R  |  E |
|  5  |  T  |  T  |  E  |  E |
-----------------------------

On the main engine BG0 can be uses as a 3D rendering surface.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description