The GMBitmapList Object
The GMBitmapList is a container for bitmaps (it stores bitmap pointers, or the addresses of bitmaps). In its simplest sense, you can use it as a storage container to hold all your bitmaps, and then simply retrieve them by number.
More useful is to use the GMBitmapList to automatically load an entire series of bitmaps. These bitmaps may be a numbered series of BMP files (mybitmap1.bmp, mybitmap2.bmp, ...., mybitmap10.bmp, ....).
The bitmaps can also come from a single BMP file. GMBitmapList will slice the bitmaps automatically from the one file. In this case, all the bitmaps must be identical in size. They may be placed horizontally in a single row, or stacked in multiple rows. When opening a GMBitmapList from a single file, you specify the width and height of the image. Say your BMP file contains six images that are each 120 pixels wide by 100 tall. The six images can be drawn in two rows of three. The BMP file would then be 360 wide and 200 tall. The top left 120 by 100 pixels would be bitmap 1 in the sequence. The middle top image is bitmap 2, and the top right is image 3. The lower left image is bitmap 4. The lower middle image is bitmap 5 and the lower right is bitmap 6.
One use of a GMBitmapList is to store a series of frames for a single animated image.
GMBitmapList Functions
Creating the GMBitmapList |
Adding more bitmaps to the list |
Count
GetNext/GetPrevious/GetBitmap/GetRandom
| GetBitmapNumber |
LoadSequence
Sample Programs
Earth GMBitmapList animation
(requires earthandspace.zip,
earthframes.zip,
earthsounds.zip)
Cards GMBitmapList
(requires deckofcards.zip)
Sample/Utility Program
BitmapListConverter This GMMachine program converts multiple BMP files for an animation into one file. These correspond to the files used for the two constructor types in GMBitmapList. The "Earth" example above uses 60 BMP files of a rotating planet earth. The "cards" example above uses one BMP file that contains images of all 52 cards. This BitmapListConverter program can combine all 60 Earth BMP files into one multi-image file. This takes less disk space, and it makes file management much easier.
The default constructor (no parameters) creates an empty GMBitmapList container. You can use the Add or LoadSequence functions to add GMBitmaps to the container.
The other two other constructors are available that load a sequence of bitmaps from a number series of BMP files, or a series of images sliced from a single BMP file. In most cases this sequence will be a series of frames used to animate a single image (or sprite). Here are the overloaded constructors:
// Loads bitmaps from a series of files: GMBitmapList(GMMachine& machine, unsigned int howmany, char *filepattern, BOOL IsTransparent=TRUE, int start=0); // Creates a BitmapList from one multiframe bitmap: GMBitmapList(GMMachine& machine, char *filename, unsigned int width, unsigned int height, unsigned int howmany=0, BOOL IsTransparent=TRUE);
Both take your GMMachine as the first parameter, and they both create a series of new GMBitmaps.
The first constructor takes a series of files and loads them all. The series must be numbered sequentially and end in ".bmp". For example, "picture1.bmp", "picture2.bmp", and so on. The second parameter tells how many files are in this series.
The third parameter tells where the files are located and the base name. If the sample "picture" files listed above are in the same directory as your EXE file, you'd simply use "picture" as the third parameter. If you create a subdirectory below the one your EXE file is in, you can give the subdirectory name, as in "directory\\picture". Remember that the double backslash compiles to a single backslash in C++.
The fourth parameter, if you provide it, is True or False (non-zero or zero) and automatically sets all the GMBitmaps in the list to transparent, using the upper-left pixel of each bitmap as the transparent color. If you leave off this parameter the GMBitmaps default to being transparent.
The fifth parameter, start is set to either 0 or 1. If it is 0 (the default), the filenames should be nnnn00.bmp, nnnn01.bmp, nnnn02.bmp,..., nnnn10.bmp, etc., where nnnn can be any name, which is given in parameter 3. Note that in this case the number is always two digits.
If the fifth parameter is set to 1, the names should be nnnn1.bmp, nnnn2.bmp, nnnn3.bmp, ...., nnnn10.bmp, etc. The reason for the choice is that some GIF animation converters start numbering their output at 00, and others start at 1.
The second constructor loads a single bitmap file, but splits it into a series of GMBitmaps. This is called a "multiframe bitmap", because one bitmap file actually contains all the frames. You give the name of the file, and the width and height of each frame. The frames can be arranged in your BMP file in a grid pattern, with the frames arranged sequentially across the first row, then across the second row, and so on.
If the total number of frames in your multiframe bitmap file is different than the number of rows times the number of columns, you must provide a number for the optional "howmany" parameter. (The number of rows and columns is determined by dividing the bitmap width and height by the frame width and height that you give in the function call.)
Again, the last parameter, if you provide it, sets the transparency for the entire series of bitmaps.
void Add(GMBitmap* bitmap)
void Add(GMBitmap& bitmap)
This function adds another GMBitmap to the GMBitmapList.
This function returns the number of bitmap pointers currently stored in the list. This is handy if you are writing a loop using GetNext or GetPrevious. Since those functions simply wrap around the list, without Count you'd have an infinite loop!
GMBitmap& GetNext()
GMBitmap& GetPrevious()
These return a reference to the next or previous bitmap from the list. Both "wrap" around the list. If you've gotten the last bitmap in the list and say "GetNext" again, it will give you the first. GetPrevious wraps from the first to the last.
GMBitmap& GetBitmap(int number)
This returns a reference to the bitmap number in the list. The numbering starts at 1 and goes through Count().
GMBitmap& GetRandom()
This returns a reference to a random bitmap in the list. Handy if you want to randomly assign bitmap images to sprites.
unsigned int GetBitmapNumber()
If you are using GetNext and GetPrevious, this function will tell you where you are currently at in the list.
This function operates the same as the constructor functions and has the same parameter lists. If you start by using the default constructor to create the GMBitmapList, you can still use LoadSequence to perform the same functions described in the overloaded constructors. The parameter list options for this function are identical to those used with the constructors.