# The Game Kit: BWindowScreen

Derived from: public BWindow

Declared in: be/game/WindowScreen.h

Library: libgame.so

## Overview

A BWindowScreen object has the dual nature its name implies: It's both a window and an object that provides direct access to the screen, bypassing the window system. When a BWindowScreen object becomes the active window, it establishes a direct connection to the graphics card driver for the screen, independent of the Application Server. This permits the application to set up the graphics environment on the card, call driver-implemented drawing functions, and directly manipulate the frame buffer.

### Screen Access

Like other 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. The Application Server's graphics operations are suspended until the BWindowScreen object gives up active window status. While the BWindowScreen is active, 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 The Interface Kit: 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 function implemented by the graphics card driver and located at index in its list of hook functions, or `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 in this chapter. Currently, there's provision for 12 functions, from index 0 through index 11. However, the first three, which set and manipulate the cursor, are unavailable 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 addons/graphics/GraphicsCard.h and contains the following fields:

short `version
` The version of the Be architecture for graphics cards; the current version is 2.

short `id
` An identifier for the driver, understood in relation to the version number.

void *`frame_buffer
` A pointer to the first byte of the frame buffer. Applications can use this pointer to draw directly to the buffer, but should attempt to do so only when the BWindowScreen has a direct screen connection.

char `rgba_order`[4]
The characters 'R' (red), 'G' (green), 'B' (blue), and 'A' (alpha) ordered as those components are intermeshed for each pixel in the frame buffer. This field is valid only for screen depths of 32 bits per pixel.

short `flags
` A mask formed from three flags (`B_CRT_CONTROL`, `B_FRAME_BUFFER_CONTROL`, and `B_GAMMA_CONTROL`) that describe the ability of the graphics card driver to perform particular tasks. `B_FRAME_BUFFER_CONTROL` matches the `CanControlFrameBuffer()` function; it indicates that the driver allows clients to set arbitrary dimensions for the frame buffer and to control which portion of the frame buffer (the display area) is mapped to the screen. The other two flags aren't important to the control exercised through the BWindowScreen object.

short `bits_per_pixel
` The depth of the screen in bits per pixel. Only 32-bit (`B_RGB_32_BIT`) and 8-bit (`B_COLOR_8_BIT`) depths are currently supported.

long `bytes_per_row
` The offset, in bytes, between two adjacent rows of pixel data in the frame buffer (the number of bytes assigned to each row).

short `width
` The width of the frame buffer in pixels (the number of pixel columns it defines).

short `height
` The height of the frame buffer measured in lines of pixels (the number of pixel rows the frame buffer defines).

The returned structure belongs to the BWindowScreen object and is provided for information only; you should not modify any of its fields. The structure may change whenever the connection to the screen is reestablished. Therefore, it's necessary to call `CardInfo()` every time `ScreenConnected()` announces a new connection.

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 contains the following fields:

short `bits_per_pixel
` The depth of the frame buffer; the number of bits assigned to a pixel.

short `bytes_per_row
` The number of bytes required to store one row of pixel data in the frame buffer.

short `width
` The width of the frame buffer in pixels (the total number of pixel columns).

short `height
` The height of the frame buffer in pixels (the total number of pixel rows).

short `display_width
` The width of the screen display in pixels (the number of pixel columns shown on-screen).

short `display_height
` The height of the screen display in pixels (the number of pixel rows shown on-screen).

short `display_x
` The horizontal position of the left top pixel shown on-screen, where 0 is the leftmost column of pixels in the frame buffer.

short `display_y
` The vertical position of the left top pixel shown on-screen, where 0 is the topmost row of pixels in the frame buffer.

The last four fields of this structure distinguish between the frame buffer itself and the part of the frame buffer that's displayed on-screen--the display area. This distinction permits the display area to be moved on a (possibly) much larger area defined by the frame buffer.

Both areas are defined by a width (the number of pixel columns the area includes) and a height (the number of pixel rows). By default, the frame buffer and the display area are the same size--the size set on construction or by `SetSpace()`. `SetFrameBuffer()` can expand the frame buffer beyond those default dimensions, opening the possibility that the display area can be mapped to different parts of the buffer at different times.

