Jump to content

Graphics Adapter Device Driver Reference: Difference between revisions

From EDM2
← Older edit
Ak120 (talk | contribs)
35,819 edits
mNo edit summary
 
(25 intermediate revisions by 2 users not shown)
Line 1: Line 1:
By [[IBM]]
{{GRADDRef}}
{{IBM-Reprint}}


==About This Book==
==About This Book==
Line 11: Line 12:
This book includes the following chapters and supporting appendixes:
This book includes the following chapters and supporting appendixes:


[[Introduction to Graphics Adapter Device Drivers]]
;[[Introduction to Graphics Adapter Device Drivers]]:This chapter briefly describes the design philosophy of the GRADD Model.
:This chapter briefly describes the design philosophy of the GRADD Model.
;[[GRADD Model Components]]:This chapter provides details on each of the components and how they work together within the GRADD Model.
 
;[[Video Manager]]:This chapter contains a list of the Video Manager Interface functions, as well as a detailed description of each.
[[GRADD Model Components]]
;[[Graphics Adapter Device Drivers]]:This chapter describes the device driver interface (DDI) for a GRADD, how and when to add extensions, and detailed description of each Graphics Hardware Interface function. In addition, this chapter describes the Enhanced Direct Interface Video Extension (EnDIVE) functions.
:This chapter provides details on each of the components and how they work together within the GRADD Model.
;[[VIDEOPMI.DLL Exported Functions]]:This chapter describes the format and syntax used to define the data necessary to set a video mode while in OS/2 Protect Mode. It also includes the APIs.
 
;[[VIDEO Protect-Mode Interface]]:This chapter discusses the purpose of the VIDEO Protect-Mode Interface (PMI) used in IBM Operating System/2. It is an extension of the VESA SVPMI standard currently in use by the operating system's base and virtual video subsystems. The PMI provides a means of setting Super VGA video modes while in Protect Mode and of enabling their virtualization in multiple DOS sessions.
[[Video Manager]]
;[[VIDEOCFG.DLL Exported Functions|Installing Video Configuration Manager for OS/2]]:This chapter discussed the Video Configuration Manager (VCMAN), the OS/2 operating-system-service module VIDEOCFG.DLL, how video installation and configuration information is stored in a persistent namespace in the Registry; this discussion includes the functions used to install and configure video adapters and monitors.
:This chapter contains a list of the Video Manager Interface functions, as well as a detailed description of each.
 
[[Graphics Adapter Device Drivers]]
:This chapter describes the device driver interface (DDI) for a GRADD, how and when to add extensions, and detailed description of each Graphics Hardware Interface function. In addition, this chapter describes the Enhanced Direct Interface Video Extension (EnDIVE) functions.
 
[[VIDEOPMI.DLL Exported Functions]]
:This chapter describes the format and syntax used to define the data necessary to set a video mode while in OS/2 Protect Mode. It also includes the APIs.
 
[[VIDEO Protect-Mode Interface]]
:This chapter discusses the purpose of the VIDEO Protect-Mode Interface (PMI) used in IBM Operating System/2. It is an extension of the VESA SVPMI standard currently in use by the operating system's base and virtual video subsystems. The PMI provides a means of setting Super VGA video modes while in Protect Mode and of enabling their virtualization in multiple DOS sessions.


'''Appendixes'''
'''Appendixes'''


Appendix A. OS/2 Version Compatibility Considerations
;Appendix A. OS/2 Version Compatibility Considerations:This appendix describes information in terms of version compatibility.
:This appendix describes information in terms of version compatibility.
;Appendix B. [[{{PAGENAME}}/Syntax Conventions|Syntax Conventions]]:This appendix indicates the conventions that have been used for the parameter names found in the data types.
 
;Appendix C. [[{{PAGENAME}}/Data Types|Data Types]]:This appendix contains a description of the parameters for all the data types called by the Video Manager Interface, the Graphics Hardware Interface, the Video Configuration Manager, and the Protect-Mode Interface.
Appendix B. Syntax Conventions
;Appendix D. Notices:This appendix contains legal notices.
:This appendix indicates the conventions that have been used for the parameter names found in the data types.
;[[GRADD Reference Glossary|Miscellaneous]]:A glossary and an index are included.
 
Appendix C. Data Types
:This appendix contains a description of the parameters for all the data types called by the Video Manager Interface, the Graphics Hardware Interface, the Video Configuration Manager, and the Protect-Mode Interface.
 
Appendix D. Notices
:This appendix contains legal notices.
 
Miscellaneous
:A glossary and an index are included.


===Assistance===
===Assistance===
Line 52: Line 34:


Additional assistance is available through the IBM Solution Developer Program. For membership information:
Additional assistance is available through the IBM Solution Developer Program. For membership information:
 
:Internet: ibmsdp@vnet.ibm.com
Internet: ibmsdp@vnet.ibm.com
:US/Canada: 800-627-8363
 
:International: 770-835-9902
US/Canada: 800-627-8363
:International Fax: 770-835-9444
 
International: 770-835-9902
 
International Fax: 770-835-9444


=== Ordering Information ===
=== Ordering Information ===
Line 73: Line 51:
*The Display Device Driver Reference
*The Display Device Driver Reference
*The Printer Device Driver Reference
*The Printer Device Driver Reference
*The The MMPM/2 Device Driver Reference (Multimedia)
*The MMPM/2 Device Driver Reference (Multimedia)
 
To order the DDK call:
<pre>
|U.S.A.:            |1-800-633-8266
|--------------------+--------------
|Canada:            |1-800-561-5293
|--------------------+---------------------+---------------------|
|When calling from  |  English            |(+45) 48101500      |
|Europe, the Middle  |  French            |(+45) 48101200      |
|East, or Africa, the|  Italian            |(+45) 48101600      |
|number depends on  |  German            |(+45) 48101000      |
|the language you use|  Spanish            |(+45) 48101100      |
|to place the order: |  Dutch              |(+45) 48101400      |
|                    |  Danish            |(+45) 48101300      |
|                    |  Finish            |(+45) 48101650      |
|                    |  Swedish            |(+45) 48101150      |
|                    |  Norwegian          |(+45) 48101250      |
|                    |  FAX                |(+45) 48142207      |
|--------------------+---------------------+---------------------|
|When ordering from  |  Bolivia            |    02-35 1840      |
|Latin America or    |  Columbia          |  01-257-0111      |
|South America, the  |  Dominican Republic |      566-5161      |
|number depends on  |  El Salvador        |    02-98 5011      |
|the country from    |  Honduras          |      32-2319      |
|which you are      |  Paraguay          |  021-444 094      |
|calling:            |  Urugruay          |    02-923 617      |
|                    |  Chile              |  02-633-4400      |
|                    |  Costa Rica        |      223-6222      |
|                    |  Ecuador            |    02-56 5100      |
|                    |  Guatemala          |    02-31 5859      |
|                    |  Panama            |    02-639 977      |
|                    |  Peru              |  014-36 6345      |
|                    |  Venezuela          |  02-908-8901      |
|                    |  Argentina          |  01-313-0014      |
|--------------------+---------------------+---------------------|
|To order from Asia/ |  All except Japan  |(61) 2-354-7684
|Pacific:            |  Japan              |(81) 3-3495-2045(Fax)
|                    |                    |Fax request to:
|                    |                    |DAP-J, IBM Japan
|--------------------+---------------------+---------------------
|To order from SE    |(021) 800-6120(Voice)|
|Brazil:            |(021) 800-6936(Fax)  |
|--------------------+---------------------+---------------------
|To order from      |  Mexico City        |627-2444
|Mexico:            |  Country            |91-800-00639
</pre>
 
==VIDEOPMI.DLL Exported Functions==
VIDEOPMI is a 32-bit dynamic link library (DLL) that represents the main Video Protect-Mode Interface handler on OS/2 Warp.
 
