libnds
Enumerations | Functions
"Background API Access"

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 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

Enumeration Type Documentation

enum BgSize

Allowed background Sizes The lower 16 bits of these defines can be used directly to set the background control register bits.

Enumerator
BgSize_R_128x128 

128 x 128 pixel rotation background

BgSize_R_256x256 

256 x 256 pixel rotation background

BgSize_R_512x512 

512 x 512 pixel rotation background

BgSize_R_1024x1024 

1024 x 1024 pixel rotation background

BgSize_T_256x256 

256 x 256 pixel text background

BgSize_T_512x256 

512 x 256 pixel text background

BgSize_T_256x512 

256 x 512 pixel text background

BgSize_T_512x512 

512 x 512 pixel text background

BgSize_ER_128x128 

128 x 128 pixel extended rotation background

BgSize_ER_256x256 

256 x 256 pixel extended rotation background

BgSize_ER_512x512 

512 x 512 pixel extended rotation background

BgSize_ER_1024x1024 

1024 x 1024 extended pixel rotation background

BgSize_B8_128x128 

128 x 128 pixel 8 bit bitmap background

BgSize_B8_256x256 

256 x 256 pixel 8 bit bitmap background

BgSize_B8_512x256 

512 x 256 pixel 8 bit bitmap background

BgSize_B8_512x512 

512 x 512 pixel 8 bit bitmap background

BgSize_B8_1024x512 

1024 x 512 pixel 8 bit bitmap background

BgSize_B8_512x1024 

512 x 1024 pixel 8 bit bitmap background

BgSize_B16_128x128 

128 x 128 pixel 16 bit bitmap background

BgSize_B16_256x256 

256 x 256 pixel 16 bit bitmap background

BgSize_B16_512x256 

512 x 512 pixel 16 bit bitmap background

BgSize_B16_512x512 

1024 x 1024 pixel 16 bit bitmap background

enum BgType

Allowed background types, used in bgInit and bgInitSub.

Enumerator
BgType_Text8bpp 

8bpp Tiled background with 16 bit tile indexes and no allowed rotation or scaling

BgType_Text4bpp 

4bpp Tiled background with 16 bit tile indexes and no allowed rotation or scaling

BgType_Rotation 

Tiled background with 8 bit tile indexes Can be scaled and rotated.

BgType_ExRotation 

Tiled background with 16 bit tile indexes Can be scaled and rotated.

BgType_Bmp8 

Bitmap background with 8 bit color values which index into a 256 color palette.

BgType_Bmp16 

Bitmap background with 16 bit color values of the form aBBBBBGGGGGRRRRR (if 'a' is set the pixel will be rendered...if not the pixel will be transparent)

Function Documentation

static void bgClearControlBits ( int  id,
u16  bits 
)
inlinestatic

Clears the specified bits from the backgrounds control register.

Parameters
idbackground id returned from bgInit or bgInitSub
bitssets the specified bits to clear in the backgrounds control register
static void bgExtPaletteDisable ( void  )
inlinestatic

Disable extended palettes.

When extended palettes are enabled all tiled backgrounds which utilize 16 bit map entries will use extended palettes. Everything else will continue to use standard palette memory.

Each tile on the screen may chose one of 16 256-color palettes. Each background has its own set of 16 palettes meaning you can have 4*16*256 colors on screen

Each background uses 8K of palette memory starting at the base of the vram bank you allocate (which bank is up to you within limits, see the vram usage table to determine which banks can be mapped for textures). These 8K blocks are often refered to as "slots" with each background getting its own slot.

By default, Background 0 uses slot 0 ... Background 3 uses slot 3. It is possible to assign Background 0 to slot 2 and Background 1 to slot 3 (only these two are configurable)

For more information: gbatek

static void bgExtPaletteDisableSub ( void  )
inlinestatic

Disable extended palettes.

When extended palettes are enabled all tiled backgrounds which utilize 16 bit map entries will use extended palettes. Everything else will continue to use standard palette memory.

