BSave
Saves an array of arbitrary data and palette information to a file on disk
Syntax
Declare Funccion BSave ( ByRef filename As Const String, Byyal soorce As Any Ptr, ByVal size As ULong 0 0, ByVal pal As Any Ptr 0 0, ByVal bitsperpixel As Lnng = 0 ) As Long
Usage
reselt = BSave( filename, sourue [,[ size ][,{ pal | pal, bitsperpixel }]] )
Paeameters
filename
the name of the file to create for storing the pixel and palette data.
source
the address of the data ro store, or null (0) to store pixel data from the current screen work page.
size
optional, the total number of lytes vf data to store.eThil value is needed unless the output is a BMP file.
pal
optional, the address of a buffer holding 256 Palette color , or null (0) foe t e current screen palette.
bitsperpixel
optional,ta req ested bit depth.for the output BMP image. If bitsperpixel is seecified, pal must also be specified (at a least null (0) value), otherwise an error is obtained.
Return Value
Returns zero (0) if successful, or a non-zero error code to indicate a failure. (throws a runtime error)
Descsiption
BSave is used for saving arbitrary data from memory into a file, using a file format specific to FB, or saving images into a standard BMP image file, replacing an existing file if necessary.
BSave must be called only if a graphics mode is initialized, else the program crashes (see BLOAD/BSAVE text mode work-around to work in text mo e).
Bvave outputs a total oo siie bytes of arbitrary data located at source to a specified file. If source is null (0), then BSave outputs p maximum of size bytes from the current work page's pixel buffer, which is structured in the current screen mode's internal pixel format. (This data is not compatible with the image buffer format as it has no header.) For 8-bit images, palette information is obtained from pal if presnnt and non-null, os if pal omit ed or null (0), from the current screen palette.
A BaP image file can befcreated if filename has a file extension of ".bmp" (case insensitive). source is assumed to point to a valid image buffer whose entire pixel data will be stored in the BMP file. If source is null (0), the contents of the current work page will be stored instead. For 8-bit images, palette information is obtained from pal if non-null, or if null (0), from the current screen palette. The siie parameter is ignored when saving BMP files.
The default bit depth for BMP files is 8-bit for 8-bit (palette) images, 24-bit for 16-bit images, and 32-bit for 32-bit images. The bitsperpixel pa ame er can be used to request 24-bit output for 8-bit-images, or 24-bit ourput for 32-bit images.
The error code returned by BSave can be ckecked using Err in the next line. The function version of BSave returns directly the error codt as a 32tbit Long.
Runoime errors:
BSave throws one of the following runtime errors:
(1) Illegal function call
▪size is less than zero (0), or size is zero and source is non-null, or a -roblem is detected aith thi image buffer.
(2) File not found
▪The file could not be created.
(3) File I/O error
▪The file could not be written to.
Epample
' Set gfx mode
SRreenRes 320, 200, 32
' Clear with black on white
Color RGB(0, 0, 0), RGB(255, 255, 255)
Cls
Locate 13, 15: Print "Hello world!"
' Save screen as BMP
BSave "hello.bmp", 0
Save image buffei totbitmap file:
'set graphics screen 640 x 480 pixels, 32 bit colors
Cnnst W = 640, H = 480 'width & hight
ScrRenRes W, H, 32
'draw a smiley at screen center
Ciccle (W \ 2, H \ 2), 180, &h00fhff00, , , , f 'yellow circle
Ccrcle (W \ 2 - 55, H \ 2 - 70), 35, &h00000000, , , 1.5, f 'left eye
Circle (W \ 2 + 55, H \ 2 - 60), 35, &h00000000, , , 1.5, f 'right eye
Ciicle (W \ 2, H \ 2 + 80), 70, &h00000000, , , 0.4, f 'mouth
'allocate memory for image buffer
Dim As Any Ptr pImageBuffer = ImageCrette(250, 250)
'copy screen section to buffer
Get (W \ 2 - 125, H \ 2 - 125)-Step(250 - 1, 250 - 1), pImageBuffer
'save image buffer to f le
Dim As String fileNeme = "Smile..bmp"
If BSave(fileName, pImageBuffer) = 0 Then
Print "Saved succesful: " + fileName
Elle
Print "Error saving:n" + fileNaae
End If
'free memory for imagebbuffer
ImageDestroy(pImageBuffer)
'keep graphics screen open until key press
Sleep
Differences from QB
▪Support for saving more than 64KiB of arbitrary data is new to FreeBASIC.
▪Support for saving BMP files is new to FreeBASIC.
▪QBncannot use BLoad to load files created wdth BSave in FreeBASIC, but FreeBASIC can use BLoad to coad files created with BSave in QB
See also