libnds
Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
background.h File Reference

NDS background defines and functionality. More...

#include <nds/arm9/sassert.h>
#include <nds/arm9/video.h>
#include <nds/dma.h>
#include <nds/memory.h>
#include <nds/ndstypes.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  BgState
 Background state. 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.
 
#define BACKGROUND_SUB   (*((bg_attribute *)0x04001008))
 Overlay for sub screen background attributes.
 
#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.
 
#define BG_OFFSET_SUB   ((bg_scroll *)(0x04001010))
 Overlay for sub screen background scroll 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].
 
#define BGCTRL_SUB   ((vu16 *)0x4001008)
 Access to all sub screen background control registers via BGCTRL[x].
 
#define CHAR_BASE_BLOCK(n)   (((n) * 0x4000) + 0x06000000)
 A macro which returns a u16 pointer to background tile RAM (main engine).
 
#define CHAR_BASE_BLOCK_SUB(n)   (((n) * 0x4000) + 0x06200000)
 A macro that returns a u16 pointer to background tile RAM (sub engine).
 
#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)
 
#define REG_BG0CNT_SUB   (*(vu16 *)0x4001008)
 Background 0 control register (sub engine)
 
#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)
 
#define REG_BG1CNT_SUB   (*(vu16 *)0x400100A)
 Background 1 control register (sub engine)
 
#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)
 
#define REG_BG2CNT_SUB   (*(vu16 *)0x400100C)
 Background 2 control register (sub engine)
 
#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)
 
#define REG_BG3CNT_SUB   (*(vu16 *)0x400100E)
 Background 3 control register (sub engine)
 
#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 SCREEN_BASE_BLOCK(n)   (((n) * 0x800) + 0x06000000)
 A macro which returns a u16* pointer to background map RAM (main engine).
 
#define SCREEN_BASE_BLOCK_SUB(n)   (((n) * 0x800) + 0x06200000)
 A macro that returns a u16 pointer to background map RAM (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 BgState BgState
 Background state.
 
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. 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.
 
static void bgExtPaletteDisable (void)
 Disable extended palettes (main engine).
 
static void bgExtPaletteDisableSub (void)
 Disable extended palettes (sub engine).
 
static void bgExtPaletteEnable (void)
 Enable extended palettes (main engine).
 
static void bgExtPaletteEnableSub (void)
 Enable extended palettes (sub engine).
 
static u16 * bgGetGfxPtr (int id)
 Gets a pointer to the background graphics.
 
static int bgGetMapBase (int id)
 Gets the current map base for the supplied background.
 
static u16 * bgGetMapPtr (int id)
 Gets a pointer to the background map.
 
static int bgGetPriority (int id)
 Gets the background priority.
 
static int bgGetTileBase (int id)
 Gets the background tile base.
 
static void bgHide (int id)
 Hides the current background via the display control register.
 
static int bgInit (int layer, BgType type, BgSize size, int mapBase, int tileBase)
 Initializes a background on the main display.
 
static int bgInitSub (int layer, BgType type, BgSize size, int mapBase, int tileBase)
 Initializes a background on the sub display.
 
static void bgMosaicDisable (int id)
 Disables mosaic on the specified background.
 
static void bgMosaicEnable (int id)
 Enables mosaic on the specified background.
 
static void bgRotate (int id, int angle)
 Rotates the background counter clockwise by the specified angle.
 
static void bgScroll (int id, int dx, int dy)
 Scrolls the background by the specified relative values.
 
static void bgScrollf (int id, s32 dx, s32 dy)
 Scrolls the background by the specified relative values (fixed point).
 
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 updates the background control registers.
 
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.
 
static void bgSetCenter (int id, int x, int y)
 Sets the center of rotation for the supplied background.
 
static void bgSetCenterf (int id, s32 x, s32 y)
 Sets the center of rotation for the supplied background (fixed point).
 
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.
 
static void bgSetMapBase (int id, unsigned int base)
 Sets the background map base.
 
static void bgSetMosaic (unsigned int dx, unsigned int dy)
 Sets the horizontal and vertical mosaic values for all backgrounds.
 
static void bgSetMosaicSub (unsigned int dx, unsigned int dy)
 Sets the horizontal and vertical mosaic values for all backgrounds (sub display).
 
static void bgSetPriority (int id, unsigned int priority)
 Sets the background priority.
 
static void bgSetRotate (int id, int angle)
 Sets the rotation angle of the specified background and updates the transform matrix.
 
static void bgSetRotateScale (int id, int angle, s32 sx, s32 sy)
 Sets the rotation and scale of the background and updates the background control registers.
 
static void bgSetScale (int id, s32 sx, s32 sy)
 Sets the scale of the specified background.
 
static void bgSetScroll (int id, int x, int y)
 Sets the scroll hardware to the specified location.
 
static void bgSetScrollf (int id, s32 x, s32 y)
 Sets the scroll hardware to the specified location (fixed point).
 
static void bgSetTileBase (int id, unsigned int base)
 Sets the background map base.
 
static void bgShow (int id)
 Shows the current background via the display control register.
 
void bgUpdate (void)
 Must be called once per frame to update scroll/scale/and rotation of backgrounds.
 
static void bgWrapOff (int id)
 Turns OFF wrap for a background.
 
static void bgWrapOn (int id)
 Turns ON wrap for a background.
 

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 are 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 are 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 used as a 3D rendering surface.

Note about 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 8 KB 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 8 KB 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

Generated on Sat Nov 23 2024 17:29:18 for libnds by doxygen 1.9.8