The display area is located in the frame buffer by the index to the column (`display_x`) and row (`display_y`) of its left top pixel. By default, it's located at (0, 0), but `MoveDisplayArea()` can remap it to another part of the frame buffer. See that function for an illustration.

The returned `frame_buffer_info` structure belongs to the BWindowScreen object. Call functions like `SetSpace()`, `SetFrameBuffer()`, and `MoveDisplayArea()` to modify its fields; don't modify them directly. Note that the first four `frame_buffer_info` fields are identical to the last four of `graphics_card_info`.

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. The size of the area is defined by the constructor and the `SetSpace()` function. By default, it's located so that the left top pixel on-screen is at (0, 0) in the frame buffer. This function moves it to (x, y), where x coordinate values are left-to-right indices to a pixel column in the frame buffer and y coordinate values are top-to-bottom indices to a pixel row. The display area must lie entirely within the frame buffer, as illustrated in miniature below.

For example, the frame buffer might be partitioned into discrete sections and the display area moved from one to another for buffered drawing and a smooth transition between images. If the frame buffer has twice as many pixel rows as the screen displays, the display area could alternate between the top and bottom halves. For hardware scrolling, the display area can be moved repeatedly by small increments.

Like `SetFrameBuffer()`, `MoveDisplayArea()` works only 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_COLOR_8_BIT` 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: BWindowScreen(), `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()`

## Graphics Card Hook Functions

The following functions are not members of the BWindowScreen class, but functions that a graphics card driver may implement and that game applications may call through the pointers returned by `CardHookAt()`. They're designed for accelerated and efficient drawing and can be called only when the BWindowScreen is connected to the screen.

The hook functions are anonymous; they're identified only by an index passed to `CardHookAt()` and by the pointer that `CardHookAt()` returns. The names given in the presentation below are merely meant to be descriptive of what the function does; they're not real names you can use in your code.

Valid indices range from 3 through 11. The functions at indices 0, 1, and 2, which concern the cursor, are not available to applications. No function has been defined for an index greater than 11 (yet).

All the functions return an error code (`status_t`) and take their own set of arguments. Since efficiency is at a premium, they typically do little error checking. Be careful not to pass invalid values.

For these functions, an x coordinate value is a left-to-right index to a pixel column in the frame buffer and a y coordinate value is a top-to-bottom index to a pixel row. All coordinate values you pass as arguments must lie somewhere in the frame buffer. For example, before calling the function at index 7, which blits a rectangle width pixels wide and height pixels high from (sourceX, sourceY) to (destinationX, destinationY), you should be sure that the source and destination rectangles both fall entirely within the area defined by the frame buffer.

### Index 3: Drawing a Line with an 8-Bit Color

          status_t draw_line_8_bits_deep(int32 startX, int32 endX, int32 startY, int32 endY,
             uchar colorIndex, bool clipToRect, int16 clipLeft,
             int16 clipTop, int16 clipRight, int16 clipBottom)

The function at index 3 draws a straight, 1-pixel thick line in the `B_COLOR_8_BIT` color space. The first four arguments define the starting and ending points of the line; it begins at (startX, startY) and ends at (endX, endY). Both points are included within the line. The fifth argument, colorIndex, is the color of the line; it's an index into the map of 256 colors.

If the sixth argument, clipToRect, is `true`, the function draws only the portion of the line that lies within the clipping rectangle defined by the last four arguments. The sides of the rectangle are included within the drawing area; everything outside the rectangle is clipped.

If clipToRect is `false`, the final four arguments are ignored.

### Index 4: Drawing a Line with a 32-Bit Color

          status_t draw_line_32_bits_deep(int32 startX, int32 endX, int32 startY, int32 endY,
             uint32 color, bool clipToRect, int16 clipLeft,
             int16 clipTop, int16 clipRight, int16 clipBottom)

The function at index 4 is like the one at index 3, except that it draws a line in the `B_RGB_32_BIT` color space. The only difference between the two functions is the color argument. Here the color is specified as a full 32-bit quantity with 8-bit red, green, blue, and alpha components. The color argument should arrange the components in the order that the driver asked for them (in the `rgba_order` field of the `graphics_card_info` structure). Otherwise, this function works just like the one at index 3.

See also: `CardInfo()`

### Index 5: Drawing a Rectangle with an 8-Bit Color

          status_t draw_rect_8_bits_deep(int32 left, int32 top, int32 right, int32 bottom,
             uchar colorIndex)

The function at index 5 fills a rectangle with a color specified by its index. The left, top, right, and bottom sides of the rectangle are included in the area that's filled.

### Index 6: Drawing a Rectangle with a 32-Bit Color

          status_t draw_rect_32_bits_deep(int32 left, int32 top, int32 right, int32 bottom,
             uint32 color)

The function at index 6, like the one at index 5, fills a rectangle. The color value contains the four color components--red, green, blue, and alpha--arranged in the order for the device (the order recorded in the `rgba_order` field of the `graphics_card_info`).

See also: `CardInfo()`

### Index 7: Copying Pixel Data

          status_t blit(int32 sourceX, int32 sourceY, int32 destinationX, int32 destinationY,
             int32 width, int32 height)

The function at index 7 copies pixel values from a source rectangle to a destination rectangle. The left top corner of the source rectangle is the pixel at (sourceX, sourceY) in the frame buffer. The left top pixel of the destination rectangle is at (destinationX, destinationY). Both rectangles are width pixels wide and height pixels high; the width and height arguments cannot be 0 or negative. You must ensure that the source and destination rectangles both lie entirely within the area defined by the frame buffer.

### Index 8: Drawing a Line Array with an 8-Bit Color

          status_t draw_array_8_bits_deep(indexed_color_line *array, int32 numItems,
             bool clipToRect, int16 clipLeft, int16 clipTop,
             int16 clipRight, int16 clipBottom)

The function at index 8 draws an array of 1-pixel thick lines in the `B_COLOR_8_BIT` color space. The line array holds a total of numItems. Each item is specified as an `indexed_color_line` structure, which contains the following fields:

short `x1
` The x coordinate of one end of the line.

short `y1
` The y coordinate of one end of the line.

short `x2
` The x coordinate of the other end of the line.

short `y2
` The y coordinate of the other end of the line.

uchar `color
` The color of the line, expressed as an index into the color map.

The function draws each line from (`x1`, `y1`) to (`x2`, `y2`) using the `color` specified for that line. If the clipToRect flag is `true`, nothing is drawn outside the clipping rectangle defined by the final four arguments. The sides of the rectangle are included in the visible region. If clipToRect is `false`, the final four arguments should be ignored.

### Index 9: Drawing a Line Array with a 32-Bit Color

          status_t draw_array_32_bits_deep(rgb_color_line *array, int32 numItems,
             bool clipToRect, int16 clipLeft, int16 clipTop,
             int16 clipRight, int16 clipBottom)

The function at index 9 has the same syntax as the one at index 8, except for the first argument. Here, each line in the array is specified as an `rgb_color_line` structure, rather than as an `indexed_color_line`. The two structures differ only in how the color is specified:

short `x1
` The x coordinate of one end of the line.

short `y1
` The y coordinate of one end of the line.

short `x2
` The x coordinate of the other end of the line.

short `y2
` The y coordinate of the other end of the line.

rgb_color `color
` The color of the line, expressed as a full 32-bit value.

In all other respects, this function works just like the one at index 8.

### Index 10: Synchronizing Drawing Operations

          status_t sync(void)

Synchronizes the application with the graphics card driver. The function returns when the driver is finished modifying the frame buffer.

If any of the other hook functions draw asynchronously--if they return before the drawing they're asked to do is complete--the graphics card driver is likely to implement this function. It waits until all drawing operations have been completed before it returns. The return value is not important; you can ignore it.

If the driver doesn't implement this function (if `CardHookAt()` returns `NULL` for index 10), it's a sign that all the other drawing functions work synchronously--they don't return until they finish modifying the frame buffer.

### Index 11: Inverting Colors

          status_t invert_rect(int32 left, int32 top, int32 right, int32 bottom)

Inverts the colors in the specified rectangle. The sides of the rectangle are included in the area that's inverted.

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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 27, 1998.