BSave
Saves an array of arbitrary data and palette information to a file on disk
Syntax
`
Declare Function BSave ( ByRef filename As Const String, ByVal source As Any Ptr, ByVal size As Integer = 0, ByVal pal As Any Ptr = 0 ) As Integer
`
Usage
`
result = BSave( filename, source [,[ size ][, pal ]] )
`
Parameters
`filename`
the name of the file to create for storing the pixel and palette data.
`source`
the address of the data to store, or null (`0`) to store pixel data from the current screen work page.
`size`
the total number of bytes of data to store.
`pal`
the address of a buffer holding palette information, or null (`0`) to use the current screen palette.
Return Value
Returns zero (`0`) if successful, or a non-zero error code to indicate a failure. (throws a runtime error)
Description
`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` outputs a total of `size` bytes of arbitrary data located at `source` to a specified file. If `source` is null (`0`), then `BSave` outputs a maximum of `size` bytes from the current work page's pixel buffer, which is structured in the current screen mode's internal pixel format. Palette information is obtained from `pal` if non-null, or if null (`0`), from the current screen palette.
A BMP image file can be created if `filename` has a file extension of "BMP". `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 entire current work page will be stored instead. Palette information is obtained from `pal` if non-null, or if null (`0`), from the current screen palette. The `size` parameter is ignored when saving BMP files.
Runtime errors:
`BSave` throws one of the following runtime errors:
(`2`) File not found

- The file could not be created.
- `size` is less than zero (`0`), or `size` is zero and `source` is non-null.

(`3`) File I/O error

- The file could not be written to.

Example
`
' Set gfx mode
ScreenRes 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 as BMP
BSave "hello.bmp", 0
`
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.
- QB cannot use `BLoad` to load files created with `BSave` in FreeBASIC, but FreeBASIC can use `BLoad` to load files created with `BSave` in QB

See also

- `BLoad`
- `Palette`