sgdk: vdp_spr.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Classes | Defines | Functions | Variables
vdp_spr.h File Reference

VDP Sprite support. More...

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

Go to the source code of this file.

## Classes

struct | VDPSprite
| VDP sprite definition structure replicating VDP hardware sprite. More...

## Defines

#define | _VDP_SPR_H_
#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()

All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines