Graphics Card Drivers: Driver Cloning Opcodes

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

The Game Kit's BWindowScreen class gives an application access to the graphics card's accelerated graphics functions ("hook" functions) by "cloning" the graphics driver that was initially loaded by the Application Server. The clone is created and managed through the four opcodes:

While the clone is active, the Server suspends its graphic operations. When the clone is finished, the Server resumes control--and assumes that the card is in the same state as it was before the clone took over. In other words, the clone must leave the card in the same state that it found it.


B_GET_INFO_FOR_CLONE

Tells the driver to write information about its current state into the location referred to by the data pointer. This information is passed to the clone (in a B_SET_CLONED_GRAPHICS_CARD request) so the clone can duplicate the state of the driver.

The structure of the information is defined by the driver. The structure should contain the driver's software settings, such as the screen configuration and frame buffer location. Hardware settings, such as the color map, don't need to be cloned.

For example, if the structure is called info_for_clone, driver code might look something like this:

   case B_GET_INFO_FOR_CLONE:
       ((info_for_clone *)data)->depth = info.bits_per_pixel;
       ((info_for_clone *)data)->height = info.height;
       ((info_for_clone *)data)->width = info.width;
       ((info_for_clone *)data)->row_byte = info.bytes_per_row;
       ((info_for_clone *)data)->frame_base = info.frame_buffer;
       ((info_for_clone *)data)->io_base = spec.io_base;
       ((info_for_clone *)data)->available_mem = unused_memory;
       ((info_for_clone *)data)->refresh_rate = rate.current;
       . . .
       break;

The driver can receive numerous B_GET_INFO_FOR_CLONE requests while the clone is active.

RETURN CODES

If the driver can provide the clone info, the function should return B_OK. If it returns B_ERROR, the clone won't be created.


B_GET_INFO_FOR_CLONE_SIZE

Asks the driver for the size (in bytes) of its "clone info" structure (the structure it will provide in response to a B_GET_INFO_FOR_CLONE opcode). The size should be written to the data pointer as an int32. For example:

   *((int32 *)data) = sizeof(info_for_clone);

RETURN CODES

If the driver can provide the size of the clone info, the function should return B_OK. If it returns B_ERROR, the clone won't be created.


B_SET_CLONED_GRAPHICS_CARD

Sent to the clone to tell it to initialize itself. The data pointer contains (a copy of) the structure that the driver provided in response to a B_GET_INFO_FOR_CLONE request. The clone should read the structure and set all the parameters that are provided.

Note that this is the first opcode that the clone will receive; it doesn't receive a B_OPEN_GRAPHICS_CARD opcode. It subsequently will receive this opcode many more times--whenever it must be synchronized with the driver loaded by the Application Server.


B_CLOSE_CLONED_GRAPHICS_CARD

Tells the clone that it's about to be unloaded. The data pointer and return value are ignored. The clone should implement this function to restore the previous (i.e. "pre-clone") state of the driver.






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

Copyright © 1998 Be, Inc. All rights reserved.

Last modified March 26, 1998.