sprite.h File Reference

nds sprite functionality. More...

#include "nds/ndstypes.h"
#include "nds/arm9/video.h"
#include "nds/memory.h"
#include "nds/system.h"

Data Structures
struct	OamState
	Holds the state for a 2D sprite engine. More...
union	SpriteEntry
	A bitfield of sprite attribute goodness...ugly to look at but not so bad to use. More...
struct	SpriteRotation
	A sprite rotation entry. More...

Macros
#define	MATRIX_COUNT   32
	maximum number of affine matrices per engine available.
#define	SPRITE_COUNT   128
	maximum number of sprites per engine available.

Typedefs
typedef struct OamState	OamState
	Holds the state for a 2D sprite engine. More...
typedef union SpriteEntry	SpriteEntry
	A bitfield of sprite attribute goodness...ugly to look at but not so bad to use.
typedef struct SpriteRotation	SpriteRotation
	A sprite rotation entry.

Enumerations

Functions
static void	oamAffineTransformation (OamState *oam, int rotId, int hdx, int hdy, int vdx, int vdy)
	allows you to directly sets the affine transformation matrix. More...
u16 *	oamAllocateGfx (OamState *oam, SpriteSize size, SpriteColorFormat colorFormat)
	Allocates graphics memory for the supplied sprite attributes. More...
void	oamClear (OamState *oam, int start, int count)
	Hides the sprites in the supplied range: if count is zero all 128 sprites will be hidden. More...
static void	oamClearSprite (OamState *oam, int index)
	Hides a single sprite. More...
int	oamCountFragments (OamState *oam)
	determines the number of fragments in the allocation engine More...
void	oamDisable (OamState *oam)
	Disables sprite rendering. More...
void	oamEnable (OamState *oam)
	Enables sprite rendering. More...
void	oamFreeGfx (OamState *oam, const void *gfxOffset)
	free vram memory obtained with oamAllocateGfx. More...
u16 *	oamGetGfxPtr (OamState *oam, int gfxOffsetIndex)
	translates an oam offset into a video ram address More...
unsigned int	oamGfxPtrToOffset (OamState *oam, const void *offset)
	convert a VRAM address to an oam offset More...
void	oamInit (OamState *oam, SpriteMapping mapping, bool extPalette)
	Initializes the 2D sprite engine In order to mix tiled and bitmap sprites use SpriteMapping_Bmp_1D_128 or SpriteMapping_Bmp_1D_256. More...
void	oamRotateScale (OamState *oam, int rotId, int angle, int sx, int sy)
	sets the specified rotation scale entry More...
void	oamSet (OamState *oam, int id, int x, int y, int priority, int palette_alpha, SpriteSize size, SpriteColorFormat format, const void *gfxOffset, int affineIndex, bool sizeDouble, bool hide, bool hflip, bool vflip, bool mosaic)
	sets an oam entry to the supplied values More...
static void	oamSetAffineIndex (OamState *oam, int id, int affineIndex, bool sizeDouble)
	sets an oam entry to the supplied affine index More...
static void	oamSetAlpha (OamState *oam, int id, int alpha)
	sets a bitmapped oam entry to the supplied transparency More...
static void	oamSetFlip (OamState *oam, int id, bool hflip, bool vflip)
	sets an oam entry to the supplied flipping More...
static void	oamSetGfx (OamState *oam, int id, SpriteSize size, SpriteColorFormat format, const void *gfxOffset)
	sets an oam entry to the supplied shape/size/pointer More...
static void	oamSetHidden (OamState *oam, int id, bool hide)
	sets an oam entry to the supplied hidden state More...
static void	oamSetMosaic (unsigned int dx, unsigned int dy)
	sets engine A global sprite mosaic More...
static void	oamSetMosaicEnabled (OamState *oam, int id, bool mosaic)
	sets an oam entry to enable or disable mosaic More...
static void	oamSetMosaicSub (unsigned int dx, unsigned int dy)
	sets engine B global sprite mosaic More...
static void	oamSetPalette (OamState *oam, int id, int palette)
	sets a paletted oam entry to the supplied palette More...
static void	oamSetPriority (OamState *oam, int id, int priority)
	sets an oam entry to the supplied priority More...
static void	oamSetXY (OamState *oam, int id, int x, int y)
	sets an oam entry to the supplied x,y position More...
void	oamUpdate (OamState *oam)
	causes oam memory to be updated...must be called during vblank if using oam api More...

Variables
OamState	oamMain
	oamMain an object representing the main 2D engine
OamState	oamSub
	oamSub an object representing the sub 2D engine

Detailed Description

nds sprite functionality.

Typedef Documentation

typedef struct OamState OamState

Holds the state for a 2D sprite engine.

There are two of these objects, oamMain and oamSub and these must be passed in to all oam functions.

Enumeration Type Documentation

enum ObjBlendMode

The blending mode of the sprite.

Enumerator
OBJMODE_NORMAL	No special mode is on - Normal sprite state.
OBJMODE_BLENDED	Color blending is on - Sprite can use HW blending features.
OBJMODE_WINDOWED	Sprite can be seen only inside the sprite window.
OBJMODE_BITMAP	Sprite is not using tiles - per pixel image data.

enum ObjColMode

The color mode of the sprite.

Enumerator
OBJCOLOR_16	sprite has 16 colors.
OBJCOLOR_256	sprite has 256 colors.

enum ObjPriority

The priority of the sprite.

Enumerator
OBJPRIORITY_0	sprite priority level 0 - highest.
OBJPRIORITY_1	sprite priority level 1.
OBJPRIORITY_2	sprite priority level 2.
OBJPRIORITY_3	sprite priority level 3 - lowest.

enum ObjShape

The shape of the sprite.

Enumerator
OBJSHAPE_SQUARE	Sprite shape is NxN (Height == Width).
OBJSHAPE_WIDE	Sprite shape is NxM with N > M (Height < Width).
OBJSHAPE_TALL	Sprite shape is NxM with N < M (Height > Width).
OBJSHAPE_FORBIDDEN	Sprite shape is undefined.

enum ObjSize

The size of the sprite.

Enumerator
OBJSIZE_8	Major sprite size is 8px.
OBJSIZE_16	Major sprite size is 16px.
OBJSIZE_32	Major sprite size is 32px.
OBJSIZE_64	Major sprite size is 64px.

enum SpriteColorFormat

Color formats for sprite graphics.

Enumerator
SpriteColorFormat_16Color	16 colors per sprite
SpriteColorFormat_256Color	256 colors per sprite
SpriteColorFormat_Bmp	16-bit sprites

enum SpriteMapping

Graphics memory layout options.

Enumerator
SpriteMapping_1D_32	1D tile mapping 32 byte boundary between offset
SpriteMapping_1D_64	1D tile mapping 64 byte boundary between offset
SpriteMapping_1D_128	1D tile mapping 128 byte boundary between offset
SpriteMapping_1D_256	1D tile mapping 256 byte boundary between offset
SpriteMapping_2D	2D tile mapping 32 byte boundary between offset
SpriteMapping_Bmp_1D_128	1D bitmap mapping 128 byte boundary between offset
SpriteMapping_Bmp_1D_256	1D bitmap mapping 256 byte boundary between offset
SpriteMapping_Bmp_2D_128	2D bitmap mapping 128 pixels wide bitmap
SpriteMapping_Bmp_2D_256	2D bitmap mapping 256 pixels wide bitmap

enum SpriteSize

Enumerates all sizes supported by the 2D engine.

Enumerator
SpriteSize_8x8	8x8
SpriteSize_16x16	16x16
SpriteSize_32x32	32x32
SpriteSize_64x64	64x64
SpriteSize_16x8	16x8
SpriteSize_32x8	32x8
SpriteSize_32x16	32x16
SpriteSize_64x32	64x32
SpriteSize_8x16	8x16
SpriteSize_8x32	8x32
SpriteSize_16x32	16x32
SpriteSize_32x64	32x64

Function Documentation

static void oamAffineTransformation ( OamState *  oam, int  rotId, int  hdx, int  hdy, int  vdx, int  vdy  )

inlinestatic

allows you to directly sets the affine transformation matrix.

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 erase the previous matrix stored at rotId.

Parameters

oam	The oam engine, must be &oamMain or &oamSub.
rotId	The id of the rotscale item you want to change, must be 0-31.
hdx	The change in x per horizontal pixel.
hdy	The change in y per horizontal pixel.
vdx	The change in x per vertical pixel.
vdy	The change in y per vertical pixel.

u16* oamAllocateGfx	(	OamState *	oam,
		SpriteSize	size,
		SpriteColorFormat	colorFormat
	)

Allocates graphics memory for the supplied sprite attributes.

Parameters

oam	must be: &oamMain or &oamSub
size	the size of the sprite to allocate
colorFormat	the color format of the sprite

Returns

the address in vram of the allocated sprite

void oamClear	(	OamState *	oam,
		int	start,
		int	count
	)

Hides the sprites in the supplied range: if count is zero all 128 sprites will be hidden.

Parameters

oam	must be: &oamMain or &oamSub
start	The first index to clear
count	The number of sprites to clear

static void oamClearSprite ( OamState *  oam, int  index  )

inlinestatic

Hides a single sprite.

Parameters

oam	the oam engine, must be &oamMain or &oamSub.
index	the index of the sprite, must be 0-127.

int oamCountFragments

(

OamState *

oam

)

determines the number of fragments in the allocation engine

Parameters

oam	must be: &oamMain or &oamSub

Returns

the number of fragments.

void oamDisable

(

OamState *

oam

)

Disables sprite rendering.

Parameters

oam	must be: &oamMain or &oamSub

void oamEnable

(

OamState *

oam

)

Enables sprite rendering.

Parameters

oam	must be: &oamMain or &oamSub

void oamFreeGfx	(	OamState *	oam,
		const void *	gfxOffset
	)

free vram memory obtained with oamAllocateGfx.

Parameters

oam	must be: &oamMain or &oamSub
gfxOffset	a vram offset obtained from oamAllocateGfx

u16* oamGetGfxPtr	(	OamState *	oam,
		int	gfxOffsetIndex
	)

translates an oam offset into a video ram address

Parameters

oam	must be: &oamMain or &oamSub
gfxOffsetIndex	the index to compute

Returns

the address in vram corresponding to the supplied offset

unsigned int oamGfxPtrToOffset	(	OamState *	oam,
		const void *	offset
	)

convert a VRAM address to an oam offset

Parameters

oam	must be: &oamMain or &oamSub
offset	the video memory address of the sprite graphics (not an offset)

void oamInit	(	OamState *	oam,
		SpriteMapping	mapping,
		bool	extPalette
	)

Initializes the 2D sprite engine In order to mix tiled and bitmap sprites use SpriteMapping_Bmp_1D_128 or SpriteMapping_Bmp_1D_256.

This will set mapping for both to 1D and give same sized boundaries so the sprite gfx allocation will function. VBlank IRQ must be enabled for this function to work.

Parameters

oam	must be: &oamMain or &oamSub
mapping	the mapping mode
extPalette	if true the engine sets up extended palettes for 8bpp sprites

void oamRotateScale	(	OamState *	oam,
		int	rotId,
		int	angle,
		int	sx,
		int	sy
	)

sets the specified rotation scale entry

Parameters

oam	must be: &oamMain or &oamSub
rotId	the rotation entry to set
angle	the ccw angle to rotate [-32768 - 32767]
sx	the inverse scale factor in the x direction
sy	the inverse scale factor in the y direction

void oamSet	(	OamState *	oam,
		int	id,
		int	x,
		int	y,
		int	priority,
		int	palette_alpha,
		SpriteSize	size,
		SpriteColorFormat	format,
		const void *	gfxOffset,
		int	affineIndex,
		bool	sizeDouble,
		bool	hide,
		bool	hflip,
		bool	vflip,
		bool	mosaic
	)

sets an oam entry to the supplied values

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0 - 127]
x	the x location of the sprite in pixels
y	the y location of the sprite in pixels
priority	The sprite priority (0 to 3)
palette_alpha	the palette number for 4bpp and 8bpp (extended palette mode), or the alpha value for bitmap sprites (bitmap sprites must specify a value > 0 to display) [0-15]
size	the size of the sprite
format	the color format of the sprite
gfxOffset	the video memory address of the sprite graphics (not an offset)
affineIndex	affine index to use (if < 0 or > 31 the sprite will be unrotated)
sizeDouble	if affineIndex >= 0 this will be used to double the sprite size for rotation
hide	if non zero (true) the sprite will be hidden
vflip	flip the sprite vertically
hflip	flip the sprite horizontally
mosaic	if true mosaic will be applied to the sprite

static void oamSetAffineIndex ( OamState *  oam, int  id, int  affineIndex, bool  sizeDouble  )

inlinestatic

sets an oam entry to the supplied affine index

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
affineIndex	affine index to use (if < 0 or > 31 the sprite will be unrotated)
sizeDouble	if affineIndex >= 0 and < 32 this will be used to double the sprite size for rotation

static void oamSetAlpha ( OamState *  oam, int  id, int  alpha  )

inlinestatic

sets a bitmapped oam entry to the supplied transparency

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
alpha	the alpha value for bitmap sprites (bitmap sprites must specify a value > 0 to display) [0-15]

static void oamSetFlip ( OamState *  oam, int  id, bool  hflip, bool  vflip  )

inlinestatic

sets an oam entry to the supplied flipping

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
hflip	flip the sprite horizontally
vflip	flip the sprite vertically

static void oamSetGfx ( OamState *  oam, int  id, SpriteSize  size, SpriteColorFormat  format, const void *  gfxOffset  )

inlinestatic

sets an oam entry to the supplied shape/size/pointer

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
size	the size of the sprite
format	the color format of the sprite
gfxOffset	the video memory address of the sprite graphics (not an offset)

static void oamSetHidden ( OamState *  oam, int  id, bool  hide  )

inlinestatic

sets an oam entry to the supplied hidden state

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
hide	if non zero (true) the sprite will be hidden

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

inlinestatic

sets engine A global sprite mosaic

Parameters

dx	(0-15) horizontal mosaic value
dy	(0-15) horizontal mosaic value

static void oamSetMosaicEnabled ( OamState *  oam, int  id, bool  mosaic  )

inlinestatic

sets an oam entry to enable or disable mosaic

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
mosaic	if true mosaic will be applied to the sprite

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

inlinestatic

sets engine B global sprite mosaic

Parameters

dx	(0-15) horizontal mosaic value
dy	(0-15) horizontal mosaic value

static void oamSetPalette ( OamState *  oam, int  id, int  palette  )

inlinestatic

sets a paletted oam entry to the supplied palette

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
palette	the palette number for 4bpp and 8bpp (extended palette mode) sprites [0-15]

static void oamSetPriority ( OamState *  oam, int  id, int  priority  )

inlinestatic

sets an oam entry to the supplied priority

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
priority	The sprite priority [0-3]

static void oamSetXY ( OamState *  oam, int  id, int  x, int  y  )

inlinestatic

sets an oam entry to the supplied x,y position

Parameters

oam	must be: &oamMain or &oamSub
id	the oam number to be set [0-127]
x	the x location of the sprite in pixels
y	the y location of the sprite in pixels

void oamUpdate

(

OamState *

oam

)

causes oam memory to be updated...must be called during vblank if using oam api

Parameters

oam	must be: &oamMain or &oamSub