Graphics Adapter Device Drivers

This chapter describes the functions called by individual Graphics Adapter Device Drivers (GRADDs), which are designated by the prefix GHI_CMD_. The chapter also discusses Enhanced Direct Interface Video Extension (EnDIVE) functions, which are designated by the prefix EXT_CMD_.

Each GRADD has its own exported function called "HWEntry," which is the same function type as VMIEntry. The differences between the VMAN protocol (VMI) and the protocol for the GRADDs (GHI) include the following: To provide the appropriate user interface, all GRADDs must export a function of the following typedef: ULONG HWEntry(GID gid, ULONG ulFunction, PVOID pIn, PVOID pOut);
 * The VMI is a super set of the GHI.
 * The ulFunction parameter value changes to the appropriate VMI_CMD_ function name.

Adding Extensions
One of the most important design points of the GRADD Model is the ability to extend or enhance the overall architecture. It is not possible to anticipate the changes in future graphics hardware, so we must provide a mechanism to extend the architecture in a manner that takes fullest advantage of the new hardware.

There are many ways to extend the GRADD Model. Using the command, an extension can be written that passes its own defined commands to a GRADD. Support for an extension can be added to an existing GRADD, or a new GRADD can be written to handle the additional support for a given extension.

Adding Extensions to an Existing GRADD
When the Video Manager (VMAN) issues the command to a GRADD, it gives the GRADD a unique ID. Upon return from the GHI_CMD_INIT command, the GRADD returns the number of function classes it supports. The GRADD must assign a unique GID to each of its function-class instances. The GID provided to the GRADD by VMAN must be bumped up by one for every function-class instance.

Note: For Presentation Manager and Seamless Windows functions, a GRADD must support the Base Function class of services. The GRE2VMAN component looks specifically for a GRADD that supports this class of function.

VMAN will allocate one GRADDINFO structure for every class of function that a GRADD supports. VMAN will call once for every function-class instance. This allows an extension layer to associate a GID with a set of function classes.

The extension layer uses the function to communicate with a GRADD. It is up to the extension layer to define the unique extension functions. The extensions must use VMAN to communicate with the GRADD. The input packet to the VMI_CMD_EXTENSION function includes information about screen change areas and hardware serialization. This information allows VMAN to maintain hardware pointer support and hardware serialization.

Creating an Extension GRADD
An extension GRADD can be added to the system without interfering with normal operations. The extension GRADD works in the same manner as a normal GRADD. The extension GRADD identifies itself to the system via the pszFunctionClassID field of the CAPSINFO data structure. This structure is returned to VMAN via GHI_CMD_QUERYCAPS.

The extension layer communicates with the extension GRADD in the same manner described in the "Adding Extensions to an Existing GRADD" section earlier.

Creating an EnDIVE Multimedia Extension GRADD
OS/2 Warp supports an enhanced direct interface video extension, referred to as EnDIVE. This extension is designed to support graphics chips that handle video acceleration in hardware. The EnDIVE multimedia extension described here supports the same level of functionality under the GRADD Model.

The following figure diagrams the DIVE Display Engine. [Artwork not shown]

The phrase "video acceleration" recently has taken on a new meaning. In the past, video acceleration was a way of describing hardware assist for bitblts, lines, and so on. Today, video acceleration or video accelerators describe hardware assist for video-acceleration software. The minimum requirement necessary to be considered a video accelerator is the ability to perform a stretch blit in hardware. More powerful video accelerators perform additional functions, such as dynamic color conversion, decompression, and compression. These types of operations are directly applicable to the needs of multimedia video-acceleration software.

The EnDIVE multimedia extension GRADD consists of four functions, contained in the ulXSubFunction field of the HWEXTENSION packet. For each extension function, the input packet is pointed to by the pXP1 field of the HWEXTENSION packet.

The four EnDIVE functions are listed below:
 * EXT_CMD_ENDIVE_GET
 * EXT_CMD_ENDIVE_INIT
 * EXT_CMD_ENDIVE_PUT
 * EXT_CMD_ENDIVE_QUERY

