Displaying 256-Color Bitmaps

Fastgraph includes several functions for displaying 256-color bitmaps. The bitmap pixels are treated as an index into the logical palette for 256-color virtual buffers, or as an index into the virtual palette for direct color virtual buffers. That is, pixels of color n are displayed in the color assigned to logical or virtual palette entry n.

The fg_drwimage() function displays regular 256-color bitmaps (by regular, we mean a bitmap that is neither clipped nor reversed). Its first parameter is the name of the bitmap array, the second is the bitmap width in pixels, and the last is the bitmap height in pixels. The fg_drwimage() function displays the bitmap with its lower left corner at the graphics cursor position in the active virtual buffer.

Suppose we want to display the 9x5 triangle bitmap in the middle of a 320x200 virtual buffer. To do this, its lower left corner must be at the screen space position (156,101). The following code does the trick:

C/C++ and Delphi:

fg_move(156,101);
fg_drwimage(triangle,9,5);

Visual Basic:

Call fg_move(156, 101)
Call fg_drwimage(triangle(0), 9, 5)

The fg_drwimage() function does not perform clipping when displaying a 256-color bitmap. If you want the bitmap to be constrained by the clipping limits, use fg_clpimage() instead of fg_drwimage(). The fg_clpimage() function takes the same three parameters as fg_drwimage() and also displays the bitmap with its lower left corner at the graphics cursor position.

When using fg_clpimage(), you may establish a graphics position beyond the virtual buffer extents, including negative coordinates (recall that the clipping limits default to the virtual buffer extents). For example, we could display our 256-color triangle bitmap four pixels beyond the active virtual buffer's left edge with these calls:

C/C++ and Delphi:

fg_move(-4,50);
fg_clpimage(triangle,9,5);

Visual Basic:

Call fg_move(-4, 50)
Call fg_clpimage(triangle(0), 9, 5)

In this case, only the rightmost five pixels of each bitmap row would be displayed.

The fg_revimage() function displays a 256-color bitmap reversed (that is, mirrored about the y axis) without clipping. It takes the same three parameters as fg_drwimage() and also displays the bitmap with its lower left corner at the graphics cursor position.

The fg_flpimage() function combines the effects of fg_revimage() and fg_clpimage(). It displays a reversed 256-color bitmap constrained by the current clipping limits. It takes the same three parameters as fg_drwimage() and also displays the bitmap with its lower left corner at the graphics cursor position.

The fg_putimage() function is the same as fg_drwimage() except it does not consider color 0 pixels to be transparent. Because it does not need to check for transparent pixels, fg_putimage() is faster than fg_drwimage(). Using fg_putimage() is recommended for cases where transparency is not an issue.

As mentioned earlier, we can also use the 256-color bitmap display functions in direct color virtual buffers. The fg_xxximage() family of functions all access the virtual palette when displaying a 256-color bitmap in direct color buffers. For instance, if a 256-color bitmap contains pixels of color 20, those pixels will be displayed in whatever color is assigned to color 20 in the virtual palette. Recall that fg_defpal() sets up the virtual palette with the same colors as the default logical palette, and that we use fg_setrgb() and fg_setdacs() to change virtual palette entries. It's also important to remember that changing an entry in the virtual palette does not affect any pixels already drawn in that color, unlike changing the value of a logical palette entry.

In direct color virtual buffers, the virtual palette makes it possible to display an object in different colors at different times using the same 256-color bitmap. Suppose, for example, that you have a sprite of a man whose shirt is defined using colors 16, 17, and 18, and that these color values do not appear elsewhere in the sprite. To display the man wearing a red shirt, just define entries 16, 17, and 18 as shades of red in the virtual palette before displaying the sprite. If you later want to give him a different color shirt, you could change virtual palette entries 16, 17, and 18 to, say, shades of green. The next time you display the sprite, the shirt will be green.

Sometimes you may need to include black pixels that are not transparent in a bitmapped image. The easiest way to do this is with fg_putimage(), but that includes no provision for transparent pixels. Suppose, for example, that you want to display a bitmap containing both black pixels and transparent pixels. An easy solution is to define a second black color, using that color for non-transparent black pixels and using color 0 for transparent pixels. You can then display the bitmap as a regular image with fg_drwimage(). For instance, logical palette colors 0 and 10 are both black by default (and in the default virtual palette), so you could use color 10 for black bitmap pixels and color 0 for transparent bitmap pixels.