Thbg

From ProjectWiki
(Difference between revisions)
Jump to: navigation, search
(→Functions)
Line 5: Line 5:
 
* finish documentation...
 
* finish documentation...
  
−
==Functions==
+
==Background functions==
−
Documentation is a work in progress...
+
'''thBgInit'''
 +
Initialize the thBg system, this includes setting up the scene manager, malloc functions and assigning VRAM banks.
 
<source lang="c">
 
<source lang="c">
−
typedef void(*_pBgStartFunc)(void); //Background Setup Function (called first)
+
void thBgInit(void);
−
typedef void(*_pBgUpdateFunc)(int); //Background update function
+
</source>
−
typedef void(*_pBgFinishFunc)(void); //Background destroy function
+
  
−
typedef struct {
+
'''thBgCreate'''
−
_pBgStartFunc start;
+
Loads a bg map, tiles, and palette into vram and displays it
−
_pBgUpdateFunc update;
+
* screen - which screen (0 to 1)
−
_pBgFinishFunc finish;
+
* bg - which background to use (0 to 3)
−
void *bgdat; //background set specific data
+
* bgnfo -
−
} thbg_t;
+
* tiles - pointer to tile data
 +
* tilesize - size of tile data in bytes
 +
* map - pointer to map data
 +
* mapsize - size of map data in bytes
 +
<source lang="c">
 +
bool thBgCreate(int screen, int bg, u16 bgnfo, u16 *tiles, int tilesize, u16 *map, int mapsize);
 +
</source>
  
−
void thBgInit(void); //get everything ready
+
'''thBgLoad'''
−
void thBgUpdate(int frame); //call this every vblank
+
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.
−
void thBgStart(thbg_t *thbg); //call this to start a bg (will first stop any already running)
+
* screen - which screen (0 to 1)
−
void thBgFinish(void); //stops bg, erases bg mem, etc
+
* 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)
 +
<source lang="c">
 +
bool thBgLoad(int screen, int bg, const char *fileprefix, int opts);
 +
</source>
  
−
void thUpdateBgPalette(uint16 *pal, int dstpal, int size);
+
'''thBgDestroy'''
−
void thUpdateBgSubPalette(uint16 *pal, int dstpal, int size);
+
Unloads and stops displaying background
 +
* screen - which screen (0 to 1)
 +
* bg - which background to use (0 to 3)
 +
<source lang="c">
 +
bool thBgDestroy(int screen, int bg); //frees any used vram, and otherwise disables specified background.. returns true if bg exists
 +
</source>
  
 +
'''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!!!)
 +
<source lang="c">
 +
void thBgSetRotScale(int screen, int bg, u16 angle, int xmag, int ymag, u32 scrollx, u32 scrolly, u32 xc, u32 yc);
 +
</source>
  
 +
'''thUpdateBgPalette'''
 +
Update the palette used by a background.
 +
* pal - pointer to RGB15 array of palette data
 +
* dstpal - destination bg (0-3)
 +
* size - in bytes of RGB15 array.
 +
<source lang="c">
 +
void thUpdateBgPalette(uint16 *pal, int dstpal, int size);
 +
</source>
  
−
//Note there rly shouldnt ever be > 4 bg loaded at a time
+
'''thUpdateBgSubPalette'''
−
//aslo map allocs grow from top downward...
+
Same as above except applies to Sub screen.
 +
<source lang="c">
 +
void thUpdateBgSubPalette(uint16 *pal, int dstpal, int size);
 +
</source>
 +
 
 +
==Macros and Defines==
 +
<source lang="c">
 +
//map allocs grow from top downward...
 
#define THMAXBGTILES (128/16) //max tile slots (128K / 16K tile slot boundries)
 
#define THMAXBGTILES (128/16) //max tile slots (128K / 16K tile slot boundries)
 
#define THMAXBGMAPS 31 //max map slots (128K / 1K map slot boundries)
 
#define THMAXBGMAPS 31 //max map slots (128K / 1K map slot boundries)
Line 36: Line 74:
 
//for thBgLoad
 
//for thBgLoad
 
#define BGDEFAULTS -1
 
#define BGDEFAULTS -1
−
 
−
typedef struct _THBG_T {
 
−
int map;
 
−
int tilealloc; //tiles grow from top of vram..
 
−
int tile;
 
−
bool used;
 
−
} THBG_T;
 
  
 
#define THMAXBG 0x4 //each screen only has up to 4 bg right?
 
#define THMAXBG 0x4 //each screen only has up to 4 bg right?
Line 80: Line 111:
  
 
inline void thBgDisable(int screen, int bg);
 
inline void thBgDisable(int screen, int bg);
−
 
−
//This is exactly the same malloc scheme i keep ripping off from vram malloc... rly i should just make a universal malloc code and consolidate all these...
 
−
//vram alloc element
 
−
typedef struct _bgre {
 
−
u16 size; //in tiles
 
−
u16 tile;
 
−
bool used;
 
−
struct _bgre *next;
 
−
} bgre;
 
  
 
void setBgVBlank(void); //set the BgVblank int
 
void setBgVBlank(void); //set the BgVblank int
Line 99: Line 121:
 
inline bool thBgTFree(int screen, int tile);
 
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
 
bool thBgCreateAlloc(int screen, int bg, int tilesize, int mapsize); //alloc for both tiles and maps, and store values into bg table
−
bool thBgCreate(int screen, int bg, u16 bgnfo, u16 *tiles, int tilesize, u16 *map, int mapsize);
 
−
bool thBgLoad(int screen, int bg, const char *fileprefix, int opts);
 
−
bool thBgDestroy(int screen, int bg); //frees any used vram, and otherwise disables specified background.. returns true if bg exists
 
−
void thBgSetRotScale(int screen, int bg, u16 angle, int xmag, int ymag, u32 scrollx, u32 scrolly, u32 xc, u32 yc);
 
  
 +
typedef struct _THBG_T {
 +
int map;
 +
int tilealloc; //tiles grow from top of vram..
 +
int tile;
 +
bool used;
 +
} THBG_T;
 +
 +
</source>
 +
 +
==Scene management functions==
 +
These functions allow for setting up, updating, and cleaning up after different scenes.
 +
<source lang="c">
 +
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)
 +
void thBgFinish(void); //stops bg, erases bg mem, etc
 +
</source>
 +
 +
==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...)
 +
<source lang="c">
 +
typedef struct _bgre {
 +
u16 size; //in tiles
 +
u16 tile;
 +
bool used;
 +
struct _bgre *next;
 +
} bgre;
 
</source>
 
</source>

Revision as of 14:58, 1 February 2009

Contents

What is this?

Background management functions for nintendo ds. Supports easy loading from filesystem, smart vram allocation, and stuff.

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)
  • bgnfo -
  • 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 bgnfo, 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!!!) 
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.

  • 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)
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;
Retrieved from "http://blea.ch/wiki/index.php?title=Thbg&oldid=1652"
Personal tools
irssi scripts
eggdrop scripts