Public Member Functions | List of all members
BBitmap Class Reference

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

Inherits BArchivable.

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. More...
 
 BBitmap (BRect bounds, color_space colorSpace, bool acceptsViews=false, bool needsContiguous=false)
 Creates and initializes a BBitmap object. More...
 
 BBitmap (const BBitmap &source, uint32 flags)
 Creates a BBitmap object as a clone of another bitmap. More...
 
 BBitmap (const BBitmap &source)
 Creates a BBitmap object as a clone of another bitmap. More...
 
 BBitmap (const BBitmap *source, bool acceptsViews=false, bool needsContiguous=false)
 Creates a BBitmap object as a clone of another bitmap. More...
 
 BBitmap (BMessage *data)
 Unarchives a bitmap from a BMessage. More...
 
virtual ~BBitmap ()
 Destructor Method. More...
 
status_t InitCheck () const
 Gets the status of the constructor. More...
 
bool IsValid () const
 Determines whether or not the BBitmap object is valid. More...
 
Locking
status_t LockBits (uint32 *state=NULL)
 Locks the bitmap bits so that they cannot be relocated. More...
 
void UnlockBits ()
 Unlocks the bitmap's buffer. More...
 
bool Lock ()
 Locks the off-screen window that belongs to the bitmap. More...
 
void Unlock ()
 Unlocks the off-screen window that belongs to the bitmap. More...
 
bool IsLocked () const
 Determines whether or not the bitmap's off-screen window is locked. More...
 
Accessors
area_id Area () const
 Gets the ID of the area the bitmap data reside in. More...
 
void * Bits () const
 Gets the pointer to the bitmap data. More...
 
int32 BitsLength () const
 Gets the length of the bitmap data. More...
 
int32 BytesPerRow () const
 Gets the number of bytes used to store a row of bitmap data. More...
 
color_space ColorSpace () const
 Gets the bitmap's color space. More...
 
BRect Bounds () const
 Gets a BRect the size of the bitmap's dimensions. More...
 
uint32 Flags () const
 Accesses the bitmap's creation flags. More...
 
status_t GetOverlayRestrictions (overlay_restrictions *restrictions) const
 Gets the overlay_restrictions structure for this bitmap. More...
 
Setters
void SetBits (const void *data, int32 length, int32 offset, color_space colorSpace)
 Assigns data to the bitmap. More...
 
status_t ImportBits (const void *data, int32 length, int32 bpr, int32 offset, color_space colorSpace)
 Assigns data to the bitmap. More...
 
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. More...
 
status_t ImportBits (const BBitmap *bitmap)
 Assigns another bitmap's data to this bitmap. More...
 
status_t ImportBits (const BBitmap *bitmap, BPoint from, BPoint to, int32 width, int32 height)
 Assigns data to the bitmap. More...
 
View Hierarchy
virtual void AddChild (BView *view)
 Adds a BView to the bitmap's view hierarchy. More...
 
virtual bool RemoveChild (BView *view)
 Removes a BView from the bitmap's view hierarchy. More...
 
int32 CountChildren () const
 Gets the number of BViews currently belonging to the bitmap. More...
 
BViewChildAt (int32 index) const
 Gets the BView at a certain index in the bitmap's list of views. More...
 
BViewFindView (const char *viewName) const
 Accesses a bitmap's child BView with a the name viewName. More...
 
BViewFindView (BPoint point) const
 Accesses a bitmap's BView at a certain location. More...
 
- Public Member Functions inherited from BArchivable
 BArchivable (BMessage *from)
 Constructor. Does important behind-the-scenes work in the unarchiving process. More...
 
 BArchivable ()
 Constructor. Does nothing. More...
 
virtual ~BArchivable ()
 Destructor. Does nothing. More...
 
virtual status_t AllArchived (BMessage *archive) const
 Method relating to the use of BArchiver. More...
 
virtual status_t AllUnarchived (const BMessage *archive)
 Method relating to the use of BUnarchiver. More...
 

Archiving

virtual status_t Archive (BMessage *data, bool deep=true) const
 Archives the BBitmap object. More...
 
static BArchivableInstantiate (BMessage *data)
 Instantiates a BBitmap from an archive. More...
 

Additional Inherited Members

- Static Public Member Functions inherited from BArchivable
static BArchivableInstantiate (BMessage *archive)
 Static member to restore objects from messages. More...
 

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.

Since
BeOS R3

Constructor & Destructor Documentation

