Loads arbitrary data from a file created with
BSave, or a compatible BMP image file.
Syntax
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 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
Return Value
Description
BLoad can be used to load image data or any other data from a file created with
BSave, and store that data in an array or paste it to the screen. If
dest is not null (
0), the image data is copied to memory starting at the address specified. Otherwise, it is pasted to the current graphics screen work page.
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 0xFD, up to 64 KiB in size
- New FB-like data files, saved with BSAVE from FB code, containing "raw" data preceded by a 7-byte header, beginning with 0xFE, no 64 KiB limit anymore
- BMP image files, supports a subset of valid ("Windows") .BMP files, beginning with "BM", saved from FB code with BSAVE, or created / saved in a compatible format using a graphics editor / converter.
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 (nonrecommended), the image files must have been created with
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 using
BLoad, the images must be true-color (24- or 32- bits per pixel) or palettized/indexed (8-bit or lower in resolution). The image data will be converted to the proper pixel format for the current color depth, except true-color won't get reduced to a palettized image.
BLoad doesn't support 15 or 16 bpp BMP's (rare), BMP's using the optional RLE compression (also rare), or other image file types (PNG, JPG, GIF, ...).
Runtime errors:
BLoad throws one of the following
runtime errors:
(1) Illegal function call
- dest was not specified or was null (0), and no graphics screen was set.
- The Bitmap is high-color (15 or 16 bits per pixel).
- The Bitmap is true-color (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.
Example
'Load a graphic to current work page
Screen 18, 32
Cls
BLoad "picture.bmp"
Sleep
'Load a 48x48 bitmap into an array
Screen 18, 32
Dim myImage As Any Ptr = ImageCreate( 48, 48 )
BLoad "picture.bmp", myImage
Put (10,10), myImage
ImageDestroy( myImage )
Sleep
Differences from QB
- Support for loading BMP files is new to FreeBASIC.
- Support for retrieving the palette from BMP files is new to FreeBASIC.
- For non-BMP files, FB uses a different file format, not having the 64 KiB limit, and unsupported by QB
See also