Access and manipulate digital images commonly known as bitmaps. More...

Inheritance diagram for BBitmap:

Public Member Functions
	BBitmap (BRect bounds, uint32 flags, color_space colorSpace, int32 bytesPerRow=B_ANY_BYTES_PER_ROW, screen_id screenID=B_MAIN_SCREEN_ID)
	Creates and initializes a BBitmap object.
	BBitmap (BRect bounds, color_space colorSpace, bool acceptsViews=false, bool needsContiguous=false)
	Creates and initializes a BBitmap object.
	BBitmap (const BBitmap &source, uint32 flags)
	Creates a BBitmap object as a clone of another bitmap.
	BBitmap (const BBitmap &source)
	Creates a BBitmap object as a clone of another bitmap.
	BBitmap (const BBitmap *source, bool acceptsViews=false, bool needsContiguous=false)
	Creates a BBitmap object as a clone of another bitmap.
virtual	~BBitmap ()
	Destructor Method.
virtual status_t	AllArchived (BMessage *archive) const
	Method relating to the use of `BArchiver`.
virtual status_t	AllUnarchived (const BMessage *archive)
	Method relating to the use of `BUnarchiver`.
status_t	InitCheck () const
	Gets the status of the constructor.
bool	IsValid () const
	Determines whether or not the BBitmap object is valid.
Locking
status_t	LockBits (uint32 *state=NULL)
	Locks the bitmap bits so that they cannot be relocated.
void	UnlockBits ()
	Unlocks the bitmap's buffer.
bool	Lock ()
	Locks the off-screen window that belongs to the bitmap.
void	Unlock ()
	Unlocks the off-screen window that belongs to the bitmap.
bool	IsLocked () const
	Determines whether or not the bitmap's off-screen window is locked.
Accessors
area_id	Area () const
	Gets the ID of the area the bitmap data reside in.
void *	Bits () const
	Gets the pointer to the bitmap data.
int32	BitsLength () const
	Gets the length of the bitmap data.
int32	BytesPerRow () const
	Gets the number of bytes used to store a row of bitmap data.
color_space	ColorSpace () const
	Gets the bitmap's color space.
BRect	Bounds () const
	Gets a BRect the size of the bitmap's dimensions.
uint32	Flags () const
	Accesses the bitmap's creation flags.
status_t	GetOverlayRestrictions (overlay_restrictions *restrictions) const
	Gets the overlay_restrictions structure for this bitmap.
Setters
void	SetBits (const void *data, int32 length, int32 offset, color_space colorSpace)
	Assigns data to the bitmap.
status_t	ImportBits (const void *data, int32 length, int32 bpr, int32 offset, color_space colorSpace)
	Assigns data to the bitmap.
status_t	ImportBits (const void *data, int32 length, int32 bpr, color_space colorSpace, BPoint from, BPoint to, int32 width, int32 height)
	Assigns data to the bitmap.
status_t	ImportBits (const BBitmap *bitmap)
	Assigns another bitmap's data to this bitmap.
status_t	ImportBits (const BBitmap *bitmap, BPoint from, BPoint to, int32 width, int32 height)
	Assigns data to the bitmap.
Child View Methods
virtual void	AddChild (BView *view)
	Adds a BView to the bitmap's view hierarchy.
virtual bool	RemoveChild (BView *view)
	Removes a BView from the bitmap's view hierarchy.
int32	CountChildren () const
	Gets the number of BViews currently belonging to the bitmap.
BView *	ChildAt (int32 index) const
	Gets the BView at a certain index in the bitmap's list of views.
BView *	FindView (const char *viewName) const
	Accesses a bitmap's child BView with a the name viewName.
BView *	FindView (BPoint point) const
	Accesses a bitmap's BView at a certain location.
Archiving
	BBitmap (BMessage *data)
	Unarchives a bitmap from a BMessage.
virtual status_t	Archive (BMessage *data, bool deep=true) const
	Archives the BBitmap object.
static BArchivable *	Instantiate (BMessage *data)
	Instantiates a BBitmap from an archive.

Detailed Description

Access and manipulate digital images commonly known as bitmaps.

A BBitmap is a rectangular map of pixel data. The BBitmap class allows you to create a bitmap by specifying its pixel data and has operations for altering and accessing the properties of bitmaps.

To create a BBitmap object use one of the constructor methods below. You can determine if initialization was successful by calling the InitCheck() method. You can determine if a BBitmap object is valid at any time by calling the IsValid() method.

An example of creating a new 32x32 pixel BBitmap object and assigning the icon of the current application looks like this:

BBitmap iconBitmap = new BBitmap(BRect(0, 0, 31, 31), B_RGBA32));
appFileInfo.GetIcon(iconBitmap, B_LARGE_ICON);