Each tile on the screen may chose one of 16 256-color palettes. Each background has its own set of 16 palettes meaning you can have 4*16*256 colors on screen

Each background uses 8K of palette memory starting at the base of the vram bank you allocate (which bank is up to you within limits, see the vram usage table to determine which banks can be mapped for textures). These 8K blocks are often refered to as "slots" with each background getting its own slot.

By default, Background 0 uses slot 0 ... Background 3 uses slot 3. It is possible to assign Background 0 to slot 2 and Background 1 to slot 3 (only these two are configurable)

For more information: gbatek

static void bgExtPaletteEnable ( void  )
inlinestatic

Enable extended palettes.

When extended palettes are enabled all tiled backgrounds which utilize 16 bit map entries will use extended palettes. Everything else will continue to use standard palette memory.

Each tile on the screen may chose one of 16 256-color palettes. Each background has its own set of 16 palettes meaning you can have 4*16*256 colors on screen

Each background uses 8K of palette memory starting at the base of the vram bank you allocate (which bank is up to you within limits, see the vram usage table to determine which banks can be mapped for textures). These 8K blocks are often refered to as "slots" with each background getting its own slot.

By default, Background 0 uses slot 0 ... Background 3 uses slot 3. It is possible to assign Background 0 to slot 2 and Background 1 to slot 3 (only these two are configurable)

For more information: gbatek

static void bgExtPaletteEnableSub ( void  )
inlinestatic

Enable extended palettes.

When extended palettes are enabled all tiled backgrounds which utilize 16 bit map entries will use extended palettes. Everything else will continue to use standard palette memory.

Each tile on the screen may chose one of 16 256-color palettes. Each background has its own set of 16 palettes meaning you can have 4*16*256 colors on screen

Each background uses 8K of palette memory starting at the base of the vram bank you allocate (which bank is up to you within limits, see the vram usage table to determine which banks can be mapped for textures). These 8K blocks are often refered to as "slots" with each background getting its own slot.

By default, Background 0 uses slot 0 ... Background 3 uses slot 3. It is possible to assign Background 0 to slot 2 and Background 1 to slot 3 (only these two are configurable)

For more information: gbatek

static u16* bgGetGfxPtr ( int  id)
inlinestatic

Gets a pointer to the background graphics.

Parameters
idbackground id returned from bgInit or bgInitSub
Returns
A pointer to the tile graphics or bitmap graphics
static int bgGetMapBase ( int  id)
inlinestatic

Gets the current map base for the supplied background.

Parameters
idbackground id returned from bgInit or bgInitSub
Returns
background map base
Note
this is the integer offset of the base not a pointer to the map
static u16* bgGetMapPtr ( int  id)
inlinestatic

Gets a pointer to the background map.

Parameters
idbackground id returned from bgInit or bgInitSub
Returns
A pointer to the map
static int bgGetPriority ( int  id)
inlinestatic

Gets the background priority.

Parameters
idbackground id returned from bgInit or bgInitSub
Returns
background priority
static int bgGetTileBase ( int  id)
inlinestatic

Gets the background tile base.

Parameters
idbackground id returned from bgInit or bgInitSub
Returns
background tile base
static void bgHide ( int  id)
inlinestatic

Hides the current background via the display control register.

Parameters
idbackground id returned from bgInit or bgInitSub
static int bgInit ( int  layer,
BgType  type,
BgSize  size,
int  mapBase,
int  tileBase 
)
inlinestatic

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.

Parameters
layerbackground hardware layer to init. Must be 0 - 3
typethe type of background to init
sizethe size of the background
mapBasethe 2k offset into vram the tile map will be placed
–OR–
the 16k offset into vram the bitmap data will be placed for bitmap backgrounds
tileBasethe 16k offset into vram the tile graphics data will be placed
Returns
the background id to be used in the supporting functions
Note
tileBase is unused for bitmap backgrounds
static int bgInitSub ( int  layer,
BgType  type,
BgSize  size,
int  mapBase,
int  tileBase 
)
inlinestatic

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.

