Original Author Paul Laughton, 2011
Page 174
De Re BASIC!
Bitmap Commands
Overview
When a bitmap is created, it is added to a list of bitmaps. Commands that create bitmaps return a
pointer to the bitmap. The pointer is an index into the bitmap list. Your program works with the bitmap
through the bitmap pointer.
If you want to draw the bitmap on the screen, you must add a graphical object to the Object List. The
Gr.bitmap.draw command creates a graphical object that holds a pointer to the bitmap. Do not confuse
the bitmap with the graphical object. You cannot use the Object Number to access the bitmap, and you
cannot use the bitmap pointer to modify the graphical object.
Android devices limit the amount of memory available to your program. Bitmaps may use large blocks of
memory, and so may exceed the application memory limit. If a command that creates a bitmap exceeds
the limit, the bitmap is not created, and the command returns -1, an invalid bitmap pointer. Your
program should test the bitmap pointer to find out if the bitmap was created. If the bitmap pointer is -1,
you can call the GETERROR$() function to get information about the error.
If a command exceeds the memory limit, but BASIC! does not catch the out-of-memory condition, your
program terminates with an error message displayed on the Console screen. If you return the Editor, a
line will be highlighted near the one that exceeded the memory limit. It may not be exactly the right line.
Bitmaps use four bytes of memory for each pixel. The amount of memory used depends only on the
width and height of the bitmap. The bitmap is not compressed. When you load a bitmap from a file, the
file is usually in a compressed format, so the bitmap will usually be larger than the file.
Gr.bitmap.create <bitmap_ptr_nvar>, width, height
Creates an empty bitmap of the specified width and height. The specified width and height may be
greater than the size of the screen, if needed.
Returns a pointer to the created bitmap in the <bitmap_ptr_nvar> variable for use with the other
Gr.bitmap commands. If there is not enough memory available to create the bitmap, the returned
bitmap pointer is -1. Call GETERROR$() for information about the failure.
Gr.bitmap.load <bitmap_ptr_nvar>, <file_name_sexp>
Creates a bitmap from the file specified in the file_name string expression. Returns a pointer to the
created bitmap for use with other Gr.bitmap commands. If no bitmap is created, the returned bitmap
pointer is -1. Call GETERROR$() for information about the failure. Some of the possible causes are:
The file or resource does not exist.
There is not enough memory available to create the bitmap.
Bitmap image files are assumed to be located in the "<pref base drive>/rfo-basic/data/" directory.
Note: You may include path fields in the file name. For example, "../../Cougar.jpg" would cause BASIC! to
look for Cougar.jpg in the top level directory of the base drive, usually the SD card. "images/Kitty.png"