libnds
|
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. | |
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. | |
WARN_UNUSED_RESULT 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. | |
static void | oamClearSprite (OamState *oam, int index) |
Hides a single sprite. | |
int | oamCountFragments (OamState *oam) |
Determines the number of fragments in the allocation engine. | |
SpriteSize | oamDimensionsToSize (int width, int height) |
Returns a SpriteSize enumeration value from dimensions in pixels. | |
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 VRAM address. | |
unsigned int | oamGfxPtrToOffset (OamState *oam, const void *offset) |
Convert a VRAM address to an OAM offset. | |
void | oamInit (OamState *oam, SpriteMapping mapping, bool extPalette) |
Initializes the 2D sprite engine. | |
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 | oamSetAffineIndex (OamState *oam, int id, int affineIndex, bool sizeDouble) |
Sets an OAM entry to the supplied affine index. | |
static void | oamSetAlpha (OamState *oam, int id, int alpha) |
Sets a bitmapped OAM entry to the supplied transparency. | |
static void | oamSetBlendMode (OamState *oam, int id, SpriteMode mode) |
Sets an OAM entry to the specified blending mode. | |
static void | oamSetFlip (OamState *oam, int id, bool hflip, bool vflip) |
Sets an OAM entry to the supplied flipping. | |
void | oamSetGfx (OamState *oam, int id, SpriteSize size, SpriteColorFormat format, const void *gfxOffset) |
Sets an OAM entry to the supplied shape/size/pointer. | |
static void | oamSetHidden (OamState *oam, int id, bool hide) |
Sets an OAM entry to the supplied hidden state. | |
static void | oamSetMosaic (unsigned int dx, unsigned int dy) |
Sets engine A global sprite mosaic. | |
static void | oamSetMosaicEnabled (OamState *oam, int id, bool mosaic) |
Sets an OAM entry to enable or disable mosaic. | |
static void | oamSetMosaicSub (unsigned int dx, unsigned int dy) |
Sets engine B global sprite mosaic. | |
static void | oamSetPalette (OamState *oam, int id, int palette) |
Sets a paletted OAM entry to the supplied palette. | |
static void | oamSetPriority (OamState *oam, int id, int priority) |
Sets an OAM entry to the supplied priority. | |
static void | oamSetXY (OamState *oam, int id, int x, int y) |
Sets an OAM entry to the supplied (x, y) position. | |
void | oamUpdate (OamState *oam) |
Causes OAM to be updated. | |
Variables | |
OamState | oamMain |
An object representing the main 2D engine. | |
OamState | oamSub |
An object representing the sub 2D engine. | |
NDS sprite helpers.
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.
enum ObjBlendMode |
The blending mode of the sprite.
enum ObjColMode |
enum ObjPriority |
enum ObjShape |
enum ObjSize |
enum SpriteColorFormat |
enum SpriteMapping |
Graphics memory layout options.
enum SpriteMode |
Color formats for sprite graphics.
enum SpriteSize |
Enumerates all sizes supported by the 2D engine.
|
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.
oam | Must be &oamMain or &oamSub. |
rotId | The ID of the rotscale item you want to change [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. |
WARN_UNUSED_RESULT u16 * oamAllocateGfx | ( | OamState * | oam, |
SpriteSize | size, | ||
SpriteColorFormat | colorFormat | ||
) |
Allocates graphics memory for the supplied sprite attributes.
oam | Must be &oamMain or &oamSub.. |
size | The size of the sprite to allocate. |
colorFormat | The color format of the sprite. |
void oamClear | ( | OamState * | oam, |
int | start, | ||
int | count | ||
) |
Hides the sprites in the supplied range.
oam | Must be &oamMain or &oamSub. |
start | The first index to clear. |
count | The number of sprites to clear (zero will clear all sprites). |
|
inlinestatic |
Hides a single sprite.
oam | Must be &oamMain or &oamSub. |
index | The index of the sprite [0 - 127]. |
int oamCountFragments | ( | OamState * | oam | ) |
Determines the number of fragments in the allocation engine.
oam | Must be &oamMain or &oamSub. |
SpriteSize oamDimensionsToSize | ( | int | width, |
int | height | ||
) |
Returns a SpriteSize enumeration value from dimensions in pixels.
width | Width in pixels. |
height | Height in pixels. |
void oamDisable | ( | OamState * | oam | ) |
Disables sprite rendering.
oam | Must be &oamMain or &oamSub. |
void oamEnable | ( | OamState * | oam | ) |
Enables sprite rendering.
oam | Must be &oamMain or &oamSub. |
void oamFreeGfx | ( | OamState * | oam, |
const void * | gfxOffset | ||
) |
Free VRAM memory obtained with oamAllocateGfx.
oam | Must be &oamMain or &oamSub. |
gfxOffset | A VRAM offset obtained from oamAllocateGfx. |
Translates an OAM offset into a VRAM address.
oam | Must be &oamMain or &oamSub. |
gfxOffsetIndex | The index to compute. |
unsigned int oamGfxPtrToOffset | ( | OamState * | oam, |
const void * | offset | ||
) |
Convert a VRAM address to an OAM offset.
oam | Must be &oamMain or &oamSub. |
offset | The VRAM 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.
oam | Must be &oamMain or &oamSub. |
mapping | The mapping mode. |
extPalette | If true it sets up extended palettes for 8 bpp sprites. |
void oamRotateScale | ( | OamState * | oam, |
int | rotId, | ||
int | angle, | ||
int | sx, | ||
int | sy | ||
) |
Sets the specified rotation scale entry.
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.
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 VRAM address of the sprite graphics (not an offset). |
affineIndex | Affine index to use [0 - 31]. |
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. |
|
inlinestatic |
Sets an OAM entry to the supplied affine index.
oam | Must be &oamMain or &oamSub. |
id | The OAM number to be set [0 - 127]. |
affineIndex | Affine index to use [0 - 31]. |
sizeDouble | If affineIndex >= 0 and < 32 this will be used to double the sprite size for rotation. |
|
inlinestatic |
Sets a bitmapped OAM entry to the supplied transparency.
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]. |
|
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.
oam | Must be &oamMain or &oamSub. |
id | The OAM number to be set [0 - 127]. |
mode | The mode to set the sprite to. |
|
inlinestatic |
Sets an OAM entry to the supplied flipping.
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. |
void oamSetGfx | ( | OamState * | oam, |
int | id, | ||
SpriteSize | size, | ||
SpriteColorFormat | format, | ||
const void * | gfxOffset | ||
) |
Sets an OAM entry to the supplied shape/size/pointer.
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 VRAM address of the sprite graphics (not an offset). |
|
inlinestatic |
Sets an OAM entry to the supplied hidden state.
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. |
|
inlinestatic |
Sets engine A global sprite mosaic.
dx | (0-15) horizontal mosaic value. |
dy | (0-15) horizontal mosaic value. |
|
inlinestatic |
Sets an OAM entry to enable or disable mosaic.
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. |
|
inlinestatic |
Sets engine B global sprite mosaic.
dx | (0-15) horizontal mosaic value. |
dy | (0-15) horizontal mosaic value. |
|
inlinestatic |
Sets a paletted OAM entry to the supplied palette.
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
|
|
inlinestatic |
Sets an OAM entry to the supplied priority.
oam | Must be &oamMain or &oamSub. |
id | The OAM number to be set [0 - 127]. |
priority | The sprite priority [0 - 3]. |
|
inlinestatic |
Sets an OAM entry to the supplied (x, y) position.
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 to be updated.
It must be called during vblank if using the OAM API.
oam | Must be &oamMain or &oamSub. |