Graphics Adapter Device Drivers

From EDM2
Revision as of 04:41, 26 February 2017 by Ak120 (Talk | contribs)

Jump to: navigation, search

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:

  • The VMI is a super set of the GHI.
  • The ulFunction parameter value changes to the appropriate VMI_CMD_ function name.

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);

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 #VMI_CMD_EXTENSION 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 #GHI_CMD_INIT 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 #VMI_CMD_QUERYCAPS 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 #VMI_CMD_EXTENSION 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 #Enhanced Direct Interface Video Extension (EnDIVE) Functions.

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

Function Type
GHI_CMD_BANK Optional
GHI_CMD_BITBLT Optional
GHI_CMD_EVENT Optional
GHI_CMD_EXTENSION Optional
GHI_CMD_INIT Mandatory
GHI_CMD_INITPROC Mandatory
GHI_CMD_LINE Optional
GHI_CMD_MOVEPTR Optional
GHI_CMD_PALETTE Mandatory*
GHI_CMD_QUERYCAPS Mandatory
GHI_CMD_QUERYMODES Mandatory
GHI_CMD_REQUESTHW Optional
GHI_CMD_SETMODE Mandatory
GHI_CMD_SETPTR Optional
GHI_CMD_SHOWPTR Optional
GHI_CMD_TERM Optional
GHI_CMD_TERMPROC Optional
GHI_CMD_TEXT Optional
GHI_CMD_USERCAPS Optional
GHI_CMD_VRAM Optional
HWEntry Entry point
  • At 256 color modes only.

GHI_CMD_BANK

Syntax

Description:

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.

#include <GRADD.h>

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 #HWBANKIN data structure.
pOut(PVOID) - output Pointer to a #HWBANKOUT data structure.
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SIMULATE
RC_SUCCESS

GHI_CMD_BITBLT

Syntax

Description:

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.

#include <GRADD.h>

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);
Parameters

gid(GID) - input ID of the GRADD.

ulFunction(ULONG) - input Set equal to GHI_CMD_BITBLT.

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

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

rc(ULONG) - returns Return codes.

RC_SIMULATE
RC_SUCCESS
RC_ERROR

GHI_CMD_EVENT

Syntax

Description:

GHI_CMD_EVENT is optional and is called to notify a GRADD of specific events.

#include <GRADD.h>

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 #HWEVENTIN data structure.
pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.

RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR

GHI_CMD_EXTENSION

Syntax

Description:

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.

#include <GRADD.h>

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);
Parameters

gid(GID) - input ID of the GRADD.

ulFunction(ULONG) - input Set equal to GHI_CMD_EXTENSION.

pIn(PVOID) - input Pointer to an #HWEXTENSION 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

Syntax

Description:

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

#include <GRADD.h>

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 #GDDINITIN data structure.
pOut(PVOID) - output Pointer to a #GDDINITOUT data structure.

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR

GHI_CMD_INITPROC

Syntax

Description:

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.

#include <GRADD.h>

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 #INITPROCOUTdata structure.

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR

GHI_CMD_LINE

Syntax

Description:

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.

#include <GRADD.h>

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 #LINEINFO or #LINEINFO2 data structure.
pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.

RC_SIMULATE
RC_SUCCESS
RC_ERROR
Remarks

The #LINEINFO structure can describe a sequence of line segments where each line segment may be clipped. The #LINEINFO2 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.

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 #CAPSINFO structure returned for the #GHI_CMD_QUERYCAPS 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

Syntax

Description:

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.

#include <GRADD.h>

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 #HWMOVEPTRIN structure.
pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.

RC_SIMULATE
RC_SUCCESS
RC_ERROR

GHI_CMD_PALETTE

Syntax

Description:

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 #HWPALETTEINFO structure with either the PALETTE_GET or PALETTE_SET flag to specify the operation to perform.

#include <GRADD.h>

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 #HWPALETTEINFO structure.
pOut(PVOID) - output NULL; no output structure is needed.

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR

GHI_CMD_QUERYCAPS

Syntax

Description:

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.

#include <GRADD.h>

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 #CAPSINFO data structure.

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR

GHI_CMD_QUERYMODES

Syntax

Description:

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.

#include <GRADD.h>

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 #GDDMODEINFO structures large enough for the number of supported modes.

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR

GHI_CMD_REQUESTHW

Syntax

Description:

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.

#include <GRADD.h>

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 #HWREQIN data structure.
pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.

RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR

GHI_CMD_SETMODE

Syntax

Description:

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

#include <GRADD.h>

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

Syntax

Description:

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.

#include <GRADD.h>

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 #HWSETPTRIN data structure.
pOut(PVOID) - output Pointer to an #HWSETPTROUT data structure.

rc(ULONG) - returns Return codes.

RC_SIMULATE
RC_SUCCESS
RC_ERROR

GHI_CMD_SHOWPTR

Syntax

Description:

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.

#include <GRADD.h>

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 #HWSHOWPTRIN data structure.
pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.

RC_SIMULATE
RC_SUCCESS
RC_ERROR

GHI_CMD_TERM

Syntax

Description:

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

#include <GRADD.h>

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

Syntax

Description:

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.

#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

Syntax

Description:

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.

#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 #TEXTBLTINFO data structure.
pOut(PVOID) - output NULL; no output structure needed.

rc(ULONG) - returns Return codes.

RC_SIMULATE
RC_SUCCESS
RC_ERROR
Remarks

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.

GHI_CMD_USERCAPS

Syntax

Description:

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.

#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);
Parameters

gid(GID) - input ID of the GRADD.

ulFunc(ULONG) - input Set equal to GHI_CMD_USERCAPS.

pIn(#PUSERCAPSIN) - input Pointer to a #USERCAPSIN 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 #USERCAPSIN structure pointed to by pIn.

If pIn->ulFunction is QUERYCAPS, pOut points to a ULONG count followed by an array of #DRIVERCAPS 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 #USERCAPSIN structure pointed to by pIn.

rc(ULONG) - returns Return codes.

RC_ERROR
RC_SUCCESS
RC_UNSUPPORTED

GHI_CMD_VRAM

Syntax

Description:

GHI_CMD_VRAM is optional and is called to request allocation of off-screen video memory.

#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 #VRAMIN 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 #VRAMALLOCOUT 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 #VRAMREGISTEROUT data structure.

rc(ULONG) - returns Return codes.

RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR

HWEntry

Syntax

Description:

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.

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

Function Type
EXT_CMD_ENDIVE_GET Optional
EXT_CMD_ENDIVE_INIT Mandatory
EXT_CMD_ENDIVE_PUT Mandatory
EXT_CMD_ENDIVE_QUERY Mandatory

EXT_CMD_ENDIVE_GET

Syntax

Description:

EXT_CMD_ENDIVE_GET is optional and is called to blit an image from the screen.

#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 #IMAGEPACK data structure.
pOut(PVOID) - output NULL.

rc(ULONG) - returns Return codes.

R_SIMULATE

RC_SUCCESS
RC_ERROR

EXT_CMD_ENDIVE_INIT

Syntax

Description:

EXT_CMD_ENDIVE_INIT is mandatory and is called to initialize the hardware. The GRADD must determine if the hardware is present.

#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);
Parameters

gid(GID) - input ID of the GRADD.

ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_INIT.

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

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

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR

EXT_CMD_ENDIVE_PUT

Syntax

Description:

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

#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 #IMAGEPACKdata structure.

pOut(PVOID) - output NULL.

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR

EXT_CMD_ENDIVE_QUERY

Syntax

Description:

EXT_CMD_ENDIVE_QUERY is mandatory and queries the capabilities of the hardware.

#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);
Parameters

gid(GID) - input ID of the GRADD.

ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_QUERY.

pIn(PVOID) - input NULL.

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

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR