BBitmap

Derived from: BArchivable
Declared in:  be/interface/Bitmap.h
Library: libbe.so
Allocation: Constructor only
Summary:  more...

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(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".

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

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

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

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

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()

int32 BitsLength(void) const

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

See also: Bits(), BytesPerRow()

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.

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.

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.

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.

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.

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.

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.

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.

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.

There's an additional constructor in the header that acts as a copy-constructor: BBitmap(BBitmap *).
--Gregor Rosenauer on March 1, 2002