Public Member Functions | List of all members
BScreen Class Reference

The BScreen class provides methods to retrieve and change display settings. More...

Public Member Functions

 BScreen (screen_id id=B_MAIN_SCREEN_ID)
 Creates a BScreen object which represents the display connected to the computer with the given screen_id. More...
 
 BScreen (BWindow *window)
 Creates a BScreen object which represents the display that contains window. More...
 
 ~BScreen ()
 Frees the resources used by the BScreen object and unlocks the screen. More...
 
Utility Methods
bool IsValid ()
 Checks that the BScreen object represents a real display that is connected to the computer. More...
 
status_t SetToNext ()
 Sets the BScreen object to the next display in the screen list. More...
 
color_space ColorSpace ()
 Returns the color_space of the display. More...
 
BRect Frame ()
 Gets the frame of the screen in the screen's coordinate system. More...
 
screen_id ID ()
 Gets the identifier of the display. More...
 
status_t WaitForRetrace ()
 Blocks until the monitor has finished its current vertical retrace. More...
 
status_t WaitForRetrace (bigtime_t timeout)
 Blocks until the monitor has finished its current vertical retrace or until timeout has expired. More...
 
Color
uint8 IndexForColor (rgb_color color)
 Returns the 8-bit color index that most closely matches a 32-bit color. More...
 
uint8 IndexForColor (uint8 red, uint8 green, uint8 blue, uint8 alpha=255)
 Returns the 8-bit color index that most closely matches a set of red, green, blue, and alpha values. More...
 
rgb_color ColorForIndex (uint8 index)
 Gets the 32-bit color representation of an 8-bit color index. More...
 
uint8 InvertIndex (uint8 index)
 Gets the "Inversion" of an 8-bit color index. More...
 
const color_map * ColorMap ()
 Gets the color_map of the BScreen. More...
 
Bitmap
status_t GetBitmap (BBitmap **_bitmap, bool drawCursor=true, BRect *frame=NULL)
 Allocates a BBitmap and copies the contents of the screen into it. More...
 
status_t ReadBitmap (BBitmap *bitmap, bool drawCursor=true, BRect *frame=NULL)
 Copies the contents of the screen into a BBitmap. More...
 
Desktop Color
rgb_color DesktopColor ()
 Gets the background color of the current workspace. More...
 
rgb_color DesktopColor (uint32 workspace)
 Gets the background color of the specified workspace. More...
 
void SetDesktopColor (rgb_color color, bool stick=true)
 Set the background color of the current workspace. More...
 
void SetDesktopColor (rgb_color color, uint32 workspace, bool stick=true)
 Set the background color of the specified workspace. More...
 
Display Mode

The following methods retrieve and alter the display_mode structure of a screen. The display_mode structure contains screen size, pixel depth, and display timings settings.

status_t ProposeMode (display_mode *target, const display_mode *low, const display_mode *high)
 Adjust the target mode to make it a supported mode. More...
 
status_t GetModeList (display_mode **_modeList, uint32 *_count)
 Allocates and returns a list of the display modes supported by the graphics card into _modeList. More...
 
status_t GetMode (display_mode *mode)
 Fills out the display_mode struct from the current workspace. More...
 
status_t GetMode (uint32 workspace, display_mode *mode)
 Fills out the display_mode struct from the specified workspace. More...
 
status_t SetMode (display_mode *mode, bool makeDefault=false)
 Sets the screen in the current workspace to the given mode. More...
 
status_t SetMode (uint32 workspace, display_mode *mode, bool makeDefault=false)
 Set the screen in the specified workspace to the given mode. More...
 
Display and Graphics Card Info
status_t GetDeviceInfo (accelerant_device_info *info)
 Fills out the info struct with information about a graphics card. More...
 
status_t GetMonitorInfo (monitor_info *info)
 Fills out the info struct with information about a monitor. More...
 
status_t GetPixelClockLimits (display_mode *mode, uint32 *_low, uint32 *_high)
 Gets the minimum and maximum pixel clock rates that are possible for the specified mode. More...
 
