Syntax

Result = LoadSprite(#Sprite, FileName$ [, Mode])

Load the specified sprite into memory for immediate use. If #PB_Any is used as '#Sprite' parameter, the new sprite identifier will be returned as 'Result'.

The sprite can be in BMP format (1 bit, 4 bits, 8 bits, 16 bits, 24 bits or 32 bits color depth, in uncompressed (non RLE) form) or any other format supported by the ImagePlugin library.

A screen should be opened with OpenScreen() or OpenWindowedScreen() before loading a sprite.

If an error occurs the value 0 is returned, otherwise the sprite was loaded successfully. A loaded sprite can be freed by using the FreeSprite() command. The following commands can be used to enable automatically more image formats:

UseJPEGImageDecoder()
UsePNGImageDecoder()
UseTIFFImageDecoder()
UseTGAImageDecoder()

The 'Mode' parameter is optional and can take the following values:

  0                 : Default mode. Sprite resides in video memory (if possible)
  #PB_Sprite_Memory : Sprite is loaded into main PC memory (for SpecialFX)
  #PB_Sprite_Alpha  : Sprite is 8 bits grayscale and will be used by DisplayAlphaSprite() or DisplayShadowSprite()
  #PB_Sprite_Texture: Sprite is created with 3D support - useful for the CreateSprite3D() command of the Sprite3D library.

Note: Sprites shouldn't be larger than the used screenmode. Using larger sprites possibly works on some hardware, on others not. Better split your large sprite to several smaller ones.

When using 8 bits screenmode (256 colors, palettized), only 8bits BMP are accepted as sprite format. The ImagePlugins or other BMP color formats aren't supported.

Supported OS

Windows, AmigaOS, Linux