You can access the properties of a bitmap by calling the Bounds(), Flags(), ColorSpace(), Area(), Bits(), BitsLength(), BytesPerRow(), and GetOverlayRestrictions() methods.

To directly set the pixel data of a bitmap call the Bits() or SetBits() methods or you can use the ImportBits() method to copy the bits from an existing bitmap.

You can also draw into a bitmap by attaching a child BView to the bitmap. To add and remove child BView's to a bitmap call the AddChild() and RemoveChild() methods respectively. You can access the child views of a bitmap by calling the CountChildren(), ChildAt(), and FindView() methods.

For off-screen bitmaps it is important to lock the bitmap before drawing the pixels and then unlock the bitmap when you are done to prevent flickering. To lock and unlock a bitmap call the LockBits() and UnLockBits() methods respectively. To lock and unlock the off-screen window that a bitmap resides in you should call the Lock() and UnLock() methods. To determine is a bitmap is currently locked you can call the IsLocked() method.

Constructor & Destructor Documentation

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

Creates and initializes a BBitmap object.

Parameters:

bounds	The bitmap dimensions.
flags	Creation flags.
colorSpace	The bitmap's color space.
bytesPerRow	The number of bytes per row the bitmap should use. `B_ANY_BYTES_PER_ROW` to let the constructor choose an appropriate value.
screenID	???

BBitmap::BBitmap	(	BRect	bounds,
		color_space	colorSpace,
		bool	acceptsViews = `false`,
		bool	needsContiguous = `false`
	)

Creates and initializes a BBitmap object.

Parameters:

bounds	The bitmap dimensions.
colorSpace	The bitmap's color space.
acceptsViews	`true`, if the bitmap shall accept BViews, i.e. if it shall be possible to attach BView to the bitmap and draw into it.
needsContiguous	If `true` a physically contiguous chunk of memory will be allocated.

BBitmap::BBitmap	(	const BBitmap &	source,
		uint32	flags
	)

Creates a BBitmap object as a clone of another bitmap.

Parameters:

source	The source bitmap.
flags	Creation flags.

BBitmap::BBitmap ( const BBitmap & source )

Creates a BBitmap object as a clone of another bitmap.

Parameters:

source The source bitmap.

BBitmap::BBitmap	(	const BBitmap *	source,
		bool	acceptsViews = `false`,
		bool	needsContiguous = `false`
	)

Creates a BBitmap object as a clone of another bitmap.

Parameters:

source	The source bitmap.
acceptsViews	`true`, if the bitmap shall accept BViews, i.e. if it shall be possible to attach BView to the bitmap and draw into it.
needsContiguous	If `true` a physically contiguous chunk of memory will be allocated.

BBitmap::~BBitmap ( ) [virtual]

Destructor Method.

Frees all resources associated with this object.

BBitmap::BBitmap ( BMessage * data )

Unarchives a bitmap from a BMessage.

Parameters:

data	The archive.

Member Function Documentation

void BBitmap::AddChild ( BView * view ) [virtual]

Adds a BView to the bitmap's view hierarchy.

The bitmap must accept views and the supplied view must not be child of another parent.

Parameters:

view	The view to be added.

status_t BArchivable::AllArchived ( BMessage * into ) const [virtual, inherited]

Method relating to the use of BArchiver.

This hook function is called once the first BArchiver that was created in an archiving session is either destroyed, or has its Finish() method called. Implementations of this method can be used, in conjunction with BArchiver::IsArchived(), to reference objects in your archive that you do not own, depending on whether or not those objects were archived by their owners. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method.

Warning:: To guarantee that your AllArchived() method will be called during archival, you must create a BArchiver object in your Archive() implementation.; You should archive any objects you own in your Archive() method implementation, and NOT your AllArchived() method.

See also:: BArchiver BArchiver::Finish()

Reimplemented in BView, BLayout, BGridLayout, BLayoutItem, BTwoDimensionalLayout, BAbstractLayout, and BGroupLayout.

status_t BArchivable::AllUnarchived ( const BMessage * archive ) [virtual, inherited]

Method relating to the use of BUnarchiver.

This hook function is called triggered in the BUnarchiver::Finish() method. In this method, you can rebuild references to objects that may be direct children of your object, or may be children of other objects. Implementations of this method should call the implementation of their parent class, the same as for the Archive() method.

Warning:: To guarantee that your AllUnarchived() method will be called during unarchival, you must create a BUnarchiver object in your archive constructor.

See also:: BUnarchiver, BUnarchiver::Finish()

Reimplemented in BView, BLayout, BGridLayout, BLayoutItem, BTwoDimensionalLayout, BAbstractLayout, and BGroupLayout.

status_t BBitmap::Archive	(	BMessage *	data,
		bool	deep = `true`
	)		const `[virtual]`