VIDEOPMI exports a single 32-bit or a 16-bit entry point (VIDEOPMI32Request or VIDEOPMI16Request), depending on which one of its numerous base video functions can be invoked-SetMode, SetPalette, SetFont, and so on. All of the exported entry points are prototyped, together with the PMI-related structures, in the common header file SVGADEFS.H. See [[#VIDEOPMI32Request]] for details about this single entry point.
 
VIDEOPMI imports device-specific functions from the underlying PMI subsystem, as provided by the video chip vendor. The PMI subsystem can be a flat .PMI file, a .DLL shared library, or a combination of the two. See [[#VIDEO Protect-Mode Interface]] for more information on the PMI subsystem.
 
All VIDEOPMI functions, except [[#PMIREQUEST_SOFTWAREINT]], require that the PMI subsystem be loaded by issuing [[#PMIREQUEST_LOADPMIFILE]] and that the [[#VIDEO_ADAPTER]] "hvideo" handle and "adapter instance" be passed into the new request.
 
The [[#ADAPTERINFO]] and [[#VIDEOMODEINFO]] data structures, within VIDEO_ADAPTER, are sizable. The AdapterInfo_cb and VideoModeInfo_cb fields should be set by the caller of VIDEOPMI. The adapter handle and instance allow VIDEOPMI and the underlying PMI subsystem to differentiate target adapters in the case of multiple devices. VIDEOPMI is also allowed to target a preferred PMI subsystem for a single video device when running multiple PMI subsystems that provide complimentary but distinct functions.
 
VIDEOPMI's most important function is video mode set. VIDEOPMI exports an API to query how many mode sets are supported, as well as a mode query API that will copy the mode table into a client-allocated memory block. VIDEOMODEINFO is a sizable data structure. The VideoModeInfo_cb field should be checked before assuming VIDEOMODEINFO format. Each mode in the table contains a mode ID that should be returned when issuing the mode. However, mode setting is parametric. The underlying PMI subsystem allows ( if implemented correctly by the vendor) for individual mode parameters to be set to the desired value, rather than to the value in the VIDEOMODEINFO structure for that mode ID in the mode table.
 
'''Note:'''Clients issuing a [SetMode] are obligated to set [[#VIDEO_ADAPTER]] and [[#VIDEOMODEINFO]] structures to desired values, even if they are the same as the mode ID values; otherwise, some mode parameters may not be set correctly.
 
There is only one exported entry point for VIDEOPMI. The various PMI services are accessed through different function numbers passed in the parameters. The exported entry point is prototyped, together with the PMI- related structures, in the common header file SVGADEFS.H.
 
=== Supported Functions ===
{|class="wikitable"
!Function Name||Purpose
|-
|VIDEOPMI32Request||Entry point for all PMIREQUEST_ APIs
|-
|PMIREQUEST_CLEANUP||Clean up extended registers
|-
|PMIREQUEST_GETBANK||Get currently addressed bank
|-
|PMIREQUEST_GETCLUT||Get copy of Color Lookup Table
|-
|PMIREQUEST_GETFONT||Get current loaded font
|-
|PMIREQUEST_GETPALETTE||Get copy of palette registers
|-
|PMIREQUEST_IDENTIFYADAPTER||Identify the installed adapter
|-
|PMIREQUEST_LOADPMIFILE||Load the specified PMI file
|-
|PMIREQUEST_LOCKREGISTERS||Lock extended registers
|-
|PMIREQUEST_QUERYMAXMODEENTRIES||Return number of available modes
|-
|PMIREQUEST_QUERYMAXMODELISTSIZE||Return maximum size required to store mode data
|-
|PMIREQUEST_QUERYMAXTRAPENTRIES||Return number of trap entries
|-
|PMIREQUEST_QUERYMODEHRDWRLIST||Return the set mode command list
|-
|PMIREQUEST_QUERYMODEINFODATA||Return table of video mode information
|-
|PMIREQUEST_QUERYTRAPLISTDATA||Return table of data for trapped ports
|-
|PMIREQUEST_RESTORESTATE||Restore video adapter state
|-
|PMIREQUEST_SAVESTATE||Save video adapter state
|-
|PMIREQUEST_SETBANK||Set current bank
|-
|PMIREQUEST_SETCLUT||Set Color Lookup Table
|-
|PMIREQUEST_SETFONT||Load given font
|-
|PMIREQUEST_SETMEMORYIOADDRESS||Set the linear aperture address
|-
|PMIREQUEST_SETMODE||Set the given mode
|-
|PMIREQUEST_SETPALETTE||Set palette registers
|-
|PMIREQUEST_SOFTWAREINT||Execute real-mode software interrupt
|-
|PMIREQUEST_TUNEDISPLAY||Tune the display
|-
|PMIREQUEST_UNLOADPMIFILE||Unload specified .PMI file
|-
|PMIREQUEST_UNLOCKREGISTERS||Unlock extended registers
|}
The individual VIDEOPMI DLL exported functions are described next, followed by code samples for loading a .PMI file, setting up a mode table, and doing a SetMode.
 
=== VIDEOPMI32Request ===
====Syntax====
Description:
 
''VIDEOPMI32Request'' is the single, exported entry point from VIDEOPMI.DLL. The various PMI services are accessed through different function numbers passed in the parameters.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to the current VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set to appropriate PMIREQUEST_ function. */
PVOID            pIn;        /*  Pointer to applicable data structure. */
PVOID            pOut;        /*  Pointer to applicable data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== VIDEOPMI32Request - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - in/out Pointer to the current [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set to appropriate PMIREQUEST_ function.
 
'''pIn'''(PVOID) - input Pointer to applicable data structure.
 
'''pOut'''(PVOID) - output Pointer to applicable data structure.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== VIDEOPMI32Request - Remarks ===
When issuing this VIDEOPMI32Request, AdapterInfo_cp and VideoModeInfo_cp in VIDEO_ADAPTER should be set to sizeof(ADAPTERINFO) and sizeof(VIDEOMODEINFO). This way, VIDEOPMI can handle callers built from different sizes of [[#ADAPTERINFO]] [[#VIDEOMODEINFO]] and included in different versions of OS/2 Warp.
 
There is a 16-bit entry point, VIDEOPMI16Request, from VIDEOPMI.DLL for 16-bit callers. It functions exactly the same as its 32-bit counterpart VIDEOPMI32Request. Refer to the VIDEO_ADAPTER data structure in [[#Data Types]] for format and syntax information.
 
=== PMIREQUEST_CLEANUP ===
=== PMIREQUEST_CLEANUP - Syntax ===
Description:
 
''PMIREQUEST_CLEANUP'' cleans up the settings in extended registers.
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_CLEANUP. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_CLEANUP - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_CLEANUP.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_CLEANUP - Remarks ===
The [CLEANUP] section in the .PMI file will be executed. The graphics adapter can be set to VGA-compatible state by executing [UNLOCK] and [ CLEANUP] sections in the .PMI file.
 
=== PMIREQUEST_GETBANK ===
=== PMIREQUEST_GETBANK - Syntax ===
Description:
 
''PMIREQUEST_GETBANK'' gets current bank.
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_GETBANK. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a BANKDATA data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_GETBANK - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_GETBANK.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a [[#BANKDATA]] data structure.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_GETBANK - Remarks ===
The bank number is obtained by executing the [GETBANK] section in the .PMI file. The bank number is saved in r0 in the .PMI file. It is then saved in ''ulBank'' in the [[#BANKDATA]] data structure. ''miBank'' in BANKDATA is the current mode ID.
 
=== PMIREQUEST_GETCLUT ===
=== PMIREQUEST_GETCLUT - Syntax ===
Description:
 
''PMIREQUEST_GETCLUT'' gets a copy of Color Lookup Table from hardware.
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_GETCLUT. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a CLUTDATA data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction, pIn, pOut);
</pre>
 
=== PMIREQUEST_GETCLUT - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_GETCLUT.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a [[#CLUTDATA]] data structure.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_GETCLUT - Remarks ===
The Color Lookup Table is set through I/O ports 0X3C7, 0X3C8, and 0X3C9. If the adapter does not use these I/O ports to set the Color Lookup Table, for example, memory-mapped adapters, this function will not work.
 
=== PMIREQUEST_GETFONT ===
=== PMIREQUEST_GETFONT - Syntax ===
Description:
 
''PMIREQUEST_GETFONT'' reads current font from video memory.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_GETFONT. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a FONTDATA data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_GETFONT - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_GETFONT.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a [[FONTDATA]] data structure.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_GETFONT - Remarks ===
''ulCharCount'' in the [[FONTDATA]] data structure is the number of characters in the font. ''ulFontHeight'' is the number of scanlines per character. ''bFontData'' is the start of the font data. The size is (''ulCharCount * ulFontHeight'') bytes.
 
=== PMIREQUEST_GETPALETTE ===
=== PMIREQUEST_GETPALETTE - Syntax ===
Description:
 
''PMIREQUEST_GETPALETTE'' gets a copy of palette registers from hardware.
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_GETPALETTE. */
PVOID            pInput;      /*  NULL. */
PVOID            pOut;        /*  Pointer to a PALETTEDATA data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pInput, pOut);</pre>
 
=== PMIREQUEST_GETPALETTE - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_GETPALETTE.
 
'''pInput'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a [[#PALETTEDATA]] data structure.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_GETPALETTE - Remarks ===
The palette registers here are the palette registers indexed 0X00 - 0X0F in 0X3C0.
 
=== PMIREQUEST_IDENTIFYADAPTER ===
====Syntax====
Description:
 
''PMIREQUEST_IDENTIFYADAPTER'' executes the [IdentifyAdapter] section in the specified .PMI file.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_IDENTIFYADAPTER. */
PVOID            pIn;        /*  Pointer to the ASCII string of the .PMI file. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_IDENTIFYADAPTER - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_IDENTIFYADAPTER.
 
'''pIn'''(PVOID) - input Pointer to the ASCII string of the .PMI file.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR if the .PMI file is for the adapter installed; otherwise, returns ERROR_ADAPTER_NOT_SUPPORTED.
 
=== PMIREQUEST_IDENTIFYADAPTER - Remarks ===
This API can be executed without loading the .PMI file. The API serves as a quick test for whether the video represented by the ''pIn''.PMI file is supported. If it is supported, the ''pAdapter''->Adapter structure is filled. For any subsequent use of VIDEOPMI, [[#PMIREQUEST_LOADPMIFILE]] has to be executed.
 
=== PMIREQUEST_LOADPMIFILE ===
=== PMIREQUEST_LOADPMIFILE - Syntax ===
Description:
''PMIREQUEST_LOADPMIFILE'' loads the specified .PMI file.
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_LOADFILE. */
PVOID            pIn;        /*  Pointer to the ASCII string of the .PMI file. */
PVOID            pOut;        /*  Pointer to BOOL; can be NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_LOADPMIFILE - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_LOADFILE.
 
'''pIn'''(PVOID) - input Pointer to the ASCII string of the .PMI file.
 
'''pOut'''(PVOID) - output Pointer to BOOL; can be NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_LOADPMIFILE - Remarks ===
If the .PMI file is successfully loaded, the ''Adapter''field in [[#VIDEO_ADAPTER]] will be filled with the information from the .PMI file.
 
If ''pOut''is not NULL, ''*pOut''is set to TRUE if the .PMI file is already loaded; FALSE, otherwise. Refer to [[#ADAPTERINFO]] and [[#VIDEO_ADAPTER]] data structures in [[#Data Types]] for format and syntax information.
 
=== PMIREQUEST_LOCKREGISTERS ===
=== PMIREQUEST_LOCKREGISTERS - Syntax ===
Description:
 
''PMIREQUEST_LOCKREGISTERS''locks extended registers.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_LOCKREGISTERS. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
Return Value - rc
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
====Parameters====
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_LOCKREGISTERS.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
====Remarks====
The [LOCK] section in the .PMI file will be executed.
 
=== PMIREQUEST_QUERYMAXMODEENTRIES ===
====Syntax====
Description:
''PMIREQUEST_QUERYMAXMODEENTRIES'' returns the number of mode entries in the .PMI file.
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXMODEENTRIES. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
====Parameters====
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODEENTRIES.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a ULONG.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
====Remarks====
None.
 
=== PMIREQUEST_QUERYMAXMODELISTSIZE ===
====Syntax====
Description:
 
''PMIREQUEST_QUERYMAXMODELISTSIZE'' returns maximum size required to save a SetMode command list.
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXMODELISTSIZE. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
====Parameters====
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODELISTSIZE.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a ULONG.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
====Remarks====
Not all modes have a command list. Modes whose [SetMode] sections have no PMI sequence commands have no hardware command lists.
 
The hardware state of such modes can neither be saved nor restored by VIDEOPMI, but can be saved by a META-PMI handler provided by the vendor.
 
=== PMIREQUEST_QUERYMAXTRAPENTRIES ===
=== PMIREQUEST_QUERYMAXTRAPENTRIES - Syntax ===
Description:
 
''PMIREQUEST_QUERYMAXTRAPENTRIES''returns the maximum number of traplist entries in the [TRAPREGS] section of the .PMI file.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXTRAPENTRIES. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
====Parameters====
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_QUERYMAXTRAPENTRIES.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a ULONG.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_QUERYMAXTRAPENTRIES - Remarks ===
This function is not supported in OS/2 Warp, Version 3. The [TRAPREGS] section is currently read and used by the virtual video driver, not by videopmi.
 
=== PMIREQUEST_QUERYMODEHRDWRLIST ===
=== PMIREQUEST_QUERYMODEHRDWRLIST - Syntax ===
Description:
 
''PMIREQUEST_QUERYMODEHRDWRLIST''returns the SetMode hardware command list of the passed mode ID.
 
<pre>#include <GRADD.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_QUERYMODEHRDWRLIST. */
PVOID            pIn;        /*  Pointer to a ULONG. */
PVOID            pOut;        /*  Pointer to VOID. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_QUERYMODEHRDWRLIST - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTER data structure .
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_QUERYMODEHRDWRLIST.
 
'''pIn'''(PVOID) - input Pointer to a ULONG.
 
'''pOut'''(PVOID) - output Pointer to VOID.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_QUERYMODEHRDWRLIST - Remarks ===
None.
 
=== PMIREQUEST_QUERYMODEINFODATA ===
=== PMIREQUEST_QUERYMODEINFODATA - Syntax ===
Description:
 
''PMIREQUEST_QUERYMODEINFODATA''copies the PMI mode table to the caller.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_QUERYMODEINFODATA. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a MODEINFO data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
====Parameters====
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_QUERYMODEINFODATA.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a MODEINFO data structure.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_QUERYMODEINFODATA - Remarks ===
''pOut''is the pointer to an area allocated by the caller. The size of that area is the number of modes obtained by [[#PMIREQUEST_QUERYMAXMODEENTRIES]], multiplied by the size of [[#VIDEOMODEINFO]].
 
=== PMIREQUEST_QUERYTRAPLISTDATA ===
=== PMIREQUEST_QUERYTRAPLISTDATA - Syntax ===
Description:
 
''PMIREQUEST_QUERYTRAPLISTDATA'' returns an array of trap register information structures in the [TRAPREG] section of the .PMI file.
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_QUERYTRAPLISTDATA. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_QUERYTRAPLISTDATA - Parameters ===
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_QUERYTRAPLISTDATA.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_QUERYTRAPLISTDATA - Remarks ===
This function is not supported in OS/2 Warp, Version 3. See "Remarks" in [[#PMIREQUEST_QUERYMAXTRAPENTRIES]].
 
=== PMIREQUEST_RESTORESTATE ===
=== PMIREQUEST_RESTORESTATE - Syntax ===
Description:
 
''PMIREQUEST_RESTORESTATE''restores the state of the hardware from supplied data.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_RESTORESTATE. */
PVOID            pIn;        /*  Pointer to a VIDEOSTATE data structure. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_RESTORESTATE - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure .
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_RESTORESTATE.
 
'''pIn'''(PVOID) - input Pointer to a [[#VIDEOSTATE]] data structure.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_RESTORESTATE - Remarks ===
See [[#PMIREQUEST_SAVESTATE]].
 
=== PMIREQUEST_SAVESTATE ===
Description:
 
''PMIREQUEST_SAVESTATE''saves partial or complete state of the hardware.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SAVESTATE. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a VIDEOSTATE data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_SAVESTATE - Syntax ===
 
Description:
 
''PMIREQUEST_SAVESTATE''saves partial or complete state of the hardware.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SAVESTATE. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  Pointer to a VIDEOSTATE data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
====Parameters====
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure .
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_SAVESTATE.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output Pointer to a [[#VIDEOSTATE]] data structure.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
====Remarks====
''miState''in the [[#VIDEOSTATE]] data structure is the current mode ID in [[#VIDEOMODEINFO]].
 
Four states can be saved and restored by setting ''fStateFlags''and related fields in VIDEOSTATE accordingly, as follows:
*Video mode (STATEFLAG_REGISTERS)
 
The Set Mode command list was saved in ''pModeData''when the mode was set. For saving state, the values of registers used by BOUTB are copied back to ''pModeData.''For restoring state, ''pModeData''is executed to set the mode.
 
*Video Memory (STATEFLAG_VRAM)
 
Video memory of size ''ulVRAMSaveSize''is saved to ''pVRAM''in saving state or restored from ''pVRAM''in restoring state.
 
*Color Lookup Table (STATEFLAG_CLUT)
 
Color Lookup Table can be saved to or restored from ''pCLUT.''
 
*Font (STATEFLAG_FONT)
 
Font can be saved to or restored from ''pFont.''
 
=== PMIREQUEST_SETBANK ===
Description:
 
''PMIREQUEST_SETBANK''sets bank to requested value.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SETBANK. */
PVOID            pIn;        /*  Pointer to a BANKDATA data structure. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
====Parameters====
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure .
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_SETBANK.
 
'''pIn'''(PVOID) - input Pointer to a [[#BANKDATA]] data structure.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
====Remarks====
 
See PMIREQUEST_GETBANK.
 
Before the [SETBANK] section in the .PMI file is executed, r0 is set to ulBank. in the [[#BANKDATA]] data structure. The current bank is set to ulBank in the BANKDATA data structure by executing the [SETBANK] section.
 
=== PMIREQUEST_SETCLUT ===
Description:
 
''PMIREQUEST_SETCLUT''sets Color Lookup Table to supplied values.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SETCLUT. */
PVOID            pIn;        /*  Pointer to a CLUTDATA data structure. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
====Parameters====
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure .
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_SETCLUT.
 
'''pIn'''(PVOID) - input Pointer to a [[#CLUTDATA]] data structure.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
 
====Remarks ====
See [[#PMIREQUEST_GETCLUT]].
 
=== PMIREQUEST_SETFONT ===
Description:
 
''PMIREQUEST_SETFONT''sets font to that supplied.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SETFONT. */
PVOID            pIn;        /*  Pointer to a FONTDATA data structure. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_SETFONT - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure .
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_SETFONT.
 
'''pIn'''(PVOID) - input Pointer to a [[FONTDATA]] data structure.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_SETFONT - Remarks ===
 
See PMIREQUEST_GETFONT.
 
=== PMIREQUEST_SETMEMORYIOADDRESS ===
Description:
 
''PMIREQUEST_SETMEMORYIOADDRESS''sets the linear aperture to the passed address.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SETMEMORYIOADDRESS. */
PVOID            pIn;        /*  Pointer to the address to be set. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_SETMEMORYIOADDRESS - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]]data structure .
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_SETMEMORYIOADDRESS.
 
'''pIn'''(PVOID) - input Pointer to the address to be set.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_SETMEMORYIOADDRESS - Remarks ===
This function executes the [SetMemoryIOAddress] section in the PMI file with r0 set to the passes address.
 
This function is also called implicitly when the [[#PMIREQUEST_SETMODE]] is called with the SET_LINEAR_BUFFER_MODE flag set to on. In this case, the address is set to pAdapter->ModeInfo.ulBufferAddress.
 
=== PMIREQUEST_SETMODE ===
Description:
 
''PMIREQUEST_SETMODE''sets requested video mode through the passed mode ID.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SETMODE. */
PVOID            pIn;        /*  Pointer to mode ID from the VIDEOMODEINFO data structure. */
PVOID            pOut;        /*  Pointer to the SetMode hardware command list. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_SETMODE - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_SETMODE.
 
'''pIn'''(PVOID) - input Pointer to mode ID from the [[#VIDEOMODEINFO]] data structure.
 
'''pOut'''(PVOID) - output Pointer to the SetMode hardware command list.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_SETMODE - Remarks ===
If ''pOut''is not NULL, the Set Mode hardware command list is copied. It will be used in saving and restoring a session. The size of the memory to which ''pOut''points is the maximum size of the hardware command list, which is obtained by the PMIREQUEST_QUERYMAXMODELISTSIZE function.
 
The caller has to set pAdapter->ModeInfo structure. If linear aperture mode is set, the mode ID should be ORed with SET_LINEAR_BUFFER_MODE. [[#PMIREQUEST_SETMEMORYIOADDRESS]] will be called implicitly with pAdapter->ModeInfo. ulBufferAddress as the input parameter used to set the linear aperture.
 
=== PMIREQUEST_SETPALETTE ===
Description:
 
''PMIREQUEST_SETPALETTE''sets palette registers to supplied values.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SETPALETTE. */
PVOID            pIn;        /*  Pointer to a PALETTEDATA data structure. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_SETPALETTE - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_SETPALETTE.
 
'''pIn'''(PVOID) - input Pointer to a [[#PALETTEDATA]] data structure.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_SETPALETTE - Remarks ===
 
See PMIREQUEST_GETPALETTE.
 
=== PMIREQUEST_SOFTWAREINT ===
====Syntax====
Description:
 
''PMIREQUEST_SOFTWAREINT''initializes and/or executes a real-mode software interrupt.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Can be NULL. If not NULL, the adapter must have been loaded. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_SOFTWAREINT. */
PVOID            pIn;        /*  Pointer to an INITVDM data structure. */
PVOID            pOut;        /*  Pointer to an INTCRF data structure. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_SOFTWAREINT - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Can be NULL. If not NULL, the adapter must have been loaded.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_SOFTWAREINT.
 
'''pIn'''(PVOID) - input Pointer to an [[#INITVDM]] data structure.
 
INITVDM defines how the worker routine will be initialized; can be NULL.
 
'''pOut'''(PVOID) - output Pointer to an [[#INTCRF]] data structure.
 
INTCRF includes client stack frame and an input/output buffer.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Possible values follow:
 
NO_ERROR
 
ERROR_INADEQUATE_VDM_SUPPORT Make sure vprpmi.sys is installed.
 
ERROR_FULLVDM_CREATION_NOT_SHELLPROCESS See Attention: LIMITATION, listed under 1.a. in the "Remarks" section of this functional description.
 
ERROR_MINIVDM_PROCESSUPPORT_ONLY Make sure vprpmi.sys. is installed. Because mini-VDM is available, subsequent requests may be successful.
 
=== PMIREQUEST_SOFTWAREINT - Remarks ===
 
This API allows for real-mode BIOS calls that need up to 4 KB in one or two input or output buffers. Although the service is generic, only VIDEO BIOS has been tested.
 
There are two types of worker VDM processes, depending on the requested VDM initialization as well as on the level of VDM support installed on the target machine, as follows:
 
1.Full VDM.
 
This process is equivalent to a full-screen DOS session that is created via an icon, stripped of its OS/2 components. The session has unrestricted video access. The session's DOS settings are manipulated by the VIDEOPMI and, therefore, are not affected by any standard settings or modifications to any of the DOS icons. The session can never be given foreground focus and is terminated only after its parent process terminates. If that should occur, there are no limitations on creating a new worker process. However, because the shell is the parent process, the event is unlikely. The session is completely hidden, as it is created without the knowledge of the session manager.
 
'''Note:'''When the int 10 full VDM session is started, the system will attempt to execute a videopmi.bat file. If the system does not find a videopmi.bat file in the root directory, it will default to autoexec.bat.
 
Because users often customize the autoexec.bat file, the autoexec.bat is unreliable or unusable in the int 10 full VDM session. To be sure the system has full control of the run-time environment of that session, make sure a videopmi.bat file exists in the system root directory.
 
'''Attention: LIMITATION'''
 
a.The full-VDM process can be created only under the shell process. VIDEOPMI ensures that the creation is limited to this window. A kernel patch is needed to cover any situations in which this may not be acceptable , for example, running a custom shell or testing the base video without a shell.
 
b.Full VDM requires that DOS support be installed on the target machine. As a result, a vendor driver using the software interface must ensure that this information is relayed to the customer. If, for any reason, DOS support is not desirable, full VDM is not the appropriate software interrupt solution and the Mini-VDM process described below should be used.
 
To ensure that a full-VDM process is created, the caller that initializes the VDM environment must specify the ''pIn''parameter. Specifying the pIn-> ulFlags = VDM_INITIALIZE is sufficient. Optional application name and parameters may be specified as well. When initializing, if VDM creation fails, one of the following errors is returned:
 
ERROR_INADEQUATE_VDM_SUPPORT Make sure vprpmi.sys is installed.
 
ERROR_FULLVDM_CREATION_NOT_SHELLPROCESS The limitation listed under 1.a. ( above) applies.
 
ERROR_MINIVDM_PROCESSUPPORT_ONLY Make sure vprpmi.sys is installed. Mini- VDM is available, so subsequent requests may be successful.
 
2.Mini VDM
 
This type of VDM process is provided for customer situations in which installing DOS support or running a full-VDM process is unacceptable. A mini-VDM process is a minimal v86 process for which ROM BIOS, BIOS data area, and video aperture are mapped in. All of the same calling interfaces and buffer passing capabilities of the full VDM apply. The worker VDM is created by the kernel as a child of the root process and, as such, is indestructable. If the video subsystem that created the process is unloaded and reloaded, the same VDM process is used.
 
'''Attention: LIMITATION'''
 
a.Virtualization of hardware resources and the exception management of mini-VDM are virtually nonexistent. All of the I/O resources are mapped physical, so any I/O that is executed goes to the hardware. None of the hardware interrupts are reflected; for example, timer ticks are not reflected in the BIOS data area. All of the ROM areas are mapped physical, so any self-modifying BIOS (those that are not in true ROM, of course) will affect subsequently started VDMs. The BIOS data area is the only page that is mapped linear, which means that it can be garbled without any danger to other VDMs running in the system.
 
There is no exception management. As a result, any of the unmapped memory ( from 4 KB up to 0x9FFFF) or above 1 MB that is touched will cause a kernel exception to occur (no recovery). Neither virtual drivers nor the DOS kernel is loaded in this process, so no TSRs or utilities can be executed.
 
b.This solution requires a kernel patch for OS/2 Warp, Version 3.x customers, and a kernel patch and DOSCALLS.DLL upgrade for OS/2 2.x customers, in addition to the base video files.
 
=== PMIREQUEST_TUNEDISPLAY ===
Description:
 
''PMIREQUEST_TUNEDISPLAY''executes the [TuneDisplay] section in the .PMI file.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_TUNEDISPLAY. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_TUNEDISPLAY - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_TUNEDISPLAY.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_TUNEDISPLAY - Remarks ===
 
None.
 
=== PMIREQUEST_UNLOCKREGISTERS ===
 
Description:
 
''PMIREQUEST_UNLOCKREGISTERS''unlocks extended registers.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_UNLOCKREGISTERS. */
PVOID            pIn;        /*  NULL. */
PVOID            pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_UNLOCKREGISTERS - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]] data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_UNLOCKREGISTERS.
 
'''pIn'''(PVOID) - input NULL.
 
'''pOut'''(PVOID) - output NULL.
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
 
=== PMIREQUEST_UNLOCKREGISTERS - Remarks ===
The [UNLOCK] section in the .PMI file will be executed.
 
=== PMIREQUEST_UNLOADPMIFILE ===
Description:
 
''PMIREQUEST_UNLOADPMIFILE''unloads the specified .PMI file. A .PMI file needs to be unloaded the same number of times it is loaded before all of its resources are freed. A .PMI file is loaded per driver-not per process. For example, a display driver, base video handler, and video configurator may all load the same .PMI file, which constitutes three users of the PMI subsystem. Before the PMI subsystem can be unloaded, PMIREQUEST_ UNLOADPMIFILE must be invoked three times before the file is unloaded.
 
<pre>#include <svgadefs.h>
 
PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG            ulFunction;  /*  Set equal to PMIREQUEST_UNLOADFILE. */
PVOID            pIn;        /*  Pointer to the ASCII string of the .PMI file. */
PVOID            pOut;        /*  NULL */
APIRET            rc;          /*  Return codes. */
 
rc = VIDEOPMI32Request(pAdapter, ulFunction,
      pIn, pOut);</pre>
 
=== PMIREQUEST_UNLOADPMIFILE - Parameters ===
 
'''pAdapter'''(PVIDEO_ADAPTER) - input Pointer to a [[#VIDEO_ADAPTER]]data structure.
 
'''ulFunction'''(ULONG) - input Set equal to PMIREQUEST_UNLOADFILE.
 
'''pIn'''(PVOID) - input Pointer to the ASCII string of the .PMI file.
 
'''pOut'''(PVOID) - output NULL
 
'''rc'''([[APIRET]]) - returns Return codes.
 
Values are as follows:
 
NO_ERROR Successful completion
 
ERROR_ADAPTER_NOT_SUPPORTED The PMI file wasn't loaded.
 
=== PMIREQUEST_UNLOADPMIFILE - Remarks ===
The .PMI file can be a flat .PMI file or a .DLL shared library.
 
=== Code Sample ===
The following code sample shows how to load the .PMI file, set up the mode table, and set the graphics mode.
<pre>
#include <os2.h>
#include <svgadefs.h>
 
#define DLLNAME                "videopmi"
#define REQUEST_ENTRYPOINT      "VIDEOPMI32Request"
#define FAIL_LENGTH            256
#define PMIFILE                "svgadata.pmi"
/*
* Adapter instance.
*/
VIDEO_ADAPTER AdapterInstance;
 
/*
* Entry point to videopmi
*/
PFNVIDEOPMIREQUEST pfnPMIRequest;
 
/*
* mode table. It is an array of VIDEOMODEINFOs.
*/
 
PVIDEOMODEINFO ModeTable;
 
ULONG ulTotalModes;
 
/************************************************************
* Load the .PMI file, get the hardware information about the
* adapter and the entry point to videopmi.
*
* Returns 0 if successful; DOS error token, otherwise.
************************************************************/
 
APIRET LoadPMIService (VOID)
{
  APIRET        rc;
  char          sFail[FAIL_LENGTH] = {0};
  HMODULE      hmodVIDEOPMI;
 
/************************************************************
* Load videopmi.dll
************************************************************/
 
  if (!(rc = DosLoadModule (sFail, FAIL_LENGTH, DLLNAME,
                            &hmodVIDEOPMI)))
 
  {
 
/************************************************************
* Get PMIREQUEST entry point
************************************************************/
 
      if (!(rc = DosQueryProcAddr (hmodVIDEOPMI,
                                  0,
                                  REQUEST_ENTRYPOINT,
                                  &pfnPMIRequest)))
 
        /*
          * Load PMI file.
          * If PMI file is successfully loaded,
          * adapter in AdapterInstance will be filled with the
          * information in .PMI file.
          *
          * Remember to set up the size information for ADAPTERINFO
          * and VIDEOMODEINFO.
          */
 
          AdapterInstance.AdapterInfo_cb    = sizeof (ADAPTERINFO);
          AdapterInstance.VideoModeInfo_cb  = sizeof (VIDEOMODEINFO);
 
        rc = pfnPMIRequest (&AdapterInstance,
                            PMIREQUEST_LOADPMIFILE,
                            PMIFILE,
                            NULL);
 
      if (rc)
 
        DosFreeModule (hmodVIDEOPMI);
 
  }
 
  return rc;
 
}
 
/************************************************************
*
* This function sets up the mode table.
*
* Copy the mode table from videopmi. It is an arrary of modes.
* All the information in [ModeInfo] and
* [MonitorModeInfo], if any, is included.
*
* Returns 0 if successful; DOS error token, otherwise.
************************************************************/
 
APIRET SetUpModeTable (VOID)
{
  APIRET        rc;
  /*
    * Get the total number of modes
    */
  if (!(rc = pfnPMIRequest (&AdapterInstance,
                            PMIREQUEST_QUERYMAXMODEENTRIES,
                            NULL,
                            &ulTotalModes)))
 
      /*
      * Allocate memory for mode table
      */
 
      if (!(rc = DosAllocSharedMem ((PPVOID)&ModeTable,
                                    NULL,
                                    ulTotalModes *
                                    sizeof (VIDEOMODEINFO),
                                    OBJ_GETTABLE | PAG_COMMIT |
                                    PAG_WRITE)))
 
        /*
          * Copy mode table.
          * Please check svgadefs.h for the fields in VIDEOMODEINFO.
          */
 
        rc = pfnPMIRequest (&AdapterInstance,
                            PMIREQUEST_QUERYMODEINFODATA,
                            NULL,
                            ModeTable);
 
  return rc;
}
 
/************************************************************
*
* This function sets the graphic mode.
*
* You can select the mode based on any information in the VIDEOMODEINFO
* structure. The following is only an example to set the graphics mode
* based on resolution and refresh rate.
* PM driver should not call videopmi to set the mode directly.
* It should call BVH to set the mode as before, such that
* the mode can be set based on the current monitor capability
* handled by BVH.
*
* Returns 0 if successful; DOS error token, otherwise.
************************************************************/
 
APIRET SETSVGAMODE (ULONG    ulHorRes,
                    ULONG    ulVerRes,
                    ULONG    ulColors,
                    ULONG    ulVerRefr,
                    PULONG    pulModeInd,
                    PCLUTDATA pCLUTData)
 
{
    APIRET rc=0xFFFF;
    ULONG  i;
 
    /* Search mode */
    if (ulVerRefr >= 0xFFL)  /* pick the first mode of the resolution */
    {
      for(i=0; i < ulTotalModes; i++)
        if ((ModeTable[i].usXResolution == (USHORT) ulHorRes) &&
            (ModeTable[i].usYResolution == (USHORT) ulVerRes) &&
            (ModeTable[i].bBitsPerPixel  == (BYTE) ulColors))
            *pulModeInd = i;
  }
  else    /* verify all including the refresh parameter */
  {
      for(i=0; i < ulTotalModes; i++)
        if ((ModeTable[i].usXResolution == (USHORT )ulHorRes) &&
            (ModeTable[i].usYResolution == (USHORT) ulVerRes) &&
            (ModeTable[i].bBitsPerPixel  == (BYTE) ulColors) &&
            ((ModeTable[i].bVrtRefresh  == 0xFF) ||
              (ModeTable[i]bVrtRefresh  == (BYTE) ulVerRefr)))
            *pulModeInd= i;
  }
  if (i == ulTotalModes)
      return rc;              /* mode not found */
 
  /* Unlock first */
  /*
    * Copy VIDEOMODEINFO of the selected mode to AdapterInstance.
    * Depending on the .PMI file, this information may be needed.
    */
  AdapterInstance.ModeInfo = ModeTable[*pulModeInd];
  /*
    * Call videopmi to set the mode.
    */
  rc = pfnPMIRequest (&AdapterInstance,
                      PMIREQUEST_SETMODE,
                      &ModeTable[*pulModeInd].miModeId,
                      NULL);
 
  if (rc)
      return rc;
  else
      /* Load Color Lookup Table */
      if (ModeTable[*pulModeInd].bBitsPerPixel <= 8)
        rc = pfnPMIRequest (&AdapterInstance,
                            PMIREQUEST_SETCLUT,
                            pCLUTData,
                            NULL);
 
  return rc;
}</pre>
 
== VIDEO Protect-Mode Interface ==
This chapter describes the VIDEO Protect-Mode-Interface (VIDEOPMI) in OS/2 Warp. This interface is an extension of the [[#VESA SVPMI]] standard.
 
The VIDEOPMI interface also provides parameters for the adapter virtualization in multiple DOS sessions and a number of support functions. The adapter description is provided as a flat file with an extension of .PMI. The main goal of the VIDEOPMI interface is to centralize all of the SetMode-related services and provide a consistent interface that is not dependent on availability of BIOS service or OEM utilities.
 
The following list includes the topics covered in this chapter:
*[[#.PMI file]]
*[[#Limitations of the PMI]]
*[[#Code vs. PMI]]
*[[#How to Customize the PMI Subsystem for Your Device]]
*[[#Supported Modes]]
*[[#Monitor Timings Support]]
*[[#Save and Restore State]]
*[[#Adapter Configuration]]
*[[#PMI Language Elements]]
*[[#PMI Sections]]
 
=== Overview ===
The VIDEOPMI interface is procedurally represented by the exported functions of its main handler-VIDEOPMI.DLL. This handler provides both 32- bit and 16-bit entry points for setting a video mode, loading fonts, and saving and restoring the video state. The handler provides a mode query function and a software interrupt function, which allows for execution of real-mode software interrupts, such as VIDEO BIOS, from the protect mode.
 
VIDEOPMI.DLL imports the device-specific function from the underlying vendor- or IBM-provided PMI subsystem. This subsystem is comprised of any of the following:
 
1.Flat .PMI file with no code imports.
 
Although VIDEOPMI does not mandate the .PMI file name, at the moment SVGA Install and Configuration mandates \OS2\SVGADATA.PMI. Example: Any OS/2 2.x .PMI file.
 
2.Flat .PMI file with imported code sections from a dynamic link library ( DLL).
 
This is called a '''HYBRID'''.PMI file. Imported functions are private to the PMI subsystem and conform to the IMPORTPMI prototype as described in the SVGADEFS.H header file. Example: Any OS/2 3.x .PMI file.
 
3.Flat .PMI file with imported code sections from a DLL that chains into VIDEOPMI.
 
This is called a '''META-HYBRID'''.PMI file. The shared library exports a "LoadAdapter" function, which signals to VIDEOPMI that the handler wishes to engage in chaining VIDEOPMI's calls. The handler is passed the VIDEOPMI's calling function table and can modify the table by replacing entries with its own entry points. When these entry points are invoked, the handler can implement the call or pass it back to VIDEOPMI. Example: A .PMI file generated by SVGAOEM.EXE in the DDK.
 
4.META handler alone, without a flat file.
 
When VIDEOPMI's PMIREQUEST_LOADPMIFILE is passed a .DLL name and the specified shared library exports and successfully handles the "LoadAdapter" call, the PMI subsystem requires no flat file. This method of customizing the PMI subsystem is not in use because SVGA install, video configuration, and the virtual driver still make assumptions and use the flat .PMI file. Example: OEMPMI.DLL in the DDK.
 
For a full description of VIDEOPMI's procedural interface, see [[#VIDEOPMI.DLL Exported Functions]].
 
=== .PMI file ===
The VIDEOPMI interface is driven by the sections of the .PMI file. There are two main types of sections:
*Query sections that describe adapter capabilities
*Set sections that service hardware programming requests
 
Query sections provide information on hardware description, list of ports, list of supported modes, and the range or set of supported timing values. The Set sections provide the capability to identify adapters; unlock registers; cleanup, size, and position the active display; set a mode; save and restore a mode, and the VRAM used by the mode.
 
The VIDEOPMI language defines a video adapter as a hardware controller in terms of its I/O and memory addresses that are programmable by the CPU. The video controller can be a dumb frame VGA/SVGA, an accelerator, or a general -purpose coprocessor. The .PMI file must contain all of the informational sections and a minimal set of Set sections (see [[#PMI Sections]]). An adapter description starts with its Hardware section, followed by IdentifyAdapter, a number of support sections, and a list of all available modes with the corresponding SetMode sections.
 
The PMI facilitates dynamic hardware configuration, which includes port remapping as well as adding or removing an adapter and its PMI definition. It also includes changing the attached display and multiple instances of the same video hardware driven by the same .PMI. The interface defines monitor timing variables needed to drive a CRT monitor. These variables provide extensive monitor support and a consistent user configuration interface. The PMI language also facilitates programming of the support chips that can be mapped into the I/O and memory space addressable by the CPU, such as external clock-synchronizing chips or smart Digital-to-Analog Converters (DACs).
 
.PMI files are to be provided by the video chip or adapter manufacturers or by the providers of the display drivers. The file should be part of the video adapter installation kit, either as a pre-manufactured flat file or one created by the OEM's installation utility.
 
=== Limitations of the PMI ===
The following limitations exist in the PMI:
*PMI does not provide a graphical interface.
*PMI does not provide a means of accessing addresses that are internal to the video controller and are not mappable into the CPU space.
*Save and Restore Hardware State Services have certain limitations (see "Save and Restore State" in this chapter).
*PMI does not provide the means to manipulate certain video parameters outside the context of the SetMode section.
 
PMI does allow, and it requires, indirect management of all of the parameters within the Mode Set sections. For example, there are no services for the manipulation of the hardware cursor or RAMDAC outside the context of a mode set. These services are an integral part of the SetMode.
 
Programming of the monitor timing is considered a special case. It is an integral part of the SetMode, but it also can be independently invoked, if the .PMI file defines a SetMonitorTimings section. The same is true for manipulation of the active display size. If the PMI file contains a TuneDisplay section, this manipulation is offered independently.
 
*Port descriptions have some limitations, as follows:
**Ports that require double or triple indirection cannot be adequately described in the PMI language.
**I/O addresses that serve as latches, or flip-flops, cannot be successfully described.
**There are no provisions for describing port addresses that define different registers depending on the read or write access.
 
These limitations have an influence on the level and success of the adapter virtualization using the system-provided virtual driver. See [TrapRegs] in [[#PMI Sections]].
 
=== Code vs. PMI ===
The Set type of sections can be implemented as pure PMI language constructs, as pure imported functions from an external binary object or as a mixture of the two. Each implementation has its benefits and its drawbacks. The vendor creating the PMI file should carefully evaluate which method is the most appropriate and beneficial.
 
=== PMI Language Constructs only ===
Full use of the PMI language hides the implementation of the I/O and MMIO access on a particular hardware and operating system platform from the vendor creating the PMI file. This method provides good portability and code reuse. The initial cost in creating the SVGADATA.PMI file is mainly in rewriting the existing source into the PMI sequences.
 
Another benefit of this implementation is tighter execution control. Since the VIDEOPMI would be totally data-driven, the chances for memory violations and other execution hazards are minimized.
 
This implementation should not be used for timing-sensitive hardware, since the interpretation of PMI sequences creates an execution overhead that cannot be fine-tuned at the current time.
 
'''Note:'''SVGADATA.PMI files created internally by IBM are written either in full PMI language or in a mixture of PMI language and imported functions to cover as many chip sets as possible.
 
=== Imported Functions only ===
This implementation provides the greatest code reuse of the source objects already created and used elsewhere by the vendors. It also provides the performance needed in programming the timing-sensitive chip sets. Importing code also allows the vendor to call VIDEO BIOS as as means of implementing the exported function. This can be achieved only from a shared library. A flat .PMI file will not call VIDEOPMI's entry point. Provided that the shared library exports the "Load Adapter" API and conforms to the META-PMI definition, this method also allows for modifying VIDEOPMI's function by chaining into its calling table.
 
The drawback to this method is that the imported objects' source code is developed for a specific hardware and operating system platform and has to be ported to a new platform. Another drawback is that the imported binary object may introduce execution violations unless it is thoroughly tested.
 
=== PMI Language Constructs + Imported Functions ===
 
This method represents a compromise between the two implementations discussed previously.
 
The method is applicable for vendors who require code reuse with small maintenance effort, but have performance-sensitive chip sets on board. Another example would be chip vendors who are handling a number of different adapter implementations with a single PMI file. Such PMI files could have common PMI sequence-based SetMode, UnLock and Cleanup functions, but adapter-specific functions, such as DAC and clock-chip programming, could be imported from an external binary object. Porting mixed PMI files to another operating system platform requires porting of the source code only.
 
External binary objects are 32-bit dynamic libraries, which have to provide instance initialization and export all of the functions that are referenced in the .PMI file. See [[#Include Files]] in [[#PMI Language Elements]] and [[#PMI Sections]] for more detail.
 
'''Note:'''The imported library (OEMPMI.DLL) that is shipped with the ''IBM Developer Connection Device Driver Kit for OS/2''illustrates the importing functions.
 
=== Sample .PMI File Using Imported PMI Binary Object ===
This section diagrams a sample .PMI file. The sample file is shipped by a chip-set vendor and supports a number of adapter implementations of the vendor's chip set. All of the adapter-specific functions are handled by the imported PMI functions from the VENDOR.DLL dynamic link library. The adapter-specific [Hardware] section, which provides the description for the specific implementation identified on the user's machine, is provided in the VENDOR.PMI Include file.
 
Thus, by copying different Include files, together with the master SVGADATA .PMI and VENDOR.DLL files, specific adapter installation is covered with minimum investment in a utility for formatting the .PMI file.
 
The generic PMI file lists all of the modes possible, with the maximum memory configuration for the chip. It also lists reasonable timing limits per mode that should be supported by all adapters. This information provides the filtering service to the configuration utility, which presents the timing choices to the user. Should a particular adapter's capabilities be lower than the timing values set, the SetMonitorTimings function should perform verification of the input parameters in order to protect the hardware. If the adapter's capabilities vary greatly, the PMI file should be formatted to reflect the correct MonitorModeInfo for the adapter.
<pre>
/*
** Vendor include PMI file VENDOR.PMI
*/
BusType            = ADAPTER_BUS_TYPE
OEMString          = "CHIPSET_NAME ADAPTER_NAME, ADAPTER_MANUFACTURER_NAME"
DACString          = "DAC_MANUFACTURER_NAME, DAC_NAME"
Version            = "3.2"
TotalMemory        = ACTUAL_VRAM_MEMORY_SIZE
MemoryIOAddress    = MMIO_ADDRESS
PortIOAddress      = PIO_ADDRESS
Endian              = LITTLE
</pre>
 
<pre>
/*
** Generic PMI file
*/
[PMIVersion]        2.2
#includecode        "vendor.DLL"  //exports all fnPMI entry points used
in this PMI file
#include            "vendor.pmi"
 
/*
*        List of declared ports. Required if adapter is dynamically
*        configurable
*/
[Declarations]
MRegisterA =MMIO{0x00180298}
...
/*
*    List of I/O and MMIO ports to be trapped
*/
 
[TrapRegs]
DWORD_MMIOPORT RW ACCEL MRegisterA;
...
 
[EnableController]
call fnPMIEnableController;
 
[DisableController]
call fnPMIDisableController;
 
[UnLock]
call fnPMIUnlock;
 
[Cleanup]
call fnPMICleanup;
 
[GetBank]
call fnPMIGetBank;
 
[SetBank]
call fnPMISetBank;
 
[SetMonitorTimings]
call fnPMIProgramTimings;
 
[TuneDisplay]
call fnPMITuneDisplay;
 
[comment]
Graphics Mode: 640 x 480 x 16 colors.
[ModeInfo]
ModeAttributes      = 0x18
BytesPerScanLine    = 640
XResolution        = 640
YResolution        = 480
TextRows            = 30
BitsPerPixel        = 4
NumberOfPlanes      = 4
PageLength          = 38400
SaveSize            = 153600
Int10ModeSet        = 0x012
BufferAddress      = 0x000a0000
ApertureSize        = 0x00010000
[MonitorModeInfo]
VerticalRefresh    = 72
HorizontalRefresh  = 38
ScreenLeftEdge      = 0x00000021
ScreenRightEdge    = 0x000000C1
ScreenTopEdge      = 0x00000019
ScreenBottomEdge      =  0x000001F9
 
[ comment ]
Graphics  Mode :  640  x  480  x  256  colors .
[ ModeInfo ]
ModeAttributes        =  0x18
BytesPerScanLine      =  640
XResolution          =  640
YResolution          =  480
TextRows              =  30
BitsPerPixel          =  8
NumberOfPlanes        =  1
PageLength            =  307200
SaveSize              =  307200
BufferAddress        =  LinearWindowAddress
ApertureSize          =  0x00200000
[ MonitorModeInfo ]
VerticalRefresh      =  72
HorizontalRefresh    =  38
ScreenLeftEdge        =  0x00000021
ScreenRightEdge      =  0x000000C1
ScreenTopEdge        =  0x00000019
ScreenBottomEdge      =  0x000001F9
 
[ comment ]
Graphics  Mode :  640  x  480  x  64K  colors .
[ ModeInfo ]
ModeAttributes        =  0x18
BytesPerScanLine      =  1280
XResolution          =  640
YResolution          =  480
TextRows              =  30
BitsPerPixel          =  16
NumberOfPlanes        =  1
PageLength            =  614400
SaveSize              =  614400
ColorFormat          =  " RGB "
ColorWeight          =  " 5 : 6 : 5 "
BufferAddress        =  LinearWindowAddress
ApertureSize          =  0x00200000
[ MonitorModeInfo ]
VerticalRefresh      =  72
HorizontalRefresh    =  38
ScreenLeftEdge        =  0x00000021
ScreenRightEdge      =  0x000000C1
ScreenTopEdge        =  0x00000019
ScreenBottomEdge      =  0x000001F9
 
[ comment ]
Graphics  Mode :  800  x  600  x  256  colors .
[ ModeInfo ]
ModeAttributes        =  0x18
BytesPerScanLine      =  800
XResolution          =  800
YResolution          =  600
TextRows              =  37
BitsPerPixel          =  8
NumberOfPlanes        =  1
PageLength            =  480000
SaveSize              =  480000
BufferAddress        =  LinearWindowAddress
ApertureSize          =  0x00200000
[ MonitorModeInfo ]
VerticalRefresh      =  72
HorizontalRefresh    =  48
ScreenLeftEdge        =  0x0000002B
ScreenRightEdge      =  0x000000F3
ScreenTopEdge        =  0x0000001D
ScreenBottomEdge      =  0x00000275
 
[ comment ]
Graphics  Mode :  1024  x  768  x  256  colors .
[ ModeInfo ]
ModeAttributes        =  0x18
BytesPerScanLine      =  1024
XResolution          =  1024
YResolution          =  768
TextRows              =  48
BitsPerPixel          =  8
NumberOfPlanes        =  1
PageLength            =  786432
SaveSize              =  786432
BufferAddress        =  LinearWindowAddress
ApertureSize          =  0x00200000
[ MonitorModeInfo ]
VerticalRefresh      =  72
HorizontalRefresh    =  58
ScreenLeftEdge        =  0x00000041
ScreenRightEdge      =  0x00000141
ScreenTopEdge        =  0x00000021
ScreenBottomEdge      =  0x00000321
 
[ SetMode ]
call fnPMISetMode;
[ comment ]
Text Mode:  80 cols, 25 rows.
[ ModeInfo ]
ModeAttributes        =  0x08
BytesPerScanLine      =  80
XResolution          =  720
YResolution          =  400
XCharSize              =  9
YCharSize              =  16
TextRows              =  25
BitsPerPixel          =  4
NumberOfPlanes        =  1
PageLength            =  4000
SaveSize              =  4000
Int10ModeSet          =  0x003
VerticalRefresh      =  60
BufferAddress        =  0x000b8000
ApertureSize          =  0x00008000
 
[ SetMode ]
call  fnPMISetTextMode ; </pre>
 
 
=== How to Customize the PMI Subsystem for Your Device ===
The VIDEO PMI subsystem consists of VIDEOPMI-the main PMI handler, a flat PMI file, and optional imported library modules. The imported library modules may optionally chain into VIDEOPMI and provide a filter or replacement for VIDEOPMI's entry points. Such a library is called a META- PMI handler. Although the VIDEO PMI subsystem places no requirements on the existence of a flat PMI file (it is possible to provide all functions with a META-PMI handler alone), the SVGA installation, SVGA virtual video driver , BVHSVGA, and VIDEOCFG all make assumptions that the PMI subsystem is represented by SVGADATA.PMI.
 
The VIDEOPMI handler is maintained by IBM; it is shipped in the IBM Developer Connection Device Driver Kit for OS/2 as a binary file. See Video Subsystem Binary Files. The SVGADATA.PMI file is either provided or can be created at install time by running a utility. The SVGA installation action routine DLL (SVGA.DLL) assumes that a DOS utility called SVGA.EXE is used to generate the SVGADATA.PMI. A vendor wishing to modify the SVGADATA.PMI can provide its own action routine DLL or create the SVGA.EXE DOS utility. DDK sources include two different sources of a utility that generates the SVGADATA.PMI file, as follows:
src\svdh\svgautil\svga.exe
 
src\svdh\svgautil sources are those of the SVGA.EXE as shipped by IBM. It is a very large and complex source that generates a .PMI file for all of the devices supported by the IBM BBS display driver packages at the time the IBM Developer Connection Device Driver Kit for OS/2 was shipped.
 
Vendors should not modify this source; it is shipped so that vendors can create sample .PMI files for legacy hardware. PMI files created by this utility use IBMGPMI.DLL as an imported PMI library. The source for IBMGPMI .DLL is not available for vendor modification, but a binary file can be extracted from the most current IBM BBS video driver package. An older version of IBMGPMI can be found in previous DDKs.
 
For purposes of documenting an imported PMI library, an alternate library source in src\oempmi for OEMPMI.DLL is provided. This PMI library exemplifies both internal PMI calls and the META-PMI interface (chaining into VIDEOPMI). It also provides an example of using the VIDEOPMI's software interrupt API to call the VIDEO BIOS directly.
src\oempmi\svgautil\svgaoem.exe
 
src\oempmi\svgautil sources are the recommended sources for vendor modification. The makefile will generate an SVGAOEM.EXE, which should be renamed to SVGA.EXE if the SVGA.DLL action routine DLL is to be used. The utility will create a generic SVGADATA.PMI file based solely on VESA mode support without any vendor modifications. This generic .PMI file depends on the OEMPMI.DLL META-PMI handler, referred to in the previous bullet, for successful VESA BIOS calls. If there is no VESA support for the adapter, or vendors wish to add refresh support or customize the generic sections, the SetupChipInfo function in SVGAOEM.C needs to be modified. The header of the SVGAOEM.C source file includes the "ROADMAP to CHANGES" instructions.
 
src\oempmi sources are open to vendor modification, and its headers also include extensive instructions on the recommended changes. However, for a vendor with VESA mode set support and a display driver that can run on top of the hardware state as left by the VESA mode set, the quickest results are obtained by doing the following:
 
-Install all of the Base Video Subsystem files.
 
-Create a .PMI file by running the unmodified SVGAOEM.EXE with command line argument "ON".
 
=== Supported Modes ===
This section lists the OS/2 Warp requirements for the modes included in a . PMI file. Each supported mode is represented by a set of sections, as follows:
*Comment (optional)
*ModeInfo (required)
*MonitorModeInfo (optional)
*SetMode (optional)
 
The ModeInfo section is a list of the common mode elements (PMI keyvariables) that define the resolution, window, and size elements of the mode. The mode definition is then complemented by all of the MonitorModeInfo sections following the ModeInfo section. There could be zero or more MonitorModeInfo sections, depending on the capabilities of the hardware to program timings. An adapter may not support a CRT in a particular mode; a single MonitorModeInfo section with zero values is used to indicate such a case. If the adapter can support only a distinct set of values, rather than a range of horizontal and vertical refresh values, multiple MonitorModeInfo sections per horizontal/vertical refresh pair are used to indicate this fact. An adapter with flexibility in programming a range of dotclock (which translates into horizontal and vertical refreshes) should list only one MonitorModeInfo entry with the end of range values for the vertical/horizontal refresh.
 
'''Suggested modes include the following:'''
*40x25 and 80x25 text
*At least one of the 132-column text modes (if applicable).
*At best, all of the supported 256-color modes with respective refresh rates (see [[#Monitor Timings Support]] in this chapter).
*:At the minimum, modes that are supported by the respective Presentation Manager display driver.
*:If the adapter in question has both accelerated and nonaccelerated modes, only the accelerated modes should be provided.
*At best, all of the supported hi-color and true-color modes with respective refresh rates (see [[#Monitor Timings Support]] in this chapter).
 
At the minimum, modes which are supported by the respective Presentation Manager display driver.
 
If the adapter in question has both accelerated and nonaccelerated modes, only the accelerated modes should be provided.
 
=== Monitor Timings Support ===
The PMI defines eight display-timing-related variables as mode keyvariables . These variables facilitate selection of the mode, depending on the current monitor specification and sizing of the active display for the current mode. The MonitorModeInfo section contains all of the timing- related PMI key variables.
 
The display-timing-related variables are:
 
VerticalRefresh Vertical refresh in Hz (rounded to the nearest integer)
 
HorizontalRefresh Horizontal refresh in KHz (rounded to the nearest integer )
 
HPolarityPositive Contains the Horizontal polarity (0,1) for the current mode selection
 
VPolarityPositive Contains the Vertical polarity (0,1) for the current mode selection
 
ScreenLeftEdge Represents the end of the horizontal blanking (HBP) in pixel count along the horizontal sweep (HSP)
 
ScreenRightEdge Represents the start of the horizontal blanking (HFP) in pixel count along the horizontal sweep (HSP)
 
ScreenTopEdge Represents the end of the vertical blanking (VBP) in line count along the vertical sweep (VSP)
 
ScreenBottomEdge Represents the start of the vertical blanking (VFP)
 
The last four timing elements, defining the start and end of the horizontal active display and start and end of the vertical active display, are suggested as mode elements in order to enhance visual quality. Their values are never directly communicated to the end user configuring the adapter, only the net results. The values are manipulated through a TuneDisplay function as part of the SetMode or upon the end user's configuration request. See [TuneDisplay] section in [[#PMI Sections]].
 
There is no interface for specification and manipulation of the widths of the Horizontal Sweep (HSP) and Vertical Sweep (VSP) signals.
 
If an adapter is capable of supporting both non-CRT- and CRT-style displays , modes of both types should be listed. Non-CRT Mode sections are those that have 0 for both horizontal and vertical refresh rate.
 
If the adapter has monitor sensing, identification, and auto-adjusting capability built in so that software manipulation of the timing-related registers is not required, none of the timing-related mode elements have to be specified. No MonitorModeInfo sections should be included and monitor sizing parameters and the TuneDisplay function should not be listed.
 
The vendor providing the .PMI file can supply either a single MonitorModeInfo, which denotes the upper limit for horizontal and vertical refresh, or a number of MonitorModeInfo sections with distinct sets of horizontal and vertical refresh values. In the first case, the OS/2 Warp configuration utility offers refresh values that are part of the current monitor definition for the desired resolution, as long as the monitor specification is within the range specified by the adapter. If more than one MonitorModeInfo section exists per mode, all of those within the monitor's specification are offered as a selection to the user by the OS/2 Warp Video Configuration Manager. Polarity PMI keyvariables are not required, unless an exact match with the monitor's capabilities is desired by the adapter vendor.
 
=== Save and Restore State ===
VIDEOPMI does not have dedicated SaveState or RestoreState sections. The VIDEOPMI engine does offer those services.
 
=== SaveRestore VRAM ===
VIDEOPMI offers saving and restoring of the video buffer of SaveSize for each mode and is internally aware of the type of VRAM access it has to perform. The parameters taken into consideration when addressing the VRAM are BufferAddress, ApertureSize, and SaveSize. See [ModeInfo] section in [[#PMI Sections]].
 
If ApertureSize is equal to or greater than SaveSize, direct linear access to the BufferAddress is assumed. If this is not the case, the SetBank function is necessary in order to save and restore the entire on-screen VRAM. Granularity of a bank is assumed to be the ApertureSize. SaveSize should be set to reflect the logical line length programmed by the current mode, rather than just horizontal resolution.
 
=== SaveRestore Hardware ===
This service is available for .PMI files that use the PMI language to define SetMode sections.
 
The PM driver performs its own Save and Restore of the state and is not dependent on the service. The bvhsvga.dll uses the Save and Restore State service to save and restore OS/2 full screen sessions; in case of a partial restore, bvhsvga.dll reissues the mode set and restores the important video attributes.
 
The SaveRestore Hardware service is based on the PMI sequence for the SetMode; all of the ports that are programmed by the SetMode section for the current mode will be saved and restored. When saving a mode, the VIDEOPMI interpreter parses the command list of the SetMode section.
 
BOUTB commands are converted into BINB commands. The VIDEOPMI executes the newly constructed section in order to capture register values and converts all of the commands back into their original SetMode format. The command list is then ready for a subsequent RestoreState call and is returned to the user.
 
This approach has some limitations, mainly for adapters that employ double and higher indirection levels in register addressing; for example, the WDc24.
 
=== Adapter Configuration ===
This portion of the chapter specifies the requirements placed on the .PMI file by the video subsystem. It does not address the physical installation steps for an adapter, or the bus management, device enumeration, and conflict management employed by the operating system.
 
An adapter is defined by its Hardware section, which lists the type of bus, the default start address of the I/O and memory space, and alternative addresses for the I/O and memory space, as addressable by the CPU. The adapter is uniquely defined by its OEMString and Version strings.
 
=== PMI Language Elements ===
The VIDEOPMI language consists of the following elements:
*Sections
*User-defined functions
*Expressions
*PMI commands, identifiers, constants, variables, string-literals, and comments
The language is not case-sensitive, so BOUTB and boutb represent the same identifier. Throughout this section, Backus-Naur Form (BNF) grammar is used to describe the syntax. Some examples are given in the text. Where such examples are omitted, sample .PMI files accompanying the document should be used as a reference.
 
=== Comments and Delimiters ===
Comments can be either in-line comments (//) or ANSI C style comments (/* */). White space is used as the token delimiter and a semicolon (;) is used as the expression delimiter.
 
The Comment section defines a mode-info related comment that describes the mode to the user. See [Comment] in [[#PMI Sections]].
 
=== Include Files ===
PMI allows for inclusion of other .PMI files, all of which must conform to the PMI language. The include files should be in the same directory as the current .PMI file. There can be more than one #include statement in a .PMI file. The include .PMI files can have #include statements to include other .PMI files. An Include file facility is provided in order to offer flexibility in supporting multiple adapter configurations with a single . PMI file. Failure to locate the include .PMI file does not cause the unloading of the SVGADATA.PMI file.
 
The external binary objects are included using a #includecode directive, and flat PMI sub-files are included using a #include directive. The include statement can be found anywhere in the .PMI file as long as it does not violate the integrity of the section before and the section after, and as long as the references to the objects belonging to the include file are made after the inclusion.
 
External binary objects are considered "binary include" files. The VIDEOPMI parser attempts to load the module as a 32-bit DLL and attempts to resolve the procedural addresses for every external code reference made using all of the loaded module. If the loading or address resolution fails, the loading of the .PMI file fails.
#include "filename" //PMI extension assumed
#includecode "filename" //DLL extension assumed
 
=== Constants, String-Literals, Identifiers, and Keywords ===
PMI constants are 32-bit integer constants, either in decimal or hexadecimal format.
<pre>
<digit>  ::= '0'..'9'
<hexdigit> ::= <digit>  |  'a'..'f'
<character> ::= 'a'..'z' |  'A'..  'Z'|  '_' |  '.'
<decimal number>  ::= <digit>  |  <decimal number> <digit>
<hexadecimal number>  ::= '0x' <hexdigit>  |
                        <hexadecimal number>  <hexdigit>
<constant>  ::= <decimal number>  |  <hexadecimal number></pre>
Any combination of printable ASCII characters in quotes is considered a string-literal. String-literals are not parsed in any way. They are stored in their uppercase format and are passed on query-style calls, converting both source and target to uppercase. String-literals are limited to 128 characters in length, including 0 at the end. Binary strings are also limited to 128 bits (4 doublewords).
 
<pre><string>  ::= "<ASCII character> [<string>]"
<binary-string>  ::= " <'0'|'1'> | <'0'|1'> [<binary-string>]"</pre>
An Identifier, or a name, is a sequence of letters and digits. The first character must be a letter. The underscore (_) and point (.) count as a letter, but point (.) cannot be used in the first position. Maximum length of an identifier is 32 characters.
 
<pre><name>  ::= <character>  <token>
<token>  ::= {<character>  |  [<digit> <token>]}</pre>
Reserved identifiers are called keywords. Keywords are divided into three groups:
*PMI keyvariables, which are keywords representing configuration and mode parameters
*PMI constants, backed by system-wide definitions
*All other reserved identifiers
 
All of the PMI keyvariables are available through the VIDEOPMI programming interface as fields of the video instance structure. They are also available to all of the PMI sections and functions and can be used in conditional statements or expressions. At run time, during a SetMode, some of the ModeInfo PMI keyvariables could differ from the values assigned by the .PMI file. These PMI keyvariables can be modified at the user or system level and are therefore regarded as '''''Dynamic'''''. Others are called '''''Static'''''. At the procedural level, static PMI keyvariables are fixed to the values specified in the .PMI file and cannot be changed for a given mode. Some dynamic variables have a limited set of possible values; others are valid in a range that should be verified by dedicated sections. See [ModeInfo], [ Hardware] and [TuneDisplay] in [[#PMI Sections]] for more information on dynamic vs. static keyvariables.
 
Not all of the PMI keyvariables have to be defined. See [ModeInfo] and [Hardware] in [[#PMI Sections]] for further explanations.
 
=== PMI Keyvariables ===
The following table lists all of the keyvariables for the Protect Mode Interface (PMI).
{|class="wikitable"
!Name||Section
|-
|ApertureSize||ModeInfo
|-
|BitsPerPixel||ModeInfo
|-
|BufferAddress||ModeInfo
|-
|BusType||Hardware
|-
|BytesPerScanLine||ModeInfo
|-
|ColorFormat||ModeInfo
|-
|ColorWeight||ModeInfo
|-
|DACString||Hardware
|-
|Endian||Hardware
|-
|HorizontalRefresh||MonitorModeInfo
|-
|HPolarityPositive||MonitorModeInfo
|-
|Int10ModeSet||ModeInfo
|-
|MemoryIOAddress||Hardware
|-
|ModeAttributes||ModeInfo
|-
|NumberOfPlanes||ModeInfo
|-
|OEMString||Hardware
|-
|PageLength||ModeInfo
|-
|PortIOAddress||Hardware
|-
|SaveSize||ModeInfo
|-
|ScreenLeftEdge||MonitorModeInfo
|-
|ScreenRightEdge||MonitorModeInfo
|-
|ScreenBottomEdge||MonitorModeInfo
|-
|ScreenTopEdge||MonitorModeInfo
|-
|SlotID||EnableController
|-
|TextRows||ModeInfo
|-
|TotalMemory||Hardware
|-
|VerticalRefresh||MonitorModeInfo
|-
|VPolarityPositive||MonitorModeInfo
|-
|XCharSize||ModeInfo
|-
|XResolution||ModeInfo
|-
|YCharSize||ModeInfo
|-
|YResolution||ModeInfo
|}
 
=== PMI Constants ===
The following table lists the constants used by the Protect Mode Interface (PMI).
<pre>
|Name                    |Section                |
|------------------------+------------------------|
|BIG                    |Hardware                |
|------------------------+------------------------|
|EISA                    |Hardware                |
|------------------------+------------------------|
|ISA                    |Hardware                |
|------------------------+------------------------|
|LITTLE                  |Hardware                |
|------------------------+------------------------|
|MCA                    |Hardware                |
|------------------------+------------------------|
|MMIO                    |Declarations            |
|------------------------+------------------------|
|PCI                    |Hardware                |
|------------------------+------------------------|
|PCMCIA**                |Hardware                |
|------------------------+------------------------|
|PIO                    |Declarations            |
|------------------------+------------------------|
|VLB                    |Hardware                |
</pre>
 
=== PMI Keywords ===
The following table lists the reserved identifiers, called Keywords, used by the Protect Mode Interface (PMI).
<pre>
|Name                          |Section                      |
|------------------------------+------------------------------|
|[Cleanup]                    |PMI sections                  |
|------------------------------+------------------------------|
|[Comment]                    |PMI sections                  |
|------------------------------+------------------------------|
|[Declarations]                |PMI sections                  |
|------------------------------+------------------------------|
|[GetBank]                    |PMI sections                  |
|------------------------------+------------------------------|
|[Hardware]                    |PMI sections                  |
|------------------------------+------------------------------|
|[IdentifyAdapter]            |PMI sections                  |
|------------------------------+------------------------------|
|[ModeInfo]                    |PMI sections                  |
|------------------------------+------------------------------|
|[MonitorModeInfo]            |PMI sections                  |
|------------------------------+------------------------------|
|[PMIVersion]                  |PMI sections                  |
|------------------------------+------------------------------|
|[SetBank]                    |PMI sections                  |
|------------------------------+------------------------------|
|[SetMode]                    |PMI sections                  |
|------------------------------+------------------------------|
|[SetMemoryIOAddress]          |PMI sections                  |
|------------------------------+------------------------------|
|[TrapRegs]                    |PMI sections                  |
|------------------------------+------------------------------|
|[TuneDisplay]                |PMI sections                  |
|------------------------------+------------------------------|
|[UnLock]                      |PMI sections                  |
|------------------------------+------------------------------|
|ABOUTDW                      |PMI commands                  |
|------------------------------+------------------------------|
|ABOUTW                        |PMI commands                  |
|------------------------------+------------------------------|
|BINB                          |PMI commands                  |
|------------------------------+------------------------------|
|BOUTB                        |PMI commands                  |
|------------------------------+------------------------------|
|ENDWHILE                      |PMI constructs                |
|------------------------------+------------------------------|
|GOTO                          |PMI constructs                |
|------------------------------+------------------------------|
|IF                            |PMI constructs                |
|------------------------------+------------------------------|
|INB                          |PMI commands                  |
|------------------------------+------------------------------|
|INDW                          |PMI commands                  |
|------------------------------+------------------------------|
|INW                          |PMI commands                  |
|------------------------------+------------------------------|
|MEMCMP                        |PMI constructs                |
|------------------------------+------------------------------|
|OUTB                          |PMI commands                  |
|------------------------------+------------------------------|
|OUTDW                        |PMI commands                  |
|------------------------------+------------------------------|
|OUTW                          |PMI commands                  |
|------------------------------+------------------------------|
|READB                        |PMI commands                  |
|------------------------------+------------------------------|
|READDW                        |PMI commands                  |
|------------------------------+------------------------------|
|READW                        |PMI commands                  |
|------------------------------+------------------------------|
|RMWB                          |PMI commands                  |
|------------------------------+------------------------------|
|RMWBI                        |PMI commands                  |
|------------------------------+------------------------------|
|RMWW                          |PMI commands                  |
|------------------------------+------------------------------|
|STRCMP                        |PMI constructs                |
|------------------------------+------------------------------|
|WHILE                        |PMI constructs                |
|------------------------------+------------------------------|
|WRITEB                        |PMI commands                  |
|------------------------------+------------------------------|
|WRITEDW                      |PMI commands                  |
|------------------------------+------------------------------|
|WRITEW                        |PMI commands                  |
</pre>
Variables are user-defined identifiers that symbolically represent a hardware register in terms of its offset, in either the CPU's I/O space or memory space. Use of variables is required for system architectures in which dynamic configuration and multiple instances of the same hardware are possible. A variable must be declared prior to being used. See [ Declarations] section in [[#PMI Sections]].
<pre><memory-mapped variable>  ::= <mmio variable>  =  'MMIO{'<number>'}'
<port-variable declaration>  ::= <pio variable>  = 'PIO{'<number>'}'
<mmio variable>  ::= <name>
<pio variable>  ::= <name></pre>
For example:
 
<pre>seq_address = PIO{0x3c4};
interrupt_en = MMIO{0x00000080}</pre>
Labels are user-defined identifiers that refer to code locations. The scope of a label is its containing function (or section). A label name within an adapter definition should be unique. The label must be declared prior to its reference.
 
<pre><label>  ::= <name>':'</pre>
 
=== Registers ===
Registers are internal local variables that are used to hold interim results and return or pass information. There are 256 32-bit noninitialized registers that are private to every VIDEOPMI caller. Registers should be assigned their values prior to being used. They can be used as a source in port OUT commands and memory WRITE commands or as a destination in the port IN commands and memory READ commands. Size of these operations is determined by the size of the PMI command. A set of 32-bit operations on registers is also defined in the syntax. When used in block I/O commands, the register index should be the same as that of the port index to which it corresponds. Register r0 is used as the return value register from functions that have a return value. Register r0 is also used to provide the bank number to the SetBank function.
 
Care should be taken in assigning registers in sections that contain function calls. Because all of the internal and imported PMI functions have addressability to the same set of registers, they will overwrite values set before function calls.
 
<pre><register>  = r<'0'..'255'></pre>
 
=== Operators, Assignment Expressions, and Conditional Expressions ===
The following operators are valid in the PMI syntax:
 
<pre><postfix unary additive op>  ::= '++'  |  '--'
<additive op>  ::= '+'  |  '-'
<shift op> ::= '<<'  |  '>>'
<bitwise op> ::= '&'  |  '|'  |  '^'
<relational op> ::= '<'  |  '>'  |  '==' | '<=' |  '>=' |  '!='
<binary assignment op> ::= '&=' | '|= ' | '<<=' |  '>>=' | '+=' | '-=' | '^='
<unary negation op>  ::= '~'
<assignment op>  ::= '='</pre>
Both assignment and conditional expressions in the PMI syntax are limited to a single expression term. The value of a conditional expression is either TRUE (nonzero) or FALSE (zero).
 
An assignment expression and example are shown below.
 
<pre><assignment>  ::=
<register><postfix unary additive op>  |
 
<register><binary assignment op> [<constant>|<register>]  |
 
<register><assignment op>  { <PMI Keyvariable>  |
                            <register operand>|<constant>  } |
 
<register><assignment op>  {<register operand>  |  <PMI keyvariable>}
                          {<additive op>|<shift op>  |  <bitwiseop>}
                          {<constant>  |  <register>
 
<register operand>  ::= [<unary negation op>]<register></pre>
Examples:
 
<pre>r0 = VerticalRefresh;
r0 <<= 0x10;
r1++; r2--;
r1 = ~r2 ^ 0x04;
r2 = XResolution <<  r1;
r1 = r2 + 0xffff;</pre>
A conditional expression and example are shown below.
 
<pre><condition>  ::=
          '(' { <PMI Keyvariable>  |  <register>} {<relational op> | <bitwise op>}
 
          { <PMI Keyvariable>  |  <register>  |  <constant>  } ')'</pre>
Examples:
 
<pre>(XResolution == 1024)
(r1 & 0x0fe0)
(r2 == VerticalRefresh)</pre>
 
=== PMI Functions ===
A PMI function is defined as a PMI Section with a user-defined name other than one of the predefined Section names.
 
PMI functions have the following characteristics:
*Argument passing is performed using registers.
*Functions can be of either the VOID type (no return value) or of the APIRET type (return 0 for success and nonzero for failure).
*Function prototypes are not explicitly declared; the calling section has to understand how many and which registers need to be set and set them before calling the function.
*Functions are invoked by specifying the function name in a section.
*Functions must be declared prior to their use.
*A function may be called from within a function.
*Recursions are not allowed.
*There is no explicit exit or return command from functions.
*The last command or assignment in the function's section is considered its exit point.
 
PMI functions should be used extensively to create commonality and to encapsulate related operations. This use will reduce development costs, support more adapter-specific variations, reduce the size of the .PMI file, and improve performance.
 
The [[#VIDEO_ADAPTER]] structure is passed by PMI procedural callers at every PMI entry point and is available to all of the PMI functions other than IdentifyAdapter. All PMI functions have addressability to the current state of the PMI registers and care should be taken in using the registers.
 
=== PMI Commands ===
PMI commands are divided into several categories, as follows:
*Simple I/O commands
*Block I/O commands
*Read/Modify/Write commands
*Simple memory access commands
*WAIT command
 
=== INx Commands ===
INx commands perform an I/O input from the source and place the result into the destination. Width can be byte, word, or doubleword. The syntax is as follows:
 
<pre>INB( destination, source);
INW( destination, source);
INDW( destination, source);
 
<destination>  ::= <register>
<source> ::= <constant>  |  <pio variable></pre>
 
=== OUTx Commands ===
OUTx commands perform an I/O output from the source into the destination. Width can be byte, word, or doubleword. The syntax is as follows:
 
<pre>OUTB( destination, source);
OUTW( destination, source);
OUTDW( destination, source);
 
<destination>  ::= <pio variable>  |  <constant>
<source>  ::= {<constant>  |  <register>}</pre>
For example:
 
<pre>outb(seq_address,r1);              //seq_address must have been declared.
outw(0x3c4,0x5520);
</pre>
 
=== Block I/O Commands ===
Block I/O commands are designed for indexed ports. Byte-indexed access requires both index and data port values. Word and Dword block I/O is implemented as autoincrement block I/O, which causes no explicit modification to the index register. Word and Dword block I/O assumes that the hardware either implements autoincrementing or that the values being written specify both index and data. The ''startindex''field is used as the index of the first PMI register in the set and as the first indexed port value. If the hardware's autoincrementing feature needs to be programmed explicitly, it should be done prior to calling the block I/O and should be left enabled upon completion of the mode set. See "Save and Restore State", and [TrapRegs] in [[#PMI Sections]].
 
<pre>BINB( count, startindex, indexport, dataport );
BOUTB( count,startindex, indexport, dataport );
 
<startindex>  ::= <constant>
<count>  ::= <constant>
<indexport>  ::= <pio variable>  |  <constant>
<dataport>  ::= <pio variable>  |  <constant>
<port>  ::= <pio variable>  |  <constant></pre>
For example:
 
<pre>r0 = 0x11; r1 = 0x12; r2 = 0x13;
boutb(0x03, 0x00, seq_address, seq_data);  //seq_address and seq_data
                                            //already declared.</pre>
 
 
=== RMWx Commands ===
RMWx (Read/Modify/Write) commands are available in byte format (indexed or nonindexed) and in word format (nonindexed). A nonindexed port RMWx can be used for ports that have different read and write access I/O addresses. The syntax is as follows:
 
<pre>RMWBI( indexport, dataport, index, andmask, ormask );
RMWB( bytereadport, bytewriteport, andmask, ormask );
RMWW( wordreadport, wordwriteport, andmask, ormask );
 
<indexport>  ::= <pio variable>  |  <constant>
<dataport>  ::= <pio variable>  |  <constant>
<bytereadport>  ::= <pio variable>  |  <constant>
<bytewriteport>  ::= <pio variable>  |  <constant>
<wordreadport>  ::= <pio variable>  |  <constant>
<wordwriteport>  ::= <pio variable>  |  <constant>
<index>  ::= <constant>
<andmask>  ::= <constant>
<ormask>  ::= <constant></pre>
For example:
 
<pre>rmww(0x4ae8, 0x4ae8, 0x01, 0x00);</pre>
 
=== Memory I/O Commands ===
Memory I/O commands have only simple, single-port access format. Block I/O or indexing is not facilitated. Supported widths are Byte, Word, or Dword. Both destination and source represent either physical addresses or a register. The syntax is as follows:
 
<pre>READB( destination, source );      //read from source address, store
                                            //in destination variable
READW(destination, source );
READDW( destination, source);
 
<destination>  ::= <register>
<source>  ::= <constant>  |  <mmio variable>
 
WRITEB( destination, source );          //read from source variable, store
                                        //in destination address
WRITEW( destination, source );
WRITEDW( destination, source );
<destination>  ::= <mmio variable>  |  <constant>
<source>  ::= <constant>|<register></pre>
For example:
 
<pre>writedw(interrupt_en, r1);      //interrupt_en already declared.
writeb(0xa0000080,0x88);      //write 0x88 into phys.  add 0xa00000080
readw(r1, 0xa0000080);        //read a word from 0xa0000080 into r1.</pre>
 
=== WAIT Command ===
The WAIT command should be used to wait on vertical retrace or to wait on a desired status. The command allows for a time-out in milliseconds. The condition for wait has been met if port value ANDed with andmask has the waitonvalue. Register r0 is set to convey the status:
*TRUE (1) means that the waiting condition has been met.
*FALSE means that a time-out has occurred.
 
The wait is interruptable. This command should not be used in Cleanup sections.
 
The port can be an immediate value, which presumes that the port is an I/O port or a declared port. In these cases, the port's declaration type is used in interpreting this command.
 
<pre>WAIT( port, andmask, timeout, waitonvalue );
<andmask>  ::= <number>
<timeout>  ::= <number>
<waitonvalue> ::= <number>
 
<port>  ::= <  constant>  |  <pio variable>  |  <mmio variable></pre>
 
=== PMI Constructs and Library Functions ===
PMI constructs are keywords that are used for program flow control in PMI command sections. There are three flow control constructs: WHILE loop, unconditional jump GOTO, and conditional IF GOTO label jump. The constructs can be nested. Label reference can only be forward; in other words, a label must have been encountered before its referring construct.
 
<pre>WHILE <condition>      ;while loop condition is true, proceed
...                            ;else continue after ENDWHILE statement
...
...
ENDWHILE
 
GOTO <label>            ;jump to label
 
IF <condition>  GOTO <label>    ;if condition true, jump to label</pre>
For example:
 
<pre>if (r1 != 0x88) goto done</pre>
Two library functions facilitate string and binary compares: STRCMP and MEMCMP. These functions are especially useful in searching for signature sequences when identifying the adapter or comparing other string-literal names. STRCMP is used to compare a zero-ended character string (must be in double quotes) source with a destination specified as its physical address. MEMCMP is used to compare binary fields. The source string-literal for MEMCMP is assumed to be a string of 1s and 0s. If there is a need to search for a hexadecimal or another string, these must be converted to their binary form first. Byte alignment of both the source and target in the physical memory is assumed. Both functions return the result in r0: zero if the match was completely successful or nonzero otherwise. The length of the search is determined by the length of the source string.
 
String compares are performed after both source and target are converted to uppercase.
 
<pre>STRCMP(<destination>, <source>};
<destination>  ::= <address>        ;physical address
<source>  ::= <string>)
MEMCMP(<destination>, <source>};
<source>  ::= <binary-string>
<address> ::= <PMI keyvariable> | <constant></pre>
For example:
 
<pre>MEMCMP (0xc0154,"1001001111010001"); //compare 2 bytes at 0xc0154 with 0x93d1</pre>
 
=== PMI Sections ===
Proceed to the following information for a description of the types of sections that appear in a .PMI file.
 
=== Sections and Their Order of Appearance ===
The service sections listed in the following table are commented on and illustrated using the PMI language.
 
The sections in the table are listed in the order they appear in a .PMI file.
{|class="wikitable"
!Name||Required||Type||Comments
|-
|[PMIVersion]||Yes||Informational||
|-
|[Hardware]||Yes||Informational||
|-
|[Declarations]||No||Informational||Provides multiple
instances, dynamic configuration support
|-
|[TrapRegs]||Yes||Informational||Provides limited virtualization support
|-
|[IdentifyAdapter]||Yes||Service||
|-
|[SetMemoryIOAddress]||No||Service||Sets the linear aperture
|-
|[UnLock]||Yes||Service||
|-
|[Cleanup]||Yes||Service||Provides reset, disable, and bail-out support
|-
|[SetBank]||Yes||Service||If applicable
|-
|[GetBank]||Yes||Service||If applicable
|-
|[TuneDisplay]||No||Service||Provides display centering and sizing
|-
|[Comment]||No||Informational||One per ModeInfo, if desired
|-
|[ModeInfo]||Yes||Informational||Multiple entries with unique values
|-
|[MonitorModeInfo]||No||Informational||Provides multiple-monitor timing support
|-
|[SetMode]||Yes||Service||At least one per file or, at most, one per MonitorModeInfo section
|}
 
=== Predefined PMI Sections ===
Proceed to the following information for a description of the PMI Sections listed in the table that appears under [[#Sections and Their Order of Appearance]].
 
=== [PMIVersion] ===
This section describes the PMI language revision level used.
 
=== [Hardware] ===
*BusType = { ISA | VLB | PCI | EISA | PCMCIA | MCA }
 
The hardware description is available through a system query function. Any other definition is regarded as a user definition.
 
*OEMString = "CHIPNAME ADAPTERNAME, ADAPTER MANUFACTURER NAME"
 
OEMString has an internal length of 128 chars, 0 ended. This string should be sufficient to uniquely describe the video adapter. The string will be presented to the user at configuration and installation and is the key element of the system's description of the adapter. It is regarded as a user definition, meaning that no translation of this information to any other format is performed. Any trademark information should be provided as a comment in the PMI file.
 
If the PMI file is not specifically written for an adapter, the ADAPTERNAME GENERIC is suggested (such files may be shipped by the chip manufacturers or software vendors). CHIPNAME is a required token and is used as a key in the display driver installation process to find a corresponding display driver for a given PMI file (and vice versa).
 
*DACString = "MANUFACTURER NAME [, DACNAME]"
 
DACNAME, such as Bt485 or AT&T 491 is optional. Regarded as a user definition. Any trademark information should be provided as a comment.
 
*Version = <string>
 
User-defined. Should represent the version of the manufacturer's .PMI file, rather than the revision level of the hardware. If multiple versions of the .PMI file exist for the same OEMString description, and all respective IdentifyAdapter function calls were successful, the file with the greater Version string is assumed to be the more appropriate one and is offered at the top of the PMI list during the video configuration.
 
The user, however, does have a choice of selecting a different PMI file. Note that the PMIVersion section is used to describe the PMI language revision level used, not the version of the PMI file.
 
*TotalMemory = <constant>
 
This represents the total size of the currently installed VRAM memory in bytes.
 
*MemoryIOAddress = <constant> ['{' <mmio list> '}'] <mmio list> ::= <constant> | <constant> [',' <mmio list>]
 
Specifies the default base memory address for memory mapped I/O and a list of possible base addresses. The default value should match the value set by the configuration performed at the time of the adapter's installation. It is possible to reconfigure the adapter's address at a later time without modifying the .PMI file.
 
If this address is specified and is not zero, the BufferAddress fields in the [ModeInfo] sections of all graphics modes with more than 256 colors will be replaced by this address and the usFlag in the [[#VIDEOMODEINFO]] structure will have MODE_FALG_LINEAR_BUFFER flag set to on, indicating that this mode can be set to linear aperture mode. [SetMemoryIOAddress] should also be provided to handle the address setting.
 
*PortIOAddress = <constant> ['{' <pio list> '}'] <pio list> ::= <constant> | <constant> [',' <pio list>]
 
Specifies default base port address for port I/O and a list of possible I/O addresses. For example, this variable for an MCA XGA adapter would reflect its instance that needs to be added to all of the register addresses. See the preceding discussion on MemoryIOAddress.
 
*Endian = {BIG | LITTLE}
 
This represents the endian control capability of the device. The PMI constants are always represented with the most significant byte at the leftmost position. There are three possible cases of endian control:
*The device can conform to the endian type of the platform, such as WEITEK or XGA.
*The device cannot conform to the endian type but is of the same endian type as the platform.
*The device is of a different endian type than the platform on which it is installed.
 
The first two cases require no endian conversion on the part of the VIDEOPMI interpreter. In the third case, the VIDEOPMI interpreter native to a platform will perform the byte swapping to the platform's endian type. The programming of the endian control on devices that are capable of address swapping, such as XGA or WEITEK, is the responsibility of the .PMI file. In the case of WEITEK, this is done indirectly by generating correct addresses. It is preferable to configure the adapter in the endian control of the platform for which it is intended, if such capability is present.
 
Here is a sample .PMI file for a Viper VLB card:
 
<pre>BusType = VLB
OEMString = "P9000 VIPER, Diamond Computer Systems Inc."
DACString = "Brooktree Corporation"
Version = "3.2"
TotalMemory = 2097152
MemoryIOAddress = 0x80000000
PortIOAddress = 0x00000000
Endian = LITTLE</pre>
 
=== [Declarations] ===
 
This section is a list of port mnemonics defined by their offsets. Use MMIO for those whose offset is relative to MemoryIOAddress and PIO for those whose offset is relative to the PortIOAddress field in the Hardware section . Addresses for the ports that are referenced by their mnemonics are resolved at the time of the mode sets, using the MemoryIOAddress and/or PortIOAddress hardware values. These values can be changed at run time to allow for dynamic reconfiguration.
 
Here is a sample .PMI file for a Viper VLB card:
 
<pre>sysconfig  = MMIO{0x00100004}
interrupt_en= MMIO{0x0010000c}
x0y0        = MMIO{0x00181018}
x1y1        = MMIO{0x00181028}
x2y2        = MMIO{0x00181048}
x3y3        = MMIO{0x00181068}
cindex      = MMIO{0x0018018c}
w_off.xy    = MMIO{0x00180190}
fground    = MMIO{0x00180200}
bground    = MMIO{0x00180204}
pmask      = MMIO{0x00180208}
draw_mode  = MMIO{0x0018020c}
pat_originx = MMIO{0x00180210}
pat_originy = MMIO{0x00180214}
raster      = MMIO{0x00180218}
pixel8_reg  = MMIO{0x0018021c}
w_min      = MMIO{0x00180220}
w_max      = MMIO{0x00180224}
pattern0    = MMIO{0x00180280}
pattern2    = MMIO{0x00180284}
pattern4    = MMIO{0x00180288}
pattern6    = MMIO{0x0018028c}
pattern8    = MMIO{0x00180290}
patternA    = MMIO{0x00180294}
patternC    = MMIO{0x00180298}
patternE    = MMIO{0x0018029c}</pre>
 
=== [TrapRegs] ===
Currently, the [TrapRegs] section is only parsed and used by virtual video driver (vsvga.sys). videopmi.dll does not interpret the contents.
 
=== [IdentifyAdapter] ===
This is a required section and should perform the adapter identification. Recommended identification steps depend on the bus architecture and hardware support for the identification. For example, on a PCI adapter, a positive check of the PCI device ID, revision ID, and vendor ID would be sufficient. On an ISA card, a physical memory location can be read and compared against a string or a binary key, using MEMCMP and STRCMP PMI commands. Or, an identification port could be read in order to confirm the adapter type and revision level. The dependency on familiar port response should be minimal and resorted to only if more reliable checks do not exist . For vendors writing .PMI files for generic adapter support, however, this may be the only option, and it should be implemented with great care.
 
Register r0 is used to hold the function result. The register should contain zero if the adapter matches its Hardware description (OEMString and DACString in its entirety) or nonzero otherwise.
 
The purpose of the IdentifyAdapter function is to verify that an instance of the adapter is found that matches the OEMString and Version string from the .PMI file's Hardware section. Whether multiple instances exist, or if the instance found is not configured to the passed MemoryIOAddress and PortIOAddress, is of no consequence.
 
An adapter is considered available if its IdentifyAdapter section returns success. Consequently, if the .PMI file contains the minimum VIDEOPMI content, its .PMI file will be loaded.
 
'''Attention:'''
 
It is essential that any I/O or MMIO registers modified in this section be saved and restored! This is of great importance, as IdentifyAdapter sections from a .PMI file will be executed on nonrelated hardware in an attempt to find the corresponding .PMI file.
 
=== [SetMemoryIOAddress] ===
This section provides a way to set the linear apertures after the mode set. It can be executed through [[#PMIREQUEST_SETMEMORYIOADDRESS]]. The passed address in that function will replace r0 in the PMI commands. Please see MemoryIOAddress under the [Hardware] section and [[#PMIREQUEST_SETMODE]] for details.
 
=== [UnLock] ===
This section contains the list of commands required to make the hardware available for the execution of the SetMode section, as well as for saving and restoring of the controller and video buffer. The list of commands should be inclusive of saving and restoring the registers modified in the process, with the exclusion of the unlock key register. The function can be made mode-sensitive by using the conditional statements that evaluate key mode PMI keyvariables. However, the function could be a superset of all required unlock commands, for as long as such a sequence is not counter- productive in any mode sets.
 
Here is a sample .PMI file for a 9GXE S3 card:
 
<pre>inb(r0, 0x3d4);              //save index
outb(0x3d4, 0x38);
outb(0x3d5, 0x48);
outb(0x3d4, 0x39);
outb(0x3d5, 0xa0);
outb(0x3d4, r0);              //restore index</pre>
 
=== [Cleanup] ===
Cleanup is used on session switches or when SetMode control is being relinquished to a driver that may not be VIDEOPMI-driven. This function is also used if and when a mode targeting the VGA chip is to be issued from a resource other than the .PMI file. The virtual video driver depends on this function during session switches when the engine is found busy and a reset engine mechanism is needed as part of the recovery. The function will also be used at shutdown, after the shutdown message is displayed. It ensures that extended functionality is disabled and reset to the extent that pure VGA compatibility and/or subsequent use of the accelerator is allowed. For SVGA and accelerator/coprocessors that coexist with a VGA chip, this function is used to disable the controller and enable the VGA chip. Recommended order of disabling is:
*Reset DAC to VGA mode.
*Reset engine.
*Disable extended functionality.
*Enable VGA.
*Set clock to 25 MHz.
 
Here is a sample .PMI file for a Viper VLB card:
<pre>[Cleanup]
          //reset DAC
r0  = 0x00000000;
r1  = 0x00000000;
ProgramDAC;
          //reset clock to 60Hz, 32 KHz
r0  = 0x0045A8BC;
ProgramClock;
          //enable VGA
DisableController;</pre>
 
=== [SetBank] ===
Specifies the commands necessary in order to switch banks on a frame buffer device. The function is called as part of the saving and restoring of the frame buffer for any mode with an aperture smaller than the PageLength. The bank number is assumed to be in r0. If the aperture is large enough to accommodate direct access to VRAM needed in any mode, the section may be omitted.
 
Here is a sample .PMI file for a 9GXE S3 card:
 
<pre>[SetBank]
                        //r0 contains the bank number
inb(r1, 0x3d4);          //save index
outb(0x3d4, 0x35);
r2  = r0  &  0x0000000f;
outb(0x3d4, 0x51);
inb(r2, 0x3d5);
r2  & = 0x00000030;
r0  >>= 0x00000002;
r2  & = 0x000000f3;
r0  |= r2  ;
outb(0x3d5, r0);        //set bank
outb(0x3d4, r1);        //restore index</pre>
 
=== [GetBank] ===
Specifies the name of the function to be called in order to get the current write bank. This assumes a device with an aperture smaller than the PageLength. The bank number is assumed to be returned in r0. It should be sensitive to the mode.
 
Here is a sample .PMI file for a 9GXE S3 card:
 
<pre>[GetBank]
inb(r1, 0x3d4);          //save index
outb(0x3d4, 0x35);
inb(r0, 0x3d5);
r0  & = 0x0000000f;
outb(0x3d4, 0x51);
inb(r2, 0x3d5);
r2  & = 0x00000004;
r2  <<= 0x00000002;
r0  |= r2  ;            //r0 contains the value
outb(0x3d4, r1);        //restore index</pre>
 
=== [TuneDisplay] ===
This section lists the execution steps required to set the start and end of the vertical active display in terms of the line count along the vertical sweep. It also lists the start and end of the horizontal active display in terms of the dot count along the horizontal sweep. The input values are the ScreenLeftEdge, ScreenRightEdge, ScreenTopEdge, and ScreenBottomEdge PMI keyvariables. The function should implement verification of the values, to keep them in the valid range for the current mode.
 
This section is not required but, if supplied, it provides a monitor centering and sizing capability. If provided, TuneDisplay should be invoked by the respective SetMode section in order to ensure that user-selected values are being reflected in the mode set. This applies to all MonitorModeInfo sections that list the four PMI keyvariables. If the current mode does not contain the PMI keyvariables, TuneDisplay will be a no-op, because default mode values do not correspond to how the real hardware is programmed and, therefore, the tuning cannot be performed.
 
The PMI keyvariable values represent the pixel count (dot count* bytesperpixel) and line count. They are incremented according to the end- user's configuration requests, which are processed one unit at a time. For example, if the user is trying to center a display in 640x480x64K, the start values of the current active display are obtained from the mode table for the current mode. For every mouse or pointer drag-increment on the centering area to the left, the current ScreenLeftEdge and ScreenRightEdge fields are incremented and a call into TuneDisplay is made with the current values. TuneDisplay translates the values into the dot count or any other internal representation and validates the range.
 
Here is a sample .PMI file for a Viper VLB card:
 
<pre>[TuneDisplay]
r0 = 1;            //set return code to failure, if validation fails
if (BitsPerPixel < 8) goto exittune
                    // all horizontal values are set in terms of DDOTCLK
                    //multiply by the number of bytes.
r9 = BitsPerPixel >> 4;
r5 = ScreenLeftEdge << r9;        //r5 = hrzbr
r6 = ScreenRightEdge << r9;        //r6 = hrzbf
r7 = ScreenTopEdge;                //r7 = vrtbr
r8 = ScreenBottomEdge;            //r8 = vrtbf
readdw(r1, hrzsr);                //validate parameters
if (r5 <= r1) goto exittune        //validate left edge > hrzsr
readdw(r2, vrtsr);
if (r7 <= r2) goto exittune        //validate top edge > vrtsr
readdw(r3, hrzt);
if (r6 >= r3) goto exittune        //validate right edge < hrzt
readdw(r4, vrtt);
if (r8 >= r4) goto exittune        //validate bottom edge < vrtt
writedw(hrzbr, r5);
writedw(hrzbf, r6);
writedw(vrtbr, r7);
writedw(vrtbf, r8);
r0 = 0;                            //indicate success exittune:</pre>
 
=== [ModeInfo] ===
ModeInfo, together with the MonitorModeInfo section, defines mode capabilities of the PMI adapter. The complete list of all ModeInfo and MonitorModeInfo headers is available through a system-mode query function. The ModeInfo header specifies attributes that are not dependent on the type of display attached. Some of the fields are optional and, if not provided, are internally set to 0. Most fields are static; that is, they will not be modified at run-time and changed from their .PMI file values. However, Aperture address is a dynamic PMI keyvariable and is set by the caller to reflect the current value. All of the mode PMI keyvariables are field members of the VIDEOMODEINFO structure, a substructure of the VIDEO_ADAPTER.
 
*ModeAttributes = <constant>
**Static PMI keyvariable. Required.
**0x18 for color graphic modes, 0x08 for color text modes.
**See VESA SVPMI Standard for full description.
 
*BytesPerScanLine = <constant>
**Static PMI keyvariable. Required.
**Length of logical scan line in bytes.
**See VESA SVPMI Standard for full description.
 
*XResolution = <constant>
**Static PMI keyvariable. Required.
**Horizontal resolution in pixels or characters in graphics and text modes, respectively.
 
*YResolution = <constant>
**Static PMI keyvariable. Required.
**Vertical resolution in pixels or characters in graphics and text modes, respectively.
 
*XCharSize = <constant>
**Static PMI keyvariable. Required in text modes.
**Character cell width in pixels.
 
*YCharSize = <constant>
**Static PMI keyvariable. Required in text modes.
**Character cell height in pixels.
 
*TextRows = <constant>
**Static PMI keyvariable. Required in both graphics and text modes.
**Number of text rows.
 
*BitsPerPixel = <constant>
**Static PMI keyvariable. Required.
**Color depth.
 
*NumberOfPlanes = <constant>
**Static PMI keyvariable. Required.
**[4|1] planar vs. linear memory organization.
 
*PageLength = <constant>
**Static PMI keyvariable. Required.
**Size of memory required to save a page of the on-screen VRAM.
 
*SaveSize = <constant>
**Static PMI keyvariable. Required.
**Size of memory required to save all of the on-screen VRAM. It should be set to include at least the logical scanline width (BytesPerScanLine* Yresolution).
 
*Int10ModeSet = <constant>
**Static PMI keyvariable. Required if the same mode can be set though BIOS.
 
*ColorFormat = <string>
**Static PMI keyvariable. Optional.
**User defined.
**Zero-ended string. Required for hi-color and true-color modes.
 
Suggested definitions:
[ RGB | BGR | GBR | YUI ]
 
<br />-Not used internally; available to drivers through a mode query. <br />-If not specified, zeros are returned.
 
ColorWeight = <constant> ':' <constant> ':' <constant>
 
-Static PMI keyvariable. Optional. <br />-User defined. <br />-Required for hi-color and true-color modes. <br />-Not used internally; available to drivers through a mode query. <br />-If not specified, zeros are returned.
 
BufferAddress = <constant>
 
-Dynamic PMI keyvariable. Required if direct VRAM access is possible.
 
-Represents the physical address of the video buffer. If direct buffer access is possible, VIDEOPMI interpreter will copy VRAM in chunks of ApertureSize or SaveSize, whichever is smaller. If 0, no direct buffer access is possible.
 
This PMI keyvariable is dynamic on all systems in which remapping of the aperture is possible. In such cases, it should be assigned the LinearWindowAddress value from the Hardware description. The SetMode section should ensure that it programs hardware to reflect the hardware's dynamic value.
 
ApertureSize = <constant>
 
-Static PMI keyvariable. Required if direct VRAM access is possible. <br />-Size of the aperture. If ApertureSize < SaveSize and BufferAddress is not 0, SetBank and GetBank sections are required. <br />-Aperture size will not be modified, even if hardware does allow for different sizes.
 
Colors.
 
-Number of colors for this mode.
 
Here is a sample .PMI file for a 9GXE S3 card:
 
<pre>[comment]
    Graphics  Mode :  1280  x  1024  x  256  colors .
 
[ ModeInfo ]
      ModeAttributes    =  0x18
      BytesPerScanLine  =  1280
      XResolution        =  1280
      YResolution        =  1024
      TextRows          =  64
      BitsPerPixel      =  8
      NumberOfPlanes    =  1
      PageLength        =  1310720
      SaveSize          =  1310720
      Int10ModeSet      =  0x107
      BufferAddress      =  0x000a0000
      ApertureSize      =  0x00010000 </pre>
 
=== [MonitorModeInfo] ===
This section provides information on the capabilities of the adapter in terms of the synchronization signal range. This section is optional if an adapter does not require software intervention in order to detect the monitor type and program the optimal HSYNC, VSYNC, HBLNK, and VBLNK signals . Because the industry lacks a standard for monitor detection, most adapters require user intervention in order to detect the monitor and additional software to handle selection of the horizontal and vertical frequencies for the configured monitor. In the OS/2 environment, the configuration and recording of the user selection is done by the DSPCONF utility. The information is then available to all video drivers.
 
Depending on the type of clock generator, the specified frequencies could be definable only in distinct (discrete) sets of values, or they could be generated within the maximum range of the clock chip. Therefore, one or more MonitorModeInfo sections are used to provide a vehicle for user configuration of the refresh setup and for the subsequent mode setting.
 
If clock generation is contiguous within a range, a single MonitorModeInfo with the end of the range should be listed per each mode. Otherwise, a list of MonitorModeInfo sections should list all of the discrete refresh pairs. In this case, an exact match between the monitor refresh specification and the adapter's refresh capability has to happen (this includes the polarity information). If the vendor providing the .PMI file does not wish to discriminate based on the polarity, the polarity can be omitted or set to a predefined value of 2.
 
Note that all of the PMI keyvariables are marked as dynamic. This means that their run-time values could differ from their values specified in the flat file, depending on the user configuration. This also means that sections programming the hardware should verify that the values passed are in the valid range.
 
VerticalRefresh = <constant>
 
-Dynamic PMI keyvariable. Required. <br />-Vertical refresh in Hz, rounded to the nearest integer. <br />-Should be set to 0 for flat panel and other non-CRT display modes. Otherwise, set to either a discrete value or end-of-range value.
 
HorizontalRefresh = <constant>
 
-Dynamic PMI keyvariable. Required. <br />-Horizontal refresh in KHz, rounded to the nearest integer. <br />-Should be set to 0 for flat panel and other non-CRT display modes. Otherwise, set to either a discrete value or end-of-range value.
 
VPolarityPositive = <'0' | '1' | '2'>
 
-Vertical polarity. <br />-Dynamic PMI keyvariable. Not required. <br />-0 indicates negative; 1 indicates positive; 2 indicates that either one can be set and should not be used when matching the monitor specification. A value of 2 is logically the same as omitting the keyvariable.
 
HPolarityPositive = <'0' | '1' | '2'>
 
-Horizontal polarity. <br />-Dynamic PMI keyvariable. Not required. <br />-0 indicates negative; 1 indicates positive; 2 indicates that either one can be set and should not be used when matching the monitor specification. A value of 2 is logically the same as omitting the keyvariable.
 
ScreenLeftEdge = <constant>
 
-Dynamic PMI keyvariable. Required if TuneDisplay section exists.
 
-Defines the start of the active horizontal display in terms of the pixel count. Internally, it represents the offset in terms of the dot count along the horizontal sweep.
 
-If the TuneDisplay section is provided, the user has the option of fine- tuning this value. Consequently, the SetMode call will set the hardware according to the dynamic value of this PMI keyvariable (see [TuneDisplay] and [SetMode] in this chapter).
 
ScreenRightEdge = <constant>
 
-Dynamic PMI keyvariable. Required if TuneDisplay section exists.
 
-Defines the end of the horizontal active display in terms of the pixel count. Internally, it represents the offset in terms of the dot count along the horizontal sweep for the current mode.
 
-If the TuneDisplay section is provided, the user has the option of fine- tuning this value. Consequently, the mode will set the hardware according to the dynamic value of this PMI keyvariable (see [TuneDisplay] and [ SetMode] in this chapter).
 
ScreenBottomEdge = <constant>
 
-Dynamic PMI keyvariable. Required if TuneDisplay section exists.
 
-Defines the end of the active vertical display in terms of the line count along the vertical sweep in the current mode.
 
-If the TuneDisplay section is provided, the user has the option of fine- tuning this value. Consequently, the mode will set the hardware according to the dynamic value of this PMI keyvariable (see [TuneDisplay] and [ SetMode] in this chapter).
 
ScreenTopEdge = <constant>
 
-Dynamic PMI keyvariable. Required if TuneDisplay section exists.
 
-Defines the start of the vertical sync in the current mode.
 
-If the TuneDisplay section is provided, the user has the option of fine- tuning this value. Consequently, the mode will set the hardware according to the dynamic value of this PMI keyvariable (see [TuneDisplay] and [ SetMode] in this chapter).
 
Here is a sample .PMI file for a Viper VLB card:
 
<pre>[MonitorModeInfo]            //1024 x 768 resolution
 
VerticalRefresh        = 80
HorizontalRefresh      = 64
VPolarityPositive      = 1
HPolarityPositive      = 1
ScreenLeftEdge          = 0x00000047
ScreenRightEdge        = 0x00000147
ScreenTopEdge          = 0x00000023
ScreenBottomEdge        = 0x00000323</pre>
 
=== [SetMode] ===
 
This section lists the required execution steps for a successful mode set. There could be one SetMode section per MonitorModeInfo, or one per ModeInfo , or one that services multiple modes. The Interpreter tags all ModeInfo and MonitorModeInfo sections found between two SetMode sections and, later on, associates the last SetMode with all of them. Thus, SetMode services for all of the modes could be provided by a number of different functions ( if desired, a single function that serves as a router can be used). The SetMode section is also executed when Saving and Restoring the mode (see [ SaveRestore] in this chapter).
 
Any number of PMI functions can be called from within the mode section. The SetMode section has to ensure that the adapter is programmed to reflect the run-time settings of the ModeInfo/MonitorModeInfo structure. These settings are passed in the VIDEO_ADAPTER.VIDEOMODEINFO structure at the procedural level. The settings are also available as PMI keyvariables to the PMI language command sequences. On dynamic Legacy and PnP hardware, or when a coprocessor co-resides with a VGA chip, the SetMode has to ensure that the setup is configured appropriately for the mode to be set. This should be facilitated by an embedded EnableController call, which is sensitive to the current Hardware PMI keyvariable values.
 
Vendors who provide the TuneDisplay section for sizing of the active display and the SetMonitorTimings section for manipulation of the timing PMI keyvariables should ensure that the SetMode section has the ability to set the run-time values for the timing PMI keyvariables. The easiest way to ensure this is by making the SetMode section use the SetMonitorTimings and TuneDisplay sections.
 
See [[#Supported Modes]] and [EnableController] in this chapter for more information.
 
Here is a sample .PMI file for a Viper VLB card:
<pre>[SetMode]
SetP9000AccelMode;
 
/*
** Set accelerated mode on P9000
*/
[SetP9000AccelMode]
EnableController;            //configure controller
r0  = 0x00000000;            //set DAC
r1  = 0x00000040;            //256 color 6:6:6
if (BitsPerPixel != 16) goto DAC
r1  = 0x00000030;            // 64K colors
DAC:
ProgramDAC;
InitializeP9000;              //initialize P9000 registers
                              //set sysconfig and clipping
if (Xresolution != 640) goto not640
r1  = 0x028001e0;            //640x480x8
r0  = 0x00563000;
if (BitsPerPixel == 8) goto domodeset
r0  = 0x00683000;            //640x480x16 bits
goto domodeset
not640:
if (Yresolution != 800) goto not800    //800x600x8
r0  =  0x00587000;
r1  =  0x03200258;
goto domodeset
not800:                      //must be 1024x760x8
r0  =  0x00603000;
r1  =  0x04000300;
domodeset:
writedw(sysconfig,r0);
writedw(w_min,0x00000000);
writedw(w_max,r1);            //program clipping
SetMonitorTimings;            //program clock and timings. Calls TuneDisplay.
writedw(srtctl,0x000001e5);  //enable</pre>
 
=== User-Defined Function Sections ===
Any section denoted by [NAME] not listed in the preceding table is regarded as a user-defined section. The function can be called internally by the predefined PMI sections or other user-defined functions (see "PMI Functions" in [[#PMI Language Elements]]).
 
==VIDEOCFG.DLL Exported Functions==
The VIDEOCFG.DLL shared library represents the video configuration module in OS/2. Resolution, monitor, and refresh configuration methods are standardized, meaning that IBM- and vendor-shipped drivers for different video devices have the same user interface for the video configuration. The configuration of the resolution is handled by Page 1 of the System Icon notebook. The monitor configuration is handled by Page 2 of the System icon notebook. Page 2 is offered whenever the PMI subsystem contains timing information in its mode table and the attached monitor does not support the VESA DDC standard. For DDC monitors, Page 2 is not offered, because the DDC standard provides a software interface for retrieving monitor specifications and no user interaction is required.
 
Resolution listbox entries are based on the mode table supported by the display driver, as retrieved via the DspQueryDisplayResolutions API. Refresh listbox on Page 1 is offered for each display driver supported mode that has timing information (VerticalRefresh other than 0xFFFF) in the PMI subsystem mode table.
 
User configuration is recorded at closing of the System object in VIDEO.CFG , a private profiling file. This is a flat file with syntax similar to that of the PMI. The very first VIDEO.CFG is created by the SVGA.EXE utility ( both the IBM-shipped version and the SVGAOEM.EXE provided in the DDK for vendor modification) and reflects the detected monitor configuration at install time. The only generic monitor detection built into the utility is that of the VESA DDC standard. For adapter-specific current monitor configuration, the utility has to be modified to &quot;read&quot; the current settings. An alternative approach is to choose and hard code some standard settings as the default monitor configuration. All of the legacy monitors, as well as the original default settings, are stored in the monitor database. The monitor database is composed of MONITOR.DIF and the optional PRIVATE.DIF. The PRIVATE.DIF can be created by vendors performing RIPL install who prefer to leave MONITOR.DIF as a read-only file. .DIF files are flat files with PMI-like syntax and can be edited to correct or add new legacy monitor entries.
 
VIDEOCFG.DLL also supports a generic display driver configuration, which allows display drivers to declare one or more settings, the type of each setting, possible values, as well as current value of each setting. When the display driver does have a need to handle some user interface, this feature is the preferred method to any custom configuration. The reason it is preferred is that, in the future, with dynamic resolution change and adapter change, the configuration manager will be able to save and restore all of the display driver custom settings. Note that VIDEOCFG does not attempt to understand the nature of each setting, nor is it performing any profiling of the setting changes.
 
When the feature is exported by the display driver via a DevEscape (see [[Generic Video Configuration Interface]]), VIDEOCFG provides a &quot;Capabilities&quot; button on Page 1 that opens a notebook with one page dedicated to each declared setting. Help for each setting, if desired, has to be exported by the display driver via a resource module and a resource ID for the help. As the user makes changes to the settings, the display driver is notified at the time the System Icon changes and is responsible for recording ( profiling) the new value. Each time the pages of the settings are opened, VIDEOCFG will query the display driver for the current value of each exported setting.
 
Current monitor and mode configuration can be queried and changed via the VIDEOCFG's exported APIs, all of which are listed here and prototyped in h\svgadefs. h.
 
=== Exported Functions ===
The following API services are exported by VIDEOCFG.DLL:
*AddMonitorData
*GetAllMonitors
*GetCurrentCFG
*GetCurrentDesktopMode
*QueryNumMonitors
*SetCurrentCFG
The format and syntax of each of the above functions is shown on the following pages.
 
=== AddMonitorData ===
Description:
 
''AddMonitorData''adds a monitor definition to the VIDEOCFG.DLL monitor definitions database. The monitor definition is also written to the MONITOR .DIF file.
 
<pre>#include &lt;svgadefs.h&gt;
 
MONITORINFO    *pNewMonitorInfo;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;                /*  Return codes. */
 
rc = AddMonitorData(*pNewMonitorInfo);</pre>
 
=== AddMonitorData - Syntax ===
 
Description:
 
''AddMonitorData''adds a monitor definition to the VIDEOCFG.DLL monitor definitions database. The monitor definition is also written to the MONITOR .DIF file.
 
<pre>#include &lt;svgadefs.h&gt;
 
MONITORINFO    *pNewMonitorInfo;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;                /*  Return codes. */
 
rc = AddMonitorData(*pNewMonitorInfo);</pre>
 
=== AddMonitorData Parameter - *pNewMonitorInfo ===
 
'''*pNewMonitorInfo'''([[MONITORINFO]]) - input Pointer to the MONITORINFO data structure.
 
This parameter points to the [[MONITORINFO]]data structure that specifies the new monitor definition to add to the database.
 
=== AddMonitorData Return Value - rc ===
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns one of the following errors:
 
<br />ERROR_INVALID_PARAMETER <br />ERROR_NO_MONITOR_SUPPORT
 
=== AddMonitorData - Parameters ===
 
'''*pNewMonitorInfo'''([[MONITORINFO]]) - input Pointer to the MONITORINFO data structure.
 
This parameter points to the [[MONITORINFO]]data structure that specifies the new monitor definition to add to the database.
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns one of the following errors:
 
<br />ERROR_INVALID_PARAMETER <br />ERROR_NO_MONITOR_SUPPORT
 
=== AddMonitorData - Remarks ===
None.
 
=== GetAllMonitors ===
Description:
 
''GetAllMonitors''retrieves all monitor definitions. These monitor definitions are defined in the MONITOR.DIF file.
 
<pre>#include &lt;svgadefs.h&gt;
 
MONITORINFO    *pMonitors;    /*  Pointer to the array of MONITORINFO data structures. */
PULONG        pulBufferSize;  /*  Specifies the size of the pMonitors buffer, in bytes. */
ULONG          rc;            /*  Return codes. */
 
rc = GetAllMonitors(*pMonitors, pulBufferSize);</pre>
 
=== GetAllMonitors - Syntax ===
Description:
 
''GetAllMonitors''retrieves all monitor definitions. These monitor definitions are defined in the MONITOR.DIF file.
 
<pre>#include &lt;svgadefs.h&gt;
 
MONITORINFO    *pMonitors;    /*  Pointer to the array of MONITORINFO data structures. */
PULONG        pulBufferSize;  /*  Specifies the size of the pMonitors buffer, in bytes. */
ULONG          rc;            /*  Return codes. */
 
rc = GetAllMonitors(*pMonitors, pulBufferSize);</pre>
 
=== GetAllMonitors Parameter - *pMonitors ===
 
'''*pMonitors'''([[MONITORINFO]]) - output Pointer to the array of [[MONITORINFO]]data structures.
 
This parameter points to the array of MONITORINFO data structures that receive all the monitor definitions in the MONITOR.DIF file.
 
=== GetAllMonitors Parameter - pulBufferSize ===
 
'''pulBufferSize'''(PULONG) - output Specifies the size of the ''pMonitors''buffer, in bytes.
 
If the buffer size is too small to contain all monitor definitions, the ERROR_NOT_ENOUGH_MEMORY error is returned. The variable is then given the size of the buffer required in order to contain all monitor definitions.
 
=== GetAllMonitors Return Value - rc ===
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns one of the following errors:
 
<br />ERROR_INVALID_PARAMETER <br />ERROR_NO_MONITOR_SUPPORT <br />ERROR_NOT_ENOUGH_MEMORY
 
=== GetAllMonitors - Parameters ===
 
'''*pMonitors'''([[MONITORINFO]]) - output Pointer to the array of [[MONITORINFO]]data structures.
 
This parameter points to the array of MONITORINFO data structures that receive all the monitor definitions in the MONITOR.DIF file.
 
'''pulBufferSize'''(PULONG) - output Specifies the size of the ''pMonitors''buffer, in bytes.
 
If the buffer size is too small to contain all monitor definitions, the ERROR_NOT_ENOUGH_MEMORY error is returned. The variable is then given the size of the buffer required in order to contain all monitor definitions.
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns one of the following errors:
 
<br />ERROR_INVALID_PARAMETER <br />ERROR_NO_MONITOR_SUPPORT <br />ERROR_NOT_ENOUGH_MEMORY
 
=== GetAllMonitors - Remarks ===
 
None.
 
 
=== GetCurrentCFG ===
 
Description:
 
''GetCurrentCFG''gets the current video configuration stored in the Registry.
 
<pre>#include &lt;svgadefs.h&gt;
 
ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;        /*  Return codes. */
 
rc = GetCurrentCFG(*pAdapter, *pMonitor);</pre>
 
=== GetCurrentCFG - Syntax ===
 
Description:
 
''GetCurrentCFG''gets the current video configuration stored in the Registry.
 
<pre>#include &lt;svgadefs.h&gt;
 
ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;        /*  Return codes. */
 
rc = GetCurrentCFG(*pAdapter, *pMonitor);</pre>
 
=== GetCurrentCFG Parameter - *pAdapter ===
 
'''*pAdapter'''(ADAPTERINFO) - output Pointer to the [[ADAPTERINFO]] data structure.
 
This parameter points to the data structure receiving the current video adapter information.
 
=== GetCurrentCFG Parameter - *pMonitor ===
 
'''*pMonitor'''([[MONITORINFO]]) - output Pointer to the [[MONITORINFO]] data structure.
 
This parameter points to the data structure receiving the current video monitor information.
 
=== GetCurrentCFG Return Value - rc ===
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns one of the following errors:
 
<br />ERROR_INVALID_PARAMETER <br />ERROR_INVALID_CONFIGURATION
 
=== GetCurrentCFG - Parameters ===
 
'''*pAdapter'''(ADAPTERINFO) - output Pointer to the [[ADAPTERINFO]] data structure.
 
This parameter points to the data structure receiving the current video adapter information.
 
'''*pMonitor'''([[MONITORINFO]]) - output Pointer to the [[MONITORINFO]] data structure.
 
This parameter points to the data structure receiving the current video monitor information.
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns one of the following errors:
 
<br />ERROR_INVALID_PARAMETER <br />ERROR_INVALID_CONFIGURATION
 
=== GetCurrentCFG - Remarks ===
None.
 
=== GetCurrentDesktopMode ===
Description:
 
''GetCurrentDesktopMode''retrieves the current desktop mode information stored in the Registry. The desktop mode information includes X and Y resolutions, bits per pixel, vertical and horizontal refresh rates, vertical and horizontal polarity positives, and screen top, bottom, left, and right.
 
<pre>#include &lt;svgadefs.h&gt;
 
VIDEO_ADAPTER    *pVideoAdapter;  /*  Pointer to the VIDEO_ADAPTER data structure. */
ULONG            rc;              /*  Return codes. */
 
rc = GetCurrentDesktopMode(*pVideoAdapter);</pre>
 
=== GetCurrentDesktopMode - Syntax ===
 
Description:
 
''GetCurrentDesktopMode''retrieves the current desktop mode information stored in the Registry. The desktop mode information includes X and Y resolutions, bits per pixel, vertical and horizontal refresh rates, vertical and horizontal polarity positives, and screen top, bottom, left, and right.
 
<pre>#include &lt;svgadefs.h&gt;
 
VIDEO_ADAPTER    *pVideoAdapter;  /*  Pointer to the VIDEO_ADAPTER data structure. */
ULONG            rc;              /*  Return codes. */
 
rc = GetCurrentDesktopMode(*pVideoAdapter);</pre>
 
=== GetCurrentDesktopMode Parameter - *pVideoAdapter ===
 
'''*pVideoAdapter'''([[VIDEO_ADAPTER]]) - output Pointer to the [[VIDEO_ADAPTER]]data structure.
 
This parameter points to the data structure receiving the desktop mode information.
 
=== GetCurrentDesktopMode Return Value - rc ===
 
'''rc'''(ULONG) - returns Return codes.
 
TRUE Function is successful <br />FALSE Function is unsuccessful.
 
=== GetCurrentDesktopMode - Parameters ===
 
'''*pVideoAdapter'''([[VIDEO_ADAPTER]]) - output Pointer to the [[VIDEO_ADAPTER]]data structure.
 
This parameter points to the data structure receiving the desktop mode information.
 
'''rc'''(ULONG) - returns Return codes.
 
TRUE Function is successful <br />FALSE Function is unsuccessful.
 
=== GetCurrentDesktopMode - Remarks ===
None.
 
=== QueryNumMonitors ===
 
Description:
 
''QueryNumMonitors'' queries the number of monitor defintions available.
 
<pre>#include &lt;svgadefs.h&gt;
 
PULONG    pulNumMonitors;  /*  Pointer to variable receiving the number of monitor definitions. */
ULONG    rc;              /*  Return codes. */
 
rc = QueryNumMonitors(pulNumMonitors);</pre>
 
=== QueryNumMonitors - Syntax ===
 
Description:
 
''QueryNumMonitors''queries the number of monitor defintions available.
 
<pre>#include &lt;svgadefs.h&gt;
 
PULONG    pulNumMonitors;  /*  Pointer to variable receiving the number of monitor definitions. */
ULONG    rc;              /*  Return codes. */
 
rc = QueryNumMonitors(pulNumMonitors);</pre>
 
=== QueryNumMonitors Parameter - pulNumMonitors ===
 
'''pulNumMonitors'''(PULONG) - output Pointer to variable receiving the number of monitor definitions.
 
=== QueryNumMonitors Return Value - rc ===
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns the following error:
 
<br />ERROR_NO_MONITOR_SUPPORT
 
=== QueryNumMonitors - Parameters ===
 
'''pulNumMonitors'''(PULONG) - output Pointer to variable receiving the number of monitor definitions.
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns the following error:
 
<br />ERROR_NO_MONITOR_SUPPORT
 
=== QueryNumMonitors - Remarks ===
None.
 
=== SetCurrentCFG ===
Description:
 
''SetCurrentCFG''sets the current video configuration in the Registry.
 
<pre>#include &lt;svgadefs.h&gt;
 
ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;        /*  Return codes. */
 
rc = SetCurrentCFG(*pAdapter, *pMonitor);</pre>
 
=== SetCurrentCFG - Syntax ===
 
Description:
 
''SetCurrentCFG''sets the current video configuration in the Registry.
 
<pre>#include &lt;svgadefs.h&gt;
 
ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;        /*  Return codes. */
 
rc = SetCurrentCFG(*pAdapter, *pMonitor);</pre>
 
=== SetCurrentCFG Parameter - *pAdapter ===
 
'''*pAdapter'''(ADAPTERINFO) - input Pointer to the [[ADAPTERINFO]]data structure.
 
This parameter points to the data structure that specifies the current adapter configuration to be set in the Registry.
 
=== SetCurrentCFG Parameter - *pMonitor ===
 
'''*pMonitor'''([[MONITORINFO]]) - input Pointer to the [[MONITORINFO]] data structure.
 
This parameter points to the data structure that specifies the current monitor configuration to be set in the Registry.
 
=== SetCurrentCFG Return Value - rc ===
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns one of the following errors:
 
<br />ERROR_INVALID_PARAMETER <br />ERROR_INVALID_CONFIGURATION
 
=== SetCurrentCFG - Parameters ===
 
'''*pAdapter'''([[ADAPTERINFO]]) - input Pointer to the [[ADAPTERINFO]] data structure.
 
This parameter points to the data structure that specifies the current adapter configuration to be set in the Registry.
 
'''*pMonitor'''([[MONITORINFO]]) - input Pointer to the [[MONITORINFO]]data structure.
 
This parameter points to the data structure that specifies the current monitor configuration to be set in the Registry.
 
'''rc'''(ULONG) - returns Return codes.
 
0 Function is successful <br />Nonzero Returns one of the following errors:
 
<br />ERROR_INVALID_PARAMETER <br />ERROR_INVALID_CONFIGURATION
 
=== SetCurrentCFG - Remarks ===
None.
 
==Generic Video Configuration Interface==
The Video Configuration Manager supports a generic video configuration interface that allows any display driver to interface with the user via notebook settings in the System icon. The driver needs to export DevEscape calls that identify the capability. The driver also needs to provide DevEscape calls that allow the VIDEOCFG to query the current value and notify the driver when the user sets the value. The DevEscape functions are invoked as Ring3. The method of recording the current setting, as well as default values, is at the driver's discretion.
 
=== GreEscape DEVESC_QUERYDRIVERCAPS ===
'''Simulation support:'''
 
This function is optional for display drivers and has no simulation support .
 
Description:
 
''GreEscape DEVESC_QUERYDRIVERCAPS''returns the capabilities descriptions. The values for each capability are not yet allocated and are queried later. The #define DEVESC_QUERYDRIVERCAPS (4010L) is defined in SVGADEFS.H.
 
<pre>#define INCL_GRE_DEVICE
#include &lt;GRADD.h&gt;
 
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_QUERYDRIVERCAPS */
LONG    lInCount;    /*  Not used. */
PBYTE    pbInData;    /*  Not used. */
PLONG    plOutCount;  /*  The number of bytes of data pointed to by pbOutData. */
PBYTE    pbOutData;  /*  The address of a buffer that will contain a ULONG variable specifying the number of capabilities. */
LONG    rc;          /*  Return Code. */
 
rc = GreEscape(hdc, lCode, lInCount, pbInData,
      plOutCount, pbOutData);</pre>
 
=== GreEscape DEVESC_QUERYDRIVERCAPS - Syntax ===
 
'''Simulation support:'''
 
This function is optional for display drivers and has no simulation support .
 
Description:
 
''GreEscape DEVESC_QUERYDRIVERCAPS''returns the capabilities descriptions. The values for each capability are not yet allocated and are queried later. The #define DEVESC_QUERYDRIVERCAPS (4010L) is defined in SVGADEFS.H.
 
<pre>#define INCL_GRE_DEVICE
#include &lt;GRADD.h&gt;
 
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_QUERYDRIVERCAPS */
LONG    lInCount;    /*  Not used. */
PBYTE    pbInData;    /*  Not used. */
PLONG    plOutCount;  /*  The number of bytes of data pointed to by pbOutData. */
PBYTE    pbOutData;  /*  The address of a buffer that will contain a ULONG variable specifying the number of capabilities. */
LONG    rc;          /*  Return Code. */
 
rc = GreEscape(hdc, lCode, lInCount, pbInData,
      plOutCount, pbOutData);</pre>
 
=== GreEscape DEVESC_QUERYDRIVERCAPS Parameter - hdc ===
 
'''hdc'''(HDC) - input A handle to the device context.
 
=== GreEscape DEVESC_QUERYDRIVERCAPS Parameter - lCode ===
 
'''lCode'''(LONG) - input DEVESC_QUERYDRIVERCAPS
 
=== GreEscape DEVESC_QUERYDRIVERCAPS Parameter - lInCount ===
 
'''lInCount'''(LONG) - input Not used.
 
=== GreEscape DEVESC_QUERYDRIVERCAPS Parameter - pbInData ===
 
'''pbInData'''(PBYTE) - input Not used.
 
=== GreEscape DEVESC_QUERYDRIVERCAPS Parameter - plOutCount ===
 
'''plOutCount'''(PLONG) - output The number of bytes of data pointed to by ''pbOutData.''
 
On return, this is updated to the number of bytes returned.
 
=== GreEscape DEVESC_QUERYDRIVERCAPS Parameter - pbOutData ===
 
'''pbOutData'''(PBYTE) - output The address of a buffer that will contain a ULONG variable specifying the number of capabilities.
 
On return, this buffer contains a ULONG variable that specifies the number of capabilities that the driver supports, immediately followed by an array of [[DRIVERCAPS]] structures.
 
'''Note:'''This allows a driver to export multiple capabilities (each, in turn, gets its own page in the System icon).
 
=== GreEscape DEVESC_QUERYDRIVERCAPS Return Value - rc ===
 
'''rc'''(LONG) - returns Return Code.
 
Returns NO_ERROR.
 
=== GreEscape DEVESC_QUERYDRIVERCAPS - Parameters ===
 
'''hdc'''(HDC) - input A handle to the device context.
 
'''lCode'''(LONG) - input DEVESC_QUERYDRIVERCAPS
 
'''lInCount'''(LONG) - input Not used.
 
'''pbInData'''(PBYTE) - input Not used.
 
'''plOutCount'''(PLONG) - output The number of bytes of data pointed to by ''pbOutData.''
 
On return, this is updated to the number of bytes returned.
 
'''pbOutData'''(PBYTE) - output The address of a buffer that will contain a ULONG variable specifying the number of capabilities.
 
On return, this buffer contains a ULONG variable that specifies the number of capabilities that the driver supports, immediately followed by an array of [[DRIVERCAPS]] structures.
 
'''Note:'''This allows a driver to export multiple capabilities (each, in turn, gets its own page in the System icon).
 
'''rc'''(LONG) - returns Return Code.
 
Returns NO_ERROR.
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST ===
'''Simulation support:'''
 
This function is optional for display drivers and has no simulation support .
 
Description:
 
''GreEscape DEVESC_QUERYDRIVERCAPSLIST''fills the ''pValueList, pCurrentValue,''and ''pDefaultValue''in the [[DRIVERCAPS]] data structure. The members must be 0 padded up to the ''ulValueMemberSize''in the ''pValueList.''
 
There are three kind of data types that we are supporting at the present time-boolean, aggregate of int values, and aggregate of strings. These data types are defined as follows:
<pre>  #define  CAPSTYPE_BOOLEAN                  1L
  #define  CAPSTYPE_AGGREGATE_INT        2L
  #define  CAPSTYPE_AGGREGATE_STRING    3L</pre>
 
<pre>#define INCL_GRE_DEVICE
#include &lt;GRADD.h&gt;
 
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_QUERYDRIVERCAPSLIST */
LONG    lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;  /*  Not used. */
LONG    rc;          /*  Return Code. */
 
rc = GreEscape(hdc, lCode, lInCount, pbInData,
      plOutCount, pbOutData);</pre>
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST - Syntax ===
 
'''Simulation support:'''
 
This function is optional for display drivers and has no simulation support .
 
Description:
 
''GreEscape DEVESC_QUERYDRIVERCAPSLIST''fills the ''pValueList, pCurrentValue,''and ''pDefaultValue''in the [[DRIVERCAPS]] data structure. The members must be 0 padded up to the ''ulValueMemberSize''in the ''pValueList.''
 
There are three kind of data types that we are supporting at the present time-boolean, aggregate of int values, and aggregate of strings. These data types are defined as follows:
 
<pre>  #define  CAPSTYPE_BOOLEAN                  1L
  #define  CAPSTYPE_AGGREGATE_INT        2L
  #define  CAPSTYPE_AGGREGATE_STRING    3L</pre>
<br /><br />
 
<pre>#define INCL_GRE_DEVICE
#include &lt;GRADD.h&gt;
 
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_QUERYDRIVERCAPSLIST */
LONG    lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;  /*  Not used. */
LONG    rc;          /*  Return Code. */
 
rc = GreEscape(hdc, lCode, lInCount, pbInData,
      plOutCount, pbOutData);</pre>
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - hdc ===
 
'''hdc'''(HDC) - input A handle to the device context.
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - lCode ===
 
'''lCode'''(LONG) - input DEVESC_QUERYDRIVERCAPSLIST
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - lInCount ===
 
'''lInCount'''(LONG) - input Number of bytes pointed to by ''pbInData.''
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - pbInData ===
 
'''pbInData'''(PBYTE) - input Pointer to a [[DRIVERCAPS]] data structure.
 
The [[DRIVERCAPS]]data structure specifies the driver capability to query. Storage is already allocated for ''pValueList, pCurrentValue,''and ''pDefaultValue.''
 
When ''ulCapsType''= CAPSTYPE_BOOLEAN, the driver does not have to fill ''pValueList.''
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - plOutCount ===
 
'''plOutCount'''(PLONG) - output Not used.
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - pbOutData ===
 
'''pbOutData'''(PBYTE) - output Not used.
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST Return Value - rc ===
 
'''rc'''(LONG) - returns Return Code.
 
Returns NO_ERROR.
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST - Parameters ===
 
'''hdc'''(HDC) - input A handle to the device context.
 
'''lCode'''(LONG) - input DEVESC_QUERYDRIVERCAPSLIST
 
'''lInCount'''(LONG) - input Number of bytes pointed to by ''pbInData.''
 
'''pbInData'''(PBYTE) - input Pointer to a [[DRIVERCAPS]]data structure.
 
The [[DRIVERCAPS]] data structure specifies the driver capability to query. Storage is already allocated for ''pValueList, pCurrentValue,''and ''pDefaultValue.''
 
When ''ulCapsType''= CAPSTYPE_BOOLEAN, the driver does not have to fill ''pValueList.''
 
'''plOutCount'''(PLONG) - output Not used.
 
'''pbOutData'''(PBYTE) - output Not used.
 
'''rc'''(LONG) - returns Return Code.
 
Returns NO_ERROR.
 
=== GreEscape DEVESC_QUERYDRIVERCAPSLIST - Topics ===
 
Select an item:
 
<pre>Syntax
Parameters
Returns
Glossary </pre>
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE ===
 
 
-----
 
Select an item:
 
<pre>Syntax
Parameters
Returns
Glossary </pre>
 
-----
 
'''Simulation support:'''
 
This function is optional for display drivers and has no simulation support .
 
Description:
 
''GreEscape DEVESC_SETDRIVERCAPSVALUE''will set the value that user has selected. The new value is specified in ''pCurrentValue.''
 
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 and aggregate type is represented by a listbox. The capability description appears as the title for that control.
 
If the driver is going to support these capabilities in multiple languages, it must get the capability description (szCapsDesc) and capability aggreate strings, if applicable, from a resource module that contains already- translated strings.
 
<pre>#define INCL_GRE_DEVICE
#include &lt;GRADD.h&gt;
 
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_SETDRIVERCAPSVALUE */
LONG    lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;  /*  Not used. */
LONG    rc;          /*  Return Code. */
 
rc = GreEscape(hdc, lCode, lInCount, pbInData,
      plOutCount, pbOutData);</pre>
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE - Syntax ===
 
'''Simulation support:'''
 
This function is optional for display drivers and has no simulation support .
 
Description:
 
''GreEscape DEVESC_SETDRIVERCAPSVALUE''will set the value that user has selected. The new value is specified in ''pCurrentValue.''
 
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 and aggregate type is represented by a listbox. The capability description appears as the title for that control.
 
If the driver is going to support these capabilities in multiple languages, it must get the capability description (szCapsDesc) and capability aggreate strings, if applicable, from a resource module that contains already- translated strings.
 
<pre>#define INCL_GRE_DEVICE
#include &lt;GRADD.h&gt;
 
HDC      hdc;        /*  A handle to the device context. */
LONG    lCode;      /*  DEVESC_SETDRIVERCAPSVALUE */
LONG    lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;  /*  Not used. */
LONG    rc;          /*  Return Code. */
 
rc = GreEscape(hdc, lCode, lInCount, pbInData,
      plOutCount, pbOutData);</pre>
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - hdc ===
 
'''hdc'''(HDC) - input A handle to the device context.
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - lCode ===
 
'''lCode'''(LONG) - input DEVESC_SETDRIVERCAPSVALUE
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - lInCount ===
 
'''lInCount'''(LONG) - input Number of bytes pointed to by ''pbInData.''
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - pbInData ===
 
'''pbInData'''(PBYTE) - input Pointer to a [[DRIVERCAPS]]data structure.
 
The DRIVERCAPS data structure specifies the driver capability to set.
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - plOutCount ===
 
'''plOutCount'''(PLONG) - output Not used.
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - pbOutData ===
 
'''pbOutData'''(PBYTE) - output Not used.
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE Return Value - rc ===
 
'''rc'''(LONG) - returns Return Code.
 
Returns NO_ERROR.
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE - Parameters ===
 
'''hdc'''(HDC) - input A handle to the device context.
 
'''lCode'''(LONG) - input DEVESC_SETDRIVERCAPSVALUE
 
'''lInCount'''(LONG) - input Number of bytes pointed to by ''pbInData.''
 
'''pbInData'''(PBYTE) - input Pointer to a [[DRIVERCAPS]]data structure.
 
The DRIVERCAPS data structure specifies the driver capability to set.
 
'''plOutCount'''(PLONG) - output Not used.
 
'''pbOutData'''(PBYTE) - output Not used.
 
'''rc'''(LONG) - returns Return Code.
 
Returns NO_ERROR.
 
=== GreEscape DEVESC_SETDRIVERCAPSVALUE - Topics ===
 
Select an item:
 
<pre>Syntax
Parameters
Returns
Glossary </pre>
 
=== How to Write to Windows Profiling Files in OS/2 ===
 
Some display drivers must perform windows profiling (updates to SYSTEM.INI or WIN.INI file). The following sample source file can be included in display driver source and executed at ring 3 only.
 
<pre>    typedef ULONG APIENTRY WPF1(VOID);
    typedef WPF1 *PWPF1;
    typedef BOOL  APIENTRY WPF2(ULONG, BOOL);
    typedef WPF2 *PWPF2;
    typedef BOOL  APIENTRY WPF3(ULONG, PSZ);
    typedef WPF3 *PWPF3;
    BOOL UpdateWindowsIniFiles(VOID)
    {
      BOOL    result = TRUE;
      BOOL    res1;
      ULONG  hWpf;
      CHAR    szUpdateString[256];
      PWPF1  pWpfOpenProfileList;
      PWPF2  pWpfCloseProfileList;
      PWPF3  pWpfWriteProfileListLine;
      HMODULE hMod;
      if (DosLoadModule(NULL, 0, &quot;WINPRF&quot;, &amp;hMod) ||
          DosQueryProcAddr(hMod, 0, &quot;WPFOPENPROFILELIST&quot;, (PFN *)&amp;pWpfOpenProfileList) ||
          DosQueryProcAddr(hMod, 0, &quot;WPFCLOSEPROFILELIST&quot;, (PFN *)&amp;pWpfCloseProfileList) ||
          DosQueryProcAddr(hMod, 0, &quot;WPFWRITEPROFILELISTLINE&quot;, (PFN *)&amp;pWpfWriteProfileListLine))
      {
          return FALSE;
      }
 
      // Open the profile handler.
      if (hWpf = (*pWpfOpenProfileList)())
      {
      /*
      ** szUpdateString has the following format
      **
      ** &lt;profile name&gt;  &lt;section&gt;  &lt;keyword&gt;  [value]
      **
      ** ex.  &quot;system.ini boot sdisplay.drv wd3116sl.drv&quot;  will insert the line
      **    sdisplay.drv=wd3116sl.drv in the boot section of system.ini
      **
      ** if [value] is omitted, the &lt;keyword&gt; is deleted from the section
      */
          if (!(*pWpfWriteProfileListLine)(hWpf, szUpdateString))
          {
            result = FALSE;          // Win Ini update failed!
          }
 
          res1 = (*pWpfCloseProfileList)(hWpf, result); // Close or abort the updates
          result &amp;= res1;
      }
      else
      {
          result = FALSE;
      }
 
      return result;
  }</pre>
 
=== Most Frequently Asked Video Configuration Questions and Answers ===
 
How does the user configure monitor, resolution, and refresh in OS/2? The user interface for video configuration is located in the System object member of the System Setup folder, which can be brought up by clicking the right mouse button on the desktop area.
 
Why use the System Icon monitor configuration vs. custom configuration? System Icon provides a large pool of legacy monitors and a consistent device-independent resolution/refresh/monitor configuration. The OS/2 Warp, Version 3.0 System Icon configuration support can be installed on OS/2 2.1 and will be supported on future versions of OS/2. The Sysem Icon's initial configuration reflects the configuration that was performed by the BIOS.
 
What other video configuration features are supported by the System Icon? VIDEOCFG, the binary module that owns the System's video pages, also has a generic capability interface. This generic interface allows for expansion of configuration if a vendor needs additional pages, such as a page for font selection, orientation selection, or any other discrete value configuration.
 
What is needed to get the System Icon to display the monitor list? The mode table exported by the PMI subsystem has to have at least one graphics mode with a [MonitorModeInfo] section. The presence of this graphics mode indicates that the base video system can take into account monitor capabilities.
 
What is needed to get the System Icon to display the Monitor size button? The PMI subsystem mode table has to have at least one mode with startup values for ScreenLeftEdge, ScreenRightEdge and so forth. The support for monitor sizing is disabled in the DDK version of the VIDEOCFG, but a refresh of the VIDEOCFG is available on request.
 
How are monitor capabilities described in OS/2? OS/2 has a pre-built database of about 300 monitors. The list is ordered alphabetically by monitor manufacturer name. Each monitor is described in terms of the resolutions it supports and the maximum refresh value for each resolution. The syntax does not allow for optimum or multiple timing choices. The database is a flat file, MONITOR.DIF, that can be modified. VIDEOCFG.DLL exports APIs that allow for monitor database queries and expansion.
 
Where is the current configuration stored? Current monitor configuration capabilities, as well as the current refresh for each mode and screen sizing information, are stored in a flat file, VIDEO.CFG, whose syntax is very similar to PMI. The content can be queried or changed by calling VIDEOCFG.DLL's configuration APIs.
 
Where does the default monitor come from? SVGA.EXE (SVGAOEM.EXE) formats the very first VIDEO.CFG that communicates to the configurator the current refresh configuration, as left by the BIOS. We have assembled per-adapter information that lets us understand how each vendor records its refresh configuration. These values are formatted into the VIDEO.CFG. If SVGA.EXE does not format the file, the very first monitor from the MONITOR.DIF database is chosen. Otherwise, the original (default) VIDEO.CFG monitor capabilities are added to the MONITOR.DIF so that the customer can go back to the BIOS-configured monitor capabilities.
 
Is there DDC support? SVGA.EXE (and SVGAOEM.EXE) and the configuration do support the DDC1 standard. SVGA.EXE formats the VIDEO.CFG with the DDC1- queried capabilities and marks the monitor as DDC. This automatically excludes any monitor from the database. As a result, the customer is not offered monitor selection page, but does have refresh choices per mode on Page 1. In order to change from a DDC monitor to a non-DDC monitor, the customer has to do one of the following:
 
�Change the current VIDEO.CFG's monitor name from the &quot;DDC&quot; keyword to anything else
 
�Issue a SetCurrentCFG API into the VIDEOCFG.DLL and specify a name other than DDC for the current monitor's name
 
�Remove VIDEO.CFG will also enable the monitor selection.
 
Where do the refresh values in the refresh listbox on Page 1 come from? The resolutions offered represent the resolutions returned by the display driver that are also available from the PMI subsystem. The match is done on horizontal and vertical resolution and color depth (NOT pixel depth).
 
If at least one of the resolutions in this group has a [MonitorModeInfo] section, the refresh box will be offered. The content of the refresh box is tied into the currently selected resolution. The refresh values are those found in the VIDEOPMI's mode query list that are within the range of the currently selected monitor. The highlight (default) is on the highest value in the listbox (unless overridden by the customer). Changing the selected monitor affects the range and elicits immediate change if the range has been diminished. If the range is increased, the configured refresh remains the same and has to be increased by the customer, if so desired.
 
What does &quot;DEFAULT&quot; entry in the refresh listbox mean? If the very first VIDEO.CFG has 0xFF for the resolutions vertical refresh, the entry &quot;DEFAULT &quot; will be highlighted in the refresh box. The actual set mode will also pass the 0xFF in the mode structure, so that the selection of the refresh is entirely up to the PMI subsystem (PMI file or imported binary that handles the setmode function). The &quot;DEFAULT&quot; can be used in places where the startup configuration of an adapter is not known at first, but the base video subsystem has ways of setting appropriate (non-harmful) refresh values. If the SVGADATA.PMI contains [MonitorModeInfo] sections with refresh entries other than 0xFF, the refresh listbox will also contain those, but the customer has to override the default highlight. As soon as an actual (non-DDC) monitor is chosen, the DEFAULT will no longer be a valid option in the refresh listbox. Going back to the original monitor &quot; DEFAULT&quot; would put the &quot;DEFAULT&quot; refresh entry into the listbox.
 
How could a vendor be noncommittal about the refresh values it supports? The vendor could provide a single [MonitorModeInfo] section that represent its highest refresh capability. This information will be filtered against the monitor's capabilities (the monitor's range is always the highest refresh entry), which effectively notifies the customer that only one ( highest capability of the monitor) refresh can be offered. The vendor could specify its [MonitorModeInfo] entry to be so high that no monitor is discriminated against. However, we strongly recommend that the monitor's refresh value passed into the setmode be respected and set as close as possible. There is the potential for some legal problems if the values requested are not within a margin. Regulations, such as ISO 9000 specifications, are established and enforced by countries where our product is sold, not by IBM.
 
Could the OS/2 configuration serve to configure BIOS/WIN-OS2? If the setmode function servicing the requested refresh also sets configuration registers used by the BIOS / WIN-OS2 driver before or after it changes the clock registers, this will affect non-OS2 mode sets as well. It is not recommended that non-OS2 applications read the VIDEO.CFG, as its format is open to change. The GetCurrentCFG and GetCurrentDesktopMode APIs are exported by the VIDEOCFG.DLL for OS/2 applications so that the current monitor capabilities and current resolution/refresh/monitor sizing values can be read.
 
How can new monitors be added to the list? A new monitor can be added by using the AddMonitorData API exported by the VIDEOCFG or by manually editing the MONITOR.DIF file. A PRIVATE.DIF file with new monitor entries will accomplish the same thing while keeping MONITOR.DIF as read-only.
 
Are customers configuring their monitors or the refresh in OS/2? The answer is both, if the vendor's PMI file has more than one [MonitorModeInfo] section per mode. In other words, after selecting the monitor, the customer still has multiple refresh choices if the PMI file had multiple refresh entries for the current mode below the monitor's end-of-range. Some vendors have utilities that are geared towards monitor configuration (a somewhat limited monitor list is usually the problem) and some are geared towards the refresh value setting (most users have a hard time understanding what the refresh means). We have a two-pronged configuration which, in the absence of DDC, lets the user choose a monitor as a way of limiting the highest refresh, and still select one of the more standard timings for a given resolution.
 
How can the System Icon refresh support be installed on OS/2 2.1? In order to install VIDEOCFG on OS/2 2.x, the VCFGINST.EXE utility provided in the video\bin directory should be executed first. This utility installs WPVIDSYS.DLL, which subclassed WPSYSTEM class to VIDEOCFG.DLL. Both WPVIDSYS.DLL and VIDEOCFG.DLL should be copied into the LIBPATH and will become active upon a reboot following the VCFGINST.EXE. There used to be a version of VIDEOCFG for OS/2 2.x called VIDEOCFG.206. This version is now consolidated into VIDEOCFG.DLL, so a single library can be installed on both versions of the operating system.
 
You can also download the S3_864.ZIP from CompuServe, OS2SUP library 23 ( search for 86C84 and UPGRADE keywords). This package supports S3 864/964 and 764 and showcases the installation on OS/2 2.x. The 764 driver also uses VIDEOPMI's software interrupt services.
 
=== OS/2 Version Compatibility Considerations ===


==OS/2 Version Compatibility Considerations==
This version of the GRADD Reference was written to support OS/2 Warp on the Intel hardware platform.
This version of the GRADD Reference was written to support OS/2 Warp on the Intel hardware platform.
=== Syntax Conventions ===
The programming statements in this book use the C language syntax. Support for code written in C is provided in header files identified by the filename extension &quot;.h&quot;. Assembler support is provided in the include files identified by the filename extension &quot;.INC&quot;.
=== Parameter Names ===
Parameter names are constructed to show the data type of the parameter and to indicate its use:
�A lowercase prefix of one or more characters that indicates the data type. <br />�An optional qualifier starting with an uppercase letter.
Where possible, standard names have been used to describe parameters. Where multiple-word qualifiers are used, the order of the words is not significant.
For example:
<pre>    hdc          /* device context handle        */
    pszFilename  /* pointer to a character string */</pre>
The following standard base tags and their associated type names are defined:
<pre>
|Tag      |Data Type |Description
|----------+----------+--------------------------------------------------|
|f        |BOOL      |Flag or Boolean variable. The qualifier describes |
|          |          |the condition associated with the flag when it is |
|          |          |TRUE. For example, fSuccess is TRUE if successful |
|          |          |and FALSE if not; whereas fError is TRUE if an    |
|          |          |error occurred and FALSE if no error occurred. For|
|          |          |objects of type BOOL, the value 0 implies FALSE  |
|          |          |and any nonzero value implies TRUE.              |
|----------+----------+--------------------------------------------------|
|ch        |CHAR      |Signed eight-bit quantity; a character.          |
|----------+----------+--------------------------------------------------|
|s        |SHORT    |Signed 16-bit quantity; a SHORT. This is often    |
|          |          |used in place of us when it does not matter      |
|          |          |whether the value is signed or unsigned.          |
|----------+----------+--------------------------------------------------|
|l        |LONG      |Signed 32-bit quantity; a LONG. This is often used|
|          |          |in place of ul when it does not matter whether the|
|          |          |value is signed or unsigned.                      |
|----------+----------+--------------------------------------------------|
|uch      |UCHAR    |Unsigned eight-bit quantity; a byte. Same as b.  |
|----------+----------+--------------------------------------------------|
|us        |USHORT    |Unsigned 16-bit quantity.                        |
|----------+----------+--------------------------------------------------|
|ul        |ULONG    |Unsigned 32-bit quantity.                        |
|----------+----------+--------------------------------------------------|
|b        |BYTE      |Unsigned eight-bit quantity; a byte. Same as uch. |
|----------+----------+--------------------------------------------------|
|sz        |CHAR[ ]  |NULL-terminated string of characters.            |
|----------+----------+--------------------------------------------------|
|fb        |UCHAR    |Byte of flags, that is, an array of flags packed  |
|          |          |in a BYTE.                                        |
|----------+----------+--------------------------------------------------|
|fs        |USHORT    |SHORT of flags, that is, an array of flags packed |
|          |          |in a USHORT.                                      |
|----------+----------+--------------------------------------------------|
|fl        |ULONG    |LONG of flags, that is, an array of flags packed  |
|          |          |in a ULONG. The three preceding types are used    |
|          |          |when more than one flag is combined into a byte,  |
|          |          |SHORT or LONG. Typically, the values are combined |
|          |          |with the OR operator and are always unsigned.    |
|----------+----------+--------------------------------------------------|
|r        |REAL      |Real number, single precision 32-bits.            |
|----------+----------+--------------------------------------------------|
|rd        |DOUBLE    |Real number, double precision 64-bits.            |
|----------+----------+--------------------------------------------------|
|pfn      |          |Pointer to a function.                            |
|----------+----------+--------------------------------------------------|
|x        |          |X-coordinate.                                    |
|----------+----------+--------------------------------------------------|
|y        |          |Y-coordinate.
</pre>
The following standard prefixes are also defined:
<pre>
|Prefix    |Description
|----------+--------------------------------------------------|
|p        |32-bit pointer for an 80386 microprocessor. For  |
|          |example, pch is a pointer to a character.        |
|----------+--------------------------------------------------|
|a        |Array. For example, ach is an array of characters.|
|----------+--------------------------------------------------|
|i        |Index to an array. For example, an ich is used to |
|          |index an ach.                                    |
|----------+--------------------------------------------------|
|c        |Count. For example, cch is a count of characters. |
|----------+--------------------------------------------------|
|d        |Delta or difference between instances of a type.  |
|          |For example, dx is the difference between two    |
|          |values of x.                                      |
|----------+--------------------------------------------------|
|h        |Handle. A value that uniquely identifies an object|
|          |but cannot directly be used to access it. For    |
|          |example, hps is a PS handle.                      |
|----------+--------------------------------------------------|
|mp        |Mapping array. This prefix is always followed by  |
|          |two base types rather than one and represents the |
|          |most general case of an array. Mathematically, an |
|          |array is a function mapping the index to the value|
|          |stored in the array. The prefix mp is an          |
|          |abbreviation of map. In the construct mpab, a is  |
|          |the type  of  the  index  and  b  is  the  type  of  the      |
|          |value stored  in  the  array .  In  most  cases ,  the  only |
|          |type that  is  important  is  the  type  of  the  value .    |
|          |The index  is  usually  an  integer  with  no  other      |
|          |meaning (the a prefix is  used  in  this  instance ) .    |
|----------+-------------------- ------------------------------|
| off        | Offset .  Generally  used  as  an  offset  within  a  data  |
|            | structure .  The  actual  address  of  the  element        |
|            | within  the  data  structure  is  derived  by  adding  an  |
|            | offset  to  a  pointer ,  which  points  to  the  beginning |
|            | of  the  data  structure .  Normally ,  OFF  is  a  byte      |
|            | offset .  For  example :  pfoo  =  ( FOO  * ) ( ( BYTE          |
|            | * ) pfooBase  +  0fff00 )                                  |
| ---------- + ---------- ---------- ---------- ---------- ---------- |
| id          | Identifier .  This  is  generally  used  for  values  that |
|            | identify  some  object .  Usually  the  association  of    |
|            | the  ID  value  and  the  object  are  established  by  the |
|            | programmer .  For  example ,  all  windows  are            |
|            | identified  by  their  Window  ID ,  which  can  be  set    |
|            | and  queried  by  the  programmer .                      |
|---------- + ---------- ---------- ---------- --------------------|
| cmd        |Command. Used for command values, typically as      |
|            |function parameters.</pre>
Some parameters are used in pairs; the qualifiers that are used reflect the relationship between the two variables. For example:
<pre>
|Parameter  |Description                                                        |
|------------+-------------------------------------------------------------------|
|First/Last  |First and last elements in a set. These are typically used with    |
|            |indexes or pointers (pchFirst, pchLast). Both values represent    |
|            |valid values (compare with Min/Max below). For all valid values of |
|            |x: xFirst <= x <= xLast. The use of > with First or < with Last is |
|            |almost always an "off-by-one" error.                              |
|            |For example, to determine whether an ich is within ichFirst and    |
|            |ichLast:    if (ich >= ichFirst && ich <= ichLast)                |
|            |        ...                                                        |
|            |A typical loop:                                                    |
|            |    for (ich = ichFirst; ich <= ichLast; ich++)                    |
|            |        ...                                                        |
|------------+-------------------------------------------------------------------|
|Min/Max    |Similar to First/Last except that Max is not a valid value in the  |
|            |set (Min is a valid value). For all valid values of x in the set:  |
|            |xMin < = x < xMax. The use of &gt; with Min or < = with Max is almost |
|            |always an &quot;off-by-one&quot; error.                                      |
|            |For example, to determine whether an ich is within ichMin and      |
|            |ichMax:    if (ich &gt;= ichMin &amp;&amp; ich < ichMax)                    |
|            |        ...                                                        |
|            |A typical loop:                                                    |
|            |    for (ich = ichMin; ich < /* or != */ ichMax; ich++)            |
|            |        ...                                                        |
|------------+-------------------------------------------------------------------|
|            |The current value (Cur) qualifier can be used with Min and Max when|
|            |Min or Max can change over time (for example, pbStackMaxCur).      |
|------------+-------------------------------------------------------------------|
|Old/New    |Old and new. Typically used for values or states when it is        |
|            |necessary to compare the old and new states of the value.          |
|------------+-------------------------------------------------------------------|
|Next/Prev  |Next and previous. Typically used in situations in which items are |
|            |being enumerated, such as with linked lists.                      |
|------------+-------------------------------------------------------------------|
|Src/Dst    |Source and destination. Typically used in transfer operations.    |
|------------+-------------------------------------------------------------------|
|T          |A temporary value.                                                |
|------------+-------------------------------------------------------------------|
|Save        |A temporary, saved value. Typically used when saving and restoring |
|            |some state.                                                        |
|------------+-------------------------------------------------------------------|
|Cur        |Current value.                                                    |
</pre>
The base types and their prefixes are defined as follows:
<pre>
|Data Type              |Prefix                |
|------------------------+----------------------|
|PSZ                    |psz                  |
|------------------------+----------------------|
|PCH                    |pch                  |
|------------------------+----------------------|
|HAB                    |hab                  |
|------------------------+----------------------|
|HPS                    |hps                  |
|------------------------+----------------------|
|HDC                        | hdc                      |
| ---------- ---------- ---- + ---------- ---------- -- |
| HRGN                      | hrgn                    |
| ---------- ---------- ---- + ---------- ---------- -- |
| HBITMAP                    | hbmp                    |
| ---------- ---------- ---- + ---------- ---------- -- |
| PLONG                      | pl                      |
| ---------- ---------- ---- + ---------- ---------- -- |
| POINTL                    | ptl                      |
| ---------- ---------- ---- + ---------- ---------- -- |
| POINTL                    | pt                      |
| ---------- ---------- ---- + ---------- ---------- -- |
| RECTL                      | rcl                      |
| ---------- ---------- ---- + ---------- ---------- -- |
| RECTL                      | rc                      |
| ---------- ---------- ---- + ---------- ---------- -- |
| HWND                      | hwnd                    |
| ---------- ---------- ---- + ---------- ---------- -- |
| WPOINT                    | wpt                      |
| ---------- ---------- ---- + ---------- ---------- -- |
| WRECT                      | wrc                      |
| ---------- ---------- ---- + ---------- ---------- -- |
| FIXED                      | fx                      |
</pre>
Parameters for defined structures are the defined parameter names. For example:
<pre>
    AREADEFS struct
              {
                    defSet
                    fFlags
                    CodePage
              }AREADEFS
</pre>
System-defined constants and flags are represented as two or more uppercase WORDs or mnemonic abbreviations separated by underscores. For example, SYS_ CONSTANT and SYS_FLAG.
=== Return Values ===
Function-handling routines pass full 32-bit return codes back to the calling function. In MASM, the return code is passed in the EAX Register.
=== Register Content Preservation ===
Registers EAX, ECX, and EDX can be destroyed. All other registers must be preserved.
=== Handles ===
All handles and pointers are 32-bit values.
=== Coordinates ===
All coordinates are passed as signed 32-bit values unless stated otherwise. World, model, and presentation-page space coordinates are restricted to the 28 low-order bits and lie within the range F8000000h through 07FFFFFFh. Device space coordinates are restricted to the 16 low-order bits and lie within the range FFFF0000h through 0000FFFFh.
=== Data Types ===
Proceed to the next section for a description of the data types referenced in this book.
=== ADAPTERINFO ===
The ADAPTERINFO data structure receives information for the current video adapter.
<pre>typedef struct _ADAPTERINFO {
  ULONG      cb;                          /*  Length of the structure. */
  ULONG      ulAdapterID;                  /*  Specifies the adapter by ID. */
  CHAR      szOEMString[MAX_OEM_STRING];  /*  Contains adapter information. */
  CHAR      szDACString[MAX_DAC_STRING];  /*  Contains DAC information. */
  CHAR      szRevision[MAX_VERSION];      /*  Contains version information. */
  ULONG      ulTotalMemory;                /*  Total video memory. */
  ULONG      ulMMIOBaseAddress;            /*  Base address for memory-mapped I/O registers. */
  ULONG      ulPIOBaseAddress;            /*  Base address for I/O ports. */
  BYTE      bBusType;                    /*  Type of bus (PCI, VLB, and so on.) */
  BYTE      bEndian;                      /*  Big Endian or little Endian. */
  USHORT    usDeviceBusID;                /*  Reserved. */
  USHORT    usVendorBusID;                /*  Reserved. */
  USHORT    usSlotID;                    /*  Reserved. */
} ADAPTERINFO;
typedef  ADAPTERINFO  * FAR  * PADAPTERINFO ; </pre>
;Field - cb
'''cb'''(ULONG) Length of the structure.
;Field - ulAdapterID
'''ulAdapterID'''(ULONG) Specifies the adapter by ID.
;Field - szOEMString[MAX_OEM_STRING]
'''szOEMString[MAX_OEM_STRING]'''(CHAR) Contains adapter information.
Valid value is as follows:
MAX_OEM_STRING 128
;Field - szDACString[MAX_DAC_STRING]
'''szDACString[MAX_DAC_STRING]'''(CHAR) Contains DAC information.
Valid value is as follows:
MAX_DAC_STRING 128
;Field - szRevision[MAX_VERSION]
'''szRevision[MAX_VERSION]'''(CHAR) Contains version information.
Valid value is as follows:
MAX_VERSION 128
;Field - ulTotalMemory
'''ulTotalMemory'''(ULONG) Total video memory.
;Field - ulMMIOBaseAddress
'''ulMMIOBaseAddress'''(ULONG) Base address for memory-mapped I/O registers.
;Field - ulPIOBaseAddress
'''ulPIOBaseAddress'''(ULONG) Base address for I/O ports.
;Field - bBusType
'''bBusType'''(BYTE) Type of bus (PCI, VLB, and so on.)
The valid values for this flag are as follows:
:ISA_BUS 0
:VLB_BUS 1
:PCI_BUS 2
:EISA_BUS 3
:PCMCIA_BUS 4
:MCA_BUS 5
;ADAPTERINFO Field - bEndian
'''bEndian'''(BYTE) Big Endian or little Endian.
LITTLE_ENDIAN 0
BIG_ENDIAN 1
;Field - usDeviceBusID
'''usDeviceBusID'''(USHORT) Reserved.
;Field - usVendorBusID
'''usVendorBusID'''(USHORT) Reserved.
;Field - usSlotID
'''usSlotID'''(USHORT) Reserved.
=== APIRET ===
Unsigned integer in the range 0 through 4 294 967 295.
<pre>typedef unsigned long APIRET;</pre>
=== BANKDATA ===
The BANKDATA data structure contains the current mode ID and the bank number.
<pre>
typedef struct _BANKDATA {
  MODEID    miBank;  /*  ID of the current mode. */
  ULONG      ulBank;  /*  Current bank number. */
} BANKDATA;
typedef  BANKDATA  * FAR  * PBANKDATA ; </pre>
;Field - miBank
'''miBank'''(MODEID) ID of the current mode.
;Field - ulBank
'''ulBank'''(ULONG) Current bank number.
=== BITBLTINFO ===
BitBlt information structure. BitBlt information structure, used for the [[GHI_CMD_BITBLT]] and [[VMI_CMD_BITBLT]]. functions.
<pre>typedef struct _BITBLTINFO {
  ULONG        ulLength;      /*  Length of the BITBLTINFO data structure, in bytes. */
  ULONG        ulBltFlags;    /*  Flags for rendering of rasterized data. */
  ULONG        cBlits;        /*  Count of Blts to be performed. */
  ULONG        ulROP;          /*  Raster operation. */
  ULONG        ulMonoBackROP;  /*  Background mix if B_APPLY_BACK_ROP is set. */
  ULONG        ulSrcFGColor;  /*  Monochrome source Foreground color. */
  ULONG        ulSrcBGColor;  /*  Monochrome source Background color and transparent color. */
  ULONG        ulPatFGColor;  /*  Monochrome pattern Foreground color. */
  ULONG        ulPatBGColor;  /*  Monochrome pattern Background color. */
  PBYTE        abColors;      /*  Pointer to color translation table. */
  PBMAPINFO    pSrcBmapInfo;  /*  Pointer to source bit map (BMAPINFO) */
  PBMAPINFO    pDstBmapInfo;  /*  Pointer to destination bit map (BMAPINFO). */
  PBMAPINFO    pPatBmapInfo;  /*  Pointer to pattern bit map (BMAPINFO). */
  PPOINTL      aptlSrcOrg;    /*  Pointer to array of source origin POINTLs. */
  PPOINTL      aptlPatOrg;    /*  Pointer to array of pattern origin POINTLs. */
  PBLTRECT      abrDst;        /*  Pointer to array of Blt rects. */
  PRECTL        prclSrcBounds;  /*  Pointer to source bounding rect of source Blts. */
  PRECTL        prclDstBounds;  /*  Pointer to destination bounding rect of destination Blts. */
} BITBLTINFO;
typedef  BITBLTINFO  * PBITBLTINFO ; </pre>
=== BITBLTINFO Field - ulLength ===
'''ulLength'''(ULONG) Length of the BITBLTINFO data structure, in bytes.
=== BITBLTINFO Field - ulBltFlags ===
'''ulBltFlags'''(ULONG) Flags for rendering of rasterized data.
Miscellaneous flags used by the graphics engine for rendering of rasterized data:
BF_DEFAULT_STATE Blt direction is left to right and top to bottom.
BF_DIR_X_NEGATIVE Blt direction is towards X origin.
BF_DIR_Y_NEGATIVE Blt direction is towards Y origin.
BF_ROP_INCL_SRC ROP includes a source bit map.
BF_ROP_INCL_PAT ROP includes a pattern bit map.
BF_SRC_TRANSPARENT Source transparent involved.
SRC will not change when SRC=BG_COLOR.
BF_DST_TRANSPARENT Destination transparent involved.
DST will not change when DST=BG_COLOR.
BF_PAT_TRANSPARENT Pattern transparent involved.
Pattern not involved when PAT=BG_COLOR.
BF_PAT_SOLID Pattern is solid; all Foreground color.
BF_PAT_HOLLOW Pattern is hollow (empty); no Foreground color.
BF_APPLY_BACK_ROP Treat ROP as Foreground mix and MonoBackROP as Background mix.
BF_SRC_MONOINVERT Zero (0) bits are Foreground on monochrome SRC bit map.
BF_PAT_MONOINVERT Zero (0) bits are Foreground on monochrome PAT bit map.
BF_SR_BITS_EXTERNAL Source bit map bits are in a nondevice-specific format.
BF_LAST_BLT Defines last blit in a banded BitBlit.
BF_SRC_Y_FLIP Source Y coordinates are inverted relative to device origin.
=== BITBLTINFO Field - cBlits ===
'''cBlits'''(ULONG) Count of Blts to be performed.
=== BITBLTINFO Field - ulROP ===
'''ulROP'''(ULONG) Raster operation.
=== BITBLTINFO Field - ulMonoBackROP ===
'''ulMonoBackROP'''(ULONG) Background mix if B_APPLY_BACK_ROP is set.
=== BITBLTINFO Field - ulSrcFGColor ===
'''ulSrcFGColor'''(ULONG) Monochrome source Foreground color.
=== BITBLTINFO Field - ulSrcBGColor ===
'''ulSrcBGColor'''(ULONG) Monochrome source Background color and transparent color.
=== BITBLTINFO Field - ulPatFGColor ===
'''ulPatFGColor'''(ULONG) Monochrome pattern Foreground color.
=== BITBLTINFO Field - ulPatBGColor ===
'''ulPatBGColor'''(ULONG) Monochrome pattern Background color.
=== BITBLTINFO Field - abColors ===
'''abColors'''(PBYTE) Pointer to color translation table.
=== BITBLTINFO Field - pSrcBmapInfo ===
'''pSrcBmapInfo'''([[PBMAPINFO]]) Pointer to source bit map ([[BMAPINFO]])
=== BITBLTINFO Field - pDstBmapInfo ===
'''pDstBmapInfo'''([[PBMAPINFO]]) Pointer to destination bit map (BMAPINFO).
=== BITBLTINFO Field - pPatBmapInfo ===
'''pPatBmapInfo'''([[PBMAPINFO]]) Pointer to pattern bit map (BMAPINFO).
=== BITBLTINFO Field - aptlSrcOrg ===
'''aptlSrcOrg'''([[PPOINTL]]) Pointer to array of source origin [[POINTL]]s.
=== BITBLTINFO Field - aptlPatOrg ===
'''aptlPatOrg'''([[PPOINTL]]) Pointer to array of pattern origin POINTLs.
=== BITBLTINFO Field - abrDst ===
'''abrDst'''([[PBLTRECT]]) Pointer to array of Blt rects.
=== BITBLTINFO Field - prclSrcBounds ===
'''prclSrcBounds'''([[PRECTL]]) Pointer to source bounding rect of source Blts.
=== BITBLTINFO Field - prclDstBounds ===
'''prclDstBounds'''([[PRECTL]]) Pointer to destination bounding rect of destination Blts.
=== BLTRECT ===
Destination rectangle for a bitblt operation.
<pre>typedef struct _BLTRECT {
  ULONG    ulXOrg;  /*  X origin of the destination Blt. */
  ULONG    ulYOrg;  /*  Y origin of the destination Blt. */
  ULONG    ulXExt;  /*  X extent of the BitBlt. */
  ULONG    ulYExt;  /*  Y extent of the BitBlt. */
} BLTRECT;
typedef  BLTRECT  * PBLTRECT ; </pre>
=== BLTRECT Field - ulXOrg ===
'''ulXOrg'''(ULONG) X origin of the destination Blt.
=== BLTRECT Field - ulYOrg ===
'''ulYOrg'''(ULONG) Y origin of the destination Blt.
=== BLTRECT Field - ulXExt ===
'''ulXExt'''(ULONG) X extent of the BitBlt.
=== BLTRECT Field - ulYExt ===
'''ulYExt'''(ULONG) Y extent of the BitBlt.
=== BMAPINFO ===
Device-dependent bit map information structure.
<pre>typedef struct _BMAPINFO {
  ULONG    ulLength;        /*  Length of the BMAPINFO data structure, in bytes. */
  ULONG    ulType;          /*  Description of the Blt. */
  ULONG    ulWidth;        /*  Width in pels of the bit map. */
  ULONG    ulHeight;        /*  Height in pels of the bit map. */
  ULONG    ulBpp;          /*  Number of bits per pel/color depth. */
  ULONG    ulBytesPerLine;  /*  Number of aligned bytes per line. */
  PBYTE    pBits;          /*  Pointer to bit-map bits. */
} BMAPINFO;
typedef  BMAPINFO  * PBMAPINFO ; </pre>
=== BMAPINFO Field - ulLength ===
'''ulLength'''(ULONG) Length of the BMAPINFO data structure, in bytes.
=== BMAPINFO Field - ulType ===
'''ulType'''(ULONG) Description of the Blt.
BMAP_VRAM Bit map is in video memory. <br />BMAP_MEMORY Bit map is in system memory. <br />BMAP_VERTICAL_SCAN Scan lines are in a vertical format instead of the default horizontal format. <br />BMAP_FONT BitBlit is a set of font character glyphs.
=== BMAPINFO Field - ulWidth ===
'''ulWidth'''(ULONG) Width in pels of the bit map.
=== BMAPINFO Field - ulHeight ===
'''ulHeight'''(ULONG) Height in pels of the bit map.
=== BMAPINFO Field - ulBpp ===
'''ulBpp'''(ULONG) Number of bits per pel/color depth.
=== BMAPINFO Field - ulBytesPerLine ===
'''ulBytesPerLine'''(ULONG) Number of aligned bytes per line.
=== BMAPINFO Field - pBits ===
'''pBits'''(PBYTE) Pointer to bit-map bits.
The scanlines of the bit map can be either byte-aligned or word-aligned.
=== BUFFER ===
Data structure inside [[INTCRF]]containing the input/output buffers for the bios call.
<pre>typedef struct _BUFFER {
  BYTE      bBufferType;  /*  Input buffer. */
  BYTE      bReserved;    /*  Reserved */
  BYTE      bSelCRF;      /*  CRF flag for the selector. */
  BYTE      bOffCRF;      /*  CRF flag for the offset. */
  VOID      pAddress;    /*  Linear address of the buffer. */
  ULONG    ulSize;
} BUFFER;
typedef  BUFFER  * PBUFFER ; </pre>
=== BUFFER Field - bBufferType ===
'''bBufferType'''(BYTE) Input buffer.
BUFFER_NONE 0
INPUT_BUFFER 1
OUTPUT_BUFFER 2
=== BUFFER Field - bReserved ===
'''bReserved'''(BYTE) Reserved
=== BUFFER Field - bSelCRF ===
'''bSelCRF'''(BYTE) CRF flag for the selector.
UlONG index into the CRF.
=== BUFFER Field - bOffCRF ===
'''bOffCRF'''(BYTE) CRF flag for the offset.
ULONG index into the CRF.
=== BUFFER Field - pAddress ===
'''pAddress'''Linear address of the buffer.
=== BUFFER Field - ulSize ===
'''ulSize'''(ULONG)
=== CAPSINFO ===
GRADD capability information.
<pre>typedef struct _CAPSINFO
{
  ULONG    ulLength;            /*  Size of the CAPSINFO data structure, in bytes. */
  PSZ      pszFunctionClassID;  /*  Name describing function set. */
  ULONG    ulFCFlags;          /*  Function class specific flags. */
} CAPSINFO;
typedef  CAPSINFO  * PCAPSINFO ; </pre>
=== CAPSINFO Field - ulLength ===
'''ulLength'''(ULONG) Size of the CAPSINFO data structure, in bytes.
=== CAPSINFO Field - pszFunctionClassID ===
'''pszFunctionClassID'''(PSZ) Name describing the function set.
A GRADD supporting the base function set should return pszFunctionClassID pointing to the string &quot;Base Function.&quot;
The following definition is provided:
#define BASE_FUNCTION_CLASS &quot;Base Function&quot;
=== CAPSINFO Field - ulFCFlags ===
'''ULONG'''(PVOID) Function class specific flags.
For the base function class, the following flags are defined:
#define GC_SEND_MEM_TO_MEM 0x00000001 /* Invoke GRADD for bitblts and lines even when hardware display memory is not used. Normally such cases are not sent to a GRADD since the hardware is unlikely to provide acceleration for system memory bitmaps. */ <br />#define TEXTBLT_DOWNLOADABLE 0x00002000 /* Downloadable fonts supported. */ <br />#define TEXTBLT_CLIPABLE 0x00004000 /* Clipable fonts. */ <br />#define TEXTBLT_DS_DEVICE_FONTS 0x00008000 /* Device supports hardware fonts. */ <br />#define DS_SIMPLE_LINES 0x00800000 /* GRADD handles LINEINFO2. */
=== CHAININFO ===
Information returned to callers of the [[VMI_CMD_QUERYCHAININFO]]function.
<pre>typedef struct _CHAININFO {
  CID            cid;            /*  GRADD chain ID. */
  PSZ            pszChainName;    /*  GRADD chain name. */
  PFNHWENTRY    pChainHWEntry;  /*  Entry point for this chain. */
  PGRADDINFO    pGraddList;      /*  List of GRADDs in this chain. */
  CHAININFO      pNextChainInfo;  /*  Pointer to next GRADD in this chain. */
} CHAININFO;
typedef  CHAININFO  * PCHAININFO ; </pre>
=== CHAININFO Field - cid ===
'''cid'''(CID) GRADD chain ID.
=== CHAININFO Field - pszChainName ===
'''pszChainName'''(PSZ) GRADD chain name.
=== CHAININFO Field - pChainHWEntry ===
'''pChainHWEntry'''(PFNHWENTRY) Entry point for this chain.
=== CHAININFO Field - pGraddList ===
'''pGraddList'''([[PGRADDINFO]]) List of GRADDs in this chain.
=== CHAININFO Field - pNextChainInfo ===
'''pNextChainInfo'''(CHAININFO) Pointer to next GRADD in this chain.
=== CLUTDATA ===
The CLUTDATA data structure receives information for the number of [[RGB]] array entries.
<pre>typedef struct _CLUTDATA {
  ULONG      ulRGBCount;  /*  Number of aRGB entries that follow. */
  ULONG      ulRGBStart;  /*  Start index for RGB triplets. */
  SVGARGB    aRGB[1];    /*  Start of SVGARGB; one entry is allocated. */
} CLUTDATA;
typedef  CLUTDATA  * FAR  * PCLUTDATA ; </pre>
=== CLUTDATA Field - ulRGBCount ===
'''ulRGBCount'''(ULONG) Number of aRGB entries that follow.
=== CLUTDATA Field - ulRGBStart ===
'''ulRGBStart'''(ULONG) Start index for [[RGB]] triplets.
=== CLUTDATA Field - aRGB[1] ===
'''aRGB[1]'''([[SVGARGB]]) Start of [[SVGARGB]]; one entry is allocated.
=== CODECINFO ===
Determines whether data is to be compressed or decompressed.
<pre>typedef struct _CODECINFO {
  ULONG      ulLength;      /*  Size of the CODECINFO data structure, in bytes. */
  FOURCC    fccCodecType;  /*  Describes compression type; 'RAW' if uncompressed. */
  ULONG      ulCodecCaps;  /*  Flag indicating CODEC capabilities. */
} CODECINFO;
typedef  CODECINFO  * PCODECINFO ; </pre>
=== CODECINFO Field - ulLength ===
'''ulLength'''(ULONG) Size of the CODECINFO data structure, in bytes.
=== CODECINFO Field - fccCodecType ===
'''fccCodecType'''(FOURCC) Describes compression type; 'RAW' if uncompressed.
The FOURCC flags have the following values:
CODEC_ULTIMOTION &quot;ULTI&quot;
CODEC_INDEO21 &quot;RT21&quot;
CODEC_INDEO31 &quot;IV31&quot;
CODEC_MPEG1 &quot;MPG1&quot;
CODEC_MPEG2 &quot;MPG2&quot;
CODEC_MJPEG &quot;MJPG&quot;
=== CODECINFO Field - ulCodecCaps ===
'''ulCodecCaps'''(ULONG) Flag indicating CODEC capabilities.
The following values are valid:
CODEC_ACCEL_STRETCHBLT 0x0002; hardware stretch
CODEC_ACCEL_BLTCOPROC 0x0002; hardware Blt
CODEC_ACCEL_DECOMP 0x0004; has hardware decompression
CODEC_ACCEL_COMP 0x0008; has hardware compression
=== COLORINFO ===
Color formats for source and destination data, organized in order of preference from the driver's perspective. This data structure is required in any driver supporting EnDIVE.
<pre>typedef struct _COLORINFO {
  ULONG      ulLength;          /*  Size of the COLORINFO data structure, in bytes. */
  FOURCC    fccColorEncoding;  /*  Field containing a name for the color space. */
} COLORINFO;
typedef  COLORINFO  * PCOLORINFO ; </pre>
=== COLORINFO Field - ulLength ===
'''ulLength'''(ULONG) Size of the COLORINFO data structure, in bytes.
=== COLORINFO Field - fccColorEncoding ===
'''fccColorEncoding'''(FOURCC) Field containing a name for the color space.
The FOURCC represents a name (for example, RGB8, Y24, and so on). The bits per pixel and data layout of the color space is implied by the name.
This field can have the following values:
FOURCC(ch0,ch1,ch2,ch3)
<pre>    ((ULONG)(BYTE)(ch0) | ((ULONG)(BYTE)(ch1) <<8) | \
    ((ULONG)(BYTE)(CH2)<<16) | ((ULONG)(BYTE)(CH3)<<24))</pre>
FOURCC_LUT8 FOURCC('L','U','T','8') 8-bit palettized color space
FOURCC_R565 FOURCC('R','5','6','5') RGB 565
FOURCC_R555 FOURCC('R','5','5','5') RGB 555
FOURCC_R666 FOURCC('R','6','6','6') RGB 666
FOURCC_R664 FOURCC('R','6','6','4') RGB 664
FOURCC_RGB3 FOURCC('R','G','B','3') RGB 24 in 3 bytes
FOURCC_BGR3 FOURCC('B','G','R','3') BGR 24 in 3 bytes
FOURCC_RGB4 FOURCC('R','G','B','4') RGB 24 in 4 bytes
FOURCC_BGR4 FOURCC('B','G','R','4') BGR 24 in 4 bytes
FOURCC_Y888 FOURCC('Y','8','8','8') YUV 24
FOURCC_Y411 FOURCC('Y','4','1','1') YUV 411 interleaved 4 x 1 subsampled
FOURCC_Y422 FOURCC('Y','4','2','2') YUV 422 (CCIR601)
FOURCC_YUV9 FOURCC('Y','U','V','9') YUV9
FOURCC_Y2X2 FOURCC('Y','2','X','2') YUV 2 by 2 subsampled multiplane
FOURCC_Y4X4 FOURCC('Y','4','X','4') YUV 4 by 4 subsampled multiplane
=== CUSTPALINFO ===
Custom palette information.
<pre>typedef struct _CUSTPALINFO {
  ULONG    ulLength;      /*  Size of the CUSTPALINFO data structure, in bytes. */
  ULONG    fFlags;        /*  Palette flag. */
  ULONG    ulStartIndex;  /*  Starting palette index. */
  ULONG    ulNumEntries;  /*  Number of palette slots to query or set. */
  PRGB2    pRGBs;        /*  Pointer to the array of RGB values. */
} CUSTPALINFO;
typedef  CUSTPALINFO  * PCUSTPALINFO ; </pre>
=== CUSTPALINFO Field - ulLength ===
'''ulLength'''(ULONG) Size of the CUSTPALINFO data structure, in bytes.
=== CUSTPALINFO Field - fFlags ===
'''fFlags'''(ULONG) Palette flag.
Not used at this time.
=== CUSTPALINFO Field - ulStartIndex ===
'''ulStartIndex'''(ULONG) Starting palette index.
=== CUSTPALINFO Field - ulNumEntries ===
'''ulNumEntries'''(ULONG) Number of palette slots to query or set.
=== CUSTPALINFO Field - pRGBs ===
'''pRGBs'''([[PRGB2]]) Pointer to the array of RGB values.
=== DRIVERCAPS ===
Information structure used for [[GreEscape DEVESC_QUERYDRIVERCAPSLIST]], [[VMI_CMD_USERCAPS]], [[GHI_CMD_USERCAPS]], and [[GreEscape DEVESC_QUERYDRIVERCAPS]]functions.
<pre>typedef struct _DRIVERCAPS {
  ULONG    ulCb;                    /*  Length of the source structure in bytes. */
  CHAR      szCapsDesc[256];        /*  Capability description. */
  CHAR      szHelpFileName[256];    /*  Help file name. */
  ULONG    ulHelpId;                /*  Help resource id. */
  ULONG    ulCapsType;              /*  Defines the returned data type. */
  ULONG    ulValueMemberSize;      /*  Size of each member. */
  ULONG    ulNumValueMember;        /*  Number of members if aggregate. */
  PVOID    pValueList;              /*  Pointer to storage for the members data. */
  PVOID    pCurrentValue;          /*  Pointer to the current selected value descriptions. */
  PVOID    pDefaultValue;          /*  Pointer to the default (reset) value information. */
  BOOL      bDefaultValueSupported;  /*  Return TRUE if driver supports default. */
  BOOL      bStaticCaps;            /*  Return TRUE if need to reboot for the new capability. */
} DRIVERCAPS;
typedef  DRIVERCAPS  * PDRIVERCAPS ; </pre>
=== DRIVERCAPS Field - ulCb ===
'''ulCb'''(ULONG) Length of the source structure in bytes.
=== DRIVERCAPS Field - szCapsDesc[256] ===
'''szCapsDesc[256]'''(CHAR) Capability description.
=== DRIVERCAPS Field - szHelpFileName[256] ===
'''szHelpFileName[256]'''(CHAR) Help file name.
=== DRIVERCAPS Field - ulHelpId ===
'''ulHelpId'''(ULONG) Help resource id.
=== DRIVERCAPS Field - ulCapsType ===
'''ulCapsType'''(ULONG) Defines the returned data type.
This field defines the datatype returned in pValueList, pCurrentValue, and pDefaultValue.
There are three data types currently supported, specified by the ulCapsType field: boolean, aggregate of int values, and aggregate of strings. These data types can be defined as follows:
#define CAPSTYPE_BOOLEAN 1L <br />#define CAPSTYPE_AGGREGATE_INT 2L <br />#define CAPSTYPE_AGGREGATE_STRING 3L
'''Note:'''When ulCapsType is CAPSTYPE_BOOLEAN, the driver does not have to fill in pValueList.
=== DRIVERCAPS Field - ulValueMemberSize ===
'''ulValueMemberSize'''(ULONG) Size of each member.
=== DRIVERCAPS Field - ulNumValueMember ===
'''ulNumValueMember'''(ULONG) Number of members if aggregate.
=== DRIVERCAPS Field - pValueList ===
'''pValueList'''(PVOID) Pointer to storage for the members data.
=== DRIVERCAPS Field - pCurrentValue ===
'''pCurrentValue'''(PVOID) Pointer to the current selected value descriptions.
=== DRIVERCAPS Field - pDefaultValue ===
'''pDefaultValue'''(PVOID) Pointer to the default (reset) value information.
=== DRIVERCAPS Field - bDefaultValueSupported ===
'''bDefaultValueSupported'''(BOOL) Return TRUE if driver supports default.
=== DRIVERCAPS Field - bStaticCaps ===
'''bStaticCaps'''(BOOL) Return TRUE if need to reboot for the new capability.
=== DEVFONTINFO ===
Information structure used for [[GHI_CMD_TEXT]] and [[VMI_CMD_TEXT]] functions. The [[TEXTBLTINFO]] structure includes a pointer to DEVFONTINFO.
<pre>typedef struct _DEVFONTINFO {
  ULONG      ulFntCnt;        /*  Maximum glyphs contained in this font. */
  ULONG      fFontInfo;        /*  Flags used to define DBCS or fixed font. */
  ULONG      ulEngTag;        /*  Renderer tag. */
  ULONG      ulUniqueFntID;    /*  Unique font identifier. */
  ULONG      ulMaxHeight;      /*  Maximum glyph height. */
  ULONG      ulMaxWidth;      /*  Maximum glyph width. */
  PGHBTBL    pghbTbl;          /*  Pointer to high byte table. */
  ULONG      ulHalfWidth;      /*  Reserved. */
  CHAR        szGlyphlist[16];  /*  Reserved */
  ULONG      ulReserved1;      /*  Reserved. */
  ULONG      ulReserved2;      /*  Reserved. */
} DEVFONTINFO;
typedef  DEVFONTINFO  * PDEVFONTINFO ; </pre>
=== DEVFONTINFO Field - ulFntCnt ===
'''ulFntCnt'''(ULONG) Maximum glyphs contained in this font.
=== DEVFONTINFO Field - fFontInfo ===
'''fFontInfo'''(ULONG) Flags used to define DBCS or fixed font.
DFI_FIXED_FONT A predefined number, such as the following:
#define DFI_FIXED_FONT    0x00000001
DFI_DBCS_FONT A predefined number, such as the following:
#define DFI_DBCS_FONT    0x00000002
=== DEVFONTINFO Field - ulEngTag ===
'''ulEngTag'''(ULONG) Renderer tag.
GRETAG A predefined string, such as the following:
#define GRETAG  ('G'+('R'<<8)+('E'<<16)+('_'<<24)) //"GRE_"
WINTAG A predefined string, such as the following:
#define WINTAG  ('W'+('I'<<8)+('N'&<<16)+('_'<<24)) //"WIN_"
=== DEVFONTINFO Field - ulUniqueFntID ===
'''ulUniqueFntID'''(ULONG) Unique font identifier.
=== DEVFONTINFO Field - ulMaxHeight ===
'''ulMaxHeight'''(ULONG) Maximum glyph height.
=== DEVFONTINFO Field - ulMaxWidth ===
'''ulMaxWidth'''(ULONG) Maximum glyph width.
=== DEVFONTINFO Field - pghbTbl ===
'''pghbTbl'''([[PGHBTBL]]) Pointer to high byte table.
=== DEVFONTINFO Field - ulHalfWidth ===
'''ulHalfWidth'''(ULONG) Reserved.
=== DEVFONTINFO Field - szGlyphlist[16] ===
'''szGlyphlist[16]'''(CHAR) Reserved
=== DEVFONTINFO Field - ulReserved1 ===
'''ulReserved1'''(ULONG) Reserved.
=== DEVFONTINFO Field - ulReserved2 ===
'''ulReserved2'''(ULONG) Reserved.
=== FBINFO ===
Information on frame buffer characteristics.
<pre>typedef struct _FBINFO {
  ULONG    ulLength;          /*  Length of FBINFO data structure, in bytes. */
  ULONG    ulFlags;          /*  Specifies the capabilities supported. */
  ULONG    ulBPP;            /*  Screen bits per pel. */
  ULONG    ulXres;            /*  Number of screen X pels. */
  ULONG    ulYres;            /*  Number of screen Y pels. */
  ULONG    ulScanLineBytes;  /*  Number of bytes per scanline. */
  ULONG    fccColorEncoding;  /*  Screen color encoding. */
  ULONG    ulENDIVEDrivers;  /*  Number of EnDIVE drivers installed under GRADD architecture.  */
} FBINFO;
typedef  FBINFO  * PFBINFO ; </pre>
=== FBINFO Field - ulLength ===
'''ulLength'''(ULONG) Length of FBINFO data structure, in bytes.
=== FBINFO Field - ulFlags ===
'''ulFlags'''(ULONG) Specifies the capabilities supported.
This flag has the following value:
FB_SUPPORTSVRAMALLOC 0x0010; supports allocation of on-card memory
=== FBINFO Field - ulBPP ===
'''ulBPP'''(ULONG) Screen bits per pel.
This value may be 32 for some 24-bit color adapters.
=== FBINFO Field - ulXres ===
'''ulXres'''(ULONG) Number of screen X pels.
=== FBINFO Field - ulYres ===
'''ulYres'''(ULONG) Number of screen Y pels.
=== FBINFO Field - ulScanLineBytes ===
'''ulScanLineBytes'''(ULONG) Number of bytes per scanline.
=== FBINFO Field - fccColorEncoding ===
'''fccColorEncoding'''(ULONG) Screen color encoding.
=== FBINFO Field - ulENDIVEDrivers ===
'''ulENDIVEDrivers'''(ULONG) Number of EnDIVE drivers installed under GRADD architecture.
=== FONTDATA ===
The FONTDATA data structure contains font and character information.
<pre>typedef struct _FONTDATA {
  ULONG    ulCharCount;                    /*  Number of characters in the font. */
  ULONG    ulFontHeight;                    /*  Number of scan lines per character. */
  ULONG    ulFontWidth;                    /*  Number of columns per character. */
  BYTE      bFontData[1];  /*  ulCharCount*ulFontHeight entries. */
} FONTDATA;
typedef  FONTDATA  * FAR  * PFONTDATA ; </pre>
=== FONTDATA Field - ulCharCount ===
'''ulCharCount'''(ULONG) Number of characters in the font.
=== FONTDATA Field - ulFontHeight ===
'''ulFontHeight'''(ULONG) Number of scan lines per character.
=== FONTDATA Field - ulFontWidth ===
'''ulFontWidth'''(ULONG) Number of columns per character.
=== FONTDATA Field - bFontData[1] ===
'''bFontData[1]'''(BYTE) ulCharCount*ulFontHeight entries.
=== GDDINITIN ===
Information provided to the GRADD in the GHI_CMD_INIT function.
<pre>typedef struct _GDDINITIN {
  ULONG          ulLength;          /*  Length of the GDDINITIN data structure, in bytes. */
  PFNHWENTRY    pfnChainedHWEntry;  /*  Entry of previous GRADD in chain. */
} GDDINITIN;
typedef  GDDINITIN  * PGDDINITIN ; </pre>
=== GDDINITIN Field - ulLength ===
'''ulLength'''(ULONG) Length of the GDDINITIN data structure, in bytes.
=== GDDINITIN Field - pfnChainedHWEntry ===
'''pfnChainedHWEntry'''(PFNHWENTRY) Entry of previous GRADD in chain.
=== GDDINITOUT ===
Information returned by the GRADD to the caller of the GHI_CMD_INIT function.
<pre>typedef struct _GDDINITOUT {
  ULONG    ulLength;          /*  Length of the GDDINITOUT data structure, in bytes. */
  ULONG    cFunctionClasses;  /*  Number of function classes supported. */
} GDDINITOUT;
typedef  GDDINITOUT  * PGDDINITOUT ; </pre>
=== GDDINITOUT Field - ulLength ===
'''ulLength'''(ULONG) Length of the GDDINITOUT data structure, in bytes.
=== GDDINITOUT Field - cFunctionClasses ===
'''cFunctionClasses'''(ULONG) Number of function classes supported.
In most cases, this value will be equal to one (1). A GRADD can, however, return a zero (0). This is typically done by filter GRADDs that do not want to be entered in the CHAININFO/GRADDINFO information returned to the translation layer via the VMI_CMD_QUERYCHAININFO function. A GRADD can include built-in extensions by returning a value greater than one (1).
=== GDDMODEINFO ===
Mode-specific information provided by the GRADD.
<pre>typedef struct _GDDMODEINFO {
  ULONG    ulLength;          /*  Size of the GDDMODEINFO data structure, in bytes. */
  ULONG    ulModeId;          /*  ID used to make SETMODE request. */
  ULONG    ulBpp;              /*  Number of colors (bpp). */
  ULONG    ulHorizResolution;  /*  Number of horizontal pels. */
  ULONG    ulVertResolution;  /*  Number of vertical scan lines. */
  ULONG    ulRefreshRate;      /*  Refresh rate in Hz. */
  PBYTE    pbVRAMPhys;        /*  Physical address of VRAM. */
  ULONG    ulApertureSize;    /*  Size of VRAM, in bytes. */
  ULONG    ulScanLineSize;    /*  Size of one scan line, in bytes. */
} GDDMODEINFO;
typedef  GDDMODEINFO  * PGDDMODEINFO ; </pre>
=== GDDMODEINFO Field - ulLength ===
'''ulLength'''(ULONG) Size of the GDDMODEINFO data structure, in bytes.
=== GDDMODEINFO Field - ulModeId ===
'''ulModeId'''(ULONG) ID used to make SETMODE request.
=== GDDMODEINFO Field - ulBpp ===
'''ulBpp'''(ULONG) Number of colors (bpp).
=== GDDMODEINFO Field - ulHorizResolution ===
'''ulHorizResolution'''(ULONG) Number of horizontal pels.
=== GDDMODEINFO Field - ulVertResolution ===
'''ulVertResolution'''(ULONG) Number of vertical scan lines.
=== GDDMODEINFO Field - ulRefreshRate ===
'''ulRefreshRate'''(ULONG) Refresh rate in Hz.
This value is zero (0) if Hz not available.
=== GDDMODEINFO Field - pbVRAMPhys ===
'''pbVRAMPhys'''(PBYTE) Physical address of VRAM.
=== GDDMODEINFO Field - ulApertureSize ===
'''ulApertureSize'''(ULONG) Size of VRAM, in bytes.
=== GDDMODEINFO Field - ulScanLineSize ===
'''ulScanLineSize'''(ULONG) Size of one scan line, in bytes.
=== GHBTBL ===
Glyph high byte table.
<pre>typedef struct _GHBTBL {
  PGLBTBL    pglbTbl[1];  /*  Up to 256 entries per table */
} GHBTBL;
typedef  GHBTBL  * PGHBTBL ; </pre>
=== GHBTBL Field - pglbTbl[1] ===
'''pglbTbl[1]'''([[PGLBTBL]]) Up to 256 entries per table
=== GLBTBL ===
Glyph low byte table.
<pre>typedef struct _GLBTBL {
  PGLYPHINFO    pGlyphInfo[1];  /*  Up to 256 entries per table */
} GLBTBL;
typedef  GLBTBL  * PGLBTBL ; </pre>
=== GLBTBL Field - pGlyphInfo[1] ===
'''pGlyphInfo[1]'''([[PGLYPHINFO]]) Up to 256 entries per table
=== GRADDINFO ===
Information describing an individual GRADD.
<pre>typedef struct _GRADDINFO {
  GID            gid;            /*  ID of the GRADD. */
  PSZ            pszGraddName;    /*  Name of this GRADD. */
  PFNHWENTRY      pGraddEntry;    /*  Pointer to HWENTRY for this GRADD. */
  PFNHWENTRY      pChainEntry;    /*  Pointer to HWENTRY for this GRADD chain. */
  ULONG          cModes;          /*  Count of available graphics modes. */
  GDDMODEINFO    pModeInfo;      /*  Pointer to GDDMODEINFO data structure. */
  CAPSINFO        pCapsInfo;      /*  Pointer to CAPSINFO data structure. */
  GRADDINFO      pNextGraddInfo;  /*  Pointer to next GRADDINFO data structure. */
} GRADDINFO;
typedef  GRADDINFO  * PGRADDINFO ; </pre>
=== GRADDINFO Field - gid ===
'''gid'''(GID) ID of the GRADD.
=== GRADDINFO Field - pszGraddName ===
'''pszGraddName'''(PSZ) Name of this GRADD.
=== GRADDINFO Field - pGraddEntry ===
'''pGraddEntry'''(PFNHWENTRY) Pointer to HWENTRY for this GRADD.
=== GRADDINFO Field - pChainEntry ===
'''pChainEntry'''(PFNHWENTRY) Pointer to HWENTRY for this GRADD chain.
=== GRADDINFO Field - cModes ===
'''cModes'''(ULONG) Count of available graphics modes.
This is the count of the available graphics modes supported by this GRADD.
=== GRADDINFO Field - pModeInfo ===
'''pModeInfo'''([[GDDMODEINFO]]) Pointer to GDDMODEINFO data structure.
=== GRADDINFO Field - pCapsInfo ===
'''pCapsInfo'''([[CAPSINFO]]) Pointer to CAPSINFO data structure.
=== GRADDINFO Field - pNextGraddInfo ===
'''pNextGraddInfo'''(GRADDINFO) Pointer to next GRADDINFO data structure.
This points to the next data structure in this GRADD chain.
=== GLYPHINFO ===
Information structure referenced by the pointer to glyph indices ( pGlyphIndicies) in the [[TEXTBLTINFO]]structure.
<pre>typedef struct _GLYPHINFO {
  CHAR        bAspace;  /*  Reserved */
  CHAR        bBspace;  /*  Reserved */
  CHAR        bCspace;  /*  Reserved */
  CHAR        bPad;      /*  Reserved */
  BMAPINFO    bmapinfo;  /*  Destination physical surface descriptions */
} GLYPHINFO;
typedef  GLYPHINFO  * PGLYPHINFO ; </pre>
=== GLYPHINFO Field - bAspace ===
'''bAspace'''(CHAR) Reserved
=== GLYPHINFO Field - bBspace ===
'''bBspace'''(CHAR) Reserved
=== GLYPHINFO Field - bCspace ===
'''bCspace'''(CHAR) Reserved
=== GLYPHINFO Field - bPad ===
'''bPad'''(CHAR) Reserved
=== GLYPHINFO Field - bmapinfo ===
'''bmapinfo'''([[BMAPINFO]]) Destination physical surface descriptions
=== HWBANKIN ===
Information structure used for [[GHI_CMD_TEXT]] and [[VMI_CMD_TEXT]] functions.
<pre>typedef struct _HWBANKIN {
  ULONG    ulLength;  /*  Length of the HWBANKIN data structure, in bytes. */
  ULONG    ulFlags;  /*  Defines for ulFlags. */
  ULONG    ulBank;    /*  Bank number. */
} HWBANKIN;
typedef  HWBANKIN  * PHWBANKIN ; </pre>
=== HWBANKIN Field - ulLength ===
'''ulLength'''(ULONG) Length of the HWBANKIN data structure, in bytes.
=== HWBANKIN Field - ulFlags ===
'''ulFlags'''(ULONG) Defines for ulFlags.
BANK_SET 1
BANK_GET 2
=== HWBANKIN Field - ulBank ===
'''ulBank'''(ULONG) Bank number.
=== HWBANKOUT ===
Information structure used for [[GHI_CMD_TEXT]] and [[VMI_CMD_TEXT]] functions.
<pre>typedef struct _HWBANKOUT {
  ULONG    ulLength;  /*  Length of the HWBANKOUT data structure, in bytes. */
  ULONG    ulBank;    /*  Bank number. */
} HWBANKOUT;
typedef  HWBANKOUT  * PHWBANKOUT ; </pre>
=== HWBANKOUT Field - ulLength ===
'''ulLength'''(ULONG) Length of the HWBANKOUT data structure, in bytes.
=== HWBANKOUT Field - ulBank ===
'''ulBank'''(ULONG) Bank number.
=== HWEVENTIN ===
Input data to the [[GHI_CMD_EVENT]] function.
<pre>typedef struct _HWEVENTIN {
  ULONG    ulLength;    /*  Size of the HWEVENTIN data structure, in bytes. */
  ULONG    ulEvent;    /*  Flag indicating type of event. */
  ULONG    pEventData;  /*  Pointer to event-specific data. */
} HWEVENTIN;
typedef  HWEVENTIN  * PHWEVENTIN ; </pre>
=== HWEVENTIN Field - ulLength ===
'''ulLength'''(ULONG) Size of the HWEVENTIN data structure, in bytes.
=== HWEVENTIN Field - ulEvent ===
'''ulEvent'''(ULONG) Flag indicating type of event.
Valid values are:
EVENT_BACKGROUND <br />EVENT_FOREGROUND <br />EVENT_NEWCHAININFO
=== HWEVENTIN Field - pEventData ===
'''pEventData'''(ULONG) Pointer to event-specific data.
=== HWEXTENSION ===
Input data to the [[GHI_CMD_EXTENSION]] function.
<pre>typedef struct _HWEXTENSION {
  ULONG      ulLength;        /*  Size of the HWEXTENSION data structure, in bytes. */
  ULONG      ulXSubFunction;  /*  Subfunction code. */
  ULONG      cScrChangeRects;  /*  Count of screen rectangles affected by HWEXTENSION. */
  PRECTL    arectlScreen;    /*  Array of screen rectangles affected by HWEXTENSION. */
  ULONG      ulXFlags;        /*  Flag indicating hardware serialization. */
  PVOID      pXP1;            /*  Extension-specific input packet. */
} HWEXTENSION;
typedef  HWEXTENSION  * PHWEXTENSION ; </pre>
=== HWEXTENSION Field - ulLength ===
'''ulLength'''(ULONG) Size of the HWEXTENSION data structure, in bytes.
=== HWEXTENSION Field - ulXSubFunction ===
'''ulXSubFunction'''(ULONG) Subfunction code.
=== HWEXTENSION Field - cScrChangeRects ===
'''cScrChangeRects'''(ULONG) Count of screen rectangles affected by HWEXTENSION.
=== HWEXTENSION Field - arectlScreen ===
'''arectlScreen'''([[PRECTL]]) Array of screen rectangles affected by HWEXTENSION.
=== HWEXTENSION Field - ulXFlags ===
'''ulXFlags'''(ULONG) Flag indicating hardware serialization.
Value for this flag is as follows:
X_REQUESTHW 1
=== HWEXTENSION Field - pXP1 ===
'''pXP1'''(PVOID) Extension-specific input packet.
=== HWMOVEPTRIN ===
Input packet provided to the GRADD in the GHI_CMD_MOVEPTR function.
<pre>typedef struct _HWMOVEPTRIN {
  ULONG      ulLength;  /*  Size of the HWMOVEPTRIN data structure, in bytes. */
  POINTL    ptlPos;    /*  Pointer to video screen coordinate of pointer hot spot. */
} HWMOVEPTRIN;
typedef  HWMOVEPTRIN  * PHWMOVEPTRIN ; </pre>
=== HWMOVEPTRIN Field - ulLength ===
'''ulLength'''(ULONG) Size of the HWMOVEPTRIN data structure, in bytes.
=== HWMOVEPTRIN Field - ptlPos ===
'''ptlPos'''([[POINTL]]) Pointer to video screen coordinate of pointer hot spot.
Video screen coordinates are expected in the ''ptlPos''field.
=== HWPALETTEINFO ===
Input packet provided to the GRADD in the [[GHI_CMD_PALETTE]] function.
<pre>typedef struct _HWPALETTEINFO {
  ULONG    ulLength;      /*  Size of the HWPALETTEINFO data structure, in bytes. */
  ULONG    fFlags;        /*  Palette flag. */
  ULONG    ulStartIndex;  /*  Starting palette index. */
  ULONG    ulNumEntries;  /*  Number of palette slots to query or set. */
  PRGB2    pRGBs;        /*  Pointer to the array of RGB values. */
} HWPALETTEINFO;
typedef  HWPALETTEINFO  * PHWPALETTEINFO ; </pre>
=== HWPALETTEINFO Field - ulLength ===
'''ulLength'''(ULONG) Size of the HWPALETTEINFO data structure, in bytes.
=== HWPALETTEINFO Field - fFlags ===
'''fFlags'''(ULONG) Palette flag.
These flags have the following values:
PALETTE_GET 0x0001 <br />PALETTE_SET 0x0002
=== HWPALETTEINFO Field - ulStartIndex ===
'''ulStartIndex'''(ULONG) Starting palette index.
=== HWPALETTEINFO Field - ulNumEntries ===
'''ulNumEntries'''(ULONG) Number of palette slots to query or set.
=== HWPALETTEINFO Field - pRGBs ===
'''pRGBs'''([[PRGB2]]) Pointer to the array of [[RGB]] values.
=== HWREQIN ===
Input packet to the [[GHI_CMD_REQUESTHW]] function.
<pre>typedef struct _HWREQIN {
  ULONG      ulLength;        /*  Size of the HWREQIN data structure, in bytes. */
  ULONG      ulFlags;          /*  Request option flags. */
  ULONG      cScrChangeRects;  /*  Count of screen rectangles affected by HWREQIN. */
  PRECTL    arectlScreen;    /*  Array of screen rectangles affected by HWREQIN. */
} HWREQIN;
typedef  HWREQIN  * PHWREQIN ; </pre>
=== HWREQIN Field - ulLength ===
'''ulLength'''(ULONG) Size of the HWREQIN data structure, in bytes.
=== HWREQIN Field - ulFlags ===
'''ulFlags'''(ULONG) Request option flags.
Request option flags can be defined as follows:
#define REQUEST_HW 0x01 <br />#define REQUEST_SEM_ONLY 0x02
If the REQUEST_HW flag is set, the VMAN hardware serialization lock is obtained, and pointer exclusion is performed.
*If the REQUEST_HW flag is set and the REQUEST_SEM_ONLY flag is not set, VMAN invokes the GRADD for GHI_CMD_REQUESTHW to request the linear aperture to the frame buffer. <br />�If the REQUEST_HW flag is set and the REQUEST_SEM_ONLY flag is set, VMAN does not invoke the GRADD for GHI_CMD_REQUESTHW.
If the REQUEST_HW flag is not set, the VMAN hardware serialization lock is released, and pointer exclusion is ended.
*If the REQUEST_HW flag is not set and the REQUEST_SEM_ONLY flag is not set , VMAN invokes the GRADD for GHI_CMD_REQUESTHW to release the linear aperture to the frame buffer. <br />�If the REQUEST_HW flag is not set and the REQUEST_SEM_ONLY flag is set, VMAN does not invoke the GRADD for GHI_CMD_REQUESTHW.
=== HWREQIN Field - cScrChangeRects ===
'''cScrChangeRects'''(ULONG) Count of screen rectangles affected by HWREQIN.
=== HWREQIN Field - arectlScreen ===
'''arectlScreen'''([[PRECTL]]) Array of screen rectangles affected by HWREQIN.
=== HWSETPTRIN ===
Input packet to the GHI_CMD_SETPTR function.
<pre>typedef struct _HWSETPTRIN {
  ULONG      ulLength;    /*  Size of the HWSETPTRIN data structure, in bytes. */
  PBYTE      pbANDMask;  /*  Pointer to AND bit-mask pointer. */
  PBYTE      pbXORMask;  /*  Pointer to XOR bit-mask pointer. */
  PBYTE      pbBits;      /*  Pointer to color pointer image. */
  ULONG      ulBpp;      /*  Color pointer bits per pel. */
  ULONG      ulWidth;    /*  Pointer width in pels. */
  ULONG      ulHeight;    /*  Pointer height in pels. */
  POINTL    ptlHotspot;  /*  Pointer to hot spot coordinate. */
} HWSETPTRIN;
typedef  HWSETPTRIN  * PHWSETPTRIN ; </pre>
=== HWSETPTRIN Field - ulLength ===
'''ulLength'''(ULONG) Size of the HWSETPTRIN data structure, in bytes.
=== HWSETPTRIN Field - pbANDMask ===
'''pbANDMask'''(PBYTE) Pointer to AND bit-mask pointer.
=== HWSETPTRIN Field - pbXORMask ===
'''pbXORMask'''(PBYTE) Pointer to XOR bit-mask pointer.
=== HWSETPTRIN Field - pbBits ===
'''pbBits'''(PBYTE) Pointer to color pointer image.
=== HWSETPTRIN Field - ulBpp ===
'''ulBpp'''(ULONG) Color pointer bits per pel.
=== HWSETPTRIN Field - ulWidth ===
'''ulWidth'''(ULONG) Pointer width in pels.
=== HWSETPTRIN Field - ulHeight ===
'''ulHeight'''(ULONG) Pointer height in pels.
=== HWSETPTRIN Field - ptlHotspot ===
'''ptlHotspot'''([[POINTL]]) Pointer to hot spot coordinate.
=== HWSETPTROUT ===
Output packet returned by the GRADD to the caller of the GHI_CMD_SETPTR function.
<pre>typedef struct _HWSETPTROUT {
  ULONG    ulLength;  /*  Size of the HWSETPTROUT data structure, in bytes. */
  ULONG    ulStatus;  /*  Current cursor description bits. */
} HWSETPTROUT;
typedef  HWSETPTROUT  * PHWSETPTROUT ; </pre>
=== HWSETPTROUT Field - ulLength ===
'''ulLength'''(ULONG) Size of the HWSETPTROUT data structure, in bytes.
=== HWSETPTROUT Field - ulStatus ===
'''ulStatus'''(ULONG) Current cursor description bits.
Values are as follows:
POINTER_VISIBLE 0x0001; cursor is visible. <br />POINTER_COLOR 0x0002; cursor is color (vs. monochrome). <br />POINTER_SOFTWARE 0x0004; this GRADD is not using a hardware sprite.
=== HWSHOWPTRIN ===
Input packet to the GHI_CMD_SHOWPTR function.
<pre>typedef struct _HWSHOWPTRIN {
  ULONG    ulLength;  /*  Size of the HWSHOWPTRIN data structure, in bytes. */
  BOOL      fShow;    /*  Indicates the visibility state of the pointer. */
} HWSHOWPTRIN;
typedef  HWSHOWPTRIN  * PHWSHOWPTRIN ; </pre>
=== HWSHOWPTRIN Field - ulLength ===
'''ulLength'''(ULONG) Size of the HWSHOWPTRIN data structure, in bytes.
=== HWSHOWPTRIN Field - fShow ===
'''fShow'''(BOOL) Indicates the visibility state of the pointer.
Values are as follows:
TRUE Pointer is visible. <br />FALSE Pointer is not visible.
=== IMAGEBUF ===
Characteristics describing an image.
<pre>typedef struct _IMAGEBUF {
  ULONG            ulLength;        /*  Length of IMAGEBUF data structure, in bytes. */
  ULONG            ulFlags;        /*  Image buf flag. */
  ULONG            ulType;          /*  Flag indicating type of memory:  VRAM or system.  */
  PBYTE            pBits;          /*  Virtual address of the image. */
  ULONG            ulImgWidth;      /*  Image width, in pels. */
  ULONG            ulImgHeight;    /*  Image height, in pels. */
  ULONG            ulBytesPerScan;  /*  Bytes per scan line. */
  PCOLORINFO      pColorInfo;      /*  Color space of data in buffer. */
  PCODECINFO      pCodecInfo;      /*  Compression type of data in buffer. */
  PCUSTPALINFO    pCustPalInfo;    /*  Pointer to custom palette information. */
} IMAGEBUF;
typedef  IMAGEBUF  * PIMAGEBUF ; </pre>
=== IMAGEBUF Field - ulLength ===
'''ulLength'''(ULONG) Length of IMAGEBUF data structure, in bytes.
=== IMAGEBUF Field - ulFlags ===
'''ulFlags'''(ULONG) Image buf flag.
This flag has the following values:
IBF_Y_ORG_BOTTOM 0x0001; origin is set at bottom
'''Note:'''This flag can be used as an optimization for 8-bpp images for the following two conditions:
1.The hardware has support for cached custom palettes, and the client application is playing frames using the same palette. The driver will return IMG_CAPS_PAL_CACHING if it has this support.
2.The screen is in 256-color mode and the source image bits have already been translated to the current hardware palette.
IBF_IGNORE_CUST_PAL 0x0002; ignore the custom palette
=== IMAGEBUF Field - ulType ===
'''ulType'''(ULONG) Flag indicating type of memory: VRAM or system.
This flag has the following values:
IBT_SRC_VRAM 0x0000; indicates source is VRAM memory <br />IBT_SRC_MEM 0x0001; indicates source is system memory
=== IMAGEBUF Field - pBits ===
'''pBits'''(PBYTE) Virtual address of the image.
Not required if source is in VRAM.
=== IMAGEBUF Field - ulImgWidth ===
'''ulImgWidth'''(ULONG) Image width, in pels.
=== IMAGEBUF Field - ulImgHeight ===
'''ulImgHeight'''(ULONG) Image height, in pels.
=== IMAGEBUF Field - ulBytesPerScan ===
'''ulBytesPerScan'''(ULONG) Bytes per scan line.
=== IMAGEBUF Field - pColorInfo ===
'''pColorInfo'''([[PCOLORINFO]]) Color space of data in buffer.
=== IMAGEBUF Field - pCodecInfo ===
'''pCodecInfo'''([[PCODECINFO]]) Compression type of data in buffer.
=== IMAGEBUF Field - pCustPalInfo ===
'''pCustPalInfo'''([[PCUSTPALINFO]]) Pointer to custom palette information.
=== IMAGECAPS ===
Capabilities of the video accelerator driver.
<pre>typedef struct _IMAGECAPS {
  ULONG          ulLength;        /*  Length of IMAGECAPS data structure, in bytes. */
  ULONG          ulCaps;          /*  Flag that specifies image capabilities supported. */
  ULONG          ulMaxHorz;        /*  Maximum horizontal pels supported by scaler. */
  ULONG          ulMaxVert;        /*  Maximum vertical lines supported by scaler. */
  BOOL          fAccelMem;        /*  Flag indicating whether the hardware accelerator has additional VRAM for use. */
  ULONG          ulPhysAddrVRAM;  /*  Physical address of the hardware accelerator VRAM. */
  ULONG          ulSize;          /*  Size of hardware accelerator VRAM, in bytes. */
  ULONG          ulScanLineBytes;  /*  Size of scan line, in bytes. */
  ULONG          ulNumCodecs;      /*  Number of FOURCCs that follow in this structure. */
  PCODECINFO    pCodecList;      /*  Pointer to array of CODEC FOURCCs. */
  ULONG          ulNumSrc;        /*  Number of source COLORINFO data structures pointed to by pSrcColorInfo. */
  PCOLORINFO    pSrcColorInfo;    /*  Pointer to array of source COLORINFO data structures. */
  ULONG          ulNumDst;        /*  Number of destination COLORINFO data structures pointed to by pDstColorInfo. */
  PCOLORINFO    pDstColorInfo;    /*  Pointer to array of destination COLORINFO data structures. */
} IMAGECAPS;
typedef  IMAGECAPS  * PIMAGECAPS ; </pre>
=== IMAGECAPS Field - ulLength ===
'''ulLength'''(ULONG) Length of IMAGECAPS data structure, in bytes.
=== IMAGECAPS Field - ulCaps ===
'''ulCaps'''(ULONG) Flag that specifies image capabilities supported.
This flag has the following values:
IMAGECAPS_STRETCHBLT 0x0001; has hardware stretch Blt assist <br />IMAGECAPS_CAPTURE 0x0002; has capture to VRAM hardware present <br />IMAGECAPS_1X_BLT 0x0004; has nonstretch Blt assist <br />IMAGECAPS_WINDOWCLIP 0x0008; supports clipping in hardware and/or software <br />IMAGECAPS_BUFALLOC 0x0010; supports allocation of on-card memory <br />IMAGECAPS_RECTALLOC 0x0020; supports allocation of rectangles in on-card memory <br />IMAGECAPS_COMP 0x0040; compression supported by driver <br />IMAGECAPS_DECOMP 0x0080; decompression supported by driver <br />IMAGECAPS_PAL_CACHING 0x0100; supports 8-bit palette caching <br />IMAGECAPS_INTERPOL 0x0200; supports color interpolation in hardware <br />IMAGECAPS_BYLOCSYSMEM 0x0400; able to read/write to system memory <br />IMIAGECAPS_SEM_BYPASS 0x0800; device serialization not required <br />IMAGECAPS_NO_SHARED_FB 0x1000; overlay device
=== IMAGECAPS Field - ulMaxHorz ===
'''ulMaxHorz'''(ULONG) Maximum horizontal pels supported by scaler.
=== IMAGECAPS Field - ulMaxVert ===
'''ulMaxVert'''(ULONG) Maximum vertical lines supported by scaler.
=== IMAGECAPS Field - fAccelMem ===
'''fAccelMem'''(BOOL) Flag indicating whether the hardware accelerator has additional VRAM for use.
The following values are valid:
TRUE VRAM available. <br />FALSE VRAM not available.
=== IMAGECAPS Field - ulPhysAddrVRAM ===
'''ulPhysAddrVRAM'''(ULONG) Physical address of the hardware accelerator VRAM.
This parameter is valid only if fAccelMem = TRUE.
=== IMAGECAPS Field - ulSize ===
'''ulSize'''(ULONG) Size of hardware accelerator VRAM, in bytes.
This parameter is valid only if fAccelMem = TRUE.
=== IMAGECAPS Field - ulScanLineBytes ===
'''ulScanLineBytes'''(ULONG) Size of scan line, in bytes.
Number of bytes includes padding. This parameter is valid only if fAccelMem = TRUE.
=== IMAGECAPS Field - ulNumCodecs ===
'''ulNumCodecs'''(ULONG) Number of FOURCCs that follow in this structure.
=== IMAGECAPS Field - pCodecList ===
'''pCodecList'''([[PCODECINFO]]) Pointer to array of CODEC FOURCCs.
This field points to the array of FOURCCs supported by the hardware accelerator.
=== IMAGECAPS Field - ulNumSrc ===
'''ulNumSrc'''(ULONG) Number of source [[COLORINFO]] data structures pointed to by ''pSrcColorInfo''.
=== IMAGECAPS Field - pSrcColorInfo ===
'''pSrcColorInfo'''([[PCOLORINFO]]) Pointer to array of source COLORINFO data structures.
=== IMAGECAPS Field - ulNumDst ===
'''ulNumDst'''(ULONG) Number of destination COLORINFO data structures pointed to by ''pDstColorInfo''.
=== IMAGECAPS Field - pDstColorInfo ===
'''pDstColorInfo'''([[PCOLORINFO]]) Pointer to array of destination COLORINFO data structures.
=== IMAGEPACK ===
Information pertaining to PutImage and GetImage.
<pre>typedef struct _IMAGEPACK {
  ULONG        ulLength;    /*  Length of IMAGEPACK data structure, in bytes. */
  ULONG        ulFlags;    /*  Image pack flag. */
  ULONG        ulHandle;    /*  Unique ID returned by VRAMREGISTEROUT. */
  ULONG        ulID;        /*  Unique buffer ID. */
  ULONG        ulCmdMask;  /*  Specific changes since the last frame. */
  PIMAGEBUF    pPutBuf;    /*  Used as source image in PutImage command. */
  PIMAGEBUF    pGetBuf;    /*  Used as destination image in GetImage command. */
  POINTL        ptlDstOrg;  /*  Destination origin (origin at upper left). */
  ULONG        ulDstXext;  /*  Destination X extent. */
  ULONG        ulDstYext;  /*  Destination Y extent. */
  POINTL        ptlSrcOrg;  /*  Offset into the source image. */
  ULONG        ulSrcXext;  /*  Source X extent. */
  ULONG        ulSrcYext;  /*  Source Y extent. */
  ULONG        cVisRects;  /*  Number of output visible rectangles. */
  PRECTL        prctlVis;    /*  Pointer to array of visible regions. */
  POINTL        ptlWBOrg;    /*  Origin of off-screen VRAM work buffer. */
  ULONG        cWBBytes;    /*  Number of bytes in the work buffer. */
  PBYTE        pVirtVRAM;  /*  A 32-bit virtual pointer to the start of VRAM. */
  ULONG        ulGrafXPar;  /*  Transparent color for overlay type devices. */
} IMAGEPACK;
typedef  IMAGEPACK  * PIMAGEPACK ; </pre>
=== IMAGEPACK Field - ulLength ===
'''ulLength'''(ULONG) Length of IMAGEPACK data structure, in bytes.
=== IMAGEPACK Field - ulFlags ===
'''ulFlags'''(ULONG) Image pack flag.
This flag has the following value:
IPF_DONT_INTERPOLATE 0x0001; don't use hardware color interpolation
=== IMAGEPACK Field - ulHandle ===
'''ulHandle'''(ULONG) Unique ID returned by [[VRAMREGISTEROUT]].
=== IMAGEPACK Field - ulID ===
'''ulID'''(ULONG) Unique buffer ID.
=== IMAGEPACK Field - ulCmdMask ===
'''ulCmdMask'''(ULONG) Specific changes since the last frame.
The following values are valid:
IPC_INTERMEDIATE_PUT 0x0001; not used at this time <br />IPC_RECTLS 0x0002; visible regions have changed <br />IPC_SRC_COLOR 0x0004; source color information has changed <br />IPC_DST_COLOR 0x0008; destination color information has changed <br />IPC_PALETTE 0x0010; palette color information has changed <br />IPC_SRC_SIZE 0x0020; source size information has changed <br />IPC_DST_SIZE 0x0040; destination size information has changed <br />IPC_DST_POS 0x0080; destination position information has changed <br />IPC_DROP_FRAME 0x0100; ignore this frame
=== IMAGEPACK Field - pPutBuf ===
'''pPutBuf'''([[PIMAGEBUF]]) Used as source image in PutImage command.
=== IMAGEPACK Field - pGetBuf ===
'''pGetBuf'''([[PIMAGEBUF]]) Used as destination image in GetImage command.
=== IMAGEPACK Field - ptlDstOrg ===
'''ptlDstOrg'''([[POINTL]]) Destination origin (origin at upper left).
=== IMAGEPACK Field - ulDstXext ===
'''ulDstXext'''(ULONG) Destination X extent.
=== IMAGEPACK Field - ulDstYext ===
'''ulDstYext'''(ULONG) Destination Y extent.
=== IMAGEPACK Field - ptlSrcOrg ===
'''ptlSrcOrg'''([[POINTL]]) Offset into the source image.
=== IMAGEPACK Field - ulSrcXext ===
'''ulSrcXext'''(ULONG) Source X extent.
=== IMAGEPACK Field - ulSrcYext ===
'''ulSrcYext'''(ULONG) Source Y extent.
=== IMAGEPACK Field - cVisRects ===
'''cVisRects'''(ULONG) Number of output visible rectangles.
=== IMAGEPACK Field - prctlVis ===
'''prctlVis'''([[PRECTL]]) Pointer to array of visible regions.
=== IMAGEPACK Field - ptlWBOrg ===
'''ptlWBOrg'''([[POINTL]]) Origin of off-screen VRAM work buffer.
=== IMAGEPACK Field - cWBBytes ===
'''cWBBytes'''(ULONG) Number of bytes in the work buffer.
=== IMAGEPACK Field - pVirtVRAM ===
'''pVirtVRAM'''(PBYTE) A 32-bit virtual pointer to the start of VRAM.
=== IMAGEPACK Field - ulGrafXPar ===
'''ulGrafXPar'''(ULONG) Transparent color for overlay type devices.
=== INITVDM ===
Data structure to initialize the full VDM session.
<pre>typedef struct _INITVDM {
  ULONG    ulFlags;  /*  VDM initialization type. */
} INITVDM;
typedef  INITVDM  * PINITVDM ; </pre>
=== INITVDM Field - ulFlags ===
'''ulFlags'''(ULONG) VDM initialization type.
VDM_POSTLOAD 0x1
Adapter just loaded (used internally for initialization).
VDM_INITIALIZE 0x2
Force initialization of a permanently open VDM, even if previously initialized.
=== INTCRF ===
Data structure to make a bios call.
<pre>typedef struct _INTCRF {
  ULONG      ulBIOSIntNo;  /*  0x10 for INT10 calls. */
  VCRF      aCRF;        /*  Client register frame. */
  BUFFER    pB[2];        /*  Description of input/output buffers. */
} INTCRF;
typedef  INTCRF  * PINTCRF ; </pre>
=== INTCRF Field - ulBIOSIntNo ===
'''ulBIOSIntNo'''(ULONG) 0x10 for INT10 calls.
=== INTCRF Field - aCRF ===
'''aCRF'''([[VCRF]]) Client register frame.
=== INTCRF Field - pB[2] ===
'''pB[2]'''([[BUFFER]]) Description of input/output buffers.
=== INITPROCOUT ===
Information returned by the GRADD to the caller of the GHI_CMD_INITPROC function.
<pre>typedef struct _INITPROCOUT {
  ULONG    ulLength;    /*  Length of the INITPROCOUT data structure, in bytes. */
  ULONG    ulVRAMVirt;  /*  32-bit virtual address of VRAM. */
} INITPROCOUT;
typedef  INITPROCOUT  * PINITPROCOUT ; </pre>
=== INITPROCOUT Field - ulLength ===
'''ulLength'''(ULONG) Length of the INITPROCOUT data structure, in bytes.
=== INITPROCOUT Field - ulVRAMVirt ===
'''ulVRAMVirt'''(ULONG) 32-bit virtual address of VRAM.
=== LINEINFO ===
Line information data structure shared by cLines in the alpkLinePack array.
<pre>typedef struct _LINEINFO {
  ULONG        ulLength;      /*  Length of LINEINFO data structure. */
  ULONG        ulType;        /*  Defines line type. */
  ULONG        ulStyleMask;  /*  A 32-bit style mask. */
  ULONG        cLines;        /*  Count of lines to be drawn. */
  ULONG        ulFGColor;    /*  Line Foreground color. */
  ULONG        ulBGColor;    /*  Line Background color. */
  USHORT        usForeROP;    /*  Line Foreground mix. */
  USHORT        usBackROP;    /*  Line Background mix. */
  PBMAPINFO    pDstBmapInfo;  /*  Pointer to destination surface bit map. */
  PLINEPACK    alpkLinePack;  /*  Pointer to LINEPACK data structure. */
  PRECTL        prclBounds;    /*  Pointer to bounding rect of a clipped line. */
} LINEINFO;
typedef  LINEINFO  * PLINEINFO ; </pre>
=== LINEINFO Field - ulLength ===
'''ulLength'''(ULONG) Length of LINEINFO data structure.
=== LINEINFO Field - ulType ===
'''ulType'''(ULONG) Defines line type.
LINE_SOLID Line will be solid in Foreground color. <br />LINE_INVISIBLE Line is not drawn. <br />LINE_ALTERNATE Line will be alternating Foreground and Background color; ignores style.
=== LINEINFO Field - ulStyleMask ===
'''ulStyleMask'''(ULONG) A 32-bit style mask.
=== LINEINFO Field - cLines ===
'''cLines'''(ULONG) Count of lines to be drawn.
=== LINEINFO Field - ulFGColor ===
'''ulFGColor'''(ULONG) Line Foreground color.
=== LINEINFO Field - ulBGColor ===
'''ulBGColor'''(ULONG) Line Background color.
=== LINEINFO Field - usForeROP ===
'''usForeROP'''(USHORT) Line Foreground mix.
=== LINEINFO Field - usBackROP ===
'''usBackROP'''(USHORT) Line Background mix.
The following flags apply to ulForeROP and ulBackROP:
LR_ZERO <br />LR_INVERTMERGEPAT <br />LR_MASKINVERTPAT <br />LR_INVERTCOPYPAT <br />LR_MASKPATINVERT <br />LR_INVERT <br />LR_XORPAT <br />LR_INVERTMASKPAT <br />LR_MASKPAT <br />LR_INVERTXORPAT <br />LR_LEAVEALONE <br />LR_MERGEINVERTPAT <br />LR_PATCOPY <br />LR_MERGEPATINVERT <br />LR_MERGEPAT <br />LR_ONE
=== LINEINFO Field - pDstBmapInfo ===
'''pDstBmapInfo'''([[PBMAPINFO]]) Pointer to destination surface bit map.
=== LINEINFO Field - alpkLinePack ===
'''alpkLinePack'''(PLINEPACK) Pointer to [[LINEPACK]] data structure.
=== LINEINFO Field - prclBounds ===
'''prclBounds'''([[PRECTL]]) Pointer to bounding rect of a clipped line.
=== LINEINFO2 ===
Line information data structure for simple lines, used for [[#VMI_CMD_LINE]] and [[#GHI_CMD_LINE]] functions.
The LINEINFO2 structure will never be passed to a GRADD unless the GRADD indicates it can handle both LINEINFO and LINEINFO2 structures by setting the DS_SIMPLE_LINES flag in the ulFCFlags member of [[#CAPSINFO]].
<pre>typedef struct _LINEINFO2 {
  ULONG        ulLength;        /*  Length of LINEINFO2 data structure. */
  ULONG        ulType;          /*  Defines line type. */
  ULONG        ulStyleMask;    /*  A 32-bit style mask. */
  ULONG        cLines;          /*  Count of lines to be drawn. */
  ULONG        ulFGColor;      /*  Line Foreground color. */
  ULONG        ulBGColor;      /*  Line Background color. */
  USHORT        usForeROP;      /*  Line Foreground mix. */
  USHORT        usBackROP;      /*  Line Background mix. */
  PBMAPINFO    pDstBmapInfo;    /*  Pointer to destination surface bit map. */
  ULONG        ulFlags;        /*  Line flags. */
  ULONG        ulXYStyleStep;  /*  Low byte of low word: x style, High byte of low word: y style. */
  PULONG        pulStyleValue;  /*  Pointer to style value at start point. */
  POINTL        ptlOrigin;      /*  Origin to be added to all coordinates. */
  PPOINTL      pptlStart;      /*  Pointer to POINTL defining start point. */
  PPOINTL      pptlLines;      /*  Pointer to POINTL array defining connected line endpoints. */
  POINTL        ptlClipStart;    /*  Clipped start point if it is clipped. */
  POINTL        ptlClipEnd;      /*  Clipped end point if it is clipped. */
  LONG          lClipStartError; /*  Bresenham error at the clip start for first line. */
  PRECTL        prclBounds;      /*  Pointer to bounding rect of clipped lines. */
} LINEINFO2;
typedef  LINEINFO2  * PLINEINFO2 ; </pre>
;Field - ulLength
'''ulLength'''(ULONG) Length of LINEINFO2 data structure.
;Field - ulType
'''ulType'''(ULONG) Defines line type.
LINE_SOLID Line will be solid in Foreground color. <br />LINE_INVISIBLE Line is not drawn. <br />LINE_ALTERNATE Line will be alternating Foreground and Background color; ignores style.
;Field - ulStyleMask
'''ulStyleMask'''(ULONG) A 32-bit style mask.
;Field - cLines
'''cLines'''(ULONG) Count of lines to be drawn.
;Field - ulFGColor
'''ulFGColor'''(ULONG) Line Foreground color.
;Field - ulBGColor
'''ulBGColor'''(ULONG) Line Background color.
;Field - usForeROP
'''usForeROP'''(USHORT) Line Foreground mix.
;Field - usBackROP
'''usBackROP'''(USHORT) Line Background mix.
The following flags apply to ulForeROP and ulBackROP:
*LR_ZERO
*LR_INVERTMERGEPAT
*LR_MASKINVERTPAT
*LR_INVERTCOPYPAT
*LR_MASKPATINVERT
*LR_INVERT
*LR_XORPAT
*LR_INVERTMASKPAT
*LR_MASKPAT
*LR_INVERTXORPAT
*LR_LEAVEALONE
*LR_MERGEINVERTPAT
*LR_PATCOPY
*LR_MERGEPATINVERT
*LR_MERGEPAT
*LR_ONE
;Field - pDstBmapInfo
'''pDstBmapInfo'''([[#PBMAPINFO]]) Pointer to destination surface bit map.
;Field - ulFlags
'''ulFlags'''(ULONG) Flags used for the LINEINFO2 data structure.
LINE_DO_FIRST_PEL Draw first pel of first line if not clipped. <br />LINE_DO_LAST_PEL Draw last pel of last line if not clipped. <br />LINE_MONO_INVERT Invert bits for mono destination. <br />LINE_START_CLIP Start of first line is clipped. <br />LINE_END_CLIP End of last line is clipped. <br />LINE_Y_FLIP Flip Y for all lines. <br />LINE_ALL_RADIAL All lines oriented 0, 45, 90, 135, 180, 225, 270, or 315 degrees. <br />LINE_DISJOINT Successive pairs of points in pptlLines array define disconnected line segments.
;Field - ulXYStyleStep
'''ulXYStyleStep'''(ULONG) Low byte of low word: x style, High byte of low word: y style.
The x style step is used for X-major lines where abs(dx) > abs(dy). The x style step is used for lines where abs(dx) < abs(dy).
The style step is added to the current style value for each pel.
;Field - pulStyleValue
'''pulStyleValue'''(PULONG) Pointer to style value at current pel.
The style value is composed as an error value and a mask position, as follows:
<pre>
|high word (16 bits) |3 bits            |5 bits            |8 bits            |
|--------------------+------------------+------------------+------------------|
|not used            |not used          |mask position    |error value      |
</pre>
The style value is updated as lines are drawn.
;Field - ptlOrigin
'''ptlOrigin'''([[POINTL]]) Origin to be added to all coordinates.
;Field - pptlStart
'''pptlStart'''([[PPOINTL]]) Pointer to [[POINTL]] defining start point of first line.
;Field - pptlLines
'''pptlLines'''([[PPOINTL]]) Pointer to [[POINTL]]array defining connected line endpoints.
The number of array entries is defined by [[cLines]].
;Field - ptlClipStart
'''ptlClipStart'''([[POINTL]]) Clipped start point if it is clipped.
;Field - ptlClipEnd
'''ptlClipEnd'''([[POINTL]]) Clipped end point if it is clipped.
;Field - lClipStartError
'''lClipStartError'''(LONG) Bresenham error at the clip start point for first line (not valid if first line is horizontal or vertical).
;Field - prclBounds
'''prclBounds'''([[PRECTL]]) Pointer to bounding rect of a clipped line.
=== LINEPACK ===
Line information data structure on a per-line basis.
<pre>typedef struct _LINEPACK {
  ULONG        ulStyleStep;      /*  Value to be added to ulStyleValue. */
  ULONG        ulStyleValue;    /*  Style value at the current pel. */
  ULONG        ulFlags;          /*  Flags used for the LINEPACK data structure. */
  LINEPACK    plpkNext;        /*  Pointer to next LINEPACK data structure. */
  ULONG        ulAbsDeltaX;      /*  Clipped Bresenham Delta X, absolute. */
  ULONG        ulAbsDeltaY;      /*  Clipped Bresenham Delta Y, absolute. */
  POINTL      ptlClipStart;    /*  Pointer to location for device to perform Bresenham algorithm. */
  POINTL      ptlClipEnd;      /*  Ending location for Bresenham algorithm (see ptlClipStart). */
  POINTL      ptlStart;        /*  Pointer to starting location for line. */
  POINTL      ptlEnd;          /*  Ending location for line. */
  LONG        lClipStartError;  /*  Standard Bresenham error at the clipped start point. */
} LINEPACK;
typedef  LINEPACK  * PLINEPACK ; </pre>
;Field - ulStyleStep
'''ulStyleStep'''(ULONG) Value to be added to ulStyleValue.
The value to be added to ulStyleValue on each pel stepped along the style major direction.
;Field - ulStyleValue
'''ulStyleValue'''(ULONG) Style value at the current pel.
The style value is composed of an error value and a mask position, as follows:
<pre>
|high word      |3 bits        |5 bits        |8 bits        |
|---------------+---------------+---------------+---------------|
|not used      |not used      |mask pos      |error value    |
</pre>
;Field - ulFlags
'''ulFlags'''(ULONG) Flags used for the LINEPACK data structure.
LINE_DO_FIRST_PEL Draws the first pel.
LINE_DIR_Y_POSITIVE Indicates line direction is bottom-to-top.
LINE_HORIZONTAL Indicates line is horizontal. No Bresenham algorithm.
LINE_X_MAJOR Line is XMAJOR.
LINE_DIR_X_POSITIVE Indicates line direction is left-to-right.
LINE_VERTICAL Indicates line is vertical. No Bresenham algorithm.
LINE_STYLE_X_MAJOR Line style is XMAJOR.
LINE_DO_LAST_PEL Draws the last pel.
;Field - plpkNext
'''plpkNext'''(LINEPACK) Pointer to next LINEPACK data structure.
;Field - ulAbsDeltaX
'''ulAbsDeltaX'''(ULONG) Clipped Bresenham Delta X, absolute.
;Field - ulAbsDeltaY
'''ulAbsDeltaY'''(ULONG) Clipped Bresenham Delta Y, absolute.
;Field - ptlClipStart
'''ptlClipStart'''([[POINTL]]) Pointer to location for device to perform Bresenham algorithm.
Pointer to location where device performs the Bresenham algorithm. Sets only the pels from ptlClipStart to ptlClipEnd, inclusive.
;Field - ptlClipEnd
'''ptlClipEnd'''([[POINTL]]) Ending location for Bresenham algorithm (see ptlClipStart).
;Field - ptlStart
'''ptlStart'''([[POINTL]]) Pointer to starting location for line.
The device can perform the Bresenham algorithm from ptlStart or ptlClipStart.
;Field - ptlEnd
'''ptlEnd'''([[POINTL]]) Ending location for line.
;Field - lClipStartError
'''lClipStartError'''(LONG) Standard Bresenham error at the clipped start point.
Error is calculated from the initial error and the error increments for major step and diagonal step. The initial error and the error increments are as follows:
MAX Maximum (ulAbsDeltaX, ulAbsDeltaY) <br />MIN Minimum (ulAbsDeltaX, ulAbsDeltaY) <br />Major Increment Increment to the error for stepping along the major axis: <br />2 * MIN. <br />Diagonal Increment Increment to the error for stepping along the major and minor axes: <br />2 * MIN - 2 * MAX. <br />Initial Error Error at the start point: <br />2 * MIN - MAX, if LINE_DIR_X_POSITIVE is On.
2 * MIN - MAX - 1, if LINE_DIR_X_POSITIVE is Off. <br />Horizontal and vertical lines The line is drawn from the clipped start to clipped end. <br />The lClipStartError will not be given. <br />First pel consideration Set the first pel at ptlStart (not ptlClipStart) only if LINE_DO_FIRST_PEL is set and the first pel is not clipped. <br />Last pel consideration Set the last pel at ptlEnd (not ptlClipEnd) only if LINE_DO_LAST_PEL is set and the last pel is not clipped. <br />Styling Lines are styled using the ulStyleMask, ulStyleStep, and ulStyleValue. <br />ulStyleMask A 32-bit style mask.
Error Value Error value at the current pel.
Mask Position Bit position of the ulStyleMask.
If this bit is on, set the current pel to the ulFGColor through usForeROP; otherwise, set the current pel to the ulBGColor through usBackRop.
=== MEMINFO ===
Physical to linear virtual address range conversion structure.
<pre>typedef struct _MEMINFO
{
  ULONG      ulPhysAddr;      /*  Start of physical address range. */
  ULONG      ulMemLen;        /*  Length of address range in bytes. */
  ULONG      ulVirtAddr;      /*  Virtual address corresponding to physical address range start. */
                              /*  (This linear virtual address is returned by VHPhysToVirt.) */
  struct    _MEMINFO pNextMI; /*  Pointer to the next MEMINFO structure in linked list. */
                              /*  In the last structure in the linked list, this must be set to NULL. */
} MEMINFO;
typedef  MEMINFO  * PMEMINFO ; </pre>
;Field - ulPhysAddr
'''ulPhysAddr'''(ULONG)
;Field - ulMemLen
'''ulMemLen'''(ULONG)
;Field - ulVirtAddr
'''ulVirtAddr'''(ULONG)
;MEMINFO Field - pNextMI
'''pNextMI'''(struct_MEMINFO)
=== MONITORINFO ===
The MONITORINFO data structure receives information for the current video monitor.
<pre>typedef struct _MONITORINFO {
  CHAR                szMonitor[MAX_MONITOR_LEN];          /*  Contains monitor information. */
  MONITORMODEINFO    MonitorModeInfo[MAX_MONITOR_MODES];  /*  Contains information about the monitor mode. */
} MONITORINFO;
typedef  MONITORINFO  * FAR  * PMONITORINFO ; </pre>
;Field - szMonitor[MAX_MONITOR_LEN]
'''szMonitor[MAX_MONITOR_LEN]'''(CHAR) Contains monitor information.
;Field - MonitorModeInfo[MAX_MONITOR_MODES]
'''MonitorModeInfo[MAX_MONITOR_MODES]'''([[#MONITORMODEINFO]]) Contains information about the monitor mode.
=== MONITORMODEINFO ===
Contains information on the types of monitor modes.
<pre>typedef struct _MONITORMODEINFO {
  USHORT    usXResolution;  /*  Horizontal pixels. */
  USHORT    usYResolution;  /*  Vertical scan lines. */
  BYTE      bVertRefresh;  /*  Vertical refresh rate. */
  BYTE      bHorizRefresh;  /*  Horizontal refresh rate. */
  BYTE      bVPolarityPos;  /*  Vertical polarity. */
  BYTE      bHPolarityPos;  /*  Horizontal polarity. */
  USHORT    usScrnTop;      /*  Vertical blanking away from the top, in line counts. */
  USHORT    usScrnBottom;  /*  Vertical blanking away from the bottom, in line counts. */
  USHORT    usScrnLeft;    /*  Horizontal blanking away from the left, in pixel counts. */
  USHORT    usScrnRight;    /*  Horizontal blanking away from the right, in pixel counts. */
} MONITORMODEINFO;
typedef  MONITORMODEINFO  * FAR  * PMONITORMODEINFO ; </pre>
=== MONITORMODEINFO Field - usXResolution ===
'''usXResolution'''(USHORT) Horizontal pixels.
=== MONITORMODEINFO Field - usYResolution ===
'''usYResolution'''(USHORT) Vertical scan lines.
=== MONITORMODEINFO Field - bVertRefresh ===
'''bVertRefresh'''(BYTE) Vertical refresh rate.
=== MONITORMODEINFO Field - bHorizRefresh ===
'''bHorizRefresh'''(BYTE) Horizontal refresh rate.
=== MONITORMODEINFO Field - bVPolarityPos ===
'''bVPolarityPos'''(BYTE) Vertical polarity.
=== MONITORMODEINFO Field - bHPolarityPos ===
'''bHPolarityPos'''(BYTE) Horizontal polarity.
=== MONITORMODEINFO Field - usScrnTop ===
'''usScrnTop'''(USHORT) Vertical blanking away from the top, in line counts.
=== MONITORMODEINFO Field - usScrnBottom ===
'''usScrnBottom'''(USHORT) Vertical blanking away from the bottom, in line counts.
=== MONITORMODEINFO Field - usScrnLeft ===
'''usScrnLeft'''(USHORT) Horizontal blanking away from the left, in pixel counts .
=== MONITORMODEINFO Field - usScrnRight ===
'''usScrnRight'''(USHORT) Horizontal blanking away from the right, in pixel counts.
=== PALETTEDATA ===
The PALETTEDATA data structure contains information on the palette registers.
<pre>typedef struct _PALETTEDATA {
  ULONG    ulPalCount;    /*  Specifies the number of bPaletteData entries that follow. */
  ULONG    ulPalStart;    /*  Start index for data. */
  BYTE      bPaletteData;  /*  One byte is allocated; start of palette. */
} PALETTEDATA;
typedef  PALETTEDATA  * FAR  * PPALETTEDATA ; </pre>
=== PALETTEDATA Field - ulPalCount ===
'''ulPalCount'''(ULONG) Specifies the number of bPaletteData entries that follow .
=== PALETTEDATA Field - ulPalStart ===
'''ulPalStart'''(ULONG) Start index for data.
=== PALETTEDATA Field - bPaletteData ===
'''bPaletteData'''(BYTE) One byte is allocated; start of palette.
=== POINTL ===
Point structure (long integers).
<pre>typedef struct _POINTL {
  LONG    x;  /*  X-coordinate. */
  LONG    y;  /*  Y-coordinate. */
} POINTL;
typedef  POINTL  * PPOINTL ; </pre>
=== POINTL Field - x ===
'''x'''(LONG) X-coordinate.
=== POINTL Field - y ===
'''y'''(LONG) Y-coordinate.
=== RECTL ===
Rectangle structure.
<pre>typedef struct _RECTL {
  LONG    xLeft;    /*  X-coordinate of left-hand edge of rectangle. */
  LONG    yBottom;  /*  Y-coordinate of bottom edge of rectangle. */
  LONG    xRight;  /*  X-coordinate of right-hand edge of rectangle. */
  LONG    yTop;    /*  Y-coordinate of top edge of rectangle. */
} RECTL;
typedef  RECTL  * PRECTL ; </pre>
=== RECTL Field - xLeft ===
'''xLeft'''(LONG) X-coordinate of left-hand edge of rectangle.
=== RECTL Field - yBottom ===
'''yBottom'''(LONG) Y-coordinate of bottom edge of rectangle.
=== RECTL Field - xRight ===
'''xRight'''(LONG) X-coordinate of right-hand edge of rectangle.
=== RECTL Field - yTop ===
'''yTop'''(LONG) Y-coordinate of top edge of rectangle.
=== RGB ===
RGB color value.
<pre>typedef struct _RGB {
  BYTE    bBlue;  /*  Blue component of the color definition. */
  BYTE    bGreen;  /*  Green component of the color definition. */
  BYTE    bRed;    /*  Red component of the color definition. */
} RGB;
typedef  RGB  * PRGB ; </pre>
=== RGB Field - bBlue ===
'''bBlue'''(BYTE) Blue component of the color definition.
=== RGB Field - bGreen ===
'''bGreen'''(BYTE) Green component of the color definition.
=== RGB Field - bRed ===
'''bRed'''(BYTE) Red component of the color definition.
=== RGB2 ===
RGB color value.
<pre>typedef struct _RGB2 {
  BYTE    bBlue;      /*  Blue component of the color definition. */
  BYTE    bGreen;    /*  Green component of the color definition. */
  BYTE    bRed;      /*  Red component of the color definition. */
  BYTE    fcOptions;  /*  Entry options. */
} RGB2;
typedef  RGB2  * PRGB2;</pre>
=== RGB2 Field - bBlue ===
'''bBlue'''(BYTE) Blue component of the color definition.
=== RGB2 Field - bGreen ===
'''bGreen'''(BYTE) Green component of the color definition.
=== RGB2 Field - bRed ===
'''bRed'''(BYTE) Red component of the color definition.
=== RGB2 Field - fcOptions ===
'''fcOptions'''(BYTE) Entry options.
These can be ORed together if required:
PC_RESERVED The color entry is reserved for animating color with the palette manager.
PC_EXPLICIT The low-order word of the color table entry designates a physical palette slot. This allows an application to show the actual contents of the device palette as realized for other logical palettes. This does not prevent the color in the slot from being changed for any reason.
=== SVGARGB ===
The SVGARGB data structure contains the values of RGB.
<pre>typedef struct _SVGARGB {
  BYTE    bR;      /*  Value of Red. */
  BYTE    bG;      /*  Value of Green. */
  BYTE    bB;      /*  Value of Blue. */
  BYTE    bUnused;  /*  Reserved. */
} SVGARGB;
typedef  SVGARGB  * FAR  * PSVGARGB ; </pre>
=== SVGARGB Field - bR ===
'''bR'''(BYTE) Value of Red.
=== SVGARGB Field - bG ===
'''bG'''(BYTE) Value of Green.
=== SVGARGB Field - bB ===
'''bB'''(BYTE) Value of Blue.
=== SVGARGB Field - bUnused ===
'''bUnused'''(BYTE) Reserved.
=== TEXTBLTINFO ===
Information structure used for [[GHI_CMD_TEXT]] and [[VMI_CMD_TEXT]] functions. The TEXTBLTINFO structure includes a pointer to [[DEVFONTINFO]].
<pre>typedef struct _TEXTBLTINFO {
  ULONG            ulLength;        /*  Length of the TEXTBLTINFO structure, in bytes. */
  ULONG            flOptions;      /*  Not used. */
  ULONG            lGlyphCnt;      /*  Count of glyph indices provided on this call. */
  PLONG            pGlyphIndicies;  /*  Pointer to glyph indices. */
  ULONG            ulFGMix;        /*  Foreground mix mode. */
  ULONG            ulBGMix;        /*  Background mix mode. */
  ULONG            ulFGColor;      /*  Foreground colors. */
  ULONG            ulBGColor;      /*  Background colors. */
  PBMAPINFO        pDstBmapInfo;    /*  Pointer to destination physical surface descriptions. */
  PDEVFONTINFO    pDevFntInfo;    /*  Pointer to DEVFONTINFO for additional font information. */
  ULONG            ulClpCnt;        /*  Number of clip regions that intersect glyph data. */
  PBLTRECT        abrClipRects;    /*  Array of ulClpCnt clip rectangles. */
  PPOINTL          aptlSrcOrg;      /*  Array of glyph origin points. */
  PBLTRECT        abrDst;          /*  Array of destination rectangles. */
} TEXTBLTINFO;
typedef  TEXTBLTINFO  * PTEXTBLTINFO ; </pre>
=== TEXTBLTINFO Field - ulLength ===
'''ulLength'''(ULONG) Length of the TEXTBLTINFO structure, in bytes.
=== TEXTBLTINFO Field - flOptions ===
'''flOptions'''(ULONG) Not used.
=== TEXTBLTINFO Field - lGlyphCnt ===
'''lGlyphCnt'''(ULONG) Count of glyph indices provided on this call.
If the specified device does not support clipping, then this field may not match actual characters in the original string. Each glyph will be repeated for each clipping rectangle of that character.
=== TEXTBLTINFO Field - pGlyphIndicies ===
'''pGlyphIndicies'''(PLONG) Pointer to glyph indices.
This string can also be modified based on lGlyphCnt conditions. Refer to [[GLYPHINFO]]for example structures to access glyph information. The lowest byte is used to access the low byte table and the 2nd to lowest byte is used to access the high byte table.
=== TEXTBLTINFO Field - ulFGMix ===
'''ulFGMix'''(ULONG) Foreground mix mode.
=== TEXTBLTINFO Field - ulBGMix ===
'''ulBGMix'''(ULONG) Background mix mode.
=== TEXTBLTINFO Field - ulFGColor ===
'''ulFGColor'''(ULONG) Foreground colors.
=== TEXTBLTINFO Field - ulBGColor ===
'''ulBGColor'''(ULONG) Background colors.
=== TEXTBLTINFO Field - pDstBmapInfo ===
'''pDstBmapInfo'''([[PBMAPINFO]]) Pointer to destination physical surface descriptions.
=== TEXTBLTINFO Field - pDevFntInfo ===
'''pDevFntInfo'''([[PDEVFONTINFO]]) Pointer to P[[DEVFONTINFO]] for additional font information.
=== TEXTBLTINFO Field - ulClpCnt ===
'''ulClpCnt'''(ULONG) Number of clip regions that intersect glyph data.
=== TEXTBLTINFO Field - abrClipRects ===
'''abrClipRects'''([[PBLTRECT]]) Array of ulClpCnt clip rectangles.
=== TEXTBLTINFO Field - aptlSrcOrg ===
'''aptlSrcOrg'''([[PPOINTL]]) Array of glyph origin points.
=== TEXTBLTINFO Field - abrDst ===
'''abrDst'''([[PBLTRECT]]) Array of destination rectangles.
=== USERCAPSIN ===
Information structure used for [[GHI_CMD_USERCAPS]] and [[VMI_CMD_USERCAPS]] functions.
<pre>typedef struct _USERCAPSIN {
  ULONG    ulLength;    /*  Length of the USERCAPSIN structure in bytes. */
  ULONG    ulFunction;  /*  Specifies the QUERYCAPS, QUERYCAPSLIST, or SETCAPS subfunctions. */
  ULONG    ulSize;      /*  Length, in bytes, of buffer area. */
} USERCAPSIN;
typedef  USERCAPSIN  * PUSERCAPSIN ; </pre>
=== USERCAPSIN Field - ulLength ===
'''ulLength'''(ULONG) Length of the USERCAPSIN structure in bytes.
=== USERCAPSIN Field - ulFunction ===
'''ulFunction'''(ULONG) Specifies the QUERYCAPS, QUERYCAPSLIST, or SETCAPS subfunctions.
The subfunctions, specified by the ulFunction field of the USERCAPSIN structure, may be defined as follows:
QUERYCAPS
<pre>#define  QUERYCAPS    1L</pre>
QUERYCAPS returns the number of capabilities and capability descriptions in the buffer area pointed to by pOut.
Because the values for each capability are not yet allocated, the pValueList, pCurrentValue, and pDefaultValue fields in the [[DRIVERCAPS]] structures must not be filled in for this call.
The driver must ensure that the buffer area size, specified by ulSize, is sufficient for the supported number of capabilities. If not, the driver should return the number of capabilities supported in the first word of the buffer area and a return code of RC_ERROR. The driver will be reinvoked with a larger buffer area for QUERYCAPS. This allows a driver to export multiple capabilities (each, in turn, gets its own page in the System Object notebook).
QUERYCAPSLIST
<pre>#define  QUERYCAPSLIST  2L</pre>
QUERYCAPSLIST fills the pValueList, pCurrentValue, and pDefaultValue fields in the [[DRIVERCAPS]] structure pointed to by pOut. The members must be 0 padded up to the length specified by ulValueMemberSize.
SETCAP
<pre>#define  SETCAP    3L</pre>
SETCAP sets a value that the user has selected. The value is specified in the pCurrentValue field of the [[DRIVERCAPS]] structure pointed to by pOut.
;Field - ulSize
'''ulSize'''(ULONG) Length, in bytes, of buffer area.
=== VCRF ===
Data structure inside [[#INTCRF]] containing the register values to be passed in the bios call.
<pre>
typedef struct _VCRF {
  ULONG    reg_eax;
  ULONG    reg_ebx;
  ULONG    reg_ecx;
  ULONG    reg_edx;
  ULONG    reg_ebp;
  ULONG    reg_esi;
  ULONG    reg_edi;
  ULONG    reg_ds;
  ULONG    reg_es;
  ULONG    reg_fs;
  ULONG    reg_gs;
  ULONG    reg_cs;
  ULONG    reg_eip;
  ULONG    reg_eflag;
  ULONG    reg_ss;
  ULONG    reg_esp;
} VCRF;</pre>
;Field - reg_eax
'''reg_eax'''(ULONG)
;Field - reg_ebx
'''reg_ebx'''(ULONG)
;Field - reg_ecx
'''reg_ecx'''(ULONG)
;Field - reg_edx
'''reg_edx'''(ULONG)
;Field - reg_ebp
'''reg_ebp'''(ULONG)
;Field - reg_esi
'''reg_esi'''(ULONG)
;Field - reg_edi
'''reg_edi'''(ULONG)
;Field - reg_ds
'''reg_ds'''(ULONG)
;Field - reg_es ===
'''reg_es'''(ULONG)
;Field - reg_fs
'''reg_fs'''(ULONG)
;Field - reg_gs
'''reg_gs'''(ULONG)
;Field - reg_cs
'''reg_cs'''(ULONG)
;Field - reg_eip
'''reg_eip'''(ULONG)
;Field - reg_eflag
'''reg_eflag'''(ULONG)
;Field - reg_ss
'''reg_ss'''(ULONG)
;Field - reg_esp
'''reg_esp'''(ULONG)
=== VIDEO_ADAPTER ===
The VIDEO_ADAPTER data structure receives information for the desktop mode.
<pre>typedef struct _VIDEO_ADAPTER {
  HVIDEO            hvideo;    /*  The handle for this adapter. */
  ADAPTERINFO      Adapter;  /*  Hardware information for this adapter. */
  VIDEOMODEINFO    ModeInfo;  /*  Information about the current video mode. */
} VIDEO_ADAPTER;
typedef  VIDEO_ADAPTER *FAR *PVIDEO_ADAPTER;</pre>
;Field - hvideo ===
'''hvideo'''(HVIDEO) The handle for this adapter.
;Field - Adapter ===
'''Adapter'''([[#ADAPTERINFO]]) Hardware information for this adapter.
;Field - ModeInfo ===
'''ModeInfo'''([[#VIDEOMODEINFO]]) Information about the current video mode.
=== VIDEOMODEINFO ===
The VIDEOMODEINFO data structure receives information for the current video monitor.
'''Note:'''The ''cb''and ''ulColors''fields are new to VIDEDOMODEINFO. The color depth field (''ulColors'') was introduced to differentiate between pixel and color depth.
<pre>typedef struct _VIDEOMODEINFO {
  ULONG      cb;                  /*  Size of the structure. */
  MODEID    miModeId;            /*  Used to make a SetMode request. */
  USHORT    usType;              /*  Flag indicating mode type. */
  USHORT    usInt10ModeSet;      /*  Interrupt 10 mode. */
  USHORT    usXResolution;      /*  Horizontal pixels. */
  USHORT    usYResolution;      /*  Vertical scanlines. */
  ULONG      ulBufferAddress;    /*  Physical address of VRAM. */
  ULONG      ulApertureSize;      /*  VRAM aperture. */
  ULONG      ulColors;            /*  Color depth. */
  BYTE      bBitsPerPixel;      /*  Pixel depth. */
  BYTE      bBitPlanes;          /*  Number of planes. */
  BYTE      bXCharSize;          /*  Font width. */
  BYTE      bYCharSize;          /*  Font height. */
  USHORT    usBytesPerScanLine;  /*  Number of bytes per scan line. */
  USHORT    usTextRows;          /*  Number of text rows. */
  ULONG      ulPageLength;        /*  Number of bytes to save a plane. */
  ULONG      ulSavesize;          /*  Total bytes of VRAM to save. */
  BYTE      bVrtRefresh;        /*  Vertical refresh rate. */
  BYTE      bHrtRefresh;        /*  Horizontal refresh rate. */
  BYTE      bVrtPolPos;          /*  Vertical polarity. */
  BYTE      bHrtPolPos;          /*  Horizontal polarity. */
  USHORT    usScrnTop;          /*  Vertical blanking away from the top, in line counts. */
  USHORT    usScrnBottom;        /*  Vertical blanking away from the bottom, in line counts. */
  USHORT    usScrnLeft;          /*  Horizontal blanking away from the left, in pixel counts. */
  USHORT    usScrnRight;        /*  Horizontal blanking away from the right, in pixel counts. */
  CHAR      szColorFormat[8];    /*  Color format string for true color or high-color modes. */
  CHAR      szColorWeight[8];    /*  Color weight string for true color or high-color modes. */
} VIDEOMODEINFO;
typedef VIDEOMODEINFO *FAR *PVIDEOMODEINFO;</pre>
;Field - cb
'''cb'''(ULONG) Size of the structure.
;Field - miModeId
'''miModeId'''(MODEID) Used to make a SetMode request.
;Field - usType
'''usType'''(USHORT) Flag indicating mode type.
The following values are valid for this flag:
MODE_FLAG_NOT_MONO 0x0001; Mono-compatible
MODE_FLAG_GRAPHICS 0x0002; Text mode, Graphics
MODE_FLAG_NO_CLR_BRST 0x0004; Disable Color burst
MODE_FLAG_NATIVE 0x0008; Native (advanced function) mode
IGNORE_CLR_BRST 0x0010; Disable color burst; doesn't make sense for this mode
NOT_PLASMA 0x0020; will not work on plasma display
MODE_FLAG_VGA_ENTRY 0x0040; VGA mode, needs clean up
;Field - usInt10ModeSet
'''usInt10ModeSet'''(USHORT) Interrupt 10 mode.
;Field - usXResolution
'''usXResolution'''(USHORT) Horizontal pixels.
;Field - usYResolution
'''usYResolution'''(USHORT) Vertical scanlines.
;Field - ulBufferAddress
'''ulBufferAddress'''(ULONG) Physical address of VRAM.
;Field - ulApertureSize
'''ulApertureSize'''(ULONG) VRAM aperture.
;Field - ulColors
'''ulColors'''(ULONG) Color depth.
;Field - bBitsPerPixel
'''bBitsPerPixel'''(BYTE) Pixel depth.
;Field - bBitPlanes
'''bBitPlanes'''(BYTE) Number of planes.
;Field - bXCharSize
'''bXCharSize'''(BYTE) Font width.
;Field - bYCharSize
'''bYCharSize'''(BYTE) Font height.
;Field - usBytesPerScanLine
'''usBytesPerScanLine'''(USHORT) Number of bytes per scan line.
;Field - usTextRows
'''usTextRows'''(USHORT) Number of text rows.
;Field - ulPageLength
'''ulPageLength'''(ULONG) Number of bytes to save a plane.
;Field - ulSavesize
'''ulSavesize'''(ULONG) Total bytes of VRAM to save.
;Field - bVrtRefresh
'''bVrtRefresh'''(BYTE) Vertical refresh rate.
;Field - bHrtRefresh
'''bHrtRefresh'''(BYTE) Horizontal refresh rate.
;Field - bVrtPolPos
'''bVrtPolPos'''(BYTE) Vertical polarity.
;Field - bHrtPolPos
'''bHrtPolPos'''(BYTE) Horizontal polarity.
;Field - usScrnTop
'''usScrnTop'''(USHORT) Vertical blanking away from the top, in line counts.
;Field - usScrnBottom
'''usScrnBottom'''(USHORT) Vertical blanking away from the bottom, in line counts.
;Field - usScrnLeft
'''usScrnLeft'''(USHORT) Horizontal blanking away from the left, in pixel counts.
;Field - usScrnRight
'''usScrnRight'''(USHORT) Horizontal blanking away from the right, in pixel counts.
;Field - szColorFormat[8]
'''szColorFormat[8]'''(CHAR) Color format string for true color or high-color modes.
;Field - szColorWeight[8]
'''szColorWeight[8]'''(CHAR) Color weight string for true color or high-color modes.
=== VIDEORESOURCEPACK ===
The VIDEORESOURCEPACK data structure contains resource information and definitions.
<pre>typedef struct _VIDEORESOURCEPACK {
  ULONG    ConsRes;    /*  An array of resource definitions. */
  ULONG    ulNumCons;  /*  Number of resources. */
} VIDEORESOURCEPACK;
typedef  VIDEORESOURCEPACK  * FAR  * PVIDEORESOURCEPACK ; </pre>
;Field - ConsRes
'''ConsRes'''(ULONG) An array of resource definitions.
;Field - ulNumCons
'''ulNumCons'''(ULONG) Number of resources.
=== VIDEOSTATE ===
The VIDEOSTATE data structure receives information for the mode to be saved .
<pre>typedef struct _VIDEOSTATE {
  ULONG        fStateFlags;    /*  Flag indicating what to save. */
  MODEID        miState;        /*  Contains the mode ID for the mode to be saved. */
  PVOID        pModeData;      /*  Pointer to set mode command sequence. */
  ULONG        ulVRAMSaveSize;  /*  Number of bytes per page to save. */
  PVRAMDATA    pVRAM;          /*  Pointer to video memory. */
  PCLUTDATA    pCLUT;          /*  Pointer to palette data. */
  PFONTDATA    pFONT;          /*  Pointer to font data. */
} VIDEOSTATE;
typedef  VIDEOSTATE  * FAR  * PVIDEOSTATE ; </pre>
;Field - fStateFlags
'''fStateFlags'''(ULONG) Flag indicating what to save.
STATEFLAG_REGISTERS 0x0001
STATEFLAG_CLUT 0x0002
STATEFLAG_VRAM 0x0004
STATEFLAG_FONT 0x0008
;Field - miState
'''miState'''(MODEID) Contains the mode ID for the mode to be saved.
;Field - pModeData
'''pModeData'''(PVOID) Pointer to set mode command sequence.
;Field - ulVRAMSaveSize
'''ulVRAMSaveSize'''(ULONG) Number of bytes per page to save.
;Field - pVRAM
'''pVRAM'''(PVRAMDATA) Pointer to video memory.
;Field - pCLUT
'''pCLUT'''(PCLUTDATA) Pointer to palette data.
;Field - pFONT
'''pFONT'''(PFONTDATA) Pointer to font data.
=== VMIQCI ===
Output packet returned by the GRADD to the caller of the VMI_CMD_ QUERYCHAININFO function.
<pre>typedef struct _VMIQCI {
  ULONG          ulLength;  /*  Size of the VMIQCI data structure, in bytes. */
  PCHAININFO    pciHead;  /*  Pointer to the head of the GRADD chain. */
} VMIQCI;
typedef VMIQCI *PVMIQCI;</pre>
;Field - ulLength
'''ulLength'''(ULONG) Size of the VMIQCI data structure, in bytes.
;Field - pciHead
'''pciHead'''([[#PCHAININFO]]) Pointer to the head of the GRADD chain.
=== VRAMALLOCIN ===
Input packet to the GHI_CMD_VRAM function.
<pre>typedef struct _VRAMALLOCIN {
  ULONG    ulLength;    /*  Size of the VRAMALLOCIN data structure, in bytes. */
  ULONG    ulFlags;    /*  Flag indicating type of VRAM allocation. */
  ULONG    ulID;        /*  ID required as input only on deallocation. */
  ULONG    ulFunction;  /*  Requested function: allocate, deallocate, or query. */
  ULONG    ulHandle;    /*  Handle returned from registering. */
  ULONG    ulSize;      /*  Requested allocation size in bytes. */
  ULONG    ulWidth;    /*  Requested allocation width in pixels. */
  ULONG    ulHeight;    /*  Requested allocation height in scanlines. */
} VRAMALLOCIN;
typedef VRAMALLOCIN *PVRAMALLOCIN;</pre>
;Field - ulLength
'''ulLength'''(ULONG) Size of the VRAMALLOCIN data structure, in bytes.
;Field - ulFlags
'''ulFlags'''(ULONG) Flag indicating type of VRAM allocation.
Values are as follows:
VRAM_ALLOC_SHARED 0x0001 <br />VRAM_ALLOC_RECTANGLE 0x0002 <br />VRAM_ALLOC_STATIC 0x1000
;Field - ulID
'''ulID'''(ULONG) ID required as input only on deallocation.
;Field - ulFunction
'''ulFunction'''(ULONG) Requested function: allocate, deallocate, or query.
Values are as follows:
VRAM_ALLOCATE 1 <br />VRAM_DEALLOCATE 2 <br />VRAM_QUERY 3
;Field - ulHandle
'''ulHandle'''(ULONG) Handle returned from registering.
;Field - ulSize
'''ulSize'''(ULONG) Requested allocation size in bytes.
;Field - ulWidth
'''ulWidth'''(ULONG) Requested allocation width in pixels.
;Field - ulHeight
'''ulHeight'''(ULONG) Requested allocation height in scanlines.
=== VRAMALLOCOUT ===
Output packet returned by the GRADD to the caller of the GHI_CMD_VRAM function.
<pre>typedef struct _VRAMALLOCOUT {
  ULONG      ulLength;        /*  Size of the VRAMALLOCOUT data structure, in bytes. */
  ULONG      ulFlags;          /*  Flag indicating type of VRAM allocation. */
  ULONG      ulID;            /*  ID returned on allocation. */
  POINTL    ptlStart;        /*  X and Y location of VRAM. */
  ULONG      ulSize;          /*  Requested size of VRAM, in bytes. */
  ULONG      ulScanLineBytes;  /*  Length of scan line, in bytes. */
} VRAMALLOCOUT;
typedef VRAMALLOCOUT *PVRAMALLOCOUT;</pre>
;Field - ulLength
'''ulLength'''(ULONG) Size of the VRAMALLOCOUT data structure, in bytes.
;Field - ulFlags
'''ulFlags'''(ULONG) Flag indicating type of VRAM allocation.
Value is as follows:
:VRAM_ALLOC_WORKBUFFER 0x0004
;Field - ulID
'''ulID'''(ULONG) ID returned on allocation.
;Field - ptlStart
'''ptlStart'''([[POINTL]]) X and Y location of VRAM.
;Field - ulSize
'''ulSize'''(ULONG) Requested size of VRAM, in bytes.
;Field - ulScanLineBytes
'''ulScanLineBytes'''(ULONG) Length of scan line, in bytes.
=== VRAMDATA ===
The VRAMDATA data structure is a pointer to video memory.
typedef BYTE VRAMDATA;
=== VRAMIN ===
Input packet to the [[#GHI_CMD_VRAM]] function.
<pre>typedef struct _VRAMIN {
  ULONG    ulLength;    /*  Size of the VRAMIN data structure, in bytes. */
  ULONG    ulFunction;  /*  Flag indicating type of VRAM allocation. */
  PVOID    pIn;        /*  Pointer to an allocate or register packet. */
} VRAMIN;
typedef VRAMIN *PVRAMIN;</pre>
;Field - ulLength
'''ulLength'''(ULONG) Size of the VRAMIN data structure, in bytes.
;VRAMIN Field - ulFunction
'''ulFunction'''(ULONG) Flag indicating type of VRAM allocation.
Values are as follows:
VRAM_ALLOCATE 1 <br />VRAM_DEALLOCATE 2 <br />VRAM_QUERY 3 <br />VRAM_REGISTER 4 <br />VRAM_DEREGISTER 5
;Field - pIn
'''pIn'''(PVOID) Pointer to an allocate or register packet.
If the ulFunction field of the VRAMIN structure is set to VRAM_ALLOCATE, VRAM_DEALLOCATE, or VRAM_QUERY, then pIn points to a [[#VRAMALLOCIN]] data structure.
If the ulFunction field of the VRAMIN structure is set to VRAM_REGISTER or VRAM_DEGISTER, then pIn points to a [[#VRAMREGISTERIN]] data structure.
=== VRAMREGISTERIN ===
Input packet to the GHI_CMD_VRAM function via the VRAMIN data structure.
<pre>
typedef struct _VRAMREGISTERIN {
  ULONG    ulLength;  /*  Size of the VRAMREGISTERIN data structure, in bytes.  */
  ULONG    ulHandle;  /*  Handle required as input on deregister. */
  ULONG    ulFlags;  /*  Flag indicating type of VRAM registration. */
} VRAMREGISTERIN;
typedef VRAMREGISTERIN *PVRAMREGISTERIN;</pre>
;Field - ulLength
'''ulLength'''(ULONG) Size of the VRAMREGISTERIN data structure, in bytes.
;Field - ulHandle
'''ulHandle'''(ULONG) Handle required as input on deregister.
;Field - ulFlags
'''ulFlags'''(ULONG) Flag indicating type of VRAM registration.
Values are as follows:
VRAM_REGISTER_HANDLE 0x0001
VRAM_REGISTER_VRAMONLY 0x1000
=== VRAMREGISTEROUT ===
Output packet returned by the GRADD to the caller of the GHI_CMD_VRAM function via the VRAMIN data structure.
<pre>
typedef struct _VRAMREGISTEROUT {
  ULONG    ulLength;  /*  Size of the VRAMREGISTEROUT data structure, in bytes.  */
  ULONG    ulFlags;  /*  Not used at this time. */
  ULONG    ulHandle;  /*  Handle returned on register. */
} VRAMREGISTEROUT;
typedef VRAMREGISTEROUT *PVRAMRGISTEROUT;</pre>
;Field - ulLength
'''ulLength'''(ULONG) Size of the VRAMREGISTEROUT data structure, in bytes.
;Field - ulFlags
'''ulFlags'''(ULONG) Not used at this time.
;Field - ulHandle:
'''ulHandle'''(ULONG) Handle returned on register.


==Notices==
==Notices==
'''OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)'''
'''OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)'''


'''The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:'''INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION &quot;AS IS&quot; WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.
'''The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law:''' INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.


This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.
Line 6,598: Line 70:
COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.
COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.


Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: &quot;(C) (your company name) (year). All rights reserved.&quot;
Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."


'''(C) Copyright International Business Machines Corporation 1996. All rights reserved.'''<br />Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.
'''(C) Copyright International Business Machines Corporation 1996. All rights reserved.'''<br />Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Latest revision as of 22:41, 18 November 2019

Graphics Adapter Device Driver Reference
  1. Introduction to Graphics Adapter Device Drivers
  2. GRADD Model Components
  3. Video Manager
  4. Graphics Adapter Device Drivers
  5. VIDEOPMI.DLL Exported Functions
  6. VIDEO Protect-Mode Interface
  7. VIDEOCFG.DLL Exported Functions
  8. Appendix A. OS/2 Version Compatibility Considerations
  9. Appendix B. Syntax Conventions
  10. Appendix C. Data Types
  11. Appendix D. Notices
  12. Miscellaneous

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

About This Book

The Graphics Adapter Device Driver (GRADD) Reference supports OS/2 Warp on the Intel hardware platform. The information in this book describes the GRADD driver model, how the related components work together, and why the GRADD model enhances OS/2 Warp device-driver support.

Detailed descriptions of control structures, data structures, and I/O formats have been included to help you understand and use the interfaces.

Developers using this book should be familiar with the C or assembler programming language and the OS/2 operating system.

How This Book is Organized

This book includes the following chapters and supporting appendixes:

Introduction to Graphics Adapter Device Drivers
This chapter briefly describes the design philosophy of the GRADD Model.
GRADD Model Components
This chapter provides details on each of the components and how they work together within the GRADD Model.
Video Manager
This chapter contains a list of the Video Manager Interface functions, as well as a detailed description of each.
Graphics Adapter Device Drivers
This chapter describes the device driver interface (DDI) for a GRADD, how and when to add extensions, and detailed description of each Graphics Hardware Interface function. In addition, this chapter describes the Enhanced Direct Interface Video Extension (EnDIVE) functions.
VIDEOPMI.DLL Exported Functions
This chapter describes the format and syntax used to define the data necessary to set a video mode while in OS/2 Protect Mode. It also includes the APIs.
VIDEO Protect-Mode Interface
This chapter discusses the purpose of the VIDEO Protect-Mode Interface (PMI) used in IBM Operating System/2. It is an extension of the VESA SVPMI standard currently in use by the operating system's base and virtual video subsystems. The PMI provides a means of setting Super VGA video modes while in Protect Mode and of enabling their virtualization in multiple DOS sessions.
Installing Video Configuration Manager for OS/2
This chapter discussed the Video Configuration Manager (VCMAN), the OS/2 operating-system-service module VIDEOCFG.DLL, how video installation and configuration information is stored in a persistent namespace in the Registry; this discussion includes the functions used to install and configure video adapters and monitors.

Appendixes

Appendix A. OS/2 Version Compatibility Considerations
This appendix describes information in terms of version compatibility.
Appendix B. Syntax Conventions
This appendix indicates the conventions that have been used for the parameter names found in the data types.
Appendix C. Data Types
This appendix contains a description of the parameters for all the data types called by the Video Manager Interface, the Graphics Hardware Interface, the Video Configuration Manager, and the Protect-Mode Interface.
Appendix D. Notices
This appendix contains legal notices.
Miscellaneous
A glossary and an index are included.

Assistance

Technical support for device driver development is provided by the IBM Driver Development Support Center (DDSC) through a bulletin board system (BBS) known as the "DUDE." You are encouraged to use the DUDE to obtain support by sending in your questions and reviewing the question and answer database which can be downloaded for off-line review.

To access the DUDE, dial 512-838-9717 (using a modem) to register and access the support system. For voice support in the United States, call 512-838-9493.

Additional assistance is available through the IBM Solution Developer Program. For membership information:

Internet: ibmsdp@vnet.ibm.com
US/Canada: 800-627-8363
International: 770-835-9902
International Fax: 770-835-9444

Ordering Information

For an illustration of OS/2 Technical Publications and other related product documents, see the figure labeled "OS/2 Technical Publications". The documents represented in this illustration are available only in English.

In addition to the actual tools and source code available on The IBM Developer Connection Device Driver Kit for OS/2, this CD-ROM also includes the following DDK reference books in online format.

  • The Physical Device Driver Reference
  • The Storage Device Driver Reference
  • The Input/Output Device Driver Reference
  • The Pen for OS/2 Device Driver Reference
  • The Virtual Device Driver Reference
  • The Presentation Device Driver Reference
  • The Display Device Driver Reference
  • The Printer Device Driver Reference
  • The MMPM/2 Device Driver Reference (Multimedia)

OS/2 Version Compatibility Considerations

This version of the GRADD Reference was written to support OS/2 Warp on the Intel hardware platform.

Notices

OS/2 Developer Connection Device Driver Kit, Version 4 Edition (June 1996)

The following paragraph does not apply to the United Kingdom or any country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This publication could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

It is possible that this publication may contain reference to, or information about, IBM products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that IBM intends to announce such IBM products, programming, or services in your country.

Requests for technical information about IBM products should be made to your IBM reseller or IBM marketing representative.

Copyright Notices

COPYRIGHT LICENSE: This publication contains printed sample application programs in source language, which illustrate OS/2 programming techniques. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the OS/2 application programming interface.

Each copy of any portion of these sample programs or any derivative work, which is distributed to others, must include a copyright notice as follows: "(C) (your company name) (year). All rights reserved."

(C) Copyright International Business Machines Corporation 1996. All rights reserved.
Note to U.S. Government Users - Documentation related to restricted rights - Use, duplication or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Disclaimers

References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Subject to IBM's valid intellectual property or other legally protectable rights, any functionally equivalent product, program, or service may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products , except those expressly designated by IBM, are the responsibility of the user.

IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY 10594
U.S.A.

Asia-Pacific users can inquire, in writing, to the IBM Director of Intellectual Property and Licensing, IBM World Trade Asia Corporation, 2-31 Roppongi 3-chome, Minato-ku, Tokyo 106, Japan.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact IBM Corporation, Department LZKS, 11400 Burnet Road, Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee.

Trademarks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both: 

IBM
Multimedia Presentation Manager/2
OS/2
OS/2 Warp 
Personal System/2
PowerPC 
Presentation Manager 
PS/2
WIN-OS/2
Workplace Shell 
XGA

The following terms are trademarks of other companies:

Trademark Owner
ATI ATI Technologies, Inc.
Cirrus Logic Cirrus Logic, Inc.
MASM Microsoft Corporation
PCMCIA Personal Computer Memory Card International Association
S3 S3 Incorporated
SVPMI Super VGA Protect Mode Interface
VDM Geographics Systems, Ltd.
VESA Video Electronics Standards Association
Viper VLB Diamond Computer Systems, Inc.
Weitek Weitek Corporation

Windows is a trademark of Microsoft Corporation

Other company, product, and service names, which may be denoted by a double asterisk (**), may be trademarks or service marks of others.

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