Sprite.c File Reference

Functions

bool TLN_ConfigSprite (int nsprite, TLN_Spriteset spriteset, TLN_TileFlags flags)
 Configures a sprite, setting setting spriteset and flags at once. More...
 
bool TLN_SetSpriteSet (int nsprite, TLN_Spriteset spriteset)
 Assigns the spriteset and its palette to a given sprite. More...
 
bool TLN_SetSpriteFlags (int nsprite, TLN_TileFlags flags)
 Sets flags for a given sprite. More...
 
bool TLN_SetSpritePosition (int nsprite, int x, int y)
 Sets the sprite position inside the viewport. More...
 
bool TLN_SetSpritePicture (int nsprite, int entry)
 Sets the actual graphic to the sprite. More...
 
bool TLN_SetSpritePalette (int nsprite, TLN_Palette palette)
 Assigns a palette to a sprite. More...
 
TLN_Palette TLN_GetSpritePalette (int nsprite)
 Gets the palette assigned to a given sprite. More...
 
bool TLN_SetSpriteBlendMode (int nsprite, TLN_Blend mode, uint8_t factor)
 Sets the blending mode (transparency effect) More...
 
bool TLN_SetSpriteScaling (int nsprite, float sx, float sy)
 Sets the scaling factor of the sprite. More...
 
bool TLN_ResetSpriteScaling (int nsprite)
 Disables scaling for a given sprite. More...
 
int TLN_GetSpritePicture (int nsprite)
 Returns the index of the assigned picture from the spriteset. More...
 
int TLN_GetAvailableSprite (void)
 Finds an available (unused) sprite. More...
 
TLNAPI bool TLN_EnableSpriteCollision (int nsprite, bool enable)
 Enable sprite collision checking at pixel level. More...
 
TLNAPI bool TLN_GetSpriteCollision (int nsprite)
 Gets the collision status of a given sprite. More...
 
bool TLN_DisableSprite (int nsprite)
 Disables the sprite so it is not drawn. More...
 

Detailed Description

Sprite control

Function Documentation

bool TLN_ConfigSprite ( int  nsprite,
TLN_Spriteset  spriteset,
TLN_TileFlags  flags 
)

Configures a sprite, setting setting spriteset and flags at once.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
spritesetReference of the spriteset containing the graphics to set
flagsCan be 0 or a combination of FLAG_FLIPX and FLAG_FLIPY
Remarks
This function also assigns the palette of the spriteset
See also
TLN_SetSpritePicture()
bool TLN_SetSpriteSet ( int  nsprite,
TLN_Spriteset  spriteset 
)

Assigns the spriteset and its palette to a given sprite.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
spritesetReference of the spriteset containing the graphics to set
Remarks
This function also assigns the palette of the spriteset
See also
TLN_SetSpritePicture()
bool TLN_SetSpriteFlags ( int  nsprite,
TLN_TileFlags  flags 
)

Sets flags for a given sprite.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
flagsCan be 0 or a combination of FLAG_FLIPX and FLAG_FLIPY
bool TLN_SetSpritePosition ( int  nsprite,
int  x,
int  y 
)

Sets the sprite position inside the viewport.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
xHorizontal position (0 = left margin)
yVertical position (0 = top margin)
Remarks
Call this function inside a raster callback to so some vertical distortion effects (fake scaling) or sprite multiplexing (reusing a single sprite at different screen heights). This technique was used by some 8 bit games, with very few hardware sprites, to draw much more sprites in the screen, as long as they don't overlap vertically
bool TLN_SetSpritePicture ( int  nsprite,
int  entry 
)

Sets the actual graphic to the sprite.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
entryIndex of the actual picture inside the srpteset to assign (0 <= entry < num_spriteset_graphics)

To show a sprite, at least two function calls are needed: first call TLN_ConfigSprite to assign the spriteset containing the graphics, and then call TLN_SetSpritePicture to assign the actual graphic. Usually all the frames for a given character are contained inside the same spriteset, so it is only needed to configure the sprite once at the beginning for a particular character, and then just reassign the graphic

See also
TLN_ConfigSprite(), TLN_SetSpriteSet(), TLN_SetSpritePictureByName()
bool TLN_SetSpritePalette ( int  nsprite,
TLN_Palette  palette 
)

Assigns a palette to a sprite.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
paletteReference of the palete to assign

Write detailed description for TLN_SetSpritePalette here.

Remarks
When a sprite is configured with a spriteset with the function TLN_ConfigSprite(), it automatically sets the palette of the assigned spriteset to the sprite. Use this function to override it and set another palette
TLN_Palette TLN_GetSpritePalette ( int  nsprite)

Gets the palette assigned to a given sprite.

Parameters
nspriteId of the sprite to query (0 <= id < max_sprites)
Returns
Reference to the sprite palette
See also
TLN_SetSpritePalette(), TLN_SetSpriteSet()
bool TLN_SetSpriteBlendMode ( int  nsprite,
TLN_Blend  mode,
uint8_t  factor 
)

Sets the blending mode (transparency effect)

Parameters
nspriteId of the sprite [0, num_sprites - 1]
modeMember of the TLN_Blend enumeration
factorDeprecated as of 1.12, left for backwards compatibility but doesn't have effect.
See also
Blending
bool TLN_SetSpriteScaling ( int  nsprite,
float  sx,
float  sy 
)

Sets the scaling factor of the sprite.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
sxHorizontal scale factor
syVertical scale factor

By default the scaling factor of a given sprite is 1.0f, 1.0f, which means no scaling. Use values below 1.0 to downscale (shrink) and above 1.0 to upscale (enlarge). Call TLN_ResetScaling() to disable scaling

Remarks
The rendering of a sprite with scaling enabled requires somewhat more CPU power than a regular sprite.
See also
TLN_ResetSpriteScaling()
bool TLN_ResetSpriteScaling ( int  nsprite)

Disables scaling for a given sprite.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
See also
TLN_SetSpriteScaling()
int TLN_GetSpritePicture ( int  nsprite)

Returns the index of the assigned picture from the spriteset.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
See also
TLN_SetSpritePicture()
int TLN_GetAvailableSprite ( void  )

Finds an available (unused) sprite.

Returns
Index of the first unused sprite (starting from 0) or -1 if none found
TLNAPI bool TLN_EnableSpriteCollision ( int  nsprite,
bool  enable 
)

Enable sprite collision checking at pixel level.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
enableSet true to enable o false to disable (default value)
Remarks
Only sprites that have collision enabled are checked between them, so to detect a collision between two sprites, both of them must have collision detection enabled. Processing collision detection sprites take more a bit more CPU time compared to non-colliding sprites, so by default it is disabled on all sprites.
See also
TLN_GetSpriteCollision()
TLNAPI bool TLN_GetSpriteCollision ( int  nsprite)

Gets the collision status of a given sprite.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
Returns
Tue if this sprite is involved in a collision with another sprite
Remarks
Collision detection must be enabled for the sprite to get checked
See also
TLN_EnableSpriteCollision()
bool TLN_DisableSprite ( int  nsprite)

Disables the sprite so it is not drawn.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
Remarks
A sprite is also automatically disabled when assigned with an invalid spriteste or palette. Disabled sprites are returned by the function TLN_GetAvailableSprite as available