Graphics Card Drivers: The Entry Point and General Opcodes


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.