Archives the BBitmap object.

Parameters:

data	The archive.
deep	if `true`, child object will be archived as well.

Returns:: B_OK, if everything went fine, an error code otherwise.

Reimplemented from BArchivable.

area_id BBitmap::Area ( ) const

Gets the ID of the area the bitmap data reside in.

Returns:: The ID of the area the bitmap data reside in.

void * BBitmap::Bits ( ) const

Gets the pointer to the bitmap data.

Returns:: The pointer to the bitmap data.

int32 BBitmap::BitsLength ( ) const

Gets the length of the bitmap data.

Returns:: The length of the bitmap data as an int32.

BRect BBitmap::Bounds ( ) const

Gets a BRect the size of the bitmap's dimensions.

Returns:: A BRect the size of the bitmap's dimensions.

int32 BBitmap::BytesPerRow ( ) const

Gets the number of bytes used to store a row of bitmap data.

Returns:: The number of bytes used to store a row of bitmap data.

BView * BBitmap::ChildAt ( int32 index ) const

Gets the BView at a certain index in the bitmap's list of views.

Parameters:

index The index of the BView to be returned.

Returns:: The BView at index index or NULL if the index is out of range.

color_space BBitmap::ColorSpace ( ) const

Gets the bitmap's color space.

Returns:: The bitmap's color space.

int32 BBitmap::CountChildren ( ) const

Gets the number of BViews currently belonging to the bitmap.

Returns:: The number of BViews currently belonging to the bitmap.

BView * BBitmap::FindView ( const char * viewName ) const

Accesses a bitmap's child BView with a the name viewName.

Parameters:

viewName The name of the BView to be returned.

Returns:: The BView with the name name or NULL if the bitmap doesn't know a view with that name.

BView * BBitmap::FindView ( BPoint point ) const

Accesses a bitmap's BView at a certain location.

Parameters:

point The location.

Returns:: The BView with located at point or NULL if the bitmap doesn't know a view at this location.

uint32 BBitmap::Flags ( ) const

Accesses the bitmap's creation flags.

This method informs about which flags have been used to create the bitmap. It would for example tell you wether this is an overlay bitmap. If bitmap creation succeeded, all flags are fulfilled.

Returns:: The bitmap's creation flags.

status_t BBitmap::GetOverlayRestrictions ( overlay_restrictions * restrictions ) const

Gets the overlay_restrictions structure for this bitmap.

Note:: This function is not part of the BeOS R5 API.

Parameters:

restrictions The overlay restrictions flag

Return values:

B_OK	The overlay restriction structure was found.
B_BAD_TYPE	The overlay restriction structure for the bitmap could not be found.

status_t BBitmap::ImportBits	(	const void *	data,
		int32	length,
		int32	bpr,
		int32	offset,
		color_space	colorSpace
	)

Assigns data to the bitmap.

Data are directly written into the bitmap's data buffer, being converted beforehand, if necessary. Unlike for SetBits(), the meaning of colorSpace is exactly the expected one here, i.e. the source buffer is supposed to contain data of that color space. bpr specifies how many bytes the source contains per row. B_ANY_BYTES_PER_ROW can be supplied, if standard padding to int32 is used.

The currently supported source/target color spaces are B_RGB{32,24,16,15}[_BIG], B_CMAP8 and B_GRAY{8,1}.

Note:: This function is not part of the BeOS R5 API.

Parameters:

data	The data to be copied.
length	The length in bytes of the data to be copied.
bpr	The number of bytes per row in the source data.
offset	The offset (in bytes) relative to beginning of the bitmap data specifying the position at which the source data shall be written.
colorSpace	Color space of the source data.

Return values:

B_OK	The bits were imported into the bitmap.
B_BAD_VALUE	`NULL` data, invalid bpr or offset, or unsupported colorSpace.

status_t BBitmap::ImportBits	(	const void *	data,
		int32	length,
		int32	bpr,
		color_space	colorSpace,
		BPoint	from,
		BPoint	to,
		int32	width,
		int32	height
	)

Assigns data to the bitmap.

Allows for a BPoint offset in the source and in the bitmap. The region of the source at from extending width and height is assigned (and converted if necessary) to the bitmap at to.

The currently supported source/target color spaces are B_RGB{32,24,16,15}[_BIG], B_CMAP8 and B_GRAY{8,1}.

Note:: This function is not part of the BeOS R5 API.

Parameters:

data	The data to be copied.
length	The length in bytes of the data to be copied.
bpr	The number of bytes per row in the source data.
colorSpace	Color space of the source data.
from	The offset in the source where reading should begin.
to	The offset in the bitmap where the source should be written.
width	The width (in pixels) to be imported.
height	The height (in pixels) to be imported.

Return values:

B_OK	The bits were imported into the bitmap.
B_BAD_VALUE,:	`NULL` data, invalid bpr, unsupported colorSpace or invalid width or height.

status_t BBitmap::ImportBits ( const BBitmap * bitmap )

Assigns another bitmap's data to this bitmap.

The supplied bitmap must have the exactly same dimensions as this bitmap. Its data is converted to the color space of this bitmap.

The currently supported source/target color spaces are B_RGB{32,24,16,15}[_BIG], B_CMAP8 and B_GRAY{8,1}.

Note:: This function is not part of the BeOS R5 API.

Parameters:

bitmap The source bitmap.

Return values:

B_OK	The bits were imported into the bitmap.
B_BAD_VALUE	`NULL` bitmap, or bitmap has other dimensions, or the conversion from or to one of the color spaces is not supported.

status_t BBitmap::ImportBits	(	const BBitmap *	bitmap,
		BPoint	from,
		BPoint	to,
		int32	width,
		int32	height
	)

Assigns data to the bitmap.

Allows for a BPoint offset in the source and in the bitmap. The region of the source at from extending width and height is assigned (and converted if necessary) to the bitmap at to. The source bitmap is clipped to the bitmap and they don't need to have the same dimensions.

The currently supported source/target color spaces are B_RGB{32,24,16,15}[_BIG], B_CMAP8 and B_GRAY{8,1}.

Note:: This function is not part of the BeOS R5 API.

Parameters:

bitmap	The source bitmap.
from	The offset in the source where reading should begin.
to	The offset in the bitmap where the source should be written.
width	The width (in pixels) to be imported.
height	The height (in pixels) to be imported.

Return values:

B_OK	The bits were imported into the bitmap.
B_BAD_VALUE	`NULL` bitmap, the conversion from or to one of the color spaces is not supported, or invalid width or height.

status_t BBitmap::InitCheck ( ) const

Gets the status of the constructor.

Returns:: B_OK if initialization succeeded, otherwise returns an error status.

BArchivable * BBitmap::Instantiate ( BMessage * data ) [static]

Instantiates a BBitmap from an archive.

Parameters:

data	The archive.

Returns:: A bitmap reconstructed from the archive or NULL, if an error occurred.

Reimplemented from BArchivable.

bool BBitmap::IsLocked ( ) const

Determines whether or not the bitmap's off-screen window is locked.

The bitmap must accept views, if locking should work.

Returns:: true, if the caller owns a lock , false otherwise.

bool BBitmap::IsValid ( ) const

Determines whether or not the BBitmap object is valid.

Returns:: true, if the object is properly initialized, false otherwise.

bool BBitmap::Lock ( )

Locks the off-screen window that belongs to the bitmap.

The bitmap must accept views, if locking should work.

Returns:: true, if the lock was acquired successfully.

status_t BBitmap::LockBits ( uint32 * state = NULL )

Locks the bitmap bits so that they cannot be relocated.

This is currently only used for overlay bitmaps; whenever you need to access their Bits() you must lock them first. On resolution change overlay bitmaps can be relocated in memory; using this call prevents you from accessing an invalid pointer and clobbering memory that doesn't belong you.

Parameters:

state Unused

Returns:: B_OK on success or an error status code.

bool BBitmap::RemoveChild ( BView * view ) [virtual]

Removes a BView from the bitmap's view hierarchy.

Parameters:

view	The view to be removed.

void BBitmap::SetBits	(	const void *	data,
		int32	length,
		int32	offset,
		color_space	colorSpace
	)

Assigns data to the bitmap.

Data are directly written into the bitmap's data buffer, being converted beforehand, if necessary. Some conversions do not work intuitively:

B_RGB32: The source buffer is supposed to contain B_RGB24_BIG data without padding at the end of the rows.
B_RGB32: The source buffer is supposed to contain B_CMAP8 data without padding at the end of the rows.
other color spaces: The source buffer is supposed to contain data according to the specified color space being padded to int32 row-wise.

The currently supported source/target color spaces are B_RGB{32,24,16,15}[_BIG], B_CMAP8 and B_GRAY{8,1}.

Note:: Since this methods is a bit strange to use, Haiku has introduced the ImportBits() method which is the recommended replacement.

Parameters:

data	The data to be copied.
length	The length in bytes of the data to be copied.
offset	The offset (in bytes) relative to beginning of the bitmap data specifying the position at which the source data shall be written.
colorSpace	Color space of the source data.

void BBitmap::Unlock ( )

Unlocks the off-screen window that belongs to the bitmap.

The bitmap must accept views, if locking should work.

void BBitmap::UnlockBits ( )

Unlocks the bitmap's buffer.

Counterpart to BBitmap::LockBits().

Public Member Functions

Archiving

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation