ANIMATED SPRITES

(C)Copyright J. Tann 1998
All Rights Reserved


This is a simple library of functions to aid in the creation and use of
animated sprites. Although, the functions can also be used for ordinary
non-animated sprites.

There are 8 functions in all as follows...

AsInit()	Initialises the animated sprites memory area.
AsFree()	Frees the animated sprites memory area.
AsUpdate()	Updates all active sprites and adds them to the order table.
AsCreate()	Creates a sprite.
AsDelete()	Deletes a sprite.
AsMove()	Moves a sprite around the screen.
AsShow()	Shows or hides a sprite.
AsControl()	Controls a sprite's animation playback.

The file ANI_SPR.H should be included in any source file that uses the
functions. ANI_SPR.O should also be linked into your project.

Here is a detailed description of each function...


int AsInit(int max)

Parameters:
	max	The maximum number of sprites to be used at any one time.

Return:		True (!0) for ok and false (0) for error.

Description:	This function intialises memory and other 'bits' for the
		animated sprites to work. All the other functions will
		not work unless this function has been called. Only call
		this function once unless you use AsFree() before calling
		it again.

Example:	AsInit(25);	// Initialise for 25 animated sprites


void AsFree()

Paramters:	None

Return:		None

Description:	This frees memory allocated by AsInit(). This must be called
		before the program ends or before another call to AsInit().


void AsUpdate(GsOT *ot)

Parameters:
	ot	The current order table being used to display objects.

Return:		None

Description:	This function is the main function that does all the work of
		animating the sprites. It should be called once every VSYNC
		in your main program loop prior to using GsDrawOt(). It sets
		each sprite's current frame of animation and adds the sprite
		to the order table.

Example:	AsUpdate(&WorldOT[activeBuff]);


int AsCreate(GsIMAGE tim, u_short tpage, int x, int y, int w, int h,
	     int frames, int delay, int loop)

Parameters:
	tim	Sprite's frame images
	tpage	Sprite's texture page
	x	X coord of the first frame in the tpage
	y	Y coord of the first frame
	w	Width of each frame
	h	Height of each frame
	frames	Number of frames
	delay	VSYNC delay for each frame displayed.
	loop	Use ANI_ONCE to play through just once, ANI_LOOP to loop the
		animation (default) and ANI_BOUNCE to loop back and forth.

Return:		The sprite number of the sprite or -1 for an error.

Description:	This function is used to create a sprite. This would normally
		be used during the program's initialisation routine where all
		sprites and images are created. The coordinates for the first
		frame should have a y offset that lies on a boundary equal to
		the sprite's height. So if the height of the sprite is 20 the
		valid y offsets are 0, 20, 40, 50 and so on. The frames of
		the sprite should flow down the columns of the tpage and move
		on to the next column if the next frame clips off the bottom
		of the tpage! The column's width is the width of the sprite.
		The delay value slows the sprite's animation by making it
		wait 'delay' calls to AsUpdate() before moving on to the next
		frame. The sprite number returned is used for all the sprite
		functions that follow.

Example:	RECT rect;
		GsIMAGE	mytim;
		u_short tpage;
		int spriteNum;
		GsGetTimInfo(spriteImageAddress, &mytim);
		rect.x = mytim.px;
		rect.y = mytim.py;
		rect.w = mytim.pw;
		rect.h = mytim.ph;
		LoadImage(&rect, mytim.pixel);
		rect.x = mytim.cx;
		rect.y = mytim.cy;
		rect.w = mytim.cw;
		rect.h = mytim.ch;
		LoadImage(&rect, mytim.clut);
		tpage = GetTPage(1, 0, mytim.px, mytim.py);
		spriteNum = AsCreate(mytim, tpage, 0, 0, 16, 16, 25, 0,
				     ANI_LOOP);


void AsDelete(int sprite)

Parameters:
	sprite	The number of the sprite returned by AsCreate()

Return:		None

Description:	This simply deletes a sprite! If you have reached the maximum
		number of sprites as specified in the call to AsInit() and
		you want to create another then you need to delete an existing
		sprite with this function or increase your maximum number!!

Example:	AsDelete(spriteNum);


void AsMove(int sprite, int x, int y, int move)

Parameters:
	sprite	The number of the sprite returned by AsCreate()
	x	The new x coordinate or the x offset for relative movement
	y	The new y coordinate or the y offset
	move	MOVE_ABSOLUTE or MOVE_RELATIVE

Return:		None

Description:	This function is used to change a sprite's position on the
		display. This function should be called once prior to
		showing a sprite with AsShow() as a sprite is created at
		position 0,0 on the display! If MOVE_RELATIVE is used then
		the sprite is moved relative to it's current location. So
		if x is -2 the sprite is moved 2 pixels left.

Example:	AsMove(spriteNum, 2, -2, MOVE_RELATIVE);


void AsShow(int sprite, int show)

Parameters:
	sprite	The number of the sprite returned by AsCreate()
	show	SHOW_SPRITE or HIDE_SPRITE

Return:		None

Description:	This is used to display a sprite or hide it. Make sure you
		have used AsMove() with an absolute position before displaying
		the sprite for the first time as AsCreate() creates the sprite
		at location 0,0.

Example:	AsShow(spriteNum, SHOW_SPRITE);


int AsControl(int sprite, int code)

Parameters:
	sprite	The number of the sprite returned by AsCreate()
	code	Animation control code. ANI_START, ANI_STOP and ANI_PAUSE

Return:		True for ok or false for invalid code.

Description:	This function controls the 'playback' of a sprite's animation.
		ANI_START starts the animation playing.
		ANI_STOP stops the animation and sets the displayed frame to
		the first frame.
		ANI_PAUSE stops the animation at the current frame.

Example:	AsControl(spriteNum, ANI_START);


I hope I have given you an easy to understand description of the functions. If
you have any questions then feel free to contact me by any of the means shown
below.

EMAIL:		johnt@nettech.demon.co.uk
ICQ:		9461567