libnds
Data Structures | Macros | Typedefs | Enumerations | Functions | Variables
sprite.h File Reference

NDS sprite helpers. More...

#include <nds/arm9/video.h>
#include <nds/memory.h>
#include <nds/ndstypes.h>
#include <nds/system.h>

Data Structures

struct  OamState
 Holds the state for a 2D sprite engine. More...
 
union  OAMTable
 Union that describes the structure of OAM in memory. More...
 
union  SpriteEntry
 A bitfield of sprite attributes. 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 OAMTable OAMTable
 Union that describes the structure of OAM in memory.
 
typedef union SpriteEntry SpriteEntry
 A bitfield of sprite attributes.
 
typedef struct SpriteRotation SpriteRotation
 A sprite rotation entry.
 

Enumerations

enum  ObjBlendMode {
  OBJMODE_NORMAL = 0 ,
  OBJMODE_BLENDED = 1 ,
  OBJMODE_WINDOWED = 2 ,
  OBJMODE_BITMAP = 3
}
 The blending mode of the sprite. More...
 
enum  ObjColMode {
  OBJCOLOR_16 = 0 ,
  OBJCOLOR_256 = 1
}
 The color mode of the sprite. More...
 
enum  ObjPriority {
  OBJPRIORITY_0 = 0 ,
  OBJPRIORITY_1 = 1 ,
  OBJPRIORITY_2 = 2 ,
  OBJPRIORITY_3 = 3
}
 The priority of the sprite. More...
 
enum  ObjShape {
  OBJSHAPE_SQUARE = 0 ,
  OBJSHAPE_WIDE = 1 ,
  OBJSHAPE_TALL = 2 ,
  OBJSHAPE_FORBIDDEN = 3
}
 The shape of the sprite. More...
 
enum  ObjSize {
  OBJSIZE_8 = 0 ,
  OBJSIZE_16 = 1 ,
  OBJSIZE_32 = 2 ,
  OBJSIZE_64 = 3
}
 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 ,
  SpriteMapping_Bmp_1D_256 ,
  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 | (int)(8U << 28) | 3
}
 Graphics memory layout options. More...
 
enum  SpriteMode {
  SpriteMode_Normal = OBJMODE_NORMAL ,
  SpriteMode_Blended = OBJMODE_BLENDED ,
  SpriteMode_Windowed = OBJMODE_WINDOWED ,
  SpriteMode_Bitmap = OBJMODE_BITMAP
}
 Color formats for sprite graphics. 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) ,
  SpriteSize_Invalid = 0
}
 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 set 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. 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...
 
SpriteSize oamDimensionsToSize (int width, int height)
 Returns a SpriteSize enumeration value from dimensions in pixels. 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 VRAM 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. 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 oamSetBlendMode (OamState *oam, int id, SpriteMode mode)
 Sets an OAM entry to the specified blending mode. More...
 
static void oamSetFlip (OamState *oam, int id, bool hflip, bool vflip)
 Sets an OAM entry to the supplied flipping. More...
 
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 to be updated. More...
 

Variables

OamState oamMain
 An object representing the main 2D engine.
 
OamState oamSub
 An object representing the sub 2D engine.
 

Detailed Description

NDS sprite helpers.

Typedef Documentation

◆ OamState

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

◆ 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.

◆ ObjColMode

enum ObjColMode

The color mode of the sprite.

Enumerator
OBJCOLOR_16 

Sprite has 16 colors.

OBJCOLOR_256 

Sprite has 256 colors.

◆ 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.

◆ ObjShape

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.

◆ ObjSize

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.

◆ SpriteColorFormat

Color formats for sprite graphics.

Enumerator
SpriteColorFormat_16Color 

16 colors per sprite

SpriteColorFormat_256Color 

256 colors per sprite

SpriteColorFormat_Bmp 

16-bit sprites

◆ 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

◆ SpriteMode

enum SpriteMode

Color formats for sprite graphics.

Enumerator
SpriteMode_Normal 

No special mode is on, normal sprite state.

