Jump to content

Graphics Adapter Device Drivers: Difference between revisions

From EDM2
Newer edit →
Ak120 (talk | contribs)
35,819 edits
Created page with "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 Enh..."
 
Ak120 (talk | contribs)
35,819 edits
Line 104: Line 104:


=== GHI_CMD_BANK ===
=== GHI_CMD_BANK ===
=== GHI_CMD_BANK - Syntax ===
;Syntax
Description:
Description:


Line 118: Line 118:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_BANK Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_BANK.
=== GHI_CMD_BANK Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to a [[HWBANKIN]] data structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_BANK.
:'''pOut'''(PVOID) - output Pointer to a [[HWBANKOUT]] data structure.
 
:'''rc'''(ULONG) - returns Return codes.
=== GHI_CMD_BANK Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to a [[HWBANKIN]] data structure.
 
=== GHI_CMD_BANK Parameter - pOut ===
'''pOut'''(PVOID) - output Pointer to a [[HWBANKOUT]] data structure.
 
=== GHI_CMD_BANK Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.


RC_ERROR <br />RC_SIMULATE <br />RC_SUCCESS
RC_ERROR <br />RC_SIMULATE <br />RC_SUCCESS
=== GHI_CMD_BANK - 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 <br />RC_SIMULATE <br />RC_SUCCESS
=== GHI_CMD_BANK - Remarks ===
None.


=== GHI_CMD_BITBLT ===
=== GHI_CMD_BITBLT ===
=== GHI_CMD_BITBLT - Syntax ===
;Syntax
Description:
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.
''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.


<pre class="western">#include &lt;GRADD.h&gt;
<pre>#include &lt;GRADD.h&gt;


GID      gid;        /*  ID of the GRADD. */
GID      gid;        /*  ID of the GRADD. */
Line 167: Line 143:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_BITBLT Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
'''gid'''(GID) - input ID of the GRADD.


=== GHI_CMD_BITBLT Parameter - ulFunction ===
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_BITBLT.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_BITBLT.


=== GHI_CMD_BITBLT Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to a [[00981.htm|BITBLTINFO]]data structure.
'''pIn'''(PVOID) - input Pointer to a [[00981.htm|BITBLTINFO]]data structure.


=== GHI_CMD_BITBLT Parameter - pOut ===
'''pOut'''(PVOID) - output NULL; no output structure needed.
'''pOut'''(PVOID) - output NULL; no output structure needed.


=== GHI_CMD_BITBLT Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_BITBLT - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_BITBLT.
'''pIn'''(PVOID) - input Pointer to a [[00981.htm|BITBLTINFO]]data structure.
'''pOut'''(PVOID) - output NULL; no output structure needed.
'''rc'''(ULONG) - returns Return codes.
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_BITBLT - Remarks ===
None.


=== GHI_CMD_EVENT ===
=== GHI_CMD_EVENT ===
====GHI_CMD_EVENT - Syntax ====
;Syntax
Description:
Description:


''GHI_CMD_EVENT'' is optional and is called to notify a GRADD of specific events.
''GHI_CMD_EVENT'' is optional and is called to notify a GRADD of specific events.
<pre class="western">#include <GRADD.h>
<pre>#include <GRADD.h>


GID      gid;        /*  ID of the GRADD. */
GID      gid;        /*  ID of the GRADD. */
Line 215: Line 171:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


==== GHI_CMD_EVENT Parameter - gid ====
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_EVENT.
==== GHI_CMD_EVENT Parameter - ulFunction ====
:'''pIn'''(PVOID) - input Pointer to an [[HWEVENTIN]] data structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_EVENT.
:'''pOut'''(PVOID) - output NULL; no output structure needed.
 
==== GHI_CMD_EVENT Parameter - pIn ====
'''pIn'''(PVOID) - input Pointer to an [[HWEVENTIN]] data structure.
 
==== GHI_CMD_EVENT Parameter - pOut ====
'''pOut'''(PVOID) - output NULL; no output structure needed.
 
==== GHI_CMD_EVENT Return Value - rc ====
'''rc'''(ULONG) - returns Return codes.
 
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
 
==== GHI_CMD_EVENT - 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'''(ULONG) - returns Return codes.


RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
==== GHI_CMD_EVENT - Remarks ====
None.


=== GHI_CMD_EXTENSION ===
=== GHI_CMD_EXTENSION ===
==== GHI_CMD_EXTENSION - Syntax ====
;Syntax
Description:
Description:


Line 263: Line 196:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


====GHI_CMD_EXTENSION Parameter - gid====
;Parameters
'''gid'''(GID) - input ID of the GRADD.
 
====GHI_CMD_EXTENSION Parameter - ulFunction====
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_EXTENSION.
 
====GHI_CMD_EXTENSION Parameter - pIn====
'''pIn'''(PVOID) - input Pointer to an [[HWEXTENSION]] structure.
 
====GHI_CMD_EXTENSION Parameter - pOut====
'''pOut'''(PVOID) - output Pointer to an extension-specific output structure.
 
====GHI_CMD_EXTENSION Return Value - rc====
'''rc'''(ULONG) - returns Return codes.
 
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
 
====GHI_CMD_EXTENSION - Parameters====
'''gid'''(GID) - input ID of the GRADD.
'''gid'''(GID) - input ID of the GRADD.


Line 292: Line 208:


RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
====GHI_CMD_EXTENSION - Remarks====
None.


=== GHI_CMD_INIT ===
=== GHI_CMD_INIT ===
====GHI_CMD_INIT - Syntax====
;Syntax
Description:
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).
''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).
<pre>#include &lt;GRADD.h&gt;
<pre>#include <GRADD.h>


GID      gid;        /*  ID of the GRADD. */
GID      gid;        /*  ID of the GRADD. */
Line 311: Line 224:
rc = HWEntry(gid, ulFunction, pIn, pOut);</pre>
rc = HWEntry(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_INIT Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_INIT.
=== GHI_CMD_INIT Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to a [[01086.htm|GDDINITIN]]data structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_INIT.
:'''pOut'''(PVOID) - output Pointer to a [[01089.htm|GDDINITOUT]]data structure.
 
=== GHI_CMD_INIT Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to a [[GDDINITIN]] data structure.
 
=== GHI_CMD_INIT Parameter - pOut ===
'''pOut'''(PVOID) - output Pointer to a [[GDDINITOUT]] data structure.
 
=== GHI_CMD_INIT Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_INIT - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
 
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_INIT.
 
'''pIn'''(PVOID) - input Pointer to a [[01086.htm|GDDINITIN]]data structure.
 
'''pOut'''(PVOID) - output Pointer to a [[01089.htm|GDDINITOUT]]data structure.


'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_SUCCESS <br />RC_ERROR
RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_INIT - Remarks ===
None.


=== GHI_CMD_INITPROC ===
=== GHI_CMD_INITPROC ===
====GHI_CMD_INITPROC - Syntax====
;Syntax
Description:
Description:


Line 352: Line 242:
The GRADD ensures that all data and code is valid under this new process.
The GRADD ensures that all data and code is valid under this new process.


<pre class="western">#include &lt;GRADD.h&gt;
<pre>#include <GRADD.h>


GID      gid;        /*  ID of the GRADD. */
GID      gid;        /*  ID of the GRADD. */
Line 362: Line 252:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_INITPROC Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_INITPROC.
=== GHI_CMD_INITPROC Parameter - ulFunction ===
:'''pIn'''(PVOID) - input NULL.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_INITPROC.
:'''pOut'''(PVOID) - output Pointer to an [[01220.htm|INITPROCOUT]]data structure.


=== GHI_CMD_INITPROC Parameter - pIn ===
'''pIn'''(PVOID) - input NULL.
=== GHI_CMD_INITPROC Parameter - pOut ===
'''pOut'''(PVOID) - output Pointer to an [[INITPROCOUT]] data structure.
=== GHI_CMD_INITPROC Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_SUCCESS <br />RC_ERROR
RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_INITPROC - 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 [[01220.htm|INITPROCOUT]]data structure.
'''rc'''(ULONG) - returns Return codes.
RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_INITPROC - Remarks ===
None.


=== GHI_CMD_LINE ===
=== GHI_CMD_LINE ===
=== GHI_CMD_LINE - Syntax ===
;Syntax
Description:
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.
''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.


<pre class="western">#include &lt;GRADD.h&gt;
<pre>#include <GRADD.h>


GID      gid;        /*  ID of the GRADD. */
GID      gid;        /*  ID of the GRADD. */
Line 411: Line 278:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_LINE Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_LINE.
:'''pIn'''(PVOID) - input Pointer to a [[01223.htm|LINEINFO]]or [[01235.htm|LINEINFO2]]data structure.
:'''pOut'''(PVOID) - output NULL; no output structure needed.


=== GHI_CMD_LINE Parameter - ulFunction ===
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_LINE.
=== GHI_CMD_LINE Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to a [[01223.htm|LINEINFO]]or [[01235.htm|LINEINFO2]]data structure.
=== GHI_CMD_LINE Parameter - pOut ===
'''pOut'''(PVOID) - output NULL; no output structure needed.
=== GHI_CMD_LINE Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR


=== GHI_CMD_LINE - Parameters ===
;Remarks
'''gid'''(GID) - input ID of the GRADD.
 
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_LINE.
 
'''pIn'''(PVOID) - input Pointer to a [[01223.htm|LINEINFO]]or [[01235.htm|LINEINFO2]]data structure.
 
'''pOut'''(PVOID) - output NULL; no output structure needed.
 
'''rc'''(ULONG) - returns Return codes.
 
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_LINE - 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]] 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.


Line 447: Line 294:


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


===GHI_CMD_MOVEPTR===
===GHI_CMD_MOVEPTR===
====GHI_CMD_MOVEPTR - Syntax====
;Syntax
Description:
Description:


Line 466: Line 311:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_MOVEPTR Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_MOVEPTR.
=== GHI_CMD_MOVEPTR Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to an [[01139.htm|HWMOVEPTRIN]]structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_MOVEPTR.
:'''pOut'''(PVOID) - output NULL; no output structure needed.
 
=== GHI_CMD_MOVEPTR Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to an [[01139.htm|HWMOVEPTRIN]]structure.
 
=== GHI_CMD_MOVEPTR Parameter - pOut ===
'''pOut'''(PVOID) - output NULL; no output structure needed.
 
=== GHI_CMD_MOVEPTR Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_MOVEPTR - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
 
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_MOVEPTR.
 
'''pIn'''(PVOID) - input Pointer to an [[01139.htm|HWMOVEPTRIN]]structure.
 
'''pOut'''(PVOID) - output NULL; no output structure needed.


'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_MOVEPTR - Remarks ===
None.


===GHI_CMD_PALETTE===
===GHI_CMD_PALETTE===
====GHI_CMD_PALETTE - Syntax====
;Syntax
Description:
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.
''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.


<pre class="western">#include &lt;GRADD.h&gt;
<pre>#include <GRADD.h>


GID      gid;        /*  ID of the GRADD. */
GID      gid;        /*  ID of the GRADD. */
Line 515: Line 337:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_PALETTE Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_PALETTE.
=== GHI_CMD_PALETTE Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to an [[01142.htm|HWPALETTEINFO]]structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_PALETTE.
:'''pOut'''(PVOID) - output NULL; no output structure is needed.
 
=== GHI_CMD_PALETTE Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to an [[01142.htm|HWPALETTEINFO]]structure.
 
=== GHI_CMD_PALETTE Parameter - pOut ===
'''pOut'''(PVOID) - output NULL; no output structure is needed.
 
=== GHI_CMD_PALETTE Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_PALETTE - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
 
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_PALETTE.
 
'''pIn'''(PVOID) - input Pointer to an [[01142.htm|HWPALETTEINFO]]structure.
 
'''pOut'''(PVOID) - output NULL; no output structure is needed.


'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_SUCCESS <br />RC_ERROR
RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_PALETTE - Remarks ===
None.


=== GHI_CMD_QUERYCAPS ===
=== GHI_CMD_QUERYCAPS ===
 
;Syntax
=== GHI_CMD_QUERYCAPS - Syntax ===
Description:
Description:


Line 564: Line 362:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_QUERYCAPS Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_QUERYCAPS.
=== GHI_CMD_QUERYCAPS Parameter - ulFunction ===
:'''pIn'''(PVOID) - input NULL.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_QUERYCAPS.
:'''pOut'''(PVOID) - output Pointer to a [[01020.htm|CAPSINFO]]data structure.
 
=== GHI_CMD_QUERYCAPS Parameter - pIn ===
'''pIn'''(PVOID) - input NULL.
 
=== GHI_CMD_QUERYCAPS Parameter - pOut ===
'''pOut'''(PVOID) - output Pointer to a [[CAPSINFO]] data structure.
 
=== GHI_CMD_QUERYCAPS Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_QUERYCAPS - 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 [[01020.htm|CAPSINFO]]data structure.


'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_SUCCESS <br />RC_ERROR
RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_QUERYCAPS - Remarks ===
None.


===GHI_CMD_QUERYMODES===
===GHI_CMD_QUERYMODES===
====Syntax====
;Syntax
Description:  
Description:  


Line 612: Line 387:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_QUERYMODES Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_QUERYMODES.
=== GHI_CMD_QUERYMODES Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer that identifies a QUERYMODE operation.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_QUERYMODES.
::This pointer identifies one of the following operations:
 
:::QUERYMODE_NUM_MODES
=== GHI_CMD_QUERYMODES Parameter - pIn ===
:::QUERYMODE_MODE_DATA
'''pIn'''(PVOID) - input Pointer that identifies a QUERYMODE operation.
:'''pOut'''(PVOID) - output Pointer to the pIn operation.
 
::This pointer indicates one of the following, depending on the value of pIn:
This pointer identifies one of the following operations:
:::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.
QUERYMODE_NUM_MODES <br />QUERYMODE_MODE_DATA
 
=== GHI_CMD_QUERYMODES Parameter - pOut ===
'''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. <br />QUERYMODE_MODE_DATA Indicates a pointer to an array of [[GDDMODEINFO]] structures large enough for the number of supported modes.
 
=== GHI_CMD_QUERYMODES Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_QUERYMODES - 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 <br />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. <br />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'''(ULONG) - returns Return codes.


RC_SUCCESS <br />RC_ERROR
RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_QUERYMODES - Remarks ===
None.


=== GHI_CMD_REQUESTHW ===
=== GHI_CMD_REQUESTHW ===
=== GHI_CMD_REQUESTHW - Syntax ===
;Syntax
Description:
Description:


Line 678: Line 420:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_REQUESTHW Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_REQUESTHW.
=== GHI_CMD_REQUESTHW Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to an [[HWREQIN]] data structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_REQUESTHW.
:'''pOut'''(PVOID) - output NULL; no output structure needed.
 
=== GHI_CMD_REQUESTHW Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to an [[HWREQIN]] data structure.
 
=== GHI_CMD_REQUESTHW Parameter - pOut ===
'''pOut'''(PVOID) - output NULL; no output structure needed.


=== GHI_CMD_REQUESTHW Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_REQUESTHW - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_REQUESTHW.
'''pIn'''(PVOID) - input Pointer to an [[01148.htm|HWREQIN]]data structure.
'''pOut'''(PVOID) - output NULL; no output structure needed.
'''rc'''(ULONG) - returns Return codes.
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_REQUESTHW - Remarks ===
None.


=== GHI_CMD_SETMODE ===
=== GHI_CMD_SETMODE ===
=== GHI_CMD_SETMODE - Syntax ===
;Syntax
Description:
Description:


Line 726: Line 445:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_SETMODE Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_SETMODE.
=== GHI_CMD_SETMODE Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to PULONG containing the ID of the requested mode.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_SETMODE.
:'''pOut'''(PVOID) - output NULL.
 
=== GHI_CMD_SETMODE Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to PULONG containing the ID of the requested mode.
 
=== GHI_CMD_SETMODE Parameter - pOut ===
'''pOut'''(PVOID) - output NULL.
 
=== GHI_CMD_SETMODE Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_SETMODE - 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'''(ULONG) - returns Return codes.


RC_SUCCESS <br />RC_ERROR
RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_SETMODE - Remarks ===
None.


===GHI_CMD_SETPTR ===
===GHI_CMD_SETPTR ===
=== GHI_CMD_SETPTR - Syntax ===
;Syntax
Description:
Description:


Line 776: Line 472:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_SETPTR Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_SETPTR.
=== GHI_CMD_SETPTR Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to an [[01153.htm|HWSETPTRIN]]data structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_SETPTR.
:'''pOut'''(PVOID) - output Pointer to an [[01162.htm|HWSETPTROUT]]data structure.
 
=== GHI_CMD_SETPTR Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to an [[01153.htm|HWSETPTRIN]]data structure.


=== GHI_CMD_SETPTR Parameter - pOut ===
'''pOut'''(PVOID) - output Pointer to an [[01162.htm|HWSETPTROUT]]data structure.
=== GHI_CMD_SETPTR Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.
 
:RC_SIMULATE
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
:RC_SUCCESS
 
:RC_ERROR
=== GHI_CMD_SETPTR - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
 
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_SETPTR.
 
'''pIn'''(PVOID) - input Pointer to an [[01153.htm|HWSETPTRIN]]data structure.
 
'''pOut'''(PVOID) - output Pointer to an [[01162.htm|HWSETPTROUT]]data structure.
 
'''rc'''(ULONG) - returns Return codes.
 
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_SETPTR - Remarks ===
None.


=== GHI_CMD_SHOWPTR ===
=== GHI_CMD_SHOWPTR ===
=== GHI_CMD_SHOWPTR - Syntax ===
;Syntax
Description:
Description:


Line 826: Line 500:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_SHOWPTR Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_SHOWPTR.
=== GHI_CMD_SHOWPTR Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to an [[HWSHOWPTRIN]] data structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_SHOWPTR.
:'''pOut'''(PVOID) - output NULL; no output structure needed.
 
=== GHI_CMD_SHOWPTR Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to an [[01165.htm|HWSHOWPTRIN]]data structure.
 
=== GHI_CMD_SHOWPTR Parameter - pOut ===
'''pOut'''(PVOID) - output NULL; no output structure needed.
 
=== GHI_CMD_SHOWPTR Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_SHOWPTR - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
 
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_SHOWPTR.
 
'''pIn'''(PVOID) - input Pointer to an [[01165.htm|HWSHOWPTRIN]]data structure.
 
'''pOut'''(PVOID) - output NULL; no output structure needed.


'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.
 
:RC_SIMULATE
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
:RC_SUCCESS
 
:RC_ERROR
=== GHI_CMD_SHOWPTR - Remarks ===
None.


=== GHI_CMD_TERM ===
=== GHI_CMD_TERM ===
=== GHI_CMD_TERM - Syntax ===
;Syntax
Description:
Description:


Line 874: Line 526:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_TERM Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_TERM.
=== GHI_CMD_TERM Parameter - ulFunction ===
:'''pIn'''(PVOID) - input NULL.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_TERM.
:'''pOut'''(PVOID) - output NULL.


=== GHI_CMD_TERM Parameter - pIn ===
'''pIn'''(PVOID) - input NULL.
=== GHI_CMD_TERM Parameter - pOut ===
'''pOut'''(PVOID) - output NULL.
=== GHI_CMD_TERM Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_TERM - 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 <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_TERM - Remarks ===
None.


=== GHI_CMD_TERMPROC ===
=== GHI_CMD_TERMPROC ===
=== GHI_CMD_TERMPROC - Syntax ===
;Syntax
Description:
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.
''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.
<pre>#include &lt;GRADD.h&gt;
<pre>#include <GRADD.h>


GID      gid;        /*  ID of the GRADD. */
GID      gid;        /*  ID of the GRADD. */
Line 923: Line 551:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_TERMPROC Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_TERMPROC.
=== GHI_CMD_TERMPROC Parameter - ulFunction ===
:'''pIn'''(PVOID) - input NULL.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_TERMPROC.
:'''pOut'''(PVOID) - output NULL.
 
=== GHI_CMD_TERMPROC Parameter - pIn ===
'''pIn'''(PVOID) - input NULL.
 
=== GHI_CMD_TERMPROC Parameter - pOut ===
'''pOut'''(PVOID) - output NULL.


'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_TERMPROC - 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 <br />RC_SUCCESS <br />RC_ERROR
=== GHI_CMD_TERMPROC - Remarks ===
None.


=== GHI_CMD_TEXT ===
=== GHI_CMD_TEXT ===
=== GHI_CMD_TEXT - Syntax ===
;Syntax
Description:
Description:


Line 970: Line 576:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_TEXT Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_TEXT.
=== GHI_CMD_TEXT Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to a [[TEXTBLTINFO]] data structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_TEXT.
:'''pOut'''(PVOID) - output NULL; no output structure needed.
 
=== GHI_CMD_TEXT Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to a [[01312.htm|TEXTBLTINFO]]data structure.
 
=== GHI_CMD_TEXT Parameter - pOut ===
'''pOut'''(PVOID) - output NULL; no output structure needed.
 
=== GHI_CMD_TEXT Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_TEXT - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
 
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_TEXT.
 
'''pIn'''(PVOID) - input Pointer to a [[01312.htm|TEXTBLTINFO]]data structure.
 
'''pOut'''(PVOID) - output NULL; no output structure needed.


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


RC_SIMULATE <br />RC_SUCCESS <br />RC_ERROR
;Remarks
 
=== GHI_CMD_TEXT - 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:
To enable and define the type of support for GHI_CMD_TEXT, the following flags should be set in the ulCFlags member of CAPSINFO:
<pre>
<pre>
Line 1,008: Line 595:


=== GHI_CMD_USERCAPS ===
=== GHI_CMD_USERCAPS ===
=== GHI_CMD_USERCAPS - Syntax ===
;Syntax
Description:
Description:


''GHI_CMD_USERCAPS'' is used to enable and support the CAPABILITIES button on the OS/2 System Object.
''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 :
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.
Boolean type is represented by a check box. <br />Aggregate type is represented by a list box.
:Aggregate type is represented by a list box.
 
The capability description appears as the title for that control.
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.
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.


<pre class="western">#include &lt;GRADD.h&gt;
<pre>#include <GRADD.h>


GID            gid;    /*  ID of the GRADD. */
GID            gid;    /*  ID of the GRADD. */
Line 1,031: Line 617:
rc = HWENTRY(gid, ulFunc, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunc, pIn, pOut);</pre>


=== GHI_CMD_USERCAPS Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
'''gid'''(GID) - input ID of the GRADD.


=== GHI_CMD_USERCAPS Parameter - ulFunc ===
'''ulFunc'''(ULONG) - input Set equal to GHI_CMD_USERCAPS.
'''ulFunc'''(ULONG) - input Set equal to GHI_CMD_USERCAPS.


=== GHI_CMD_USERCAPS Parameter - pIn ===
'''pIn'''([[PUSERCAPSIN]]) - input Pointer to a [[USERCAPSIN]] data structure.
'''pIn'''([[PUSERCAPSIN]]) - input Pointer to a [[USERCAPSIN]]data structure.


