Blitz3D+ Command Reference

FreeImage image

Parameters

image - handle of the image to delete

Description

Deletes an image and releases the memory it was using.

Free art you have finished with - the images for a level you have just left, a title screen you will not show again, the scratch surfaces you built an effect out of - and your game keeps working on machines with less memory than yours. Images are usually the biggest thing a 2D game holds, so this is worth being tidy about.

Freeing does not clear your variable. The handle you were holding still contains the old number but no longer refers to anything, and using it in DrawImage or any other image command is an error. Set the variable to 0 right after freeing and you get a cheap "have I loaded this yet?" test for free. Any other variable that happened to hold the same handle is stale too, and a handle from CopyImage is a separate image that needs its own FreeImage.

You do not have to free everything before your program ends - that happens automatically - and changing mode with Graphics invalidates image handles anyway, so reload rather than reuse across a mode change.

See also: LoadImage, CreateImage, CopyImage, SaveImage.

Example

; FreeImage Example
; -----------------

Graphics 640,480,0,2
SetBuffer BackBuffer()

player=LoadImage("media/player.bmp")

While Not KeyDown(1)

    Cls

    ; Space frees the image; zero the handle so we know it is gone
    If KeyHit(57) And player<>0 Then
        FreeImage player
        player=0
    End If

    ; L loads the ship again after it has been freed
    If KeyHit(38) And player=0 Then player=LoadImage("media/player.bmp")

    ; Only draw the image while its handle is valid
    If player<>0 Then DrawImage player,MouseX(),MouseY()

    Text 0,0,"Space: FreeImage   L: reload   Esc: exit"
    If player<>0 Then
        Text 0,20,"Image handle: "+player+" - move the mouse to fly the ship"
    Else
        Text 0,20,"FreeImage called - the image memory has been released"
    End If

    Flip

Wend

End

Index