Data Structures
struct	BgState
	Background state. More...

Typedefs
typedef struct BgState	BgState
	Background state.

Enumerations
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

Enumeration Type Documentation

◆ BgSize

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

◆ BgType

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 not set, the pixel will be transparent)

Function Documentation

◆ bgClearControlBits()

static void bgClearControlBits	(	int	id,
		u16	bits
	)

inlinestatic

Clears the specified bits from the backgrounds control register.

Parameters

id	Background ID returned from bgInit or bgInitSub.
bits	Bits to clear in the background control register.

◆ bgGetGfxPtr()

static u16 * bgGetGfxPtr ( int id )

inlinestatic

Gets a pointer to the background graphics.

Parameters

id	Background ID returned from bgInit or bgInitSub.

Returns: A pointer to the tile graphics or bitmap graphics.

◆ bgGetMapBase()

static int bgGetMapBase ( int id )

inlinestatic

Gets the current map base for the supplied background.

Parameters

id	Background 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.

◆ bgGetMapPtr()

static u16 * bgGetMapPtr ( int id )

inlinestatic

Gets a pointer to the background map.

Parameters

id	Background ID returned from bgInit or bgInitSub.

Returns: A pointer to the map.

◆ bgGetPriority()

static int bgGetPriority ( int id )

inlinestatic

Gets the background priority.

Parameters

id	Background ID returned from bgInit or bgInitSub.

Returns: Background priority.

◆ bgGetTileBase()

static int bgGetTileBase ( int id )

inlinestatic

Gets the background tile base.

Parameters

id	Background ID returned from bgInit or bgInitSub.

Returns: Background tile base.

◆ bgHide()

static void bgHide ( int id )

inlinestatic

Hides the current background via the display control register.

Parameters

id	Background ID returned from bgInit or bgInitSub.

◆ bgInit()

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

layer	Background layer to init. Must be 0 - 3.
type	Type of background to init.
size	Size of the background.
mapBase	The 2k offset into VRAM where the tile map will be placed, OR the 16k offset into vram the bitmap data will be placed.
tileBase	The 16k offset into VRAM where 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

◆ bgInitSub()

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

layer	Background hardware layer to init. Must be 0 - 3.
type	The type of background to init.
size	The size of the background.
mapBase	The 2 KB offset into VRAM where the tile map will be placed, OR the 16 KB offset into vram the bitmap data will be placed for bitmap backgrounds.
tileBase	The 16 KB offset into VRAM where 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.

◆ bgMosaicDisable()

static void bgMosaicDisable ( int id )

inlinestatic

Disables mosaic on the specified background.

Parameters

id	Background ID returned from bgInit or bgInitSub.

◆ bgMosaicEnable()

static void bgMosaicEnable ( int id )

inlinestatic

Enables mosaic on the specified background.

Note: If layer 0 is displaying the 3D engine output, mosaic won't work.

Parameters

id	Background ID returned from bgInit or bgInitSub.

◆ bgRotate()

static void bgRotate	(	int	id,
		int	angle
	)

inlinestatic

Rotates the background counter clockwise by the specified angle.

This rotation is cumulative.

Parameters

id	Background ID returned from bgInit or bgInitSub.
angle	The angle of counter clockwise rotation (-32768 to 32767).

◆ bgScroll()

static void bgScroll	(	int	id,
		int	dx,
		int	dy
	)

inlinestatic

Scrolls the background by the specified relative values.

Parameters

id	Background ID returned from bgInit or bgInitSub.
dx	Horizontal scroll.
dy	Vertical scroll.

◆ bgScrollf()

static void bgScrollf	(	int	id,
		s32	dx,
		s32	dy
	)

inlinestatic

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

Parameters

id	Background ID returned from bgInit or bgInitSub.
dx	8 bits fractional fixed point horizontal scroll.
dy	8 bits fractional fixed point vertical scroll.

Note: In text backgrounds the fractional part is ignored.

◆ bgSet()

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 updates the background control registers.

Parameters

id	Background ID returned from bgInit or bgInitSub.
angle	Angle of counter clockwise rotation (-32768 to 32767).
sx	24.8 bit fractional fixed point inverse horizontal scaling.
sy	24.8 bit fractional fixed point inverse vertical scaling.
scrollX	24.8 bit fractional fixed point horizontal scroll.
scrollY	24.8 bit fractional fixed point vertical scroll.
rotCenterX	24.8 bit fractional fixed point center of rotation (X).
rotCenterY	24.8 bit fractional fixed point center of rotation (Y).

◆ bgSetAffineMatrixScroll()

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

id	Background ID returned from bgInit or bgInitSub.
hdx	The change in x per horizontal pixel.
vdx	The change in x per vertical pixel.
hdy	The change in y per horizontal pixel.
vdy	The change in y per vertical pixel.
scrollx	The horizontal scroll/offset value of the background.
scrolly	The vertical scroll/offset value of the background.

◆ bgSetCenter()

static void bgSetCenter	(	int	id,
		int	x,
		int	y
	)

inlinestatic

Sets the center of rotation for the supplied background.

Parameters

id	Background ID returned from bgInit or bgInitSub.
x	Center x.
y	Center y.

◆ bgSetCenterf()

static void bgSetCenterf	(	int	id,
		s32	x,
		s32	y
	)

inlinestatic

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

Parameters

