mirror of
https://github.com/QB64Official/qb64.git
synced 2024-07-16 18:55:13 +00:00
41 lines
1.9 KiB
Markdown
41 lines
1.9 KiB
Markdown
The **_FREEIMAGE** statement releases the designated file image created by the [_LOADIMAGE](_LOADIMAGE), [_NEWIMAGE](_NEWIMAGE) or [_COPYIMAGE](_COPYIMAGE) functions from memory when they are no longer needed.
|
|
|
|
## Syntax
|
|
|
|
> [_FREEIMAGE](_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](ERROR-Codes) will occur.** Check the handle value first.
|
|
* **[SCREEN](SCREEN) modes in use cannot be freed or an [ERROR Codes](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](_FREEIMAGE).
|
|
* **Images are not deallocated when the [SUB](SUB) or [FUNCTION](FUNCTION) they are created in ends. Free them with [_FREEIMAGE](_FREEIMAGE).**
|
|
* **It is important to free unused or unneeded images with [_FREEIMAGE](_FREEIMAGE) to prevent memory overflow errors.**
|
|
* **Do not try to free image handles currently being used as the active [SCREEN](SCREEN). Change screen modes first.**
|
|
|
|
## Example(s)
|
|
|
|
Loading a program splash screen and freeing image when no longer necessary:
|
|
|
|
```vb
|
|
|
|
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](_LOADIMAGE) or the invalid handle memory value will not need to be freed.
|
|
|
|
## See Also
|
|
|
|
* [_NEWIMAGE](_NEWIMAGE)
|
|
* [_LOADIMAGE](_LOADIMAGE)
|
|
* [_SCREENIMAGE](_SCREENIMAGE)
|
|
* [_COPYIMAGE](_COPYIMAGE)
|