xref: /haiku/docs/user/interface/Bitmap.dox (revision 984f843b917a1c4e077915c5961a6ef1cf8dabc7)

/*
 * Copyright 2011 Haiku, Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *		Axel Dörfler, axeld@pinc-software.de
 *		John Scipione, jscipione@gmail.com
 *
 * Corresponds to:
 *		headers/os/interface/Bitmap.h	 rev 42274
 *		src/kits/interface/Bitmap.cpp	 rev 42274
 */


/*!
	\file Bitmap.h
	\ingroup interface
	\ingroup libbe
	\brief Defines the BBitmap class and global operators and functions for
	       handling bitmaps.
*/


/*!
	\class BBitmap
	\ingroup interface
	\ingroup libbe
	\brief 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:

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

	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
*/


/*!
	\fn BBitmap::BBitmap(BRect bounds, uint32 flags, color_space colorSpace,
		int32 bytesPerRow, screen_id screenID)
	\brief Creates and initializes a BBitmap object.

	\param bounds The bitmap dimensions.
	\param flags Creation flags.
	\param colorSpace The bitmap's color space.
	\param bytesPerRow The number of bytes per row the bitmap should use.
		   \c B_ANY_BYTES_PER_ROW to let the constructor choose an appropriate
		   value.
	\param screenID Currently unused. May be used for multi-monitor support in
		   the future.

	\since Haiku R1
*/


/*!
	\fn BBitmap::BBitmap(BRect bounds, color_space colorSpace,
		bool acceptsViews, bool needsContiguous)
	\brief Creates and initializes a BBitmap object.

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

	\since BeOS R3
*/


/*!
	\fn BBitmap::BBitmap(const BBitmap* source, bool acceptsViews,
		bool needsContiguous)
	\brief Creates a BBitmap object as a clone of another bitmap.

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

	\since Haiku R1
*/


/*!
	\fn BBitmap::BBitmap(const BBitmap& source, uint32 flags)
	\brief Creates a BBitmap object as a clone of another bitmap.

	\param source The source bitmap.
	\param flags Creation flags.

	\since Haiku R1
*/


/*!
	\fn BBitmap::BBitmap(const BBitmap& source)
	\brief Creates a BBitmap object as a clone of another bitmap.

	\param source The source bitmap.

	\since Haiku R1
*/


/*!
	\fn BBitmap::BBitmap(area_id area, ptrdiff_t areaOffset,
		BRect bounds, uint32 flags, color_space colorSpace,
		int32 bytesPerRow, screen_id screenID)
	\brief 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.

	\param area The memory area to use
	\param areaOffset Offset within the memory area to place bitmap.
	\param bounds The bitmap dimensions.
	\param flags Creation flags.
	\param colorSpace The bitmap's color space.
	\param bytesPerRow The number of bytes per row the bitmap should use.
		   \c B_ANY_BYTES_PER_ROW to let the constructor choose an appropriate
		   value.
	\param screenID Currently unused. May be used for multi-monitor support in
		   the future.

	\since Haiku R1
*/


/*!
	\fn BBitmap::BBitmap(BMessage* data)
	\brief Unarchives a bitmap from a BMessage.

	\param data The archive.

	\since BeOS R3
*/


/*!
	\fn BBitmap::~BBitmap()
	\brief Destructor Method

	Frees all resources associated with this object.

	\since BeOS R3
*/


/*!
	\name Archiving
*/


//! @{


/*!
	\fn BArchivable* BBitmap::Instantiate(BMessage* data)
	\brief Instantiates a BBitmap from an archive.

	\param data The archive.
	\return A bitmap reconstructed from the archive or \c NULL if an error
	        occurred.

	\since BeOS R3
*/


/*!
	\fn status_t BBitmap::Archive(BMessage* data, bool deep) const
	\brief Archives the BBitmap object.

	\param data The archive.
	\param deep if \c true, child object will be archived as well.

	\return \c B_OK, if everything went fine, an error code otherwise.

	\since BeOS R3
*/


//! @}


/*!
	\fn status_t BBitmap::InitCheck() const
	\brief Gets the status of the constructor.

	\returns B_OK if initialization succeeded, otherwise returns an
	         error status.


	\since Haiku R1
*/


/*!
	\fn bool BBitmap::IsValid() const
	\brief Determines whether or not the BBitmap object is valid.

	\return \c true, if the object is properly initialized, \c false otherwise.

	\since BeOS R3
*/


/*!
	\name Locking
*/


//! @{


/*!
	\fn status_t BBitmap::LockBits(uint32* state)
	\brief 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.

	\param state Unused
	\returns \c B_OK on success or an error status code.

	\since Haiku R1
*/


/*!
	\fn void BBitmap::UnlockBits()
	\brief Unlocks the bitmap's buffer.

	Counterpart to BBitmap::LockBits().

	\since Haiku R1
*/


/*!
	\fn bool BBitmap::Lock()
	\brief Locks the off-screen window that belongs to the bitmap.

	The bitmap must accept views, if locking should work.

	\returns \c true, if the lock was acquired successfully.

	\since BeOS R3
*/


/*!
	\fn void BBitmap::Unlock()
	\brief Unlocks the off-screen window that belongs to the bitmap.

	The bitmap must accept views, if locking should work.

	\since BeOS R3
*/


/*!
	\fn bool BBitmap::IsLocked() const
	\brief Determines whether or not the bitmap's off-screen window is locked.

	The bitmap must accept views, if locking should work.

	\return \c true, if the caller owns a lock , \c false otherwise.

	\since BeOS R4
*/