id	Background ID returned from bgInit or bgInitSub.
x	8 bits fractional center x.
y	8 bits fractional center y.

Note: In text backgrounds the fractional part is ignored.

◆ bgSetControlBits()

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

id	Background ID returned from bgInit or bgInitSub.
bits	Bits to set in the background control register.

Returns: A pointer to the appropriate background control register.

◆ bgSetMapBase()

static void bgSetMapBase	(	int	id,
		unsigned int	base
	)

inlinestatic

Sets the background map base.

Parameters

id	Background ID returned from bgInit or bgInitSub.
base	The 2 KB offset into VRAM for the backgrounds tile map or the 16 KB offset for bitmap graphics.

◆ bgSetMosaic()

static void bgSetMosaic	(	unsigned int	dx,
		unsigned int	dy
	)

inlinestatic

Sets the horizontal and vertical mosaic values for all backgrounds.

Parameters

dx	Horizontal mosaic value (between 0 and 15).
dy	Vertical mosaic value (between 0 and 15).

◆ bgSetMosaicSub()

static void bgSetMosaicSub	(	unsigned int	dx,
		unsigned int	dy
	)

inlinestatic

Sets the horizontal and vertical mosaic values for all backgrounds (sub display).

Parameters

dx	Horizontal mosaic value (between 0 and 15).
dy	Vertical mosaic value (between 0 and 15).

◆ bgSetPriority()

static void bgSetPriority	(	int	id,
		unsigned int	priority
	)

inlinestatic

Sets the background priority.

Higher level priority will result in background rendering on top of lower level priority. Low numbers have higher priority over high numbers.

Parameters

id	Background ID returned from bgInit or bgInitSub.
priority	Background priority (0 - 3).

◆ bgSetRotate()

static void bgSetRotate	(	int	id,
		int	angle
	)

inlinestatic

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

Parameters

id	Background id returned from bgInit or bgInitSub
angle	The angle of counter clockwise rotation (0 to 511)

◆ bgSetRotateScale()

static void bgSetRotateScale	(	int	id,
		int	angle,
		s32	sx,
		s32	sy
	)

inlinestatic

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

Parameters

id	Background ID returned from bgInit or bgInitSub.
angle	Angle of counter clockwise rotation (-32768 to 32767).
sx	24.8 bit fractional fixed point horizontal scaling.
sy	24.8 bit fractional fixed point vertical scaling.

◆ bgSetScale()

static void bgSetScale	(	int	id,
		s32	sx,
		s32	sy
	)

inlinestatic

Sets the scale of the specified background.

Parameters

id	Background ID returned from bgInit or bgInitSub.
sx	24.8 bit fractional fixed point horizontal scaling.
sy	24.8 bit fractional fixed point vertical scaling.

◆ bgSetScroll()

static void bgSetScroll	(	int	id,
		int	x,
		int	y
	)

inlinestatic

Sets the scroll hardware to the specified location.

Parameters

id	Background ID returned from bgInit or bgInitSub.
x	The horizontal scroll.
y	The vertical scroll.

◆ bgSetScrollf()

static void bgSetScrollf	(	int	id,
		s32	x,
		s32	y
	)

inlinestatic

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

Parameters

id	Background ID returned from bgInit or bgInitSub.
x	The 8 bits fractional fixed point horizontal scroll.
y	The 8 bits fractional fixed point vertical scroll.

Note: In text backgrounds the fractional part is ignored.

◆ bgSetTileBase()

static void bgSetTileBase	(	int	id,
		unsigned int	base
	)

inlinestatic

Sets the background map base.

Parameters

id	Background ID returned from bgInit or bgInitSub.
base	The 16 KB offset into vram for the backgrounds tile map. Ignored for bitmap graphics.

◆ bgShow()

static void bgShow ( int id )

inlinestatic

Shows the current background via the display control register.

Parameters

id	Background ID returned from bgInit or bgInitSub.

◆ bgWrapOff()

static void bgWrapOff ( int id )

inlinestatic

Turns OFF wrap for a background.

It has no effect on text backgrounds, which are always wrapped.

Parameters

id	Background ID returned from bgInit or bgInitSub.

◆ bgWrapOn()

static void bgWrapOn ( int id )

inlinestatic

Turns ON wrap for a background.

It has no effect on text backgrounds, which are always wrapped.

Parameters

id	Background ID returned from bgInit or bgInitSub.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ BgSize

◆ BgType

Function Documentation

◆ bgClearControlBits()

◆ bgGetGfxPtr()

◆ bgGetMapBase()

◆ bgGetMapPtr()

◆ bgGetPriority()

◆ bgGetTileBase()

◆ bgHide()

◆ bgInit()

◆ bgInitSub()

◆ bgMosaicDisable()

◆ bgMosaicEnable()

◆ bgRotate()

◆ bgScroll()

◆ bgScrollf()

◆ bgSet()

◆ bgSetAffineMatrixScroll()

◆ bgSetCenter()

◆ bgSetCenterf()

◆ bgSetControlBits()

◆ bgSetMapBase()

◆ bgSetMosaic()

◆ bgSetMosaicSub()

◆ bgSetPriority()

◆ bgSetRotate()

◆ bgSetRotateScale()

◆ bgSetScale()

◆ bgSetScroll()

◆ bgSetScrollf()

◆ bgSetTileBase()

◆ bgShow()

◆ bgWrapOff()

◆ bgWrapOn()