Declared in: be/add-ons/graphics/GraphicsCard.h
The primary means by which the Application Server and Game Kit communicate with a graphics card driver--the driver's "entry point"--is the control_graphics_card()function; every graphics card driver must implement this function:
int32 control_graphics_card(uint32 opcode, void *data)
The first argument, opcode, specifies the operation the driver is to perform. The second argument, data, is used to pass data to the driver, or to return information from it; the type of data depends on the nature of the operation.
The return value is an error code. In general, the control function should return B_OK or B_ERROR to indicate success or failure. It should also return B_ERROR for op codes that it doesn't understand.
Only the Application Server and Game Kit objects can (effectively) call control_graphics_card(); random applications can't load the driver and invoke the function themselves.
Listed below are descriptions of the general opcodes and structures that examine and configure a graphics card driver. Briefly, the opcodes are:
Opcode | Description |
---|---|
B_OPEN_GRAPHICS_CARD
B_CLOSE_GRAPHICS_CARD |
Initiates and terminates communication with the driver. |
B_GET_GRAPHICS_CARD_INFO,
B_GET_GRAPHICS_CARD_HOOKS, B_GET_SCREEN_SPACES B_GET_REFRESH_RATES |
Queries the driver for information such as the location of the hook functions, the supported screen configurations, and so on. |
B_SET_INDEXED_COLOR,
B_SET_SCREEN_GAMMA |
Tells the driver to poke entries into its color map, and to set its color correction table. |
B_CONFIG_GRAPHICS_CARD | Tells the driver to configure the frame buffer and turn on the display. |
Tells the driver to open and initialize the graphics card specified by the data argument. data points to a graphics_card_spec structure, which has the following fields:
void *screen_base | The beginning of the card's memory. |
void *io_base | The base address for the I/O registers that control the graphics card. Registers are at 16-bit offsets from the base address. |
uint32 vendor_id | A number that identifies the manufacturer of the card's graphics chip, (as given by a register on the card). |
uint32 device_id | A number that identifies the particular graphics chip of that manufacturer (as given by a register on the card). |
The driver can initialize structures and perform other startup routines, but should wait for the B_CONFIG_GRAPHICS_CARD opcode before initializing the frame buffer or turning on the video display.
RETURN CODES
The function should return B_OK if the driver can open the card, and B_ERROR if not. If the driver returns B_ERROR, it will immediately get a B_CLOSE_GRAPHICS_CARD opcode.
Notifies the graphics card driver that it's about to be unloaded. The data argument and return value are ignored.
Asks the driver to supply a set of hook functions that the Application Server can call to carry out specific graphics tasks. See Graphics Card Hook Functions , for more information.
A driver can expect this opcode soon after it's opened, and again any time the screen configuration changes.
RETURN CODES
The function should return B_OK if the driver can supply any hooks; a return of B_ERROR sets all the hook pointers to NULL.
Asks the driver to supply information about itself and the current configuration of the screen. The driver provides this information by filling in the fields of the graphics_card_info structure that's passed through the data argument. All fields must be filled in, and they must all be valid:
int16 version | The version of the Be architecture for graphics cards that the driver was designed to work with. |
int16 id | A driver-defined identifier for the driver. |
void *frame_buffer | A pointer to the first byte of the frame buffer. |
char rgba_order[4] | This field, which is intended to encode color component order, is currently ignored. The order of components is "bgra" for Intel processors and the BeBox, and "argb" for Power Mac-compatible machines. |
int16 flags | A mask containing flags that describe the ability of the graphics card driver to perform particular tasks. (See below.) |
int16 bits_per_pixel | The depth of the screen in bits per pixel--one of 8,15,16, or 32. Note that 15 bpp designates 5-5-5-1 encoding, as opposed to "true" 16-bit which designates 5-6-5 encoding. The nominal 15-bit format actually uses 16 bits; other "bits per pixel" API returns 16 bits for both formats, and differentiates the encodings through some other field (typically named "color space", or the like). |
int32 bytes_per_row | The number of bytes required to represent a single row of pixel data in the frame buffer. |
int16 width | The width of the display area in pixels. |
int16 height | The height of the display area in pixels. |
There are four flags:
B_CRT_CONTROL | Indicates that the driver is able to control in software, to any extent, the position or the size of the CRT display on the monitor. |
B_GAMMA_CONTROL | Indicates that the driver is able to make gamma corrections that compensate for the particular characteristics of the display device. |
B_FRAME_BUFFER_CONTROL | Indicates that the driver accepts the frame buffer opcodes (described in Graphics Card Drivers: Frame Buffer Opcodes ). |
B_PARALLEL_BUFFER_ACCESS | Enables parallel access to the frame buffer. If the card doesn't allow parallel access, the Game Kit's BDirectWindow class won't work in "window mode" (the class will still work in "full screen mode"). |
The driver will receive frequent B_GET_GRAPHICS_CARD_INFO requests. The graphics_card_info structure it supplies should always reflect the values currently in effect.
RETURN CODES
The function should return B_OK if the driver has filled in all fields with valid info. A return of B_ERROR causes the info structure to be ignored.
Asks the driver to place the current refresh rate, as well as the maximum and minimum rates, in the refresh_rate_info structure referred to by the data pointer. The structure contains these fields:
float current | The current refresh rate in Hertz. |
float min | The minimum refresh rate (Hz) that the graphics card is capable of, given the current configuration. |
float max | The maximum refresh rate (Hz) that the graphics card is capable of, given the current configuration. |
RETURN CODES
The return value is ignored.
Asks the driver to provide a mask containing all possible configurations of pixel depth and screen dimensions (in pixels) that it supports. The mask is formed from the following constants (defined in interface/GraphicsDefs.h) and is returned through the data pointer:
![]() |
Don't use the two reserved screen space constants (B_8_BIT_640x400 and B_FAKE_DEVICE) that are also defined in interface/GraphicsDefs.h. |
RETURN CODES
The return value is ignored.
Tells the driver to poke a 32-bit RGB color value into a slot in its 8-bit color map. The index into the map and the color value are encoded in the fields of the indexed_color structure that's pointed to by data:
int32 index | The index (0-based) into the map. |
rgb_color color | The full 32-bit color that should be associated with the index. |
A driver can expect a series of these calls (one for each index in the color map) at startup time. Thereafter, it might get indexed color requests when an application modifies the color map, or when a Game Kit window returns control to the Application Server.
RETURN CODES
The return value is ignored.
![]() |
This opcode is currently unused. |
Tells the driver to set up a table for adjusting color values to correct for the peculiarities of the display device. This opcode is only meaningful to drivers that can make gamma corrections (i.e. those that set the B_GAMMA_CONTROL flag in response to a B_GET_GRAPHICS_CARD_INFO request).
The data argument points to a screen_gamma structure that contains "replacement arrays" for the three color components:
uint8 red[256] | Mappings for the red component. |
uint8 green[256] | Mappings for the green component. |
uint8 blue[256] | Mappings for the blue component. |
The value at a given index replaces the index taken as a value. For example, if the value at blue[152] is 154, all blue component values of 152 are displayed as 154.
RETURN CODES
The return value is ignored.
Tells the driver to configure the frame buffer and enable the display according to the values set in the graphics_card_config structure that the data argument points to. The structure contains the following fields:
uint32 space | A "screen space" constant that describes the size and depth of the frame buffer. The constants are listed under B_GET_SCREEN_SPACES, above. |
float refresh_rate | The refresh rate of the screen in Hertz. |
uint8 h_position | The horizontal position of the CRT display on the monitor. |
uint8 v_position | The vertical position of the CRT display on the monitor. |
uint8 h_size | The horizontal size of the CRT display on the monitor. |
uint8 v_size | The vertical size of the CRT display on the monitor. |
The space setting must be precisely adhered to. The driver should come as close as it can to the requested refresh_rate, but precise adherence isn't mandatory
The last four fields are only meaningful to drivers that can control CRT positioning (i.e. those that set the B_CRT_CONTROL flag in response to a B_GET_GRAPHICS_CARD_INFO request). The values in these fields range from 0 through 100, with 50 as the default. Values less than 50 for h_position and v_position should move the display toward the left and top; greater than 50 should move it to the right and bottom. Values of less than 50 for h_size and v_size should make the display narrower and shorter, squeezing it into a smaller area; values greater than 50 should make it wider and taller.
The driver receives this opcode during the startup routine, and, thereafter, whenever the screen configuration needs to change (when the user plays with the Screen preferences, for example).
RETURN CODES
If the driver can configure the frame buffer as described by the space value, the function should return B_OK; otherwise, it should return B_ERROR.
The Be Book, in lovely HTML, for BeOS Release 3.
Copyright © 1998 Be, Inc. All rights reserved.
Last modified March 26, 1998.