status_t GetTimingConstraints (display_timing_constraints *timingConstraints)
 Fills out the constraints structure with the timing constraints of the current display mode. More...
 
VESA Display Power Management Signaling Settings

VESA Display Power Management Signaling (or DPMS) is a standard from the VESA consortium for managing the power usage of displays through the graphics card. DPMS allows you to shut off the display after the computer has been unused for some time to save power.

DPMS states include:

  • B_DPMS_ON Normal display operation.
  • B_DPMS_STAND_BY Image not visible normal operation and returns to normal after ~1 second.
  • B_DPMS_SUSPEND Image not visible, returns to normal after ~5 seconds.
  • B_DPMS_OFF Image not visible, display is off except for power to monitoring circuitry. Returns to normal after ~8-20 seconds.

Power usage in each of the above states depends on the monitor used. CRT monitors typically receive larger power savings than LCD monitors in low-power states.

status_t SetDPMS (uint32 state)
 Sets the VESA Display Power Management Signaling (DPMS) state for the display. More...
 
uint32 DPMSState ()
 Gets the current VESA Display Power Management Signaling (DPMS) state of the screen. More...
 
uint32 DPMSCapabilites ()
 Gets the VESA Display Power Management Signaling (DPMS) modes that the display supports as a bit mask. More...
 

Detailed Description

The BScreen class provides methods to retrieve and change display settings.

Each BScreen object describes one display connected to the computer. Multiple BScreen objects can represent the same physical display.

Attention
Haiku currently supports only a single display. The main screen with id B_MAIN_SCREEN_ID contains the origin in its top left corner. Additional displays, when they become supported, will extend the coordinates of the main screen.

Some utility methods provided by this class are ColorSpace() to get the color space of the screen, Frame() to get the frame rectangle, and ID() to get the identifier of the screen.

Methods to convert between 8-bit and 32-bit colors are provided by IndexForColor() and ColorForIndex().

You can also use this class to take a screenshot of the entire screen or a particular portion of it. To take a screenshot use either the GetBitmap() or ReadBitmap() method.

Furthermore, you can use this class get and set the background color of a workspace. To get the background color call DesktopColor() or to set the background color use SetDesktopColor().

This class provides methods to get and set the resolution, pixel depth, and color map of a display. To get a list of the display modes supported by the graphics card use the GetModeList() method. You can get and set the screen resolution by calling the GetMode() and SetMode() methods. The color map of the display can be retrieved by calling the ColorMap() method.

You can use this class to get information about the graphics card and monitor connected to the computer by calling the GetDeviceInfo() and GetMonitorInfo() methods.

VESA Display Power Management Signaling support allow you to put the monitor into a low-power mode. Call DPMSCapabilites() to check what modes are supported by your monitor. DPMSState() tells you what state your monitor is currently in and SetDPMS() allows you to change it.

Since
BeOS R3

Constructor & Destructor Documentation

◆ BScreen() [1/2]

BScreen::BScreen ( screen_id  id = B_MAIN_SCREEN_ID)

Creates a BScreen object which represents the display connected to the computer with the given screen_id.

In the current implementation, there is only one display (B_MAIN_SCREEN_ID). To be sure that the object was constructed correctly, call IsValid().

Parameters
idThe screen_id of the screen to create a BScreen object from.
Since
BeOS R3

◆ BScreen() [2/2]

BScreen::BScreen ( BWindow window)

Creates a BScreen object which represents the display that contains window.

In the current implementation, there is only one display (B_MAIN_SCREEN_ID). To be sure that the object was constructed correctly, call IsValid().

Parameters
windowA BWindow object.
Since
BeOS R3

◆ ~BScreen()

BScreen::~BScreen ( )

Frees the resources used by the BScreen object and unlocks the screen.

Note
The main screen object will never go away, even if you disconnect all monitors.
Since
BeOS R3

Member Function Documentation

◆ ColorForIndex()

rgb_color BScreen::ColorForIndex ( uint8  index)

Gets the 32-bit color representation of an 8-bit color index.