//! @}


/*!
	\name Accessors
*/


//! @{


/*!
	\fn area_id BBitmap::Area() const
	\brief Gets the ID of the area the bitmap data reside in.

	\return The ID of the area the bitmap data reside in.

	\since Haiku R1
*/


/*!
	\fn void* BBitmap::Bits() const
	\brief Gets the pointer to the bitmap data.

	\return The pointer to the bitmap data.

	\since BeOS R3
*/


/*!
	\fn int32 BBitmap::BitsLength() const
	\brief Gets the length of the bitmap data.

	\return The length of the bitmap data as an int32.

	\since BeOS R3
*/


/*!
	\fn int32 BBitmap::BytesPerRow() const
	\brief Gets the number of bytes used to store a row of bitmap data.

	\return The number of bytes used to store a row of bitmap data.

	\since BeOS R3
*/


/*!
	\fn color_space BBitmap::ColorSpace() const
	\brief Gets the bitmap's color space.

	\return The bitmap's color space.

	\since BeOS R3
*/


/*!
	\fn BRect BBitmap::Bounds() const
	\brief Gets a BRect the size of the bitmap's dimensions.

	\return A BRect the size of the bitmap's dimensions.

	\since BeOS R3
*/


/*!
	\fn uint32 BBitmap::Flags() const
	\brief 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.

	\return The bitmap's creation flags.

	\since Haiku R1
*/


/*!
	\fn status_t BBitmap::GetOverlayRestrictions(
		overlay_restrictions* restrictions) const
	\brief Gets the overlay_restrictions structure for this bitmap.

	\param restrictions The overlay restrictions flag

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

	\since Haiku R1
*/


//! @}


/*!
	\name Setters
*/


//! @{


/*!
	\fn void BBitmap::SetBits(const void* data, int32 length, int32 offset,
		color_space colorSpace)
	\brief 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:
	- \c B_RGB32: The source buffer is supposed to contain \c B_RGB24_BIG
	  data without padding at the end of the rows.
	- \c B_RGB32: The source buffer is supposed to contain \c 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
	<code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and
	<code>B_GRAY{8,1}</code>.

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

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

	\since BeOS R3
*/


/*!
	\fn status_t BBitmap::ImportBits(const void* data, int32 length, int32 bpr,
		int32 offset, color_space colorSpace)
	\brief 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
	\a colorSpace is exactly the expected one here, i.e. the source buffer
	is supposed to contain data of that color space. \a bpr specifies how
	many bytes the source contains per row. \c B_ANY_BYTES_PER_ROW can be
	supplied, if standard padding to int32 is used.

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

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

	\retval B_OK The bits were imported into the bitmap.
	\retval B_BAD_VALUE \c NULL \a data, invalid \a bpr or \a offset, or
	        unsupported \a colorSpace.

	\since Haiku R1
*/


/*!
	\fn status_t BBitmap::ImportBits(const void* data, int32 length,
		int32 bpr, color_space colorSpace, BPoint from, BPoint to,
		int32 width, int32 height)
	\brief Assigns data to the bitmap.

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

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

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

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

	\since Haiku R1
*/


/*!
	\fn status_t BBitmap::ImportBits(const BBitmap* bitmap)
	\brief 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
	<code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and
	<code>B_GRAY{8,1}</code>.

	\param bitmap The source bitmap.

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

	\since Haiku R1
*/


/*!
	\fn status_t BBitmap::ImportBits(const BBitmap* bitmap, BPoint from,
		BPoint to,int32 width, int32 height)
	\brief Assigns data to the bitmap.

	Allows for a BPoint offset in the source and in the bitmap. The region
	of the source at \a from extending \a width and \a height is assigned
	(and converted if necessary) to the bitmap at \a 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
	<code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and
	<code>B_GRAY{8,1}</code>.

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

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

	\since Haiku R1
*/


//! @}


/*!
	\name View Hierarchy
*/


//! @{


/*!
	\fn void BBitmap::AddChild(BView* view)
	\brief 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.

	\param view The view to be added.

	\since BeOS R3
*/


/*!
	\fn bool BBitmap::RemoveChild(BView* view)
	\brief Removes a BView from the bitmap's view hierarchy.

	\param view The view to be removed.

	\since BeOS R3
*/


/*!
	\fn int32 BBitmap::CountChildren() const
	\brief Gets the number of BViews currently belonging to the bitmap.

	\returns The number of BViews currently belonging to the bitmap.

	\since BeOS R3
*/


/*!
	\fn BView* BBitmap::ChildAt(int32 index) const
	\brief Gets the BView at a certain index in the bitmap's list of views.

	\param index The index of the BView to be returned.
	\returns The BView at index \a index or \c NULL if the index is out of
		range.

	\since BeOS R3
*/


/*!
	\fn BView* BBitmap::FindView(const char* viewName) const
	\brief Accesses a bitmap's child BView with the name \a viewName.

	\param viewName The name of the BView to be returned.
	\returns The BView with the name \a name or \c NULL if the bitmap doesn't
		know a view with that name.

	\since BeOS R3
*/


/*!
	\fn BView* BBitmap::FindView(BPoint point) const
	\brief Accesses a bitmap's BView at a certain location.

	\param point The location.
	\returns The BView with located at \a point or \c NULL if the bitmap
		doesn't know a view at this location.

	\since BeOS R3
*/


//! @}