VDP Sprite support. More...

#include "config.h"
#include "types.h"
#include "dma.h"

Classes
struct	VDPSprite
	VDP sprite definition structure replicating VDP hardware sprite. More...
Defines
#define	MAX_VDP_SPRITE 80
	Maximum number of hardware sprite.
#define	SPRITE_SIZE(w, h) ((((w) - 1) << 2) \| ((h) - 1))
	Helper to define sprite size in sprite definition structure.
Functions
void	VDP_resetSprites ()
	Clear all sprites and reset VDP sprite allocation (if any).
void	VDP_releaseAllSprites ()
	Release all VDP sprite allocation.
s16	VDP_allocateSprites (u16 num)
	Allocate the specified number of hardware VDP sprites and link them together.
void	VDP_releaseSprites (u16 index, u16 num)
	Release specified number of VDP sprites.
u16	VDP_getAvailableSprites ()
	Return the number of available VDP sprite.
s16	VDP_refreshHighestAllocatedSpriteIndex ()
	Compute and return the highest index of currently allocated VDP sprite. A value of -1 mean no VDP Sprite are allocated. This value can be used to define the number of sprite to transfer with VDP_updateSprites(..) method.
void	VDP_clearSprites ()
	Clear all sprites.
void	VDP_setSpriteFull (u16 index, s16 x, s16 y, u8 size, u16 attribut, u8 link)
	Set a sprite (use sprite list cache).
void	VDP_setSprite (u16 index, s16 x, s16 y, u8 size, u16 attribut)
	Set a sprite (use sprite list cache).
void	VDP_setSpritePosition (u16 index, s16 x, s16 y)
	Set sprite position (use sprite list cache).
void	VDP_setSpriteSize (u16 index, u8 size)
	Set sprite size (use sprite list cache).
void	VDP_setSpriteAttribut (u16 index, u16 attribut)
	Set sprite attributes (use sprite list cache).
void	VDP_setSpriteLink (u16 index, u8 link)
	Set sprite link (use sprite list cache).
VDPSprite *	VDP_linkSprites (u16 index, u16 num)
	Link sprites starting at the specified index. Links are created in simple ascending order (1 --> 2 --> 3 --> ...)
void	VDP_updateSprites (u16 num, TransferMethod tm)
	Send the cached sprite list to the VDP.
Variables
VDPSprite	vdpSpriteCache [MAX_VDP_SPRITE]
	VDP sprite cache.
VDPSprite *	lastAllocatedVDPSprite
	Pointer to last allocated sprite after calling VDP_allocateSprites(..) method. This can be used to do the link from the last allocated VDP sprite.
s16	highestVDPSpriteIndex
	Highest index of allocated VDP sprite since the last call to VDP_resetSprites() or VDP_releaseAllSprites(). A value of -1 mean no VDP Sprite were allocated.. This can be used to define the number of sprite to transfer with VDP_updateSprites(..) method. WARNING: this value is not correctly updated on sprite release operation so it may gives an higher index than reality. You can ue currently VDP_refreshHighestAllocatedSpriteIndex() method to force recomputation of highest index (costs a bit of time).

Detailed Description

VDP Sprite support.

Author:: Stephane Dallongeville

Date:: 08/2011

This unit provides methods to allocate and manipulate VDP Sprite at low level.
The Sega Genesis VDP can handle up to 80 simultanous sprites of 4x4 tiles (32x32 pixels).

Define Documentation

#define SPRITE_SIZE	(	w,
		h
	)	((((w) - 1) << 2) \| ((h) - 1))

Helper to define sprite size in sprite definition structure.

Parameters:

w	sprite width (in tile).
h	sprite height (in tile).

Function Documentation

s16 VDP_allocateSprites ( u16 num )

Allocate the specified number of hardware VDP sprites and link them together.

Parameters:

num	Number of VDP sprite to allocate (need to be > 0)

Returns:: the first VDP sprite index where allocation was made.
-1 if there is not enough available VDP sprite remaining.

This method allocates the specified number of VDP sprite and returns the index of the first allocated sprite in VDP sprite table (see vdpSpriteCache).
Sprites are linked together using link field (last sprite ends with link 0).
If there is not enough available VDP sprites the allocation operation fails and return -1. NOTE: The last sprite from the allocated list can be retrieved with lastAllocatedVDPSprite, this is to avoid parsing all the list to find it, if we want to link it to a specific sprite for instance.

See also:: VDP_releaseSprites(..)

u16 VDP_getAvailableSprites ( )

Return the number of available VDP sprite.

See also:: VDP_allocateSprites(..); VDP_releaseSprites(..)

VDPSprite* VDP_linkSprites	(	u16	index,
		u16	num
	)

Link sprites starting at the specified index.
Links are created in simple ascending order (1 --> 2 --> 3 --> ...)

Parameters:

index	Index of the first sprite we want to link (should be < MAX_VDP_SPRITE).
num	Number of link to create (if you want to link 2 sprites you should use 1 here)

Returns:: The last linked sprite

s16 VDP_refreshHighestAllocatedSpriteIndex ( )

Compute and return the highest index of currently allocated VDP sprite.
A value of -1 mean no VDP Sprite are allocated.
This value can be used to define the number of sprite to transfer with VDP_updateSprites(..) method.

See also:: VDP_allocateSprites(..); VDP_releaseSprites(..); highestVDPSpriteIndex

void VDP_releaseSprites	(	u16	index,
		u16	num
	)

Release specified number of VDP sprites.

Parameters:

index	The index of the first VDP sprite to release (0 <= index < MAX_SPRITE)
num	Number of VDP sprite to release (should be > 0)

This method release the specified number of VDP sprite from the specified index using the link field information to determine which sprites to release when more than 1 sprite is released.

See also:: VDP_allocateSprites(..)

void VDP_setSprite	(	u16	index,
		s16	x,
		s16	y,
		u8	size,
		u16	attribut
	)

Set a sprite (use sprite list cache).

Parameters:

index	Index of the sprite to set (should be < MAX_VDP_SPRITE).
x	Sprite position X on screen.
y	Sprite position Y on screen.
size	Sprite size (see SPRITE_SIZE() macro).
attribut	Sprite tile attributes (see TILE_ATTR_FULL() macro).

See also:: VDP_setSpriteFull(); VDP_updateSprites()

void VDP_setSpriteAttribut	(	u16	index,
		u16	attribut
	)

Set sprite attributes (use sprite list cache).

Parameters:

index	Index of the sprite to modify attributes (should be < MAX_VDP_SPRITE).
attribut	Sprite tile attributes (see TILE_ATTR_FULL() macro).

See also:: VDP_setSprite(..); VDP_updateSprites()

void VDP_setSpriteFull	(	u16	index,
		s16	x,
		s16	y,
		u8	size,
		u16	attribut,
		u8	link
	)

Set a sprite (use sprite list cache).

Parameters:

index	Index of the sprite to set (should be < MAX_VDP_SPRITE).
x	Sprite position X on screen.
y	Sprite position Y on screen.
size	Sprite size (see SPRITE_SIZE() macro).
attribut	Sprite tile attributes (see TILE_ATTR_FULL() macro).
link	Sprite link (index of next sprite, 0 for end) Be careful to not modify link made by VDP_allocateSprite(..), use VDP_setSprite(..) instead in that case.

See also:: VDP_setSprite(); VDP_updateSprites()

void VDP_setSpriteLink	(	u16	index,
		u8	link
	)

Set sprite link (use sprite list cache).

Parameters:

index	Index of the sprite to modify link (should be < MAX_VDP_SPRITE).
link	Sprite link (index of next sprite, 0 for end).

See also:: VDP_setSprite(..); VDP_updateSprites()

void VDP_setSpritePosition	(	u16	index,
		s16	x,
		s16	y
	)

Set sprite position (use sprite list cache).

Parameters:

index	Index of the sprite to modify position (should be < MAX_VDP_SPRITE).
x	Sprite position X.
y	Sprite position Y.

See also:: VDP_setSprite(..); VDP_updateSprites()

void VDP_setSpriteSize	(	u16	index,
		u8	size
	)

Set sprite size (use sprite list cache).

Parameters:

index	Index of the sprite to modify size (should be < MAX_VDP_SPRITE).
size	Sprite size (see SPRITE_SIZE() macro).

See also:: VDP_setSprite(..); VDP_updateSprites()

void VDP_updateSprites	(	u16	num,
		TransferMethod	tm
	)

Send the cached sprite list to the VDP.

Parameters:

num	Number of sprite to transfer starting at index 0 (max = MAX_SPRITE). If you use dynamic VDP Sprite allocation you may use 'highestVDPSpriteIndex + 1' here
tm	Transfer method. Accepted values are: CPU DMA DMA_QUEUE DMA_QUEUE_COPY

See also:: highestVDPSpriteIndex; VDP_refreshHighestAllocatedSpriteIndex()

Variable Documentation

s16 highestVDPSpriteIndex

Highest index of allocated VDP sprite since the last call to VDP_resetSprites() or VDP_releaseAllSprites().
A value of -1 mean no VDP Sprite were allocated..
This can be used to define the number of sprite to transfer with VDP_updateSprites(..) method.
WARNING: this value is not correctly updated on sprite release operation so it may gives an higher index than reality.
You can ue currently VDP_refreshHighestAllocatedSpriteIndex() method to force recomputation of highest index (costs a bit of time).

See also:: VDP_refreshHighestAllocatedSpriteIndex()

Classes

Defines

Functions

Variables

Detailed Description

Define Documentation

Function Documentation

Variable Documentation