CatchImage()

Syntax

Result = CatchImage(#Image, *MemoryAddress [, Size])

Load the specified image from the given memory area.

Parameters

#Image	A number to identify the loaded image. #PB_Any can be specified to auto-generate this number.
*MemoryAddress	The memory address from which to load the image.
Size (optional)	The size of the image in bytes. The size is optional as the loader can determine from the image when to stop reading. It is however advisable to provide a size when loading unknown images, as the loader can then handle corrupted images correctly (without specifying the image size, a corrupt image can crash the program).

Return value

Returns nonzero if the image was loaded successfully and zero if the image could not be loaded. If #PB_Any was specified as the #Image parameter then the auto-generated number is returned on success.

Remarks

The limit for the image size that can be handled depends on the operating system and the available amount of memory. If enough memory is available, then images up to at least 8192x8192 pixel can be handled by all operating systems supported by PureBasic.

When an image is loaded, it is converted either in 24-bit (if the image depth is less or equal to 24-bit) or in 32-bit (if the image has an alpha-channel). A loaded image can be freed by using the FreeImage() function.

This function is useful when using the 'IncludeBinary' PureBasic keyword. Then images can be packed inside the executable. Nevertheless, use this option with care, as it will take more memory than storing the file in an external file (the file are both in executable memory and load in physical memory).

The image can be in BMP, icon (.ico, only on Windows) or any other format supported by the ImagePlugin library. The following functions can be used to enable automatically more image formats:

UseJPEGImageDecoder()
UseJPEG2000ImageDecoder()
UsePNGImageDecoder()
UseTIFFImageDecoder()
UseTGAImageDecoder()
UseGIFImageDecoder()

Example

  CatchImage(0, ?Logo)
  End

  DataSection
    Logo: 
      IncludeBinary "Logo.bmp"
  EndDataSection

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

See Also

CreateImage(), LoadImage(), FreeImage(), ImagePlugin library

Supported OS

All