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