`

`

# Graphics Card Drivers: The Entry Point and General Opcodes

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.

## General Opcodes and Structures

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.

### B_OPEN_GRAPHICS_CARD, graphics_card_spec

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.

### B_CLOSE_GRAPHICS_CARD

Notifies the graphics card driver that it's about to be unloaded. The data argument and return value are ignored.

### B_GET_GRAPHICS_CARD_HOOKS

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`.

### B_GET_GRAPHICS_CARD_INFO, graphics_card_info

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.

### B_GET_REFRESH_RATES, refresh_rate_info

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.

### B_GET_SCREEN_SPACES

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:

`B_8_BIT_640x480` | `B_15_BIT_640x480` | `B_16_BIT_640x480` | `B_32_BIT_640x480`
```B_8_BIT_800x600` | `B_15_BIT_800x600` | `B_16_BIT_800x600` | `B_32_BIT_800x600`
```B_8_BIT_1024x768` | `B_15_BIT_1024x768` | `B_16_BIT_1024x768` | `B_32_BIT_1024x768`
```B_8_BIT_1152x900` | `B_15_BIT_1152x900` | `B_16_BIT_1152x900` | `B_32_BIT_1152x900`
```B_8_BIT_1280x1024` | `B_15_BIT_1280x1024` | `B_16_BIT_1280x1024` | `B_32_BIT_1280x1024`
```B_8_BIT_1600x1200` | `B_15_BIT_1600x1200` | `B_16_BIT_1600x1200` | `B_32_BIT_1600x1200`

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

### B_SET_INDEXED_COLOR, indexed_color

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.

### B_SET_SCREEN_GAMMA, screen_gamma

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

### B_CONFIG_GRAPHICS_CARD, graphics_card_config

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.