{{fbdoc item="title" value="BLOAD"}}----
Loads arbitrary data from a file created with ##[[KeyPgBsave|Bsave]]##, or a compatible BMP image file.

{{fbdoc item="syntax"}}##
	[[KeyPgDeclare|declare]] [[KeyPgFunction|function]] **Bload** ( [[KeyPgByref|byref]] //filename// [[KeyPgAs|as]] [[KeyPgConstQualifier|const]] [[KeyPgString|string]], [[KeyPgByval|byval]] //dest// [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]] = 0, [[KeyPgByval|byval]] //pal// [[KeyPgAs|as]] [[KeyPgAny|any]] [[KeyPgPtr|ptr]] = 0 ) [[KeyPgAs|as]] [[KeyPgLong|long]]
##
{{fbdoc item="usage"}}##
	//result// = **Bload**( //filename// [, [ //dest// ] [, //pal// ] ] )
##
{{fbdoc item="param"}}
	##//filename//##
		the name of the file to load the image from; can include a file path
	##//dest//##
		the memory location to load the image to, or null (##0##) to copy the image to the current graphics screen work page
	##//pal//##
		the memory location to load the palette to, or null (##0##) to change the current graphics screen palette, if it uses one

{{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"}}
	##**Bload**## can be used to load image data or any other data from a file created with ##[[KeyPgBsave|Bsave]]##, and store that data in an array or paste it to the screen. If ##//dest//## is absent or null (##0##), the image data is pasted to the current graphics screen work page.  Otherwise it is loaded as image data to the address given by ##//dest//##.
	##**Bload**## 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).
	
	##**Bload**## can load 3 different types of files:
		- Old QB-like data files, saved with ##BSAVE## from QB code, containing "raw" data preceded by a 7-byte header, beginning with ##&HFD##, up to 64 ""KiB"" in size
		- New FB-like data files, saved with ##[[KeyPgBsave|Bsave]]## from FB code, containing "raw" data preceded by a 5-byte header, beginning with ##&HFE##. There is no 64 ""KiB"" limit with this format
		- BMP image files, supports a subset of valid ("Windows") .BMP files, beginning with ##"BM"##, saved from FB code with ##[[KeyPgBsave|Bsave]]##, or created / saved in a compatible format using a graphics editor / converter.
	QB-like data files and BMP files are converted to an FB-compatible image format when opened.
	
	Image files with 8-bit per pixel resolution or lower contain a palette that describes the color values used in the images. If ##//pal//## is not null (##0##), the palette is copied to memory starting at the address specified. Otherwise, if the current graphics screen uses a palette then its palette is changed to match that of the image file.
	
	When using one of the 2 "non-BMP" file formats to save images, the image files must have been created with ##[[KeyPgBsave|Bsave]]## in the same graphics screen mode as it is being loaded into. When using the BMP file format, this restriction doesn't apply. 
	
	When loading a BMP file using ##**Bload**##,  the images must be true-color (15-, 16-, 24- or 32-bits per pixel) or palettized/indexed (8-bit or lower). The image data will be converted to the proper pixel format for the current color depth, except that true-color can't be reduced to a palettized image. ##**Bload**## doesn't support BMP files using RLE compression or other image file types (PNG, JPG, GIF, ...).  ##**Bload**## will load alpha channel information, if available, from 32-bit BMP files with ##BITMAPV4HEADER## or ##BITMAPV5HEADER## file headers.
	
	The error code returned by ##**Bload**## can be checked using ##[[KeyPgErr|Err]]## in the next line. The function version of  ##**Bload**## returns directly the error code as a 32 bit ##[[KeyPgLong|Long]]##.

**Runtime errors:**
	##**Bload**## throws one of the following [[ProPgErrorHandling|runtime errors]]:
		//(##1##) Illegal function call//
			- ##//dest//## was not specified or was null (##0##), and no graphics screen was set.
			- The Bitmap uses an unsupported BMP file compression type (##BI_RLE4##, ##BI_RLE8##)
			- The Bitmap is true-color (16, 24, or 32 bits per pixel) and the current graphics screen uses a palette (8 bits per pixel or lower).
		//(##2##) File not found//
			- The file ##//filename//## could not be found.
		//(##3##) File I/O error//
			- The file doesn't have any of the supported types 
			- A general read error occurred.
			
~&//Note: When you use ##**BLoad**## to load a BMP file into an image buffer, the original dimensions of the image are not changed.  If you want the image buffer to have the same dimensions as the BMP file, you have to find out the dimensions beforehand, and create an image of the right size yourself.  See {{anchor name="bmp_load|the example below"}} for an example of how to do this.//

{{fbdoc item="ex"}}
	{{fbdoc item="filename" value="examples/manual/gfx/bload.bas"}}%%(freebasic)
'Load a graphic to current work page
SCREEN 18, 32
cls
bload "picture.bmp"
sleep
%%
	{{fbdoc item="filename" value="examples/manual/gfx/bload2.bas"}}%%(freebasic)
'Load a 48x48 bitmap into an image
screenres 320, 200, 32
dim myImage as any ptr = imagecreate( 48, 48 )
bload "picture.bmp", myImage
put (10,10), myImage
imagedestroy( myImage )
sleep
%%
	{{fbdoc item="filename" value="examples/manual/gfx/bload3.bas"}}%%(freebasic)
screenres 640, 480, 8 '' 8-bit palette graphics mode
dim pal(0 to 256-1) as integer '' 32-bit integer array with room for 256 colors

'' load bitmap to screen, put palette into pal() array
bload "picture.bmp", , @pal(0)

windowtitle "Old palette"
sleep

'' set new palette from pal() array
palette using pal(0)

windowtitle "New palette"
sleep
%%
{{anchor name="bmp_load"}}
	{{fbdoc item="filename" value="examples/manual/gfx/bload4.bas"}}%%(freebasic)
'' A function that creates an image buffer with the same 
'' dimensions as a BMP image, and loads a file into it.

const NULL as any ptr = 0

function bmp_load( byref filename as const string ) as any ptr

	dim as long filenum, bmpwidth, bmpheight
	dim as any ptr img

	'' open BMP file
	filenum = freefile()
	if open( filename for binary access read as #filenum ) <> 0 then return NULL

		'' retrieve BMP dimensions
		get #filenum, 19, bmpwidth
		get #filenum, 23, bmpheight

	close #filenum

	'' create image with BMP dimensions
	img = imagecreate( bmpwidth, abs(bmpheight) )

	if img = NULL then return NULL

	'' load BMP file into image buffer
	if bload( filename, img ) <> 0 then imagedestroy( img ): return NULL

	return img

end function



dim as any ptr img

screenres 640, 480, 32

img = bmp_load( "picture.bmp" )

if img = NULL then
	print "bmp_load failed"

else

	put (10, 10), img

	imagedestroy( img )

end if

sleep
%%
{{fbdoc item="diff"}}
	- Support for loading BMP files is new to ""FreeBASIC"".
	- Support for retrieving the palette from BMP files is new to ""FreeBASIC"".
	- ""FreeBASIC"" uses a different file format from QBASIC internally, which doesn't have the 64 ""KiB"" limit, and is unsupported by QBASIC.

{{fbdoc item="see"}}
	- ##[[KeyPgBsave|Bsave]]##
	- ##[[KeyPgPalette|Palette]]##
	- ##[[KeyPgImagecreate|ImageCreate]]##
	- ##[[KeyPgImageDestroy|ImageDestroy]]##
	- [[GfxInternalFormats|Internal Graphics Formats]]

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