For details on each of these functions, refer to.

NLS Support
The GRADD Model is independent of the language and the operating system service being used. Double-byte character sets and other issues for different language releases are a matter of the translation of the operating system service, not of any code in the GRADD Model.

Graphics Hardware Interface Functions
The Graphics Adapter Device Driver Interface (GHI) functions are listed in the following table for easy reference. Each of these functions has an identical corresponding VMAN VMI_CMD_ function (refer to VMI_CMD_xx Functions and GHI_CMD_xx Functions). The difference between VMI and GHI functions is that the VMI functions use VMIEntry, while the GHI functions use. In addition, the differences between the VMAN VMI protocol and the GRADD GHI protocol can be described as follows:
 * The VMI is a super set of the GHI.
 * The ulFunction parameter value changes to the appropriate VMI_CMD_ function name.

The following table lists the GRADD Graphics Hardware Interface functions and whether they are mandatory or optional.

GHI_CMD_BANK
Description:
 * Syntax

GHI_CMD_BANK is optional and is called to set or get the region or bank number of the active area of the video display. The GRADD can return this function call to VMAN for simulation.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_BANK. */ PVOID   pIn;         /*  Pointer to a HWBANKIN data structure. */ PVOID   pOut;        /*  Pointer to a HWBANKOUT data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_BANK.
 * pIn(PVOID) - input Pointer to a data structure.
 * pOut(PVOID) - output Pointer to a data structure.
 * rc(ULONG) - returns Return codes.
 * RC_ERROR
 * RC_SIMULATE
 * RC_SUCCESS

GHI_CMD_BITBLT
Description:
 * Syntax

GHI_CMD_BITBLT is optional and is called to draw bit maps to and from the video display. The GRADD can return this function call to VMAN for simulation.


 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_BITBLT. */ PVOID   pIn;         /*  Pointer to a BITBLTINFO data structure. */ PVOID   pOut;        /*  NULL; no output structure needed. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);

gid(GID) - input ID of the GRADD.
 * Parameters

ulFunction(ULONG) - input Set equal to GHI_CMD_BITBLT.

pIn(PVOID) - input Pointer to a data structure.

pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.
 * RC_SIMULATE
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_EVENT
Description:
 * Syntax

GHI_CMD_EVENT is optional and is called to notify a GRADD of specific events.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_EVENT. */ PVOID   pIn;         /*  Pointer to an HWEVENTIN data structure. */ PVOID   pOut;        /*  NULL; no output structure needed. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_EVENT.
 * pIn(PVOID) - input Pointer to an data structure.
 * pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.
 * RC_UNSUPPORTED
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_EXTENSION
Description:
 * Syntax

GHI_CMD_EXTENSION is optional and is called to send an extension command to a GRADD. The extension subfunction is placed in the ulXSubFunction field of the pIn input packet.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_EXTENSION. */ PVOID   pIn;         /*  Pointer to an HWEXTENSION structure. */ PVOID   pOut;        /*  Pointer to an extension-specific output structure. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);

gid(GID) - input ID of the GRADD.
 * Parameters

ulFunction(ULONG) - input Set equal to GHI_CMD_EXTENSION.

pIn(PVOID) - input Pointer to an structure.

pOut(PVOID) - output Pointer to an extension-specific output structure.

rc(ULONG) - returns Return codes.
 * RC_UNSUPPORTED
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_INIT
Description:
 * Syntax

GHI_CMD_INIT is mandatory and is called to initialize the GRADD. It is the first command a GRADD receives from the Video Manager (VMAN).
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_INIT. */ PVOID   pIn;         /*  Pointer to a GDDINITIN data structure. */ PVOID   pOut;        /*  Pointer to a GDDINITOUT data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWEntry(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_INIT.
 * pIn(PVOID) - input Pointer to a data structure.
 * pOut(PVOID) - output Pointer to a data structure.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_INITPROC
Description:
 * Syntax

GHI_CMD_INITPROC is mandatory and informs a GRADD that a new process is being initialized. It indicates that this new process intends to be a client of the GRADD component.

The GRADD ensures that all data and code is valid under this new process.


 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_INITPROC. */ PVOID   pIn;         /*  NULL. */ PVOID   pOut;        /*  Pointer to an INITPROCOUT data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_INITPROC.
 * pIn(PVOID) - input NULL.
 * pOut(PVOID) - output Pointer to an data structure.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_LINE
Description:
 * Syntax

GHI_CMD_LINE is optional and is called to draw lines to the video display. The GRADD can return this function call to VMAN for simulation.


 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_LINE. */ PVOID   pIn;         /*  Pointer to a LINEINFO or LINEINFO2 data structure. */ PVOID   pOut;        /*  NULL; no output structure needed. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_LINE.
 * pIn(PVOID) - input Pointer to a or  data structure.
 * pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.
 * RC_SIMULATE
 * RC_SUCCESS
 * RC_ERROR

The structure can describe a sequence of line segments where each line segment may be clipped. The structure describes a sequence of line segments where only the start of the first segment and the end of the last segment may be clipped. For many cases, the simpler LINEINFO2 data can be generated more efficiently than for the more general LINEINFO data.
 * Remarks

The LINEINFO and LINEINFO2 structures can be differentiated using the ulLength field at the start of each structure.

Since the LINEINFO2 mechanism was defined after several GRADDs were already released, a LINEINFO2 structure will not be passed to a GRADD unless the GRADD sets the DS_SIMPLE_LINES flag in the ulFCFlags member of the structure returned for the  function. Note that if a GRADD indicates it can handle the LINEINFO2 structure, it may still be passed a LINEINFO structure when that generality is needed.

GHI_CMD_MOVEPTR
Description:
 * Syntax

GHI_CMD_MOVEPTR is optional and is called to move the pointer to the new location. The GRADD can return this function call to VMAN for simulation.


 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_MOVEPTR. */ PVOID   pIn;         /*  Pointer to an HWMOVEPTRIN structure. */ PVOID   pOut;        /*  NULL; no output structure needed. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_MOVEPTR.
 * pIn(PVOID) - input Pointer to an structure.
 * pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.
 * RC_SIMULATE
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_PALETTE
Description:
 * Syntax

GHI_CMD_PALETTE is mandatory if the device supports 256-color modes. This function is called to set or query the hardware palette. The GRADD is expected to respond by describing the palette in a given array or by using the palette given in the array. The GRADD is always given an structure with either the PALETTE_GET or PALETTE_SET flag to specify the operation to perform.


 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_PALETTE. */ PVOID   pIn;         /*  Pointer to an HWPALETTEINFO structure. */ PVOID   pOut;        /*  NULL; no output structure is needed. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_PALETTE.
 * pIn(PVOID) - input Pointer to an structure.
 * pOut(PVOID) - output NULL; no output structure is needed.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_QUERYCAPS
Description:
 * Syntax

GHI_CMD_QUERYCAPS is mandatory. The GRADD is expected to return its capabilities. The returned capabilities are packaged by VMAN and given to a Translation Layer. The Translation Layer uses these capabilities to decide which GHI_CMD_ functions are sent to the GRADD.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_QUERYCAPS. */ PVOID   pIn;         /*  NULL. */ PVOID   pOut;        /*  Pointer to a CAPSINFO data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_QUERYCAPS.
 * pIn(PVOID) - input NULL.
 * pOut(PVOID) - output Pointer to a data structure.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_QUERYMODES
Description:
 * Syntax

GHI_CMD_QUERYMODES is mandatory and is called to query the available video mode information. The GRADD is expected to respond with information regarding the video graphics modes supported by the GRADD.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_QUERYMODES. */ PVOID   pIn;         /*  Pointer that identifies a QUERYMODE operation. */ PVOID   pOut;        /*  Pointer to the pIn operation. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_QUERYMODES.
 * pIn(PVOID) - input Pointer that identifies a QUERYMODE operation.
 * This pointer identifies one of the following operations:
 * QUERYMODE_NUM_MODES
 * QUERYMODE_MODE_DATA
 * pOut(PVOID) - output Pointer to the pIn operation.
 * This pointer indicates one of the following, depending on the value of pIn:
 * QUERYMODE_NUM_MODES Indicates a pointer to a ULONG that is to be given the number of supported modes.
 * QUERYMODE_MODE_DATA Indicates a pointer to an array of structures large enough for the number of supported modes.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_REQUESTHW
Description:
 * Syntax

GHI_CMD_REQUESTHW is optional and allows a translation layer exclusive access to the video hardware. It can do such operations as writing directly to the video buffer.

This function is used to request and release the video hardware. The ulFlags field of the pIn data packet determines if this function is a request or a release.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_REQUESTHW. */ PVOID   pIn;         /*  Pointer to an HWREQIN data structure. */ PVOID   pOut;        /*  NULL; no output structure needed. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_REQUESTHW.
 * pIn(PVOID) - input Pointer to an data structure.
 * pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.
 * RC_UNSUPPORTED
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_SETMODE
Description:
 * Syntax

GHI_CMD_SETMODE is mandatory. The GRADD is expected to set the video mode, given an ID of the chosen mode.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_SETMODE. */ PVOID   pIn;         /*  Pointer to PULONG containing the ID of the requested mode. */ PVOID   pOut;        /*  NULL. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_SETMODE.
 * pIn(PVOID) - input Pointer to PULONG containing the ID of the requested mode.
 * pOut(PVOID) - output NULL.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_SETPTR
Description:
 * Syntax

GHI_CMD_SETPTR is optional and is called to set the pointer bit masks. Both monochrome and color pointers can be set.

The GRADD can return this function call to VMAN for simulation.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_SETPTR. */ PVOID   pIn;         /*  Pointer to an HWSETPTRIN data structure. */ PVOID   pOut;        /*  Pointer to an HWSETPTROUT data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_SETPTR.
 * pIn(PVOID) - input Pointer to an data structure.
 * pOut(PVOID) - output Pointer to an data structure.

rc(ULONG) - returns Return codes.
 * RC_SIMULATE
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_SHOWPTR
Description:
 * Syntax

GHI_CMD_SHOWPTR is optional and sets the visibility state of the pointer. The fShow field of the pIn data packet determines the visibility state.

The GRADD can return this function call to VMAN for simulation.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_SHOWPTR. */ PVOID   pIn;         /*  Pointer to an HWSHOWPTRIN data structure. */ PVOID   pOut;        /*  NULL; no output structure needed. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_SHOWPTR.
 * pIn(PVOID) - input Pointer to an data structure.
 * pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.
 * RC_SIMULATE
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_TERM
Description:
 * Syntax

GHI_CMD_TERM is optional and is called by a VMAN when it no longer requires the services of the GRADD.
 * 1) include 

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_TERM. */ PVOID   pIn;         /*  NULL. */ PVOID   pOut;        /*  NULL. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_TERM.
 * pIn(PVOID) - input NULL.
 * pOut(PVOID) - output NULL.

rc(ULONG) - returns Return codes.

RC_UNSUPPORTED
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_TERMPROC
Description:
 * Syntax

GHI_CMD_TERMPROC is optional and informs the GRADD that an existing client process is being terminated. The GRADD should clean up all resources owned by this process.
 * 1) include <GRADD.h>

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_TERMPROC. */ PVOID   pIn;         /*  NULL. */ PVOID   pOut;        /*  NULL. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_TERMPROC.
 * pIn(PVOID) - input NULL.
 * pOut(PVOID) - output NULL.

rc(ULONG) - returns Return codes.
 * RC_UNSUPPORTED
 * RC_SUCCESS
 * RC_ERROR

GHI_CMD_TEXT
Description:
 * Syntax

GHI_CMD_TEXT is optional and is called to draw text to the video display. Each textblt provides a string of characters, called glyphs, to blit to the video display. The GRADD can store the glyphs in an offscreen video cache. If another textblt has glyphs already stored in cache, the GRADD can transfer video memory to video display rather than taking the glyph from system memory. The GRADD can return this function call to VMAN for simulation.
 * 1) include <GRADD.h>

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_TEXT. */ PVOID   pIn;         /*  Pointer to a TEXTBLTINFO data structure. */ PVOID   pOut;        /*  NULL; no output structure needed. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_TEXT.
 * pIn(PVOID) - input Pointer to a data structure.
 * pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.
 * RC_SIMULATE
 * RC_SUCCESS
 * RC_ERROR

To enable and define the type of support for GHI_CMD_TEXT, the following flags should be set in the ulCFlags member of CAPSINFO: TEXTBLT_DOWNLOADABLE      Indicates downloadable fonts. TEXTBLT_CLIPABLE          Indicates clipable fonts.
 * Remarks

GHI_CMD_USERCAPS
Description:
 * Syntax

GHI_CMD_USERCAPS is used to enable and support the CAPABILITIES button on the OS/2 System Object.

When the Video Configuration Manager presents the interface to the user, each capability is presented in a separate window page of the capabilities notebook in System Object. The window layout depends on the capability type:
 * Boolean type is represented by a check box.
 * Aggregate type is represented by a list box.

The capability description appears as the title for that control.

If a GRADD is going to support capabilities in multiple languages, it must get the capability description (szCapsDesc) and capability aggregate strings, if applicable, from a resource module that contains already-translated strings.


 * 1) include <GRADD.h>

GID           gid;     /*  ID of the GRADD. */ ULONG         ulFunc;  /*  Set equal to GHI_CMD_USERCAPS. */ PUSERCAPSIN   pIn;     /*  Pointer to a USERCAPSIN data structure. */ PVOID         pOut;    /*  Pointer to a buffer area. */ ULONG         rc;      /*  Return codes. */

