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 number 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 (also combined with the '|' operator):

  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.
  #PB_Sprite_AlphaBlending: Sprite is created with per pixel alpha-channel support, the image format has to support it (only 
                            PNG and TIFF for now). The #PB_Sprite_Texture needs to be specified as well, and the sprite 
                            has to be displayed with DisplaySprite3D().

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