SpriteMode_Blended 

Color blending is on, sprite can use HW blending features.

SpriteMode_Windowed 

Sprite can be seen only inside the sprite window.

SpriteMode_Bitmap 

Sprite is not using tiles, per pixel image data.

◆ SpriteSize

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

SpriteSize_Invalid 

Invalid size.

Function Documentation

◆ oamAffineTransformation()

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

Allows you to directly set 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
oamMust be &oamMain or &oamSub.
rotIdThe ID of the rotscale item you want to change [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.

◆ oamAllocateGfx()

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.

◆ oamClear()

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

Hides the sprites in the supplied range.

Parameters
oamMust be &oamMain or &oamSub.
startThe first index to clear.
countThe number of sprites to clear (zero will clear all sprites).

◆ oamClearSprite()

static void oamClearSprite ( OamState oam,
int  index 
)
inlinestatic

Hides a single sprite.

Parameters
oamMust be &oamMain or &oamSub.
indexThe index of the sprite [0 - 127].

◆ oamCountFragments()

int oamCountFragments ( OamState oam)

Determines the number of fragments in the allocation engine.

Parameters
oamMust be &oamMain or &oamSub.
Returns
The number of fragments.

◆ oamDimensionsToSize()

SpriteSize oamDimensionsToSize ( int  width,
int  height 
)

Returns a SpriteSize enumeration value from dimensions in pixels.

Parameters
widthWidth in pixels.
heightHeight in pixels.
Returns
A valid SpriteSize enum value or SpriteSize_Invalid.

◆ oamDisable()

void oamDisable ( OamState oam)

Disables sprite rendering.

Parameters
oamMust be &oamMain or &oamSub.

◆ oamEnable()

void oamEnable ( OamState oam)

Enables sprite rendering.

Parameters
oamMust be &oamMain or &oamSub.

◆ oamFreeGfx()

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.

◆ oamGetGfxPtr()

u16 * oamGetGfxPtr ( OamState oam,
int  gfxOffsetIndex 
)

Translates an OAM offset into a VRAM address.

Parameters
oamMust be &oamMain or &oamSub.
gfxOffsetIndexThe index to compute.
Returns
The address in VRAM corresponding to the supplied offset.

◆ oamGfxPtrToOffset()

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

Convert a VRAM address to an OAM offset.

Parameters
oamMust be &oamMain or &oamSub.
offsetThe VRAM of the sprite graphics (not an offset).
Returns
OAM offset.

◆ oamInit()

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 it sets up extended palettes for 8 bpp sprites.

◆ oamRotateScale()

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.

◆ oamSet()

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 VRAM address of the sprite graphics (not an offset).
affineIndexAffine index to use [0 - 31].
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.

◆ oamSetAffineIndex()

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 [0 - 31].
sizeDoubleIf affineIndex >= 0 and < 32 this will be used to double the sprite size for rotation.

◆ oamSetAlpha()

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].

◆ oamSetBlendMode()

static void oamSetBlendMode ( OamState oam,
int  id,
SpriteMode  mode 
)
inlinestatic

Sets an OAM entry to the specified blending mode.

Normally you should only use this function with SpriteMode_Blended and SpriteMode_Windowed. SpriteMode_Normal and SpriteMode_Bitmap are set automatically by the other functions in this file.

Parameters
oamMust be &oamMain or &oamSub.
idThe OAM number to be set [0 - 127].
modeThe mode to set the sprite to.

◆ oamSetFlip()

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.

◆ oamSetGfx()

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

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 VRAM address of the sprite graphics (not an offset).

◆ oamSetHidden()

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.

◆ oamSetMosaic()

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.

◆ oamSetMosaicEnabled()

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.

◆ oamSetMosaicSub()

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.

◆ oamSetPalette()

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].

◆ oamSetPriority()

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].

◆ oamSetXY()

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.

◆ oamUpdate()

void oamUpdate ( OamState oam)

Causes OAM to be updated.

It must be called during vblank if using the OAM API.

Parameters
oamMust be &oamMain or &oamSub.