CatchSprite()

Syntax

Result = CatchSprite(#Sprite, MemoryAddress [, Mode])

Load the specified sprite from the given memory area. If #PB_Any is used as '#Sprite' parameter, the new sprite identifier will be returned as 'Result'. A screen should be opened with OpenScreen() or OpenWindowedScreen() before loading a sprite. If an error occurs the value 0 is returned. Sprites 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 catched sprite can be freed by using the FreeSprite() command. The 'CatchSprite' command is useful when using the 'IncludeBinary' PureBasic keyword. The images can be packed inside the executable. Nevertheless, use this option very carefully, as it will take more memory than storing the file in an external file (the file will be in both executable memory and loaded into physical memory). 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.

Example:

  CatchSprite(0, ?Pic)
  End

  Pic: IncludeBinary "Sprite.bmp"

Note: The "?" is a pointer to a label. More informations about pointers and memory access can be found in the relating chapter here.

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

All