Initializes the BScreen object so that it represents the screen where window is displayed or the screen identified by id. If window is NULL or hidden, or if the id is invalid, the BScreen will represent the main screen.

Note

Since multiple monitors aren't currently supported, there's no API for screen identifiers other than for the main screen.

To be sure the new object was correctly constructed, call IsValid().

Unlocks the screen and invalidates the BScreen object.

These functions return information from the color_map structure for this screen. The color_map structure defines the set of 256 colors that can be displayed in an B_CMAP8 color space. A single color_map is shared by all applications that display on the same screen. See the color_map structure for more information about the structure.

ColorMap() returns a pointer to the color_map itself. The structure belongs to the BScreen object; you can't modify or free it. (Note that the the system_colors() function retrieves the color_map structure for the main screen without reference to a BScreen object.)

IndexForColor() returns the "index" of the 8-bit color that, in this screen's color map, most closely matches the given 32-bit color. You can pass the index to functions such BBitmap::SetBits() to set an 8-bit color. Note that IndexForColor() knows how to convert B_TRANSPARENT_32_BIT into B_TRANSPARENT_8_BIT.

ColorForIndex() returns the 32-bit color representation of a given 8-bit color index. This function doesn't convert B_TRANSPARENT_8_BIT into B_TRANSPARENT_32_BIT.

InvertIndex() takes an 8-bit index and returns an index that represents the color's "inversion." Inverted colors are typically used for highlighting.

Important

The information gained through IndexForColor(), ColorForIndex(), and InvertIndex() can be retrieved more efficiently from the color_map structure. If you're repeatedly calling these functions, you should consider accessing the color_map structure, instead. Note, however, that the intelligent B_TRANSPARENT_32_BIT to B_TRANSPARENT_8_BIT conversion is not supported by the structure.

Returns the color space of the screen display—typically B_CMAP8, B_RGB15, or B_RGB32—or B_NO_COLOR_SPACE if the BScreen object is invalid.

The color space is set by the user through the Screen preferences application. You can set it programatically through the SetMode() function.

Returns the rectangle that locates the screen in the screen coordinate system. For example, the frame for a 1,024 * 768 main screen looks like this:

BRect(0.0, 0.0, 1023.0, 767.0)

If the BScreen object is invalid, all sides of the rectangle are set to 0.0.

The screen's frame rectangle is set by the user through the Screen preferences application. You can set it programatically through the SetMode() function.

Returns information about the graphics card.

These functions set and get the screen's display mode. Each display_mode structure (defined in add-ons/graphics/Accelerant.h) is a distinct combination of screen size, pixel depth, and display timing.

GetModeList() allocates and returns, in mode_list, a list of the display_mode structures that the graphics card is guaranteed to support; count is set to the number of display_mode elements in the list. The caller is responsible for freeing mode_list.

Warning

There's no guarantee that the monitor can support all of the modes that GetModeList() retrieves.

SetMode() resets the screen to the given mode. If makeDefault is true, the mode becomes the default for the current workspace.

GetMode() copies the current display_mode into mode.

The display_mode structure is:

typedef struct {
      display_timing timing;
      uint32 space;
      uint16 virtual_width;
      uint16 virtual_height;
      uint16 h_display_start;
      uint16 v_display_start;
      uint32 flags;
} display_mode;

The display_timing structure is:

typedef struct {
      uint32 pixel_clock;
      uint16 h_display;
      uint16 h_sync_start;
      uint16 h_sync_end;
      uint16 h_total;
      uint16 v_display;
      uint16 h_display;
      uint16 v_sync_start;
      uint16 v_sync_end;
      uint16 v_total;
      uint32 flags;
} display_timing;

See also: ProposeMode()

This function returns, in low and high, the minimum and maximum "pixel clock" rates (in thousands-of-pixels per second) that are possible for the given mode. Given the pixel clock and a display mode, you can determine the refresh rate range by dividing the pixel clock by the "real" size of the screen, thus:

uint32 hi_clock, lo_clock;
float hi_refresh, lo_refresh;
float real_size;
display_mode mode;

GetMode(&mode);
GetPixelClockLimits(&mode, &lo_clock, &hi_clock);

/* The real screen dimensions (i.e. the dimensions for the purposes
* of the gun) are given by the 'timing.h_total' and
* 'timing.v_total' fields.
*/
total_size = mode.timing.h_total * mode.timing.v_total

/* Get the refresh rate by dividing the pixel clock by the total
* screen size. Remember -- the pixel clock values are given in
* kHz; we multiply by 1000.0 to retrieve refresh rates in Hz.
*/
hi_refresh = ((float) hi_clock*1000.0)/(float) total_size;
lo_refresh = ((float) lo_clock*1000.0)/(float) total_size;

This function fills out the dtc structure with the timing constraints of the current display mode.

Returns the identifier for the screen. The main screen is identified as B_MAIN_SCREEN_ID.

The ID isn't presistent across boots, and may change if the monitor is diconnected and then reconnected.

Warning

Currently, this function always returns B_MAIN_SCREEN_ID, even if the BScreen object is invalid.

Returns true if the BScreen object is valid (if it represents a real screen connected to the computer), and false if not.

ProposeMode() is a convenience function that attempts to adjust candidate so that it's a supported mode (as listed by the GetModeList() function). It then compares the possibly-adjusted candidate to the limits declared in low and high and expresses this comparison in the return value. Note that the function doesn't adjust candidate so that it is, of necessity, between low and high.

Exactly how ProposeMode() works is up to the individual graphics driver. It's expected that the function will adjust candidate's screen size fields while holding the color space constant.

Note

This function was formerly called ProposeDisplayMode().

These functions provide read-only access to the screen by copying the screen's contents into the first argument BBitmap. The difference between them is that ReadBitmap() expects you to allocate the BBitmap before passing it in, while GetBitmap() allocates a new BBitmap for you. The caller is responsible for freeing the BBitmap allocated by GetBitmap().

The draw_cursor argument determines whether the cursor is drawn in the screen shot; bounds let you specify the region, in screen coordinates, that you want copied. If bounds is NULL, the entire screen is copied. The functions fail if the bounds rectangle doesn't fall wholly within the screen's frame.

The functions return B_OK on success or B_ERROR on failure.

These functions set and return the color of the desktop—the backdrop against which windows are displayed on the screen. SetDesktopColor() makes an immediate change in the desktop color displayed on-screen; DesktopColor() returns the color currently displayed.

If the makeDefault flag is true, the color that's set becomes the default color for the screen; it's the color that will be shown the next time the machine is booted. If the flag is false, the color is set only for the current session.

Note

The "Background Images" section tells you how to convince the desktop to display a bitmap image.

Typically, users choose the desktop color with the Screen preferences application.

SetDPMS() lets you set the VESA Display Power Management Signaling state for the screen. The state can be one of the following values:

DPMSState() returns the current display state, indicating whether the monitor is on or off or in one of the two sleep modes.

DPMSCapabilities() indicates which of the above modes the monitor supports.

In the current BeOS release, this function always returns B_ERROR.

Blocks until the monitor has finished the current vertical retrace, then returns B_OK. There are a few milliseconds available before it begins another retrace. Drawing changes made to the frame buffer in this period won't cause any "flicker" on-screen.

For some graphics card drivers, this function will wait for vertical sync; for others it will wait until vertical blank, providing a few extra milliseconds.

The timeout argument lets you provide a timeout in microseconds—if the screen hasn't retraced within the limit, the function returns B_ERROR.