Thbg

From ProjectWiki
(Difference between revisions)
Jump to: navigation, search
 
(42 intermediate revisions by 29 users not shown)
Line 8: Line 8:
 
* management functions for starting, stopping, selecting, and updating background scenery
 
* management functions for starting, stopping, selecting, and updating background scenery
  
 +
2009-04-08: Made a small dent in the documentation, some things are a bit difficult to explain >_<  but working on it in between other projects.
 
2009-03-24: have fixed most of the bitmap bg issues, and wrote example/eval code. :D updates comming soon...
 
2009-03-24: have fixed most of the bitmap bg issues, and wrote example/eval code. :D updates comming soon...
  
Line 15: Line 16:
 
* [http://svn.blea.ch/thdslib/trunk/thdslib/source/arm9/include/thbg.h thbg.h]
 
* [http://svn.blea.ch/thdslib/trunk/thdslib/source/arm9/include/thbg.h thbg.h]
 
* [http://svn.blea.ch/thdslib/trunk/thdslib/source/arm9/source/thbg.c thbg.c]
 
* [http://svn.blea.ch/thdslib/trunk/thdslib/source/arm9/source/thbg.c thbg.c]
This file is separate and contains the special effects macros separate from thbg because these functions are shared with the sprite and 3D libs as well.
+
This file is separate and contains the special effects macros that may be used with thbg (these functions are shared with the sprite and 3D libs as well)
 
* [http://svn.blea.ch/thdslib/trunk/thdslib/source/arm9/include/thsfx.h thsfx.h]  
 
* [http://svn.blea.ch/thdslib/trunk/thdslib/source/arm9/include/thsfx.h thsfx.h]  
  
 
Example code:
 
Example code:
* [http://svn.blea.ch/thdslib/trunk/thdslib/examples/thbg simple thbg example]. Demonstrates custom fonts, rotation, scaling, scrolling, 16 and 256 color.
+
* [http://svn.blea.ch/thdslib/trunk/thdslib/examples/thbg simple thbg example]. Demonstrates custom fonts, rotation, scaling, scrolling, 16 and 256 color, BMP backgrounds, and BG management functions. :D
  
 
==Todo/Bugs==
 
==Todo/Bugs==
Line 43: Line 44:
 
Same as above function except allocates 256K of vram on engine A using Banks B and D.
 
Same as above function except allocates 256K of vram on engine A using Banks B and D.
 
void thBgInit256(void);
 
void thBgInit256(void);
 +
<source lang="c">
 +
void thBgInit256(void);
 +
</source>
 +
 +
'''void thBgUninit(void)'''<br>
 +
Deallocates resources used by thbg. VRAM banks remain set but are no longer used. This function may be used if it is desired to call thBgInit* again, or simply used to clear all backgrounds.
 +
<source lang="c">
 +
void thBgUninit(void);
 +
</source>
  
 
'''setBgVBlank'''<br>
 
'''setBgVBlank'''<br>
Line 54: Line 64:
 
<source lang="c">
 
<source lang="c">
 
void thBgSetVBlank(_pBgVBlankFunc newvbfunc);
 
void thBgSetVBlank(_pBgVBlankFunc newvbfunc);
 +
</source>
 +
 +
'''thBgCreateBmp'''
 +
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.
 +
* bmp - pointer to tile data
 +
* bmpsize - size of tile data in bytes
 +
returns true if successfull
 +
<source lang="c">
 +
bool thBgCreateBmp(int screen, int bg, u16 opts, u16 *bmp, int bmpsize);
 
</source>
 
</source>
  
Line 65: Line 87:
 
* map - pointer to map data
 
* map - pointer to map data
 
* mapsize - size of map data in bytes
 
* mapsize - size of map data in bytes
 +
returns true if successfull
 
<source lang="c">
 
<source lang="c">
 
bool thBgCreate(int screen, int bg, u16 opts, u16 *tiles, int tilesize, u16 *map, int mapsize);
 
bool thBgCreate(int screen, int bg, u16 opts, u16 *tiles, int tilesize, u16 *map, int mapsize);
Line 75: Line 98:
 
* fileprefix - filename, or start of filename if paletted bg
 
* 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). The macro BGDEFAULTS is provided to to set the default bg values BG_32x32|BG_COLOR_256.
 
* opts - options for this background, ORed together, such as: BG_32x32|BG_COLOR_256|BG_PRIORITY(BG_PRIORITY_2). The macro BGDEFAULTS is provided to to set the default bg values BG_32x32|BG_COLOR_256.
 +
returns true if successfull
 
<source lang="c">
 
<source lang="c">
 
bool thBgLoad(int screen, int bg, const char *fileprefix, int opts);
 
bool thBgLoad(int screen, int bg, const char *fileprefix, int opts);
Line 83: Line 107:
 
* screen - which screen (0 to 1)
 
* screen - which screen (0 to 1)
 
* bg - which background to use (0 to 3)
 
* bg - which background to use (0 to 3)
 +
returns true if successfull
 
<source lang="c">
 
<source lang="c">
 
bool thBgDestroy(int screen, int bg); //frees any used vram, and otherwise disables specified background.. returns true if bg exists
 
bool thBgDestroy(int screen, int bg); //frees any used vram, and otherwise disables specified background.. returns true if bg exists
 +
</source>
 +
 +
'''thBgEnable'''<br>
 +
Enables (displays) the background where:
 +
* screen - screen 0 ~ 1
 +
* bg - background 0 ~ 4
 +
<source lang="c">
 +
void thBgEnable(int screen, int bg);
 +
</source>
 +
 +
'''thBgDisable'''<br>
 +
Disables (turns off) the background where:
 +
* screen - screen 0 ~ 1
 +
* bg - background 0 ~ 4
 +
<source lang="c">
 +
void thBgDisable(int screen, int bg);
 
</source>
 
</source>
  
 
'''thBgSetRotScale'''<br>
 
'''thBgSetRotScale'''<br>
 
Rotates and/or scales a background. Screen must first be set to proper mode using thBgSetMode or thBgSetModeSub
 
Rotates and/or scales a background. Screen must first be set to proper mode using thBgSetMode or thBgSetModeSub
* screen - which screen (0 to 1)
+
* screen - which screen (0 ~ 1)
* bg - which background to use (2 to 3 only!!!)
+
* bg - which background to use (2 ~ 3 only!!!)
 
* angle - rotation angle (standard nds angles)
 
* angle - rotation angle (standard nds angles)
 
* xmag, ymag - magnification  (256 == 1:1, 512=1/2, 128=double size, etc)
 
* xmag, ymag - magnification  (256 == 1:1, 512=1/2, 128=double size, etc)
Line 124: Line 165:
 
</source>
 
</source>
  
==Macros and Defines==
+
===Macros and Defines===
 
Below are relevant macros and defines.
 
Below are relevant macros and defines.
 
<source lang="c">
 
<source lang="c">
Line 174: Line 215:
  
 
extern THBG_T thbgs[THMAXSCR][THMAXBG];
 
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)
 
void thBgVramAllocInit(void); //alloc init (called in bg init)
Line 192: Line 221:
 
inline bool thBgMFree(int screen, int map); //free for each of above  
 
inline bool thBgMFree(int screen, int map); //free for each of above  
 
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
 
  
 
typedef struct _THBG_T {
 
typedef struct _THBG_T {
Line 202: Line 230:
  
 
</source>
 
</source>
 +
 
===Examples===
 
===Examples===
 
Some quick examples. In addition to enabling the displays and vblank interrupt as usual the following thbg functions should be called:
 
Some quick examples. In addition to enabling the displays and vblank interrupt as usual the following thbg functions should be called:
Line 225: Line 254:
 
</source>
 
</source>
  
===Display a BMP background from ram, and change it===
+
testing to see if it worked
<source lang="c">
+
//Set BMP mode (this needs to be done manually see also thBgSetModeSub)
+
thBgSetMode(MODE_5_2D);
+
//Allocate ram and display. BMP bg is always number 2
+
thBgCreateBmp(0, 2, BG_BMP16_256x256, (u16*)ranka1_raw, 256*192*sizeof(u16));
+
  
/* Do other things for a while
+
Hi :)
...
+
  ok now change the bg */
+
 
+
thBgBlitBmp(0,2, ranka2_raw, ranka_raw2_size);
+
</source>
+
 
+
==Scene management functions==
+
These functions allow for setting up, updating, and cleaning up after different scenes.
+
 
+
===Scene Control Functions===
+
These functions are called from the user's program to start, update, and stop playground playback.<br>
+
Functions are used as follows:
+
'''thBgStart'''<br>
+
Start a background scene. If a previous scene was running it will be stopped before starting the next one
+
* thbg - pointer to a structure of the thbg_t type.
+
<source lang="c">
+
void thBgStart(thbg_t *thbg);
+
</source>
+
 
+
'''thBgUpdate'''<br>
+
This function should be called every frame from the mainloop of program.
+
* frame - frame count.. this may (or may not) be used by the user's background
+
<source lang="c">
+
void thBgUpdate(int frame);
+
</source>
+
 
+
'''thBgFinish'''<br>
+
Stops currently running background
+
<source lang="c">
+
void thBgFinish(void);
+
</source>
+
 
+
===Scene Function Types===
+
'''_pBgStartFunc'''<br>
+
Background Setup Function (called first)
+
<source lang="c">
+
typedef void(*_pBgStartFunc)(void);
+
</source>
+
 
+
'''_pBgUpdateFunc'''<br>
+
Background update function
+
<source lang="c">
+
typedef void(*_pBgUpdateFunc)(int);
+
</source>
+
 
+
'''_pBgFinishFunc'''<br>
+
Background destroy function
+
<source lang="c">
+
typedef void(*_pBgFinishFunc)(void);
+
</source>
+
 
+
'''thbg_t'''<br>
+
This structure type defines
+
<source lang="c">
+
typedef struct {
+
_pBgStartFunc start;
+
_pBgUpdateFunc update;
+
_pBgFinishFunc finish;
+
} thbg_t;
+
</source>
+
  
 
==Internally Used Structures==
 
==Internally Used Structures==

Latest revision as of 14:15, 13 August 2011

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

2009-04-08: Made a small dent in the documentation, some things are a bit difficult to explain >_< but working on it in between other projects. 2009-03-24: have fixed most of the bitmap bg issues, and wrote example/eval code. :D updates comming soon...

Where to get it

thbg demo: loads custom font and displays rotscaled scrolling backgrounds.

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:

This file is separate and contains the special effects macros that may be used with thbg (these functions are shared with the sprite and 3D libs as well)

Example code:

  • simple thbg example. Demonstrates custom fonts, rotation, scaling, scrolling, 16 and 256 color, BMP backgrounds, and BG management functions. :D

Todo/Bugs

  • Seperate loading and displaying functions to improve scene change time
  • add png/bmp displaying ability (perhaps using a common gfx object type to load png or bmp, for backgrounds and sprites both?)
  • need bmp example
  • finish documentation...

Author's notes: need to provide better facilities for caching data from the filesystem to ram before loading to vram. perhaps thBgCreate can be used to prepare a bg in ram before thBgDisplay

Background functions

thBgInit
Initialize the thBg system, this includes setting up the scene manager, malloc functions and assigning VRAM banks:

  • VRAM_B - MAIN BG
  • VRAM_E - MAIN PAL (EXT)
  • VRAM_C - SUB BG
  • VRAM H - SUB PAL (EXT)
void thBgInit(void);

thBgInit256
Same as above function except allocates 256K of vram on engine A using Banks B and D. void thBgInit256(void);

void thBgInit256(void);

void thBgUninit(void)
Deallocates resources used by thbg. VRAM banks remain set but are no longer used. This function may be used if it is desired to call thBgInit* again, or simply used to clear all backgrounds.

void thBgUninit(void);

setBgVBlank
This function currently must be called separately from thBgInit* and sets up the vblank interrupt for use with thbg. The rotation and scale data must be updated during vBlank, and calling this function ensures this will occur. However it may be necessary to use the vBlank for other purposes so thBgSetVBlank is provided to to allow auxiliary functions to be called. Alternatively vblankInt may be called from the user's own blank function.

void setBgVBlank(void);

thBgSetVBlank
adds an auxillary function to be called during vblank. See setBgVBlank for more explanation.

void thBgSetVBlank(_pBgVBlankFunc newvbfunc);

thBgCreateBmp 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.
  • bmp - pointer to tile data
  • bmpsize - size of tile data in bytes

returns true if successfull

bool thBgCreateBmp(int screen, int bg, u16 opts, u16 *bmp, int bmpsize);

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

returns true if successfull

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). The macro BGDEFAULTS is provided to to set the default bg values BG_32x32|BG_COLOR_256.

returns true if successfull

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)

returns true if successfull

bool thBgDestroy(int screen, int bg); //frees any used vram, and otherwise disables specified background.. returns true if bg exists

thBgEnable
Enables (displays) the background where:

  • screen - screen 0 ~ 1
  • bg - background 0 ~ 4
void thBgEnable(int screen, int bg);

thBgDisable
Disables (turns off) the background where:

  • screen - screen 0 ~ 1
  • bg - background 0 ~ 4
void thBgDisable(int screen, int bg);

thBgSetRotScale
Rotates and/or scales a background. Screen must first be set to proper mode using thBgSetMode or thBgSetModeSub

  • screen - which screen (0 ~ 1)
  • bg - which background to use (2 ~ 3 only!!!)
  • angle - rotation angle (standard nds angles)
  • xmag, ymag - magnification (256 == 1:1, 512=1/2, 128=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);

thUpdateBgPal
This macro allows a more automated way of updating the palette by automatically selecting the proper function based on the 'screen' variable.

  • s - screen 0~1
  • d - destination background 0~3
  • p - source palette data. RGB15(x,x,x) array
  • l - palette length in bytes
thUpdateBgPal(s,d,p,l);

Macros and Defines

Below are relevant macros and defines.

//for thBgLoad
#define BGDEFAULTS	-1
 
//macro to find proper bg control reg
#define BGCR(s,b) (*(vuint16*)(0x04000008+((s)<<12)+((b)<<1)))
//calc (non-rotscale||bitmap) scroll register values..
#define BGX(s,b) (*(vuint16*)(0x04000010+((s)<<12)+((b)<<2)))
#define BGY(s,b) (*(vuint16*)(0x04000012+((s)<<12)+((b)<<2)))
 
 
//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)
 
//Calculate ram address based on screen
//bitmap same as tile 0x4000 boundries ^^
#define BGCTILERAM(s,t) (((t)<<14) + 0x06000000+((s)<<21))
#define BGCBMPRAM(s,b) (((b)<<14) + 0x06000000+((s)<<21))
#define BGCMAPRAM(s,m)  (((m)<<11) +  0x06000000+((s)<<21))
 
//same as above but lookup via the screen/bg from alloc tables
#define BGTILERAM(s,b) (BGCTILERAM((s),thbgs[(s)][(b)].tile))
#define BGBMPRAM(s,b) (BGCBMPRAM((s),thbgs[(s)][(b)].tile))
#define BGMAPRAM(s,b) (BGCMAPRAM((s),thbgs[(s)][(b)].map))
 
//Psuedo blitter type operations for copying to 
//display allocated display ram  screen, bg0~3, inbuffer, imagesize
#define thBgBlitBmp(s,b,i,l) dmaCopyWords(THBGDMA,(void*)(i), (u16*)BGBMPRAM((s),(b)), (l))
#define thBgBlitTile(s,b,i,l) dmaCopyWords(THBGDMA,(void*)(i), (u16*)BGTILERAM((s),(b)), (l))
#define thBgBlitMap(s,b,i,l) dmaCopyWords(THBGDMA,(void*)(i), (u16*)BGMAPRAM((s),(b)), (l))
 
 
#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];
 
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);
 
typedef struct _THBG_T {
	int	map;
	int	tilealloc;	//tiles grow from top of vram.. 
	int	tile;
	bool	used;
} THBG_T;

Examples

Some quick examples. In addition to enabling the displays and vblank interrupt as usual the following thbg functions should be called:

thBgInit();
setBgVBlank();

Display 16 color 256x256 background from RAM

Displays on screen 0, background #1

thUpdateBgPal(0,1, background_pal, background_pal_size);
thBgCreate(0, 1, BG_32x32 | BG_16_COLOR, 
           (u16*)backgroundtiles_raw, backgroundtiles_raw_size, 
           backgroundmap, backgroundmap_size);

Display a 256 color background from file

Will load and display a 256 color bg from a file.

thBgSetMode(1);
thBgLoad(0, 3, "nitro:/somebg",BG_RS_32x32|BG_COLOR_256|BG_PRIORITY(BG_PRIORITY_3)|BG_WRAP_ON);

testing to see if it worked

Hi :)

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;
Personal tools
irssi scripts
eggdrop scripts