The Game Kit: BWindowScreen

The Game Kit Table of Contents | The Game Kit Index

# BWindowScreen

Derived from: public BWindow

Declared in: be/game/WindowScreen.h

Library: libgame.so

###### Summary

A BWindowScreen object provides exclusive access to the entire screen, bypassing the Application Server's window system. The object has direct access to the graphics card driver: It can set up the graphics environment on the graphics card, call driver-implemented drawing functions, and directly manipulate the frame buffer.

### Screen Access

Like all windows, a BWindowScreen is hidden (off-screen) when it's constructed. By calling `Show()` to put it on-screen and make it the active window, an application takes over the whole screen. While the BWindowScreen is active, the Application Server's graphics operations are suspended—this means that you can't use any BView functions, nor any functions in classes derived from BView; you have to draw directly into the screen's frame buffer, and nothing except what the application draws will be visible to the user—no other windows and no desktop. When the BWindowScreen gives up active status, the Application Server automatically refreshes the screen with its old contents.

Although the BWindowScreen object provides a connection to the screen, you shouldn't draw from the BWindowScreen's thread. Use the thread only to regulate the access of other threads to the frame buffer.

### Keyboard and Mouse

A BWindowScreen object remains a window while it has control of the screen; it stays attached to the Application Server and its message loop continues to function. It gets messages reporting the user's actions on the keyboard and mouse, just like any other active window. Because it covers the whole screen, it's notified of all mouse and keyboard events. You can attach filters to the window to get the messages as they arrive. Or you can call the Interface Kit's `get_key_info()` function to poll the state of the keyboard and construct a nominal BView so that you can call `GetMouse()` to poll the mouse.

### Workspaces

This class respects workspaces. A BWindowScreen object releases its grip on the screen when the user turns to another workspace and reestablishes its control when the user returns to the workspace in which it's the active window.

### Debugging

A BWindowScreen object can be constructed in a debugging mode that lets you switch back and forth between the workspace in which the game is running and a workspace where error messages are printed. See the constructor and the `RegisterThread()` function for details.

## Hook Functions

`ScreenConnected()`
Can be implemented to do whatever is necessary when the BWindowScreen object obtains direct access to the frame buffer for the screen, and when it loses that access.

## Constructor and Destructor

### BWindowScreen()

`BWindowScreen(`const char *title, uint32 space, status_t *error, bool debugging = false`)`

Initializes the BWindowScreen object by assigning the window a title and specifying a space configuration for the screen. The window won't have a visible border or a tab in which to display the title to the user. However, others—such as the Workspaces application—can use the title to identify the window.

The window is constructed to fill the screen; its frame rectangle contains every screen pixel when the screen is configured according to the space argument. That argument describes the pixel dimensions and bits-per-pixel depth of the screen that the BWindowScreen object should establish when it obtains direct access to the frame buffer. It should be one of the following constants:

`B_8_BIT_640x480` | `B_16_BIT_640x480` | `B_32_BIT_640x480`
`B_8_BIT_800x600` | `B_16_BIT_800x600` | `B_32_BIT_800x600`
`B_8_BIT_1024x768` | `B_16_BIT_1024x768` | `B_32_BIT_1024x768`
`B_8_BIT_1152x900` | `B_16_BIT_1152x900` | `B_32_BIT_1152x900`
`B_8_BIT_1280x1024` | `B_16_BIT_1280x1024` | `B_32_BIT_1280x1024`
`B_8_BIT_1600x1200` | `B_16_BIT_1600x1200` | `B_32_BIT_1600x1200`

These are the same constants that can be passed to `set_screen_space()`, the Interface Kit function that preference applications call to configure the screen.

The space configuration applies only while the BWindowScreen object is in control of the screen. When it gives up control, the previous configuration is restored.

The constructor assigns the window to the active workspace (`B_CURRENT_WORKSPACE`). It fails if another BWindowScreen object in any application is already assigned to the same workspace.

To be sure there wasn't an error in constructing the object, check the error argument. If all goes well, the constructor sets the error variable to `B_OK`. If not, it sets it to `B_ERROR`. If there's an error, it's likely to occur in this constructor, not the inherited BWindow constructor. Since the underlying window will probably exist, you'll need to instruct it to quit. For example:

       status_t error;
       MyWindowScreen *screen =
                    new MyWindowScreen("Glacier", B_8_BIT_1024x768, &error);
       if ( error != B_OK )
           screen->PostMessage(B_QUIT_REQUESTED, screen);

If the debugging flag is `true`, the BWindowScreen is constructed in debugging mode. This modifies its behavior and enables three functions, `RegisterThread()`, `Suspend()`, and `SuspensionHook()`. The debugging regime is described under those functions.