◆ BBitmap() [1/6]

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
boundsThe bitmap dimensions.
flagsCreation flags.
colorSpaceThe bitmap's color space.
bytesPerRowThe number of bytes per row the bitmap should use. B_ANY_BYTES_PER_ROW to let the constructor choose an appropriate value.
screenID???
Since
Haiku R1

◆ BBitmap() [2/6]

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

Creates and initializes a BBitmap object.

Parameters
boundsThe bitmap dimensions.
colorSpaceThe bitmap's color space.
acceptsViewstrue, if the bitmap shall accept BViews, i.e. if it shall be possible to attach BView to the bitmap and draw into it.
needsContiguousIf true a physically contiguous chunk of memory will be allocated.
Since
BeOS R3

◆ BBitmap() [3/6]

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

Creates a BBitmap object as a clone of another bitmap.

Parameters
sourceThe source bitmap.
flagsCreation flags.
Since
Haiku R1

◆ BBitmap() [4/6]

BBitmap::BBitmap ( const BBitmap source)

Creates a BBitmap object as a clone of another bitmap.

Parameters
sourceThe source bitmap.
Since
Haiku R1

◆ BBitmap() [5/6]

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

Creates a BBitmap object as a clone of another bitmap.

Parameters
sourceThe source bitmap.
acceptsViewstrue, if the bitmap shall accept BViews, i.e. if it shall be possible to attach BView to the bitmap and draw into it.
needsContiguousIf true a physically contiguous chunk of memory will be allocated.
Since
Haiku R1

◆ ~BBitmap()

BBitmap::~BBitmap ( )
virtual

Destructor Method.

Frees all resources associated with this object.

Since
BeOS R3

◆ BBitmap() [6/6]

BBitmap::BBitmap ( BMessage data)

Unarchives a bitmap from a BMessage.

Parameters
dataThe 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
viewThe view to be added.
Since
BeOS R3

◆ Archive()

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

Archives the BBitmap object.

Parameters
dataThe archive.
deepif 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
indexThe 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 ( const char *  viewName) const

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

Parameters
viewNameThe 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

◆ FindView() [2/2]

BView * BBitmap::FindView ( BPoint  point) const

Accesses a bitmap's BView at a certain location.

Parameters
pointThe location.
Returns
The BView with located at point or NULL if the bitmap doesn't know a view at this location.
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
restrictionsThe overlay restrictions flag
Return values
B_OKThe overlay restriction structure was found.
B_BAD_TYPEThe overlay restriction structure for the bitmap could not be found.
Since
Haiku R1

◆ ImportBits() [1/4]

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
dataThe data to be copied.
lengthThe length in bytes of the data to be copied.
bprThe number of bytes per row in the source data.
offsetThe offset (in bytes) relative to beginning of the bitmap data specifying the position at which the source data shall be written.
colorSpaceColor space of the source data.
Return values
B_OKThe bits were imported into the bitmap.
B_BAD_VALUENULL data, invalid bpr or offset, or unsupported colorSpace.
Since
Haiku R1

◆ ImportBits() [2/4]

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

Parameters
dataThe data to be copied.
lengthThe length in bytes of the data to be copied.
bprThe number of bytes per row in the source data.
colorSpaceColor space of the source data.
fromThe offset in the source where reading should begin.
toThe offset in the bitmap where the source should be written.
widthThe width (in pixels) to be imported.
heightThe height (in pixels) to be imported.
Return values
B_OKThe bits were imported into the bitmap.
B_BAD_VALUENULL data, invalid bpr, unsupported colorSpace or invalid width or height.
Since
Haiku R1

◆ ImportBits() [3/4]

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

Parameters
bitmapThe source bitmap.
Return values
B_OKThe bits were imported into the bitmap.
B_BAD_VALUENULL bitmap, or bitmap has other dimensions, or the conversion from or to one of the color spaces is not supported.
Since
Haiku R1

◆ ImportBits() [4/4]

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

Parameters
bitmapThe source bitmap.
fromThe offset in the source where reading should begin.
toThe offset in the bitmap where the source should be written.
widthThe width (in pixels) to be imported.
heightThe height (in pixels) to be imported.
Return values
B_OKThe bits were imported into the bitmap.
B_BAD_VALUENULL bitmap, the conversion from or to one of the color spaces is not supported, or invalid width or height.
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
dataThe 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
stateUnused
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
viewThe 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
dataThe data to be copied.
lengthThe length in bytes of the data to be copied.
offsetThe offset (in bytes) relative to beginning of the bitmap data specifying the position at which the source data shall be written.
colorSpaceColor 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