Thbg
(→What is this?) |
(→Scene management functions) |
||
Line 142: | Line 142: | ||
==Scene management functions== | ==Scene management functions== | ||
− | These functions allow for setting up, updating, and cleaning up after different scenes. | + | These functions allow for setting up, updating, and cleaning up after different scenes. |
<source lang="c"> | <source lang="c"> | ||
typedef void(*_pBgStartFunc)(void); //Background Setup Function (called first) | typedef void(*_pBgStartFunc)(void); //Background Setup Function (called first) | ||
Line 156: | Line 156: | ||
void thBgUpdate(int frame); //call this every vblank | void thBgUpdate(int frame); //call this every vblank | ||
− | void thBgStart(thbg_t *thbg); //call this to start a bg (will first stop any already running) | + | void thBgStart(thbg_t *thbg); //call this to start a bg (will first stop any already running background) |
void thBgFinish(void); //stops bg, erases bg mem, etc | void thBgFinish(void); //stops bg, erases bg mem, etc | ||
</source> | </source> |
Revision as of 03:09, 11 March 2009
Contents |
What is this?
Background image functions for nintendo ds.
Features:
- easy loading from filesystem or memory
- auto vram allocation
- rotation and scaling function
- supports rotscale, tile, bitmap modes
- management functions for starting, stopping, selecting, and updating background scenery
Todo/Bugs
- finish documentation...
Background functions
thBgInit
Initialize the thBg system, this includes setting up the scene manager, malloc functions and assigning VRAM banks.
void thBgInit(void);
thBgCreate
Loads a bg map, tiles, and palette into vram and displays it
- screen - which screen (0 to 1)
- bg - which background to use (0 to 3)
- opts - options for this background, such as BG_32x32|BG_COLOR_256|BG_PRIORITY() to be OR'd onto this background's control register.
- tiles - pointer to tile data
- tilesize - size of tile data in bytes
- map - pointer to map data
- mapsize - size of map data in bytes
bool thBgCreate(int screen, int bg, u16 opts, u16 *tiles, int tilesize, u16 *map, int mapsize);
thBgLoad
Loads a background from from file(s). If tiled bg, fileprefix is the beginning of name, .raw, .bin, .pal is then appended to provide names for loading.
- screen - which screen (0 to 1)
- bg - which background to use (0 to 3)
- fileprefix - filename, or start of filename if paletted bg
- opts - options for this background, ORed together, such as: BG_32x32|BG_COLOR_256|BG_PRIORITY(BG_PRIORITY_2)
bool thBgLoad(int screen, int bg, const char *fileprefix, int opts);
thBgDestroy
Unloads and stops displaying background
- screen - which screen (0 to 1)
- bg - which background to use (0 to 3)
bool thBgDestroy(int screen, int bg); //frees any used vram, and otherwise disables specified background.. returns true if bg exists
thBgSetRotScale
Rotates and/or scales a background. Screen must first be set to proper mode using thBgSetMode or thBgSetModeSub
- screen - which screen (0 to 1)
- bg - which background to use (2 to 3 only!!!)
- angle - rotation angle (standard nds angles)
- xmag, ymag - magnification (128 == 1:1, 256=1/2, 64=double size, etc)
- scrollx, scrolly - scrolls either x or y
- xc, yc - center point of source image
void thBgSetRotScale(int screen, int bg, u16 angle, int xmag, int ymag, u32 scrollx, u32 scrolly, u32 xc, u32 yc);
thUpdateBgPalette
Update the palette used by a background. Background's control register must first be setup using thBgCreate, thBgLoad, or the BGCR macro in order for thUpdateBgPalette to know if its 16 or 256 color mode.
- pal - pointer to RGB15 array of palette data
- dstpal - destination bg (0-3)
- size - in bytes of RGB15 array.
void thUpdateBgPalette(uint16 *pal, int dstpal, int size);
thUpdateBgSubPalette
Same as above except applies to Sub screen.
void thUpdateBgSubPalette(uint16 *pal, int dstpal, int size);
Macros and Defines
//map allocs grow from top downward... #define THMAXBGTILES (128/16) //max tile slots (128K / 16K tile slot boundries) #define THMAXBGMAPS 31 //max map slots (128K / 1K map slot boundries) //for thBgLoad #define BGDEFAULTS -1 #define THMAXBG 0x4 //each screen only has up to 4 bg right? #define THMAXSCR 0x2 //macro to find proper bg control reg #define BGCR(s,b) (*(vuint16*)(0x04000008+((s)<<12)+((b)<<1))) #define BGX(s,b) (*(vuint16*)(0x04000010+((s)<<12)+((b)<<2))) #define BGY(s,b) (*(vuint16*)(0x04000012+((s)<<12)+((b)<<2))) //bitmap same as tile 0x4000 boundries ^^ #define BGBMPRAM(s,b) (((b)<<14) + 0x06000000+((s)<<21)) #define BGTILERAM(s,b) (((b)<<14) + 0x06000000+((s)<<21)) #define BGMAPRAM(s,b) (((b)<<11) + 0x06000000+((s)<<21)) #define DISPLAYCR(s) (*(vuint32*)(0x04000000+((s)<<12))) enum { BGNORMAL=0, BGROTSCALE=1, BGBMP=2 }; #define thBgSetMode(m) ((*(vuint32*)0x04000000)=((*(vuint32*)0x04000000)&0xfffffff8)|(m)) #define thBgGetMode() ((*(vuint32*)0x04000000)&0x7) #define thBgSetModeSub(m) ((*(vuint32*)0x04001000)=((*(vuint32*)0x04001000)&0xfffffff8)|(m)) #define thBgGetModeSub() ((*(vuint32*)0x04001000)&0x7) extern THBG_T thbgs[THMAXSCR][THMAXBG]; //Macros to get the allocated tile and map locations for a particular screen #define thBgTile(s,b) (thbgs[(s)][(b)].tile) #define thBgMap(s,b) (thbgs[(s)][(b)].map) inline void thBgEnable(int screen, int bg); inline void thBgDisable(int screen, int bg); void setBgVBlank(void); //set the BgVblank int void vblankInt(void); //this function needs to be called during vblank, calling setBgVBlank() sets this as vblank interrupt.. void thBgVramAllocInit(void); //alloc init (called in bg init) inline int thBgMAlloc(int screen, u32 size); //bg map alloc (size in map slots 0x800 boundries) inline int thBgTAlloc(int screen, u32 size); //bg tile alloc (size in tile slots 0x4000 bounds) inline bool thBgMFree(int screen, int map); //free for each of above inline bool thBgTFree(int screen, int tile); bool thBgCreateAlloc(int screen, int bg, int tilesize, int mapsize); //alloc for both tiles and maps, and store values into bg table typedef struct _THBG_T { int map; int tilealloc; //tiles grow from top of vram.. int tile; bool used; } THBG_T;
Scene management functions
These functions allow for setting up, updating, and cleaning up after different scenes.
typedef void(*_pBgStartFunc)(void); //Background Setup Function (called first) typedef void(*_pBgUpdateFunc)(int); //Background update function typedef void(*_pBgFinishFunc)(void); //Background destroy function typedef struct { _pBgStartFunc start; _pBgUpdateFunc update; _pBgFinishFunc finish; void *bgdat; //background set specific data } thbg_t; void thBgUpdate(int frame); //call this every vblank void thBgStart(thbg_t *thbg); //call this to start a bg (will first stop any already running background) void thBgFinish(void); //stops bg, erases bg mem, etc
Internally Used Structures
bgre vram alloc element (This is exactly the same malloc scheme i keep ripping off from vram malloc and is used by sprites, fifo and bglibs... rly i should just make a universal malloc code and consolidate all these...)
typedef struct _bgre { u16 size; //in tiles u16 tile; bool used; struct _bgre *next; } bgre;