rc = HWENTRY(gid, ulFunc, pIn, pOut);

gid(GID) - input ID of the GRADD.
 * Parameters

ulFunc(ULONG) - input Set equal to GHI_CMD_USERCAPS.

pIn - input Pointer to a data structure.

pOut(PVOID) - output Pointer to a buffer area.

Pointer to a buffer area whose format depends on the value of the ulFunction field of the structure pointed to by pIn.

If pIn->ulFunction is QUERYCAPS, pOut points to a ULONG count followed by an array of structures. If pIn->ulFunction is QUERYCAPSLIST or SETCAP, pOut points to a DRIVERCAPS structure.

The length of the buffer area provided is specified by the ulSize field of the structure pointed to by pIn.

rc(ULONG) - returns Return codes.
 * RC_ERROR
 * RC_SUCCESS
 * RC_UNSUPPORTED

GHI_CMD_VRAM
Description:
 * Syntax

GHI_CMD_VRAM is optional and is called to request allocation of off-screen video memory.
 * 1) include <GRADD.h>

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to GHI_CMD_VRAM. */ PVOID   pIn;         /*  Pointer to a VRAMIN data structure. */ PVOID   pOut;        /*  Pointer to a function-specific output data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to GHI_CMD_VRAM.
 * pIn(PVOID) - input Pointer to a data structure.
 * pOut(PVOID) - output Pointer to a function-specific output data structure.

If the ulFunction field of the VRAMIN structure pointed to by pIn is set to VRAM_ALLOCATE, VRAM_DEALLOCATE, or VRAM_QUERY, then pOut points to a data structure.

If the ulFunction field of the VRAMIN structure pointed to by pIn is set to VRAM_REGISTER or VRAM_DEREGISTER, then pOut points to a data structure.

rc(ULONG) - returns Return codes.
 * RC_UNSUPPORTED
 * RC_SUCCESS
 * RC_ERROR

HWEntry
Description:
 * Syntax

HWEntry is the single exported function from a graphics adapter device driver (GRADD). It is part of the Graphics Hardware Interface (GHI) protocol for GRADDs and receives all of the operations from the Video Manager (VMAN) component.
 * 1) include <GRADD.h>

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set to appropriate GHI_CMD_ function. */ PVOID   pIn;         /*  Pointer to a GHI_-specific input data structure. */ PVOID   pOut;        /*  Pointer to a GHI_-specific output data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWEntry(gid, ulFunction, pIn, pOut);


 * Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set to appropriate GHI_CMD_ function.
 * This parameter is set to one of the GHI_CMD_ functions shown in the table at the beginning of this section.
 * pIn(PVOID) - input Pointer to a GHI_-specific inputdata structure.
 * pOut(PVOID) - output Pointer to a GHI_-specific outputdata structure.

rc(ULONG) - returns Return codes.

Valid values are dictated by the applicable GHI_CMD_ function.

Enhanced Direct Interface Video Extension (EnDIVE) Functions
The following table lists the EXT_CMD_ functions that are specific to the Enhanced Direct Interface Video Extension (EnDIVE) process. These EnDIVE functions do not have corresponding VMI_CMD_ functions.

The following table lists the EnDIVE functions and whether they are mandatory or optional.

EXT_CMD_ENDIVE_GET
Description:
 * Syntax

EXT_CMD_ENDIVE_GET is optional and is called to blit an image from the screen.
 * 1) include <GRADD.h>

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to EXT_CMD_ENDIVE_GET. */ PVOID   pIn;         /*  Pointer to an IMAGEPACK data structure. */ PVOID   pOut;        /*  NULL. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);


 * EXT_CMD_ENDIVE_GET - Parameters
 * gid(GID) - input ID of the GRADD.
 * ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_GET.
 * pIn(PVOID) - input Pointer to an data structure.
 * pOut(PVOID) - output NULL.

rc(ULONG) - returns Return codes.

R_SIMULATE
 * RC_SUCCESS
 * RC_ERROR

EXT_CMD_ENDIVE_INIT
Description:
 * Syntax

EXT_CMD_ENDIVE_INIT is mandatory and is called to initialize the hardware. The GRADD must determine if the hardware is present.
 * 1) include <GRADD.h>

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to EXT_CMD_ENDIVE_INIT. */ PVOID   pIn;         /*  Pointer to an FBINFO data structure. */ PVOID   pOut;        /*  Pointer to an HWEXTENSIONOUT data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);

gid(GID) - input ID of the GRADD.
 * Parameters

ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_INIT.

pIn(PVOID) - input Pointer to an data structure.

pOut(PVOID) - output Pointer to an HWEXTENSIONOUT data structure.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR

EXT_CMD_ENDIVE_PUT
Description:
 * Syntax

EXT_CMD_ENDIVE_PUT is mandatory and is called to blit an image to the screen.


 * 1) include <GRADD.h>

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to EXT_CMD_ENDIVE_PUT. */ PVOID   pIn;         /*  Pointer to an IMAGEPACK data structure. */ PVOID   pOut;        /*  NULL. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);

EXT_CMD_ENDIVE_PUT - Parameters
gid(GID) - input ID of the GRADD.

ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_PUT.

pIn(PVOID) - input Pointer to an data structure.

pOut(PVOID) - output NULL.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR

EXT_CMD_ENDIVE_QUERY
Description:
 * Syntax

EXT_CMD_ENDIVE_QUERY is mandatory and queries the capabilities of the hardware.


 * 1) include <GRADD.h>

GID     gid;         /*  ID of the GRADD. */ ULONG   ulFunction;  /*  Set equal to EXT_CMD_ENDIVE_QUERY. */ PVOID   pIn;         /*  NULL. */ PVOID   pOut;        /*  Pointer to an IMAGECAPS data structure. */ ULONG   rc;          /*  Return codes. */

rc = HWENTRY(gid, ulFunction, pIn, pOut);

gid(GID) - input ID of the GRADD.
 * Parameters

ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_QUERY.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to an data structure.

rc(ULONG) - returns Return codes.
 * RC_SUCCESS
 * RC_ERROR