# The Interface Kit: BScreen

Derived from: none

Declared in: be/interface/Screen.h

Library: libbe.so

## Overview

A BScreen object represents a screen, a monitor that's connected to the computer and the graphics card that serves the monitor. The object's main purpose is to provide information about the screen--its pixel dimensions, depth, color map, color space, and so on. However, it can also set one screen parameter, the background "desktop" color.

You can't copy a BScreen object. (The copy constructor and assignment operators are private.)

### 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

### Screen()

          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

### BaseAddress(), BytesPerRow()

          void *BaseAddress(void)

          uint32 BytesPerRow(void)

`BaseAddress()` returns the base address for the frame buffer for the screen and `BytesPerRow()` returns the number of bytes in the frame buffer for each row of pixel data. The count includes bytes that hold pixel values and possibly bytes at the end of each row to make sure the next row is aligned on an appropriate boundary.

These are dangerous functions. Although the BScreen object locks the current configuration of the screen, the screen itself is not locked. You cannot safely read from the frame buffer or write to it. Use the BWindowScreen class in the Game Kit to get direct access to the frame buffer.

See also: the BWindowScreen class in The Game Kit chapter

### 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

### 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).

### 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. (However, it's currently not implemented and always returns `B_ERROR` without blocking.)

The Be Book, in lovely HTML, for BeOS Release 3.

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.