Graphics Adapter Device Driver Reference: Difference between revisions
| Line 19,835: | Line 19,835: | ||
==Glossary Listing == | ==Glossary Listing == | ||
=== Glossary - A === | === Glossary - A === | ||
Revision as of 17:04, 8 November 2014
By IBM
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 DriversThis chapter briefly describes the design philosophy of the GRADD Model.
GRADD Model ComponentsThis chapter provides details on each of the components and how they work together within the GRADD Model.
Video ManagerThis chapter contains a list of the Video Manager Interface functions, as well as a detailed description of each.
Graphics Adapter Device DriversThis 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 FunctionsThis 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 InterfaceThis 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
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
�The MMPM/2 Device Driver Reference (Multimedia)
To order the DDK call:
/----------------------------------------------------------------\ |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 | \----------------------------------------------------------------/
Introduction to Graphics Adapter Device Drivers
This chapter briefly describes the design and intent of the Graphics Adapter Device Driver (GRADD) model. Details on specific components of the GRADD model are located in GRADD Model Components.
The GRADD model is divided into several components that work together on the same desktop to support a variety of operating system services for OS/2 Warp. GRADD components include the following:
�Video Manager and the Video Manager Interface (VMI) protocol
�Translation layers, one for each graphics engine in OS/2 Warp
�SOFTDRAW for default software simulation of graphics functions
�GRADDs and the Graphics Hardware Interface (GHI) protocol
GRADDs support all the graphics subsystems designed to run on OS/2 Warp. A GRADD contains only the hardware-dependent code required for graphic functions that are common among different graphics subsystems. These common functions are designed to act as a small set of building blocks for the larger, more complex operations that are typically required by a graphics engine. The translation layers that exist between the graphics subsystems and the components of the GRADD model provide access to the GRADD building blocks. The transition layer converts the complex function calls issued by a graphics subsystem into the protocol required by the GRADD model.
By reducing the set of mandatory functions required within a GRADD, this model makes video display driver development easier and faster than it was for OS/2 Releases 2.1 and earlier. The only mandatory GHI functions in the GRADD architecture are initialization, return capabilities, return mode information, mode setting, and palette setting (if using 256 colors).
Graphics adapter support for direct access to video memory renders all other GHI functions optional. The GRADD model uses a software library called SOFTDRAW to simulate drawing functions (such as drawing bit maps and lines, and handling pointer support). Software simulation allows developers to write a driver in incremental stages. Once the mandatory functions are written, a developer can use SOFTDRAW for optional functions that have not been written to use the accelerated features of the hardware. When an optional function is handled by a GRADD, the results can be compared with the results of the software simulation. This comparison gives developers a way to ensure that their GRADDs are producing correct output.
Most developers who write device drivers based on the GRADD model will be required to create only the hardware-specific code confined exclusively to the GRADD module. In the GRADD model, components that do not need direct access to the hardware are not located in the GRADD. This modular design makes it possible for developers to write new device drivers easily and quickly.
GRADD Model Components
This chapter describes the individual components of the Graphics ADapter Device (GRADD) driver model used for developing device drivers.
The GRADD model is composed of several components that coordinate the communication among each graphic subsystem and the available graphics hardware. The components include the following:
Video Manager (VMAN) The VMAN component binds the GRADD model components together. VMAN synchronizes the communication between translation layers and a GRADD and also manages the graphics pointer.
When an operating system service requests a graphics operation, the associated translation layer sends one of the defined Video Manager Interface (VMI) commands to VMAN. On receiving a VMI command, VMAN either handles the request or sends it down to the appropriate GRADD. For more information about VMAN, refer to Video Manager (VMAN).
Translation Layers A translation layer exists for each graphics engine in OS/2 Warp. The translation layer converts the function calls made by the graphics engine to the VMI protocol required by VMAN. For more information about transition layers, refer to Translation Layers.
SOFTDRAW SOFTDRAW is the default for any simulated graphics functions for nonaccelerated graphics operations.
Acting as a graphics library, SOFTDRAW exports the base drawing functions ( SDBitBlt and SDLine) used by VMAN to simulate graphics operations. SOFTDRAW provides a generic graphics library. Given a pointer to a linear address (a VRAM bit map or system-memory bit map), SOFTDRAW can draw the bits directly into the bit map.
Graphics Adapter Device Driver The GRADDs represent the available video hardware. They execute the requested operation or returns it for simulation.
When a GRADD receives a GHI function call from VMAN that is not mandatory, the GRADD has the option of performing the requested operation or returning the request to VMAN with a return code of RC_SIMULATE. The RC_SIMULATE return code informs VMAN that the operation needs to be simulated in software. For more information about GRADDs, refer to Graphics Adapter Device Driver (GRADD).
The following figure graphically illustrates the components of the GRADD model. [Artwork not shown]
Video Manager (VMAN)
This section describes how the Video Manager (VMAN) component fits into the GRADD model.
When VMAN is initialized, a series of components are loaded and initialized . These components include SOFTDRAW and the GRADDs required for the available graphics adapters (each graphics adapter may require more than one GRADD).
The GRADD model supports multiple GRADDs. If a developer wants to extend the GRADD model or to filter out operations, a filter GRADD can be placed between VMAN and the primary GRADD running the hardware. This form of linking GRADDs is called chainingand provides a way of modifying a GRADD's behavior without rewriting and recompiling the GRADD. "Adding Extensions" in Graphics Adapter Device Driversdiscusses the specifics involved when extending the GRADD architecture.
Video Manager Interface (VMI)
The VMAN component relies on a special protocol, called the Video Manager Interface (VMI), to receive requests from the translation layers. VMI consists of a small set of operations, each identified by a unique function number. Separate function numbers are required for each operation because VMAN exports only one entry point for the translation layers to communicate with VMAN. This exported function is called VMIEntry. VMIEntry expects four parameters from each function call it receives from a translation layer.
Because the VMIEntry function receives many different types of requests from the translation layers, the gidprovides an ID number that identifies the GRADD to receive the operation and the ulFunctionprovides a function number that identifies the requested operation. The last two parameters ( pIn, pOut) pointer to input and output data structures that are unique to each VMI function.
Most of the requests VMAN receives from a translation layer are passed directly to the appropriate GRADD. Each GRADD has its own exported function , called HWEntry, which is the same function type as VMIEntry (see Graphics Adapter Device Driversfor more information about GHI protocol).
Pointer Management in the Video Manager
VMAN is responsible for pointer management. When a pointer movement occurs, VMAN is notified by the VMI_CMD_MOVEPTRfunction. VMAN calls down the GRADD chain for the pointer update. The GRADD can either update the pointer or return to VMAN for simulation. If RC_SIMULATE is returned, VMAN uses the regular bitblit command to simulate the pointer movement.
VMAN tracks information about the current state of the pointer. All drawing VMI commands that affect the display surface must include the areas of the screen being updated by the primitive. VMAN uses this information to determine whether or not the pointer should be hidden before it passes a drawing request down the GRADD chain. On return from the drawing command, VMAN will restore the pointer if it was previously hidden.
Video Helper Functions
VMAN exports a number of helper services that GRADDs may use for common required functions. By using video helpers, a GRADD can avoid operating system specific calls. These helper functions are described below:
The VHAllocMemhelper returns a 32-bit pointer to a piece of memory. The caller of this function supplies the byte count required.
The VHFreeMemhelper frees memory that has been allocated via the VHAllocMem helper.
The VHLockMemhelper makes code or data segments available for ring 0 interrupt-time processing.
The VHPhystoVirthelper converts physical address ranges to linear virtual address ranges for processes using VMI.
The VHMaphelper aliases process memory to a global ring 0 context.
The VHMapVRAMhelper converts the physical address of VRAM to linear virtual aperture for both process and global ring 0 context.
Translation Layers
Translation layers use the CHAININFOstructure to gain access to the hardware capabilities and available modes. The VMI_CMD_QUERYCHAININFOfunction returns the CHAININFO structure.
When the VMIEntryfunction receives an operation from a translation layer, VMAN checks the function number and either handles the operation or forwards it to the appropriate GRADD. VMAN will handle the operation if the GRADD returns an RC_SIMULATE. The GRADD Model diagram shows how the VMAN component handles communication among the various components and the paths that commands can take during processing.
Translation Layer between OS/2 Graphics Engine and VMAN
The translation layer for the OS/2 Graphics Engine (GRE) is called GRE2VMAN . For a system that uses OS/2 as the dominant operating system service, GRE2VMAN is the first translation layer and the first component of the GRADD model to be loaded. When GRE2VMAN is loaded, it calls VMAN's VMIEntry function with a VMI_CMD_INIT. When VMAN receives a VMI_CMD_INIT for the first time, it loads the other GRADD model components.
Virtual VMI Device Driver (VVMI)
Video Manager (VMAN) creates a thread which is used to process all VMAN requests from the VDM. This thread is blocked by VVMI until a request is made, at which time the thread is unblocked and the request is serviced by VMAN.
Future Translation Layers
In the future, other graphics subsystems can be adapted to work in the IBM Operating System/2 operating system. To accomplish this, a translation layer must be provided (shown as 'n2VMAN' in the GRADD Model diagram). This translation layer must map the graphics primitives of the graphics subsystem to the appropriate VMI_CMD_ functions.
Translation Layer for Extensions
The GRADD Model can be extended using the VMI extension protocol. Using this protocol, a translation layer directs extension functions to a GRADD through the VMI_CMD_EXTENSIONfunction. In order to accomplish this, a translation layer must be provided (shown as 'EXT2VMAN' in the GRADD Model diagram).
See Adding Extensionsfor more information.
Graphics Adapter Device Driver (GRADD)
This section describes how the Graphics Adapter Device Driver components interface with VMAN.
Graphics Hardware Interface (GHI)
The entry point and functions supported by a GRADD are referred to as the Graphics Hardware Interface (GHI). The differences between the VMAN protocol (VMI) and the protocol for the GRADDs GHI include the following:
�The GHI is a subset of the VMI.
�The ulFunctionparameter value changes to the appropriate GHI_CMD_ function name.
Each GRADD has an exported function, called HWEntry, which is the same function type as VMIEntryin VMAN.
HWEntry receives all of the operations from VMAN.
In the GRADD model, the GRADDs are the only components that have direct access to the video hardware. GRADD code uses the accelerated features of a graphics adapter. By returning RC_SIMULATE for a graphics operation, the GRADD gives the SOFTDRAW component permission to draw directly to the video memory of the hardware. The serialization of video memory is handled by the Video Manager through the the GHI_CMD_REQUESTHWfunction.
Each GRADD must process the following GHI_CMD_ functions:
�GHI_CMD_INIT
�GHI_CMD_QUERYCAPS
�GHI_CMD_QUERYMODES
�GHI_CMD_SETMODE
�GHI_CMD_PALETTE
- This function is mandatory only when a 256-color mode has been chosen.
The following GHI functions can return RC_SIMULATE and let VMAN handle the operations:
�GHI_CMD_BANK
�GHI_CMD_BITBLT
�GHI_CMD_LINE
�GHI_CMD_MOVEPTR
�GHI_CMD_SETPTR
�GHI_CMD_SHOWPTR
�GHI_CMD_TEXT
The GHI function numbers are assigned in such a way that they can be used as a zero-based index into a function jump table.
Systems Management (RAS)
Because performance is critical in a video graphics subsystem, all systems management and RAS hooks should be placed in a filter GRADD. This protects the majority of users, who do not need this support, from performance degradations caused by the addition of trace points and hooks.
Video Manager
This chapter describes the functions, called by the Video Manager (VMAN), that are designated by the prefix VMI_CMD_. Refer to Graphics Adapter Device Driversfor descriptions of the Graphics Hardware Interface functions and to Enhanced Direct Interface Video Extension (EnDIVE) Functionsfor descriptions of the EnDIVE functions.
VMI_CMD_xx Functions and GHI_CMD_xx Functions
There are only a few differences between the VMAN protocol, Video Manager Interface (VMI), and the GRADD protocol, Graphics Hardware Interface (GHI). In fact, the majority of the functions are identical, with only the prefix (VMI or GHI) indicating to which component the function belongs.
The common functions are as follows:
/-------------------------------------------------------------\ |VMI |GHI | |------------------------------+------------------------------| |VMI_CMD_BANK |GHI_CMD_BANK | |------------------------------+------------------------------| |VMI_CMD_BITBLT |GHI_CMD_BITBLT | |------------------------------+------------------------------| |VMI_CMD_EVENT |GHI_CMD_EVENT | |------------------------------+------------------------------| |VMI_CMD_EXTENSION |GHI_CMD_EXTENSION | |------------------------------+------------------------------| |VMI_CMD_INIT |GHI_CMD_INIT | |------------------------------+------------------------------| |VMI_CMD_INITPROC |GHI_CMD_INITPROC | |------------------------------+------------------------------| |VMI_CMD_LINE |GHI_CMD_LINE | |------------------------------+------------------------------| |VMI_CMD_MOVEPTR |GHI_CMD_MOVEPTR | |------------------------------+------------------------------| |VMI_CMD_PALETTE |GHI_CMD_PALETTE | |------------------------------+------------------------------| |VMI_CMD_QUERYCAPS |GHI_CMD_QUERYCAPS | |------------------------------+------------------------------| |VMI_CMD_QUERYMODES |GHI_CMD_QUERYMODES | |------------------------------+------------------------------| |VMI_CMD_REQUESTHW |GHI_CMD_REQUESTHW | |------------------------------+------------------------------| |VMI_CMD_SETMODE |GHI_CMD_SETMODE | |------------------------------+------------------------------| |VMI_CMD_SETPTR |GHI_CMD_SETPTR | |------------------------------+------------------------------| |VMI_CMD_SHOWPTR |GHI_CMD_SHOWPTR | |------------------------------+------------------------------| |VMI_CMD_TERM |GHI_CMD_TERM | |------------------------------+------------------------------| |VMI_CMD_TERMPROC |GHI_CMD_TERMPROC | |------------------------------+------------------------------| |VMI_CMD_TEXT |GHI_CMD_TEXT | |------------------------------+------------------------------| |VMI_CMD_USERCAPS |GHI_CMD_USERCAPS | |------------------------------+------------------------------| |VMI_CMD_VRAM |GHI_CMD_VRAM | \-------------------------------------------------------------/
Note:The VMI_CMD_QUERYCHAININFOfunction has no corresponding GHI function.
VMAN and GRADD Entry Points
The main difference between the two types of functions (VMI_ and GHI_) is that the ulFunctionparameter in VMIEntryand HWEntrypoints to the respective VMI_ or GHI_ function name.
/-------------------------------------------------------------\ |VMI |GHI | |------------------------------+------------------------------| |VMIEntry |HWEntry | \-------------------------------------------------------------/
Video Helper Functions
The following list identifies the VMI video helper functions:
The Video Manager Interface Functions
The remainder of this chapter contains a detailed description of the Video Manager interface. Proceed to the following alphabetical list for a description of each function. Helper functions and entry points are included for easy reference.
VHAllocMem
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VHAllocMemreturns a 32-bit pointer to a piece of memory. The caller of this function supplies the byte count required. This function is a helper service for operations that are common across all GRADDs.
#include <GRADD.h> ULONG cBytes; /* Number of bytes of memory requested. */ PVOID pMem; /* Returned address of allocated memory, or NULL. */ pMem = VHAllocMem(cBytes);
VHAllocMem - Syntax
Description:
VHAllocMemreturns a 32-bit pointer to a piece of memory. The caller of this function supplies the byte count required. This function is a helper service for operations that are common across all GRADDs.
#include <GRADD.h> ULONG cBytes; /* Number of bytes of memory requested. */ PVOID pMem; /* Returned address of allocated memory, or NULL. */ pMem = VHAllocMem(cBytes);
VHAllocMem Parameter - cBytes
cBytes(ULONG) - input Number of bytes of memory requested.
Indicates the number of bytes of memory required for this allocation request.
VHAllocMem Return Value - pMem
pMem(PVOID) - returns Return value.
Success Returns pointer to allocated memory.
Error Returns NULL pointer.
VHAllocMem - Parameters
cBytes(ULONG) - input Number of bytes of memory required.
Indicates the number of bytes of memory required for this allocation request.
pMem(PVOID) - returns Return value.
Success Returns pointer to allocated memory.
Error Returns NULL pointer.
VHAllocMem - Remarks
Memory is valid across all processes.
VHAllocMem - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VHFreeMem
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VHFreeMemfrees memory that has been allocated via the VHAllocMem helper. This function is a helper service for operations that are common across all GRADDs.
#include <GRADD.h> PVOID pMem; /* Pointer to previous memory allocation. */ ULONG rc; /* Return codes. */ rc = VHFreeMem(pMem);
VHFreeMem - Syntax
Description:
VHFreeMemfrees memory that has been allocated via the VHAllocMem helper. This function is a helper service for operations that are common across all GRADDs.
#include <GRADD.h> PVOID pMem; /* Pointer to previous memory allocation. */ ULONG rc; /* Return codes. */ rc = VHFreeMem(pMem);
VHFreeMem Parameter - pMem
pMem(PVOID) - input Pointer to memory previously allocated via VHAllocMem.
VHFreeMem Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VHFreeMem - Parameters
pMem(PVOID) - input Pointer to memory previously allocated using VHAllocMem.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VHFreeMem - Remarks
None.
VHFreeMem - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VHLockMem
Select an item:
Syntax Parameters Returns Glossary
Description:
VHLockMemmakes code or data segments available for ring 0 interrupt-time processing. At interrupt time, code and data segments must be non-swappable and accessible from the ring 0 context.
#include <GRADD.h> PVOID pAddress; /* Address within the first page of code or data. */ ULONG ulLength; /* Size of code or data segment. */ BOOL fData; /* FALSE indicates code segment; TRUE indicates data segment. */ ULONG rc; /* Return value. */ rc = VHLockMem(pAddress, ulLength, fData);
VHLockMem - Syntax
Description:
VHLockMemmakes code or data segments available for ring 0 interrupt-time processing. At interrupt time, code and data segments must be non-swappable and accessible from the ring 0 context.
#include <GRADD.h> PVOID pAddress; /* Address within the first page of code or data. */ ULONG ulLength; /* Size of code or data segment. */ BOOL fData; /* FALSE indicates code segment; TRUE indicates data segment. */ ULONG rc; /* Return value. */ rc = VHLockMem(pAddress, ulLength, fData);
VHLockMem Parameter - pAddress
pAddress(PVOID) - input Address within the first page of code or data.
VHLockMem Parameter - ulLength
ulLength(ULONG) - input Size of code or data segment.
VHLockMem Parameter - fData
fData(BOOL) - input FALSE indicates code segment; TRUE indicates data segment.
VHLockMem Return Value - rc
rc(ULONG) - returns Return value.
Non-zero lockhandle indicates success; zero indicates error.
VHLockMem - Parameters
pAddress(PVOID) - input Address within the first page of code or data.
ulLength(ULONG) - input Size of code or data segment.
fData(BOOL) - input FALSE indicates code segment; TRUE indicates data segment.
rc(ULONG) - returns Return value.
Non-zero lockhandle indicates success; zero indicates error.
VHLockMem - Topics
Select an item:
Syntax Parameters Returns Glossary
VHPhysToVirt
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VHPhysToVirtconverts physical address ranges to linear virtual address ranges for processes using VMI.
#include <GRADD.h> PMEMINFO pMemInfo; /* Pointer to linked list of MEMINFO structures defining address ranges. */ ULONG rc; rc = VHPhysToVirt (pMemInfo);
VHPhysToVirt - Syntax
Description:
VHPhysToVirtconverts physical address ranges to linear virtual address ranges for processes using VMI.
#include <GRADD.h> PMEMINFO pMemInfo; /* Pointer to linked list of MEMINFO structures defining address ranges. */ ULONG rc; rc = VHPhysToVirt (pMemInfo);
VHPhysToVirt Parameter - pMemInfo
pMemInfo(PMEMINFO) - input Pointer to linked list of MEMINFOstructures defining address ranges.
VHPhysToVirt Return Value - rc
rc(ULONG) - returns Return codes.
VHPhysToVirt - Parameters
pMemInfo(PMEMINFO) - input Pointer to linked list of MEMINFOstructures defining address ranges.
rc(ULONG) - returns Return codes.
VHPhysToVirt - Remarks
Linear virtual address ranges are valid for all processes.
VHPhysToVirt - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VHMap
Select an item:
Syntax Parameters Returns Glossary
Description:
VHMapaliases process memory to a global ring 0 context.
#include <GRADD.h> PVOID pAddress; /* Address within the first page of code or data. */ ULONG ulLength; /* Size of code or data segment. */ ULONG rc; /* Return value. */ rc = VHMap(pAddress, ulLength);
VHMap - Syntax
Description:
VHMapaliases process memory to a global ring 0 context.
#include <GRADD.h> PVOID pAddress; /* Address within the first page of code or data. */ ULONG ulLength; /* Size of code or data segment. */ ULONG rc; /* Return value. */ rc = VHMap(pAddress, ulLength);
VHMap Parameter - pAddress
pAddress(PVOID) - input Address within the first page of code or data.
VHMap Parameter - ulLength
ulLength(ULONG) - input Size of code or data segment.
VHMap Return Value - rc
rc(ULONG) - returns Return value.
Non-zero indicates ring 0 alias address; zero indicates error.
VHMap - Parameters
pAddress(PVOID) - input Address within the first page of code or data.
ulLength(ULONG) - input Size of code or data segment.
rc(ULONG) - returns Return value.
Non-zero indicates ring 0 alias address; zero indicates error.
VHMap - Topics
Select an item:
Syntax Parameters Returns Glossary
VHMapVRAM
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VHMapVRAMconverts the physical address of VRAM to linear virtual aperture for both process and global ring 0 context.
#include <GRADD.h>
ULONG ulPhysAddr; /* Physical address of the start of the VRAM aperture. */
ULONG ulLength; /* Length of VRAM aperture. */
PBYTE *pVRAM; /* Returned process virtual linear aperture pointer. */
PBYTE *pVRAMRing0; /* Returned ring 0 virtual linear aperture pointer. */
ULONG rc; /* Return value. */
rc = VHMapVRAM(ulPhysAddr, ulLength, pVRAM,
pVRAMRing0);
VHMapVRAM - Syntax
Description:
VHMapVRAMconverts the physical address of VRAM to linear virtual aperture for both process and global ring 0 context.
#include <GRADD.h>
ULONG ulPhysAddr; /* Physical address of the start of the VRAM aperture. */
ULONG ulLength; /* Length of VRAM aperture. */
PBYTE *pVRAM; /* Returned process virtual linear aperture pointer. */
PBYTE *pVRAMRing0; /* Returned ring 0 virtual linear aperture pointer. */
ULONG rc; /* Return value. */
rc = VHMapVRAM(ulPhysAddr, ulLength, pVRAM,
pVRAMRing0);
VHMapVRAM Parameter - ulPhysAddr
ulPhysAddr(ULONG) - input Physical address of the start of the VRAM aperture.
VHMapVRAM Parameter - ulLength
ulLength(ULONG) - input Length of VRAM aperture.
VHMapVRAM Parameter - pVRAM
pVRAM(PBYTE *) - output Returned process virtual linear aperture pointer.
VHMapVRAM Parameter - pVRAMRing0
pVRAMRing0(PBYTE *) - output Returned ring 0 virtual linear aperture pointer.
VHMapVRAM Return Value - rc
rc(ULONG) - returns Return value.
RC_SUCCESS or RC_ERROR.
VHMapVRAM - Parameters
ulPhysAddr(ULONG) - input Physical address of the start of the VRAM aperture.
ulLength(ULONG) - input Length of VRAM aperture.
pVRAM(PBYTE *) - output Returned process virtual linear aperture pointer.
pVRAMRing0(PBYTE *) - output Returned ring 0 virtual linear aperture pointer.
rc(ULONG) - returns Return value.
RC_SUCCESS or RC_ERROR.
VHMapVRAM - Remarks
VHMapVRAM must be used instead of VHPhysToVirt() and VHMap() for the frame buffer so that the ring 0 address is available for SoftDraw. For other physical memory areas needed by GRADD at interrupt time, use VHPhysToVirt() and VHMap().
The ulPhysAddr and ulLength parameters for VHMapVRAM() and VHPhysToVirt() are usually obtained from the VIDEOPMI function PMIREQUEST_SETMODE.
VHMapVRAM - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMIEntry
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMIEntryis the single exported function from the Video Manager component. It is part of the Video Manager Interface (VMI) protocol and receives operations from the translation layer components.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set to appropriate VMI_CMD_ function. */ PVOID pIn; /* Pointer to applicable data structure. */ PVOID pOut; /* Pointer to applicable data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMIEntry - Syntax
Description:
VMIEntryis the single exported function from the Video Manager component. It is part of the Video Manager Interface (VMI) protocol and receives operations from the translation layer components.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set to appropriate VMI_CMD_ function. */ PVOID pIn; /* Pointer to applicable data structure. */ PVOID pOut; /* Pointer to applicable data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMIEntry Parameter - gid
gid(GID) - input ID of the GRADD.
VMIEntry Parameter - ulFunction
ulFunction(ULONG) - input Set to appropriate VMI_CMD_ function.
This parameter is set to one of the VMI_CMD_ functions shown in the table of common functions shown at the beginning of this section.
VMIEntry Parameter - pIn
pIn(PVOID) - input Pointer to applicable data structure.
VMIEntry Parameter - pOut
pOut(PVOID) - output Pointer to applicable data structure.
VMIEntry Return Value - rc
rc(ULONG) - returns Return codes.
Valid values are dictated by the applicable VMI_CMD_ function.
VMIEntry - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set to appropriate VMI_CMD_ function.
This parameter is set to one of the VMI_CMD_ functions shown in the table of common functions shown at the beginning of this section.
pIn(PVOID) - input Pointer to applicable data structure.
pOut(PVOID) - output Pointer to applicable data structure.
rc(ULONG) - returns Return codes.
Valid values are dictated by the applicable VMI_CMD_ function.
VMIEntry - Remarks
None.
VMIEntry - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_BANK
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_BANKis called to set or get the region or bank number of the video display. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_BANK. */ PVOID pIn; /* Pointer to a HWBANKIN data structure. */ PVOID pOut; /* Pointer to HWBANKOUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_BANK - Syntax
Description:
VMI_CMD_BANKis called to set or get the region or bank number of the video display. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_BANK. */ PVOID pIn; /* Pointer to a HWBANKIN data structure. */ PVOID pOut; /* Pointer to HWBANKOUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_BANK Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_BANK Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_BANK.
VMI_CMD_BANK Parameter - pIn
pIn(PVOID) - input Pointer to a HWBANKINdata structure.
VMI_CMD_BANK Parameter - pOut
pOut(PVOID) - output Pointer to HWBANKOUTdata structure.
VMI_CMD_BANK Return Value - rc
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SUCCESS
RC_UNSUPPORTED
VMI_CMD_BANK - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_BANK.
pIn(PVOID) - input Pointer to a HWBANKINdata structure.
pOut(PVOID) - output Pointer to HWBANKOUTdata structure.
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SUCCESS
RC_UNSUPPORTED
VMI_CMD_BANK - Remarks
None.
VMI_CMD_BANK - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_BITBLT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_BITBLTis called to blit a rectangle or series of rectangles to or from the video display. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_BITBLT. */ PVOID pIn; /* Pointer to a BITBLTINFO data structure. */ PVOID pOut; /* Null; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_BITBLT - Syntax
Description:
VMI_CMD_BITBLTis called to blit a rectangle or series of rectangles to or from the video display. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_BITBLT. */ PVOID pIn; /* Pointer to a BITBLTINFO data structure. */ PVOID pOut; /* Null; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_BITBLT Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_BITBLT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_BITBLT.
VMI_CMD_BITBLT Parameter - pIn
pIn(PVOID) - input Pointer to a BITBLTINFOdata structure.
VMI_CMD_BITBLT Parameter - pOut
pOut(PVOID) - output Null; no output structure needed.
VMI_CMD_BITBLT Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_BITBLT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_BITBLT.
pIn(PVOID) - input Pointer to a BITBLTINFOdata structure.
pOut(PVOID) - output Null; no output structure needed.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_BITBLT - Remarks
None.
VMI_CMD_BITBLT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_EVENT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_EVENTis called to notify a GRADD of specific events. VMAN sends this command directly to the GRADD chain identified by the GRADD ID.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_EVENT. */ PVOID pIn; /* Pointer to an HWEVENTIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_EVENT - Syntax
Description:
VMI_CMD_EVENTis called to notify a GRADD of specific events. VMAN sends this command directly to the GRADD chain identified by the GRADD ID.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_EVENT. */ PVOID pIn; /* Pointer to an HWEVENTIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_EVENT Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_EVENT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_EVENT.
VMI_CMD_EVENT Parameter - pIn
pIn(PVOID) - input Pointer to an HWEVENTINdata structure.
VMI_CMD_EVENT Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
VMI_CMD_EVENT Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
VMI_CMD_EVENT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_EVENT.
pIn(PVOID) - input Pointer to an HWEVENTINdata structure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
VMI_CMD_EVENT - Remarks
None.
VMI_CMD_EVENT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_EXTENSION
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_EXTENSIONis called to send an extension command to a GRADD. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_EXTENSION. */ PVOID pIn; /* Pointer to an HWEXTENSION data structure. */ PVOID pOut; /* Pointer to an extension-specific output structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_EXTENSION - Syntax
Description:
VMI_CMD_EXTENSIONis called to send an extension command to a GRADD. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_EXTENSION. */ PVOID pIn; /* Pointer to an HWEXTENSION data structure. */ PVOID pOut; /* Pointer to an extension-specific output structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_EXTENSION Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_EXTENSION Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_EXTENSION.
VMI_CMD_EXTENSION Parameter - pIn
pIn(PVOID) - input Pointer to an HWEXTENSIONdata structure.
VMI_CMD_EXTENSION Parameter - pOut
pOut(PVOID) - output Pointer to an extension-specific output structure.
VMI_CMD_EXTENSION Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
VMI_CMD_EXTENSION - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_EXTENSION.
pIn(PVOID) - input Pointer to an HWEXTENSIONdata structure.
pOut(PVOID) - output Pointer to an extension-specific output structure.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
VMI_CMD_EXTENSION - Remarks
None.
VMI_CMD_EXTENSION - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_INIT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_INITinforms the Video Manager (VMAN) that a translation layer has been loaded and that VMAN may need to be initialized. VMAN initializes itself once only; subsequent VMI_CMD_INIT calls are ignored.
During the first initialization, VMAN loads SOFTDRAW and all of the GRADDs specified by the environment variables.
#include <GRADD.h> GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_INIT. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMI_CMD_INIT - Syntax
Description:
VMI_CMD_INITinforms the Video Manager (VMAN) that a translation layer has been loaded and that VMAN may need to be initialized. VMAN initializes itself once only; subsequent VMI_CMD_INIT calls are ignored.
During the first initialization, VMAN loads SOFTDRAW and all of the GRADDs specified by the environment variables.
#include <GRADD.h> GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_INIT. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMI_CMD_INIT Parameter - gid
gid(GID) - input NULL.
VMI_CMD_INIT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_INIT.
VMI_CMD_INIT Parameter - pIn
pIn(PVOID) - input NULL.
VMI_CMD_INIT Parameter - pOut
pOut(PVOID) - output NULL.
VMI_CMD_INIT Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_INIT - Parameters
gid(GID) - input NULL.
ulFunction(ULONG) - input Set equal to VMI_CMD_INIT.
pIn(PVOID) - input NULL.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_INIT - Remarks
None.
VMI_CMD_INIT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_INITPROC
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_INITPROCinforms VMAN that a new process is being initialized. It indicates that this new process intends to be a client of the VMAN component.
VMAN ensures that all data and code is valid under this new process.
#include <GRADD.h> GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_INITPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an INITPROCOUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMI_CMD_INITPROC - Syntax
Description:
VMI_CMD_INITPROCinforms VMAN that a new process is being initialized. It indicates that this new process intends to be a client of the VMAN component.
VMAN ensures that all data and code is valid under this new process.
#include <GRADD.h> GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_INITPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an INITPROCOUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMI_CMD_INITPROC Parameter - gid
gid(GID) - input NULL.
VMI_CMD_INITPROC Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_INITPROC.
VMI_CMD_INITPROC Parameter - pIn
pIn(PVOID) - input NULL.
VMI_CMD_INITPROC Parameter - pOut
pOut(PVOID) - output Pointer to an INITPROCOUTdata structure.
VMI_CMD_INITPROC Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_INITPROC - Parameters
gid(GID) - input NULL.
ulFunction(ULONG) - input Set equal to VMI_CMD_INITPROC.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to an INITPROCOUTdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_INITPROC - Remarks
None.
VMI_CMD_INITPROC - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_LINE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_LINEis called to draw a line to the video display. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_LINE. */ PVOID pIn; /* Pointer to a LINEINFO or LINEINFO2 data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_LINE - Syntax
Description:
VMI_CMD_LINEis called to draw a line to the video display. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_LINE. */ PVOID pIn; /* Pointer to a LINEINFO or LINEINFO2 data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_LINE Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_LINE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_LINE.
VMI_CMD_LINE Parameter - pIn
pIn(PVOID) - input Pointer to a LINEINFOor LINEINFO2data structure.
VMI_CMD_LINE Parameter - pOut
pOut(PVOID) - output NULL; no output structure is needed.
VMI_CMD_LINE Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_LINE - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_LINE.
pIn(PVOID) - input Pointer to a LINEINFOor LINEINFO2data structure.
pOut(PVOID) - output NULL; no output structure is needed.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_LINE - Remarks
The LINEINFOstructure can describe a sequence of line segments where each line segment may be clipped. The LINEINFO2structure describes a sequence of line segments where only the start of the first segment and the end of the last segment may be clipped. For many cases, the simpler LINEINFO2 data can be generated more efficiently than for the more general LINEINFO data.
The LINEINFO and LINEINFO2 structures can be differentiated using the ulLength field at the start of each structure.
Since the LINEINFO2 mechanism was defined after several GRADDs were already released, a LINEINFO2 structure will not be passed to a GRADD unless the GRADD sets the DS_SIMPLE_LINES flag in the ulFCFlags member of the CAPSINFOstructure returned for the GHI_CMD_QUERYCAPSfunction. Note that if a GRADD indicates it can handle the LINEINFO2 structure, it may still be passed a LINEINFO structure when that generality is needed.
VMI_CMD_LINE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_MOVEPTR
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_MOVEPTRis called to change the position of the pointer hot spot. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_MOVEPTR. */ PVOID pIn; /* Pointer to an HWMOVEPTRIN data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_MOVEPTR - Syntax
Description:
VMI_CMD_MOVEPTRis called to change the position of the pointer hot spot. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_MOVEPTR. */ PVOID pIn; /* Pointer to an HWMOVEPTRIN data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_MOVEPTR Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_MOVEPTR Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_MOVEPTR.
VMI_CMD_MOVEPTR Parameter - pIn
pIn(PVOID) - input Pointer to an HWMOVEPTRINdata structure.
VMI_CMD_MOVEPTR Parameter - pOut
pOut(PVOID) - output NULL; no output structure is needed.
VMI_CMD_MOVEPTR Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_MOVEPTR - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_MOVEPTR.
pIn(PVOID) - input Pointer to an HWMOVEPTRINdata structure.
pOut(PVOID) - output NULL; no output structure is needed.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_MOVEPTR - Remarks
None.
VMI_CMD_MOVEPTR - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_PALETTE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
This function is called to query or set the hardware color palette. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
The GRADD is expected to respond by describing the palette in a given array or by using the palette given in the array. The GRADD is always given an HWPALETTEINFOstructure with either the PALETTE_GET or PALETTE_SET flag to specifiy the operation to perform.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_PALETTE. */ PVOID pIn; /* Pointer to an HWPALETTEINFO data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_PALETTE - Syntax
Description:
This function is called to query or set the hardware color palette. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
The GRADD is expected to respond by describing the palette in a given array or by using the palette given in the array. The GRADD is always given an HWPALETTEINFOstructure with either the PALETTE_GET or PALETTE_SET flag to specifiy the operation to perform.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_PALETTE. */ PVOID pIn; /* Pointer to an HWPALETTEINFO data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_PALETTE Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_PALETTE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_PALETTE.
VMI_CMD_PALETTE Parameter - pIn
pIn(PVOID) - input Pointer to an HWPALETTEINFOdata structure.
VMI_CMD_PALETTE Parameter - pOut
pOut(PVOID) - output NULL; no output structure is needed.
VMI_CMD_PALETTE Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_PALETTE - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_PALETTE.
pIn(PVOID) - input Pointer to an HWPALETTEINFOdata structure.
pOut(PVOID) - output NULL; no output structure is needed.
If '_SET' is specified by pIn, pOutIf '_GET' is specified by pIn, pOutis a pointer to an HWPALETTEINFOdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_PALETTE - Remarks
None.
VMI_CMD_PALETTE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_QUERYCAPS
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_QUERYCAPSreturns the capabilities of a particular GRADD. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
VMI_CMD_QUERYCAPS is not typically used by translation layers because the VMI_CMD_QUERYCHAININFOfunction returns the capabilities of allGRADDs, as opposed to just one. VMI_CMD_QUERYCHAININFO is the recommended way of querying the capabilities of all GRADDs in the system.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYCAPS. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a CAPSINFO data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_QUERYCAPS - Syntax
Description:
VMI_CMD_QUERYCAPSreturns the capabilities of a particular GRADD. VMAN sends this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
VMI_CMD_QUERYCAPS is not typically used by translation layers because the VMI_CMD_QUERYCHAININFOfunction returns the capabilities of allGRADDs, as opposed to just one. VMI_CMD_QUERYCHAININFO is the recommended way of querying the capabilities of all GRADDs in the system.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYCAPS. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a CAPSINFO data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_QUERYCAPS Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_QUERYCAPS Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_QUERYCAPS.
VMI_CMD_QUERYCAPS Parameter - pIn
pIn(PVOID) - input NULL.
VMI_CMD_QUERYCAPS Parameter - pOut
pOut(PVOID) - output Pointer to a CAPSINFOdata structure.
VMI_CMD_QUERYCAPS Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_QUERYCAPS - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_QUERYCAPS.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a CAPSINFOdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_QUERYCAPS - Remarks
None.
VMI_CMD_QUERYCAPS - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_QUERYCHAININFO
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_QUERYCHAININFOis unique to VMAN (there is no corresponding function in the Graphics Hardware Interface). This function is called to obtain a pointer to the video chain information, which contains information about every GRADD currently loaded.
Each GRADDINFO structure contains information, such as capabilities and mode information, for a single GRADD. The CHAININFOstructure contains a pointer to a linked list of GRADDINFO structures. If multiple GRADD chains are in use, the head CHAININFO structure contains a pointer to the next CHAININFO structure.
#include <GRADD.h> GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYCHAININFO. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a VMIQCI data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMI_CMD_QUERYCHAININFO - Syntax
Description:
VMI_CMD_QUERYCHAININFOis unique to VMAN (there is no corresponding function in the Graphics Hardware Interface). This function is called to obtain a pointer to the video chain information, which contains information about every GRADD currently loaded.
Each GRADDINFO structure contains information, such as capabilities and mode information, for a single GRADD. The CHAININFOstructure contains a pointer to a linked list of GRADDINFO structures. If multiple GRADD chains are in use, the head CHAININFO structure contains a pointer to the next CHAININFO structure.
#include <GRADD.h> GID gid; /* NULL. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYCHAININFO. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a VMIQCI data structure. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMI_CMD_QUERYCHAININFO Parameter - gid
gid(GID) - input NULL.
VMI_CMD_QUERYCHAININFO Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_QUERYCHAININFO.
VMI_CMD_QUERYCHAININFO Parameter - pIn
pIn(PVOID) - input NULL.
VMI_CMD_QUERYCHAININFO Parameter - pOut
pOut(PVOID) - output Pointer to a VMIQCIdata structure.
VMI_CMD_QUERYCHAININFO Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_QUERYCHAININFO - Parameters
gid(GID) - input NULL.
ulFunction(ULONG) - input Set equal to VMI_CMD_QUERYCHAININFO.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a VMIQCIdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_QUERYCHAININFO - Remarks
None.
VMI_CMD_QUERYCHAININFO - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_QUERYMODES
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_QUERYMODESreturns video mode information for a particular GRADD. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
VMI_CMD_QUERYMODES is not typically used by translation layers because the VMI_CMD_QUERYCHAININFOfunction returns the supported modes of allGRADDs, as opposed to just one. VMI_CMD_QUERYCHAININFO is the recommended way of querying the available modes of all GRADDs in the system.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYMODES. */ PVOID pIn; /* Pointer that identifies a QUERYMODE operation. */ PVOID pOut; /* Pointer to the pIn operation. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMI_CMD_QUERYMODES - Syntax
Description:
VMI_CMD_QUERYMODESreturns video mode information for a particular GRADD. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
VMI_CMD_QUERYMODES is not typically used by translation layers because the VMI_CMD_QUERYCHAININFOfunction returns the supported modes of allGRADDs, as opposed to just one. VMI_CMD_QUERYCHAININFO is the recommended way of querying the available modes of all GRADDs in the system.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_QUERYMODES. */ PVOID pIn; /* Pointer that identifies a QUERYMODE operation. */ PVOID pOut; /* Pointer to the pIn operation. */ ULONG rc; /* Return codes. */ rc = VMIEntry(gid, ulFunction, pIn, pOut);
VMI_CMD_QUERYMODES Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_QUERYMODES Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_QUERYMODES.
VMI_CMD_QUERYMODES Parameter - pIn
pIn(PVOID) - input Pointer that identifies a QUERYMODE operation.
This pointer identifies one of the following operations:
QUERYMODE_NUM_MODES
QUERYMODE_MODE_DATA
VMI_CMD_QUERYMODES Parameter - pOut
pOut(PVOID) - output Pointer to the pInoperation.
This pointer indicates one of the following, depending on the value of pIn:
QUERYMODE_NUM_MODES Indicates a pointer to a ULONG containing the number of supported modes.
QUERYMODE_MODE_DATA Indicates a pointer to an array of GDDMODEINFOstructures large enough for the number of supported modes.
VMI_CMD_QUERYMODES Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_QUERYMODES - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_QUERYMODES.
pIn(PVOID) - input Pointer that identifies a QUERYMODE operation.
This pointer identifies one of the following operations:
QUERYMODE_NUM_MODES
QUERYMODE_MODE_DATA
pOut(PVOID) - output Pointer to the pInoperation.
This pointer indicates one of the following, depending on the value of pIn:
QUERYMODE_NUM_MODES Indicates a pointer to a ULONG containing the number of supported modes.
QUERYMODE_MODE_DATA Indicates a pointer to an array of GDDMODEINFOstructures large enough for the number of supported modes.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_QUERYMODES - Remarks
None.
VMI_CMD_QUERYMODES - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_REQUESTHW
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_REQUESTHWis called to request access to the video hardware. VMAN processes this command and sends a GHI_CMD_REQUESTHW call to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_REQUESTHW. */ PVOID pIn; /* Pointer to an HWREQIN data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_REQUESTHW - Syntax
Description:
VMI_CMD_REQUESTHWis called to request access to the video hardware. VMAN processes this command and sends a GHI_CMD_REQUESTHW call to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_REQUESTHW. */ PVOID pIn; /* Pointer to an HWREQIN data structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_REQUESTHW Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_REQUESTHW Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_REQUESTHW.
VMI_CMD_REQUESTHW Parameter - pIn
pIn(PVOID) - input Pointer to an HWREQINdata structure.
VMI_CMD_REQUESTHW Parameter - pOut
pOut(PVOID) - output NULL; no output structure is needed.
VMI_CMD_REQUESTHW Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_REQUESTHW - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_REQUESTHW.
pIn(PVOID) - input Pointer to an HWREQINdata structure.
pOut(PVOID) - output NULL; no output structure is needed.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_REQUESTHW - Remarks
None.
VMI_CMD_REQUESTHW - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_SETMODE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_SETMODEsets the video display adapter to a given mode. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller. The GRADD is expected to set the video mode, given an ID of the chosen mode.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SETMODE. */ PVOID pIn; /* Pointer to PULONG containing the ID of the requested mode. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_SETMODE - Syntax
Description:
VMI_CMD_SETMODEsets the video display adapter to a given mode. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller. The GRADD is expected to set the video mode, given an ID of the chosen mode.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SETMODE. */ PVOID pIn; /* Pointer to PULONG containing the ID of the requested mode. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_SETMODE Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_SETMODE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_SETMODE.
VMI_CMD_SETMODE Parameter - pIn
pIn(PVOID) - input Pointer to PULONG containing the ID of the requested mode.
VMI_CMD_SETMODE Parameter - pOut
pOut(PVOID) - output NULL.
VMI_CMD_SETMODE Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_SETMODE - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_SETMODE.
pIn(PVOID) - input Pointer to PULONG containing the ID of the requested mode.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_SETMODE - Remarks
None.
VMI_CMD_SETMODE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_SETPTR
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_SETPTRsets the pointer AND,XOR masks. VMAN sends this command to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SETPTR. */ PVOID pIn; /* Pointer to an HWSETPTRIN data structure. */ PVOID pOut; /* Pointer to an HWSETPTROUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_SETPTR - Syntax
Description:
VMI_CMD_SETPTRsets the pointer AND,XOR masks. VMAN sends this command to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SETPTR. */ PVOID pIn; /* Pointer to an HWSETPTRIN data structure. */ PVOID pOut; /* Pointer to an HWSETPTROUT data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_SETPTR Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_SETPTR Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_SETPTR.
VMI_CMD_SETPTR Parameter - pIn
pIn(PVOID) - input Pointer to an HWSETPTRINdata structure.
VMI_CMD_SETPTR Parameter - pOut
pOut(PVOID) - output Pointer to an HWSETPTROUTdata structure.
VMI_CMD_SETPTR Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_SETPTR - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_SETPTR.
pIn(PVOID) - input Pointer to an HWSETPTRINdata structure.
pOut(PVOID) - output Pointer to an HWSETPTROUTdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_SETPTR - Remarks
None.
VMI_CMD_SETPTR - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_SHOWPTR
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_SHOWPTRsets the visibility state of the pointer. VMAN sends this command to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SHOWPTR. */ PVOID pIn; /* Pointer to an HWSHOWPTRIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_SHOWPTR - Syntax
Description:
VMI_CMD_SHOWPTRsets the visibility state of the pointer. VMAN sends this command to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_SHOWPTR. */ PVOID pIn; /* Pointer to an HWSHOWPTRIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_SHOWPTR Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_SHOWPTR Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_SHOWPTR.
VMI_CMD_SHOWPTR Parameter - pIn
pIn(PVOID) - input Pointer to an HWSHOWPTRINdata structure.
VMI_CMD_SHOWPTR Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
VMI_CMD_SHOWPTR Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_SHOWPTR - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_SHOWPTR.
pIn(PVOID) - input Pointer to an HWSHOWPTRINdata structure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_SHOWPTR - Remarks
None.
VMI_CMD_SHOWPTR - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_TERM
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_TERMis called by a translation layer when it no longer requires the services of VMAN.
#include <GRADD.h> GID gid; /* NULL; parameter ignored by VMAN. */ ULONG ulFunction; /* Set equal to VMI_CMD_TERM. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_TERM - Syntax
Description:
VMI_CMD_TERMis called by a translation layer when it no longer requires the services of VMAN.
#include <GRADD.h> GID gid; /* NULL; parameter ignored by VMAN. */ ULONG ulFunction; /* Set equal to VMI_CMD_TERM. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_TERM Parameter - gid
gid(GID) - input NULL; parameter ignored by VMAN.
VMI_CMD_TERM Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_TERM.
VMI_CMD_TERM Parameter - pIn
pIn(PVOID) - input NULL.
VMI_CMD_TERM Parameter - pOut
pOut(PVOID) - output NULL.
VMI_CMD_TERM Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_TERM - Parameters
gid(GID) - input NULL; parameter ignored by VMAN.
ulFunction(ULONG) - input Set equal to VMI_CMD_TERM.
pIn(PVOID) - input NULL.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_TERM - Remarks
None.
VMI_CMD_TERM - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_TERMPROC
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_TERMPROCinforms VMAN that an existing client process is being terminated. VMAN cleans up all resources owned by this process. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_TERMPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_TERMPROC - Syntax
Description:
VMI_CMD_TERMPROCinforms VMAN that an existing client process is being terminated. VMAN cleans up all resources owned by this process. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_TERMPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_TERMPROC Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_TERMPROC Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_TERMPROC.
VMI_CMD_TERMPROC Parameter - pIn
pIn(PVOID) - input NULL.
VMI_CMD_TERMPROC Parameter - pOut
pOut(PVOID) - output NULL.
VMI_CMD_TERMPROC Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_TERMPROC - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_TERMPROC.
pIn(PVOID) - input NULL.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
VMI_CMD_TERMPROC - Remarks
None.
VMI_CMD_TERMPROC - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_TEXT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_TEXTis called to draw text to the video display. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_TEXT. */ PVOID pIn; /* Pointer to a TEXTBLTINFO data structure. */ PVOID pOut; /* Null; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_TEXT - Syntax
Description:
VMI_CMD_TEXTis called to draw text to the video display. VMAN passes this command directly to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_TEXT. */ PVOID pIn; /* Pointer to a TEXTBLTINFO data structure. */ PVOID pOut; /* Null; no output structure needed. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_TEXT Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_TEXT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_TEXT.
VMI_CMD_TEXT Parameter - pIn
pIn(PVOID) - input Pointer to a TEXTBLTINFOdata structure.
VMI_CMD_TEXT Parameter - pOut
pOut(PVOID) - output Null; no output structure needed.
VMI_CMD_TEXT Return Value - rc
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SIMULATE
RC_SUCCESS
RC_UNSUPPORTED
VMI_CMD_TEXT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_TEXT.
pIn(PVOID) - input Pointer to a TEXTBLTINFOdata structure.
pOut(PVOID) - output Null; no output structure needed.
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SIMULATE
RC_SUCCESS
RC_UNSUPPORTED
VMI_CMD_TEXT - Remarks
None.
VMI_CMD_TEXT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_USERCAPS
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_USERCAPSenables and supports the CAPABILITIES button on the OS/2 System Object.
When the Video Configuration Manager presents the interface to the user, each capability is presented in a separate window page of the capabilities notebook in System Object. The window layout depends on the capability type :
Boolean type is represented by a check box.
Aggregate type is represented by a list box.
The capability description appears as the title for that control.
VMAN accumulates capabilities for all GRADDs, and routes capability settings to the specific GRADD that supports certain capabilities.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunc; /* Set equal to VMI_CMD_USERCAPS. */ PUSERCAPSIN pIn; /* Pointer to a USERCAPSIN data structure. */ PVOID pOut; /* Pointer to a buffer area. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunc, pIn, pOut);
VMI_CMD_USERCAPS - Syntax
Description:
VMI_CMD_USERCAPSenables and supports the CAPABILITIES button on the OS/2 System Object.
When the Video Configuration Manager presents the interface to the user, each capability is presented in a separate window page of the capabilities notebook in System Object. The window layout depends on the capability type :
Boolean type is represented by a check box.
Aggregate type is represented by a list box.
The capability description appears as the title for that control.
VMAN accumulates capabilities for all GRADDs, and routes capability settings to the specific GRADD that supports certain capabilities.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunc; /* Set equal to VMI_CMD_USERCAPS. */ PUSERCAPSIN pIn; /* Pointer to a USERCAPSIN data structure. */ PVOID pOut; /* Pointer to a buffer area. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunc, pIn, pOut);
VMI_CMD_USERCAPS Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_USERCAPS Parameter - ulFunc
ulFunc(ULONG) - input Set equal to VMI_CMD_USERCAPS.
VMI_CMD_USERCAPS Parameter - pIn
pIn(PUSERCAPSIN) - input Pointer to a USERCAPSINdata structure.
VMI_CMD_USERCAPS Parameter - pOut
pOut(PVOID) - output Pointer to a buffer area.
Pointer to a buffer area whose format depends on the value of the ulFunction field of the USERCAPSINstructure pointed to by pIn.
If pIn->ulFunction is QUERYCAPS, pOut points to a ULONG count followed by an array of DRIVERCAPSstructures. If pIn->ulFunction is QUERYCAPSLIST or SETCAP, pOut points to a DRIVERCAPSstructure.
The length of the buffer area provided is specified by the ulSize field of the USERCAPSINstructure pointed to by pIn.
VMI_CMD_USERCAPS Return Value - rc
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SUCCESS
RC_UNSUPPORTED
VMI_CMD_USERCAPS - Parameters
gid(GID) - input ID of the GRADD.
ulFunc(ULONG) - input Set equal to VMI_CMD_USERCAPS.
pIn(PUSERCAPSIN) - input Pointer to a USERCAPSINdata structure.
pOut(PVOID) - output Pointer to a buffer area.
Pointer to a buffer area whose format depends on the value of the ulFunction field of the USERCAPSINstructure pointed to by pIn.
If pIn->ulFunction is QUERYCAPS, pOut points to a ULONG count followed by an array of DRIVERCAPSstructures. If pIn->ulFunction is QUERYCAPSLIST or SETCAP, pOut points to a DRIVERCAPSstructure.
The length of the buffer area provided is specified by the ulSize field of the USERCAPSINstructure pointed to by pIn.
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SUCCESS
RC_UNSUPPORTED
VMI_CMD_USERCAPS - Remarks
None.
VMI_CMD_USERCAPS - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
VMI_CMD_VRAM
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VMI_CMD_VRAMis called to allocate off-screen video memory. VMAN sends this command to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_VRAM. */ PVOID pIn; /* Pointer to a VRAMIN data structure. */ PVOID pOut; /* Pointer to a function-specific output data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_VRAM - Syntax
Description:
VMI_CMD_VRAMis called to allocate off-screen video memory. VMAN sends this command to the GRADD chain identified by the GRADD ID provided by the caller.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to VMI_CMD_VRAM. */ PVOID pIn; /* Pointer to a VRAMIN data structure. */ PVOID pOut; /* Pointer to a function-specific output data structure. */ ULONG rc; /* Return codes. */ rc = VMIENTRY(gid, ulFunction, pIn, pOut);
VMI_CMD_VRAM Parameter - gid
gid(GID) - input ID of the GRADD.
VMI_CMD_VRAM Parameter - ulFunction
ulFunction(ULONG) - input Set equal to VMI_CMD_VRAM.
VMI_CMD_VRAM Parameter - pIn
pIn(PVOID) - input Pointer to a VRAMINdata structure.
VMI_CMD_VRAM Parameter - pOut
pOut(PVOID) - output Pointer to a function-specific output data structure.
If the ulFunction field of the VRAMINstructure pointed to by pIn is set to VRAM_ALLOCATE, VRAM_DEALLOCATE, or VRAM_QUERY, then pOut points to a VRAMALLOCOUTdata structure.
If the ulFunction field of the VRAMINstructure pointed to by pIn is set to VRAM_REGISTER or VRAM_DEREGISTER, then pOut points to a VRAMREGISTEROUTdata structure.
VMI_CMD_VRAM Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
VMI_CMD_VRAM - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to VMI_CMD_VRAM.
pIn(PVOID) - input Pointer to a VRAMINdata structure.
pOut(PVOID) - output Pointer to a function-specific output data structure.
If the ulFunction field of the VRAMINstructure pointed to by pIn is set to VRAM_ALLOCATE, VRAM_DEALLOCATE, or VRAM_QUERY, then pOut points to a VRAMALLOCOUTdata structure.
If the ulFunction field of the VRAMINstructure pointed to by pIn is set to VRAM_REGISTER or VRAM_DEREGISTER, then pOut points to a VRAMREGISTEROUTdata structure.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
VMI_CMD_VRAM - Remarks
None.
VMI_CMD_VRAM - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
Graphics Adapter Device Drivers
This chapter describes the functions called by individual Graphics Adapter Device Drivers (GRADDs), which are designated by the prefix GHI_CMD_. The chapter also discusses Enhanced Direct Interface Video Extension (EnDIVE) functions, which are designated by the prefix EXT_CMD_.
Each GRADD has its own exported function called "HWEntry," which is the same function type as VMIEntry. The differences between the VMAN protocol (VMI) and the protocol for the GRADDs (GHI) include the following:
�The VMI is a super set of the GHI.
�The ulFunctionparameter value changes to the appropriate VMI_CMD_ function name.
To provide the appropriate user interface, all GRADDs must export a function of the following typedef:
ULONG HWEntry(GID gid, ULONG ulFunction, PVOID pIn, PVOID pOut);
Adding Extensions
One of the most important design points of the GRADD Model is the ability to extend or enhance the overall architecture. It is not possible to anticipate the changes in future graphics hardware, so we must provide a mechanism to extend the architecture in a manner that takes fullest advantage of the new hardware.
There are many ways to extend the GRADD Model. Using the VMI_CMD_EXTENSIONcommand, an extension can be written that passes its own defined commands to a GRADD. Support for an extension can be added to an existing GRADD, or a new GRADD can be written to handle the additional support for a given extension.
Adding Extensions to an Existing GRADD
When the Video Manager (VMAN) issues the GHI_CMD_INITcommand to a GRADD, it gives the GRADD a unique ID. Upon return from the GHI_CMD_INIT command, the GRADD returns the number of function classes it supports. The GRADD must assign a unique GID to each of its function-class instances. The GID provided to the GRADD by VMAN must be bumped up by one for every function- class instance.
Note:For Presentation Manager and Seamless Windows functions, a GRADD must support the Base Function class of services. The GRE2VMAN component looks specifically for a GRADD that supports this class of function.
VMAN will allocate one GRADDINFO structure for every class of function that a GRADD supports. VMAN will call VMI_CMD_QUERYCAPSonce for every function- class instance. This allows an extension layer to associate a GID with a set of function classes.
The extension layer uses the VMI_CMD_EXTENSIONfunction to communicate with a GRADD. It is up to the extension layer to define the unique extension functions. The extensions must use VMAN to communicate with the GRADD. The input packet to the VMI_CMD_EXTENSION function includes information about screen change areas and hardware serialization. This information allows VMAN to maintain hardware pointer support and hardware serialization.
Creating an Extension GRADD
An extension GRADD can be added to the system without interfering with normal operations. The extension GRADD works in the same manner as a normal GRADD. The extension GRADD identifies itself to the system via the pszFunctionClassIDfield of the CAPSINFO data structure. This structure is returned to VMAN via GHI_CMD_QUERYCAPS.
The extension layer communicates with the extension GRADD in the same manner described in the "Adding Extensions to an Existing GRADD" section earlier.
Creating an EnDIVE Multimedia Extension GRADD
OS/2 Warp supports an enhanced direct interface video extension, referred to as EnDIVE. This extension is designed to support graphics chips that handle video acceleration in hardware. The EnDIVE multimedia extension described here supports the same level of functionality under the GRADD Model.
The following figure diagrams the DIVE Display Engine. [Artwork not shown]
The phrase "video acceleration" recently has taken on a new meaning. In the past, video acceleration was a way of describing hardware assist for bitblts, lines, and so on. Today, video acceleration or video accelerators describe hardware assist for video-acceleration software. The minimum requirement necessary to be considered a video accelerator is the ability to perform a stretch blit in hardware. More powerful video accelerators perform additional functions, such as dynamic color conversion, decompression, and compression. These types of operations are directly applicable to the needs of multimedia video-acceleration software.
The EnDIVE multimedia extension GRADD consists of four functions, contained in the ulXSubFunctionfield of the HWEXTENSION packet. For each extension function, the input packet is pointed to by the pXP1field of the HWEXTENSION packet.
The four EnDIVE functions are listed below:
�EXT_CMD_ENDIVE_GET
�EXT_CMD_ENDIVE_INIT
�EXT_CMD_ENDIVE_PUT
�EXT_CMD_ENDIVE_QUERY
For details on each of these functions, refer to Enhanced Direct Interface Video Extension (EnDIVE) Functions.
NLS Support
The GRADD Model is independent of the language and the operating system service being used. Double-byte character sets and other issues for different language releases are a matter of the translation of the operating system service, not of any code in the GRADD Model.
Graphics Hardware Interface Functions
The Graphics Adapter Device Driver Interface (GHI) functions are listed in the following table for easy reference. Each of these functions has an identical corresponding VMAN VMI_CMD_ function (refer to VMI_CMD_xx Functions and GHI_CMD_xx Functions). The difference between VMI and GHI functions is that the VMI functions use VMIEntry, while the GHI functions use HWEntry. In addition, the differences between the VMAN VMI protocol and the GRADD GHI protocol can be described as follows:
�The VMI is a super set of the GHI.
�The ulFunctionparameter value changes to the appropriate VMI_CMD_ function name.
The following table lists the GRADD Graphics Hardware Interface functions and whether they are mandatory or optional.
/-------------------------------------------------------------\ |Function |Type | |----------------------------------------+--------------------| |GHI_CMD_BANK |Optional | |----------------------------------------+--------------------| |GHI_CMD_BITBLT |Optional | |----------------------------------------+--------------------| |GHI_CMD_EVENT |Optional | |----------------------------------------+--------------------| |GHI_CMD_EXTENSION |Optional | |----------------------------------------+--------------------| |GHI_CMD_INIT |Mandatory | |----------------------------------------+--------------------| |GHI_CMD_INITPROC |Mandatory | |----------------------------------------+--------------------| |GHI_CMD_LINE |Optional | |----------------------------------------+--------------------| |GHI_CMD_MOVEPTR |Optional | |----------------------------------------+--------------------| |GHI_CMD_PALETTE |Mandatory* | |----------------------------------------+--------------------| |GHI_CMD_QUERYCAPS |Mandatory | |----------------------------------------+--------------------| |GHI_CMD_QUERYMODES |Mandatory | |----------------------------------------+--------------------| |GHI_CMD_REQUESTHW |Optional | |----------------------------------------+--------------------| |GHI_CMD_SETMODE |Mandatory | |----------------------------------------+--------------------| |GHI_CMD_SETPTR |Optional | |----------------------------------------+--------------------| |GHI_CMD_SHOWPTR |Optional | |----------------------------------------+--------------------| |GHI_CMD_TERM |Optional | |----------------------------------------+--------------------| |GHI_CMD_TERMPROC |Optional | |----------------------------------------+--------------------| |GHI_CMD_TEXT |Optional | |----------------------------------------+--------------------| |GHI_CMD_USERCAPS |Optional | |----------------------------------------+--------------------| |GHI_CMD_VRAM |Optional | |----------------------------------------+--------------------| |HWEntry |Entry point | | |* At 256 color modes| | |only. | \-------------------------------------------------------------/
GHI_CMD_BANK
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_BANKis optional and is called to set or get the region or bank number of the active area of the video display. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_BANK. */ PVOID pIn; /* Pointer to a HWBANKIN data structure. */ PVOID pOut; /* Pointer to a HWBANKOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_BANK - Syntax
Description:
GHI_CMD_BANKis optional and is called to set or get the region or bank number of the active area of the video display. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_BANK. */ PVOID pIn; /* Pointer to a HWBANKIN data structure. */ PVOID pOut; /* Pointer to a HWBANKOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_BANK Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_BANK Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_BANK.
GHI_CMD_BANK Parameter - pIn
pIn(PVOID) - input Pointer to a HWBANKINdata structure.
GHI_CMD_BANK Parameter - pOut
pOut(PVOID) - output Pointer to a HWBANKOUTdata structure.
GHI_CMD_BANK Return Value - rc
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SIMULATE
RC_SUCCESS
GHI_CMD_BANK - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_BANK.
pIn(PVOID) - input Pointer to a HWBANKINdata structure.
pOut(PVOID) - output Pointer to a HWBANKOUTdata structure.
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SIMULATE
RC_SUCCESS
GHI_CMD_BANK - Remarks
None.
GHI_CMD_BANK - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_BITBLT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_BITBLTis optional and is called to draw bit maps to and from the video display. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_BITBLT. */ PVOID pIn; /* Pointer to a BITBLTINFO data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_BITBLT - Syntax
Description:
GHI_CMD_BITBLTis optional and is called to draw bit maps to and from the video display. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_BITBLT. */ PVOID pIn; /* Pointer to a BITBLTINFO data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_BITBLT Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_BITBLT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_BITBLT.
GHI_CMD_BITBLT Parameter - pIn
pIn(PVOID) - input Pointer to a BITBLTINFOdata structure.
GHI_CMD_BITBLT Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
GHI_CMD_BITBLT Return Value - rc
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_BITBLT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_BITBLT.
pIn(PVOID) - input Pointer to a BITBLTINFOdata structure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_BITBLT - Remarks
None.
GHI_CMD_BITBLT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_EVENT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_EVENTis optional and is called to notify a GRADD of specific events.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_EVENT. */ PVOID pIn; /* Pointer to an HWEVENTIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_EVENT - Syntax
Description:
GHI_CMD_EVENTis optional and is called to notify a GRADD of specific events.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_EVENT. */ PVOID pIn; /* Pointer to an HWEVENTIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_EVENT Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_EVENT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_EVENT.
GHI_CMD_EVENT Parameter - pIn
pIn(PVOID) - input Pointer to an HWEVENTINdata structure.
GHI_CMD_EVENT Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
GHI_CMD_EVENT Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_EVENT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_EVENT.
pIn(PVOID) - input Pointer to an HWEVENTINdata structure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_EVENT - Remarks
None.
GHI_CMD_EVENT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_EXTENSION
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_EXTENSIONis optional and is called to send an extension command to a GRADD. The extension subfunction is placed in the ulXSubFunctionfield of the pIninput packet.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_EXTENSION. */ PVOID pIn; /* Pointer to an HWEXTENSION structure. */ PVOID pOut; /* Pointer to an extension-specific output structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_EXTENSION - Syntax
Description:
GHI_CMD_EXTENSIONis optional and is called to send an extension command to a GRADD. The extension subfunction is placed in the ulXSubFunctionfield of the pIninput packet.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_EXTENSION. */ PVOID pIn; /* Pointer to an HWEXTENSION structure. */ PVOID pOut; /* Pointer to an extension-specific output structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_EXTENSION Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_EXTENSION Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_EXTENSION.
GHI_CMD_EXTENSION Parameter - pIn
pIn(PVOID) - input Pointer to an HWEXTENSIONstructure.
GHI_CMD_EXTENSION Parameter - pOut
pOut(PVOID) - output Pointer to an extension-specific output structure.
GHI_CMD_EXTENSION Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_EXTENSION - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_EXTENSION.
pIn(PVOID) - input Pointer to an HWEXTENSIONstructure.
pOut(PVOID) - output Pointer to an extension-specific output structure.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_EXTENSION - Remarks
None.
GHI_CMD_EXTENSION - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_INIT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_INITis mandatory and is called to initialize the GRADD. It is the first command a GRADD receives from the Video Manager (VMAN).
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_INIT. */ PVOID pIn; /* Pointer to a GDDINITIN data structure. */ PVOID pOut; /* Pointer to a GDDINITOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWEntry(gid, ulFunction, pIn, pOut);
GHI_CMD_INIT - Syntax
Description:
GHI_CMD_INITis mandatory and is called to initialize the GRADD. It is the first command a GRADD receives from the Video Manager (VMAN).
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_INIT. */ PVOID pIn; /* Pointer to a GDDINITIN data structure. */ PVOID pOut; /* Pointer to a GDDINITOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWEntry(gid, ulFunction, pIn, pOut);
GHI_CMD_INIT Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_INIT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_INIT.
GHI_CMD_INIT Parameter - pIn
pIn(PVOID) - input Pointer to a GDDINITINdata structure.
GHI_CMD_INIT Parameter - pOut
pOut(PVOID) - output Pointer to a GDDINITOUTdata structure.
GHI_CMD_INIT Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_INIT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_INIT.
pIn(PVOID) - input Pointer to a GDDINITINdata structure.
pOut(PVOID) - output Pointer to a GDDINITOUTdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_INIT - Remarks
None.
GHI_CMD_INIT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_INITPROC
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_INITPROCis mandatory and informs a GRADD that a new process is being initialized. It indicates that this new process intends to be a client of the GRADD component.
The GRADD ensures that all data and code is valid under this new process.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_INITPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an INITPROCOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_INITPROC - Syntax
Description:
GHI_CMD_INITPROCis mandatory and informs a GRADD that a new process is being initialized. It indicates that this new process intends to be a client of the GRADD component.
The GRADD ensures that all data and code is valid under this new process.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_INITPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an INITPROCOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_INITPROC Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_INITPROC Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_INITPROC.
GHI_CMD_INITPROC Parameter - pIn
pIn(PVOID) - input NULL.
GHI_CMD_INITPROC Parameter - pOut
pOut(PVOID) - output Pointer to an INITPROCOUTdata structure.
GHI_CMD_INITPROC Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_INITPROC - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_INITPROC.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to an INITPROCOUTdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_INITPROC - Remarks
None.
GHI_CMD_INITPROC - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_LINE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_LINEis optional and is called to draw lines to the video display. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_LINE. */ PVOID pIn; /* Pointer to a LINEINFO or LINEINFO2 data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_LINE - Syntax
Description:
GHI_CMD_LINEis optional and is called to draw lines to the video display. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_LINE. */ PVOID pIn; /* Pointer to a LINEINFO or LINEINFO2 data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_LINE Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_LINE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_LINE.
GHI_CMD_LINE Parameter - pIn
pIn(PVOID) - input Pointer to a LINEINFOor LINEINFO2data structure.
GHI_CMD_LINE Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
GHI_CMD_LINE Return Value - rc
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_LINE - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_LINE.
pIn(PVOID) - input Pointer to a LINEINFOor LINEINFO2data structure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_LINE - Remarks
The LINEINFOstructure can describe a sequence of line segments where each line segment may be clipped. The LINEINFO2structure describes a sequence of line segments where only the start of the first segment and the end of the last segment may be clipped. For many cases, the simpler LINEINFO2 data can be generated more efficiently than for the more general LINEINFO data.
The LINEINFO and LINEINFO2 structures can be differentiated using the ulLength field at the start of each structure.
Since the LINEINFO2 mechanism was defined after several GRADDs were already released, a LINEINFO2 structure will not be passed to a GRADD unless the GRADD sets the DS_SIMPLE_LINES flag in the ulFCFlags member of the CAPSINFOstructure returned for the GHI_CMD_QUERYCAPSfunction. Note that if a GRADD indicates it can handle the LINEINFO2 structure, it may still be passed a LINEINFO structure when that generality is needed.
None.
GHI_CMD_LINE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_MOVEPTR
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_MOVEPTRis optional and is called to move the pointer to the new location. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_MOVEPTR. */ PVOID pIn; /* Pointer to an HWMOVEPTRIN structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_MOVEPTR - Syntax
Description:
GHI_CMD_MOVEPTRis optional and is called to move the pointer to the new location. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_MOVEPTR. */ PVOID pIn; /* Pointer to an HWMOVEPTRIN structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_MOVEPTR Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_MOVEPTR Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_MOVEPTR.
GHI_CMD_MOVEPTR Parameter - pIn
pIn(PVOID) - input Pointer to an HWMOVEPTRINstructure.
GHI_CMD_MOVEPTR Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
GHI_CMD_MOVEPTR Return Value - rc
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_MOVEPTR - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_MOVEPTR.
pIn(PVOID) - input Pointer to an HWMOVEPTRINstructure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_MOVEPTR - Remarks
None.
GHI_CMD_MOVEPTR - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_PALETTE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_PALETTEis mandatory if the device supports 256-color modes. This function is called to set or query the hardware palette. The GRADD is expected to respond by describing the palette in a given array or by using the palette given in the array. The GRADD is always given an HWPALETTEINFOstructure with either the PALETTE_GET or PALETTE_SET flag to specify the operation to perform.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_PALETTE. */ PVOID pIn; /* Pointer to an HWPALETTEINFO structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_PALETTE - Syntax
Description:
GHI_CMD_PALETTEis mandatory if the device supports 256-color modes. This function is called to set or query the hardware palette. The GRADD is expected to respond by describing the palette in a given array or by using the palette given in the array. The GRADD is always given an HWPALETTEINFOstructure with either the PALETTE_GET or PALETTE_SET flag to specify the operation to perform.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_PALETTE. */ PVOID pIn; /* Pointer to an HWPALETTEINFO structure. */ PVOID pOut; /* NULL; no output structure is needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_PALETTE Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_PALETTE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_PALETTE.
GHI_CMD_PALETTE Parameter - pIn
pIn(PVOID) - input Pointer to an HWPALETTEINFOstructure.
GHI_CMD_PALETTE Parameter - pOut
pOut(PVOID) - output NULL; no output structure is needed.
GHI_CMD_PALETTE Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_PALETTE - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_PALETTE.
pIn(PVOID) - input Pointer to an HWPALETTEINFOstructure.
pOut(PVOID) - output NULL; no output structure is needed.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_PALETTE - Remarks
None.
GHI_CMD_PALETTE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_QUERYCAPS
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_QUERYCAPSis mandatory. The GRADD is expected to return its capabilities. The returned capabilities are packaged by VMAN and given to a Translation Layer. The Translation Layer uses these capabilities to decide which GHI_CMD_ functions are sent to the GRADD.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_QUERYCAPS. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a CAPSINFO data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_QUERYCAPS - Syntax
Description:
GHI_CMD_QUERYCAPSis mandatory. The GRADD is expected to return its capabilities. The returned capabilities are packaged by VMAN and given to a Translation Layer. The Translation Layer uses these capabilities to decide which GHI_CMD_ functions are sent to the GRADD.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_QUERYCAPS. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to a CAPSINFO data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_QUERYCAPS Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_QUERYCAPS Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_QUERYCAPS.
GHI_CMD_QUERYCAPS Parameter - pIn
pIn(PVOID) - input NULL.
GHI_CMD_QUERYCAPS Parameter - pOut
pOut(PVOID) - output Pointer to a CAPSINFOdata structure.
GHI_CMD_QUERYCAPS Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_QUERYCAPS - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_QUERYCAPS.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a CAPSINFOdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_QUERYCAPS - Remarks
None.
GHI_CMD_QUERYCAPS - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_QUERYMODES
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_QUERYMODESis mandatory and is called to query the available video mode information. The GRADD is expected to respond with information regarding the video graphics modes supported by the GRADD.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_QUERYMODES. */ PVOID pIn; /* Pointer that identifies a QUERYMODE operation. */ PVOID pOut; /* Pointer to the pIn operation. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_QUERYMODES - Syntax
Description:
GHI_CMD_QUERYMODESis mandatory and is called to query the available video mode information. The GRADD is expected to respond with information regarding the video graphics modes supported by the GRADD.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_QUERYMODES. */ PVOID pIn; /* Pointer that identifies a QUERYMODE operation. */ PVOID pOut; /* Pointer to the pIn operation. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_QUERYMODES Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_QUERYMODES Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_QUERYMODES.
GHI_CMD_QUERYMODES Parameter - pIn
pIn(PVOID) - input Pointer that identifies a QUERYMODE operation.
This pointer identifies one of the following operations:
QUERYMODE_NUM_MODES
QUERYMODE_MODE_DATA
GHI_CMD_QUERYMODES Parameter - pOut
pOut(PVOID) - output Pointer to the pIn operation.
This pointer indicates one of the following, depending on the value of pIn:
QUERYMODE_NUM_MODES Indicates a pointer to a ULONG that is to be given the number of supported modes.
QUERYMODE_MODE_DATA Indicates a pointer to an array of GDDMODEINFOstructures large enough for the number of supported modes.
GHI_CMD_QUERYMODES Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_QUERYMODES - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_QUERYMODES.
pIn(PVOID) - input Pointer that identifies a QUERYMODE operation.
This pointer identifies one of the following operations:
QUERYMODE_NUM_MODES
QUERYMODE_MODE_DATA
pOut(PVOID) - output Pointer to the pIn operation.
This pointer indicates one of the following, depending on the value of pIn:
QUERYMODE_NUM_MODES Indicates a pointer to a ULONG that is to be given the number of supported modes.
QUERYMODE_MODE_DATA Indicates a pointer to an array of GDDMODEINFOstructures large enough for the number of supported modes.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_QUERYMODES - Remarks
None.
GHI_CMD_QUERYMODES - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_REQUESTHW
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_REQUESTHWis optional and allows a translation layer exclusive access to the video hardware. It can do such operations as writing directly to the video buffer.
This function is used to request and release the video hardware. The ulFlagsfield of the pIndata packet determines if this function is a request or a release.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_REQUESTHW. */ PVOID pIn; /* Pointer to an HWREQIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_REQUESTHW - Syntax
Description:
GHI_CMD_REQUESTHWis optional and allows a translation layer exclusive access to the video hardware. It can do such operations as writing directly to the video buffer.
This function is used to request and release the video hardware. The ulFlagsfield of the pIndata packet determines if this function is a request or a release.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_REQUESTHW. */ PVOID pIn; /* Pointer to an HWREQIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_REQUESTHW Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_REQUESTHW Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_REQUESTHW.
GHI_CMD_REQUESTHW Parameter - pIn
pIn(PVOID) - input Pointer to an HWREQINdata structure.
GHI_CMD_REQUESTHW Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
GHI_CMD_REQUESTHW Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_REQUESTHW - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_REQUESTHW.
pIn(PVOID) - input Pointer to an HWREQINdata structure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_REQUESTHW - Remarks
None.
GHI_CMD_REQUESTHW - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_SETMODE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_SETMODEis mandatory. The GRADD is expected to set the video mode, given an ID of the chosen mode.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SETMODE. */ PVOID pIn; /* Pointer to PULONG containing the ID of the requested mode. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_SETMODE - Syntax
Description:
GHI_CMD_SETMODEis mandatory. The GRADD is expected to set the video mode, given an ID of the chosen mode.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SETMODE. */ PVOID pIn; /* Pointer to PULONG containing the ID of the requested mode. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_SETMODE Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_SETMODE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_SETMODE.
GHI_CMD_SETMODE Parameter - pIn
pIn(PVOID) - input Pointer to PULONG containing the ID of the requested mode.
GHI_CMD_SETMODE Parameter - pOut
pOut(PVOID) - output NULL.
GHI_CMD_SETMODE Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_SETMODE - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_SETMODE.
pIn(PVOID) - input Pointer to PULONG containing the ID of the requested mode.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
GHI_CMD_SETMODE - Remarks
None.
GHI_CMD_SETMODE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_SETPTR
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_SETPTRis optional and is called to set the pointer bit masks. Both monochrome and color pointers can be set.
The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SETPTR. */ PVOID pIn; /* Pointer to an HWSETPTRIN data structure. */ PVOID pOut; /* Pointer to an HWSETPTROUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_SETPTR - Syntax
Description:
GHI_CMD_SETPTRis optional and is called to set the pointer bit masks. Both monochrome and color pointers can be set.
The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SETPTR. */ PVOID pIn; /* Pointer to an HWSETPTRIN data structure. */ PVOID pOut; /* Pointer to an HWSETPTROUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_SETPTR Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_SETPTR Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_SETPTR.
GHI_CMD_SETPTR Parameter - pIn
pIn(PVOID) - input Pointer to an HWSETPTRINdata structure.
GHI_CMD_SETPTR Parameter - pOut
pOut(PVOID) - output Pointer to an HWSETPTROUTdata structure.
GHI_CMD_SETPTR Return Value - rc
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_SETPTR - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_SETPTR.
pIn(PVOID) - input Pointer to an HWSETPTRINdata structure.
pOut(PVOID) - output Pointer to an HWSETPTROUTdata structure.
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_SETPTR - Remarks
None.
GHI_CMD_SETPTR - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_SHOWPTR
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_SHOWPTRis optional and sets the visibility state of the pointer. The fShowfield of the pIndata packet determines the visibility state.
The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SHOWPTR. */ PVOID pIn; /* Pointer to an HWSHOWPTRIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_SHOWPTR - Syntax
Description:
GHI_CMD_SHOWPTRis optional and sets the visibility state of the pointer. The fShowfield of the pIndata packet determines the visibility state.
The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_SHOWPTR. */ PVOID pIn; /* Pointer to an HWSHOWPTRIN data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_SHOWPTR Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_SHOWPTR Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_SHOWPTR.
GHI_CMD_SHOWPTR Parameter - pIn
pIn(PVOID) - input Pointer to an HWSHOWPTRINdata structure.
GHI_CMD_SHOWPTR Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
GHI_CMD_SHOWPTR Return Value - rc
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_SHOWPTR - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_SHOWPTR.
pIn(PVOID) - input Pointer to an HWSHOWPTRINdata structure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_SHOWPTR - Remarks
None.
GHI_CMD_SHOWPTR - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_TERM
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_TERMis optional and is called by a VMAN when it no longer requires the services of the GRADD.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_TERM. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_TERM - Syntax
Description:
GHI_CMD_TERMis optional and is called by a VMAN when it no longer requires the services of the GRADD.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_TERM. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_TERM Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_TERM Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_TERM.
GHI_CMD_TERM Parameter - pIn
pIn(PVOID) - input NULL.
GHI_CMD_TERM Parameter - pOut
pOut(PVOID) - output NULL.
GHI_CMD_TERM Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_TERM - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_TERM.
pIn(PVOID) - input NULL.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_TERM - Remarks
None.
GHI_CMD_TERM - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_TERMPROC
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_TERMPROCis optional and informs the GRADD that an existing client process is being terminated. The GRADD should clean up all resources owned by this process.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_TERMPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_TERMPROC - Syntax
Description:
GHI_CMD_TERMPROCis optional and informs the GRADD that an existing client process is being terminated. The GRADD should clean up all resources owned by this process.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_TERMPROC. */ PVOID pIn; /* NULL. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_TERMPROC Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_TERMPROC Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_TERMPROC.
GHI_CMD_TERMPROC Parameter - pIn
pIn(PVOID) - input NULL.
GHI_CMD_TERMPROC Parameter - pOut
pOut(PVOID) - output NULL.
GHI_CMD_TERMPROC Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_TERMPROC - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_TERMPROC.
pIn(PVOID) - input NULL.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_TERMPROC - Remarks
None.
GHI_CMD_TERMPROC - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_TEXT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_TEXTis optional and is called to draw text to the video display. Each textblt provides a string of characters, called glyphs, to blit to the video display. The GRADD can store the glyphs in an offscreen video cache. If another textblt has glyphs already stored in cache, the GRADD can transfer video memory to video display rather than taking the glyph from system memory. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_TEXT. */ PVOID pIn; /* Pointer to a TEXTBLTINFO data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_TEXT - Syntax
Description:
GHI_CMD_TEXTis optional and is called to draw text to the video display. Each textblt provides a string of characters, called glyphs, to blit to the video display. The GRADD can store the glyphs in an offscreen video cache. If another textblt has glyphs already stored in cache, the GRADD can transfer video memory to video display rather than taking the glyph from system memory. The GRADD can return this function call to VMAN for simulation.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_TEXT. */ PVOID pIn; /* Pointer to a TEXTBLTINFO data structure. */ PVOID pOut; /* NULL; no output structure needed. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_TEXT Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_TEXT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_TEXT.
GHI_CMD_TEXT Parameter - pIn
pIn(PVOID) - input Pointer to a TEXTBLTINFOdata structure.
GHI_CMD_TEXT Parameter - pOut
pOut(PVOID) - output NULL; no output structure needed.
GHI_CMD_TEXT Return Value - rc
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_TEXT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_TEXT.
pIn(PVOID) - input Pointer to a TEXTBLTINFOdata structure.
pOut(PVOID) - output NULL; no output structure needed.
rc(ULONG) - returns Return codes.
RC_SIMULATE
RC_SUCCESS
RC_ERROR
GHI_CMD_TEXT - Remarks
To enable and define the type of support for GHI_CMD_TEXT, the following flags should be set in the ulCFlags member of CAPSINFO:
TEXTBLT_DOWNLOADABLE Indicates downloadable fonts. TEXTBLT_CLIPABLE Indicates clipable fonts.
GHI_CMD_TEXT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_USERCAPS
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_USERCAPSis used to enable and support the CAPABILITIES button on the OS/2 System Object.
When the Video Configuration Manager presents the interface to the user, each capability is presented in a separate window page of the capabilities notebook in System Object. The window layout depends on the capability type :
Boolean type is represented by a check box.
Aggregate type is represented by a list box.
The capability description appears as the title for that control.
If a GRADD is going to support capabilities in multiple languages, it must get the capability description (szCapsDesc) and capability aggregate strings, if applicable, from a resource module that contains already- translated strings.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunc; /* Set equal to GHI_CMD_USERCAPS. */ PUSERCAPSIN pIn; /* Pointer to a USERCAPSIN data structure. */ PVOID pOut; /* Pointer to a buffer area. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunc, pIn, pOut);
GHI_CMD_USERCAPS - Syntax
Description:
GHI_CMD_USERCAPSis used to enable and support the CAPABILITIES button on the OS/2 System Object.
When the Video Configuration Manager presents the interface to the user, each capability is presented in a separate window page of the capabilities notebook in System Object. The window layout depends on the capability type :
Boolean type is represented by a check box.
Aggregate type is represented by a list box.
The capability description appears as the title for that control.
If a GRADD is going to support capabilities in multiple languages, it must get the capability description (szCapsDesc) and capability aggregate strings, if applicable, from a resource module that contains already- translated strings.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunc; /* Set equal to GHI_CMD_USERCAPS. */ PUSERCAPSIN pIn; /* Pointer to a USERCAPSIN data structure. */ PVOID pOut; /* Pointer to a buffer area. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunc, pIn, pOut);
GHI_CMD_USERCAPS Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_USERCAPS Parameter - ulFunc
ulFunc(ULONG) - input Set equal to GHI_CMD_USERCAPS.
GHI_CMD_USERCAPS Parameter - pIn
pIn(PUSERCAPSIN) - input Pointer to a USERCAPSINdata structure.
GHI_CMD_USERCAPS Parameter - pOut
pOut(PVOID) - output Pointer to a buffer area.
Pointer to a buffer area whose format depends on the value of the ulFunction field of the USERCAPSINstructure pointed to by pIn.
If pIn->ulFunction is QUERYCAPS, pOut points to a ULONG count followed by an array of DRIVERCAPSstructures. If pIn->ulFunction is QUERYCAPSLIST or SETCAP, pOut points to a DRIVERCAPSstructure.
The length of the buffer area provided is specified by the ulSize field of the USERCAPSINstructure pointed to by pIn.
GHI_CMD_USERCAPS Return Value - rc
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SUCCESS
RC_UNSUPPORTED
GHI_CMD_USERCAPS - Parameters
gid(GID) - input ID of the GRADD.
ulFunc(ULONG) - input Set equal to GHI_CMD_USERCAPS.
pIn(PUSERCAPSIN) - input Pointer to a USERCAPSINdata structure.
pOut(PVOID) - output Pointer to a buffer area.
Pointer to a buffer area whose format depends on the value of the ulFunction field of the USERCAPSINstructure pointed to by pIn.
If pIn->ulFunction is QUERYCAPS, pOut points to a ULONG count followed by an array of DRIVERCAPSstructures. If pIn->ulFunction is QUERYCAPSLIST or SETCAP, pOut points to a DRIVERCAPSstructure.
The length of the buffer area provided is specified by the ulSize field of the USERCAPSINstructure pointed to by pIn.
rc(ULONG) - returns Return codes.
RC_ERROR
RC_SUCCESS
RC_UNSUPPORTED
GHI_CMD_USERCAPS - Remarks
None.
GHI_CMD_USERCAPS - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GHI_CMD_VRAM
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GHI_CMD_VRAMis optional and is called to request allocation of off-screen video memory.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_VRAM. */ PVOID pIn; /* Pointer to a VRAMIN data structure. */ PVOID pOut; /* Pointer to a function-specific output data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_VRAM - Syntax
Description:
GHI_CMD_VRAMis optional and is called to request allocation of off-screen video memory.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to GHI_CMD_VRAM. */ PVOID pIn; /* Pointer to a VRAMIN data structure. */ PVOID pOut; /* Pointer to a function-specific output data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
GHI_CMD_VRAM Parameter - gid
gid(GID) - input ID of the GRADD.
GHI_CMD_VRAM Parameter - ulFunction
ulFunction(ULONG) - input Set equal to GHI_CMD_VRAM.
GHI_CMD_VRAM Parameter - pIn
pIn(PVOID) - input Pointer to a VRAMINdata structure.
GHI_CMD_VRAM Parameter - pOut
pOut(PVOID) - output Pointer to a function-specific output data structure.
If the ulFunction field of the VRAMINstructure pointed to by pIn is set to VRAM_ALLOCATE, VRAM_DEALLOCATE, or VRAM_QUERY, then pOut points to a VRAMALLOCOUTdata structure.
If the ulFunction field of the VRAMINstructure pointed to by pIn is set to VRAM_REGISTER or VRAM_DEREGISTER, then pOut points to a VRAMREGISTEROUTdata structure.
GHI_CMD_VRAM Return Value - rc
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_VRAM - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to GHI_CMD_VRAM.
pIn(PVOID) - input Pointer to a VRAMINdata structure.
pOut(PVOID) - output Pointer to a function-specific output data structure.
If the ulFunction field of the VRAMINstructure pointed to by pIn is set to VRAM_ALLOCATE, VRAM_DEALLOCATE, or VRAM_QUERY, then pOut points to a VRAMALLOCOUTdata structure.
If the ulFunction field of the VRAMINstructure pointed to by pIn is set to VRAM_REGISTER or VRAM_DEREGISTER, then pOut points to a VRAMREGISTEROUTdata structure.
rc(ULONG) - returns Return codes.
RC_UNSUPPORTED
RC_SUCCESS
RC_ERROR
GHI_CMD_VRAM - Remarks
None.
GHI_CMD_VRAM - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
HWEntry
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
HWEntryis the single exported function from a graphics adapter device driver (GRADD). It is part of the Graphics Hardware Interface (GHI) protocol for GRADDs and receives all of the operations from the Video Manager (VMAN) component.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set to appropriate GHI_CMD_ function. */ PVOID pIn; /* Pointer to a GHI_-specific input data structure. */ PVOID pOut; /* Pointer to a GHI_-specific output data structure. */ ULONG rc; /* Return codes. */ rc = HWEntry(gid, ulFunction, pIn, pOut);
HWEntry - Syntax
Description:
HWEntryis the single exported function from a graphics adapter device driver (GRADD). It is part of the Graphics Hardware Interface (GHI) protocol for GRADDs and receives all of the operations from the Video Manager (VMAN) component.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set to appropriate GHI_CMD_ function. */ PVOID pIn; /* Pointer to a GHI_-specific input data structure. */ PVOID pOut; /* Pointer to a GHI_-specific output data structure. */ ULONG rc; /* Return codes. */ rc = HWEntry(gid, ulFunction, pIn, pOut);
HWEntry Parameter - gid
gid(GID) - input ID of the GRADD.
HWEntry Parameter - ulFunction
ulFunction(ULONG) - input Set to appropriate GHI_CMD_ function.
This parameter is set to one of the GHI_CMD_ functions shown in the table at the beginning of this section.
HWEntry Parameter - pIn
pIn(PVOID) - input Pointer to a GHI_-specific inputdata structure.
HWEntry Parameter - pOut
pOut(PVOID) - output Pointer to a GHI_-specific outputdata structure.
HWEntry Return Value - rc
rc(ULONG) - returns Return codes.
Valid values are dictated by the applicable GHI_CMD_ function.
HWEntry - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set to appropriate GHI_CMD_ function.
This parameter is set to one of the GHI_CMD_ functions shown in the table at the beginning of this section.
pIn(PVOID) - input Pointer to a GHI_-specific inputdata structure.
pOut(PVOID) - output Pointer to a GHI_-specific outputdata structure.
rc(ULONG) - returns Return codes.
Valid values are dictated by the applicable GHI_CMD_ function.
HWEntry - Remarks
None.
HWEntry - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
Enhanced Direct Interface Video Extension (EnDIVE) Functions
The following table lists the EXT_CMD_ functions that are specific to the Enhanced Direct Interface Video Extension (EnDIVE) process. These EnDIVE functions do nothave corresponding VMI_CMD_ functions.
The following table lists the EnDIVE functions and whether they are mandatory or optional.
/-------------------------------------------------------------\ |Function |Type | |----------------------------------------+--------------------| |EXT_CMD_ENDIVE_GET |Optional | |----------------------------------------+--------------------| |EXT_CMD_ENDIVE_INIT |Mandatory | |----------------------------------------+--------------------| |EXT_CMD_ENDIVE_PUT |Mandatory | |----------------------------------------+--------------------| |EXT_CMD_ENDIVE_QUERY |Mandatory | \-------------------------------------------------------------/
EXT_CMD_ENDIVE_GET
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
EXT_CMD_ENDIVE_GETis optional and is called to blit an image from the screen.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_GET. */ PVOID pIn; /* Pointer to an IMAGEPACK data structure. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
EXT_CMD_ENDIVE_GET - Syntax
Description:
EXT_CMD_ENDIVE_GETis optional and is called to blit an image from the screen.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_GET. */ PVOID pIn; /* Pointer to an IMAGEPACK data structure. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
EXT_CMD_ENDIVE_GET Parameter - gid
gid(GID) - input ID of the GRADD.
EXT_CMD_ENDIVE_GET Parameter - ulFunction
ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_GET.
EXT_CMD_ENDIVE_GET Parameter - pIn
pIn(PVOID) - input Pointer to an IMAGEPACKdata structure.
EXT_CMD_ENDIVE_GET Parameter - pOut
pOut(PVOID) - output NULL.
EXT_CMD_ENDIVE_GET Return Value - rc
rc(ULONG) - returns Return codes.
R_SIMULATE
RC_SUCCESS
RC_ERROR
EXT_CMD_ENDIVE_GET - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_GET.
pIn(PVOID) - input Pointer to an IMAGEPACKdata structure.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
R_SIMULATE
RC_SUCCESS
RC_ERROR
EXT_CMD_ENDIVE_GET - Remarks
None.
EXT_CMD_ENDIVE_GET - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
EXT_CMD_ENDIVE_INIT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
EXT_CMD_ENDIVE_INITis mandatory and is called to initialize the hardware. The GRADD must determine if the hardware is present.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_INIT. */ PVOID pIn; /* Pointer to an FBINFO data structure. */ PVOID pOut; /* Pointer to an HWEXTENSIONOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
EXT_CMD_ENDIVE_INIT - Syntax
Description:
EXT_CMD_ENDIVE_INITis mandatory and is called to initialize the hardware. The GRADD must determine if the hardware is present.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_INIT. */ PVOID pIn; /* Pointer to an FBINFO data structure. */ PVOID pOut; /* Pointer to an HWEXTENSIONOUT data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
EXT_CMD_ENDIVE_INIT Parameter - gid
gid(GID) - input ID of the GRADD.
EXT_CMD_ENDIVE_INIT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_INIT.
EXT_CMD_ENDIVE_INIT Parameter - pIn
pIn(PVOID) - input Pointer to an FBINFOdata structure.
EXT_CMD_ENDIVE_INIT Parameter - pOut
pOut(PVOID) - output Pointer to an HWEXTENSIONOUT data structure.
EXT_CMD_ENDIVE_INIT Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
EXT_CMD_ENDIVE_INIT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_INIT.
pIn(PVOID) - input Pointer to an FBINFOdata structure.
pOut(PVOID) - output Pointer to an HWEXTENSIONOUT data structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
EXT_CMD_ENDIVE_INIT - Remarks
None.
EXT_CMD_ENDIVE_INIT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
EXT_CMD_ENDIVE_PUT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
EXT_CMD_ENDIVE_PUTis mandatory and is called to blit an image tothe screen.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_PUT. */ PVOID pIn; /* Pointer to an IMAGEPACK data structure. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
EXT_CMD_ENDIVE_PUT - Syntax
Description:
EXT_CMD_ENDIVE_PUTis mandatory and is called to blit an image tothe screen.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_PUT. */ PVOID pIn; /* Pointer to an IMAGEPACK data structure. */ PVOID pOut; /* NULL. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
EXT_CMD_ENDIVE_PUT Parameter - gid
gid(GID) - input ID of the GRADD.
EXT_CMD_ENDIVE_PUT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_PUT.
EXT_CMD_ENDIVE_PUT Parameter - pIn
pIn(PVOID) - input Pointer to an IMAGEPACKdata structure.
EXT_CMD_ENDIVE_PUT Parameter - pOut
pOut(PVOID) - output NULL.
EXT_CMD_ENDIVE_PUT Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
EXT_CMD_ENDIVE_PUT - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_PUT.
pIn(PVOID) - input Pointer to an IMAGEPACKdata structure.
pOut(PVOID) - output NULL.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
EXT_CMD_ENDIVE_PUT - Remarks
None.
EXT_CMD_ENDIVE_PUT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
EXT_CMD_ENDIVE_QUERY
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
EXT_CMD_ENDIVE_QUERYis mandatory and queries the capabilities of the hardware.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_QUERY. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an IMAGECAPS data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
EXT_CMD_ENDIVE_QUERY - Syntax
Description:
EXT_CMD_ENDIVE_QUERYis mandatory and queries the capabilities of the hardware.
#include <GRADD.h> GID gid; /* ID of the GRADD. */ ULONG ulFunction; /* Set equal to EXT_CMD_ENDIVE_QUERY. */ PVOID pIn; /* NULL. */ PVOID pOut; /* Pointer to an IMAGECAPS data structure. */ ULONG rc; /* Return codes. */ rc = HWENTRY(gid, ulFunction, pIn, pOut);
EXT_CMD_ENDIVE_QUERY Parameter - gid
gid(GID) - input ID of the GRADD.
EXT_CMD_ENDIVE_QUERY Parameter - ulFunction
ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_QUERY.
EXT_CMD_ENDIVE_QUERY Parameter - pIn
pIn(PVOID) - input NULL.
EXT_CMD_ENDIVE_QUERY Parameter - pOut
pOut(PVOID) - output Pointer to an IMAGECAPSdata structure.
EXT_CMD_ENDIVE_QUERY Return Value - rc
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
EXT_CMD_ENDIVE_QUERY - Parameters
gid(GID) - input ID of the GRADD.
ulFunction(ULONG) - input Set equal to EXT_CMD_ENDIVE_QUERY.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to an IMAGECAPSdata structure.
rc(ULONG) - returns Return codes.
RC_SUCCESS
RC_ERROR
EXT_CMD_ENDIVE_QUERY - Remarks
None.
EXT_CMD_ENDIVE_QUERY - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
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 VIDEOPMI32Requestfor 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 Interfacefor more information on the PMI subsystem.
All VIDEOPMI functions, except PMIREQUEST_SOFTWAREINT, require that the PMI subsystem be loaded by issuing PMIREQUEST_LOADPMIFILEand that the VIDEO_ ADAPTER"hvideo" handle and "adapter instance" be passed into the new request.
The ADAPTERINFOand VIDEOMODEINFOdata 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. VIDEOMODEINFOis 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_ADAPTERand VIDEOMODEINFOstructures 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
/-------------------------------------------------------------\ |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
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
VIDEOPMI32Requestis the single, exported entry point from VIDEOPMI.DLL. The various PMI services are accessed through different function numbers passed in the parameters.
#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);
VIDEOPMI32Request - Syntax
Description:
VIDEOPMI32Requestis the single, exported entry point from VIDEOPMI.DLL. The various PMI services are accessed through different function numbers passed in the parameters.
#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);
VIDEOPMI32Request Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - in/out Pointer to the current VIDEO_ADAPTERdata structure.
VIDEOPMI32Request Parameter - ulFunction
ulFunction(ULONG) - input Set to appropriate PMIREQUEST_ function.
VIDEOPMI32Request Parameter - pIn
pIn(PVOID) - input Pointer to applicable data structure.
VIDEOPMI32Request Parameter - pOut
pOut(PVOID) - output Pointer to applicable data structure.
VIDEOPMI32Request Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
VIDEOPMI32Request - Parameters
pAdapter(PVIDEO_ADAPTER) - in/out Pointer to the current VIDEO_ADAPTERdata 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_ADAPTERshould be set to sizeof(ADAPTERINFO) and sizeof(VIDEOMODEINFO ). This way, VIDEOPMI can handle callers built from different sizes of ADAPTERINFOVIDEOMODEINFOand 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_ADAPTERdata structure in Data Typesfor format and syntax information.
VIDEOPMI32Request - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_CLEANUP
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_CLEANUPcleans up the settings in extended registers.
#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);
PMIREQUEST_CLEANUP - Syntax
Description:
PMIREQUEST_CLEANUPcleans up the settings in extended registers.
#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);
PMIREQUEST_CLEANUP Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_CLEANUP Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_CLEANUP.
PMIREQUEST_CLEANUP Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_CLEANUP Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_CLEANUP Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_CLEANUP - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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_CLEANUP - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_GETBANK
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_GETBANKgets current bank.
#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);
PMIREQUEST_GETBANK - Syntax
Description:
PMIREQUEST_GETBANKgets current bank.
#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);
PMIREQUEST_GETBANK Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_GETBANK Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETBANK.
PMIREQUEST_GETBANK Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_GETBANK Parameter - pOut
pOut(PVOID) - output Pointer to a BANKDATAdata structure.
PMIREQUEST_GETBANK Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_GETBANK - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETBANK.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a BANKDATAdata 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 ulBankin the BANKDATAdata structure. miBankin BANKDATA is the current mode ID.
PMIREQUEST_GETBANK - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_GETCLUT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_GETCLUTgets a copy of Color Lookup Table from hardware.
#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);
PMIREQUEST_GETCLUT - Syntax
Description:
PMIREQUEST_GETCLUTgets a copy of Color Lookup Table from hardware.
#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);
PMIREQUEST_GETCLUT Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_GETCLUT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETCLUT.
PMIREQUEST_GETCLUT Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_GETCLUT Parameter - pOut
pOut(PVOID) - output Pointer to a CLUTDATAdata structure.
PMIREQUEST_GETCLUT Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_GETCLUT - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETCLUT.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a CLUTDATAdata 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_GETCLUT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_GETFONT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_GETFONTreads current font from video memory.
#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);
PMIREQUEST_GETFONT - Syntax
Description:
PMIREQUEST_GETFONTreads current font from video memory.
#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);
PMIREQUEST_GETFONT Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_GETFONT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETFONT.
PMIREQUEST_GETFONT Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_GETFONT Parameter - pOut
pOut(PVOID) - output Pointer to a FONTDATAdata structure.
PMIREQUEST_GETFONT Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_GETFONT - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETFONT.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a FONTDATAdata structure.
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_GETFONT - Remarks
ulCharCountin the FONTDATAdata structure is the number of characters in the font. ulFontHeightis the number of scanlines per character. bFontDatais the start of the font data. The size is (ulCharCount * ulFontHeight) bytes.
PMIREQUEST_GETFONT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_GETPALETTE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_GETPALETTEgets a copy of palette registers from hardware.
#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);
PMIREQUEST_GETPALETTE - Syntax
Description:
PMIREQUEST_GETPALETTEgets a copy of palette registers from hardware.
#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);
PMIREQUEST_GETPALETTE Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_GETPALETTE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETPALETTE.
PMIREQUEST_GETPALETTE Parameter - pInput
pInput(PVOID) - input NULL.
PMIREQUEST_GETPALETTE Parameter - pOut
pOut(PVOID) - output Pointer to a PALETTEDATAdata structure.
PMIREQUEST_GETPALETTE Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_GETPALETTE - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETPALETTE.
pInput(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a PALETTEDATAdata 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_GETPALETTE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_IDENTIFYADAPTER
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_IDENTIFYADAPTERexecutes the [IdentifyAdapter] section in the specified .PMI file.
#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);
PMIREQUEST_IDENTIFYADAPTER - Syntax
Description:
PMIREQUEST_IDENTIFYADAPTERexecutes the [IdentifyAdapter] section in the specified .PMI file.
#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);
PMIREQUEST_IDENTIFYADAPTER Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_IDENTIFYADAPTER Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_IDENTIFYADAPTER.
PMIREQUEST_IDENTIFYADAPTER Parameter - pIn
pIn(PVOID) - input Pointer to the ASCII string of the .PMI file.
PMIREQUEST_IDENTIFYADAPTER Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_IDENTIFYADAPTER Return Value - rc
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 - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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_LOADPMIFILEhas to be executed.
PMIREQUEST_IDENTIFYADAPTER - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_LOADPMIFILE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_LOADPMIFILEloads the specified .PMI file.
#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);
PMIREQUEST_LOADPMIFILE - Syntax
Description:
PMIREQUEST_LOADPMIFILEloads the specified .PMI file.
#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);
PMIREQUEST_LOADPMIFILE Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_LOADPMIFILE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_LOADFILE.
PMIREQUEST_LOADPMIFILE Parameter - pIn
pIn(PVOID) - input Pointer to the ASCII string of the .PMI file.
PMIREQUEST_LOADPMIFILE Parameter - pOut
pOut(PVOID) - output Pointer to BOOL; can be NULL.
PMIREQUEST_LOADPMIFILE Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_LOADPMIFILE - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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 Adapterfield in VIDEO_ADAPTERwill be filled with the information from the .PMI file.
If pOutis not NULL, *pOutis set to TRUE if the .PMI file is already loaded; FALSE, otherwise. Refer to ADAPTERINFOand VIDEO_ADAPTERdata structures in Data Typesfor format and syntax information.
PMIREQUEST_LOADPMIFILE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_LOCKREGISTERS
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_LOCKREGISTERSlocks extended registers.
#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);
PMIREQUEST_LOCKREGISTERS - Syntax
Description:
PMIREQUEST_LOCKREGISTERSlocks extended registers.
#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);
PMIREQUEST_LOCKREGISTERS Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_LOCKREGISTERS Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_LOCKREGISTERS.
PMIREQUEST_LOCKREGISTERS Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_LOCKREGISTERS Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_LOCKREGISTERS Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_LOCKREGISTERS - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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.
PMIREQUEST_LOCKREGISTERS - Remarks
The [LOCK] section in the .PMI file will be executed.
PMIREQUEST_LOCKREGISTERS - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_QUERYMAXMODEENTRIES
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_QUERYMAXMODEENTRIESreturns the number of mode entries in the . PMI file.
#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);
PMIREQUEST_QUERYMAXMODEENTRIES - Syntax
Description:
PMIREQUEST_QUERYMAXMODEENTRIESreturns the number of mode entries in the . PMI file.
#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);
PMIREQUEST_QUERYMAXMODEENTRIES Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_QUERYMAXMODEENTRIES Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODEENTRIES.
PMIREQUEST_QUERYMAXMODEENTRIES Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_QUERYMAXMODEENTRIES Parameter - pOut
pOut(PVOID) - output Pointer to a ULONG.
PMIREQUEST_QUERYMAXMODEENTRIES Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_QUERYMAXMODEENTRIES - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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.
PMIREQUEST_QUERYMAXMODEENTRIES - Remarks
None.
PMIREQUEST_QUERYMAXMODEENTRIES - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_QUERYMAXMODELISTSIZE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_QUERYMAXMODELISTSIZEreturns maximum size required to save a SetMode command list.
#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);
PMIREQUEST_QUERYMAXMODELISTSIZE - Syntax
Description:
PMIREQUEST_QUERYMAXMODELISTSIZEreturns maximum size required to save a SetMode command list.
#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);
PMIREQUEST_QUERYMAXMODELISTSIZE Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_QUERYMAXMODELISTSIZE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODELISTSIZE.
PMIREQUEST_QUERYMAXMODELISTSIZE Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_QUERYMAXMODELISTSIZE Parameter - pOut
pOut(PVOID) - output Pointer to a ULONG.
PMIREQUEST_QUERYMAXMODELISTSIZE Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_QUERYMAXMODELISTSIZE - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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.
PMIREQUEST_QUERYMAXMODELISTSIZE - 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_QUERYMAXMODELISTSIZE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_QUERYMAXTRAPENTRIES
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_QUERYMAXTRAPENTRIESreturns the maximum number of traplist entries in the [TRAPREGS] section of the .PMI file.
#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);
PMIREQUEST_QUERYMAXTRAPENTRIES - Syntax
Description:
PMIREQUEST_QUERYMAXTRAPENTRIESreturns the maximum number of traplist entries in the [TRAPREGS] section of the .PMI file.
#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);
PMIREQUEST_QUERYMAXTRAPENTRIES Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_QUERYMAXTRAPENTRIES Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXTRAPENTRIES.
PMIREQUEST_QUERYMAXTRAPENTRIES Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_QUERYMAXTRAPENTRIES Parameter - pOut
pOut(PVOID) - output Pointer to a ULONG.
PMIREQUEST_QUERYMAXTRAPENTRIES Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_QUERYMAXTRAPENTRIES - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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_QUERYMAXTRAPENTRIES - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_QUERYMODEHRDWRLIST
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_QUERYMODEHRDWRLISTreturns the SetMode hardware command list of the passed mode ID.
#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);
PMIREQUEST_QUERYMODEHRDWRLIST - Syntax
Description:
PMIREQUEST_QUERYMODEHRDWRLISTreturns the SetMode hardware command list of the passed mode ID.
#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);
PMIREQUEST_QUERYMODEHRDWRLIST Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTER data structure .
PMIREQUEST_QUERYMODEHRDWRLIST Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMODEHRDWRLIST.
PMIREQUEST_QUERYMODEHRDWRLIST Parameter - pIn
pIn(PVOID) - input Pointer to a ULONG.
PMIREQUEST_QUERYMODEHRDWRLIST Parameter - pOut
pOut(PVOID) - output Pointer to VOID.
PMIREQUEST_QUERYMODEHRDWRLIST Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
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_QUERYMODEHRDWRLIST - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_QUERYMODEINFODATA
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_QUERYMODEINFODATAcopies the PMI mode table to the caller.
#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);
PMIREQUEST_QUERYMODEINFODATA - Syntax
Description:
PMIREQUEST_QUERYMODEINFODATAcopies the PMI mode table to the caller.
#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);
PMIREQUEST_QUERYMODEINFODATA Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_QUERYMODEINFODATA Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMODEINFODATA.
PMIREQUEST_QUERYMODEINFODATA Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_QUERYMODEINFODATA Parameter - pOut
pOut(PVOID) - output Pointer to a MODEINFO data structure.
PMIREQUEST_QUERYMODEINFODATA Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_QUERYMODEINFODATA - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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
pOutis 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_QUERYMODEINFODATA - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_QUERYTRAPLISTDATA
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_QUERYTRAPLISTDATAreturns an array of trap register information structures in the [TRAPREG] section of the .PMI file.
#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);
PMIREQUEST_QUERYTRAPLISTDATA - Syntax
Description:
PMIREQUEST_QUERYTRAPLISTDATAreturns an array of trap register information structures in the [TRAPREG] section of the .PMI file.
#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);
PMIREQUEST_QUERYTRAPLISTDATA Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_QUERYTRAPLISTDATA Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYTRAPLISTDATA.
PMIREQUEST_QUERYTRAPLISTDATA Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_QUERYTRAPLISTDATA Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_QUERYTRAPLISTDATA Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_QUERYTRAPLISTDATA - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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_QUERYTRAPLISTDATA - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_RESTORESTATE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_RESTORESTATErestores the state of the hardware from supplied data.
#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);
PMIREQUEST_RESTORESTATE - Syntax
Description:
PMIREQUEST_RESTORESTATErestores the state of the hardware from supplied data.
#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);
PMIREQUEST_RESTORESTATE Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_RESTORESTATE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_RESTORESTATE.
PMIREQUEST_RESTORESTATE Parameter - pIn
pIn(PVOID) - input Pointer to a VIDEOSTATEdata structure.
PMIREQUEST_RESTORESTATE Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_RESTORESTATE Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_RESTORESTATE - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_RESTORESTATE.
pIn(PVOID) - input Pointer to a VIDEOSTATEdata 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_RESTORESTATE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_SAVESTATE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_SAVESTATEsaves partial or complete state of the hardware.
#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);
PMIREQUEST_SAVESTATE - Syntax
Description:
PMIREQUEST_SAVESTATEsaves partial or complete state of the hardware.
#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);
PMIREQUEST_SAVESTATE Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_SAVESTATE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_SAVESTATE.
PMIREQUEST_SAVESTATE Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_SAVESTATE Parameter - pOut
pOut(PVOID) - output Pointer to a VIDEOSTATEdata structure.
PMIREQUEST_SAVESTATE Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SAVESTATE - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_SAVESTATE.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a VIDEOSTATEdata structure.
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SAVESTATE - Remarks
miStatein the VIDEOSTATEdata structure is the current mode ID in VIDEOMODEINFO.
Four states can be saved and restored by setting fStateFlagsand related fields in VIDEOSTATE accordingly, as follows:
�Video mode (STATEFLAG_REGISTERS)
The Set Mode command list was saved in pModeDatawhen the mode was set. For saving state, the values of registers used by BOUTB are copied back to pModeData.For restoring state, pModeDatais executed to set the mode.
�Video Memory (STATEFLAG_VRAM)
Video memory of size ulVRAMSaveSizeis saved to pVRAMin saving state or restored from pVRAMin 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_SAVESTATE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_SETBANK
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_SETBANKsets bank to requested value.
#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);
PMIREQUEST_SETBANK - Syntax
Description:
PMIREQUEST_SETBANKsets bank to requested value.
#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);
PMIREQUEST_SETBANK Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_SETBANK Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETBANK.
PMIREQUEST_SETBANK Parameter - pIn
pIn(PVOID) - input Pointer to a BANKDATAdata structure.
PMIREQUEST_SETBANK Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_SETBANK Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SETBANK - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETBANK.
pIn(PVOID) - input Pointer to a BANKDATAdata structure.
pOut(PVOID) - output NULL.
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SETBANK - Remarks
See PMIREQUEST_GETBANK.
Before the [SETBANK] section in the .PMI file is executed, r0 is set to ulBank. in the BANKDATAdata structure. The current bank is set to ulBank in the BANKDATA data structure by executing the [SETBANK] section.
PMIREQUEST_SETBANK - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_SETCLUT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_SETCLUTsets Color Lookup Table to supplied values.
#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);
PMIREQUEST_SETCLUT - Syntax
Description:
PMIREQUEST_SETCLUTsets Color Lookup Table to supplied values.
#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);
PMIREQUEST_SETCLUT Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_SETCLUT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETCLUT.
PMIREQUEST_SETCLUT Parameter - pIn
pIn(PVOID) - input Pointer to a CLUTDATAdata structure.
PMIREQUEST_SETCLUT Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_SETCLUT Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SETCLUT - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETCLUT.
pIn(PVOID) - input Pointer to a CLUTDATAdata structure.
pOut(PVOID) - output NULL.
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SETCLUT - Remarks
See PMIREQUEST_GETCLUT.
PMIREQUEST_SETCLUT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_SETFONT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_SETFONTsets font to that supplied.
#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);
PMIREQUEST_SETFONT - Syntax
Description:
PMIREQUEST_SETFONTsets font to that supplied.
#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);
PMIREQUEST_SETFONT Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_SETFONT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETFONT.
PMIREQUEST_SETFONT Parameter - pIn
pIn(PVOID) - input Pointer to a FONTDATAdata structure.
PMIREQUEST_SETFONT Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_SETFONT Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SETFONT - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETFONT.
pIn(PVOID) - input Pointer to a FONTDATAdata 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_SETFONT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_SETMEMORYIOADDRESS
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_SETMEMORYIOADDRESSsets the linear aperture to the passed address.
#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);
PMIREQUEST_SETMEMORYIOADDRESS - Syntax
Description:
PMIREQUEST_SETMEMORYIOADDRESSsets the linear aperture to the passed address.
#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);
PMIREQUEST_SETMEMORYIOADDRESS Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_SETMEMORYIOADDRESS Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMEMORYIOADDRESS.
PMIREQUEST_SETMEMORYIOADDRESS Parameter - pIn
pIn(PVOID) - input Pointer to the address to be set.
PMIREQUEST_SETMEMORYIOADDRESS Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_SETMEMORYIOADDRESS Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SETMEMORYIOADDRESS - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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_SETMODEis called with the SET_LINEAR_BUFFER_MODE flag set to on. In this case, the address is set to pAdapter->ModeInfo.ulBufferAddress.
PMIREQUEST_SETMEMORYIOADDRESS - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_SETMODE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_SETMODEsets requested video mode through the passed mode ID.
#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);
PMIREQUEST_SETMODE - Syntax
Description:
PMIREQUEST_SETMODEsets requested video mode through the passed mode ID.
#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);
PMIREQUEST_SETMODE Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_SETMODE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMODE.
PMIREQUEST_SETMODE Parameter - pIn
pIn(PVOID) - input Pointer to mode ID from the VIDEOMODEINFOdata structure.
PMIREQUEST_SETMODE Parameter - pOut
pOut(PVOID) - output Pointer to the SetMode hardware command list.
PMIREQUEST_SETMODE Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SETMODE - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMODE.
pIn(PVOID) - input Pointer to mode ID from the VIDEOMODEINFOdata 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 pOutis 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 pOutpoints 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_ SETMEMORYIOADDRESSwill be called implicitly with pAdapter->ModeInfo. ulBufferAddress as the input parameter used to set the linear aperture.
PMIREQUEST_SETMODE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_SETPALETTE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_SETPALETTEsets palette registers to supplied values.
#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);
PMIREQUEST_SETPALETTE - Syntax
Description:
PMIREQUEST_SETPALETTEsets palette registers to supplied values.
#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);
PMIREQUEST_SETPALETTE Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_SETPALETTE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETPALETTE.
PMIREQUEST_SETPALETTE Parameter - pIn
pIn(PVOID) - input Pointer to a PALETTEDATAdata structure.
PMIREQUEST_SETPALETTE Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_SETPALETTE Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_SETPALETTE - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
ulFunction(ULONG) - input Set equal to PMIREQUEST_SETPALETTE.
pIn(PVOID) - input Pointer to a PALETTEDATAdata 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_SETPALETTE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_SOFTWAREINT
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_SOFTWAREINTinitializes and/or executes a real-mode software interrupt.
#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);
PMIREQUEST_SOFTWAREINT - Syntax
Description:
PMIREQUEST_SOFTWAREINTinitializes and/or executes a real-mode software interrupt.
#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);
PMIREQUEST_SOFTWAREINT Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Can be NULL. If not NULL, the adapter must have been loaded.
PMIREQUEST_SOFTWAREINT Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_SOFTWAREINT.
PMIREQUEST_SOFTWAREINT Parameter - pIn
pIn(PVOID) - input Pointer to an INITVDMdata structure.
INITVDM defines how the worker routine will be initialized; can be NULL.
PMIREQUEST_SOFTWAREINT Parameter - pOut
pOut(PVOID) - output Pointer to an INTCRFdata structure.
INTCRF includes client stack frame and an input/output buffer.
PMIREQUEST_SOFTWAREINT Return Value - rc
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 - 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 INITVDMdata structure.
INITVDM defines how the worker routine will be initialized; can be NULL.
pOut(PVOID) - output Pointer to an INTCRFdata 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 pInparameter. 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_SOFTWAREINT - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_TUNEDISPLAY
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_TUNEDISPLAYexecutes the [TuneDisplay] section in the .PMI file.
#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);
PMIREQUEST_TUNEDISPLAY - Syntax
Description:
PMIREQUEST_TUNEDISPLAYexecutes the [TuneDisplay] section in the .PMI file.
#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);
PMIREQUEST_TUNEDISPLAY Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_TUNEDISPLAY Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_TUNEDISPLAY.
PMIREQUEST_TUNEDISPLAY Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_TUNEDISPLAY Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_TUNEDISPLAY Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_TUNEDISPLAY - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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_TUNEDISPLAY - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_UNLOCKREGISTERS
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_UNLOCKREGISTERSunlocks extended registers.
#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);
PMIREQUEST_UNLOCKREGISTERS - Syntax
Description:
PMIREQUEST_UNLOCKREGISTERSunlocks extended registers.
#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);
PMIREQUEST_UNLOCKREGISTERS Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_UNLOCKREGISTERS Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_UNLOCKREGISTERS.
PMIREQUEST_UNLOCKREGISTERS Parameter - pIn
pIn(PVOID) - input NULL.
PMIREQUEST_UNLOCKREGISTERS Parameter - pOut
pOut(PVOID) - output NULL.
PMIREQUEST_UNLOCKREGISTERS Return Value - rc
rc(APIRET) - returns Return codes.
Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.
PMIREQUEST_UNLOCKREGISTERS - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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_UNLOCKREGISTERS - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
PMIREQUEST_UNLOADPMIFILE
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
PMIREQUEST_UNLOADPMIFILEunloads 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.
#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);
PMIREQUEST_UNLOADPMIFILE - Syntax
Description:
PMIREQUEST_UNLOADPMIFILEunloads 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.
#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);
PMIREQUEST_UNLOADPMIFILE Parameter - pAdapter
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .
PMIREQUEST_UNLOADPMIFILE Parameter - ulFunction
ulFunction(ULONG) - input Set equal to PMIREQUEST_UNLOADFILE.
PMIREQUEST_UNLOADPMIFILE Parameter - pIn
pIn(PVOID) - input Pointer to the ASCII string of the .PMI file.
PMIREQUEST_UNLOADPMIFILE Parameter - pOut
pOut(PVOID) - output NULL
PMIREQUEST_UNLOADPMIFILE Return Value - rc
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 - Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata 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.
PMIREQUEST_UNLOADPMIFILE - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
Code Sample
The following code sample shows how to load the .PMI file, set up the mode table, and set the graphics mode.
#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;
}
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 SVPMIstandard.
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 Filesin PMI Language Elementsand PMI Sectionsfor more detail.
Note:The imported library (OEMPMI.DLL) that is shipped with the IBM Developer Connection Device Driver Kit for OS/2illustrates 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.
/* ** 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
/*
** 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 ;
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 Supportin 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 Supportin 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.
<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>
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).
<string> ::= "<ASCII character> [<string>]" <binary-string> ::= " <'0'|'1'> | <'0'|1'> [<binary-string>]"
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.
<name> ::= <character> <token>
<token> ::= {<character> | [<digit> <token>]}
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 Sectionsfor more information on dynamic vs. static keyvariables.
Not all of the PMI keyvariables have to be defined. See [ModeInfo] and [ Hardware] in PMI Sectionsfor further explanations.
PMI Keyvariables
The following table lists all of the keyvariables for the Protect Mode Interface (PMI).
/-------------------------------------------------\ |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).
/-------------------------------------------------\ |Name |Section | |------------------------+------------------------| |BIG |Hardware | |------------------------+------------------------| |EISA |Hardware | |------------------------+------------------------| |ISA |Hardware | |------------------------+------------------------| |LITTLE |Hardware | |------------------------+------------------------| |MCA |Hardware | |------------------------+------------------------| |MMIO |Declarations | |------------------------+------------------------| |PCI |Hardware | |------------------------+------------------------| |PCMCIA** |Hardware | |------------------------+------------------------| |PIO |Declarations | |------------------------+------------------------| |VLB |Hardware | \-------------------------------------------------/
PMI Keywords
The following table lists the reserved identifiers, called Keywords, used by the Protect Mode Interface (PMI).
/-------------------------------------------------------------\ |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 | \-------------------------------------------------------------/
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.
<memory-mapped variable> ::= <mmio variable> = 'MMIO{'<number>'}'
<port-variable declaration> ::= <pio variable> = 'PIO{'<number>'}'
<mmio variable> ::= <name>
<pio variable> ::= <name>
For example:
seq_address = PIO{0x3c4};
interrupt_en = MMIO{0x00000080}
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.
<label> ::= <name>':'
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.
<register> = r<'0'..'255'>
Operators, Assignment Expressions, and Conditional Expressions
The following operators are valid in the PMI syntax:
<postfix unary additive op> ::= '++' | '--' <additive op> ::= '+' | '-' <shift op> ::= '<<' | '>>' <bitwise op> ::= '&' | '|' | '^' <relational op> ::= '<' | '>' | '==' | '<=' | '>=' | '!=' <binary assignment op> ::= '&=' | '|= ' | '<<=' | '>>=' | '+=' | '-=' | '^=' <unary negation op> ::= '~' <assignment op> ::= '='
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.
<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>
Examples:
r0 = VerticalRefresh; r0 <<= 0x10; r1++; r2--; r1 = ~r2 ^ 0x04; r2 = XResolution << r1; r1 = r2 + 0xffff;
A conditional expression and example are shown below.
<condition> ::=
'(' { <PMI Keyvariable> | <register>} {<relational op> | <bitwise op>}
{ <PMI Keyvariable> | <register> | <constant> } ')'
Examples:
(XResolution == 1024) (r1 & 0x0fe0) (r2 == VerticalRefresh)
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_ADAPTERstructure 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:
INB( destination, source); INW( destination, source); INDW( destination, source); <destination> ::= <register> <source> ::= <constant> | <pio variable>
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:
OUTB( destination, source);
OUTW( destination, source);
OUTDW( destination, source);
<destination> ::= <pio variable> | <constant>
<source> ::= {<constant> | <register>}
For example:
outb(seq_address,r1); //seq_address must have been declared. outw(0x3c4,0x5520);
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 startindexfield 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.
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>
For example:
r0 = 0x11; r1 = 0x12; r2 = 0x13;
boutb(0x03, 0x00, seq_address, seq_data); //seq_address and seq_data
//already declared.
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:
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>
For example:
rmww(0x4ae8, 0x4ae8, 0x01, 0x00);
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:
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>
For example:
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.
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.
WAIT( port, andmask, timeout, waitonvalue ); <andmask> ::= <number> <timeout> ::= <number> <waitonvalue> ::= <number> <port> ::= < constant> | <pio variable> | <mmio variable>
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.
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
For example:
if (r1 != 0x88) goto done
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.
STRCMP(<destination>, <source>}; <destination> ::= <address> ;physical address <source> ::= <string>) MEMCMP(<destination>, <source>}; <source> ::= <binary-string> <address> ::= <PMI keyvariable> | <constant>
For example:
MEMCMP (0xc0154,"1001001111010001"); //compare 2 bytes at 0xc0154 with 0x93d1
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.
/-----------------------------------------------------------------------------\ |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 VIDEOMODEINFOstructure 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:
BusType = VLB OEMString = "P9000 VIPER, Diamond Computer Systems Inc." DACString = "Brooktree Corporation" Version = "3.2" TotalMemory = 2097152 MemoryIOAddress = 0x80000000 PortIOAddress = 0x00000000 Endian = LITTLE
[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:
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}
[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_SETMODEfor 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:
inb(r0, 0x3d4); //save index outb(0x3d4, 0x38); outb(0x3d5, 0x48); outb(0x3d4, 0x39); outb(0x3d5, 0xa0); outb(0x3d4, r0); //restore index
[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:
[Cleanup]
//reset DAC
r0 = 0x00000000;
r1 = 0x00000000;
ProgramDAC;
//reset clock to 60Hz, 32 KHz
r0 = 0x0045A8BC;
ProgramClock;
//enable VGA
DisableController;
[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:
[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
[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:
[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
[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:
[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:
[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 ]
-Not used internally; available to drivers through a mode query.
-If not specified, zeros are returned.
�ColorWeight = <constant> ':' <constant> ':' <constant>
-Static PMI keyvariable. Optional.
-User defined.
-Required for hi-color and true-color modes.
-Not used internally; available to drivers through a mode query.
-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.
-Size of the aperture. If ApertureSize < SaveSize and BufferAddress is not 0, SetBank and GetBank sections are required.
-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:
[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
[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.
-Vertical refresh in Hz, rounded to the nearest integer.
-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.
-Horizontal refresh in KHz, rounded to the nearest integer.
-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.
-Dynamic PMI keyvariable. Not required.
-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.
-Dynamic PMI keyvariable. Not required.
-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:
[MonitorModeInfo] //1024 x 768 resolution VerticalRefresh = 80 HorizontalRefresh = 64 VPolarityPositive = 1 HPolarityPositive = 1 ScreenLeftEdge = 0x00000047 ScreenRightEdge = 0x00000147 ScreenTopEdge = 0x00000023 ScreenBottomEdge = 0x00000323
[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 Modesand [EnableController] in this chapter for more information.
Here is a sample .PMI file for a Viper VLB card:
[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
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 "read" 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 "Capabilities" 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
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
AddMonitorDataadds a monitor definition to the VIDEOCFG.DLL monitor definitions database. The monitor definition is also written to the MONITOR .DIF file.
#include <svgadefs.h> MONITORINFO *pNewMonitorInfo; /* Pointer to the MONITORINFO data structure. */ ULONG rc; /* Return codes. */ rc = AddMonitorData(*pNewMonitorInfo);
AddMonitorData - Syntax
Description:
AddMonitorDataadds a monitor definition to the VIDEOCFG.DLL monitor definitions database. The monitor definition is also written to the MONITOR .DIF file.
#include <svgadefs.h> MONITORINFO *pNewMonitorInfo; /* Pointer to the MONITORINFO data structure. */ ULONG rc; /* Return codes. */ rc = AddMonitorData(*pNewMonitorInfo);
AddMonitorData Parameter - *pNewMonitorInfo
*pNewMonitorInfo(MONITORINFO) - input Pointer to the MONITORINFO data structure.
This parameter points to the MONITORINFOdata 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
Nonzero Returns one of the following errors:
ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT
AddMonitorData - Parameters
*pNewMonitorInfo(MONITORINFO) - input Pointer to the MONITORINFO data structure.
This parameter points to the MONITORINFOdata structure that specifies the new monitor definition to add to the database.
rc(ULONG) - returns Return codes.
0 Function is successful
Nonzero Returns one of the following errors:
ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT
AddMonitorData - Remarks
None.
AddMonitorData - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GetAllMonitors
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GetAllMonitorsretrieves all monitor definitions. These monitor definitions are defined in the MONITOR.DIF file.
#include <svgadefs.h> 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);
GetAllMonitors - Syntax
Description:
GetAllMonitorsretrieves all monitor definitions. These monitor definitions are defined in the MONITOR.DIF file.
#include <svgadefs.h> 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);
GetAllMonitors Parameter - *pMonitors
*pMonitors(MONITORINFO) - output Pointer to the array of MONITORINFOdata 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 pMonitorsbuffer, 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
Nonzero Returns one of the following errors:
ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT
ERROR_NOT_ENOUGH_MEMORY
GetAllMonitors - Parameters
*pMonitors(MONITORINFO) - output Pointer to the array of MONITORINFOdata 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 pMonitorsbuffer, 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
Nonzero Returns one of the following errors:
ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT
ERROR_NOT_ENOUGH_MEMORY
GetAllMonitors - Remarks
None.
GetAllMonitors - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GetCurrentCFG
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GetCurrentCFGgets the current video configuration stored in the Registry.
#include <svgadefs.h> ADAPTERINFO *pAdapter; /* Pointer to the ADAPTERINFO data structure. */ MONITORINFO *pMonitor; /* Pointer to the MONITORINFO data structure. */ ULONG rc; /* Return codes. */ rc = GetCurrentCFG(*pAdapter, *pMonitor);
GetCurrentCFG - Syntax
Description:
GetCurrentCFGgets the current video configuration stored in the Registry.
#include <svgadefs.h> ADAPTERINFO *pAdapter; /* Pointer to the ADAPTERINFO data structure. */ MONITORINFO *pMonitor; /* Pointer to the MONITORINFO data structure. */ ULONG rc; /* Return codes. */ rc = GetCurrentCFG(*pAdapter, *pMonitor);
GetCurrentCFG Parameter - *pAdapter
*pAdapter(ADAPTERINFO) - output Pointer to the ADAPTERINFOdata structure.
This parameter points to the data structure receiving the current video adapter information.
GetCurrentCFG Parameter - *pMonitor
*pMonitor(MONITORINFO) - output Pointer to the MONITORINFOdata 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
Nonzero Returns one of the following errors:
ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION
GetCurrentCFG - Parameters
*pAdapter(ADAPTERINFO) - output Pointer to the ADAPTERINFOdata structure.
This parameter points to the data structure receiving the current video adapter information.
*pMonitor(MONITORINFO) - output Pointer to the MONITORINFOdata structure.
This parameter points to the data structure receiving the current video monitor information.
rc(ULONG) - returns Return codes.
0 Function is successful
Nonzero Returns one of the following errors:
ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION
GetCurrentCFG - Remarks
None.
GetCurrentCFG - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
GetCurrentDesktopMode
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
GetCurrentDesktopModeretrieves 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.
#include <svgadefs.h> VIDEO_ADAPTER *pVideoAdapter; /* Pointer to the VIDEO_ADAPTER data structure. */ ULONG rc; /* Return codes. */ rc = GetCurrentDesktopMode(*pVideoAdapter);
GetCurrentDesktopMode - Syntax
Description:
GetCurrentDesktopModeretrieves 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.
#include <svgadefs.h> VIDEO_ADAPTER *pVideoAdapter; /* Pointer to the VIDEO_ADAPTER data structure. */ ULONG rc; /* Return codes. */ rc = GetCurrentDesktopMode(*pVideoAdapter);
GetCurrentDesktopMode Parameter - *pVideoAdapter
*pVideoAdapter(VIDEO_ADAPTER) - output Pointer to the VIDEO_ADAPTERdata 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
FALSE Function is unsuccessful.
GetCurrentDesktopMode - Parameters
*pVideoAdapter(VIDEO_ADAPTER) - output Pointer to the VIDEO_ADAPTERdata structure.
This parameter points to the data structure receiving the desktop mode information.
rc(ULONG) - returns Return codes.
TRUE Function is successful
FALSE Function is unsuccessful.
GetCurrentDesktopMode - Remarks
None.
GetCurrentDesktopMode - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
QueryNumMonitors
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
QueryNumMonitorsqueries the number of monitor defintions available.
#include <svgadefs.h> PULONG pulNumMonitors; /* Pointer to variable receiving the number of monitor definitions. */ ULONG rc; /* Return codes. */ rc = QueryNumMonitors(pulNumMonitors);
QueryNumMonitors - Syntax
Description:
QueryNumMonitorsqueries the number of monitor defintions available.
#include <svgadefs.h> PULONG pulNumMonitors; /* Pointer to variable receiving the number of monitor definitions. */ ULONG rc; /* Return codes. */ rc = QueryNumMonitors(pulNumMonitors);
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
Nonzero Returns the following error:
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
Nonzero Returns the following error:
ERROR_NO_MONITOR_SUPPORT
QueryNumMonitors - Remarks
None.
QueryNumMonitors - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
SetCurrentCFG
Select an item:
Syntax Parameters Returns Remarks Glossary
Description:
SetCurrentCFGsets the current video configuration in the Registry.
#include <svgadefs.h> ADAPTERINFO *pAdapter; /* Pointer to the ADAPTERINFO data structure. */ MONITORINFO *pMonitor; /* Pointer to the MONITORINFO data structure. */ ULONG rc; /* Return codes. */ rc = SetCurrentCFG(*pAdapter, *pMonitor);
SetCurrentCFG - Syntax
Description:
SetCurrentCFGsets the current video configuration in the Registry.
#include <svgadefs.h> ADAPTERINFO *pAdapter; /* Pointer to the ADAPTERINFO data structure. */ MONITORINFO *pMonitor; /* Pointer to the MONITORINFO data structure. */ ULONG rc; /* Return codes. */ rc = SetCurrentCFG(*pAdapter, *pMonitor);
SetCurrentCFG Parameter - *pAdapter
*pAdapter(ADAPTERINFO) - input Pointer to the ADAPTERINFOdata 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 MONITORINFOdata 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
Nonzero Returns one of the following errors:
ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION
SetCurrentCFG - Parameters
*pAdapter(ADAPTERINFO) - input Pointer to the ADAPTERINFOdata 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 MONITORINFOdata 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
Nonzero Returns one of the following errors:
ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION
SetCurrentCFG - Remarks
None.
SetCurrentCFG - Topics
Select an item:
Syntax Parameters Returns Remarks Glossary
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
Select an item:
Syntax Parameters Returns Glossary
Simulation support:
This function is optional for display drivers and has no simulation support .
Description:
GreEscape DEVESC_QUERYDRIVERCAPSreturns 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.
#define INCL_GRE_DEVICE
#include <GRADD.h>
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);
GreEscape DEVESC_QUERYDRIVERCAPS - Syntax
Simulation support:
This function is optional for display drivers and has no simulation support .
Description:
GreEscape DEVESC_QUERYDRIVERCAPSreturns 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.
#define INCL_GRE_DEVICE
#include <GRADD.h>
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);
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 DRIVERCAPSstructures.
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 DRIVERCAPSstructures.
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_QUERYDRIVERCAPS - Topics
Select an item:
Syntax Parameters Returns Glossary
GreEscape DEVESC_QUERYDRIVERCAPSLIST
Select an item:
Syntax Parameters Returns Glossary
Simulation support:
This function is optional for display drivers and has no simulation support .
Description:
GreEscape DEVESC_QUERYDRIVERCAPSLISTfills the pValueList, pCurrentValue,and pDefaultValuein the DRIVERCAPSdata structure. The members must be 0 padded up to the ulValueMemberSizein 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:
#define CAPSTYPE_BOOLEAN 1L #define CAPSTYPE_AGGREGATE_INT 2L #define CAPSTYPE_AGGREGATE_STRING 3L
#define INCL_GRE_DEVICE
#include <GRADD.h>
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);
GreEscape DEVESC_QUERYDRIVERCAPSLIST - Syntax
Simulation support:
This function is optional for display drivers and has no simulation support .
Description:
GreEscape DEVESC_QUERYDRIVERCAPSLISTfills the pValueList, pCurrentValue,and pDefaultValuein the DRIVERCAPSdata structure. The members must be 0 padded up to the ulValueMemberSizein 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:
#define CAPSTYPE_BOOLEAN 1L #define CAPSTYPE_AGGREGATE_INT 2L #define CAPSTYPE_AGGREGATE_STRING 3L
#define INCL_GRE_DEVICE
#include <GRADD.h>
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);
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 DRIVERCAPSdata structure.
The DRIVERCAPSdata 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 DRIVERCAPSdata structure.
The DRIVERCAPSdata 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:
Syntax Parameters Returns Glossary
GreEscape DEVESC_SETDRIVERCAPSVALUE
Select an item:
Syntax Parameters Returns Glossary
Simulation support:
This function is optional for display drivers and has no simulation support .
Description:
GreEscape DEVESC_SETDRIVERCAPSVALUEwill 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.
#define INCL_GRE_DEVICE
#include <GRADD.h>
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);
GreEscape DEVESC_SETDRIVERCAPSVALUE - Syntax
Simulation support:
This function is optional for display drivers and has no simulation support .
Description:
GreEscape DEVESC_SETDRIVERCAPSVALUEwill 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.
#define INCL_GRE_DEVICE
#include <GRADD.h>
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);
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 DRIVERCAPSdata 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 DRIVERCAPSdata 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:
Syntax Parameters Returns Glossary
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.
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, "WINPRF", &hMod) ||
DosQueryProcAddr(hMod, 0, "WPFOPENPROFILELIST", (PFN *)&pWpfOpenProfileList) ||
DosQueryProcAddr(hMod, 0, "WPFCLOSEPROFILELIST", (PFN *)&pWpfCloseProfileList) ||
DosQueryProcAddr(hMod, 0, "WPFWRITEPROFILELISTLINE", (PFN *)&pWpfWriteProfileListLine))
{
return FALSE;
}
// Open the profile handler.
if (hWpf = (*pWpfOpenProfileList)())
{
/*
** szUpdateString has the following format
**
** <profile name> <section> <keyword> [value]
**
** ex. "system.ini boot sdisplay.drv wd3116sl.drv" will insert the line
** sdisplay.drv=wd3116sl.drv in the boot section of system.ini
**
** if [value] is omitted, the <keyword> 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 &= res1;
}
else
{
result = FALSE;
}
return result;
}
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 "DDC" 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 "DEFAULT" entry in the refresh listbox mean? If the very first VIDEO.CFG has 0xFF for the resolutions vertical refresh, the entry "DEFAULT " 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 "DEFAULT" 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 " DEFAULT" would put the "DEFAULT" 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
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 ".h". Assembler support is provided in the include files identified by the filename extension ".INC".
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.
�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:
hdc /* device context handle */
pszFilename /* pointer to a character string */
The following standard base tags and their associated type names are defined:
/------------------------------------------------------------------------\ |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. | \------------------------------------------------------------------------/
The following standard prefixes are also defined:
/-------------------------------------------------------------\ |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 . | \ ---------- - ---------- ---------- ---------- ---------- ---------- /
Some parameters are used in pairs; the qualifiers that are used reflect the relationship between the two variables. For example:
/--------------------------------------------------------------------------------\ |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 > with Min or < = with Max is almost | | |always an "off-by-one" error. | | |For example, to determine whether an ich is within ichMin and | | |ichMax: if (ich >= ichMin && 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. | \--------------------------------------------------------------------------------/
The base types and their prefixes are defined as follows:
/-----------------------------------------------\ |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 | \ ---------- ---------- ---- - ---------- ---------- -- /
Parameters for defined structures are the defined parameter names. For example:
--------------------------------------------------------------
AREADEFS struct
{
defSet
fFlags
CodePage
}AREADEFS
--------------------------------------------------------------
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.
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 ;
ADAPTERINFO Field - cb
cb(ULONG) Length of the structure.
ADAPTERINFO Field - ulAdapterID
ulAdapterID(ULONG) Specifies the adapter by ID.
ADAPTERINFO Field - szOEMString[MAX_OEM_STRING]
szOEMString[MAX_OEM_STRING](CHAR) Contains adapter information.
Valid value is as follows:
MAX_OEM_STRING 128
ADAPTERINFO Field - szDACString[MAX_DAC_STRING]
szDACString[MAX_DAC_STRING](CHAR) Contains DAC information.
Valid value is as follows:
MAX_DAC_STRING 128
ADAPTERINFO Field - szRevision[MAX_VERSION]
szRevision[MAX_VERSION](CHAR) Contains version information.
Valid value is as follows:
MAX_VERSION 128
ADAPTERINFO Field - ulTotalMemory
ulTotalMemory(ULONG) Total video memory.
ADAPTERINFO Field - ulMMIOBaseAddress
ulMMIOBaseAddress(ULONG) Base address for memory-mapped I/O registers.
ADAPTERINFO Field - ulPIOBaseAddress
ulPIOBaseAddress(ULONG) Base address for I/O ports.
ADAPTERINFO 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
ADAPTERINFO Field - usDeviceBusID
usDeviceBusID(USHORT) Reserved.
ADAPTERINFO Field - usVendorBusID
usVendorBusID(USHORT) Reserved.
ADAPTERINFO Field - usSlotID
usSlotID(USHORT) Reserved.
APIRET
Unsigned integer in the range 0 through 4 294 967 295.
typedef unsigned long APIRET;
BANKDATA
The BANKDATA data structure contains the current mode ID and the bank number.
typedef struct _BANKDATA {
MODEID miBank; /* ID of the current mode. */
ULONG ulBank; /* Current bank number. */
} BANKDATA;
typedef BANKDATA * FAR * PBANKDATA ;
BANKDATA Field - miBank
miBank(MODEID) ID of the current mode.
BANKDATA Field - ulBank
ulBank(ULONG) Current bank number.
BITBLTINFO
BitBlt information structure. BitBlt information structure, used for the GHI_CMD_BITBLTand VMI_CMD_BITBLT. functions.
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 ;
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 POINTLs.
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.
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 ;
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.
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 ;
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.
BMAP_MEMORY Bit map is in system memory.
BMAP_VERTICAL_SCAN Scan lines are in a vertical format instead of the default horizontal format.
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 INTCRFcontaining the input/output buffers for the bios call.
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 ;
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
pAddressLinear address of the buffer.
BUFFER Field - ulSize
ulSize(ULONG)
CAPSINFO
GRADD capability information.
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 ;
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 "Base Function."
The following definition is provided:
- define BASE_FUNCTION_CLASS "Base Function"
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. */
#define TEXTBLT_DOWNLOADABLE 0x00002000 /* Downloadable fonts supported. */
#define TEXTBLT_CLIPABLE 0x00004000 /* Clipable fonts. */
#define TEXTBLT_DS_DEVICE_FONTS 0x00008000 /* Device supports hardware fonts. */
#define DS_SIMPLE_LINES 0x00800000 /* GRADD handles LINEINFO2. */
CHAININFO
Information returned to callers of the VMI_CMD_QUERYCHAININFOfunction.
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 ;
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 RGBarray entries.
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 ;
CLUTDATA Field - ulRGBCount
ulRGBCount(ULONG) Number of aRGB entries that follow.
CLUTDATA Field - ulRGBStart
ulRGBStart(ULONG) Start index for RGBtriplets.
CLUTDATA Field - aRGB[1]
aRGB[1](SVGARGB) Start of SVGARGB; one entry is allocated.
CODECINFO
Determines whether data is to be compressed or decompressed.
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 ;
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 "ULTI"
CODEC_INDEO21 "RT21"
CODEC_INDEO31 "IV31"
CODEC_MPEG1 "MPG1"
CODEC_MPEG2 "MPG2"
CODEC_MJPEG "MJPG"
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.
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 ;
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)
((ULONG)(BYTE)(ch0) | ((ULONG)(BYTE)(ch1) <<8) | \
((ULONG)(BYTE)(CH2)<<16) | ((ULONG)(BYTE)(CH3)<<24))
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.
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 ;
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_QUERYDRIVERCAPSfunctions.
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 ;
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
#define CAPSTYPE_AGGREGATE_INT 2L
#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_TEXTand VMI_CMD_TEXTfunctions. The TEXTBLTINFOstructure includes a pointer to DEVFONTINFO.
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 ;
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.
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 ;
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.
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 ;
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.
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 ;
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.
typedef struct _GDDINITOUT {
ULONG ulLength; /* Length of the GDDINITOUT data structure, in bytes. */
ULONG cFunctionClasses; /* Number of function classes supported. */
} GDDINITOUT;
typedef GDDINITOUT * PGDDINITOUT ;
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.
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 ;
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.
typedef struct _GHBTBL {
PGLBTBL pglbTbl[1]; /* Up to 256 entries per table */
} GHBTBL;
typedef GHBTBL * PGHBTBL ;
GHBTBL Field - pglbTbl[1]
pglbTbl[1](PGLBTBL) Up to 256 entries per table
GLBTBL
Glyph low byte table.
typedef struct _GLBTBL {
PGLYPHINFO pGlyphInfo[1]; /* Up to 256 entries per table */
} GLBTBL;
typedef GLBTBL * PGLBTBL ;
GLBTBL Field - pGlyphInfo[1]
pGlyphInfo[1](PGLYPHINFO) Up to 256 entries per table
GRADDINFO
Information describing an individual GRADD.
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 ;
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 TEXTBLTINFOstructure.
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 ;
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_TEXTand VMI_CMD_TEXTfunctions.
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 ;
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_TEXTand VMI_CMD_TEXTfunctions.
typedef struct _HWBANKOUT {
ULONG ulLength; /* Length of the HWBANKOUT data structure, in bytes. */
ULONG ulBank; /* Bank number. */
} HWBANKOUT;
typedef HWBANKOUT * PHWBANKOUT ;
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_EVENTfunction.
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 ;
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
EVENT_FOREGROUND
EVENT_NEWCHAININFO
HWEVENTIN Field - pEventData
pEventData(ULONG) Pointer to event-specific data.
HWEXTENSION
Input data to the GHI_CMD_EXTENSIONfunction.
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 ;
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.
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 ;
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 ptlPosfield.
HWPALETTEINFO
Input packet provided to the GRADD in the GHI_CMD_PALETTEfunction.
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 ;
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
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 RGBvalues.
HWREQIN
Input packet to the GHI_CMD_REQUESTHWfunction.
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 ;
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
#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.
�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.
�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.
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 ;
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.
typedef struct _HWSETPTROUT {
ULONG ulLength; /* Size of the HWSETPTROUT data structure, in bytes. */
ULONG ulStatus; /* Current cursor description bits. */
} HWSETPTROUT;
typedef HWSETPTROUT * PHWSETPTROUT ;
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.
POINTER_COLOR 0x0002; cursor is color (vs. monochrome).
POINTER_SOFTWARE 0x0004; this GRADD is not using a hardware sprite.
HWSHOWPTRIN
Input packet to the GHI_CMD_SHOWPTR function.
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 ;
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.
FALSE Pointer is not visible.
IMAGEBUF
Characteristics describing an image.
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 ;
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
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.
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 ;
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
IMAGECAPS_CAPTURE 0x0002; has capture to VRAM hardware present
IMAGECAPS_1X_BLT 0x0004; has nonstretch Blt assist
IMAGECAPS_WINDOWCLIP 0x0008; supports clipping in hardware and/or software
IMAGECAPS_BUFALLOC 0x0010; supports allocation of on-card memory
IMAGECAPS_RECTALLOC 0x0020; supports allocation of rectangles in on-card memory
IMAGECAPS_COMP 0x0040; compression supported by driver
IMAGECAPS_DECOMP 0x0080; decompression supported by driver
IMAGECAPS_PAL_CACHING 0x0100; supports 8-bit palette caching
IMAGECAPS_INTERPOL 0x0200; supports color interpolation in hardware
IMAGECAPS_BYLOCSYSMEM 0x0400; able to read/write to system memory
IMIAGECAPS_SEM_BYPASS 0x0800; device serialization not required
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.
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 COLORINFOdata 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.
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 ;
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
IPC_RECTLS 0x0002; visible regions have changed
IPC_SRC_COLOR 0x0004; source color information has changed
IPC_DST_COLOR 0x0008; destination color information has changed
IPC_PALETTE 0x0010; palette color information has changed
IPC_SRC_SIZE 0x0020; source size information has changed
IPC_DST_SIZE 0x0040; destination size information has changed
IPC_DST_POS 0x0080; destination position information has changed
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.
typedef struct _INITVDM {
ULONG ulFlags; /* VDM initialization type. */
} INITVDM;
typedef INITVDM * PINITVDM ;
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.
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 ;
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.
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 ;
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.
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 ;
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.
LINE_INVISIBLE Line is not drawn.
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
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
LINEINFO Field - pDstBmapInfo
pDstBmapInfo(PBMAPINFO) Pointer to destination surface bit map.
LINEINFO Field - alpkLinePack
alpkLinePack(PLINEPACK) Pointer to LINEPACKdata 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_LINEand GHI_CMD_LINEfunctions.
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.
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 ;
LINEINFO2 Field - ulLength
ulLength(ULONG) Length of LINEINFO2 data structure.
LINEINFO2 Field - ulType
ulType(ULONG) Defines line type.
LINE_SOLID Line will be solid in Foreground color.
LINE_INVISIBLE Line is not drawn.
LINE_ALTERNATE Line will be alternating Foreground and Background color; ignores style.
LINEINFO2 Field - ulStyleMask
ulStyleMask(ULONG) A 32-bit style mask.
LINEINFO2 Field - cLines
cLines(ULONG) Count of lines to be drawn.
LINEINFO2 Field - ulFGColor
ulFGColor(ULONG) Line Foreground color.
LINEINFO2 Field - ulBGColor
ulBGColor(ULONG) Line Background color.
LINEINFO2 Field - usForeROP
usForeROP(USHORT) Line Foreground mix.
LINEINFO2 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
LINEINFO2 Field - pDstBmapInfo
pDstBmapInfo(PBMAPINFO) Pointer to destination surface bit map.
LINEINFO2 Field - ulFlags
ulFlags(ULONG) Flags used for the LINEINFO2 data structure.
LINE_DO_FIRST_PEL Draw first pel of first line if not clipped.
LINE_DO_LAST_PEL Draw last pel of last line if not clipped.
LINE_MONO_INVERT Invert bits for mono destination.
LINE_START_CLIP Start of first line is clipped.
LINE_END_CLIP End of last line is clipped.
LINE_Y_FLIP Flip Y for all lines.
LINE_ALL_RADIAL All lines oriented 0, 45, 90, 135, 180, 225, 270, or 315 degrees.
LINE_DISJOINT Successive pairs of points in pptlLines array define disconnected line segments.
LINEINFO2 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.
LINEINFO2 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:
/-----------------------------------------------------------------------------\ |high word (16 bits) |3 bits |5 bits |8 bits | |--------------------+------------------+------------------+------------------| |not used |not used |mask position |error value | \-----------------------------------------------------------------------------/
The style value is updated as lines are drawn.
LINEINFO2 Field - ptlOrigin
ptlOrigin(POINTL) Origin to be added to all coordinates.
LINEINFO2 Field - pptlStart
pptlStart(PPOINTL) Pointer to POINTLdefining start point of first line.
LINEINFO2 Field - pptlLines
pptlLines(PPOINTL) Pointer to POINTLarray defining connected line endpoints.
The number of array entries is defined by cLines.
LINEINFO2 Field - ptlClipStart
ptlClipStart(POINTL) Clipped start point if it is clipped.
LINEINFO2 Field - ptlClipEnd
ptlClipEnd(POINTL) Clipped end point if it is clipped.
LINEINFO2 Field - lClipStartError
lClipStartError(LONG) Bresenham error at the clip start point for first line (not valid if first line is horizontal or vertical).
LINEINFO2 Field - prclBounds
prclBounds(PRECTL) Pointer to bounding rect of a clipped line.
LINEPACK
Line information data structure on a per-line basis.
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 ;
LINEPACK 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.
LINEPACK 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:
/---------------------------------------------------------------\ |high word |3 bits |5 bits |8 bits | |---------------+---------------+---------------+---------------| |not used |not used |mask pos |error value | \---------------------------------------------------------------/
LINEPACK 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.
LINEPACK Field - plpkNext
plpkNext(LINEPACK) Pointer to next LINEPACK data structure.
LINEPACK Field - ulAbsDeltaX
ulAbsDeltaX(ULONG) Clipped Bresenham Delta X, absolute.
LINEPACK Field - ulAbsDeltaY
ulAbsDeltaY(ULONG) Clipped Bresenham Delta Y, absolute.
LINEPACK 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.
LINEPACK Field - ptlClipEnd
ptlClipEnd(POINTL) Ending location for Bresenham algorithm (see ptlClipStart).
LINEPACK Field - ptlStart
ptlStart(POINTL) Pointer to starting location for line.
The device can perform the Bresenham algorithm from ptlStart or ptlClipStart.
LINEPACK Field - ptlEnd
ptlEnd(POINTL) Ending location for line.
LINEPACK 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)
MIN Minimum (ulAbsDeltaX, ulAbsDeltaY)
Major Increment Increment to the error for stepping along the major axis:
2 * MIN.
Diagonal Increment Increment to the error for stepping along the major and minor axes:
2 * MIN - 2 * MAX.
Initial Error Error at the start point:
2 * MIN - MAX, if LINE_DIR_X_POSITIVE is On.
2 * MIN - MAX - 1, if LINE_DIR_X_POSITIVE is Off.
Horizontal and vertical lines The line is drawn from the clipped start to clipped end.
The lClipStartError will not be given.
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.
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.
Styling Lines are styled using the ulStyleMask, ulStyleStep, and ulStyleValue.
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.
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 ;
MEMINFO Field - ulPhysAddr
ulPhysAddr(ULONG)
MEMINFO Field - ulMemLen
ulMemLen(ULONG)
MEMINFO Field - ulVirtAddr
ulVirtAddr(ULONG)
MEMINFO Field - pNextMI
pNextMI(struct_MEMINFO)
MONITORINFO
The MONITORINFO data structure receives information for the current video monitor.
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 ;
MONITORINFO Field - szMonitor[MAX_MONITOR_LEN]
szMonitor[MAX_MONITOR_LEN](CHAR) Contains monitor information.
MONITORINFO 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.
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 ;
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.
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 ;
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).
typedef struct _POINTL {
LONG x; /* X-coordinate. */
LONG y; /* Y-coordinate. */
} POINTL;
typedef POINTL * PPOINTL ;
POINTL Field - x
x(LONG) X-coordinate.
POINTL Field - y
y(LONG) Y-coordinate.
RECTL
Rectangle structure.
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 ;
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.
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 ;
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.
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 ;
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.
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 ;
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_TEXTand VMI_CMD_TEXTfunctions. The TEXTBLTINFO structure includes a pointer to DEVFONTINFO.
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 ;
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 GLYPHINFOfor 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 PDEVFONTINFOfor 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_USERCAPSand VMI_CMD_USERCAPSfunctions.
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 ;
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
#define QUERYCAPS 1L
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 DRIVERCAPSstructures 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
#define QUERYCAPSLIST 2L
QUERYCAPSLIST fills the pValueList, pCurrentValue, and pDefaultValue fields in the DRIVERCAPSstructure pointed to by pOut. The members must be 0 padded up to the length specified by ulValueMemberSize.
SETCAP
#define SETCAP 3L
SETCAP sets a value that the user has selected. The value is specified in the pCurrentValue field of the DRIVERCAPSstructure pointed to by pOut.
USERCAPSIN Field - ulSize
ulSize(ULONG) Length, in bytes, of buffer area.
VCRF
Data structure inside INTCRFcontaining the register values to be passed in the bios call.
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;
VCRF Field - reg_eax
reg_eax(ULONG)
VCRF Field - reg_ebx
reg_ebx(ULONG)
VCRF Field - reg_ecx
reg_ecx(ULONG)
VCRF Field - reg_edx
reg_edx(ULONG)
VCRF Field - reg_ebp
reg_ebp(ULONG)
VCRF Field - reg_esi
reg_esi(ULONG)
VCRF Field - reg_edi
reg_edi(ULONG)
VCRF Field - reg_ds
reg_ds(ULONG)
VCRF Field - reg_es
reg_es(ULONG)
VCRF Field - reg_fs
reg_fs(ULONG)
VCRF Field - reg_gs
reg_gs(ULONG)
VCRF Field - reg_cs
reg_cs(ULONG)
VCRF Field - reg_eip
reg_eip(ULONG)
VCRF Field - reg_eflag
reg_eflag(ULONG)
VCRF Field - reg_ss
reg_ss(ULONG)
VCRF Field - reg_esp
reg_esp(ULONG)
VIDEO_ADAPTER
The VIDEO_ADAPTER data structure receives information for the desktop mode.
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 ;
VIDEO_ADAPTER Field - hvideo
hvideo(HVIDEO) The handle for this adapter.
VIDEO_ADAPTER Field - Adapter
Adapter(ADAPTERINFO) Hardware information for this adapter.
VIDEO_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 cband ulColorsfields are new to VIDEDOMODEINFO. The color depth field (ulColors) was introduced to differentiate between pixel and color depth.
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 ;
VIDEOMODEINFO Field - cb
cb(ULONG) Size of the structure.
VIDEOMODEINFO Field - miModeId
miModeId(MODEID) Used to make a SetMode request.
VIDEOMODEINFO 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
VIDEOMODEINFO Field - usInt10ModeSet
usInt10ModeSet(USHORT) Interrupt 10 mode.
VIDEOMODEINFO Field - usXResolution
usXResolution(USHORT) Horizontal pixels.
VIDEOMODEINFO Field - usYResolution
usYResolution(USHORT) Vertical scanlines.
VIDEOMODEINFO Field - ulBufferAddress
ulBufferAddress(ULONG) Physical address of VRAM.
VIDEOMODEINFO Field - ulApertureSize
ulApertureSize(ULONG) VRAM aperture.
VIDEOMODEINFO Field - ulColors
ulColors(ULONG) Color depth.
VIDEOMODEINFO Field - bBitsPerPixel
bBitsPerPixel(BYTE) Pixel depth.
VIDEOMODEINFO Field - bBitPlanes
bBitPlanes(BYTE) Number of planes.
VIDEOMODEINFO Field - bXCharSize
bXCharSize(BYTE) Font width.
VIDEOMODEINFO Field - bYCharSize
bYCharSize(BYTE) Font height.
VIDEOMODEINFO Field - usBytesPerScanLine
usBytesPerScanLine(USHORT) Number of bytes per scan line.
VIDEOMODEINFO Field - usTextRows
usTextRows(USHORT) Number of text rows.
VIDEOMODEINFO Field - ulPageLength
ulPageLength(ULONG) Number of bytes to save a plane.
VIDEOMODEINFO Field - ulSavesize
ulSavesize(ULONG) Total bytes of VRAM to save.
VIDEOMODEINFO Field - bVrtRefresh
bVrtRefresh(BYTE) Vertical refresh rate.
VIDEOMODEINFO Field - bHrtRefresh
bHrtRefresh(BYTE) Horizontal refresh rate.
VIDEOMODEINFO Field - bVrtPolPos
bVrtPolPos(BYTE) Vertical polarity.
VIDEOMODEINFO Field - bHrtPolPos
bHrtPolPos(BYTE) Horizontal polarity.
VIDEOMODEINFO Field - usScrnTop
usScrnTop(USHORT) Vertical blanking away from the top, in line counts.
VIDEOMODEINFO Field - usScrnBottom
usScrnBottom(USHORT) Vertical blanking away from the bottom, in line counts.
VIDEOMODEINFO Field - usScrnLeft
usScrnLeft(USHORT) Horizontal blanking away from the left, in pixel counts .
VIDEOMODEINFO Field - usScrnRight
usScrnRight(USHORT) Horizontal blanking away from the right, in pixel counts.
VIDEOMODEINFO Field - szColorFormat[8]
szColorFormat[8](CHAR) Color format string for true color or high-color modes.
VIDEOMODEINFO 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.
typedef struct _VIDEORESOURCEPACK {
ULONG ConsRes; /* An array of resource definitions. */
ULONG ulNumCons; /* Number of resources. */
} VIDEORESOURCEPACK;
typedef VIDEORESOURCEPACK * FAR * PVIDEORESOURCEPACK ;
VIDEORESOURCEPACK Field - ConsRes
ConsRes(ULONG) An array of resource definitions.
VIDEORESOURCEPACK Field - ulNumCons
ulNumCons(ULONG) Number of resources.
VIDEOSTATE
The VIDEOSTATE data structure receives information for the mode to be saved .
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 ;
VIDEOSTATE Field - fStateFlags
fStateFlags(ULONG) Flag indicating what to save.
STATEFLAG_REGISTERS 0x0001
STATEFLAG_CLUT 0x0002
STATEFLAG_VRAM 0x0004
STATEFLAG_FONT 0x0008
VIDEOSTATE Field - miState
miState(MODEID) Contains the mode ID for the mode to be saved.
VIDEOSTATE Field - pModeData
pModeData(PVOID) Pointer to set mode command sequence.
VIDEOSTATE Field - ulVRAMSaveSize
ulVRAMSaveSize(ULONG) Number of bytes per page to save.
VIDEOSTATE Field - pVRAM
pVRAM(PVRAMDATA) Pointer to video memory.
VIDEOSTATE Field - pCLUT
pCLUT(PCLUTDATA) Pointer to palette data.
VIDEOSTATE Field - pFONT
pFONT(PFONTDATA) Pointer to font data.
VMIQCI
Output packet returned by the GRADD to the caller of the VMI_CMD_ QUERYCHAININFO function.
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 ;
VMIQCI Field - ulLength
ulLength(ULONG) Size of the VMIQCI data structure, in bytes.
VMIQCI Field - pciHead
pciHead(PCHAININFO) Pointer to the head of the GRADD chain.
VRAMALLOCIN
Input packet to the GHI_CMD_VRAM function.
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 ;
VRAMALLOCIN Field - ulLength
ulLength(ULONG) Size of the VRAMALLOCIN data structure, in bytes.
VRAMALLOCIN Field - ulFlags
ulFlags(ULONG) Flag indicating type of VRAM allocation.
Values are as follows:
VRAM_ALLOC_SHARED 0x0001
VRAM_ALLOC_RECTANGLE 0x0002
VRAM_ALLOC_STATIC 0x1000
VRAMALLOCIN Field - ulID
ulID(ULONG) ID required as input only on deallocation.
VRAMALLOCIN Field - ulFunction
ulFunction(ULONG) Requested function: allocate, deallocate, or query.
Values are as follows:
VRAM_ALLOCATE 1
VRAM_DEALLOCATE 2
VRAM_QUERY 3
VRAMALLOCIN Field - ulHandle
ulHandle(ULONG) Handle returned from registering.
VRAMALLOCIN Field - ulSize
ulSize(ULONG) Requested allocation size in bytes.
VRAMALLOCIN Field - ulWidth
ulWidth(ULONG) Requested allocation width in pixels.
VRAMALLOCIN 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.
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 ;
VRAMALLOCOUT Field - ulLength
ulLength(ULONG) Size of the VRAMALLOCOUT data structure, in bytes.
VRAMALLOCOUT Field - ulFlags
ulFlags(ULONG) Flag indicating type of VRAM allocation.
Value is as follows:
VRAM_ALLOC_WORKBUFFER 0x0004
VRAMALLOCOUT Field - ulID
ulID(ULONG) ID returned on allocation.
VRAMALLOCOUT Field - ptlStart
ptlStart(POINTL) X and Y location of VRAM.
VRAMALLOCOUT Field - ulSize
ulSize(ULONG) Requested size of VRAM, in bytes.
VRAMALLOCOUT 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_VRAMfunction.
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 ;
VRAMIN 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
VRAM_DEALLOCATE 2
VRAM_QUERY 3
VRAM_REGISTER 4
VRAM_DEREGISTER 5
VRAMIN 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 VRAMALLOCINdata structure.
If the ulFunction field of the VRAMIN structure is set to VRAM_REGISTER or VRAM_DEGISTER, then pIn points to a VRAMREGISTERINdata structure.
VRAMREGISTERIN
Input packet to the GHI_CMD_VRAM function via the VRAMIN data structure.
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 ;
VRAMREGISTERIN Field - ulLength
ulLength(ULONG) Size of the VRAMREGISTERIN data structure, in bytes.
VRAMREGISTERIN Field - ulHandle
ulHandle(ULONG) Handle required as input on deregister.
VRAMREGISTERIN 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.
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 ;
VRAMREGISTEROUT Field - ulLength
ulLength(ULONG) Size of the VRAMREGISTEROUT data structure, in bytes.
VRAMREGISTEROUT Field - ulFlags
ulFlags(ULONG) Not used at this time.
VRAMREGISTEROUT Field - ulHandle
ulHandle(ULONG) Handle returned on register.
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.
Glossary
This glossary contains terms and definitions that are, for the most part, used for OS/2 products. This is not a complete dictionary of computer terms .
Introduction
This glossary defines many of the terms used in this book. It includes terms and definitions from the IBM Dictionary of Computing, as well as terms specific to the Presentation Manager, but it is not a complete glossary for OS/2.
Other primary sources for these definitions are:
�The American National Standard Dictionary for Information Systems, ANSI X3 .172-1990, copyrighted 1990 by the American National Standards Institute, 11 West 42nd Street, New York, New York 10036. These definitions are identified by the symbol (A) after the definition.
�The Information Technology Vocabulary, developed by Subcommittee 1, Joint Technical Committee 1, of the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are identified by the symbol (I) after the definition; definitions taken from draft international standards, committee drafts, and working papers being developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that final agreement has not yet been reached among the participating National Bodies of SC1.
Glossary Listing
Glossary - A
A
ABIOS -Advanced BIOS. See BIOS.
accumulator -(1) A register in which one operand of an operation can be stored and subsequently replaced by the result of that operation. (T) (2) In the IBM 3800 Printing Subsystem Models 3 and 8, a feature that supplies a separate storage that can hold data in raster form. It can be used either for composing a sheet of data that combines a large amount of variable and constant data, or for storing an electronic overlay in raster form that will be merged with variable data as the sheet is printed.
access permission -All access rights a user has regarding an object. (I)
adapter -A piece of hardware that modifies the system unit to allow it to operate in a particular way, often by connecting the system unit to an external device such as a video monitor.
adapter device driver -A device driver that provides hardware-dependent services for an OEMadapter.
address space -(1) The range of addresses available to a program. (A) ( 2) The area of virtual storage available for a particular job.
all points addressable (APA) -In computer graphics, pertaining to the ability to address and display or not display each picture element (pel) on a display surface.
anchor block -An area of the internal resources of OS/2 Presentation Manager which is allocated to a process or thread that calls WinInitialize.
anchor point -The position or choice from which selection or deselection is extended.
APA -All points addressable.
API -Application programming interface.
application programming interface (API) -A functional interface supplied by the operating system, or by a separately-orderable licensed program, that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program.
archive flag -In the OS/2 operating system, a flag of files and directories that the operating system uses to determine which files are new or modified. Files with this flag are included when a backup copy is made or when all the files are restored on a hard disk. See flag.
area -In computer graphics, a filled shape such as a solid rectangle.
ASCIIZ -A string of ASCII characters that is terminated with a byte containing the value 0.
aspect ratio -(1) The ratio of the height of a rectangle to its width. A rectangle of width 10 inches and height 5 inches has an aspect ratio of 10/ 5 or 2. (2) On a display screen, the ratio of the maximum length of a display line to the maximum length of a display column.
asynchronous (ASYNC) -(1) Pertaining to two or more processes that do not depend upon the occurrence of specific events such as common timing signals . (T) (2) Without regular time relationship; unexpected or unpredictable with respect to the execution of program instructions.
atom -A constant that represents a string. Once a string has been defined as an atom, the atom can be used in place of the string to save space. Strings are associated with their respective atoms in an atom table. See integer atom.
atom table -A table used to associate atoms with the strings that they represent. This table contains the mechanism by which the presence of a string can be verified.
AVIO -Advanced Video Input/Output
Glossary - B
B
background color -The color assigned to a background image.
background mix -An attribute that determines how the background of a graphic primitive is combined with the existing color of the graphics presentation space.
base device driver -An OS/2 device driver that performs I/O during the OS/ 2 kernel boot sequence to provide IPL support. Base device drivers are loaded by way of the CONFIG.SYS BASEDEV keyword, rather than the DEVICE keyword. See BASEDEV keyword, adapter device driver, and device manager.
BASEDEV keyword -New CONFIG.SYS keyword; loads a base device driver into the operating system.
Basic Input/Output System (BIOS) -Code that controls basic hardware operations, such as interactions with diskette drives, hard disk drives, and the keyboard.
Bezier curve -A mathematical technique of specifying a smooth, continuous line or surface, requiring a starting point and an ending point, with several intermediate points that influence or control the path of the linking curve.
BIOS -Basic Input/Output System.
bit-block transfer (bitblt) -Transfer of a rectangular array of bit-map data.
bitblt -Bit-block transfer.
bit map -A representation of an image by an array of bits.
block -(1) In programming languages, a compound statement that coincides with the scope of at least one of the declarations contained within it. A block may also specify storage allocation or segment programs for other purposes. (I) (2) A string of data elements recorded or transmitted as a unit. The elements may be characters, words or physical records. (T) (3) A collection of contiguous records recorded as a unit. Blocks are separated by interblock gaps and each block may contain one or more records. (A)
Bit block transfer (bitblt) -The process of transferring one or more blocks of data.
border -A visual indicator of a window's boundaries.
BPB -BIOS Parameter Block.
breakpoint -(1) A point in a computer program where execution may be halted. A breakpoint is usually at the beginning of an instruction where halts, caused by external intervention, are convenient for resuming execution. (T) (2) An instruction in a program for halting execution. Breakpoints are usually established at positions in a program where halts, caused by external intervention, are convenient for restarting. (T) (3) A place in a program, specified by a command or a condition, where the system halts execution and gives control to the workstation user or to a specified program.
Bus Master adapter -An adapter capable of performing Reads and Writes to physical storage by communicating directly with the storage subsystem ( memory) rather than depending on a host DMA channel or host CPU. Synonymous with first-party DMA adapter.
Glossary - C
C
cached micro presentation space -A presentation space from a Presentation Manager owned store of micro presentation spaces. It can be used for drawing to a window only, and must be returned to the store when the task is complete.
CDB -Command Descriptor Block.
cell -See character cell.
character box -(1) An imaginary parallelogram on a display surface that contains all parts of one graphic character. Synonymous with bounding box. (T) (2) The maximum area in which a symbol and all associated elements, such as a cursor, an underline, or space surrounding the symbol to separate it from other symbols, can be printed or displayed. Synonymous with character cell. (3) The imaginary parallelogram whose boundaries govern the size, orientation, and spacing of individual characters to be displayed on a graphics display device.
character cell -(1) An addressable location on a display surface or printing medium. (2) The physical width and height in pels of a font. See also bounding box. (3) The imaginary box whose boundaries govern the size , orientation, and spacing of individual characters to be displayed on a workstation.
character mode -A mode that, in conjunction with the font type, determines the extent to which graphics characters are affected by the character box, shear, and angle attributes.
clipping -In computer graphics, removing those parts of display elements that lie outside of given boundary.
clip limits -The area of the paper that can be reached by a printer or plotter.
clipping path -A clipping boundary in world-coordinate space.
code page -An assignment of graphic characters and control function meanings to all code points; for example, assignment of characters and meanings to 256 code points for an 8-bit code, assignment of characters and meanings to 128 code points for a 7-bit code.
code point -A 1-byte code representing one of 256 potential characters.
code segment -An executable section of programming code within a load module.
color conversion -Changing one color format to another. Required, for example, when the source color format is different from the destination color format. When going from the monochrome color format to the color format, 1 (one) bits are converted to the image foreground color, and 0 ( zero) bits are converted to the image background color.
When going from color to monochrome, all pels that match the passed background color are converted to the image background color of the destination.
All other pels are converted to the image foreground color of the destination. The color conversion takes place prior to any mix mode.
color dithering -See dithering.
command code -In this specification, refers to a group of related commands that an adapter device driver can receive.
All command codes have a prefix of "IOCC_". For example, common I/O requests (such as Read, Write, etc.) are grouped under the command code IOCC_EXECUTE_IO.
command data block -A data structure defined by the Small Computer System Interface standard to send commands to devices that conform to SCSI standards.
command descriptor block (CDB) -The structure used to communicate commands from a source to a destination.
command modifier -In this specification, a specific operation that an adapter device driver is to perform.
All command modifiers have a prefix of "IOCM_". For example, an adapter device driver might receive an IOCC_EXECUTE_IO command with a command modifier of IOCM_READ.
compatibility kernel -The portion of the OS/2 kernel that exists to support DOS INT 20, 21, 25, 26, and 27 functions. It acts as an interface to common kernel functionality such as the file system.
CON -Character-device name reserved for the console keyboard and screen.
conditional compilation -Processing by the preprocessor of certain specified code in the file, depending on the evaluation of a specified condition.
context hook -Similar to a "force flag" in earlier versions of OS/2. These are events, signaled by a virtual device driver, that are processed at task time. Forcing an IRET, and simulating an NMI, can fall into this category.
control program -A computer program designed to schedule and to supervise the execution of programs of a computer system.
controller sector buffer -One or more buffers, managed by a hardware adapter, to improve I/O transfer rates by helping to match a device and software timing requirements.
Glossary - D
D
DASD -Direct-access storage device.
data bus -A bus used to communicate data internally and externally to and from a processing unit, storage, and peripheral devices. (A) See bus.
data structure -The syntactic structure of symbolic expressions and their storage allocation characteristics. (T)
DBCS -Double-byte character set.
DC -Device context.
DDB -Device-dependent bit map.
deinstantiation -See instantiation.
DevHlp -Device helper.
device context (DC) -A logical description of a data destination such as memory, metafile, display, printer, or plotter. See also direct device context, information device context, memory device context, metafile device context, and screen device context.
device driver -A file that contains the code needed to attach and use a device such as a display, printer, or plotter.
device driver initialization (init) time -See initialization (init) time, device driver.
device driver profile -A file with a "DDP" extension, containing a script that is interpreted by the OS/2 DDINSTAL utility. Among other things, it defines which files to copy from installation diskettes to target directories and specifies how the CONFIG.SYS file will be updated.
device helper (DevHlp) -(1) A kernel service (memory, hardware interrupt, software interrupt, queuing, semaphore, and so forth) provided to physical device drivers. (2) A callable C-language or assembler-language routine that provides an operating system service for an OS/2 device driver.
device object -A device that provides a means of communication between a computer and the outside world. A printer is an example of a device object.
device table -A data structure containing a summary of the adapters an adapter device driver supports and a list of the I/O devices attached to each adapter. This data structure is built by the adapter device driver in response to an IOCC_CONFIGURATION IOCM_GET_DEVICE_TABLE request.
direct access storage device (DASD) -A device in which access time is effectively independent of the location of the data.
direct memory access (DMA) -(1) A technique for moving data directly between main storage and peripheral equipment without requiring processing of the data by the processing unit. (2) The transfer of data between memory and input/output units without processor intervention.
display frame -(1) In computer graphics, an area in storage in which a display image can be recorded. (2) In computer micrographics, an area on a microform in which a display image can be recorded.
dispatch table -(1) A block of memory, allocated by the graphics engine, for the containment of entry points for use by a display driver. (2) An array of pointers to function-handling routines.
dithering -A technique for interleaving dark and light pels so that the resulting image looks smoothly shaded from a distance.
DLL -Dynamic link library.
DMA -Direct memory access.
double-byte character set (DBCS) -A set of characters in which each character is represented by two bytes. Languages such as Japanese, Chinese, and Korean, which contain more characters than can be represented by 256 code points, require double-byte character sets. Because each character requires 2 bytes, the typing, display, and printing of DBCS characters requires hardware and programs that support DBCS. Contrast with single-byte character set.
driver -(1) A program (and possibly data files) that contain information needed to run a particular unit, such as a plotter, printer, port, or mouse. See also device driver and printer driver. (2) A system or device that enables a functional unit to operate.
dynamic link library (DLL) -A file containing executable code and data bound to a program at load time or run time, rather than during linking. The code and data in a dynamic link library can be shared by several applications simultaneously.
Glossary - E
E
entry point -(1) In a database, the record that is first accessed upon entry into a database, caused by a user's command. (T) (2) The address or label of the first instruction executed on entering a computer program, routine, or subroutine. A computer program, routine, or subroutine may have a number of different entry points, each perhaps corresponding to a different function or purpose. (I) (A) Synonymous with entrance, entry. (3) In a routine, any place to which control can be passed. (A) (4) In the C, FORTRAN, and Pascal languages, the address or label of the first instruction processed or entered in a program, routine, or subroutine. A program, routine, or subroutine can have a number of different entry points , each corresponding to a different function or purpose.
EOI -End Of Interrupt
Glossary - F
F
Far call -Code that calls from one segment into another segment.
fillet -An arc that is tangential to the end points of two adjacent lines. See also polyfillet.
filter adapter device driver -A special class of adapter device drivers that do not manage the hardware directly, but monitor the stream of commands between a device manager and an adapter device driver. See Device Managerand adapter device driver.
first-party DMA adapter -See bus master adapter.
flag -A characteristic of a file or directory that enables it to be used in certain ways. See also archive flag, hidden flag, and read-only flag.
flat address -See linear address.
frame styles -Standard window layouts provided by the Presentation Manager .
freeze and thaw services -Functions that prevent a DOS session from executing (VDHFreezeVDM) until the matching thaw function (VDHThawVDM) is called. The freeze occurs when the specified DOS session leaves kernel mode .
Glossary - G
G
GDT -Global descriptor table.
Global Descriptor Table (GDT) -A table that defines code and data segments available to all tasks in an application.
glyph -A graphic symbol whose appearance conveys information; for example, the vertical and horizontal arrows on cursor keys that indicate the directions in which they control cursor movement, the sunburst symbol on the screen illumination control of a display device.
GPI -Graphics programming interface
graphic primitive -In computer graphics, a basic element, such as an arc or a line, that is not made up of smaller parts and that is used to create diagrams and pictures.
graphics attributes -The attributes that apply to graphics primitives. Examples are color selection, line type, and shading pattern definition. Contrast with segment attributes.
Graphics programming interface (GPI) -The formally-defined programming language that lies between an IBM graphics program and the user of the program.
graphics segment -A sequence of related graphic primitives and graphics attributes. See also graphic primitive.
GRE -Graphics engine.
Glossary - H
H
handle -(1) An identifier that represents an object, such as a device or a window, to the Presentation Interface. (2) In the Advanced DOS and OS/2 operating systems, a binary value created by the system that identifies a drive, directory, and file so that the file can be found and opened.
handshaking -A method by which two pieces of hardware, such as a personal computer and a plotter, can communicate. Depending upon the devices communicating, handshaking occurs either as a hardware function or through software, such as a device driver.
hard error -An error condition on a network that requires that the network be reconfigured or that the source of the error be removed before the network can resume reliable operation.
hardware palette -The array of RGBs that the physical device is displaying .
heap -An area of free storage available for dynamic allocation by an application. Its size varies depending on the storage requirements of the application.
hex -See hexadecimal
hexadecimal -Pertaining to a system of numbers to the base 16; hexadecimal digits range from 0 through 9 and A through F, where A represents 10 and F represents 15.
hook -A point in a system-defined function where an application can supply additional code that the system processes as though it were part of the function.
hook chain -A sequence of hook procedures that are "chained" together so that each event is passed in turn to each procedure in the chain.
Glossary - I
I
IDC -Inter-device-driver communication.
in-memory buffer -A block of memory in the address space of the host machine, used for data transfer.
init time -See initialization time, device driver.
initialization time, device driver -After the OS/2 loads a device driver, it sends it an OS/2 request packet to initialize. During this initialization, certain DevHlp functions are not permitted. Also called init time.
Input/Output Control (IOCtl) -A system service that provides a way for an application to send device-specific control commands to a device driver.
Input/Output Privilege Level (IOPL) -Allows part of a Ring 3 application or device driver to execute at Ring 0.
input router -OS/2 internal process that removes messages from the system queue.
inter-device-driver communication (IDC) -A mechanism that enables a physical device driver to communicate with another physical device driver.
interprocess communication -In the OS/2 operating system, the exchange of information between processes or threads through semaphores, queues, and shared memory.
interrupt -An instruction that directs the microprocessor to suspend what it is doing and run a specified routine. When the routine is complete, the microprocessor resumes its original work. See also routine.
interrupt request (IR) -Broadly, an "interrupt request level", referring to pending or in-service interrupt requests, or to a specific level (for example, IR 4).
interrupt request flag -A bit in the 8259 PIC controller that indicates an interrupt is pending on particular level. The VPIC also maintains a virtual interrupt request flag for each interrupt level for each DOS session.
interrupt service flag -A bit in the 8259 PIC controller that indicates an interrupt request is being serviced. It is cleared when the PIC is sent EOI . The VPIC maintains a virtual interrupt service flag indicating that a simulated interrupt is in-progress in a DOS session.
interrupt time -When a device driver is run because of an interrupt rather than because of an application request. OS/2 device drivers receive interrupts either from the hardware they manage or from the system real- time clock.
During interrupt time, certain DevHlp functions are not permitted. Also, addresses received directly from OS/2 applications might not be valid unless they are converted system addresses.
IOCtl -Input/Output Control.
IOPL -Input/Output Privilege Level.
IORB -Input/Output Request Block.
Input/Output Request Block (IORB) -A data structure defined by this specification that is passed as a parameter on all calls to an adapter device driver. It contains a fixed section, followed by a command-dependent section.
IORBH -Input/Output Request Block Header
IRET -Interrupt return.
IRQ -Interrupt Request.
Glossary - J
J
journal -A special-purpose file or data set that can be used to provide an audit trail of operator and system actions, or as a means of recovering superseded data.
Glossary - K
K
kanji -A graphic character set consisting of symbols used in Japanese ideographic alphabets. Each character is represented by 2 bytes.
kernel -(1) The part of an operating system that performs basic functions such as allocating hardware resources. (2) A program that can run under different operating system environments.
kerning -The design of graphic characters so that their character boxes overlap. The toned picture elements (pels) of the character appear outside the character cell.
Note:Kerning allows character boxes to overlap and characters to run together, so that characters can be designed for cursive languages, ligatures, or any other kind of character that requires more than one character box. It also allows for design of proportional-spaced fonts. By overlapping character boxes, characters can be placed closer together, or they can be placed farther apart by using overlapped blank character boxes.
Glossary - L
L
LCT -logical color table.
LDT -Local descriptor table.
LIFO stack -A data structure from which data is retrieved in "Last-In, First-Out" order.
linked list -A list in which the data elements may be dispersed, but in which each data element contains information for locating the next. Synonym for chained list.
linear address -A unique value that identifies the memory object.
Local Descriptor Table (LDT) -A table that defines code and data segments specific to a single task.
logical palette -An array of RGB and mapping index pairs, created by the device driver when defining a palette (as a result of a GpqCreatePalette call).
LVB -Logical Video Buffer.
Glossary - M
M
memory device context -A logical description of a data destination that is a memory bit map. See also device context.
metafile -A file containing a series of attributes that set color, shape, and size, usually of a picture or a drawing. Using a program that can interpret these attributes, a user can view the assembled image.
metafile device context -A logical description of a data destination that is a metafile which is used for graphics interchange. See also device context.
mickey -A unit of measurement for physical mouse motion whose value depends on the mouse device driver that is currently loaded.
mixed character string -A string containing a mixture of one-byte and kanji or Hangeul (two-byte) characters.
mutex semaphore -(Mutual exclusion semaphore). A semaphore that enables threads to serialize their access to resources. Only the thread that currently owns the mutex semaphore can gain access to the resource, thus preventing one thread from interrupting operations being performed by another.
Glossary - N
N
named pipe -A named buffer that provides client-to-server, server-to- client or duplex communication between unrelated processes. Contrast with unnamed pipe.
notification callout -The feature that provides for a routine to be called on completion of an input/output request. See also notification routine.
notification routine -The routine indicated in an input/output request block to be called on completion of that request. See also notification callout.
null-terminated string -A string of (n+1) characters where the (n+1)th character is the "null" character (X'00') and is used to represent an n- character string with implicit length. Also called a "zero-terminated" string or an "ASCIIZ". string.
Glossary - O
O
Glossary - P
P
palette -A list of colors assigned to various areas on a panel. A user can change the color of these areas.
PDD -Physical Device Driver.
PDE -PageDirectoryEntry.
pel -Picture element.
permissible action -In a conceptual schema language, an action conforming to specified rules or constraints that changes a presumably consistent collection of sentences into a consistent one or makes known a consistent one present in the information base or conceptual schema.
phase alignment -Aligning source bits with destination bits. Often required in a Bitblt function move operation where byte blocks are moved on bit boundaries.
physical address -A 32-bit byte address giving the actual address in physical storage for a data item.
physical device driver (PDD) -A system interface that handles hardware interrupts and supports a set of input and output functions.
pipe -See named pipe, unnamed pipe.
picture element (pel, pixel) -(1) In computer graphics, the smallest element of a display surface that can be independently assigned color and intensity. (T) . (2) The area of the finest detail that can be reproduced effectively on the recording medium. (3) An element of a raster pattern about which a toned area on a photoconductor can appear.
PIO -Programmed I/O.
pixel -Picture element.
polyfillet -A curve based on a sequence of lines. The curve is tangential to the end points of the first and last lines, and tangential also to the midpoints of all other lines.
polyline -In computer graphics, a sequence of adjoining lines.
pop -To remove an item from the top of a pushdown list. Contrast with push .
prefetch -To locate and load a quantity of data in anticipation of a request.
presence-check function -A Ring 3 (non-privileged) .EXE program that determines whether a given hardware interface is present on a workstation.
PRESENCECHECK -A keyword, interpreted by the DDINSTAL utility, to determine whether to process the device driver profile file, based on the return code from PRESENCECHECK.
printer driver -A file that describes the physical characteristics of a printer, plotter, or other peripheral device, and is used to convert graphics and text into device-specific data at the time of printing or plotting.
Print Manager -In the Presentation Manager, the part of the spooler that manages the spooling process. It also allows the user to view print queues and to manipulate print jobs.
privilege level -A method of protection that allows only certain program instructions to be used by certain programs.
program group -Several programs that can be acted upon as a single entity.
protect mode -A method of program operation that limits or prevents access to certain instructions or areas of storage. Contrast with real mode.
push -To add an item to the top of a pushdown list. Contrast with pop.
Glossary - Q
Q
queued device context -A logical description of a data destination (for example, a printer or plotter) where the output is to go through the spooler. See also device context.
Glossary - R
R
read-only memory basic input/output system (ROM-BIOS) -Microcode in read- only memory that controls basic input/output operations such as interactions with cassettes, diskette drives, hard disk drives, and the keyboard. See also BIOS, NetBIOS.
Note:ROM BIOS allows the user to write programs and add or remove devices without concern for characteristics such as device addresses.
real mode -In the OS/2 operating system, a method of program operation that does not limit or prevent access to any instructions or areas of storage. The operating system loads the entire program into storage and gives the program access to all system resources.
reentrant -The attribute of a program or routine that allows the same copy of the program or routine to be used concurrently by two or more tasks.
removable-media indicator -A flag (bit) indicating that a device permits media removal.
resource -The means of providing extra information used in the definition of a window. A resource can contain definitions of fonts, templates, accelerators and mnemonics; the definitions are held in a resource file.
resurrection -The Presentation Manager event that occurs when switched back from a full-screen DOS or WIN-OS/2 session.
RETF -Return far.
reverse video -A form of highlighting a character, field, or cursor by reversing the color of the character, field, or cursor with its background; for example, changing a red character on a black background to a black character on a red background.
ROM BIOS -Read-Only Memory Basic Input/Output System.
ROP -Raster operation.
RTC -Real-Time Clock.
Glossary - S
S
SBCS -Single-byte character set
SCB -See subsystem control block architecture.
screen device context -A logical description of a data destination that is a particular window on the screen. See also device context.
SCSI -Small Computer System Interface.
seamless windows -An architecture contained within OS/2 which permits one or more applications to share windowed desktop graphical space and other resources, while executing concurrently. Application session windows managed by seamless windows can share border information, and pointing device transitions from session to session are handled smoothly and transparently.
second-party DMA adapter -See DMA slave.
semaphore -(1) A variable that is used to enforce mutual exclusion. (T) (2) An indicator used to control access to a file; for example, in a multiuser application, a flag that prevents simultaneous access to a file. (3) An entity used to control access to system resources. Processes can be locked to a resource with semaphores if the processes follow certain programming conventions.
sense data -Data which describes an I/O error as defined by the ANSI SCSI specifications.
single-byte character set (SBCS) -A character set in which each character is represented by a one-byte code. Contrast with double-byte character set.
Small Computer System Interface (SCSI) -An input and output bus that provides a standard interface between the OS/2 multimedia system and peripheral devices.
spline curve -In computer graphics, a shape created when a user specifies a series of points and the computer software draws a curve that smoothly approaches those points.
spooler -A program that intercepts data going to a device driver and writes it to a disk. The data is later printed or plotted when the required device is available. A spooler prevents output from different sources from being intermixed.
synchronous -Pertaining to two or more processes that depend upon the occurrence of specific events such as common timing signals.
Glossary - T
T
text window -See VIO window.
thread -The smallest unit of operation to be performed within a process.
thunk -term used to describe the process of address conversion, stack, and structure realignment that is necessary when passing control between 16-bit and 32-bit modules.
thunk layer -An interface that converts 32-bit parameters to 16-bit parameters, and maps linear addresses to segmented addresses.
time slice -(1) The period of processing time allocated for running a program. (2) An interval of time on the processing unit allocated for use in performing a task. After the interval has expired, processing unit time is allocated to another task, so a task cannot monopolize processing unit time beyond a fixed limit.
tuple -In a relational database, a part of a relation that uniquely describes an entity and its attribute.
Glossary - U
U
unnamed pipe -A circular buffer created in memory; used by related processes to communicate with one another. Contrast with named pipe.
Glossary - V
V
VBIOS -Virtual BIOS device driver
VCMOS -Virtual CMOS device driver
VDD -Virtual device driver
VDH -Virtual video Device Handler
VDM -Virtual DOS Machine; use DOS session.
VDMA -Virtual Direct Memory Access device driver
VDSK -Virtual hard DiSK device driver
video graphics adapter (VGA) -A computer adapter that provides high- resolution graphics and a total of 256 colors.
VIO -Virtual Input/Output
VIRR -Virtual Interrupt Request Register
Virtual Device Driver (VDD) -In the OS/2 operating system, a type of device driver used by DOS programs running in a DOS session to access devices, such as the screen or mouse, which must be shared with other processes in the system. The virtual device driver maps DOS device commands to the normal (physical) device driver under OS/2 2.0 and later versions of the operating system.
virtual DevHlp (VDH) -Kernel (linear memory, paging, hardware interrupt, event control, port control) services provided to virtual device drivers.
virtual I/O (VIO) -A facility that pages data into and out of external page storage.
virtual memory -Synonym for virtual storage.
Virtual Programmable Interrupt Controller -Virtualizes the 8259 Programmable Interrupt Controller (PIC). A special virtual device driver, in that it provides services to other virtual device drivers.
virtual storage -Addressable space that is apparent to the user as the processor storage space, from which the instructions and the data are mapped into the processor storage locations. Synonymous with virtual memory .
visible region -A window's presentation space clipped to the boundary of the window and the boundaries of any overlying window.
VPIC -Virtual Programmable Interrupt Controller device driver.
VRAM -Video Random-Access Memory.
VTIMER -Virtual TIMER device driver.
V86 mode -Virtual 8086 mode of the 80386 CPU.
Glossary - W
W
window coordinates -A set of coordinates by which a window position or size is defined; measured in device units, or pels.
Glossary - X
X
Glossary - Y
Y
There are no glossary terms for this initial letter.
Glossary - Z
Z
This chapter is based in part on the VESA SVPMI (Video Electronics Standards Association Super VGA Protect Mode Interface) proposal.