libnds
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
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

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. More...
 
u16oamAllocateGfx (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...
 
u16oamGetGfxPtr (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

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.

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.

Color formats for sprite graphics.

Enumerator
SpriteColorFormat_16Color 

16 colors per sprite

SpriteColorFormat_256Color 

256 colors per sprite

SpriteColorFormat_Bmp 

16-bit sprites

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
oamThe oam engine, must be &oamMain or &oamSub.
rotIdThe id of the rotscale item you want to change, must be 0-31.
hdxThe change in x per horizontal pixel.
hdyThe change in y per horizontal pixel.
vdxThe change in x per vertical pixel.
vdyThe change in y per vertical pixel.
u16* oamAllocateGfx ( OamState oam,
SpriteSize  size,
SpriteColorFormat  colorFormat 
)

Allocates graphics memory for the supplied sprite attributes.

Parameters
oammust be: &oamMain or &oamSub
sizethe size of the sprite to allocate
colorFormatthe 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
oammust be: &oamMain or &oamSub
startThe first index to clear
countThe number of sprites to clear
static void oamClearSprite ( OamState oam,
int  index 
)
inlinestatic

Hides a single sprite.

Parameters
oamthe oam engine, must be &oamMain or &oamSub.
indexthe index of the sprite, must be 0-127.
int oamCountFragments ( OamState oam)

determines the number of fragments in the allocation engine

Parameters
oammust be: &oamMain or &oamSub
Returns
the number of fragments.
void oamDisable ( OamState oam)

Disables sprite rendering.

Parameters
oammust be: &oamMain or &oamSub
void oamEnable ( OamState oam)

Enables sprite rendering.

Parameters
oammust be: &oamMain or &oamSub
void oamFreeGfx ( OamState oam,
const void *  gfxOffset 
)

free vram memory obtained with oamAllocateGfx.

Parameters
oammust be: &oamMain or &oamSub
gfxOffseta vram offset obtained from oamAllocateGfx
u16* oamGetGfxPtr ( OamState oam,
int  gfxOffsetIndex 
)

translates an oam offset into a video ram address

Parameters
oammust be: &oamMain or &oamSub
gfxOffsetIndexthe 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
oammust be: &oamMain or &oamSub
offsetthe 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
oammust be: &oamMain or &oamSub
mappingthe mapping mode
extPaletteif 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
oammust be: &oamMain or &oamSub
rotIdthe rotation entry to set
anglethe ccw angle to rotate [-32768 - 32767]
sxthe inverse scale factor in the x direction
sythe 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0 - 127]
xthe x location of the sprite in pixels
ythe y location of the sprite in pixels
priorityThe sprite priority (0 to 3)
palette_alphathe 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]
sizethe size of the sprite
formatthe color format of the sprite
gfxOffsetthe video memory address of the sprite graphics (not an offset)
affineIndexaffine index to use (if < 0 or > 31 the sprite will be unrotated)
sizeDoubleif affineIndex >= 0 this will be used to double the sprite size for rotation
hideif non zero (true) the sprite will be hidden
vflipflip the sprite vertically
hflipflip the sprite horizontally
mosaicif 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
affineIndexaffine index to use (if < 0 or > 31 the sprite will be unrotated)
sizeDoubleif 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
alphathe 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
hflipflip the sprite horizontally
vflipflip 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
sizethe size of the sprite
formatthe color format of the sprite
gfxOffsetthe 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
hideif 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
mosaicif 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
palettethe 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
priorityThe 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
oammust be: &oamMain or &oamSub
idthe oam number to be set [0-127]
xthe x location of the sprite in pixels
ythe 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
oammust be: &oamMain or &oamSub