1/* 2 * Copyright 2011 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Axel Dörfler, axeld@pinc-software.de 7 * John Scipione, jscipione@gmail.com 8 * 9 * Corresponds to: 10 * headers/os/interface/Bitmap.h rev 42274 11 * src/kits/interface/Bitmap.cpp rev 42274 12 */ 13 14 15/*! 16 \file Bitmap.h 17 \ingroup interface 18 \ingroup libbe 19 \brief Defines the BBitmap class and global operators and functions for 20 handling bitmaps. 21*/ 22 23 24/*! 25 \class BBitmap 26 \ingroup interface 27 \ingroup libbe 28 \brief Access and manipulate digital images commonly known as bitmaps. 29 30 A BBitmap is a rectangular map of pixel data. The BBitmap class allows you 31 to create a bitmap by specifying its pixel data and has operations for 32 altering and accessing the properties of bitmaps. 33 34 To create a BBitmap object use one of the constructor methods below. You 35 can determine if initialization was successful by calling the InitCheck() 36 method. You can determine if a BBitmap object is valid at any time by 37 calling the IsValid() method. 38 39 An example of creating a new 32x32 pixel BBitmap object and assigning the 40 icon of the current application looks like this: 41 42\code 43BBitmap iconBitmap = new BBitmap(BRect(0, 0, 31, 31), B_RGBA32)); 44appFileInfo.GetIcon(iconBitmap, B_LARGE_ICON); 45\endcode 46 47 You can access the properties of a bitmap by calling the Bounds(), 48 Flags(), ColorSpace(), Area(), Bits(), BitsLength(), BytesPerRow(), 49 and GetOverlayRestrictions() methods. 50 51 To directly set the pixel data of a bitmap call the Bits() or SetBits() 52 methods or you can use the ImportBits() method to copy the bits from an 53 existing bitmap. 54 55 You can also draw into a bitmap by attaching a child BView to the bitmap. 56 To add and remove child BView's to a bitmap call the AddChild() and 57 RemoveChild() methods respectively. You can access the child views of a 58 bitmap by calling the CountChildren(), ChildAt(), and FindView() methods. 59 60 For off-screen bitmaps it is important to lock the bitmap before drawing 61 the pixels and then unlock the bitmap when you are done to prevent 62 flickering. To lock and unlock a bitmap call the LockBits() and UnLockBits() 63 methods respectively. To lock and unlock the off-screen window that a 64 bitmap resides in you should call the Lock() and UnLock() methods. To 65 determine is a bitmap is currently locked you can call the IsLocked() 66 method. 67 68 \since BeOS R3 69*/ 70 71 72/*! 73 \fn BBitmap::BBitmap(BRect bounds, uint32 flags, color_space colorSpace, 74 int32 bytesPerRow, screen_id screenID) 75 \brief Creates and initializes a BBitmap object. 76 77 \param bounds The bitmap dimensions. 78 \param flags Creation flags. 79 \param colorSpace The bitmap's color space. 80 \param bytesPerRow The number of bytes per row the bitmap should use. 81 \c B_ANY_BYTES_PER_ROW to let the constructor choose an appropriate 82 value. 83 \param screenID ??? 84 85 \since Haiku R1 86*/ 87 88 89/*! 90 \fn BBitmap::BBitmap(BRect bounds, color_space colorSpace, 91 bool acceptsViews, bool needsContiguous) 92 \brief Creates and initializes a BBitmap object. 93 94 \param bounds The bitmap dimensions. 95 \param colorSpace The bitmap's color space. 96 \param acceptsViews \c true, if the bitmap shall accept BViews, i.e. if 97 it shall be possible to attach BView to the bitmap and draw into 98 it. 99 \param needsContiguous If \c true a physically contiguous chunk of memory 100 will be allocated. 101 102 \since BeOS R3 103*/ 104 105 106/*! 107 \fn BBitmap::BBitmap(const BBitmap* source, bool acceptsViews, 108 bool needsContiguous) 109 \brief Creates a BBitmap object as a clone of another bitmap. 110 111 \param source The source bitmap. 112 \param acceptsViews \c true, if the bitmap shall accept BViews, i.e. if 113 it shall be possible to attach BView to the bitmap and draw into 114 it. 115 \param needsContiguous If \c true a physically contiguous chunk of memory 116 will be allocated. 117 118 \since Haiku R1 119*/ 120 121 122/*! 123 \fn BBitmap::BBitmap(const BBitmap& source, uint32 flags) 124 \brief Creates a BBitmap object as a clone of another bitmap. 125 126 \param source The source bitmap. 127 \param flags Creation flags. 128 129 \since Haiku R1 130*/ 131 132 133/*! 134 \fn BBitmap::BBitmap(const BBitmap& source) 135 \brief Creates a BBitmap object as a clone of another bitmap. 136 137 \param source The source bitmap. 138 139 \since Haiku R1 140*/ 141 142 143/*! 144 \fn BBitmap::BBitmap(BMessage* data) 145 \brief Unarchives a bitmap from a BMessage. 146 147 \param data The archive. 148 149 \since BeOS R3 150*/ 151 152 153/*! 154 \fn BBitmap::~BBitmap() 155 \brief Destructor Method 156 157 Frees all resources associated with this object. 158 159 \since BeOS R3 160*/ 161 162 163/*! 164 \name Archiving 165*/ 166 167 168//! @{ 169 170 171/*! 172 \fn BArchivable* BBitmap::Instantiate(BMessage* data) 173 \brief Instantiates a BBitmap from an archive. 174 175 \param data The archive. 176 \return A bitmap reconstructed from the archive or \c NULL if an error 177 occurred. 178 179 \since BeOS R3 180*/ 181 182 183/*! 184 \fn status_t BBitmap::Archive(BMessage* data, bool deep) const 185 \brief Archives the BBitmap object. 186 187 \param data The archive. 188 \param deep if \c true, child object will be archived as well. 189 190 \return \c B_OK, if everything went fine, an error code otherwise. 191 192 \since BeOS R3 193*/ 194 195 196//! @} 197 198 199/*! 200 \fn status_t BBitmap::InitCheck() const 201 \brief Gets the status of the constructor. 202 203 \returns B_OK if initialization succeeded, otherwise returns an 204 error status. 205 206 207 \since Haiku R1 208*/ 209 210 211/*! 212 \fn bool BBitmap::IsValid() const 213 \brief Determines whether or not the BBitmap object is valid. 214 215 \return \c true, if the object is properly initialized, \c false otherwise. 216 217 \since BeOS R3 218*/ 219 220 221/*! 222 \name Locking 223*/ 224 225 226//! @{ 227 228 229/*! 230 \fn status_t BBitmap::LockBits(uint32* state) 231 \brief Locks the bitmap bits so that they cannot be relocated. 232 233 This is currently only used for overlay bitmaps; whenever you 234 need to access their Bits() you must lock them first. 235 On resolution change overlay bitmaps can be relocated in memory; 236 using this call prevents you from accessing an invalid pointer 237 and clobbering memory that doesn't belong you. 238 239 \param state Unused 240 \returns \c B_OK on success or an error status code. 241 242 \since Haiku R1 243*/ 244 245 246/*! 247 \fn void BBitmap::UnlockBits() 248 \brief Unlocks the bitmap's buffer. 249 250 Counterpart to BBitmap::LockBits(). 251 252 \since Haiku R1 253*/ 254 255 256/*! 257 \fn bool BBitmap::Lock() 258 \brief Locks the off-screen window that belongs to the bitmap. 259 260 The bitmap must accept views, if locking should work. 261 262 \returns \c true, if the lock was acquired successfully. 263 264 \since BeOS R3 265*/ 266 267 268/*! 269 \fn void BBitmap::Unlock() 270 \brief Unlocks the off-screen window that belongs to the bitmap. 271 272 The bitmap must accept views, if locking should work. 273 274 \since BeOS R3 275*/ 276 277 278/*! 279 \fn bool BBitmap::IsLocked() const 280 \brief Determines whether or not the bitmap's off-screen window is locked. 281 282 The bitmap must accept views, if locking should work. 283 284 \return \c true, if the caller owns a lock , \c false otherwise. 285 286 \since BeOS R4 287*/ 288 289 290//! @} 291 292 293/*! 294 \name Accessors 295*/ 296 297 298//! @{ 299 300 301/*! 302 \fn area_id BBitmap::Area() const 303 \brief Gets the ID of the area the bitmap data reside in. 304 305 \return The ID of the area the bitmap data reside in. 306 307 \since Haiku R1 308*/ 309 310 311/*! 312 \fn void* BBitmap::Bits() const 313 \brief Gets the pointer to the bitmap data. 314 315 \return The pointer to the bitmap data. 316 317 \since BeOS R3 318*/ 319 320 321/*! 322 \fn int32 BBitmap::BitsLength() const 323 \brief Gets the length of the bitmap data. 324 325 \return The length of the bitmap data as an int32. 326 327 \since BeOS R3 328*/ 329 330 331/*! 332 \fn int32 BBitmap::BytesPerRow() const 333 \brief Gets the number of bytes used to store a row of bitmap data. 334 335 \return The number of bytes used to store a row of bitmap data. 336 337 \since BeOS R3 338*/ 339 340 341/*! 342 \fn color_space BBitmap::ColorSpace() const 343 \brief Gets the bitmap's color space. 344 345 \return The bitmap's color space. 346 347 \since BeOS R3 348*/ 349 350 351/*! 352 \fn BRect BBitmap::Bounds() const 353 \brief Gets a BRect the size of the bitmap's dimensions. 354 355 \return A BRect the size of the bitmap's dimensions. 356 357 \since BeOS R3 358*/ 359 360 361/*! 362 \fn uint32 BBitmap::Flags() const 363 \brief Accesses the bitmap's creation flags. 364 365 This method informs about which flags have been used to create the 366 bitmap. It would for example tell you wether this is an overlay 367 bitmap. If bitmap creation succeeded, all flags are fulfilled. 368 369 \return The bitmap's creation flags. 370 371 \since Haiku R1 372*/ 373 374 375/*! 376 \fn status_t BBitmap::GetOverlayRestrictions( 377 overlay_restrictions* restrictions) const 378 \brief Gets the overlay_restrictions structure for this bitmap. 379 380 \param restrictions The overlay restrictions flag 381 382 \retval B_OK The overlay restriction structure was found. 383 \retval B_BAD_TYPE The overlay restriction structure for the bitmap could 384 not be found. 385 386 \since Haiku R1 387*/ 388 389 390//! @} 391 392 393/*! 394 \name Setters 395*/ 396 397 398//! @{ 399 400 401/*! 402 \fn void BBitmap::SetBits(const void* data, int32 length, int32 offset, 403 color_space colorSpace) 404 \brief Assigns data to the bitmap. 405 406 Data are directly written into the bitmap's data buffer, being converted 407 beforehand, if necessary. Some conversions do not work intuitively: 408 - \c B_RGB32: The source buffer is supposed to contain \c B_RGB24_BIG 409 data without padding at the end of the rows. 410 - \c B_RGB32: The source buffer is supposed to contain \c B_CMAP8 411 data without padding at the end of the rows. 412 - other color spaces: The source buffer is supposed to contain data 413 according to the specified color space being padded to int32 row-wise. 414 415 The currently supported source/target color spaces are 416 <code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and 417 <code>B_GRAY{8,1}</code>. 418 419 \note Since this methods is a bit strange to use, Haiku has introduced 420 the ImportBits() method which is the recommended replacement. 421 422 \param data The data to be copied. 423 \param length The length in bytes of the data to be copied. 424 \param offset The offset (in bytes) relative to beginning of the bitmap 425 data specifying the position at which the source data shall be 426 written. 427 \param colorSpace Color space of the source data. 428 429 \since BeOS R3 430*/ 431 432 433/*! 434 \fn status_t BBitmap::ImportBits(const void* data, int32 length, int32 bpr, 435 int32 offset, color_space colorSpace) 436 \brief Assigns data to the bitmap. 437 438 Data are directly written into the bitmap's data buffer, being converted 439 beforehand, if necessary. Unlike for SetBits(), the meaning of 440 \a colorSpace is exactly the expected one here, i.e. the source buffer 441 is supposed to contain data of that color space. \a bpr specifies how 442 many bytes the source contains per row. \c B_ANY_BYTES_PER_ROW can be 443 supplied, if standard padding to int32 is used. 444 445 The currently supported source/target color spaces are 446 <code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and 447 <code>B_GRAY{8,1}</code>. 448 449 \param data The data to be copied. 450 \param length The length in bytes of the data to be copied. 451 \param bpr The number of bytes per row in the source data. 452 \param offset The offset (in bytes) relative to beginning of the bitmap 453 data specifying the position at which the source data shall be 454 written. 455 \param colorSpace Color space of the source data. 456 457 \retval B_OK The bits were imported into the bitmap. 458 \retval B_BAD_VALUE \c NULL \a data, invalid \a bpr or \a offset, or 459 unsupported \a colorSpace. 460 461 \since Haiku R1 462*/ 463 464 465/*! 466 \fn status_t BBitmap::ImportBits(const void* data, int32 length, 467 int32 bpr, color_space colorSpace, BPoint from, BPoint to, 468 int32 width, int32 height) 469 \brief Assigns data to the bitmap. 470 471 Allows for a BPoint offset in the source and in the bitmap. The region 472 of the source at \a from extending \a width and \a height is assigned 473 (and converted if necessary) to the bitmap at \a to. 474 475 The currently supported source/target color spaces are 476 <code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and 477 <code>B_GRAY{8,1}</code>. 478 479 \param data The data to be copied. 480 \param length The length in bytes of the data to be copied. 481 \param bpr The number of bytes per row in the source data. 482 \param colorSpace Color space of the source data. 483 \param from The offset in the source where reading should begin. 484 \param to The offset in the bitmap where the source should be written. 485 \param width The width (in pixels) to be imported. 486 \param height The height (in pixels) to be imported. 487 488 \retval B_OK The bits were imported into the bitmap. 489 \retval B_BAD_VALUE: \c NULL \a data, invalid \a bpr, unsupported 490 \a colorSpace or invalid \a width or \a height. 491 492 \since Haiku R1 493*/ 494 495 496/*! 497 \fn status_t BBitmap::ImportBits(const BBitmap* bitmap) 498 \brief Assigns another bitmap's data to this bitmap. 499 500 The supplied bitmap must have the exactly same dimensions as this bitmap. 501 Its data is converted to the color space of this bitmap. 502 503 The currently supported source/target color spaces are 504 <code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and 505 <code>B_GRAY{8,1}</code>. 506 507 \param bitmap The source bitmap. 508 509 \retval B_OK The bits were imported into the bitmap. 510 \retval B_BAD_VALUE \c NULL \a bitmap, or \a bitmap has other dimensions, 511 or the conversion from or to one of the color spaces is not supported. 512 513 \since Haiku R1 514*/ 515 516 517/*! 518 \fn status_t BBitmap::ImportBits(const BBitmap* bitmap, BPoint from, 519 BPoint to,int32 width, int32 height) 520 \brief Assigns data to the bitmap. 521 522 Allows for a BPoint offset in the source and in the bitmap. The region 523 of the source at \a from extending \a width and \a height is assigned 524 (and converted if necessary) to the bitmap at \a to. The source bitmap is 525 clipped to the bitmap and they don't need to have the same dimensions. 526 527 The currently supported source/target color spaces are 528 <code>B_RGB{32,24,16,15}[_BIG]</code>, \c B_CMAP8 and 529 <code>B_GRAY{8,1}</code>. 530 531 \param bitmap The source bitmap. 532 \param from The offset in the source where reading should begin. 533 \param to The offset in the bitmap where the source should be written. 534 \param width The width (in pixels) to be imported. 535 \param height The height (in pixels) to be imported. 536 537 \retval B_OK The bits were imported into the bitmap. 538 \retval B_BAD_VALUE \c NULL \a bitmap, the conversion from or to one of 539 the color spaces is not supported, or invalid \a width or \a height. 540 541 \since Haiku R1 542*/ 543 544 545//! @} 546 547 548/*! 549 \name View Hierarchy 550*/ 551 552 553//! @{ 554 555 556/*! 557 \fn void BBitmap::AddChild(BView* view) 558 \brief Adds a BView to the bitmap's view hierarchy. 559 560 The bitmap must accept views and the supplied view must not be child of 561 another parent. 562 563 \param view The view to be added. 564 565 \since BeOS R3 566*/ 567 568 569/*! 570 \fn bool BBitmap::RemoveChild(BView* view) 571 \brief Removes a BView from the bitmap's view hierarchy. 572 573 \param view The view to be removed. 574 575 \since BeOS R3 576*/ 577 578 579/*! 580 \fn int32 BBitmap::CountChildren() const 581 \brief Gets the number of BViews currently belonging to the bitmap. 582 583 \returns The number of BViews currently belonging to the bitmap. 584 585 \since BeOS R3 586*/ 587 588 589/*! 590 \fn BView* BBitmap::ChildAt(int32 index) const 591 \brief Gets the BView at a certain index in the bitmap's list of views. 592 593 \param index The index of the BView to be returned. 594 \returns The BView at index \a index or \c NULL if the index is out of 595 range. 596 597 \since BeOS R3 598*/ 599 600 601/*! 602 \fn BView* BBitmap::FindView(const char* viewName) const 603 \brief Accesses a bitmap's child BView with a the name \a viewName. 604 605 \param viewName The name of the BView to be returned. 606 \returns The BView with the name \a name or \c NULL if the bitmap doesn't 607 know a view with that name. 608 609 \since BeOS R3 610*/ 611 612 613/*! 614 \fn BView* BBitmap::FindView(BPoint point) const 615 \brief Accesses a bitmap's BView at a certain location. 616 617 \param point The location. 618 \returns The BView with located at \a point or \c NULL if the bitmap 619 doesn't know a view at this location. 620 621 \since BeOS R3 622*/ 623 624 625//! @} 626