Retrieving Bitmaps

Sometimes it's necessary to retrieve an bitmap from a virtual buffer. Fastgraph includes three functions, fg_getimage(), fg_getdcb(), and fg_getmap(), for this purpose. The fg_getimage() function retrieves a 256-color bitmap. The fg_getdcb() function retrieves a direct color bitmap in either high color or true color format, depending on the virtual buffer color depth. The fg_getmap() function retrieves pixels of the current color and stores them as a monochrome bitmap. The parameters to these three functions are the same as for their corresponding bitmap display functions. In all cases, the graphics cursor position in the active virtual buffer defines the lower left corner of the bitmap to retrieve.

In direct color virtual buffers, we can use fg_getimage() to retrieve 256-color bitmaps, or fg_getdcb() to retrieve direct color bitmaps. When fg_getimage() retrieves a 256-color bitmap from a direct color virtual buffer, it looks for a matching color in the virtual palette. If it finds an exact match, fg_getimage() sets the bitmap pixel to the index of the first matching virtual palette entry (which will be between 0 and 255). If fg_getimage() doesn't find a match, it sets the bitmap pixel to zero.

If we want to use fg_getmap() to retrieve an image containing more than one color, we must call the function once per color. In this case we'll usually want to pass different bitmap arrays to fg_getmap() (or perhaps different offsets into the same array). This might seem unusual at first, but it parallels the behavior of fg_drawmap(). That is, to display a multicolor image using fg_drawmap(), we must call it once for each color in the image.