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

Inherits BArchivable.

Public Member Functions
	BBitmap (area_id area, ptrdiff_t areaOffset, BRect bounds, uint32 flags, color_space colorSpace, int32 bytesPerRow=B_ANY_BYTES_PER_ROW, screen_id screenID=B_MAIN_SCREEN_ID)
	Creates a BBitmap object inside of an existing memory area.

	BBitmap (BMessage *data)
	Unarchives a bitmap from a BMessage.

	BBitmap (BRect bounds, color_space colorSpace, bool acceptsViews=false, bool needsContiguous=false)
	Creates and initializes a BBitmap object.

	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 (const BBitmap &source)
	Creates a BBitmap object as a clone of another bitmap.

	BBitmap (const BBitmap &source, uint32 flags)
	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.

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.

View Hierarchy
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 the name viewName.

BView *	FindView (BPoint point) const
	Accesses a bitmap's BView at a certain location.

Public Member Functions inherited from BArchivable
	BArchivable ()
	Constructor. Does nothing.

	BArchivable (BMessage *from)
	Constructor. Does important behind-the-scenes work in the unarchiving process.

virtual	~BArchivable ()
	Destructor. Does nothing.

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

virtual status_t	Archive (BMessage *into, bool deep=true) const
	Archive the object into a BMessage.

virtual status_t	Perform (perform_code d, void *arg)
	Perform some action (Internal method defined for binary compatibility purposes).

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

Setters
status_t	ImportBits (const void *data, int32 length, int32 bpr, int32 offset, color_space colorSpace)
	Assigns data to the bitmap.

status_t	ImportBits (const BBitmap *bitmap)
	Assigns another bitmap's data to this bitmap.

void	SetBits (const void *data, int32 length, int32 offset, color_space colorSpace)
	Assigns data to the bitmap.

Additional Inherited Members
Static Public Member Functions inherited from BArchivable
static BArchivable *	Instantiate (BMessage *archive)
	Static member to restore objects from messages.

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

B_LARGE_ICON

@ B_LARGE_ICON

Definition: Mime.h:17

BBitmap

Access and manipulate digital images commonly known as bitmaps.

Definition: Bitmap.h:45

BRect

Defines a rectangular area aligned along pixel dimensions.

Definition: Rect.h:15

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.

Since: BeOS R3

Constructor & Destructor Documentation

◆ BBitmap() [1/7]

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	Currently unused. May be used for multi-monitor support in the future.

Since: Haiku R1

◆ BBitmap() [2/7]

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.

Since: BeOS R3

◆ BBitmap() [3/7]

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.

Since: Haiku R1

◆ BBitmap() [4/7]

BBitmap::BBitmap ( const BBitmap & source )

Creates a BBitmap object as a clone of another bitmap.

Parameters

source The source bitmap.

Since: Haiku R1

◆ BBitmap() [5/7]

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.

Since: Haiku R1

◆ BBitmap() [6/7]

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

Creates a BBitmap object inside of an existing memory area.

This method is useful if you want to create a BBitmap on top of existing memory or want to share a BBitmap between two or more applications.

This BBitmap should be deleted before the area is deleted.

Parameters

area	The memory area to use
areaOffset	Offset within the memory area to place bitmap.
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	Currently unused. May be used for multi-monitor support in the future.

Since: Haiku R1

◆ ~BBitmap()

BBitmap::~BBitmap ( )

virtual

Destructor Method.

Frees all resources associated with this object.

Since: BeOS R3

◆ BBitmap() [7/7]

BBitmap::BBitmap ( BMessage * data )

Unarchives a bitmap from a BMessage.

Parameters

data	The archive.

Since: BeOS R3

Member Function Documentation

◆ AddChild()

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.

Since: BeOS R3

◆ Archive()

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.

Since: BeOS R3

Reimplemented from BArchivable.

◆ Area()

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.

Since: Haiku R1

◆ Bits()

void * BBitmap::Bits ( ) const

Gets the pointer to the bitmap data.

Returns: The pointer to the bitmap data.

Since: BeOS R3

◆ BitsLength()

int32 BBitmap::BitsLength ( ) const

Gets the length of the bitmap data.

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

Since: BeOS R3

◆ Bounds()

BRect BBitmap::Bounds ( ) const

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

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

Since: BeOS R3

◆ BytesPerRow()

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.

Since: BeOS R3

◆ ChildAt()

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.

Since: BeOS R3

◆ ColorSpace()

color_space BBitmap::ColorSpace ( ) const

Gets the bitmap's color space.

Returns: The bitmap's color space.

Since: BeOS R3

◆ CountChildren()

int32 BBitmap::CountChildren ( ) const

Gets the number of BViews currently belonging to the bitmap.

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

Since: BeOS R3

◆ FindView() [1/2]

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.

Since: BeOS R3

◆ FindView() [2/2]

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

Accesses a bitmap's child BView with 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.

Since: BeOS R3

◆ Flags()

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.

Since: Haiku R1

◆ GetOverlayRestrictions()

status_t BBitmap::GetOverlayRestrictions ( overlay_restrictions * restrictions ) const

Gets the overlay_restrictions structure for this bitmap.

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.

Since: Haiku R1

◆ ImportBits() [1/2]

status_t BBitmap::ImportBits ( const BBitmap * bitmap )

Assigns another bitmap's data to this bitmap.

The supplied bitmap must have the exact 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}.

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.

Since: Haiku R1

◆ ImportBits() [2/2]

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

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.

Since: Haiku R1

◆ InitCheck()

status_t BBitmap::InitCheck ( ) const

Gets the status of the constructor.

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

Since: Haiku R1

◆ Instantiate()

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.

Since: BeOS R3

◆ IsLocked()

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.

Since: BeOS R4

◆ IsValid()

bool BBitmap::IsValid ( ) const

Determines whether or not the BBitmap object is valid.

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

Since: BeOS R3

◆ Lock()

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.

Since: BeOS R3

◆ LockBits()

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.

Since: Haiku R1

◆ RemoveChild()

bool BBitmap::RemoveChild ( BView * view )

virtual

Removes a BView from the bitmap's view hierarchy.

Parameters

view	The view to be removed.

Since: BeOS R3

◆ SetBits()

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.

Since: BeOS R3

◆ Unlock()

void BBitmap::Unlock ( )

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

The bitmap must accept views, if locking should work.

Since: BeOS R3

◆ UnlockBits()

void BBitmap::UnlockBits ( )

Unlocks the bitmap's buffer.

Counterpart to BBitmap::LockBits().

Since: Haiku R1

Public Member Functions

Archiving

Setters

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BBitmap() [1/7]

◆ BBitmap() [2/7]

◆ BBitmap() [3/7]

◆ BBitmap() [4/7]

◆ BBitmap() [5/7]

◆ BBitmap() [6/7]

◆ ~BBitmap()

◆ BBitmap() [7/7]

Member Function Documentation

◆ AddChild()

◆ Archive()

◆ Area()

◆ Bits()

◆ BitsLength()

◆ Bounds()

◆ BytesPerRow()

◆ ChildAt()

◆ ColorSpace()

◆ CountChildren()

◆ FindView() [1/2]

◆ FindView() [2/2]

◆ Flags()

◆ GetOverlayRestrictions()

◆ ImportBits() [1/2]

◆ ImportBits() [2/2]

◆ InitCheck()

◆ Instantiate()

◆ IsLocked()

◆ IsValid()

◆ Lock()

◆ LockBits()

◆ RemoveChild()

◆ SetBits()

◆ Unlock()

◆ UnlockBits()