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...
Defines
#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.
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
enum	ObjBlendMode {   OBJMODE_NORMAL,   OBJMODE_BLENDED,   OBJMODE_WINDOWED,   OBJMODE_BITMAP }
	The blending mode of the sprite. More...
enum	ObjColMode {   OBJCOLOR_16,   OBJCOLOR_256 }
	The color mode of the sprite. More...
enum	ObjPriority {   OBJPRIORITY_0,   OBJPRIORITY_1,   OBJPRIORITY_2,   OBJPRIORITY_3 }
	The priority of the sprite. More...
enum	ObjShape {   OBJSHAPE_SQUARE,   OBJSHAPE_WIDE,   OBJSHAPE_TALL,   OBJSHAPE_FORBIDDEN }
	The shape of the sprite. More...
enum	ObjSize {   OBJSIZE_8,   OBJSIZE_16,   OBJSIZE_32,   OBJSIZE_64 }
	The size of the sprite. More...
enum	SpriteColorFormat {   SpriteColorFormat_16Color = OBJCOLOR_16,   SpriteColorFormat_256Color = OBJCOLOR_256,   SpriteColorFormat_Bmp = OBJMODE_BITMAP }
	Color formats for sprite graphics. More...
enum	SpriteMapping {   SpriteMapping_1D_32 = DISPLAY_SPR_1D | DISPLAY_SPR_1D_SIZE_32 | (0 << 28) | 0,   SpriteMapping_1D_64 = DISPLAY_SPR_1D | DISPLAY_SPR_1D_SIZE_64 | (1 << 28) | 1,   SpriteMapping_1D_128 = DISPLAY_SPR_1D | DISPLAY_SPR_1D_SIZE_128 | (2 << 28) | 2,   SpriteMapping_1D_256 = DISPLAY_SPR_1D | DISPLAY_SPR_1D_SIZE_256 | (3 << 28) | 3,   SpriteMapping_2D = DISPLAY_SPR_2D | (4 << 28),   SpriteMapping_Bmp_1D_128 = DISPLAY_SPR_1D | DISPLAY_SPR_1D_SIZE_128 | DISPLAY_SPR_1D_BMP |DISPLAY_SPR_1D_BMP_SIZE_128 | (5 << 28) | 2,   SpriteMapping_Bmp_1D_256 = DISPLAY_SPR_1D | DISPLAY_SPR_1D_SIZE_256 | DISPLAY_SPR_1D_BMP |DISPLAY_SPR_1D_BMP_SIZE_256 | (6 << 28) | 3,   SpriteMapping_Bmp_2D_128 = DISPLAY_SPR_2D | DISPLAY_SPR_2D_BMP_128 | (7 << 28) | 2,   SpriteMapping_Bmp_2D_256 = DISPLAY_SPR_2D | DISPLAY_SPR_2D_BMP_256 | (8 << 28) | 3 }
	Graphics memory layout options. More...
enum	SpriteSize {   SpriteSize_8x8 = (OBJSIZE_8 << 14) | (OBJSHAPE_SQUARE << 12) | (8*8>>5),   SpriteSize_16x16 = (OBJSIZE_16 << 14) | (OBJSHAPE_SQUARE << 12) | (16*16>>5),   SpriteSize_32x32 = (OBJSIZE_32 << 14) | (OBJSHAPE_SQUARE << 12) | (32*32>>5),   SpriteSize_64x64 = (OBJSIZE_64 << 14) | (OBJSHAPE_SQUARE << 12) | (64*64>>5),   SpriteSize_16x8 = (OBJSIZE_8 << 14) | (OBJSHAPE_WIDE << 12) | (16*8>>5),   SpriteSize_32x8 = (OBJSIZE_16 << 14) | (OBJSHAPE_WIDE << 12) | (32*8>>5),   SpriteSize_32x16 = (OBJSIZE_32 << 14) | (OBJSHAPE_WIDE << 12) | (32*16>>5),   SpriteSize_64x32 = (OBJSIZE_64 << 14) | (OBJSHAPE_WIDE << 12) | (64*32>>5),   SpriteSize_8x16 = (OBJSIZE_8 << 14) | (OBJSHAPE_TALL << 12) | (8*16>>5),   SpriteSize_8x32 = (OBJSIZE_16 << 14) | (OBJSHAPE_TALL << 12) | (8*32>>5),   SpriteSize_16x32 = (OBJSIZE_32 << 14) | (OBJSHAPE_TALL << 12) | (16*32>>5),   SpriteSize_32x64 = (OBJSIZE_64 << 14) | (OBJSHAPE_TALL << 12) | (32*64>>5) }
	Enumerates all sizes supported by the 2D engine. More...
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.
u16 *	oamAllocateGfx (OamState *oam, SpriteSize size, SpriteColorFormat colorFormat)
	Allocates graphics memory for the supplied sprite attributes.
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.
static void	oamClearSprite (OamState *oam, int index)
	Hides a single sprite.
int	oamCountFragments (OamState *oam)
	determines the number of fragments in the allocation engine
void	oamDisable (OamState *oam)
	Disables sprite rendering.
void	oamEnable (OamState *oam)
	Enables sprite rendering.
void	oamFreeGfx (OamState *oam, const void *gfxOffset)
	free vram memory obtained with oamAllocateGfx.
u16 *	oamGetGfxPtr (OamState *oam, int gfxOffsetIndex)
	translates an oam offset into a video ram address
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.
void	oamRotateScale (OamState *oam, int rotId, int angle, int sx, int sy)
	sets the specified rotation scale entry
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
static void	oamSetMosaic (unsigned int dx, unsigned int dy)
	sets engine A global sprite mosaic
static void	oamSetMosaicSub (unsigned int dx, unsigned int dy)
	sets engine B global sprite mosaic
void	oamUpdate (OamState *oam)
	causes oam memory to be updated...must be called during vblank if using oam api
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
	)			[inline, static]

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

Examples:

audio/maxmod/song_events_example/source/template.c, audio/maxmod/song_events_example2/source/template.c, Graphics/Sprites/allocation_test/source/main.c, Graphics/Sprites/animate_simple/source/template.c, Graphics/Sprites/bitmap_sprites/source/main.cpp, Graphics/Sprites/simple/source/template.c, Graphics/Sprites/sprite_extended_palettes/source/template.c, and Graphics/Sprites/sprite_rotate/source/template.c.

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
	)			[inline, static]

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

Examples:

Graphics/Sprites/allocation_test/source/main.c.

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

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

Examples:

audio/maxmod/song_events_example/source/template.c, audio/maxmod/song_events_example2/source/template.c, Graphics/3D/3D_Both_Screens/source/template.c, Graphics/Sprites/allocation_test/source/main.c, Graphics/Sprites/animate_simple/source/template.c, Graphics/Sprites/bitmap_sprites/source/main.cpp, Graphics/Sprites/simple/source/template.c, Graphics/Sprites/sprite_extended_palettes/source/template.c, and Graphics/Sprites/sprite_rotate/source/template.c.

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

Examples:

Graphics/Sprites/bitmap_sprites/source/main.cpp, and Graphics/Sprites/sprite_rotate/source/template.c.

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

Examples:

audio/maxmod/song_events_example/source/template.c, audio/maxmod/song_events_example2/source/template.c, Graphics/Sprites/allocation_test/source/main.c, Graphics/Sprites/animate_simple/source/template.c, Graphics/Sprites/bitmap_sprites/source/main.cpp, Graphics/Sprites/simple/source/template.c, Graphics/Sprites/sprite_extended_palettes/source/template.c, and Graphics/Sprites/sprite_rotate/source/template.c.

static void oamSetMosaic	(	unsigned int	dx,
		unsigned int	dy
	)			[inline, static]

sets engine A global sprite mosaic

Parameters:

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

static void oamSetMosaicSub	(	unsigned int	dx,
		unsigned int	dy
	)			[inline, static]

sets engine B global sprite mosaic

Parameters:

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

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

Examples:

audio/maxmod/song_events_example/source/template.c, audio/maxmod/song_events_example2/source/template.c, Graphics/3D/3D_Both_Screens/source/template.c, Graphics/Sprites/allocation_test/source/main.c, Graphics/Sprites/animate_simple/source/template.c, Graphics/Sprites/bitmap_sprites/source/main.cpp, Graphics/Sprites/simple/source/template.c, Graphics/Sprites/sprite_extended_palettes/source/template.c, and Graphics/Sprites/sprite_rotate/source/template.c.