2.9.4
Functions
Sprite

Sprites management. More...

Description

Sprites management.

Functions

bool TLN_ConfigSprite (int nsprite, TLN_Spriteset spriteset, uint32_t flags)
 Configures a sprite, 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, uint32_t flags)
 Sets flags for a given sprite. More...
 
bool TLN_EnableSpriteFlag (int nsprite, uint32_t flag, bool enable)
 Enables or disables specified flag for a sprite. More...
 
bool TLN_SetSpritePivot (int nsprite, float px, float py)
 Sets sprite pivot point. By default is at (0,0) = top left corner. More...
 
bool TLN_SetSpritePosition (int nsprite, int x, int y)
 Sets the sprite position in screen space. 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...
 
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...
 
bool TLN_EnableSpriteCollision (int nsprite, bool enable)
 Enable sprite collision checking at pixel level. More...
 
bool TLN_GetSpriteCollision (int nsprite)
 Gets the collision status of a given sprite. More...
 
bool TLN_GetSpriteState (int nsprite, TLN_SpriteState *state)
 Returns runtime info about a given sprite. More...
 
bool TLN_SetFirstSprite (int nsprite)
 Sets the first sprite drawn (beginning of list) More...
 
bool TLN_SetNextSprite (int nsprite, int next)
 Sets the next sprite to draw after a given sprite, builds list. More...
 
bool TLN_EnableSpriteMasking (int nsprite, bool enable)
 Enables or disables masking for this sprite, if enabled it won't be drawn inside the region set up with TLN_SetSpritesMaskRegion() More...
 
void TLN_SetSpritesMaskRegion (int top_line, int bottom_line)
 Defines a sprite masking region between the two scanlines. Sprites masked with TLN_EnableSpriteMasking() won't be drawn inside this region. More...
 
bool TLN_SetSpriteAnimation (int nsprite, TLN_Sequence sequence, int loop)
 Starts a sprite animation. More...
 
bool TLN_DisableSpriteAnimation (int nsprite)
 Disables animation for the given sprite. More...
 
bool TLN_DisableSprite (int nsprite)
 Disables the sprite so it is not drawn. More...
 
TLN_Palette TLN_GetSpritePalette (int nsprite)
 Gets the palette assigned to a given sprite. More...
 

Function Documentation

◆ TLN_ConfigSprite()

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

Configures a sprite, setting spriteset and flags at once.

Deprecated:
use TLN_SetSpriteSet and TLN_EnableSpriteFlag
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()

◆ TLN_SetSpriteSet()

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 and resets pivot to top left corner (default)
See also
TLN_SetSpritePicture()

◆ TLN_SetSpriteFlags()

bool TLN_SetSpriteFlags ( int  nsprite,
uint32_t  flags 
)

Sets flags for a given sprite.

Deprecated:
Use TLN_EnableSpriteFlag to enable or disable individual flags
Parameters
nspriteId of the sprite [0, num_sprites - 1]
flagsCan be 0 or a combination of TLN_TileFlags

◆ TLN_EnableSpriteFlag()

bool TLN_EnableSpriteFlag ( int  nsprite,
uint32_t  flag,
bool  enable 
)

Enables or disables specified flag for a sprite.

Parameters
nspriteof the sprite [0, num_sprites - 1]
flagflag (or combination of flags) to modfy
enabletrue for enable, false for disable

◆ TLN_SetSpritePivot()

bool TLN_SetSpritePivot ( int  nsprite,
float  px,
float  py 
)

Sets sprite pivot point. By default is at (0,0) = top left corner.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
pxhorizontal normalized value (0.0 = full left, 1.0 = full right)
pyvertical normalized value (0.0 = full top, 1.0 = full bottom)
Remarks
Sprite pivot is reset automatically to default position after changing the spriteset

◆ TLN_SetSpritePosition()

bool TLN_SetSpritePosition ( int  nsprite,
int  x,
int  y 
)

Sets the sprite position in screen space.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
xHorizontal position of pivot (0 = left margin)
yVertical position of pivot (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
See also
TLN_SetSpritePivot

◆ TLN_SetSpritePicture()

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)
See also
TLN_SetSpriteSet()

◆ TLN_SetSpritePalette()

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

◆ TLN_SetSpriteBlendMode()

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

◆ TLN_SetSpriteScaling()

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()

◆ 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()

◆ TLN_GetSpritePicture()

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()

◆ TLN_GetAvailableSprite()

int TLN_GetAvailableSprite ( void  )

Finds an available (unused) sprite.

Returns
Index of the first unused sprite (starting from 0) or -1 if none found

◆ TLN_EnableSpriteCollision()

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()

◆ TLN_GetSpriteCollision()

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()

◆ TLN_GetSpriteState()

bool TLN_GetSpriteState ( int  nsprite,
TLN_SpriteState state 
)

Returns runtime info about a given sprite.

Parameters
nspriteId of the sprite [0, num_sprites - 1]
statePointer to a user-allocated TLN_SpriteState structure to fill with requested data

◆ TLN_SetFirstSprite()

bool TLN_SetFirstSprite ( int  nsprite)

Sets the first sprite drawn (beginning of list)

Parameters
nspriteId of the sprite [0, num_sprites - 1]. Must be enabled (visible)

◆ TLN_SetNextSprite()

bool TLN_SetNextSprite ( int  nsprite,
int  next 
)

Sets the next sprite to draw after a given sprite, builds list.

Parameters
nspriteId of the sprite [0, num_sprites - 1]. Must be enabled (visible)
nextId of the sprite to draw after Id [0, num_sprites - 1]. Must be enabled (visible)

◆ TLN_EnableSpriteMasking()

bool TLN_EnableSpriteMasking ( int  nsprite,
bool  enable 
)

Enables or disables masking for this sprite, if enabled it won't be drawn inside the region set up with TLN_SetSpritesMaskRegion()

Deprecated:
, use TLN_EnableSpriteFlag (nsprite, FLAG_MASKED, enable)
Parameters
nspriteId of the sprite to mask [0, num_sprites - 1].
enableEnables (true) or disables (false) masking

◆ TLN_SetSpritesMaskRegion()

void TLN_SetSpritesMaskRegion ( int  top_line,
int  bottom_line 
)

Defines a sprite masking region between the two scanlines. Sprites masked with TLN_EnableSpriteMasking() won't be drawn inside this region.

Parameters
top_lineTop scaline where masking starts
bottom_lineBottom scaline where masking ends

◆ TLN_SetSpriteAnimation()

bool TLN_SetSpriteAnimation ( int  nsprite,
TLN_Sequence  sequence,
int  loop 
)

Starts a sprite animation.

Parameters
nspriteIf of the sprite to animate (0 <= id < num_sprites)
sequenceReference of the sequence to assign
loopamount of times to loop, 0=infinite
See also
Animations

◆ TLN_DisableSpriteAnimation()

bool TLN_DisableSpriteAnimation ( int  index)

Disables animation for the given sprite.

Parameters
indexId of the spriteto set (0 <= id < num_sprites)
See also
Animations

◆ TLN_DisableSprite()

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

◆ TLN_GetSpritePalette()

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()