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

Warning

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

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 "Color Spaces".

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.

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

Warning

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

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

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

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

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

See also: Bits(), BytesPerRow()

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.

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

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.

Returns the BView 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.

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

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.

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.

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.

Note

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.

Warning

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.

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