libnds
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
background.h File Reference

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

enum  BackgroundControl {
  BG_32x32 = (0 << 14),
  BG_64x32 = (1 << 14),
  BG_32x64 = (2 << 14),
  BG_64x64 = (3 << 14),
  BG_RS_16x16 = (0 << 14),
  BG_RS_32x32 = (1 << 14),
  BG_RS_64x64 = (2 << 14),
  BG_RS_128x128 = (3 << 14),
  BG_BMP8_128x128 = ((0 << 14) | BIT(7)),
  BG_BMP8_256x256 = ((1 << 14) | BIT(7)),
  BG_BMP8_512x256 = ((2 << 14) | BIT(7)),
  BG_BMP8_512x512 = ((3 << 14) | BIT(7)),
  BG_BMP8_1024x512 = BIT(14),
  BG_BMP8_512x1024 = 0,
  BG_BMP16_128x128 = ((0 << 14) | BIT(7) | BIT(2)),
  BG_BMP16_256x256 = ((1 << 14) | BIT(7) | BIT(2)),
  BG_BMP16_512x256 = ((2 << 14) | BIT(7) | BIT(2)),
  BG_BMP16_512x512 = ((3 << 14) | BIT(7) | BIT(2)),
  BG_MOSAIC_ON = (BIT(6)),
  BG_MOSAIC_OFF = (0),
  BG_PRIORITY_0 = (0),
  BG_PRIORITY_1 = (1),
  BG_PRIORITY_2 = (2),
  BG_PRIORITY_3 = (3),
  BG_WRAP_OFF = (0),
  BG_WRAP_ON = (1 << 13),
  BG_PALETTE_SLOT0 = 0,
  BG_PALETTE_SLOT1 = 0,
  BG_PALETTE_SLOT2 = BIT(13),
  BG_PALETTE_SLOT3 = BIT(13),
  BG_COLOR_256 = 0x80,
  BG_COLOR_16 = 0x00
}
 Bit defines for the background control registers. More...
 
enum  BgSize {
  BgSize_R_128x128 = (0 << 14),
  BgSize_R_256x256 = (1 << 14),
  BgSize_R_512x512 = (2 << 14),
  BgSize_R_1024x1024 = (3 << 14),
  BgSize_T_256x256 = (0 << 14) | (1 << 16),
  BgSize_T_512x256 = (1 << 14) | (1 << 16),
  BgSize_T_256x512 = (2 << 14) | (1 << 16),
  BgSize_T_512x512 = (3 << 14) | (1 << 16),
  BgSize_ER_128x128 = (0 << 14) | (2 << 16),
  BgSize_ER_256x256 = (1 << 14) | (2 << 16),
  BgSize_ER_512x512 = (2 << 14) | (2 << 16),
  BgSize_ER_1024x1024 = (3 << 14) | (2 << 16),
  BgSize_B8_128x128 = ((0 << 14) | BIT(7) | (3 << 16)),
  BgSize_B8_256x256 = ((1 << 14) | BIT(7) | (3 << 16)),
  BgSize_B8_512x256 = ((2 << 14) | BIT(7) | (3 << 16)),
  BgSize_B8_512x512 = ((3 << 14) | BIT(7) | (3 << 16)),
  BgSize_B8_1024x512 = (1 << 14) | (3 << 16),
  BgSize_B8_512x1024 = (0) | (3 << 16),
  BgSize_B16_128x128 = ((0 << 14) | BIT(7) | BIT(2) | (4 << 16)),
  BgSize_B16_256x256 = ((1 << 14) | BIT(7) | BIT(2) | (4 << 16)),
  BgSize_B16_512x256 = ((2 << 14) | BIT(7) | BIT(2) | (4 << 16)),
  BgSize_B16_512x512 = ((3 << 14) | BIT(7) | BIT(2) | (4 << 16))
}
 Allowed background Sizes The lower 16 bits of these defines can be used directly to set the background control register bits. More...
 
enum  BgType {
  BgType_Text8bpp,
  BgType_Text4bpp,
  BgType_Rotation,
  BgType_ExRotation,
  BgType_Bmp8,
  BgType_Bmp16
}
 Allowed background types, used in bgInit and bgInitSub. More...
 

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 u16bgGetGfxPtr (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 u16bgGetMapPtr (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 vuint16bgSetControlBits (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.