FREEIMAGE: Difference between revisions
Jump to navigation
Jump to search
Navigation:
Main Page with Articles and Tutorials
Keyword Reference - Alphabetical
Keyword Reference - By usage
Report a broken link
No edit summary |
No edit summary |
||
| (5 intermediate revisions by 2 users not shown) | |||
| Line 11: | Line 11: | ||
*Freeing the destination image or source image will result in the display page being selected instead. | *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|"Illegal Function" error]] will occur.''' Check the handle value first. | *'''Invalid image handle values of -1 or 0 cannot be freed or an [[ERROR Codes|"Illegal Function" error]] will occur.''' Check the handle value first. | ||
* '''[[SCREEN]] modes in use cannot be freed or an [[ERROR Codes|"Illegal Function" error]] will occur.''' Change SCREEN modes before freeing. | * '''[[SCREEN]] modes in use cannot be freed or an [[ERROR Codes|"Illegal Function" error]] 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]]. | *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]].''' | * '''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.''' | * '''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.''' | * '''Do not try to free image handles currently being used as the active [[SCREEN]]. Change screen modes first.''' | ||
* '''Note that calling _FREEIMAGE only frees the handle. It does NOT reset the variable used to store the handle back to 0. (This is because 0 is often used as a short cut value for the current display, such as with _DEST 0.)''' | |||
{{PageExamples}} | {{PageExamples}} | ||
''Example:'' Loading a program splash screen and freeing image when no longer necessary: | ''Example:'' Loading a program splash screen and freeing image when no longer necessary: | ||
{{CodeStart}} | {{CodeStart}} | ||
s& = {{Cl|_LOADIMAGE}}("SPLASH.BMP",32) | s& = {{Cl|_LOADIMAGE}}({{Text|<nowiki>"SPLASH.BMP"</nowiki>|#FFB100}}, {{Text|32|#F580B1}}) {{Text|<nowiki>'load 32 bit(24 BPP) image</nowiki>|#919191}} | ||
{{Cl|IF}} s& < -1 THEN {{Cl | {{Cl|IF}} s& < {{Text|-1|#F580B1}} {{Cl|THEN}} {{Cl|SCREEN}} s& {{Text|<nowiki>'use image as a 32 bit SCREEN</nowiki>|#919191}} | ||
{{Cl|_DELAY}} 6 | {{Cl|_DELAY}} {{Text|6|#F580B1}} {{Text|<nowiki>'display splash screen for 6 seconds</nowiki>|#919191}} | ||
{{Cl|SCREEN | {{Cl|SCREEN}} {{Text|0|#F580B1}} {{Text|<nowiki>'MUST change screen mode before freeing a SCREEN image!</nowiki>|#919191}} | ||
{{Cl|IF}} s& < -1 THEN {{Cl|_FREEIMAGE}} s& | {{Cl|IF}} s& < {{Text|-1|#F580B1}} {{Cl|THEN}} {{Cl|_FREEIMAGE}} s& {{Text|<nowiki>'handle value MUST be less than -1 or error!</nowiki>|#919191}} | ||
{{Cl|CLS}} | {{Cl|CLS}} | ||
{{CodeEnd}} | {{CodeEnd}} | ||
: ''Note:'' A valid image file name must be used by [[_LOADIMAGE]] or the invalid handle memory value will not need to be freed. | : ''Note:'' A valid image file name must be used by [[_LOADIMAGE]] or the invalid handle memory value will not need to be freed. | ||
| Line 36: | Line 36: | ||
* [[_SCREENIMAGE]] | * [[_SCREENIMAGE]] | ||
* [[_COPYIMAGE]] | * [[_COPYIMAGE]] | ||
* [[_SAVEIMAGE]] | |||
{{PageNavigation}} | {{PageNavigation}} | ||
Latest revision as of 08:21, 10 January 2024
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 "Illegal Function" error will occur. Check the handle value first.
- SCREEN modes in use cannot be freed or an "Illegal Function" error 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.
- Note that calling _FREEIMAGE only frees the handle. It does NOT reset the variable used to store the handle back to 0. (This is because 0 is often used as a short cut value for the current display, such as with _DEST 0.)
Examples
Example: 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