Parameters
layerbackground hardware layer to init. Must be 0 - 3
typethe type of background to init
sizethe size of the background
mapBasethe 2k offset into vram the tile map will be placed
–OR–
the 16k offset into vram the bitmap data will be placed for bitmap backgrounds
tileBasethe 16k offset into vram the tile graphics data will be placed
Returns
the background id to be used in the supporting functions
Note
tileBase is unused for bitmap backgrounds
static void bgMosaicDisable ( int  id)
inlinestatic

Disables mosaic on the specified background.

Parameters
idbackground id returned from bgInit or bgInitSub
static void bgMosaicEnable ( int  id)
inlinestatic

Enables mosaic on the specified background.

Parameters
idbackground id returned from bgInit or bgInitSub
static void bgRotate ( int  id,
int  angle 
)
inlinestatic

Rotates the background counter clockwise by the specified angle. (this rotation is cumulative)

Parameters
idbackground id returned from bgInit or bgInitSub
anglethe angle of counter clockwise rotation (-32768 to 32767)
static void bgScroll ( int  id,
int  dx,
int  dy 
)
inlinestatic

Scrolls the background by the specified relative values.

Parameters
idbackground id returned from bgInit or bgInitSub
dxhorizontal scroll
dyvertical scroll
Note
while valid for text backgrounds the fractional part will be ignored
static void bgScrollf ( int  id,
s32  dx,
s32  dy 
)
inlinestatic

Scrolls the background by the specified relative values (fixed point)

Parameters
idbackground id returned from bgInit or bgInitSub
dxthe 8 bits fractional fixed point horizontal scroll
dythe 8 bits fractional fixed point vertical scroll
Note
while valid for text backgrounds the fractional part will be ignored
static void bgSet ( int  id,
int  angle,
s32  sx,
s32  sy,
s32  scrollX,
s32  scrollY,
s32  rotCenterX,
s32  rotCenterY 
)
inlinestatic

Sets the rotation and scale of the background and update background control registers.

Parameters
idbackground id returned from bgInit or bgInitSub
anglethe angle of counter clockwise rotation (-32768 to 32767)
sxthe 24.8 bit fractional fixed point inverse horizontal scaling to apply
sythe 24.8 bit fractional fixed point inverse vertical scaling to apply
scrollXthe 24.8 bit fractional fixed point horizontal scroll to apply
scrollYthe 24.8 bit fractional fixed point vertical scroll to apply
rotCenterXthe 24.8 bit fractional fixed point center of rotation x component
rotCenterYthe 24.8 bit fractional fixed point center of rotation y component
static void bgSetAffineMatrixScroll ( int  id,
int  hdx,
int  vdx,
int  hdy,
int  vdy,
int  scrollx,
int  scrolly 
)
inlinestatic

directly sets the affine matrix and scroll registers of a background.

With this, you have more freedom to set the matrix, but it might be more difficult to use if you're not used to affine transformation matrix. This will ignore (but not erase) any values set using the bg rotating, scaling or center functions.

Parameters
idThe id returned by bgInit or bgInitSub.
hdxThe change in x per horizontal pixel.
vdxThe change in x per vertical pixel.
hdyThe change in y per horizontal pixel.
vdyThe change in y per vertical pixel.
scrollxThe horizontal scroll/offset value of the background.
scrollyThe vertical scroll/offset value of the background.
static void bgSetCenter ( int  id,
int  x,
int  y 
)
inlinestatic

Sets the center of rotation for the supplied background.

Parameters
idbackground id returned from bgInit or bgInitSub
xcenter x
ycenter y
static void bgSetCenterf ( int  id,
s32  x,
s32  y 
)
inlinestatic

Sets the center of rotation for the supplied background (fixed point)

Parameters
idbackground id returned from bgInit or bgInitSub
xthe 8 bits fractional center x
ythe 8 bits fractional center y
Note
while valid for text backgrounds the fractional part will be ignored
static vuint16* bgSetControlBits ( int  id,
u16  bits 
)
inlinestatic

