From ProjectWiki
Jump to: navigation, search

thSprite - Danmaku dual screen spritelib for NDS


Project Status: Alpha Testing

What is this?

Purpose of this library is to create dual screen sprite engine for danmaku (also known as curtain fire, bullet hell, and/or Touhou games) and encourage their development on the NDS. (I'm sorta a fan, can you tell??) The library is being created for this Touhou fan game, and posting here because of interest from others. Right now is coded for current version of libnds, but will soon most likely update for the beta version.

The documentation is completely unfinished as is the library. Most features are supported already however.

660 randomly placed multiplexed sprites

should have the following features:

  • treats both screens as one long 384px high screen
  • be able to multiplex sprites giving up to 1024 sprites total (tho limited to 128 sprites in any of 8 48px high vertical blocks see image below of sprite saturation)
  • dynamically created/destroyed sprites
  • efficient use of hardware sprites only allocating sprite for which screen it can be viewed on
  • auto deallocation of hardware sprites that are not visible and reallocation if returned to screen (sprite x,y values are singed 32 bit singed ints so offscreen sprites are possible)
  • loose priority system in the range of 0-127, tries to give u whatever priority u request or closest match.. -1 = psuedo random priority
  • handles double sized sprites
  • supports multiple sprite shapes, not just square...
  • Anchor points can be set for centering gfx or to ease combining multiple sprites (composite)
  • support multiple bitdepths instead of just 8bpp (saves significant amounts of vram)
  • improved vram allocation. uses smallest hole that will fit requested size first. added thSpriteGfxUnload()


  • readd support for changing sprite gfx
  • add macros for getting sprite x,y positions ?
  • break up gfx from sprite .h (and mebbe .c) files for consistency between png2thg converter and ds code.
  • add .bmp loader!! (keep forgetting about this) :PPPPPP

Where to get it

Currently the sources for this are part of LibThds. The source can be downloaded via SVN (see libthds page) or directly from the svn httpd:

If the png loader is desired:

This file contains special effects macros that may be used with thdualsrites (these functions are shared with the background and 3D libs as well):

A demonstration and example code for most functions can be found here:


User should typically not touch the data contained within these types...

spriteGfx_t - graphics object data and information.

  • size - in pixels, only using width atm because all my sprites are square, but will soon add x,y sizes
  • attr1 - size in attr1 format or any other attr1 info
  • attr2 - palette to use, again already in attr2 format
  • framesize - how many tiles make up 1 frame

thSprite_t - sprite object information..

  • which gfx object does this sprite use
  • attr0
  • attr1
  • attr2 - these are ofc the preformated attribs
  • ani - used to associate an animation object with this sprite

Gfx functions

These functions deal with loading and managing graphics and palettes in vram. Most will return or take an object of type spriteGfx_t.

Loads a graphics object from file (converted to .thg format using my converter)

  • filename - filename/path string
  • dstpal - which palette will the gfx object use

returns newly created gfx object, or NULL if error

spriteGfx_t *thSpriteGfxLoad(const char *filename, int dstpal)

Create a gfx object from raw data (maybe have a simpler version without the anchors?)

  • gfx - raw graphics data (from grit or whatever)
  • width, height - width & height in pixels
  • xanchor, yanchor - sets the anchor point (0,0 == top left, width,height = bottom right, etc)
  • dstpal - which palette will the gfx object use

returns newly created gfx object, or NULL if error

spriteGfx_t *thSpriteGfxCreate(void *gfx, int width, int height, s16 xanchor, s16 yanchor, int dstpal)

Makes a copy of a gfx object

  • gfx - already created graphics object

returns newly created gfx object, or NULL if error

spriteGfx_t *thSpriteGfxCopy(spriteGfx_t *gfx)

Loads gfx object from .png file (this is not part of the spritelib really, but included for testing and eval)

  • filename - path to .png file
  • dstpal - which palette the gfx object will use
  • frames - number of frames contained within image (frames are one after another vertically)

returns newly created gfx object, or NULL if error

spriteGfx_t *thSpritePngLoad(char *filename, int dstpal, u16 frames)

Erases gfx and free's up vram. gfx then becomes invalid and should not be used.

  • gfx - pointer to gfx object.
void thSpriteGfxUnload(spriteGfx_t *gfx)

Load sprite palette (rgb15,256 colors, 16 pals). (or each frame to do color rotations ooo ahhh :P)

  • pal - pointer to rgb15 format color table
  • dstpal - the destination palette (1-16)
  • cmode - either THCMODE256, or THCMODE16. It will copy 256 or 16 colors from dstpal, if the supplied tabels are shorter than the expect number of palette entries it will copy random data to unused colors.
void thSpriteGfxPal(u16 *pal, int dstpal, u16 cmode)

Sprite Functions

Display and manipulate sprites.

Initalize thSprite system (and gfx)

void thSpriteInit(void)

create a sprite, returns sprite obj or NULL if error...

  • gfx - gfx object to use (see above)
  • x,y - starting position of sprite
  • attr0, attr1, attr2 - attributes, sets things like rotation and alpha blending, double sized, etc
  • priority - which priority, 0 == top 127 == bottom, -1 == random
thSprite_t *thSpriteCreate(spriteGfx_t *gfx, int x, int y, u16 attr0, u16 attr1, u16 attr2, signed char priority)

called by external functions to destory a created sprite, pass spriteHandle

  • thsp - touhou sprite object to destroy
int thSpriteDestroy(thSprite_t *thsp)

Sets new x,y position first arg= sprite object

  • thsp - touhou sprite object
  • x,y - new x,y position (offset by anchor points set in gfx loading functions :)
void thSpriteSetXY(thSprite_t *thsp, int x, int y)

enables or disables alpha on a sprite

  • thsp - touhou sprite object
  • alpha - false == no alpha, true == alpha
void thSpriteSetAlpha(thSprite_t *thsp, bool alpha)

changes which rotset is associated with a sprite

  • thsp - touhou sprite object
void thSpriteUpdateRotset(thSprite_t *thsp, unsigned char rotset)

NOTE: these last two functions are things i need in my game and may not be in any librarys i publish. (in game where bullets may turn to bonus boxes the player can collect and its easier to upadte just the gfx than deleting and creating hundreds of new bullets/sprites)

update the image used by the sprite

  • thsp - touhou sprite object
  • gfx - gfx object to use (see above)
  • attr0, attr1, attr2 (see above)
void thSpriteUpdateGfx(thSprite_t *thsp, spriteGfx_t *gfx, u16 attr0, u16 attr1, u16 attr2)

displays info such as memory used, number of active sprites etc, just for debugging...

void thSpriteDiag(void)

Various Macros
returns true or false indicating if sprite is visible or not.

  • s = sprite of type thSprite_t *
#define thSpriteVisable(s) (((s)->hwsprite[0]==-1)?false:true)


Animate a sprite or display a particular frame.

display the specified frame of the sprite

  • sprite - sprite object to animate
  • start - first frame of animation
void thSpriteFrame(thSprite_t *thsp, int frame)

stop animations on sprite, you may wanna set a new frame now :P Should be called before sprite is destroyed, if sprite destroyed will automatically stop animation.. (may cause unexpected results if stopped after sprite has been destroyed)

  • sprite - sprite object to animate
void thSpriteAnimStop(thSprite_t *sprite)

start a sprite animation

  • sprite - sprite object to animate
  • start - first frame of animation
  • loop - loop start point (if < start will be set to start value)
  • end - last frame of animation
  • speed - 256 == 1 frame per second, 128 == .5 frames per second, 512 == 2 frames per sec, etc
void thSpriteAnim(thSprite_t *sprite, u8 start, u8 loop, u8 end, u16 speed)

called each frame in users program to do animations

void thSpriteUpdateAnim(void)


Manage and manipulate rotsets

init rotsets, tho this should prolly be called from spriteInit() eh?

void rotsetInit(void)

change rotset params

void rotSet(int rotset, u16 angle, int xmag, int ymag)

same as above without magnify

void rotSetNoZoom(int rotset, u16 angle)

allocate a rotset, and start automagic rotation.. if spd and angle are set.. returns a rotset you can apply to a sprite

u8 rotsetCreate(int spd, u32 angle)

dealloc rotset

void rotsetDestroy(u8 rotset)

called each frame to update automagic rotations

void rotsetUpdate()

Misc Functions

  • x1, y1 - First set of x,y coords
  • x2, y2 - Second set

returns square distance between two objects in 2D space

inline u64 thDistance(s32 x1, s32 y1, s32 x2, s32 y2);


if(thDistance(obj1x, obj1y, obj2x, obj2y)<(30*30)) {
 printf("they're closer than 30 pixels from each other!");


Most of these effects macros were 'borrowed' from palib. They worked well... >_> <_<

//These first few lines stolen *gasp* from palib (hey i liked the way they did a few things)
#define REG_BLDCNT(s)   (*(uint16 *)(0x04000050+((s)*0x1000)))
#define REG_BLDALPHA(s) (*(uint16 *)(0x04000052+((s)*0x1000)))
#define thSpriteSetAlphaBlend(s, a, b) REG_BLDALPHA(s)=(a)+((b)<<8)
#define thEnableSpecialFx(s, t, a, b) REG_BLDCNT(s) = ((a)+((b)<<8)+((t)<<6))
#define SFX_BG0 1
#define SFX_BG1 2
#define SFX_BG2 4
#define SFX_BG3 8
#define SFX_OBJ 16
#define SFX_BD  32
#define SFX_NONE 0
#define SFX_ALPHA 1
//end of palib theft :p


Examples are probably the best way to understand how this should be used...

//create player sprite from thg format gfx file.. pur her about center of bottom screen with priority of 119
spriteGfx_t *loli=thSpriteCreate(thSpriteGfxLoad("nitro:/kaguya-boss.thg", 5), 128, 264, 0, 0, 0, 119);
//Animate her!! (start with frame 0, and loop from frame 0 to frame 3, with speed of 65)
thSpriteAnim(loli, 0, 0, 3, 65);
//and move her around (this would be ofc in user's vblank loop)
if(touchXY.x>100) {
//Create a sprite from raw data... 8x8 pixels width/height, anchor points 4,4 (center of sprite)
//will display onto center of screen about 32 pixels down
 thSpriteGfxPal((u16*)fampalp_Pal, 256, 2);
 thSpriteCreate(thSpriteGfxCreate((void*)fambullet8x8_Sprite,8,8,4,4,2), 128, 32, 0, 0, 0, 120);
//Load a star sprite from png file and make it rotate automagically..
                   10, 5, ATTR0_ROTSCALE, ATTR1_ROTDATA(rotsetCreate(600, 0)), 0, -1);
//Load enemy 64x64 sprite from png, and create her on screen with a priority of 50, and place in middle of screen
spriteGfx_t *gfx;
thSpriteCreate(gfx, 128-32, 64, 0, 0, 0, 50);	
//Create 450 sprites using the same gfx (see random picture above :P)
if(a<450) {
  thSpriteCreate(gfx, rand()&0xff, rand()&0x1ff, 0, 0, 0, -1);

thg graphics file format

Just some notes on this.. its basically just the raw gfx, palette, and size, frames, etc data in a simple format for easy loading without requiring entering a zillion params. File extension is ".thg" and can be stored on the FAT, Nitro, or other filesystems and loaded as needed.

Description of format
The file contains the following data (in order):

spriteGfx_t spritegfx structure populated with appropriate data
thggfx_t thggfx  other gfx metadata (see struct below)
u16[] pallette image palette array of either 16 or 256 u16's depending
u16[] imagedata    

the thgfx structure type:

typedef struct {
	int	imgdatasz;	//image data size
	u16	frames;		//total frames
	u16	cmode;		//color mode
} thggfx_t;

Various Screenshots

515 sprites moving in a pattern
Pretty more practical moving pattern.. note the crappy double sized laser effects! im not good at drawing lasers, yet!)
Here is what happens if u push it too hard, will try its best, but if it cannot allocate a hw sprite will simply move on and not completely freak tho the image may be screwed for a bit
Personal tools
irssi scripts
eggdrop scripts