=== GHI_CMD_USERCAPS Parameter - pOut ===
'''pOut'''(PVOID) - output Pointer to a buffer area.
'''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 [[01327.htm|USERCAPSIN]] structure pointed to by pIn.
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 [[01047.htm|DRIVERCAPS]] structures. If pIn->ulFunction is QUERYCAPSLIST or SETCAP, pOut points to a [[DRIVERCAPS]] structure.
If pIn-&gt;ulFunction is QUERYCAPS, pOut points to a ULONG count followed by an array of [[DRIVERCAPS]] structures. If pIn-&gt;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.
The length of the buffer area provided is specified by the ulSize field of the [[USERCAPSIN]] structure pointed to by pIn.
=== GHI_CMD_USERCAPS Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
RC_ERROR <br />RC_SUCCESS <br />RC_UNSUPPORTED
=== GHI_CMD_USERCAPS - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
'''ulFunc'''(ULONG) - input Set equal to GHI_CMD_USERCAPS.
'''pIn'''([[01327.htm|PUSERCAPSIN]]) - input Pointer to a [[01327.htm|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-&gt;ulFunction is QUERYCAPS, pOut points to a ULONG count followed by an array of [[DRIVERCAPS]] structures. If pIn-&gt;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 [[01327.htm|USERCAPSIN]] structure pointed to by pIn.


'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.


RC_ERROR <br />RC_SUCCESS <br />RC_UNSUPPORTED
RC_ERROR <br />RC_SUCCESS <br />RC_UNSUPPORTED
=== GHI_CMD_USERCAPS - Remarks ===
None.


=== GHI_CMD_VRAM ===
=== GHI_CMD_VRAM ===
=== GHI_CMD_VRAM - Syntax ===
;Syntax
Description:
Description:


Line 1,091: Line 651:
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>
rc = HWENTRY(gid, ulFunction, pIn, pOut);</pre>


=== GHI_CMD_VRAM Parameter - gid ===
;Parameters
'''gid'''(GID) - input ID of the GRADD.
:'''gid'''(GID) - input ID of the GRADD.
 
:'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_VRAM.
=== GHI_CMD_VRAM Parameter - ulFunction ===
:'''pIn'''(PVOID) - input Pointer to a [[VRAMIN]] data structure.
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_VRAM.
:'''pOut'''(PVOID) - output Pointer to a function-specific output data structure.
 
=== GHI_CMD_VRAM Parameter - pIn ===
'''pIn'''(PVOID) - input Pointer to a [[VRAMIN]] data structure.
 
=== GHI_CMD_VRAM Parameter - pOut ===
'''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.
 
=== GHI_CMD_VRAM Return Value - rc ===
'''rc'''(ULONG) - returns Return codes.
 
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
 
=== GHI_CMD_VRAM - Parameters ===
'''gid'''(GID) - input ID of the GRADD.
 
'''ulFunction'''(ULONG) - input Set equal to GHI_CMD_VRAM.
 
'''pIn'''(PVOID) - input Pointer to a [[01411.htm|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_ALLOCATE, VRAM_DEALLOCATE, or VRAM_QUERY, then pOut points to a [[VRAMALLOCOUT]] data structure.
Line 1,126: Line 662:


'''rc'''(ULONG) - returns Return codes.
'''rc'''(ULONG) - returns Return codes.
 
:RC_UNSUPPORTED
RC_UNSUPPORTED <br />RC_SUCCESS <br />RC_ERROR
:RC_SUCCESS
:RC_ERROR


===HWEntry ===
===HWEntry ===

Revision as of 03:28, 4 January 2017

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

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 GDDINITINdata structure.
pOut(PVOID) - output Pointer to a GDDINITOUTdata 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 LINEINFOor LINEINFO2data 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 HWMOVEPTRINstructure.
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 HWPALETTEINFOstructure.
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 CAPSINFOdata 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 HWSETPTRINdata structure.
pOut(PVOID) - output Pointer to an HWSETPTROUTdata 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 IMAGECAPSdata structure.

rc(ULONG) - returns Return codes.

RC_SUCCESS
RC_ERROR

Retrieved from "https://www.edm2.com/index.php?title=Graphics_Adapter_Device_Drivers&oldid=39061"