The Interface Kit: BBitmap

The Interface Kit Table of Contents | The Interface Kit Index

# BBitmap

Derived from: BArchivable

Declared in: be/interface/Bitmap.h

Library: libbe.so

Allocation: Constructor only

###### Summary

A BBitmap describes a rectangular image as a two-dimensional array of pixel data (or bitmap). The BBitmap class lets you create a bitmap by specifying raw pixel data (through the `Bits()` and `SetBits()` functions), or you can add a BView to your BBitmap and use the view's drawing operations (`FillRect()`, `StrokeLine()`, etc) to draw into the BBitmap object (see "Using a View to Draw into a Bitmap", below).

The BBitmap class doesn't provide a way to actually display bitmap data. Displaying a bitmap is the task of BView functions such as `DrawBitmap()`.

## Bitmap Data

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 boudns rectangle.

## Using a View to Draw into a Bitmap

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 BBitmap'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.

### Transparency

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.

`B_TRANSPARENT_MAGIC_CMAP8` | 8-bit indexed color transparent pixel.
`B_TRANSPARENT_MAGIC_RGBA15` | 15-bit transparent pixel.
`B_TRANSPARENT_MAGIC_RGBA15_BIG` | 15-bit transparent pixel, big-endian.
`B_TRANSPARENT_MAGIC_RGBA32` | 32-bit transparent pixel.
`B_TRANSPARENT_MAGIC_RGBA32_BIG` | 32-bit transparent pixel, big-endian.

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" on page26.

See also: `system_colors()`

## Constructor and Destructor

### BBitmap()

`BBitmap(` BRect bounds, color_space space, bool acceptsViews = false, bool needsContiguousMemory = false`)`
`BBitmap(` BMessage *archive`)`

| The BBitmap class insists that a BApplication object be present (but not necessarily running).

Creates a new BBitmap object that can hold a bitmap whose size and depth are described by bounds and space. The bitmap data is uninitialized; you set the data through `Bits()`/`SetBits()`, or by drawing into an attached BView (see "Using a View to Draw into a Bitmap").

If BViews are to be used, the acceptsViews argument must be set to `true`. Furthermore (in this case), the origin of the bounds rectangle must be 0.0.

If the needsContiguousMemory flag is `true`, the BBitmap will make sure that the (physical) memory it allocates is one contiguous physical chunk. This should matter only to drivers doing direct DMA into physical memory.

The possible color spaces are enumerated in the section above titled "The Color Space".

### ~BBitmap()

virtual `~BBitmap() `

Frees all memory allocated to hold image data, deletes any BViews used to create the image, gets rid of the off-screen window that held the views, and severs the BBitmap's connection to the Application Server.

## Static Functions

### Instantiate()

static BArchivable *`Instantiate(` BMessage *archive`)`

Returns a new BBitmap object—or `NULL`, if the archive message doesn't contain data for a BBitmap object. The new object is allocated by `new` and created with the version of the constructor that takes a BMessage archive.

See also: `BArchivable::Instantiate()`, `instantiate_object()`, `Archive()`

## Member Functions

### AddChild()

virtual void `AddChild(` BView *aView`) `

Adds aView (and all its children) to this BBitmap's view hierarchy, and causes `AttachedToWindow()` to be sent to the newly add children.

| If aView already has a parent, the application may crash. Be sure to remove the view from a previous parent before trying to add it to a bitmap.

`AddChild()` fails if the BBitmap was not constructed to accept views.

See also: `BWindow::AddChild()`, `BView::AttachedToWindow()`, `RemoveChild()`, the BBitmap constructor

### Archive()

virtual status_t `Archive(` BMessage *archive, bool deep = true`)` const

Calls the inherited version of `Archive()` and stores the BBitmap in the BMessage archive.

See also: `BArchivable::Archive()`, `Instantiate()` static function

### Bits()

void *`Bits(`void`)` const

Returns a pointer to the bitmap data. The length of the data can be obtained by calling `BitsLength()`—or it can be calculated from the height of the bitmap (the number of rows) and `BytesPerRow()`.

The data is in the format specified by `ColorSpace()`.

This pointer is valid throughout the entire lifespan of the object.

See also: `Bounds()`, `BytesPerRow()`, `BitsLength()`

### BitsLength()

int32 `BitsLength(`void`)` const

Returns the number of bytes that were allocated to store the bitmap data.

See also: `Bits()`, `BytesPerRow()`

### Bounds()

BRect `Bounds(`void`)` const

Returns the bounds rectangle that defines the size and coordinate system of the bitmap. This should be identical to the rectangle used in constructing the object.

### BytesPerRow()

int32 `BytesPerRow(`void`)` const

Returns how many bytes of data are required to specify a row of pixels. This may include slop space required by the graphics hardware; you should always use this call to determine the width of a row of pixels in bytes instead of assuming that it will be the number of pixels multiplied by the size of a pixel in bytes.

### ChildAt() , CountChildren()