Parameters
indexThe 8-bit color index to convert to a 32-bit color.
Returns
A 32-bit rgb_color structure.
Since
BeOS R3

◆ ColorMap()

const color_map * BScreen::ColorMap ( )

Gets the color_map of the BScreen.

Returns
A pointer to the BScreen object's color_map.
Since
BeOS R3

◆ ColorSpace()

color_space BScreen::ColorSpace ( )

Returns the color_space of the display.

Returns
B_CMAP8, B_RGB15, B_RGB32, or B_NO_COLOR_SPACE if the BScreen object is invalid.
Since
BeOS R3

◆ DesktopColor() [1/2]

rgb_color BScreen::DesktopColor ( )

Gets the background color of the current workspace.

Returns
A 32-bit rgb_color structure containing the background color of the current workspace.
Since
BeOS R3

◆ DesktopColor() [2/2]

rgb_color BScreen::DesktopColor ( uint32  workspace)

Gets the background color of the specified workspace.

Parameters
workspaceThe workspace index to get the desktop background color of.
Returns
An 32-bit rgb_color structure containing the background color of the specified workspace.
Since
Haiku R1

◆ DPMSCapabilites()

uint32 BScreen::DPMSCapabilites ( )

Gets the VESA Display Power Management Signaling (DPMS) modes that the display supports as a bit mask.

  • B_DPMS_ON is worth 1
  • B_DPMS_STAND_BY is worth 2
  • B_DPMS_SUSPEND is worth 4
  • B_DPMS_OFF is worth 8
Returns
A bit mask of the VESA Display Power Management Signaling (DPMS) modes that the display supports or 0 in the case of an error.
Since
BeOS R5

◆ DPMSState()

uint32 BScreen::DPMSState ( )

Gets the current VESA Display Power Management Signaling (DPMS) state of the screen.

Returns
The current VESA Display Power Management Signaling (DPMS) state of the display or 0 in the case of an error.
Since
BeOS R5

◆ Frame()

BRect BScreen::Frame ( )

Gets the frame of the screen in the screen's coordinate system.

For example if the BScreen object points to the main screen with a resolution of 1,366x768 then this method returns BRect(0.0, 0.0, 1365.0, 767.0). If the BScreen object is invalid then this method returns an empty rectangle i.e. BRect(0.0, 0.0, 0.0, 0.0)

You can set the frame programmatically by calling the SetMode() method.

Returns
a BRect frame of the screen in the screen's coordinate system.
Since
BeOS R3

◆ GetBitmap()

status_t BScreen::GetBitmap ( BBitmap **  _bitmap,
bool  drawCursor = true,
BRect bounds = NULL 
)

Allocates a BBitmap and copies the contents of the screen into it.

Note
GetBitmap() will allocate a BBitmap object for you while ReadBitmap() requires you to pre-allocate a BBitmap object first.
The caller is responsible for freeing the BBitmap object.
Parameters
_bitmapA pointer to a BBitmap pointer where this method will store the contents of the display.
drawCursorSpecifies whether or not to draw the cursor.
boundsSpecifies the screen area that you want copied. If bounds is NULL then the entire screen is copied.
Returns
B_OK if the operation was successful, B_ERROR otherwise.
Since
BeOS R4

◆ GetDeviceInfo()

status_t BScreen::GetDeviceInfo ( accelerant_device_info *  info)

Fills out the info struct with information about a graphics card.

Parameters
infoAn accelerant_device_info struct to store the device info.
Return values
B_OKif the operation was successful.
B_BAD_VALUEif info is invalid.
B_ERRORfor all other errors.
Since
BeOS R5

◆ GetMode() [1/2]

status_t BScreen::GetMode ( display_mode *  mode)

Fills out the display_mode struct from the current workspace.

Parameters
modeA pointer to a display_mode struct to copy into.
Return values
B_OKif the operation was successful.
B_BAD_VALUEif mode is invalid.
B_ERRORfor all other errors.
Since
BeOS R5

◆ GetMode() [2/2]