See also: `RegisterThread()`, the BScreen class in the Interface Kit

### ~BWindowScreen()

virtual `~BWindowScreen() `

Closes the clone of the graphics card driver (through which the BWindowScreen object established its connection to the screen), unloads it from the application, and cleans up after it.

## Member Functions

### CanControlFrameBuffer()

bool `CanControlFrameBuffer(`void`) `

Returns `true` if the graphics card driver permits applications to control the configuration of the frame buffer, and `false` if not. Control is exercised through these two functions:

| `SetFrameBuffer()` `MoveDisplayArea()`

A return of `true` means that these functions can communicate with the graphics card driver and at least the first will do something useful. A return of `false` means that neither of them will work.

See also: `SetFrameBuffer()`, `MoveDisplayArea()`

### CardHookAt()

graphics_card_hook `CardHookAt(`int32 index`) `

Returns a pointer to the graphics card "hook" function that's located at index in its list of hook functions. The function returns `NULL` if the graphics card driver doesn't implement a function at that index or the index is out of range.

The hook functions provide accelerated drawing capabilities. They're documented under "Graphics Card Hook Functions". The first three hook functions (indices 0, 1, and 2) are not available through the Game Kit; if you pass an index of 0, 1, or 2 to `CardHookAt()`, it will return `NULL` even if the function is implemented.

An application can cache the pointers that `CardHookAt()` returns, but it should ask for a new set each time the depth or dimensions of the screen changes and each time the BWindowScreen object releases or regains control of the screen. You'd typically call `CardHookAt()` in your implementation of `ScreenConnection()`.

### CardInfo()

graphics_card_info *`CardInfo(`void`) `

Returns a description of the current configuration of the graphics card, as kept by the driver for the card. The returned `graphics_card_info` structure is defined in be/addons/graphics/GraphicsCard.h and is documented in "The Entry Point and General Opcodes" in the "Graphics Card Drivers" chapter.

| The information returned by this function is only valid when the BWindowScreen is connected to the display.

See also: `FrameBufferInfo()`

### ColorList() see SetColorList()

### Disconnect()

void `Disconnect(`void`)`

Forces the BWindowScreen object to disconnect itself from the screen—to give up its authority over the graphics card driver, allowing the Application Server to reassert control. Normally, you'd disconnect the BWindowScreen only when hiding the game, reducing it to an ordinary window in the background, or quitting. The `Hide()` and `Quit()` functions automatically disconnect the BWindowScreen as part of the process of hiding and quitting. `Disconnect()` allows you to sever the connection before calling those functions.

Before breaking the screen connection, `Disconnect()` causes the BWindowScreen object to receive a `ScreenConnected()` notification with a flag of `false`. It doesn't return until `ScreenConnected()` returns and the connection is broken. `Hide()` and `Quit()` share this behavior.

See also: `Hide()`, `Quit()`

### FrameBufferInfo()

frame_buffer_info *`FrameBufferInfo(`void`) `

Returns a pointer to the `frame_buffer_info` structure that holds the driver's current conception of the frame buffer. The structure is defined in addons/graphics/GraphicsCard.h and is documented in "Frame Buffer Opcodes" in the "Graphics Card Drivers" chapter.

| The information returned by this function is only valid if `SetFrameBuffer()` has been called.

See also: `SetSpace()`, `SetFrameBuffer()`, `MoveDisplayArea()`, `CardInfo()`

### Hide() , Show()

virtual void `Hide(`void`) `
virtual void `Show(`void`) `

These functions augment their BWindow counterparts to make sure that the BWindowScreen is disconnected from the screen before it's hidden and that it's ready to establish a connection when it becomes the active window.

`Hide()` calls `ScreenConnected()` (with an argument of `false`) and breaks the connection to the screen when `ScreenConnected()` returns. It then hides the window.

`Show()` shows the window on-screen and makes it the active window, which will cause it to establish a direct connection to the graphics card driver for the screen. Unlike `Hide()`, it may return before `ScreenConnected()` is called (with an argument of `true`).

See also: `BWindow::Hide()`

### IOBase()

void *`IOBase(`void`) `

Returns a pointer to the base address for the input/output registers on the graphics card. Registers are addressed by 16-bit offsets from this base address. (This function may not be supported in future releases.)

### MoveDisplayArea()

status_t `MoveDisplayArea(`int32 x, int32 y`) `

Relocates the display area, the portion of the frame buffer that's mapped to the screen. This function moves the area's left-top corner to (x, y); by default, the corner lies at (0, 0). The display area must lie entirely within the frame buffer.