BView *`ChildAt(`int32 index`)` const
int32 `CountChildren(`void`)` const

`ChildAt()` returns the child BView at index, or `NULL` if there's no child at index. Indices begin at 0 and count only BViews that were added to the BBitmap (added as children of the top view of the BBitmap's off-screen window) and not subsequently removed.

`CountChildren()` returns the number of BViews the BBitmap currently has. (It counts only BViews that were added directly to the BBitmap, not BViews farther down the view hierarchy.)

These functions fail if the BBitmap wasn't constructed to accept views.

### ColorSpace()

color_space `ColorSpace(`void`)` const

Returns the color space of the data being stored (not necessarily the color space of the data passed to the `SetBits()` function). Once set by the BBitmap constructor, the color space doesn't change.

### CountChildren() see ChildAt()

### FindView()

BView *`FindView(` BPoint point`)` const
BView *`FindView(`const char *name`)` const

Returns the BView located at point within the bitmap or the BView tagged with name. The point must be somewhere within the BBitmap's bounds rectangle, which must have the coordinate origin, (0.0, 0.0), at its left top corner.

If the BBitmap doesn't accept views, this function fails. If no view draws at the point given, or no view associated with the BBitmap has the name given, it returns `NULL`.

### IsValid()

bool `IsValid(`void`)` const

Returns `true` if there's memory for the bitmap (if the address returned by `Bits()` is valid), and `false` if not.

### Lock() , Unlock() , IsLocked()

bool `Lock(`void`) `
void `Unlock(`void`) `
bool `IsLocked(`void`)` const

These functions lock and unlock the off-screen window where BViews associated with the BBitmap draw. Locking works for this window and its views just as it does for ordinary on-screen windows.

`Lock()` returns `false` if the BBitmap doesn't accept views or if its off-screen window is unlockable (and therefore unusable) for some reason. Otherwise, it doesn't return until it has the window locked and can return `true`.

`IsLocked()` returns `false` if the BBitmap doesn't accept views. Otherwise, it returns the lock status of its off-screen window.

### RemoveChild()

virtual bool `RemoveChild(` BView *aView`) `

Removes aView from the hierarchy of views associated with the BBitmap, but only if aView was added to the hierarchy by calling BBitmap's version of the `AddChild()` function.

If aView is successfully removed, `RemoveChild()` returns `true`. If not, it returns `false`.

### SetBits()

void `SetBits(`const void *data, int32 length, int32 offset, color_space mode`) `

Assigns length bytes of data to the BBitmap object. The new data is copied into the bitmap beginning offset bytes (not pixels) from the start of allocated memory. To set data beginning with the first (left top) pixel in the image, the offset should be 0; to set data beginning with, for example, the sixth pixel in the first row of a `B_RGB32` image, the offset should be 20. The offset counts any padding required to align rows of data.

This function is intended to be used for importing existing data from a different format rather than for setting individual pixels in the bitmap. If you're interested in coloring individual pixels, use `Bits()` to obtain direct access to the bitmap data.

The source data is specified in the mode color space, which may or may not be the same as the color space that the BBitmap uses to store the data. If not, the following conversions are automatically made:

- `B_GRAY1` and `B_RGB32` to `B_CMAP8`.

- `B_CMAP8` and `B_GRAY1` to `B_RGB32`.

| These are the only color conversions SetBits() understands; all other conversions must be performed manually.

Colors may be dithered in a conversion to `B_CMAP8` so that the resulting image will match the original as closely as possible, despite the lost information.

If the color space mode is `B_RGB32`, the data should be triplets of three 8-bit components—red, green, and blue, in that order—without an alpha component. Although stored as 32-bit quantities with the components in BGRA order, the input data is only 24 bits in RGB order. Rows of source data do not need to be aligned.

However, if the source data is in any mode other than `B_RGB32`, padding must be added so that each row is aligned on a `int32` word boundary.

| `SetBits()` works only on BBitmaps in B_GRAY1, B_CMAP8, and B_RGB32 color spaces; all other conversions must be carried out manually.

This function works for all BBitmaps, whether or not BViews are also enlisted to produce the image.

## Archived Fields

The `Archive()` function adds the following fields to its BMessage argument:

Field | Type code | Meaning
--- | --- | ---
"_frame" | `B_RECT_TYPE` | The BBitmap's bounds rectangle.
"_cspace" | `B_INT32_TYPE` | The color_space of the data.
"_view_ok" | `B_BOOL_TYPE` | Always `true`, indicating the BBitmap accepts views (only present in deep copy archives of BBitmaps accepting views).
"_data" | `B_RAW_TYPE` | The bitmap data (present only if "_view_ok" not present).
"_continguous" | `B_BOOL_TYPE` | Whether the BBitmap requires memory in one contiguous chunk.

If the "_view_ok" field is present, the child views of the BBitmap are additionally archived in the "_views" array of BMessages. See the description of the BView Archived Fields for more information on those fields.

The Interface Kit Table of Contents | The Interface Kit Index

The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..