status_t BScreen::GetMode ( uint32  workspace,
display_mode *  mode 
)

Fills out the display_mode struct from the specified workspace.

Parameters
workspaceThe index of the workspace to query.
modeA pointer to a display_mode structure to copy into.
Return values
B_OKif the operation was successful
B_BAD_VALUEif mode is invalid.
B_ERRORfor all other errors.
Since
Haiku R1

◆ GetModeList()

status_t BScreen::GetModeList ( display_mode **  _modeList,
uint32 *  _count 
)

Allocates and returns a list of the display modes supported by the graphics card into _modeList.

Warning
The monitor may not be able to display all of the modes that GetModeList() retrieves.
Note
The caller is responsible for freeing the display_mode object.
Parameters
_modeListA pointer to a display_mode pointer, where the function will allocate an array of display_mode structures.
_countA pointer to an integer used to store the count of available display modes.
Return values
B_OKif the operation was successful.
B_ERRORif modeList or count is invalid.
B_ERRORfor all other errors.
Since
BeOS R5

◆ GetMonitorInfo()

status_t BScreen::GetMonitorInfo ( monitor_info *  info)

Fills out the info struct with information about a monitor.

Parameters
infoA monitor_info struct to store the monitor info.
Return values
B_OKif the operation was successful.
B_BAD_VALUEif info is invalid.
B_ERRORfor all other errors.
Since
Haiku R1

◆ GetPixelClockLimits()

status_t BScreen::GetPixelClockLimits ( display_mode *  mode,
uint32 *  _low,
uint32 *  _high 
)

Gets the minimum and maximum pixel clock rates that are possible for the specified mode.

Parameters
modeA pointer to a display_mode structure.
_lowA pointer to a uint32 where the method stores the lowest available pixel clock.
_highA pointer to a uint32 where the method stores the highest available pixel clock.
Return values
B_OKif the operation was successful.
B_BAD_VALUEif mode, low, or high is invalid.
B_ERRORfor all other errors.
Since
BeOS R5

◆ GetTimingConstraints()

status_t BScreen::GetTimingConstraints ( display_timing_constraints *  constraints)

Fills out the constraints structure with the timing constraints of the current display mode.

Parameters
constraintsA pointer to a display_timing_constraints structure to store the timing constraints.
Return values
B_OKif the operation was successful.
B_BAD_VALUEif constraints is invalid.
B_ERRORfor all other errors.
Since
BeOS R5

◆ ID()

screen_id BScreen::ID ( )

Gets the identifier of the display.

In the current implementation this method returns B_MAIN_SCREEN_ID even if the object is invalid.

Returns
A screen_id that identifies the screen.
Since
BeOS R3

◆ IndexForColor() [1/2]

uint8 BScreen::IndexForColor ( rgb_color  color)
inline

Returns the 8-bit color index that most closely matches a 32-bit color.

Parameters
colorThe 32-bit color to get the 8-bit index of.
Returns
An 8-bit color index in the screen's color_map.
Since
BeOS R3

◆ IndexForColor() [2/2]

uint8 BScreen::IndexForColor ( uint8  red,
uint8  green,
uint8  blue,
uint8  alpha = 255 
)

Returns the 8-bit color index that most closely matches a set of red, green, blue, and alpha values.

Parameters
redThe red value.
greenThe green value.
blueThe blue value.
alphaThe alpha value.
Returns
An 8-bit color index in the screen's color_map.
Since
BeOS R3

◆ InvertIndex()

uint8 BScreen::InvertIndex ( uint8  index)

Gets the "Inversion" of an 8-bit color index.

Inverted colors are useful for highlighting.

Parameters
indexThe 8-bit color index.
Returns
An 8-bit color index that represents the "Inversion" of the given color in the screen's color_map.
Since
BeOS R3

◆ IsValid()

bool BScreen::IsValid ( )

Checks that the BScreen object represents a real display that is connected to the computer.

Returns
true if the BScreen object is valid, false otherwise.
Since
BeOS R3

◆ ProposeMode()

status_t BScreen::ProposeMode ( display_mode *  target,
const display_mode *  low,
const display_mode *  high 
)

Adjust the target mode to make it a supported mode.

The list of supported modes for the graphics card is supplied by the GetModeList() method.

Parameters
targetThe mode you want adjust.
lowThe lower display mode limit.
highThe higher display mode limit.
Returns
A status code.
Return values
B_OKif target is supported and falls within the low and high limits.
B_BAD_VALUEif target is supported but does not fall within the low and high limits.
B_ERRORif the target mode isn't supported.
Since
BeOS R5

◆ ReadBitmap()

status_t BScreen::ReadBitmap ( BBitmap bitmap,
bool  drawCursor = true,
BRect bounds = NULL 
)

Copies the contents of the screen into a BBitmap.

Note
ReadBitmap() requires you to pre-allocate a BBitmap object first, while GetBitmap() will allocate a BBitmap object for you.
Parameters
bitmapA pointer to a pre-allocated BBitmap where this method will store the contents of the display.
drawCursorSpecifies whether or not to draw the cursor.
boundsSpecifies the screen area that you want copied. If bounds is NULL then the entire screen is copied.
Returns
B_OK if the operation was successful, B_ERROR otherwise.
Since
BeOS R4

◆ SetDesktopColor() [1/2]

void BScreen::SetDesktopColor ( rgb_color  color,
bool  stick = true 
)

Set the background color of the current workspace.

Parameters
colorThe 32-bit color to paint the desktop background.
stickWhether or not the color will stay after a reboot.
Since
BeOS R3

◆ SetDesktopColor() [2/2]

void BScreen::SetDesktopColor ( rgb_color  color,
uint32  workspace,
bool  stick = true 
)

Set the background color of the specified workspace.

Parameters
colorThe 32-bit color to paint the desktop background.
workspaceThe workspace index to update.
stickWhether or not the color will stay after a reboot.
Since
Haiku R1

◆ SetDPMS()

status_t BScreen::SetDPMS ( uint32  dpmsState)

Sets the VESA Display Power Management Signaling (DPMS) state for the display.

Parameters
dpmsStateThe DPMS state to set, valid values are:
  • B_DPMS_ON
  • B_DPMS_STAND_BY
  • B_DPMS_SUSPEND
  • B_DPMS_OFF
Returns
B_OK if the operation was successful, otherwise an error code.
Since
BeOS R5

◆ SetMode() [1/2]

status_t BScreen::SetMode ( display_mode *  mode,
bool  makeDefault = false 
)

Sets the screen in the current workspace to the given mode.

Parameters
modeA pointer to a display_mode struct.
makeDefaultWhether or not mode is set as the default.
Returns
B_OK if the operation was successful, B_ERROR otherwise.
Since
BeOS R5

◆ SetMode() [2/2]

status_t BScreen::SetMode ( uint32  workspace,
display_mode *  mode,
bool  makeDefault = false 
)

Set the screen in the specified workspace to the given mode.

Parameters
workspaceThe index of the workspace to set the mode of.
modeA pointer to a display_mode struct.
makeDefaultWhether or not the mode is set as the default for the specified workspace.
Returns
B_OK if the operation was successful, B_ERROR otherwise.
Since
Haiku R1

◆ SetToNext()

status_t BScreen::SetToNext ( )

Sets the BScreen object to the next display in the screen list.

Returns
B_OK if successful, otherwise B_ERROR.
Since
BeOS R5

◆ WaitForRetrace() [1/2]

status_t BScreen::WaitForRetrace ( )

Blocks until the monitor has finished its current vertical retrace.

Returns
B_OK or B_ERROR if the screen object is invalid.
Since
BeOS R3

◆ WaitForRetrace() [2/2]

status_t BScreen::WaitForRetrace ( bigtime_t  timeout)

Blocks until the monitor has finished its current vertical retrace or until timeout has expired.

Parameters
timeoutThe amount of time to wait before returning.
Returns
B_OK if the monitor has retraced in the given timeout duration, B_ERROR otherwise.
Since
BeOS R5