Blitz3D+ Command Reference

SaveImage ( image,bmpfile$[,frame] )

Parameters

image - handle of the image to save

bmpfile$ - path of the file to write

frame (optional) - frame of an animated image to save; 0 (default)

Description

Writes one frame of an image to a file. Returns True on success, False if the file could not be written.

Useful for saving out things your program made rather than loaded: a procedurally generated tile set, a level map you drew into an image, a player-created sprite from a paint tool, or a debug dump of a render target you cannot otherwise inspect.

The file is always written as an uncompressed 24-bit Windows BMP, whatever extension you give it - naming it .png will not produce a PNG, just a BMP with a misleading name. Uncompressed and 24-bit also means large files and no alpha channel, so this is a tool for development and for data your program will read back, not a way to ship artwork.

Only one frame is written per call. To save a whole animation strip, loop over the frames and write a numbered file for each.

It returns False if the path is bad or the file cannot be opened - worth checking, since a failed save is silent otherwise.

See also: SaveBuffer, LoadImage, GrabImage, CreateImage.

Example

; SaveImage Example
; -----------------

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

; Paint a badge sprite into an image so we have something to save
badge=CreateImage(64,64)
SetBuffer ImageBuffer(badge)
Color 255,128,0
Oval 2,2,60,60,True
Color 255,255,255
Oval 16,16,32,32,True
SetBuffer BackBuffer()

saved=-1

While Not KeyDown(1)

    Cls

    DrawImage badge,288,180

    ; S saves the image as a BMP file next to this example
    If KeyHit(31) Then saved=SaveImage(badge,"saveimage_demo.bmp")

    Text 0,0,"S: save the badge to disk   Esc: exit"
    If saved=1 Then
        Text 0,20,"SaveImage returned 1 - wrote saveimage_demo.bmp"
    ElseIf saved=0 Then
        Text 0,20,"SaveImage returned 0 - the file could not be written"
    Else
        Text 0,20,"Press S to call SaveImage(badge,saveimage_demo.bmp)"
    End If

    Flip

Wend

End

Index