docs/user/interface/Screen.dox

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