`MoveDisplayArea()` only works if the graphics card driver permits application control over the frame buffer. It must also permit a frame buffer with a total area larger than the display area. If successful in relocating the display area, this function returns `B_OK`; if not, it returns `B_ERROR`.

See also: `CanControlFrameBuffer()`

### Quit()

virtual void `Quit(`void`)`

Augments the BWindow version of `Quit()` to force the BWindowScreen object to disconnect itself from the screen, so that it doesn't quit while in control of the frame buffer.

Although `Quit()` disconnects the object before quitting, this may not be soon enough for your application. For example, if you need to destroy some drawing threads before the BWindowScreen object is itself destroyed, you should get rid of them after the screen connection is severed. You can force the object to disconnect itself by calling `Disconnect()`. For example:

       void MyWindowScreen::Quit()
       {
           Disconnect();
           kill_thread(drawing_thread_a);
           kill_thread(drawing_thread_b);
           BWindowScreen::Quit();
       }

If the screen connection is still in place when `Quit()` is called, it calls `ScreenConnected()` with a flag of `false`. It doesn't return until `ScreenConnected()` returns and the connection is broken.

See also: `ScreenConnected()`

### RegisterThread() , Suspend() , SuspensionHook()

void `RegisterThread(`thread_id thread`)`
void `Suspend(`char *label`)`
virtual void *`SuspensionHook(`bool suspended`)`

These three functions aid in debugging a game application. They have relevance only if the BWindowScreen is running in debugging mode. To set up the mode, you must:

- Construct the BWindowScreen with the debugging flag set to `true`. The flag is `false` by default.

- Register all drawing threads (all threads that can touch the frame buffer in any way) by passing the `thread_id` to `RegisterThread()` immediately after the thread is spawned—before `resume_thread()` is called to start the thread's execution. The window thread for the BWindowScreen object should not draw and should not be registered.

- Launch the application from the command line in a Terminal window. The window will collect debugging output from the application while the BWindowScreen runs in a different workspace, generally the one at the immediately preceding index. For example, if the Terminal window is in the fifth workspace (Command-F5), the game will run in the fourth (Command-F4); if the Terminal is in the fourth (CommandF4), the game runs in the third (Command-F3); and so on. However, if the Terminal window is in the first workspace (Command-F1), the game runs in the second (Command-F2).

The Terminal window is the destination for all messages the game writes to the standard error stream or to the standard output—from `printf()`, for example. You can switch back and forth between the game and Terminal workspaces to check the messages and run your application. When you switch from the game workspace to the Terminal workspace, all registered threads are suspended and the graphics context is saved. When you switch back to the game, the graphics context is restored and the threads are resumed.

Calling `Suspend()` switches to the Terminal workspace programmatically, just as pressing the correct Command–function key combination would. Registered threads are suspended, the Terminal workspace is activated, and the label passed as an argument is displayed in a message in the Terminal window. You can resume the game by manually switching back to its workspace.

`SuspensionHook()` is called whenever the game is suspended or resumed—whether by the user switching workspaces or by `Suspend()`. It gives you an opportunity to save and restore any state that would otherwise be lost. `SuspensionHook()` is called with a suspended flag of `true` just after the application is suspended and with a flag of `false` just before it's about to be resumed.

`ScreenConnected()` is not called when you switch between the Terminal and game workspaces while in debugging mode. However, it is called for all normal game activities—when the BWindowScreen is first activated and when it hides or quits, for example.

Debugging mode can also preserve some information in case of a crash. Hold down all the left modifier keys (Shift, Control, Option, Command, Alt, or whatever the keys may happen to be on your keyboard), and press the F12 key. This restarts the screen with a 640 * 480 resolution and displays a debugger window. You should then be able to switch to the Terminal workspace to check the last set of messages before the crash, modify your code, and start again.

### ScreenChanged()

virtual void `ScreenChanged(` BRect frame, color_space mode`) `

Overrides the BWindow version of `ScreenChanged()` so that it does nothing. This function is called automatically when the screen configuration changes. It's not one that you should call in application code or reimplement for the game.

See also: `BWindow::ScreenChanged()`

### ScreenConnected()

virtual void `ScreenConnected(`bool connected`) `

Implemented by derived classes to take action when the application gains direct access to the screen and when it's about to lose that access.

This function is called with the connected flag set to `true` immediately after the BWindowScreen object becomes the active window and establishes a direct connection to the graphics card driver for the screen. At that time, the Application Server's connection to the screen is suspended; drawing can only be accomplished through the screen access that the BWindowScreen object provides.

`ScreenConnected()` is called with a flag of `false` just before the BWindowScreen object is scheduled to lose its control over the screen and the Application Server's control is reasserted. The BWindowScreen's connection to the screen will not be broken until this function returns. It should delay returning until the application has finished all current drawing and no longer needs direct screen access.

