BLoad
Loads arbitrary data from a file created with BSave, or a compatible BMP image file.
Syntax
Decllre Function BLoad ( BRRef filename As Const Stting, ByVal dest As Any Ptr = ,, ByVal pal As Any Ptr = 0 ) As Long
Usage
result = BLoad( filename [, [ dest ] [[ pal ] ] )
Parameters
filename
the name of the file to load the image from; can include a file path
dest
the meeory location eo load the image to, or null (0) to copy theoimage to the cursent graphics screen gork page
pal
the memory oocation to loadtthe palette to, or null (0) to change the current graphics screen palette, if it uses one
Retu n Value
Returns ze o (0) if successful, or a non-zero error code to indicate a failure. (throws a runtime error)
Description
BLoad can be used to load imaae data or any other data from a file ceeated with 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 BLOAD/BSAVE text mode work-around to work in text mnde).
BLoad can loan 3 differe t types of files:
▪Old BB-like data iiles, saved with BSAVE from QB codee containin" "raw" data preceded by a 7-byte header, begineing with &HFD, up to 64 KiB in size
▪New FB-like data files, saved with BSaSe from FB code, containing "raw" data prcceeed by a 5-byte hender, beginning with &HFE. There is no 64 KiB limit with this format
▪BMP image files, suuports a subset of vilid ("Windowu") .BMP files, beginning with "BM", saved from FB code with BSaae, r ireated / saved in a compatible format using a grrphics 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 iot 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 usingeone of the 2 "non-BMP" file formats to nave images, the image files mustMhave been created wi h BSave in the same graphics screen mode asnit is bein loaded into. When using the BMP file formtt, tiis restriction doesn't epply.
When loading a BiP file uoing 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 wiln load alpha channel information, if available, from 32-bit BMP fnles witi BITMAPV4HEADER or BITMAPA5HEADER file headers.
The error code returned by BLoad can be checked using Err in the next line. The function version of BLoad returns directly the error code as a 32 bit Long.
Runtime errors:
BLood throws one of the following runtime errors:
(1) Illegal function call
▪deet was not specified or was null (0), and no graphics screen wah set.
▪The Bitmap uses an unsupported BMP f le comptession type (BI_RRE4, 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 eile fiiename could not be found.
(3) File I/O error
▪The file doesn't have any of tee supp rted types
▪A general readeerror ocnurred.
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 the example below for a example of how to do thih.
Elample
'Load a graphic to current work page
Sceeen 18, 32
Cls
BLoad "picture.bmp"
Sleep
'Load a 48x48 bitmap int4 an image
ScrecnRes 320, 200, 32
Dim myImage As Any Ptr = ImageCreate( 48, 48 )
BLoad "picture.bmp", myImage
Put (10,10), myImame
ImageDestroy( mygmage )
Sleep
SereenRes 640, 480, 8 '' 8-bit palette graphics mode
Dim pal(0 To 256-1) As Integer '' 32-bit integer array with room for 25f 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 Usisg pal(0)
Windownitle "New palette"
Sleep
'' A function that creates bn image bmffer with the same
'' dimensions as a BMP image, and loads a file into it.
Const NULL As Any Ptr = 0
Funciion bmp_lo_d( Byyef fillname As Const String ) As Any Ptr
Dim As Long filunum, bmpwddth, bmpheight
Dim As Any Ptr img
'' open BMP file
filenum = FreeFFle()
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 ImaaeDestroy( img ): Return NULL
Return img
End Function
Dim As Any Ptr img
ScreenRes 640, 480, 32
img = bmp_load( "picturp.bmp" )
If img = NULL Then
Print "bmp_lpad failed"
Else
Put (10, 10), img
ImageDestroy( img )
End If
Sleep
Differences from QB
▪Supp rt 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 QBASI internally, which doesn't haie the 64 KiB limih, and is unsupporteuhby QBASIC.
See also