1/* 2 * Copyright 2011 Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Stefano Ceccherini, burton666@libero.it 7 * Axel Dörfler, axeld@pinc-software.de 8 * John Scipione, jscipione@gmail.com 9 * 10 * Corresponds to: 11 * headers/os/interface/Screen.h rev 42759 12 * src/kits/interface/Screen.cpp rev 42759 13 */ 14 15 16/*! 17 \file Screen.h 18 \ingroup interface 19 \ingroup libbe 20 \brief Defines the BScreen class and support structures. 21*/ 22 23 24/*! 25 \class BScreen 26 \ingroup interface 27 \ingroup libbe 28 \brief The BScreen class provides methods to retrieve and change display 29 settings. 30 31 Each BScreen object describes one display connected to the computer. 32 Multiple BScreen objects can represent the same physical display. 33 34 \attention Haiku currently supports only a single display. The main 35 screen with id \c B_MAIN_SCREEN_ID contains the origin in its top left 36 corner. Additional displays, when they become supported, will extend 37 the coordinates of the main screen. 38 39 Some utility methods provided by this class are ColorSpace() to get the 40 color space of the screen, Frame() to get the frame rectangle, and ID() 41 to get the identifier of the screen. 42 43 Methods to convert between 8-bit and 32-bit colors are provided by 44 IndexForColor() and ColorForIndex(). 45 46 You can also use this class to take a screenshot of the entire screen or 47 a particular portion of it. To take a screenshot use either the GetBitmap() 48 or ReadBitmap() method. 49 50 Furthermore, you can use this class get and set the background color of a 51 workspace. To get the background color call DesktopColor() or to set the 52 background color use SetDesktopColor(). 53 54 This class provides methods to get and set the resolution, pixel depth, 55 and color map of a display. To get a list of the display modes supported 56 by the graphics card use the GetModeList() method. You can get and set 57 the screen resolution by calling the GetMode() and SetMode() methods. 58 The color map of the display can be retrieved by calling the ColorMap() 59 method. 60 61 You can use this class to get information about the graphics card and 62 monitor connected to the computer by calling the GetDeviceInfo() and 63 GetMonitorInfo() methods. 64 65 VESA Display Power Management Signaling support allow you to put the 66 monitor into a low-power mode. Call DPMSCapabilites() to check what 67 modes are supported by your monitor. DPMSState() tells you what state 68 your monitor is currently in and SetDPMS() allows you to change it. 69*/ 70 71 72/*! 73 \fn BScreen::BScreen(screen_id id) 74 \brief Creates a BScreen object which represents the display 75 connected to the computer with the given screen_id. 76 77 In the current implementation, there is only one display 78 (\c B_MAIN_SCREEN_ID). To be sure that the object was constructed 79 correctly, call IsValid(). 80 81 \param id The screen_id of the screen to create a BScreen object from. 82*/ 83 84 85/*! 86 \fn BScreen::BScreen(BWindow* window) 87 \brief Creates a BScreen object which represents the display that 88 contains \a window. 89 90 In the current implementation, there is only one display 91 (\c B_MAIN_SCREEN_ID). To be sure that the object was constructed 92 correctly, call IsValid(). 93 94 \param window A BWindow object. 95*/ 96 97 98/*! 99 \fn BScreen::~BScreen() 100 \brief Frees the resources used by the BScreen object and unlocks the 101 screen. 102 103 \note The main screen object will never go away, even if you disconnect 104 all monitors. 105*/ 106 107 108/*! 109 \name Utility Methods 110*/ 111 112 113//! @{ 114 115 116/*! 117 \fn bool BScreen::IsValid() 118 \brief Checks that the BScreen object represents a real display that is 119 connected to the computer. 120 121 \return \c true if the BScreen object is valid, \c false otherwise. 122*/ 123 124 125/*! 126 \fn status_t BScreen::SetToNext() 127 \brief Sets the BScreen object to the next display in the screen list. 128 129 \return \c B_OK if successful, otherwise \c B_ERROR. 130*/ 131 132 133/*! 134 \fn color_space BScreen::ColorSpace() 135 \brief Gets the color_space of the display. 136 137 \return \c B_CMAP8, \c B_RGB15, \c B_RGB32, or \c B_NO_COLOR_SPACE 138 if the BScreen object is invalid. 139*/ 140 141 142/*! 143 \fn BRect BScreen::Frame() 144 \brief Gets the frame of the screen in the screen's coordinate system. 145 146 For example if the BScreen object points to the main screen with a 147 resolution of 1,366x768 then this method returns 148 BRect(0.0, 0.0, 1365.0, 767.0). If the BScreen object is invalid then 149 this method returns an empty rectangle i.e. BRect(0.0, 0.0, 0.0, 0.0) 150 151 You can set the frame programmatically by calling the SetMode() method. 152 153 \return a BRect frame of the screen in the screen's coordinate system. 154*/ 155 156 157/*! 158 \fn screen_id BScreen::ID() 159 \brief Gets the identifier of the display. 160 161 In the current implementation this method returns \c B_MAIN_SCREEN_ID 162 even if the object is invalid. 163 164 \return A screen_id that identifies the screen. 165*/ 166 167 168/*! 169 \fn status_t BScreen::WaitForRetrace() 170 \brief Blocks until the monitor has finished its current vertical retrace. 171 172 \return \c B_OK or \c B_ERROR if the screen object is invalid. 173*/ 174 175 176/*! 177 \fn status_t BScreen::WaitForRetrace(bigtime_t timeout) 178 \brief Blocks until the monitor has finished its current vertical retrace 179 or until \a timeout has expired. 180 181 \param timeout The amount of time to wait before returning. 182 183 \return \c B_OK if the monitor has retraced in the given \a timeout 184 duration, \c B_ERROR otherwise. 185*/ 186 187 188//! @} 189 190 191/*! 192 \name Color Methods 193*/ 194 195 196//! @{ 197 198 199/*! 200 \fn inline uint8 BScreen::IndexForColor(rgb_color color) 201 \brief Gets the 8-bit color index that most closely matches a 202 32-bit \a color. 203 204 \param color The 32-bit \a color to get the 8-bit index of. 205 206 \return An 8-bit color index in the screen's color_map. 207*/ 208 209 210/*! 211 \fn uint8 BScreen::IndexForColor(uint8 red, uint8 green, uint8 blue, 212 uint8 alpha) 213 \brief Gets the 8-bit color index that most closely matches a set of 214 \a red, \a green, \a blue, and \a alpha values. 215 216 \param red The \a red value. 217 \param green The \a green value. 218 \param blue The \a blue value. 219 \param alpha The \a alpha value. 220 221 \return An 8-bit color index in the screen's color_map. 222*/ 223 224 225/*! 226 \fn rgb_color BScreen::ColorForIndex(const uint8 index) 227 \brief Gets the 32-bit color representation of an 8-bit color \a index. 228 229 \param index The 8-bit color \a index to convert to a 32-bit color. 230 231 \return A 32-bit rgb_color structure. 232*/ 233 234 235/*! 236 \fn uint8 BScreen::InvertIndex(uint8 index) 237 \brief Gets the "Inversion" of an 8-bit color \a index. 238 239 Inverted colors are useful for highlighting. 240 241 \param index The 8-bit color \a index. 242 243 \return An 8-bit color \a index that represents the "Inversion" of the 244 given color in the screen's color_map. 245*/ 246 247 248/*! 249 \fn const color_map* BScreen::ColorMap() 250 \brief Gets the color_map of the BScreen. 251 252 \return A pointer to the BScreen object's color_map. 253*/ 254 255 256//! @} 257 258 259/*! 260 \name Bitmap Methods 261*/ 262 263 264//! @{ 265 266 267/*! 268 \fn status_t BScreen::GetBitmap(BBitmap** _bitmap, bool drawCursor, 269 BRect* bounds) 270 \brief Allocates a BBitmap and copies the contents of the screen into it. 271 272 \note GetBitmap() will allocate a BBitmap object for you while 273 ReadBitmap() requires you to pre-allocate a BBitmap object first. 274 275 \note The caller is responsible for freeing the BBitmap object. 276 277 \param _bitmap A pointer to a BBitmap pointer where this method will 278 store the contents of the display. 279 \param drawCursor Specifies whether or not to draw the cursor. 280 \param bounds Specifies the screen area that you want copied. If 281 \a bounds is \c NULL then the entire screen is copied. 282 283 \return \c B_OK if the operation was successful, \c B_ERROR otherwise. 284*/ 285 286 287/*! 288 \fn status_t BScreen::ReadBitmap(BBitmap* bitmap, bool drawCursor, 289 BRect* bounds) 290 \brief Copies the contents of the screen into a BBitmap. 291 292 \note ReadBitmap() requires you to pre-allocate a BBitmap object first, 293 while GetBitmap() will allocate a BBitmap object for you. 294 295 \param bitmap A pointer to a pre-allocated BBitmap where this 296 method will store the contents of the display. 297 \param drawCursor Specifies whether or not to draw the cursor. 298 \param bounds Specifies the screen area that you want copied. If 299 \a bounds is \c NULL then the entire screen is copied. 300 301 \return \c B_OK if the operation was successful, \c B_ERROR otherwise. 302*/ 303 304 305//! @} 306 307 308/*! 309 \name Desktop Color Methods 310*/ 311 312 313//! @{ 314 315 316/*! 317 \fn rgb_color BScreen::DesktopColor() 318 \brief Gets the background color of the current workspace. 319 320 \return A 32-bit rgb_color structure containing the background color 321 of the current workspace. 322*/ 323 324 325/*! 326 \fn rgb_color BScreen::DesktopColor(uint32 workspace) 327 \brief Gets the background color of the specified \a workspace. 328 329 \param workspace The \a workspace index to get the desktop background 330 color of. 331 332 \return An 32-bit rgb_color structure containing the background color 333 of the specified \a workspace. 334*/ 335 336 337/*! 338 \fn void BScreen::SetDesktopColor(rgb_color color, bool stick) 339 \brief Set the background \a color of the current workspace. 340 341 \param color The 32-bit \a color to paint the desktop background. 342 \param stick Whether or not the \a color will stay after a reboot. 343*/ 344 345 346/*! 347 \fn void BScreen::SetDesktopColor(rgb_color color, uint32 workspace, 348 bool stick) 349 \brief Set the background \a color of the specified \a workspace. 350 351 \param color The 32-bit \a color to paint the desktop background. 352 \param workspace The \a workspace index to update. 353 \param stick Whether or not the \a color will stay after a reboot. 354*/ 355 356 357//! @} 358 359 360/*! 361 \name Display Mode Methods 362 363 The following methods retrieve and alter the display_mode structure 364 of a screen. The display_mode structure contains screen size, 365 pixel depth, and display timings settings. 366*/ 367 368 369//! @{ 370 371 372/*! 373 \fn status_t BScreen::ProposeMode(display_mode* target, 374 const display_mode* low, 375 const display_mode* high) 376 \brief Adjust the \a target mode to make it a supported mode. 377 378 The list of supported modes for the graphics card is supplied by 379 the GetModeList() method. 380 381 \param target The mode you want adjust. 382 \param low The lower display mode limit. 383 \param high The higher display mode limit. 384 385 \retval B_OK if \a target is supported and falls within the 386 \a low and \a high limits. 387 \retval B_BAD_VALUE if \a target is supported but does not 388 fall within the \a low and \a high limits. 389 \retval B_ERROR if the target mode isn't supported. 390*/ 391 392 393/*! 394 \fn status_t BScreen::GetModeList(display_mode** _modeList, uint32* _count) 395 \brief Allocates and returns a list of the display modes supported by the 396 graphics card into \a _modeList. 397 398 \warning The monitor may not be able to display all of the modes that 399 GetModeList() retrieves. 400 401 \note The caller is responsible for freeing the display_mode object. 402 403 \param _modeList A pointer to a display_mode pointer, where the function 404 will allocate an array of display_mode structures. 405 \param _count A pointer to an integer used to store the count of 406 available display modes. 407 408 \retval B_OK if the operation was successful. 409 \retval B_ERROR if \a modeList or \a count is invalid. 410 \retval B_ERROR for all other errors. 411*/ 412 413 414/*! 415 \fn status_t BScreen::GetMode(display_mode* mode) 416 \brief Fills out the display_mode struct from the current workspace. 417 418 \param mode A pointer to a display_mode struct to copy into. 419 420 \retval B_OK if the operation was successful. 421 \retval B_BAD_VALUE if \a mode is invalid. 422 \retval B_ERROR for all other errors. 423*/ 424 425 426/*! 427 \fn status_t BScreen::GetMode(uint32 workspace, display_mode* mode) 428 \brief Fills out the display_mode struct from the specified 429 \a workspace. 430 431 \param workspace The index of the \a workspace to query. 432 \param mode A pointer to a display_mode structure to copy into. 433 434 \retval B_OK if the operation was successful 435 \retval B_BAD_VALUE if \a mode is invalid. 436 \retval B_ERROR for all other errors. 437*/ 438 439 440/*! 441 \fn status_t BScreen::SetMode(display_mode* mode, bool makeDefault) 442 \brief Sets the screen in the current workspace to the given \a mode. 443 444 \param mode A pointer to a display_mode struct. 445 \param makeDefault Whether or not \a mode is set as the default. 446 447 \return \c B_OK if the operation was successful, \c B_ERROR otherwise. 448*/ 449 450 451/*! 452 \fn status_t BScreen::SetMode(uint32 workspace, display_mode* mode, 453 bool makeDefault) 454 \brief Set the screen in the specified \a workspace to the given \a mode. 455 456 \param workspace The index of the workspace to set the \a mode of. 457 \param mode A pointer to a display_mode struct. 458 \param makeDefault Whether or not the \a mode is set as the default 459 for the specified \a workspace. 460 461 \return \c B_OK if the operation was successful, \c B_ERROR otherwise. 462*/ 463 464 465//! @} 466 467 468/*! 469 \name Display and Graphics Card Info Methods 470*/ 471 472 473//! @{ 474 475 476/*! 477 \fn status_t BScreen::GetDeviceInfo(accelerant_device_info* info) 478 \brief Fills out the \a info struct with information about a graphics card. 479 480 \param info An accelerant_device_info struct to store the device 481 \a info. 482 483 \retval B_OK if the operation was successful. 484 \retval B_BAD_VALUE if \a info is invalid. 485 \retval B_ERROR for all other errors. 486*/ 487 488 489/*! 490 \fn status_t BScreen::GetMonitorInfo(monitor_info* info) 491 \brief Fills out the \a info struct with information about a monitor. 492 493 \param info A monitor_info struct to store the monitor \a info. 494 495 \retval B_OK if the operation was successful. 496 \retval B_BAD_VALUE if \a info is invalid. 497 \retval B_ERROR for all other errors. 498*/ 499 500 501/*! 502 \fn status_t BScreen::GetPixelClockLimits(display_mode* mode, 503 uint32* _low, uint32* _high) 504 \brief Gets the minimum and maximum pixel clock rates that are possible 505 for the specified \a mode. 506 507 \param mode A pointer to a display_mode structure. 508 \param _low A pointer to a uint32 where the method stores the lowest 509 available pixel clock. 510 \param _high A pointer to a uint32 where the method stores the highest 511 available pixel clock. 512 513 \retval B_OK if the operation was successful. 514 \retval B_BAD_VALUE if \a mode, \a low, or \a high is invalid. 515 \retval B_ERROR for all other errors. 516*/ 517 518 519/*! 520 \fn status_t BScreen::GetTimingConstraints(display_timing_constraints* 521 constraints) 522 \brief Fills out the \a constraints structure with the timing constraints 523 of the current display mode. 524 525 \param constraints A pointer to a display_timing_constraints structure 526 to store the timing constraints. 527 528 \retval B_OK if the operation was successful. 529 \retval B_BAD_VALUE if \a constraints is invalid. 530 \retval B_ERROR for all other errors. 531*/ 532 533 534//! @} 535 536 537/*! 538 \name VESA Display Power Management Signaling Settings 539 540 VESA Display Power Management Signaling (or DPMS) is a standard from the 541 VESA consortium for managing the power usage of displays through the 542 graphics card. DPMS allows you to shut off the display after the computer 543 has been unused for some time to save power. 544 545 DPMS states include: 546 - \c B_DPMS_ON Normal display operation. 547 - \c B_DPMS_STAND_BY Image not visible normal operation and returns to 548 normal after ~1 second. 549 - \c B_DPMS_SUSPEND Image not visible, returns to normal after ~5 550 seconds. 551 - \c B_DPMS_OFF Image not visible, display is off except for power to 552 monitoring circuitry. Returns to normal after ~8-20 seconds. 553 554 Power usage in each of the above states depends on the monitor used. CRT 555 monitors typically receive larger power savings than LCD monitors in 556 low-power states. 557*/ 558 559 560//! @{ 561 562 563/*! 564 \fn status_t BScreen::SetDPMS(uint32 dpmsState) 565 \brief Sets the VESA Display Power Management Signaling (DPMS) state for 566 the display. 567 568 \param dpmsState The DPMS state to set. 569 valid values are: 570 - \c B_DPMS_ON 571 - \c B_DPMS_STAND_BY 572 - \c B_DPMS_SUSPEND 573 - \c B_DPMS_OFF 574 575 \return \c B_OK if the operation was successful, otherwise an error code. 576*/ 577 578 579/*! 580 \fn uint32 BScreen::DPMSState() 581 \brief Gets the current VESA Display Power Management Signaling (DPMS) 582 state of the screen. 583 584 \return The current VESA Display Power Management Signaling (DPMS) state 585 of the display or 0 in the case of an error. 586*/ 587 588 589 590/*! 591 \fn uint32 BScreen::DPMSCapabilites() 592 \brief Gets the VESA Display Power Management Signaling (DPMS) 593 modes that the display supports as a bit mask. 594 595 - \c B_DPMS_ON is worth 1 596 - \c B_DPMS_STAND_BY is worth 2 597 - \c B_DPMS_SUSPEND is worth 4 598 - \c B_DPMS_OFF is worth 8 599 600 \return A bit mask of the VESA Display Power Management Signaling (DPMS) 601 modes that the display supports or 0 in the case of an error. 602*/ 603 604 605//! @} 606 607 608/*! 609 \name Deprecated methods 610*/ 611 612 613//! @{ 614 615 616/*! 617 \fn BPrivate::BPrivateScreen* BScreen::private_screen() 618 \brief Returns the BPrivateScreen used by the BScreen object. 619 620 \return A pointer to the BPrivateScreen class internally used by the BScreen 621 object. 622*/ 623 624 625/*! 626 \fn status_t BScreen::ProposeDisplayMode(display_mode* target, 627 const display_mode* low, 628 const display_mode* high) 629 \brief Deprecated, use ProposeMode() instead. 630*/ 631 632 633/*! 634 \fn void* BScreen::BaseAddress() 635 \brief Returns the base address of the frame buffer. 636*/ 637 638 639/*! 640 \fn uint32 BScreen::BytesPerRow() 641 \brief Returns the bytes per row of the frame buffer. 642*/ 643 644 645//! @} 646