Note that whenever `ScreenConnected()` is called, the BWindowScreen object is guaranteed to be connected to the screen; if connected is `true`, it just became connected, if connected is `false`, it's still connected but will be disconnected when the function returns.

Derived classes typically use this function to regulate access to the screen. For example, they may acquire a semaphore when the connected flag is `false`, so that application threads won't attempt direct drawing when the connection isn't in place, and release the semaphore for drawing threads to acquire when the flag is `true`. For example:

       void MyWindowScreen::ScreenConnected(bool connected)
       {
           if ( connected == false )
               acquire_sem(directDrawingSemaphore);
           else
               release_sem(directDrawingSemaphore);
       }

See also: `Disconnect()`

### SetColorList() , ColorList()

void `SetColorList(`rgb_color *colors, int32 first = 0, int32 last = 255`) `
rgb_color *`ColorList(`void`) `

These functions set and return the list of 256 colors that can be displayed when the frame buffer has a depth of 8 bits per pixel (the `B_CMAP8` color space). `SetColorList()` is passed an array of one or more colors to replace the colors currently in the list. The first color in the array replaces the color in the list at the specified first index; all colors up through the last specified index are modified. It fails if either index is out of range.

`SetColorList()` alters the list of colors kept on the graphics card. If the BWindowScreen isn't connected to the screen, the new list takes effect when it becomes connected.

`ColorList()` returns a pointer to the entire list of 256 colors. This is not the list kept by the graphics card driver, but a local copy. It belongs to the BWindowScreen object and should be altered only by calling `SetColorList()`.

See also: `BScreen::ColorMap()` in the Interface Kit

### SetFrameBuffer()

status_t `SetFrameBuffer(`int32 width, int32 height`)`

Configures the frame buffer on the graphics card so that it's width pixel columns wide and height pixel rows high. This function works only if the driver for the graphics card allows custom configurations (as reported by `CanControlFrameBuffer()`) and the BWindowScreen object is currently connected to the screen.

The new dimensions of the frame buffer must be large enough to hold all the pixels displayed on-screen—that is, they must be at least as large as the dimensions of the display area. If the driver can't accommodate the proposed width and height, `SetFrameBuffer()` returns `B_ERROR`. If the change is made, it returns `B_OK`.

This function doesn't alter the depth of the frame buffer or the size or location of the display area.

See also: `MoveDisplayArea()`, `SetSpace()`

### SetSpace()

status_t `SetSpace(`uint32 space`) `

Configures the screen space to one of the standard combinations of width, height, and depth. The configuration is first set by the class constructor—permitted space constants are documented there—and it may be altered after construction only by this function.

Setting the screen space sets the dimensions of the frame buffer and display area. For example, if space is `B_32_BIT_800x600`, the frame buffer will be 32 bits deep and at least 800 pixel columns wide and 600 pixel rows high. The display area (the area of the frame buffer mapped to the screen) will also be 800 pixels * 600 pixels. After setting the screen space, you can enlarge the frame buffer by calling `SetFrameBuffer()` and relocate the display area in the larger buffer by calling `MoveDisplayArea()`.

If the requested configuration is refused by the graphics card driver, `SetSpace()` returns `B_ERROR`. If all goes well, it returns `B_OK`.

See also: the BWindowScreen constructor, `SetFrameBuffer()`, `MoveDisplayArea()`

### Suspend() see RegisterThread()

### SuspensionHook() see RegisterThread()

### WindowActivated()

virtual void `WindowActivated(`bool active`) `

Overrides the BWindow version of `WindowActivated()` to connect the BWindowScreen object to the screen (give it control over the graphics card driver) when the active flag is `true`.

This function doesn't disconnect the BWindowScreen when the flag is `false`, because there's no way for the window to cease being the active window without the connection already having been lost.

Don't reimplement this function in your application, even if you call the inherited version; rely instead on `ScreenConnected()` for accurate notifications of when the BWindowScreen gains and loses control of the screen.

See also: `BWindow::WindowActivated()`, `ScreenConnected()`

### WorkspaceActivated()

virtual void `WorkspaceActivated(`int32 workspace, bool active`) `

Overrides the BWindow version of `WorkspaceActivated()` to connect the BWindowScreen object to the screen when the active flag is `true` and to disconnect it when the flag is `false`. User's typically activate the game by activating the workspace in which it's running, and deactivate it by moving to another workspace.

Don't override this function in your application; implement `ScreenConnected()` instead.

See also: `BWindow::WorkspaceActivated()`, `ScreenConnected()`

The Game Kit Table of Contents | The Game Kit Index

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

Copyright © 2000 Be, Inc. All rights reserved..