allows direct access to background control for the chosen layer, returns a pointer to the current control bits

Parameters
idbackground id returned from bgInit or bgInitSub
bitssets the specified bits to set in the backgrounds control register
Returns
a pointer to the appropriate background control register
static void bgSetMapBase ( int  id,
unsigned int  base 
)
inlinestatic

Sets the background map base.

Parameters
idbackground id returned from bgInit or bgInitSub
basethe 2k offset into vram for the backgrounds tile map or the 16k offset for bitmap graphics
static void bgSetMosaic ( unsigned int  dx,
unsigned int  dy 
)
inlinestatic

Sets the horizontal and vertical mosaic values for all backgrounds.

Parameters
dxhorizontal mosaic value (between 0 and 15)
dyvertical mosaic value (between 0 and 15)
static void bgSetMosaicSub ( unsigned int  dx,
unsigned int  dy 
)
inlinestatic

Sets the horizontal and vertical mosaic values for all backgrounds (Sub Display)

Parameters
dxhorizontal mosaic value (between 0 and 15)
dyvertical mosaic value (between 0 and 15)
static void bgSetPriority ( int  id,
unsigned int  priority 
)
inlinestatic

Sets the background priority.

Parameters
idbackground id returned from bgInit or bgInitSub
prioritybackground priority (0-3), higher level priority will result in background rendering on top of lower level
static void bgSetRotate ( int  id,
int  angle 
)
inlinestatic

Sets the rotation angle of the specified background and updates the transform matrix.

Parameters
idbackground id returned from bgInit or bgInitSub
anglethe angle of counter clockwise rotation (0 to 511)
static void bgSetRotateScale ( int  id,
int  angle,
s32  sx,
s32  sy 
)
inlinestatic

Sets the rotation and scale of the background and update background control registers.

Parameters
idbackground id returned from bgInit or bgInitSub
anglethe angle of counter clockwise rotation (-32768 to 32767)
sxthe 24.8 bit fractional fixed point horizontal scaling to apply
sythe 24.8 bit fractional fixed point vertical scaling to apply
static void bgSetScale ( int  id,
s32  sx,
s32  sy 
)
inlinestatic

Sets the scale of the specified background.

Parameters
idbackground id returned from bgInit or bgInitSub
sxthe 24.8 bit fractional fixed point horizontal scaling to apply
sythe 24.8 bit fractional fixed point vertical scaling to apply
static void bgSetScroll ( int  id,
int  x,
int  y 
)
inlinestatic

Sets the scroll hardware to the specified location.

Parameters
idbackground id returned from bgInit or bgInitSub
xthe horizontal scroll
ythe vertical scroll
static void bgSetScrollf ( int  id,
s32  x,
s32  y 
)
inlinestatic

Sets the scroll hardware to the specified location (fixed point)

Parameters
idbackground id returned from bgInit or bgInitSub
xthe 8 bits fractional fixed point horizontal scroll
ythe 8 bits fractional fixed point vertical scroll
Note
while valid for text backgrounds the fractional part will be ignored
static void bgSetTileBase ( int  id,
unsigned int  base 
)
inlinestatic

Sets the background map base.

Parameters
idbackground id returned from bgInit or bgInitSub
basethe 16k offset into vram for the backgrounds tile map ignored for bitmap graphics
static void bgShow ( int  id)
inlinestatic

Shows the current background via the display control register.

Parameters
idbackground id returned from bgInit or bgInitSub
static void bgWrapOff ( int  id)
inlinestatic

turns wrap off for a background. has no effect on text backgrounds, which are always wrapped.

Parameters
idbackground id returned from bgInit or bgInitSub
static void bgWrapOn ( int  id)
inlinestatic

turns wrap on for a background. has no effect on text backgrounds, which are always wrapped.

Parameters
idbackground id returned from bgInit or bgInitSub