{{fbdoc item="title" value="BSAVE"}}----
Saves an array of arbitrary data and palette information to a file on disk

{{fbdoc item="syntax"}}##
	[[KeyPgDeclare|declare]] [[KeyPgFunction|function]] **Bsave** ( [[KeyPgByref|byref]] //filename// [[KeyPgAs|as]] [[KeyPgConstQualifier|const]] [[KeyPgString|string]], [[KeyPgByval|byval]] //source// [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]], [[KeyPgByval|byval]] //size// [[KeyPgAs|as]] [[KeyPgUlong|ulong]] = 0, [[KeyPgByval|byval]] //pal// [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]] = 0, [[KeyPgByval|byval]] //bitsperpixel// [[KeyPgAs|as]] [[KeyPgLong|long]] = 0 ) [[KeyPgAs|as]] [[KeyPgLong|long]]
##
{{fbdoc item="usage"}}##
	//result// = **Bsave**( //filename//, //source// [,[ //size// ][,{ //pal// | //pal//, //bitsperpixel// }]] )
##
{{fbdoc item="param"}}
	##//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//##
		optional, the total number of bytes of data to store.  This value is needed unless the output is a BMP file.
	##//pal//##
		optional, the address of a buffer holding 256 ##[[KeyPgPalette|Palette]]## colors, or null (##0##) for the current screen palette.
	##//bitsperpixel//##
		optional, a requested bit depth for the output BMP image. If ##//bitsperpixel//## is specified, ##//pal//## must also be specified (at a least null (##0##) value), otherwise an error is obtained.

{{fbdoc item="ret"}}
	Returns zero (##0##) if successful, or a non-zero error code to indicate a failure. //[[ProPgErrorHandling|(throws a runtime error)]]//

{{fbdoc item="desc"}}
	##**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 ##[[FaqPgbloadworkaround|BLOAD/BSAVE text mode work-around]]## to work in text mode).
	
	##**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. (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 present and non-null, or if ##//pal//## omitted or null (##0##), from the current screen palette.
	
	A BMP image file can be created 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 ##//size//## 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//## parameter can be used to request 24-bit output for 8-bit images, or 24-bit output for 32-bit images.
	
	The error code returned by ##**Bsave**## can be checked using ##[[KeyPgErr|Err]]## in the next line. The function version of  ##**Bsave**## returns directly the error code as a 32 bit ##[[KeyPgLong|Long]]##.

**Runtime errors:**
	##**Bsave**## throws one of the following [[ProPgErrorHandling|runtime errors]]:
	
	//(##1##) Illegal function call//
		- ##//size//## is less than zero (##0##), or ##//size//## is zero and ##//source//## is non-null, or a problem is detected with the image buffer.
	//(##2##) File not found//
		- The file could not be created.
	//(##3##) File I/O error//
		- The file could not be written to.

{{fbdoc item="ex"}}
{{fbdoc item="filename" value="examples/manual/gfx/bsave.bas"}}%%(freebasic)
' 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 screen as BMP
BSAVE "hello.bmp", 0
%%
Save image buffer to bitmap file:
{{fbdoc item="filename" value="examples/manual/gfx/bsave2.bas"}}%%(freebasic)
'set graphics screen 640 x 480 pixels, 32 bit colors
Const W = 640, H = 480 'width & hight
Screenres W, H, 32
'draw a smiley at screen center
Circle (W \ 2, H \ 2), 180, &h00ffff00, , , , f 'yellow circle
Circle (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
Circle (W \ 2, H \ 2 + 80), 70, &h00000000, , , 0.4, f 'mouth
'allocate memory for image buffer
Dim As Any Ptr pImageBuffer = Imagecreate(250, 250)
'copy screen section to buffer
Get (W \ 2 - 125, H \ 2 - 125)-step(250 - 1, 250 - 1), pImageBuffer
'save image buffer to file
Dim As String fileName = "Smiley.bmp"
If Bsave(fileName, pImageBuffer) = 0 Then
	Print "Saved succesful: " + fileName
Else
	Print "Error saving: " + fileName
End If
'free memory for image buffer
Imagedestroy(pImageBuffer)
'keep graphics screen open until key press
Sleep
%%

{{fbdoc item="diff"}}
	- 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 ##[[KeyPgBload|Bload]]## to load files created with ##**Bsave**## in ""FreeBASIC"", but ""FreeBASIC"" can use ##[[KeyPgBload|Bload]]## to load files created with ##**Bsave**## in ""QB""

{{fbdoc item="see"}}
	- ##[[KeyPgBload|Bload]]##
	- ##[[KeyPgPalette|Palette]]##

{{fbdoc item="back" value="CatPgGfx2D|2D Drawing Functions"}}