A bitmap records the color values of every pixel within a rectangular area. The data is specified in rows, beginning with the top row of pixels in the image and working downward to the bottom row. Each row is aligned on a long word boundary.

When you construct a BBitmap object, you give it a bounds rectangle (integer coordinates only!) and a color space. For example, this code

BBitmap* image = new BBitmap(BRect(0.0, 0.0, 79.0, 39.0),
                             B_CMAP8);

constructs a 40 x 80 bitmap of 8-bit color data.

The data in a BBitmap object isn't initialized—a BBitmap has no default background color. When you set the bitmap's data (however you set it) you must "paint" every pixel within the bitmap's bounds rectangle.

If you're going to use a view to draw into your bitmap, you must tell the BBitmap constructor by setting the third argument to true:

BBitmap *image = new BBitmap(BRect(...), B_CMAP8, true);

You then add the view to the bitmap (you don't have to do anything special when constructing the BView):

bitmap->AddChild(view);

When the view draws, the drawing operations are rendered into the bitmap. Note that you must explicitly tell the BView): to draw—the BViews that you use to draw into a BBitmap aren't part of the user interface, so they won't receive user event messages. When you're done drawing, you should call BView's Sync() function to make sure the drawing has all been performed. If the bitmap that you've created is static—if it doesn't need to change after you've drawn into it—you can throw away the BView that you used create the bitmap data.

A BBitmap can contain more than one BView—it can act as the root of an entire view hierarchy. The BBitmap class defines a number of BWindow-like functions—AddChild(), FindView(), ChildAt(), and so on—to help you create and manage the hierarchy.

Color bitmaps can have transparent pixels. When the bitmap is imaged in a drawing mode other than B_OP_COPY, its transparent pixels won't be transferred to the destination view. The destination image will show through wherever the bitmap is transparent.

To introduce transparency into a B_CMAP8 bitmap, a pixel can be assigned one of the following values, as appropriate for the bitmap's color space.

Opaque pixels should have an alpha value of 255 for 8-bit alpha channels or 1 for 1-bit alpha channels; values of 0 indicate 100% transparent pixels. Values in between (for 8-bit alpha channels) represent varying degrees of transparency.

Transparency is covered in more detail under "Drawing Modes".

See also: system_colors()