Multiple Screens
Currently, the BeOS supports only one screen. However, in the future, it will allow you to hook up more than one monitor to your computer. One of the screens, the main screen, will have the origin of the screen coordinate system at its left top corner. Other screens will be located elsewhere in the same coordinate system. If there's just one screen, it's the main screen.
A BScreen object represents just one screen. An application can have more than one object referring to the same screen, but you'll need a different BScreen object for each screen you want to query.
When multiple screens are supported, a screen_id identifier will be assigned to each one. Currently, B_MAIN_SCREEN_ID is the only identifier.
Locking and Allocation
When a BScreen object is constructed, it locks the screen in its current configuration, preventing all changes (except to the desktop color). The screen is unlocked when the object is destroyed, unless another BScreen object still has it locked. Therefore, you should keep a BScreen object for as short a period as possible, only until it has finished revealing the information you need. BScreen objects should not be cached or dynamically allocated. Allocate one on the stack each time you need information about the screen and make sure it's in a block of code that won't linger for long.
If a BScreen object is being used to get just one piece of information about the screen, it can be constructed anonymously (without assigning it to a variable). For example:
BRect screenRect = BScreen(myWindow).Frame();
However, anonymous construction doesn't mean that the object goes away after its single use. The normal rules of engagement for static construction apply--the object will be destroyed when the flow of execution leaves the braces that enclose the block of code it's in.
Constructor and Destructor
BScreen()
BScreen(BWindow *window)
BScreen(screen_id id = B_MAIN_SCREEN_ID)
Initializes the BScreen object so that it represents the screen where window is displayed or the screen identified by id. If window is NULL, the window is hidden, or the id is invalid, the BScreen will represent the main screen (which is currently the only possibility anyway).
Since multiple monitors are not currently supported, there's no API for getting screen identifiers other than for the main screen.
Constructing a BScreen object locks the screen configuration; the user won't be able to change its depth or resolution until the object is destroyed. Therefore, you should keep the object for only as brief a time as possible. It's best to construct it statically in a block of code that will be executed quickly.
To be sure the new object was correctly constructed, call IsValid().
See also: IsValid()
~BScreen()
~BScreen()
Unlocks the screen and invalidates the BScreen object.
Member Functions
ColorForIndex() see IndexForColor()
ColorMap()
const color_map* ColorMap(void)
Returns a pointer to the color map for the screen. The color map defines the set of 256 colors that can be displayed in the B_CMAP8 color space. A single set of colors is shared by all applications that display on the screen.
The color_map structure is defined in interface/GraphicsDefs.h and contains the following fields:
int32 id
An identifier that the Application Server uses to distinguish one color map from another.
rgb_color color_list[256]
A list of the 256 colors, expressed as rgb_color structures. Indices into the list can be used to specify colors in the B_CMAP8 color space. See IndexForColor().
uint8 inversion_map[256]
A mapping of each color in the color_list to its opposite color. Indices are mapped to indices. An example of how this map might be used is given below.
uint8 index_map[32768]
An array that maps RGB colors--specified using 5 bits per component--to their nearest counterparts in the color list. An example of how to use this map is also given below.
The inversion_map is a list of indices into the color_list where each index locates the "inversion" of the original color. The inversion of the nth color in color_list would be found as follows:
BScreen screen; const color_map *map = screen.ColorMap(); uint8 inversionIndex = map->inversion_map[n]; rgb_color inversionColor = map->color_list[inversionIndex];
Inverting an inverted index returns the original index, so this code
uint8 color = map->inversion_map[inversionIndex];
would return n. The InvertIndex() function is an alternative to indexing into the inversion_map in this way, though it carries the overhead of a function call for each operation.
Inverted colors are used, primarily, for highlighting. Given a color, its highlight complement is its inversion.
The index_map maps every RGB combination that can be expressed in 15 bits (5 bits per component) to a single color_list index that best approximates the original RGB data. The following example demonstrates how to squeeze 24-bit RGB data into a 15-bit number that can be used as an index into the index_map:
long rgb15 = ( ((red & 0xf8) << 7) |
((green & 0xf8) << 2) |
((blue & 0xf8) >> 3) );
Most applications won't need to use the index map directly; the IndexForColor() function performs the same conversion with less fuss (no masking and shifting required). However, applications that implement repetitive graphic operations, such as dithering, may want to access the index map themselves, and thus avoid the overhead of an additional function call.
You should never modify or free the color_map structure returned by this function; it belongs to the BScreen object.
See also: IndexForColor(), system_colors()
ColorSpace()
color_space ColorSpace(void)
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 under the control of the user and the Screen preferences application.
See also: "Colors" near the beginning of this chapter for an explanation of the various color spaces
DesktopColor() see SetDesktopColor()
Frame()
BRect Frame(void)
Returns the rectangle that locates the screen in the screen coordinate system and defines its dimensions. For example, a screen with a resolution of 1,024 pixels * 768 pixels would have a frame rectangle with both its left and top sides at 0.0 (assuming it's the main screen), its right side at 1,023.0, and its bottom at 767.0.
If the BScreen object is invalid, all sides of the rectangle are set to 0.0.
See also: the BRect class
GetBitmap() see ReadBitmap()
ID()
screen_id ID(void)
Returns the identifier for the screen, which for the main screen (currently the only screen) should be B_MAIN_SCREEN_ID.
The screen_id is not persistent. A new one may be assigned each time the machine is rebooted or a monitor is disconnected then reconnected.
This function currently returns B_MAIN_SCREEN_ID even if the BScreen object is invalid.
IndexForColor(), ColorForIndex()
inline uint8 IndexForColor(rgb_color color)
uint8 IndexForColor(uint8 red, uint8 green, uint8 blue, uint8 alpha = 0)
rgb_color ColorForIndex(const uint8 index)
IndexForColor() returns an index into the list of 256 colors that comprise the 8-bit color space for the screen. The value returned picks out the listed color that most closely matches a full 32-bit color--specified either as an rgb_color value or by its red, green, and blue components. (The alpha component is currently ignored.)
The returned index identifies a color in the B_CMAP8 color space. It can, for example, be passed to BBitmap's SetBits() function to set the color of a bitmap pixel. If the color is B_TRANSPARENT_32_BIT, the return value will be B_TRANSPARENT_8_BIT.
To find the fully specified color that an index picks out, you can call ColorForIndex() or you can get the color list for the screen and find the color directly. For example, if you first obtain the index for the "best fit" color that most closely matches an arbitrary color,
BScreen screen; uint8 index = screen.IndexForColor(134, 210, 6);
you can then pass the index to ColorForIndex(),
rgb_color bestFit = screen.ColorForIndex(index);
or you can use the index to locate that color in the color list:
rgb_color bestFit = screen.ColorMap()->color_list[index];
Neither method will correctly translate B_TRANSPARENT_8_BIT to B_TRANSPARENT_32_BIT.
See also: ColorMap(), the BBitmap class
InvertIndex()
uint8 InvertIndex(uint8 index)
Returns the index to the color that's the inversion (or exact opposite) of the index color passed as an argument. Both the return value and the argument specify colors in the B_CMAP8 color space. Inverting an inverted color returns the original color. For example:
uint8 inversion = InvertIndex(colorIndex); uint8 inversionOfInversion = InvertIndex(inversion); ASSERT(inversionOfInversion == colorIndex);
This function is an alternative to getting the color map and looking at the inversion_map yourself.
See also: ColorMap()
IsValid()
bool IsValid(void)
Returns true if the BScreen object is valid (if it represents a real screen connected to the computer), and false if not (for example, if the screen has been disconnected).
ReadBitmap(), GetBitmap()
status_t ReadBitmap(BBitmap *buffer,
bool draw_cursor = true,
BRect *bound = NULL)
status_t GetBitmap(BBitmap **screen_shot,
bool draw_cursor = true,
BRect *bound = NULL)
These methods provide read access to the contents of the screen. ReadBitmap() places the contents in a user-supplied BBitmap buffer, while GetBitmap() allocates a new BBitmap, returning its address in screen_shot. The draw_cursor parameter determines whether the cursor is drawn in the screen shot while the bound parameter can be used to specify, in screen coordinates, the region to be read into the bitmap. bound may be NULL, in which case the entire screen is read.
These methods return B_NO_ERROR on success or B_ERROR on failure (typically due to bad bound coordinates. The caller is responsible for freeing the BBitmap created by GetBitmap().
SetDesktopColor(), DesktopColor()
void SetDesktopColor(rgb_color color, bool makeDefault = true)
rgb_color DesktopColor(void)
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.
Typically, users choose the desktop color with the Screen preferences application. Other applications can look at the desktop color, but should not set it.
WaitForRetrace()
status_t WaitForRetrace(void)
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 done (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.
 |
This function is currently not implemented and always returns B_ERROR without blocking. |
The Be Book, in lovely HTML, for BeOS Release 4.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified December 23, 1998.