BBitmap Class Reference

#include <Bitmap.h>

Inheritance diagram for BBitmap:

Detailed Description

A BBitmap describes a rectangular image as a two-dimensional array of pixel data (or bitmap).

See also:: Using BBitmap

Public Member Functions

BBitmap ()

BBitmap (BRect bounds, uint32 flags, color_space depth, int32 bytesPerRow=B_ANY_BYTES_PER_ROW, screen_id screenID=B_MAIN_SCREEN_ID)

BBitmap (const BBitmap &source)

BBitmap (const BBitmap &source, uint32 flags)

virtual ~BBitmap ()

BBitmap (BMessage *data)

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

BBitmap & operator= (const BBitmap &_source)

status_t InitCheck () const

bool IsValid () const

status_t LockBits (uint32 *state=NULL)

void UnlockBits ()

area_id Area () const

void * Bits () const

int32 BitsLength () const

int32 BytesPerRow () const

color_space ColorSpace () const

BRect Bounds () const

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

status_t Upload (BBitmap *from, BRect fromRect, BPoint toPoint)

status_t Freeze ()

status_t Thaw ()

status_t GetOverlayRestrictions (overlay_restrictions *restrict) const

virtual void AddChild (BView *view)

virtual bool RemoveChild (BView *view)

int32 CountChildren () const

BView * ChildAt (int32 index) const

BView * FindView (const char *view_name) const

BView * FindView (BPoint point) const

bool Lock ()

void Unlock ()

bool IsLocked () const

BBitmap (BRect bounds, color_space depth, bool accepts_views=false, bool need_contiguous=false)

BBitmap (const BBitmap *source, bool accepts_views=false, bool need_contiguous=false)

virtual status_t Perform (perform_code d, void *arg)

Static Public Member Functions

static BArchivable * Instantiate (BMessage *data)

Friends

class BPrivate::IKAccess

class BApplication

class BBitmapCollection

void _get_screen_bitmap_ (BBitmap *, BRect, bool)

Constructor & Destructor Documentation

BBitmap ( )

BBitmap ( BRect bounds,

uint32 flags,

color_space depth,

int32 bytesPerRow = B_ANY_BYTES_PER_ROW,

screen_id screenID = B_MAIN_SCREEN_ID

)

BBitmap ( const BBitmap & source )

Copy constructor.

BBitmap ( const BBitmap & source,

uint32 flags

)

~BBitmap ( ) [virtual]

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.

BBitmap ( BMessage * data )

BBitmap ( BRect frame,

color_space depth,

bool accepts_views = false,

bool need_contiguous = false

)

Deprecated:

Attention:
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 (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 ColorSpaces.

BBitmap ( const BBitmap * source,

bool accepts_view = false,

bool need_contiguous = false

)

Deprecated:

Member Function Documentation

void AddChild ( BView * view ) [virtual]

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

Attention:
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

status_t Archive ( BMessage * data,

bool deep = true

) const [virtual]

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

See also:
BArchivable::Archive(), Instantiate() static function
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.
Reimplemented from BArchivable.

area_id Area ( ) const

void * Bits ( ) 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 Bounds(), BytesPerRow(), BitsLength()

int32 BitsLength ( ) const

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

See also:
Bits(), BytesPerRow()

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

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.

Parameters:

index Index of child view.

This function fail if the BBitmap wasn't constructed to accept views.

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

int32 CountChildren ( ) const

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

Returns:
the number of BViews the BBitmap currently has.
This function fail if the BBitmap wasn't constructed to accept views.

BView * FindView ( BPoint pt ) const

Parameters:

pt Point at the bitmap.

Returns:
The BView located at point within the bitmap.
If the BBitmap doesn't accept views, this function fails. If no view draws at the point given, it returns NULL.

BView * FindView ( const char * name ) const

Parameters:

name Name of BView to find.

Returns:
The BView tagged with name.
If the BBitmap doesn't accept views, this function fails. If no view associated with the BBitmap has the name given, it returns NULL.

status_t Freeze ( )

status_t GetOverlayRestrictions ( overlay_restrictions * restrict ) const

status_t InitCheck ( ) const

BArchivable * Instantiate ( BMessage * data ) [static]

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

Reimplemented from BArchivable.

bool IsLocked ( ) const

Returns:
false if the BBitmap doesn't accept views. Otherwise, it returns the lock status of its off-screen window.

bool IsValid ( ) const

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

bool Lock ( )

This function lock 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.

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.

status_t LockBits ( uint32 * state = NULL )

BBitmap & operator= ( const BBitmap & _source )

status_t Perform ( perform_code d,

void * arg

) [virtual]

Reimplemented from BArchivable.

bool RemoveChild ( BView * view ) [virtual]

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 depth

)

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.

Attention:
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.

status_t Thaw ( )

void Unlock ( )

This function 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.

void UnlockBits ( )

status_t Upload ( BBitmap * from,

BRect fromRect,

BPoint toPoint

)

Friends And Related Function Documentation

void _get_screen_bitmap_ ( BBitmap * ,

BRect ,

bool

) [friend]

friend class BApplication [friend]

friend class BBitmapCollection [friend]

friend class BPrivate::IKAccess [friend]


Public Member Functions
	BBitmap ()
	BBitmap (BRect bounds, uint32 flags, color_space depth, int32 bytesPerRow=B_ANY_BYTES_PER_ROW, screen_id screenID=B_MAIN_SCREEN_ID)
	BBitmap (const BBitmap &source)
	BBitmap (const BBitmap &source, uint32 flags)
virtual	~BBitmap ()
	BBitmap (BMessage *data)
virtual status_t	Archive (BMessage *data, bool deep=true) const
BBitmap &	operator= (const BBitmap &_source)
status_t	InitCheck () const
bool	IsValid () const
status_t	LockBits (uint32 *state=NULL)
void	UnlockBits ()
area_id	Area () const
void *	Bits () const
int32	BitsLength () const
int32	BytesPerRow () const
color_space	ColorSpace () const
BRect	Bounds () const
void	SetBits (const void *data, int32 length, int32 offset, color_space cs)
status_t	Upload (BBitmap *from, BRect fromRect, BPoint toPoint)
status_t	Freeze ()
status_t	Thaw ()
status_t	GetOverlayRestrictions (overlay_restrictions *restrict) const
virtual void	AddChild (BView *view)
virtual bool	RemoveChild (BView *view)
int32	CountChildren () const
BView *	ChildAt (int32 index) const
BView *	FindView (const char *view_name) const
BView *	FindView (BPoint point) const
bool	Lock ()
void	Unlock ()
bool	IsLocked () const
	BBitmap (BRect bounds, color_space depth, bool accepts_views=false, bool need_contiguous=false)
	BBitmap (const BBitmap *source, bool accepts_views=false, bool need_contiguous=false)
virtual status_t	Perform (perform_code d, void *arg)
Static Public Member Functions
static BArchivable *	Instantiate (BMessage *data)
Friends
class	BPrivate::IKAccess
class	BApplication
class	BBitmapCollection
void	_get_screen_bitmap_ (BBitmap *, BRect, bool)