spman.lib reference

Version 1.2.0

Overview

spman is a simple sprite manager that provides:

support for 16x16 sprites.
an easy way to manage sprite patterns.
a simple yet effective sprite flicker that allows displaying more than 4 sprites on the same line, with support for “fixed” sprites that are excluded from flickering.

It should be easy to modify and customize (spman.c is around 100 lines of code).

The manager is used as follows:

Initialize the manager with spman_init.
Allocate patterns with spman_alloc. This can be done at any time, it is not needed to allocate all the patterns in one go.
In the game loop:
- Allocate sprites to be drawn on screen, using spman_alloc_fixed_sprite for sprites excluded from the flicker and spman_alloc_sprite for any other sprite.
- Update the sprites on screen with spman_update.

The allocate/update cycle needs to happen per frame, so the flicker function is effective. The longer between updates, the slower the flickering will be. If the game updates at least 25/30 FPS, that’s good enough for most games.

There are other functions to flush allocated sprites without updating the screen, or to hide all the sprites on screen.

The manager supports all 64 patterns and up to 31 visible sprites (one sprite is used by the flicker).

spman comes from “Sprite Pattern MANager”.

Initialization and pattern allocation

spman_alloc_pat

uint8_t spman_alloc_pat(uint8_t type, const uint8_t *data, uint8_t len, uint8_t flip);

Allocates a pattern for sprite type using data.

len specifies the number of sprite patterns to allocate (16x16 each, exactly 32 bytes).

If flip is set to a non zero value, the pattern data will be flipped horizontally.

The function returns the allocated index in the pattern table, than can be used in struct sprite_attr. It can be called multiple times for the same type and the allocation happens only once per type, returning the previously allocated index.

type is an abstraction to group patterns. For example, if our game’s player character has 3 animation frames per horizontal direction, we could use two different types to group those.

Example:

enum sprite_types
{
  SPRITE_PLAYER = 0,
  SPRITE_PLAYER_FLIP,
  SPRITE_ENEMY,
}:

spman_alloc_pat(SPRITE_PLAYER, player_sprite, 3, 0);
// allocate the same frames flipped horizontally, on the next type
spman_alloc_pat(SPRITE_PLAYER_FLIP, player_sprite, 3, 1);

// only one frame, keep the allocated pattern
uint8_t enemy_pat = spman_alloc_pat(SPRITE_ENEMY, enemy_sprite, 1, 0);

A type can’t be reused with a different pattern, spman_init has to be called again to free all the patterns.

spman_init

void spman_init(void);

Initialize spman.

Sets all the patterns as unused and no allocated sprites.

it needs to be called before using any of the functions of the sprite manager.

Sprite allocation

spman_alloc_fixed_sprite

void spman_alloc_fixed_sprite(const struct sprite_attr *sp);

Allocates a sprite described by sp to be shown on the screen on the next call to spman_update. This sprite will be excluded from flickering.

It is recommended that the number of fixed sprites per line is below 4, or some sprites may never be shown.

The limit of sprites to be allocated is 31, including non-fixed sprites.

The pattern specified in the struct should be allocated with spman_alloc_pat.

Allocated sprites are shown on screen by calling to spman_update.

spman_alloc_sprite

void spman_alloc_sprite(const struct sprite_attr *sp);

Allocates a sprite described by sp to be shown on the screen on the next call to spman_update.

If more than 4 sprites are drawn on the same line, the sprite manager will alternate which ones are drawn, resulting on a “flickering” effect.

The limit of sprites to be allocated is 31, including fixed sprites.

The pattern specified in the struct should be allocated with spman_alloc_pat.

Allocated sprites are shown on screen by calling to spman_update.

spman_sprite_flush

void spman_sprite_flush(void);

Any allocated sprite will be freed.

This doesn’t affect sprites currently being shown on the screen.

Sprites on screen

spman_hide_all_sprites

void spman_hide_all_sprites(void);

Hides all the sprites currently shown on screen.

This doesn’t affect any allocated sprites. To free allocated sprites use spman_sprite_flush.

spman_update

void spman_update(void);

Allocated sprites are processed, making the changes visible on screen.

Once the changes have been applied, all the allocations are freed. This doesn’t affect the sprites being shown on screen.

Sprites must be allocated with spman_alloc_fixed_sprite and spman_alloc_sprite.