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

Public Member Functions
	BScreen (BWindow *window)
	Creates a BScreen object which represents the display that contains window.

	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.

	~BScreen ()
	Frees the resources used by the BScreen object and unlocks the screen.

Utility Methods
bool	IsValid ()
	Checks that the BScreen object represents a real display that is connected to the computer.

status_t	SetToNext ()
	Sets the BScreen object to the next display in the screen list.

color_space	ColorSpace ()
	Returns the color_space of the display.

BRect	Frame ()
	Gets the frame of the screen in the screen's coordinate system.

screen_id	ID ()
	Gets the identifier of the display.

status_t	WaitForRetrace ()
	Blocks until the monitor has finished its current vertical retrace.

status_t	WaitForRetrace (bigtime_t timeout)
	Blocks until the monitor has finished its current vertical retrace or until timeout has expired.

Color
uint8	IndexForColor (rgb_color color)
	Returns the 8-bit color index that most closely matches a 32-bit color.

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.

rgb_color	ColorForIndex (uint8 index)
	Gets the 32-bit color representation of an 8-bit color index.

uint8	InvertIndex (uint8 index)
	Gets the "Inversion" of an 8-bit color index.

const color_map *	ColorMap ()
	Gets the color_map of the BScreen.

Bitmap
status_t	GetBitmap (BBitmap *_bitmap, bool drawCursor=true, BRect frame=NULL)
	Allocates a BBitmap and copies the contents of the screen into it.

status_t	ReadBitmap (BBitmap bitmap, bool drawCursor=true, BRect frame=NULL)
	Copies the contents of the screen into a BBitmap.

Desktop Color
rgb_color	DesktopColor ()
	Gets the background color of the current workspace.

rgb_color	DesktopColor (uint32 workspace)
	Gets the background color of the specified workspace.

void	SetDesktopColor (rgb_color color, bool stick=true)
	Set the background color of the current workspace.

void	SetDesktopColor (rgb_color color, uint32 workspace, bool stick=true)
	Set the background color of the specified workspace.

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.

status_t	GetModeList (display_mode *_modeList, uint32 _count)
	Allocates and returns a list of the display modes supported by the graphics card into _modeList.

status_t	GetMode (display_mode *mode)
	Fills out the display_mode struct from the current workspace.

status_t	GetMode (uint32 workspace, display_mode *mode)
	Fills out the display_mode struct from the specified workspace.

status_t	SetMode (display_mode *mode, bool makeDefault=false)
	Sets the screen in the current workspace to the given mode.

status_t	SetMode (uint32 workspace, display_mode *mode, bool makeDefault=false)
	Set the screen in the specified workspace to the given mode.

Display and Graphics Card Info
status_t	GetDeviceInfo (accelerant_device_info *info)
	Fills out the info struct with information about a graphics card.

status_t	GetMonitorInfo (monitor_info *info)
	Fills out the info struct with information about a monitor.

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.

status_t	GetTimingConstraints (display_timing_constraints *timingConstraints)
	Fills out the constraints structure with the timing constraints of the current display mode.

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.

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

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

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

id	The 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

window A 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

index The 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

workspace The 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

_bitmap	A pointer to a BBitmap pointer where this method will store the contents of the display.
drawCursor	Specifies whether or not to draw the cursor.
bounds	Specifies 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

info	An accelerant_device_info struct to store the device info.

Return values

B_OK	if the operation was successful.
B_BAD_VALUE	if info is invalid.
B_ERROR	for 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

mode	A pointer to a display_mode struct to copy into.

Return values

B_OK	if the operation was successful.
B_BAD_VALUE	if mode is invalid.
B_ERROR	for 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

workspace	The index of the workspace to query.
mode	A pointer to a display_mode structure to copy into.

Return values

B_OK	if the operation was successful
B_BAD_VALUE	if mode is invalid.
B_ERROR	for 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

_modeList	A pointer to a display_mode pointer, where the function will allocate an array of display_mode structures.
_count	A pointer to an integer used to store the count of available display modes.

Return values

B_OK	if the operation was successful.
B_ERROR	for 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

info	A monitor_info struct to store the monitor info.

Return values

B_OK	if the operation was successful.
B_BAD_VALUE	if info is invalid.
B_ERROR	for 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

mode	A pointer to a display_mode structure.
_low	A pointer to a uint32 where the method stores the lowest available pixel clock.
_high	A pointer to a uint32 where the method stores the highest available pixel clock.

Return values

B_OK	if the operation was successful.
B_BAD_VALUE	if mode, low, or high is invalid.
B_ERROR	for 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

constraints A pointer to a display_timing_constraints structure to store the timing constraints.

Return values

B_OK	if the operation was successful.
B_BAD_VALUE	if constraints is invalid.
B_ERROR	for 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

color The 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

References rgb_color::alpha, rgb_color::blue, rgb_color::green, IndexForColor(), and rgb_color::red.

Referenced by IndexForColor().

◆ 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

red	The red value.
green	The green value.
blue	The blue value.
alpha	The 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

index The 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

target	The mode you want adjust.
low	The lower display mode limit.
high	The higher display mode limit.

Returns: A status code.

Return values

B_OK	if target is supported and falls within the low and high limits.
B_BAD_VALUE	if target is supported but does not fall within the low and high limits.
B_ERROR	if 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

bitmap	A pointer to a pre-allocated BBitmap where this method will store the contents of the display.
drawCursor	Specifies whether or not to draw the cursor.
bounds	Specifies 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

color	The 32-bit color to paint the desktop background.
stick	Whether 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

color	The 32-bit color to paint the desktop background.
workspace	The workspace index to update.
stick	Whether 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

dpmsState

The 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

mode	A pointer to a display_mode struct.
makeDefault	Whether 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

workspace	The index of the workspace to set the mode of.
mode	A pointer to a display_mode struct.
makeDefault	Whether 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

timeout The 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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ BScreen() [1/2]

◆ BScreen() [2/2]

◆ ~BScreen()

Member Function Documentation

◆ ColorForIndex()

◆ ColorMap()

◆ ColorSpace()

◆ DesktopColor() [1/2]

◆ DesktopColor() [2/2]

◆ DPMSCapabilites()

◆ DPMSState()

◆ Frame()

◆ GetBitmap()

◆ GetDeviceInfo()

◆ GetMode() [1/2]

◆ GetMode() [2/2]

◆ GetModeList()

◆ GetMonitorInfo()

◆ GetPixelClockLimits()

◆ GetTimingConstraints()

◆ ID()

◆ IndexForColor() [1/2]

◆ IndexForColor() [2/2]

◆ InvertIndex()

◆ IsValid()

◆ ProposeMode()

◆ ReadBitmap()

◆ SetDesktopColor() [1/2]

◆ SetDesktopColor() [2/2]

◆ SetDPMS()

◆ SetMode() [1/2]

◆ SetMode() [2/2]

◆ SetToNext()

◆ WaitForRetrace() [1/2]

◆ WaitForRetrace() [2/2]