Graphics Card Drivers: Frame Buffer Opcodes

Declared in: be/add-ons/graphics/GraphicsCard.h

If the graphics card driver allows it, the BWindowScreen class in the Game Kit will provide direct control of the frame buffer. A driver announces that it allows this control by including the B_FRAME_BUFFER_CONTROL constant when responding to a B_GET_GRAPHICS_CARD_INFO request. (See B_GET_GRAPHICS_CARD_INFO .)

The Game Kit's frame buffer control is performed through the four opcodes described below. All four opcodes use the frame_buffer_info structure to pass data to the driver. The structure contains eight fields:

int16 bits_per_pixel The frame buffer depth.
int16 bytes_per_row The size (in bytes) of a frame buffer row.
int16 width The width of the frame buffer, in pixels.
int16 height The height of the frame buffer, in pixels.
int16 display_width The width of the display area, in pixels.
int16 display_height The height of the display area, in pixels.
int16 display_x The frame buffer column that's mapped to the leftmost column on the screen, where columns are indicated by a left-to-right index beginning with 0.
int16 display_y The frame buffer row that's mapped to the topmost row on the screen, where rows are indicated by a top-to-bottom index beginning with 0.

The first four fields describe the frame buffer itself (these are the "frame buffer fields"); the final four describe the the part of the frame buffer that's displayed on-screen (these are the "display area fields"). This distinction permits the display area to be moved within a (possibly) much larger frame buffer, and also facilitates buffered drawing (since you can set up display area partitions).

In all cases, the driver should return B_OK if it can comply with the request, and B_ERROR if not.


B_PROPOSE_FRAME_BUFFER

Asks the driver if it can handle a particular frame buffer width and depth, as encoded in the width and bits_per_pixel fields of the frame_buffer_info argument. If the driver accepts, it should set the other two frame buffer fields and return B_OK:

The driver shouldn't actually configure the frame buffer yet; it should wait for a B_SET_FRAME_BUFFER opcode. (But note that B_PROPOSE_FRAME_BUFFER isn't guaranteed to be sent before a B_SET_FRAME_BUFFER request.)

If the driver can't accommodate the proposed dimensions, it should place -1 in the bytes_per_row and height fields and return B_ERROR.

The display area fields needn't be set in either case.


B_SET_FRAME_BUFFER

Tells the driver to configure the frame buffer according to the description in the frame_buffer_info argument. All eight fields in the structure contain meaningful values.


B_MOVE_DISPLAY_AREA

Tells the driver to move the display area so its left top pixel is at the location specified by the display_x and display_y fields of the frame_buffer_info argument. The other fields should be ignored.




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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.