_FREEIMAGE

The _FREEIMAGE statement releases the designated file image created by the _LOADIMAGE, _NEWIMAGE or _COPYIMAGE functions from memory when they are no longer needed.

Syntax

_FREEIMAGE [handle&]

Description

• If handle& is omitted, the current destination image is freed from memory.
• Freeing the destination image or source image will result in the display page being selected instead.
• Invalid image handle values of -1 or 0 cannot be freed or an ERROR Codes will occur. Check the handle value first.
• SCREEN modes in use cannot be freed or an ERROR Codes will occur. Change SCREEN modes before freeing.
• Once a specific image handle is no longer used or referenced by your program, it can be freed with _FREEIMAGE.
• Images are not deallocated when the SUB or FUNCTION they are created in ends. Free them with _FREEIMAGE.
• It is important to free unused or unneeded images with _FREEIMAGE to prevent memory overflow errors.
• Do not try to free image handles currently being used as the active SCREEN. Change screen modes first.

Example(s)

Loading a program splash screen and freeing image when no longer necessary:

s& = _LOADIMAGE("SPLASH.BMP",32)  'load 32 bit(24 BPP) image
IF s& < -1 THEN SCREEN s&   'use image as a 32 bit SCREEN 
_DELAY 6                          'display splash screen for 6 seconds
SCREEN 0       'MUST change screen mode before freeing a SCREEN image!
IF s& < -1 THEN _FREEIMAGE s&  'handle value MUST be less than -1 or error!
CLS 

Note: A valid image file name must be used by _LOADIMAGE or the invalid handle memory value will not need to be freed.

See Also

• _NEWIMAGE
• _LOADIMAGE
• _SCREENIMAGE
• _COPYIMAGE