Graphics Adapter Device Driver Reference

From EDM2
Jump to: navigation, search

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

Contents

About This Book

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

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

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

How This Book is Organized

This book includes the following chapters and supporting appendixes:

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

Appendixes

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

Assistance

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

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

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

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

Ordering Information

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

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

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

VIDEOPMI.DLL Exported Functions

VIDEOPMI is a 32-bit dynamic link library (DLL) that represents the main Video Protect-Mode Interface handler on OS/2 Warp.

VIDEOPMI exports a single 32-bit or a 16-bit entry point (VIDEOPMI32Request or VIDEOPMI16Request), depending on which one of its numerous base video functions can be invoked - SetMode, SetPalette, SetFont, and so on. All of the exported entry points are prototyped, together with the PMI-related structures, in the common header file SVGADEFS.H. See #VIDEOPMI32Request for details about this single entry point.

VIDEOPMI imports device-specific functions from the underlying PMI subsystem, as provided by the video chip vendor. The PMI subsystem can be a flat .PMI file, a .DLL shared library, or a combination of the two. See #VIDEO Protect-Mode Interface for more information on the PMI subsystem.

All VIDEOPMI functions, except #PMIREQUEST_SOFTWAREINT, require that the PMI subsystem be loaded by issuing #PMIREQUEST_LOADPMIFILE and that the #VIDEO_ADAPTER "hvideo" handle and "adapter instance" be passed into the new request.

The #ADAPTERINFO and #VIDEOMODEINFO data structures, within VIDEO_ADAPTER, are sizable. The AdapterInfo_cb and VideoModeInfo_cb fields should be set by the caller of VIDEOPMI. The adapter handle and instance allow VIDEOPMI and the underlying PMI subsystem to differentiate target adapters in the case of multiple devices. VIDEOPMI is also allowed to target a preferred PMI subsystem for a single video device when running multiple PMI subsystems that provide complimentary but distinct functions.

VIDEOPMI's most important function is video mode set. VIDEOPMI exports an API to query how many mode sets are supported, as well as a mode query API that will copy the mode table into a client-allocated memory block. VIDEOMODEINFO is a sizable data structure. The VideoModeInfo_cb field should be checked before assuming VIDEOMODEINFO format. Each mode in the table contains a mode ID that should be returned when issuing the mode. However, mode setting is parametric. The underlying PMI subsystem allows (if implemented correctly by the vendor) for individual mode parameters to be set to the desired value, rather than to the value in the VIDEOMODEINFO structure for that mode ID in the mode table.

Note:Clients issuing a [SetMode] are obligated to set #VIDEO_ADAPTER and #VIDEOMODEINFO structures to desired values, even if they are the same as the mode ID values; otherwise, some mode parameters may not be set correctly.

There is only one exported entry point for VIDEOPMI. The various PMI services are accessed through different function numbers passed in the parameters. The exported entry point is prototyped, together with the PMI-related structures, in the common header file SVGADEFS.H.

Supported Functions

Function Name Purpose
VIDEOPMI32Request Entry point for all PMIREQUEST_ APIs
PMIREQUEST_CLEANUP Clean up extended registers
PMIREQUEST_GETBANK Get currently addressed bank
PMIREQUEST_GETCLUT Get copy of Color Lookup Table
PMIREQUEST_GETFONT Get current loaded font
PMIREQUEST_GETPALETTE Get copy of palette registers
PMIREQUEST_IDENTIFYADAPTER Identify the installed adapter
PMIREQUEST_LOADPMIFILE Load the specified PMI file
PMIREQUEST_LOCKREGISTERS Lock extended registers
PMIREQUEST_QUERYMAXMODEENTRIES Return number of available modes
PMIREQUEST_QUERYMAXMODELISTSIZE Return maximum size required to store mode data
PMIREQUEST_QUERYMAXTRAPENTRIES Return number of trap entries
PMIREQUEST_QUERYMODEHRDWRLIST Return the set mode command list
PMIREQUEST_QUERYMODEINFODATA Return table of video mode information
PMIREQUEST_QUERYTRAPLISTDATA Return table of data for trapped ports
PMIREQUEST_RESTORESTATE Restore video adapter state
PMIREQUEST_SAVESTATE Save video adapter state
PMIREQUEST_SETBANK Set current bank
PMIREQUEST_SETCLUT Set Color Lookup Table
PMIREQUEST_SETFONT Load given font
PMIREQUEST_SETMEMORYIOADDRESS Set the linear aperture address
PMIREQUEST_SETMODE Set the given mode
PMIREQUEST_SETPALETTE Set palette registers
PMIREQUEST_SOFTWAREINT Execute real-mode software interrupt
PMIREQUEST_TUNEDISPLAY Tune the display
PMIREQUEST_UNLOADPMIFILE Unload specified .PMI file
PMIREQUEST_UNLOCKREGISTERS Unlock extended registers

The individual VIDEOPMI DLL exported functions are described next, followed by code samples for loading a .PMI file, setting up a mode table, and doing a SetMode.

VIDEOPMI32Request

Syntax

Description:

VIDEOPMI32Request is the single, exported entry point from VIDEOPMI.DLL. The various PMI services are accessed through different function numbers passed in the parameters.

#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);
Parameters
pAdapter(PVIDEO_ADAPTER) - in/out Pointer to the current #VIDEO_ADAPTER data structure.
ulFunction(ULONG) - input Set to appropriate PMIREQUEST_ function.
pIn(PVOID) - input Pointer to applicable data structure.
pOut(PVOID) - output Pointer to applicable data structure.
rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks
When issuing this VIDEOPMI32Request, AdapterInfo_cp and VideoModeInfo_cp in VIDEO_ADAPTER should be set to sizeof(ADAPTERINFO) and sizeof(VIDEOMODEINFO). This way, VIDEOPMI can handle callers built from different sizes of #ADAPTERINFO #VIDEOMODEINFO and included in different versions of OS/2 Warp.
There is a 16-bit entry point, VIDEOPMI16Request, from VIDEOPMI.DLL for 16-bit callers. It functions exactly the same as its 32-bit counterpart VIDEOPMI32Request. Refer to the VIDEO_ADAPTER data structure in #Data Types for format and syntax information.

PMIREQUEST_CLEANUP

Syntax

Description:

PMIREQUEST_CLEANUP cleans 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);
Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.
ulFunction(ULONG) - input Set equal to PMIREQUEST_CLEANUP.
pIn(PVOID) - input NULL.
pOut(PVOID) - output NULL.
rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks
The [CLEANUP] section in the .PMI file will be executed. The graphics adapter can be set to VGA-compatible state by executing [UNLOCK] and [CLEANUP] sections in the .PMI file.

PMIREQUEST_GETBANK

Syntax

Description:

PMIREQUEST_GETBANK gets 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);
Parameters
pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.
ulFunction(ULONG) - input Set equal to PMIREQUEST_GETBANK.
pIn(PVOID) - input NULL.
pOut(PVOID) - output Pointer to a #BANKDATA data structure.
rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks
The bank number is obtained by executing the [GETBANK] section in the .PMI file. The bank number is saved in r0 in the .PMI file. It is then saved in ulBank in the #BANKDATA data structure. miBank in BANKDATA is the current mode ID.

PMIREQUEST_GETCLUT

Syntax

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETCLUT.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a #CLUTDATA data structure.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

The Color Lookup Table is set through I/O ports 0X3C7, 0X3C8, and 0X3C9. If the adapter does not use these I/O ports to set the Color Lookup Table, for example, memory-mapped adapters, this function will not work.

PMIREQUEST_GETFONT

Syntax

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETFONT.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a #FONTDATA data structure.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

ulCharCount in the #FONTDATA data structure is the number of characters in the font. ulFontHeight is the number of scanlines per character. bFontData is the start of the font data. The size is (ulCharCount * ulFontHeight) bytes.

PMIREQUEST_GETPALETTE

Syntax

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETPALETTE.

pInput(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a #PALETTEDATA data structure.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

The palette registers here are the palette registers indexed 0X00 - 0X0F in 0X3C0.

PMIREQUEST_IDENTIFYADAPTER

Syntax

Description:

PMIREQUEST_IDENTIFYADAPTER executes the [IdentifyAdapter] section in the specified .PMI file.

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_IDENTIFYADAPTER.

pIn(PVOID) - input Pointer to the ASCII string of the .PMI file.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR if the .PMI file is for the adapter installed; otherwise, returns ERROR_ADAPTER_NOT_SUPPORTED.

Remarks

This API can be executed without loading the .PMI file. The API serves as a quick test for whether the video represented by the pIn.PMI file is supported. If it is supported, the pAdapter->Adapter structure is filled. For any subsequent use of VIDEOPMI, #PMIREQUEST_LOADPMIFILE has to be executed.

PMIREQUEST_LOADPMIFILE

Syntax

Description: PMIREQUEST_LOADPMIFILE loads 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);

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_LOADFILE.

pIn(PVOID) - input Pointer to the ASCII string of the .PMI file.

pOut(PVOID) - output Pointer to BOOL; can be NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

If the .PMI file is successfully loaded, the Adapterfield in #VIDEO_ADAPTER will be filled with the information from the .PMI file.

If pOut is not NULL, *pOut is set to TRUE if the .PMI file is already loaded; FALSE, otherwise. Refer to #ADAPTERINFO and #VIDEO_ADAPTER data structures in #Data Types for format and syntax information.

PMIREQUEST_LOCKREGISTERS

Syntax

Description:

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

Return Value - rc rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_LOCKREGISTERS.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

The [LOCK] section in the .PMI file will be executed.

PMIREQUEST_QUERYMAXMODEENTRIES

Syntax

Description: PMIREQUEST_QUERYMAXMODEENTRIES returns the number of mode entries in the .PMI file.

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

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODEENTRIES.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a ULONG.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

None.

PMIREQUEST_QUERYMAXMODELISTSIZE

Syntax

Description:

PMIREQUEST_QUERYMAXMODELISTSIZE returns maximum size required to save a SetMode command list.

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODELISTSIZE.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a ULONG.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

Not all modes have a command list. Modes whose [SetMode] sections have no PMI sequence commands have no hardware command lists.

The hardware state of such modes can neither be saved nor restored by VIDEOPMI, but can be saved by a META-PMI handler provided by the vendor.

PMIREQUEST_QUERYMAXTRAPENTRIES

Syntax

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXTRAPENTRIES.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a ULONG.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

This function is not supported in OS/2 Warp, Version 3. The [TRAPREGS] section is currently read and used by the virtual video driver, not by videopmi.

PMIREQUEST_QUERYMODEHRDWRLIST

Syntax

Description:

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

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.

Remarks

None.

PMIREQUEST_QUERYMODEINFODATA

Syntax

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMODEINFODATA.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a MODEINFO data structure.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

pOut is the pointer to an area allocated by the caller. The size of that area is the number of modes obtained by #PMIREQUEST_QUERYMAXMODEENTRIES, multiplied by the size of #VIDEOMODEINFO.

PMIREQUEST_QUERYTRAPLISTDATA

Syntax

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYTRAPLISTDATA.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

This function is not supported in OS/2 Warp, Version 3. See "Remarks" in #PMIREQUEST_QUERYMAXTRAPENTRIES.

PMIREQUEST_RESTORESTATE

Syntax

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_RESTORESTATE.

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

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

See #PMIREQUEST_SAVESTATE.

PMIREQUEST_SAVESTATE

Syntax

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_SAVESTATE.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a #VIDEOSTATE data structure.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

miState in the #VIDEOSTATE data structure is the current mode ID in #VIDEOMODEINFO.

Four states can be saved and restored by setting fStateFlags and related fields in VIDEOSTATE accordingly, as follows:

  • Video mode (STATEFLAG_REGISTERS)

The Set Mode command list was saved in pModeData when the mode was set. For saving state, the values of registers used by BOUTB are copied back to pModeData. For restoring state, pModeData is executed to set the mode.

  • Video Memory (STATEFLAG_VRAM)

Video memory of size ulVRAMSaveSize is saved to pVRAM in saving state or restored from pVRAM in restoring state.

  • Color Lookup Table (STATEFLAG_CLUT)

Color Lookup Table can be saved to or restored from pCLUT.

  • Font (STATEFLAG_FONT)

Font can be saved to or restored from pFont.

PMIREQUEST_SETBANK

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETBANK.

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

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

See PMIREQUEST_GETBANK.

Before the [SETBANK] section in the .PMI file is executed, r0 is set to ulBank. in the #BANKDATA data structure. The current bank is set to ulBank in the BANKDATA data structure by executing the [SETBANK] section.

PMIREQUEST_SETCLUT

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETCLUT.

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

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.


Remarks

See #PMIREQUEST_GETCLUT.

PMIREQUEST_SETFONT

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETFONT.

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

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

See PMIREQUEST_GETFONT.

PMIREQUEST_SETMEMORYIOADDRESS

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMEMORYIOADDRESS.

pIn(PVOID) - input Pointer to the address to be set.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

This function executes the [SetMemoryIOAddress] section in the PMI file with r0 set to the passes address.

This function is also called implicitly when the #PMIREQUEST_SETMODE is called with the SET_LINEAR_BUFFER_MODE flag set to on. In this case, the address is set to pAdapter->ModeInfo.ulBufferAddress.

PMIREQUEST_SETMODE

Description:

PMIREQUEST_SETMODE sets requested video mode through the passed mode ID.

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMODE.

pIn(PVOID) - input Pointer to mode ID from the #VIDEOMODEINFO data structure.

pOut(PVOID) - output Pointer to the SetMode hardware command list.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

If pOut is not NULL, the Set Mode hardware command list is copied. It will be used in saving and restoring a session. The size of the memory to which pOut points is the maximum size of the hardware command list, which is obtained by the PMIREQUEST_QUERYMAXMODELISTSIZE function.

The caller has to set pAdapter->ModeInfo structure. If linear aperture mode is set, the mode ID should be ORed with SET_LINEAR_BUFFER_MODE. #PMIREQUEST_SETMEMORYIOADDRESS will be called implicitly with pAdapter->ModeInfo. ulBufferAddress as the input parameter used to set the linear aperture.

PMIREQUEST_SETPALETTE

Description:

PMIREQUEST_SETPALETTE sets palette registers to supplied values.

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETPALETTE.

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

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

See PMIREQUEST_GETPALETTE.

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Can be NULL. If not NULL, the adapter must have been loaded.

ulFunction(ULONG) - input Set equal to PMIREQUEST_SOFTWAREINT.

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

INITVDM defines how the worker routine will be initialized; can be NULL.

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

INTCRF includes client stack frame and an input/output buffer.

rc(APIRET) - returns Return codes.

Possible values follow:

NO_ERROR

ERROR_INADEQUATE_VDM_SUPPORT Make sure vprpmi.sys is installed.

ERROR_FULLVDM_CREATION_NOT_SHELLPROCESS See Attention: LIMITATION, listed under 1.a. in the "Remarks" section of this functional description.

ERROR_MINIVDM_PROCESSUPPORT_ONLY Make sure vprpmi.sys. is installed. Because mini-VDM is available, subsequent requests may be successful.

Remarks

This API allows for real-mode BIOS calls that need up to 4 KB in one or two input or output buffers. Although the service is generic, only VIDEO BIOS has been tested.

There are two types of worker VDM processes, depending on the requested VDM initialization as well as on the level of VDM support installed on the target machine, as follows:

1.Full VDM.

This process is equivalent to a full-screen DOS session that is created via an icon, stripped of its OS/2 components. The session has unrestricted video access. The session's DOS settings are manipulated by the VIDEOPMI and, therefore, are not affected by any standard settings or modifications to any of the DOS icons. The session can never be given foreground focus and is terminated only after its parent process terminates. If that should occur, there are no limitations on creating a new worker process. However, because the shell is the parent process, the event is unlikely. The session is completely hidden, as it is created without the knowledge of the session manager.

Note: When the int 10 full VDM session is started, the system will attempt to execute a videopmi.bat file. If the system does not find a videopmi.bat file in the root directory, it will default to autoexec.bat.

Because users often customize the autoexec.bat file, the autoexec.bat is unreliable or unusable in the int 10 full VDM session. To be sure the system has full control of the run-time environment of that session, make sure a videopmi.bat file exists in the system root directory.

Attention: LIMITATION

a.The full-VDM process can be created only under the shell process. VIDEOPMI ensures that the creation is limited to this window. A kernel patch is needed to cover any situations in which this may not be acceptable , for example, running a custom shell or testing the base video without a shell.

b.Full VDM requires that DOS support be installed on the target machine. As a result, a vendor driver using the software interface must ensure that this information is relayed to the customer. If, for any reason, DOS support is not desirable, full VDM is not the appropriate software interrupt solution and the Mini-VDM process described below should be used.

To ensure that a full-VDM process is created, the caller that initializes the VDM environment must specify the pIn parameter. Specifying the pIn-> ulFlags = VDM_INITIALIZE is sufficient. Optional application name and parameters may be specified as well. When initializing, if VDM creation fails, one of the following errors is returned:

ERROR_INADEQUATE_VDM_SUPPORT Make sure vprpmi.sys is installed.

ERROR_FULLVDM_CREATION_NOT_SHELLPROCESS The limitation listed under 1.a. (above) applies.

ERROR_MINIVDM_PROCESSUPPORT_ONLY Make sure vprpmi.sys is installed. Mini-VDM is available, so subsequent requests may be successful.

2.Mini VDM

This type of VDM process is provided for customer situations in which installing DOS support or running a full-VDM process is unacceptable. A mini-VDM process is a minimal v86 process for which ROM BIOS, BIOS data area, and video aperture are mapped in. All of the same calling interfaces and buffer passing capabilities of the full VDM apply. The worker VDM is created by the kernel as a child of the root process and, as such, is indestructable. If the video subsystem that created the process is unloaded and reloaded, the same VDM process is used.

Attention: LIMITATION

a.Virtualization of hardware resources and the exception management of mini-VDM are virtually nonexistent. All of the I/O resources are mapped physical, so any I/O that is executed goes to the hardware. None of the hardware interrupts are reflected; for example, timer ticks are not reflected in the BIOS data area. All of the ROM areas are mapped physical, so any self-modifying BIOS (those that are not in true ROM, of course) will affect subsequently started VDMs. The BIOS data area is the only page that is mapped linear, which means that it can be garbled without any danger to other VDMs running in the system.

There is no exception management. As a result, any of the unmapped memory (from 4 KB up to 0x9FFFF) or above 1 MB that is touched will cause a kernel exception to occur (no recovery). Neither virtual drivers nor the DOS kernel is loaded in this process, so no TSRs or utilities can be executed.

b.This solution requires a kernel patch for OS/2 Warp, Version 3.x customers, and a kernel patch and DOSCALLS.DLL upgrade for OS/2 2.x customers, in addition to the base video files.

PMIREQUEST_TUNEDISPLAY

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_TUNEDISPLAY.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

None.

PMIREQUEST_UNLOCKREGISTERS

Description:

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_UNLOCKREGISTERS.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

Returns NO_ERROR upon successful completion; otherwise, returns applicable DOS error messages.

Remarks

The [UNLOCK] section in the .PMI file will be executed.

PMIREQUEST_UNLOADPMIFILE

Description:

PMIREQUEST_UNLOADPMIFILE unloads the specified .PMI file. A .PMI file needs to be unloaded the same number of times it is loaded before all of its resources are freed. A .PMI file is loaded per driver-not per process. For example, a display driver, base video handler, and video configurator may all load the same .PMI file, which constitutes three users of the PMI subsystem. Before the PMI subsystem can be unloaded, PMIREQUEST_UNLOADPMIFILE must be invoked three times before the file is unloaded.

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

Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a #VIDEO_ADAPTER data structure.

ulFunction(ULONG) - input Set equal to PMIREQUEST_UNLOADFILE.

pIn(PVOID) - input Pointer to the ASCII string of the .PMI file.

pOut(PVOID) - output NULL

rc(APIRET) - returns Return codes.

Values are as follows:

NO_ERROR Successful completion

ERROR_ADAPTER_NOT_SUPPORTED The PMI file wasn't loaded.

Remarks

The .PMI file can be a flat .PMI file or a .DLL shared library.

Code Sample

The following code sample shows how to load the .PMI file, set up the mode table, and set the graphics mode.

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

The VIDEOPMI interface also provides parameters for the adapter virtualization in multiple DOS sessions and a number of support functions. The adapter description is provided as a flat file with an extension of .PMI. The main goal of the VIDEOPMI interface is to centralize all of the SetMode-related services and provide a consistent interface that is not dependent on availability of BIOS service or OEM utilities.

The following list includes the topics covered in this chapter:

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 means of implementing the exported function. This can be achieved only from a shared library. A flat .PMI file will not call VIDEOPMI's entry point. Provided that the shared library exports the "Load Adapter" API and conforms to the META-PMI definition, this method also allows for modifying VIDEOPMI's function by chaining into its calling table.

The drawback to this method is that the imported objects' source code is developed for a specific hardware and operating system platform and has to be ported to a new platform. Another drawback is that the imported binary object may introduce execution violations unless it is thoroughly tested.

PMI Language Constructs + Imported Functions

This method represents a compromise between the two implementations discussed previously.

The method is applicable for vendors who require code reuse with small maintenance effort, but have performance-sensitive chip sets on board. Another example would be chip vendors who are handling a number of different adapter implementations with a single PMI file. Such PMI files could have common PMI sequence-based SetMode, UnLock and Cleanup functions, but adapter-specific functions, such as DAC and clock-chip programming, could be imported from an external binary object. Porting mixed PMI files to another operating system platform requires porting of the source code only.

External binary objects are 32-bit dynamic libraries, which have to provide instance initialization and export all of the functions that are referenced in the .PMI file. See #Include Files in #PMI Language Elements and #PMI Sections for more detail.

Note:The imported library (OEMPMI.DLL) that is shipped with the IBM Developer Connection Device Driver Kit for OS/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 Support in this chapter).
    At the minimum, modes that are supported by the respective Presentation Manager display driver.
    If the adapter in question has both accelerated and nonaccelerated modes, only the accelerated modes should be provided.
  • At best, all of the supported hi-color and true-color modes with respective refresh rates (see #Monitor Timings Support in this chapter).

At the minimum, modes which are supported by the respective Presentation Manager display driver.

If the adapter in question has both accelerated and nonaccelerated modes, only the accelerated modes should be provided.

Monitor Timings Support

The PMI defines eight display-timing-related variables as mode keyvariables . These variables facilitate selection of the mode, depending on the current monitor specification and sizing of the active display for the current mode. The MonitorModeInfo section contains all of the timing- related PMI key variables.

The display-timing-related variables are:

VerticalRefresh Vertical refresh in Hz (rounded to the nearest integer)

HorizontalRefresh Horizontal refresh in KHz (rounded to the nearest integer )

HPolarityPositive Contains the Horizontal polarity (0,1) for the current mode selection

VPolarityPositive Contains the Vertical polarity (0,1) for the current mode selection

ScreenLeftEdge Represents the end of the horizontal blanking (HBP) in pixel count along the horizontal sweep (HSP)

ScreenRightEdge Represents the start of the horizontal blanking (HFP) in pixel count along the horizontal sweep (HSP)

ScreenTopEdge Represents the end of the vertical blanking (VBP) in line count along the vertical sweep (VSP)

ScreenBottomEdge Represents the start of the vertical blanking (VFP)

The last four timing elements, defining the start and end of the horizontal active display and start and end of the vertical active display, are suggested as mode elements in order to enhance visual quality. Their values are never directly communicated to the end user configuring the adapter, only the net results. The values are manipulated through a TuneDisplay function as part of the SetMode or upon the end user's configuration request. See [TuneDisplay] section in #PMI Sections.

There is no interface for specification and manipulation of the widths of the Horizontal Sweep (HSP) and Vertical Sweep (VSP) signals.

If an adapter is capable of supporting both non-CRT- and CRT-style displays , modes of both types should be listed. Non-CRT Mode sections are those that have 0 for both horizontal and vertical refresh rate.

If the adapter has monitor sensing, identification, and auto-adjusting capability built in so that software manipulation of the timing-related registers is not required, none of the timing-related mode elements have to be specified. No MonitorModeInfo sections should be included and monitor sizing parameters and the TuneDisplay function should not be listed.

The vendor providing the .PMI file can supply either a single MonitorModeInfo, which denotes the upper limit for horizontal and vertical refresh, or a number of MonitorModeInfo sections with distinct sets of horizontal and vertical refresh values. In the first case, the OS/2 Warp configuration utility offers refresh values that are part of the current monitor definition for the desired resolution, as long as the monitor specification is within the range specified by the adapter. If more than one MonitorModeInfo section exists per mode, all of those within the monitor's specification are offered as a selection to the user by the OS/2 Warp Video Configuration Manager. Polarity PMI keyvariables are not required, unless an exact match with the monitor's capabilities is desired by the adapter vendor.

Save and Restore State

VIDEOPMI does not have dedicated SaveState or RestoreState sections. The VIDEOPMI engine does offer those services.

SaveRestore VRAM

VIDEOPMI offers saving and restoring of the video buffer of SaveSize for each mode and is internally aware of the type of VRAM access it has to perform. The parameters taken into consideration when addressing the VRAM are BufferAddress, ApertureSize, and SaveSize. See [ModeInfo] section in #PMI Sections.

If ApertureSize is equal to or greater than SaveSize, direct linear access to the BufferAddress is assumed. If this is not the case, the SetBank function is necessary in order to save and restore the entire on-screen VRAM. Granularity of a bank is assumed to be the ApertureSize. SaveSize should be set to reflect the logical line length programmed by the current mode, rather than just horizontal resolution.

SaveRestore Hardware

This service is available for .PMI files that use the PMI language to define SetMode sections.

The PM driver performs its own Save and Restore of the state and is not dependent on the service. The bvhsvga.dll uses the Save and Restore State service to save and restore OS/2 full screen sessions; in case of a partial restore, bvhsvga.dll reissues the mode set and restores the important video attributes.

The SaveRestore Hardware service is based on the PMI sequence for the SetMode; all of the ports that are programmed by the SetMode section for the current mode will be saved and restored. When saving a mode, the VIDEOPMI interpreter parses the command list of the SetMode section.

BOUTB commands are converted into BINB commands. The VIDEOPMI executes the newly constructed section in order to capture register values and converts all of the commands back into their original SetMode format. The command list is then ready for a subsequent RestoreState call and is returned to the user.

This approach has some limitations, mainly for adapters that employ double and higher indirection levels in register addressing; for example, the WDc24.

Adapter Configuration

This portion of the chapter specifies the requirements placed on the .PMI file by the video subsystem. It does not address the physical installation steps for an adapter, or the bus management, device enumeration, and conflict management employed by the operating system.

An adapter is defined by its Hardware section, which lists the type of bus, the default start address of the I/O and memory space, and alternative addresses for the I/O and memory space, as addressable by the CPU. The adapter is uniquely defined by its OEMString and Version strings.

PMI Language Elements

The VIDEOPMI language consists of the following elements:

  • Sections
  • User-defined functions
  • Expressions
  • PMI commands, identifiers, constants, variables, string-literals, and comments

The language is not case-sensitive, so BOUTB and boutb represent the same identifier. Throughout this section, Backus-Naur Form (BNF) grammar is used to describe the syntax. Some examples are given in the text. Where such examples are omitted, sample .PMI files accompanying the document should be used as a reference.

Comments and Delimiters

Comments can be either in-line comments (//) or ANSI C style comments (/* */). White space is used as the token delimiter and a semicolon (;) is used as the expression delimiter.

The Comment section defines a mode-info related comment that describes the mode to the user. See [Comment] in #PMI Sections.

Include Files

PMI allows for inclusion of other .PMI files, all of which must conform to the PMI language. The include files should be in the same directory as the current .PMI file. There can be more than one #include statement in a .PMI file. The include .PMI files can have #include statements to include other .PMI files. An Include file facility is provided in order to offer flexibility in supporting multiple adapter configurations with a single . PMI file. Failure to locate the include .PMI file does not cause the unloading of the SVGADATA.PMI file.

The external binary objects are included using a #includecode directive, and flat PMI sub-files are included using a #include directive. The include statement can be found anywhere in the .PMI file as long as it does not violate the integrity of the section before and the section after, and as long as the references to the objects belonging to the include file are made after the inclusion.

External binary objects are considered "binary include" files. The VIDEOPMI parser attempts to load the module as a 32-bit DLL and attempts to resolve the procedural addresses for every external code reference made using all of the loaded module. If the loading or address resolution fails, the loading of the .PMI file fails.

#include "filename" //PMI extension assumed
#includecode "filename" //DLL extension assumed

Constants, String-Literals, Identifiers, and Keywords

PMI constants are 32-bit integer constants, either in decimal or hexadecimal format.

<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 Sections for more information on dynamic vs. static keyvariables.

Not all of the PMI keyvariables have to be defined. See [ModeInfo] and [Hardware] in #PMI Sections for further explanations.

PMI Keyvariables

The following table lists all of the keyvariables for the Protect Mode Interface (PMI).

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_ADAPTER structure is passed by PMI procedural callers at every PMI entry point and is available to all of the PMI functions other than IdentifyAdapter. All PMI functions have addressability to the current state of the PMI registers and care should be taken in using the registers.

PMI Commands

PMI commands are divided into several categories, as follows:

  • Simple I/O commands
  • Block I/O commands
  • Read/Modify/Write commands
  • Simple memory access commands
  • WAIT command

INx Commands

INx commands perform an I/O input from the source and place the result into the destination. Width can be byte, word, or doubleword. The syntax is as follows:

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 #VIDEOMODEINFO structure will have MODE_FALG_LINEAR_BUFFER flag set to on, indicating that this mode can be set to linear aperture mode. [SetMemoryIOAddress] should also be provided to handle the address setting.

  • PortIOAddress = <constant> ['{' <pio list> '}'] <pio list> ::= <constant> | <constant> [',' <pio list>]

Specifies default base port address for port I/O and a list of possible I/O addresses. For example, this variable for an MCA XGA adapter would reflect its instance that needs to be added to all of the register addresses. See the preceding discussion on MemoryIOAddress.

  • Endian = {BIG | LITTLE}

This represents the endian control capability of the device. The PMI constants are always represented with the most significant byte at the leftmost position. There are three possible cases of endian control:

  • The device can conform to the endian type of the platform, such as WEITEK or XGA.
  • The device cannot conform to the endian type but is of the same endian type as the platform.
  • The device is of a different endian type than the platform on which it is installed.

The first two cases require no endian conversion on the part of the VIDEOPMI interpreter. In the third case, the VIDEOPMI interpreter native to a platform will perform the byte swapping to the platform's endian type. The programming of the endian control on devices that are capable of address swapping, such as XGA or WEITEK, is the responsibility of the .PMI file. In the case of WEITEK, this is done indirectly by generating correct addresses. It is preferable to configure the adapter in the endian control of the platform for which it is intended, if such capability is present.

Here is a sample .PMI file for a Viper VLB card:

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_SETMODE for details.

[UnLock]

This section contains the list of commands required to make the hardware available for the execution of the SetMode section, as well as for saving and restoring of the controller and video buffer. The list of commands should be inclusive of saving and restoring the registers modified in the process, with the exclusion of the unlock key register. The function can be made mode-sensitive by using the conditional statements that evaluate key mode PMI keyvariables. However, the function could be a superset of all required unlock commands, for as long as such a sequence is not counter- productive in any mode sets.

Here is a sample .PMI file for a 9GXE S3 card:

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 Modes and [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

Syntax

Description:

AddMonitorData adds a monitor definition to the VIDEOCFG.DLL monitor definitions database. The monitor definition is also written to the MONITOR.DIF file.

#include <svgadefs.h>

MONITORINFO    *pNewMonitorInfo;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;                /*  Return codes. */

rc = AddMonitorData(*pNewMonitorInfo);

Parameters

*pNewMonitorInfo(#MONITORINFO) - input Pointer to the MONITORINFO data structure.

This parameter points to the #MONITORINFO data structure that specifies the new monitor definition to add to the database.

rc(ULONG) - returns Return codes.

0 Function is successful
Nonzero Returns one of the following errors:


ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT

Remarks

None.

GetAllMonitors

Syntax

Description:

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

Parameters

*pMonitors(MONITORINFO) - output Pointer to the array of #MONITORINFO data structures.

This parameter points to the array of MONITORINFO data structures that receive all the monitor definitions in the MONITOR.DIF file.

pulBufferSize(PULONG) - output Specifies the size of the 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.


GetCurrentCFG

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

*pAdapter(ADAPTERINFO) - output Pointer to the #ADAPTERINFO data structure.

This parameter points to the data structure receiving the current video adapter information.

*pMonitor(MONITORINFO) - output Pointer to the #MONITORINFO data structure.

This parameter points to the data structure receiving the current video monitor information.

rc(ULONG) - returns Return codes.

0 Function is successful
Nonzero Returns one of the following errors:


ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION

GetCurrentCFG - Remarks

None.

GetCurrentDesktopMode

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

*pVideoAdapter(VIDEO_ADAPTER) - output Pointer to the #VIDEO_ADAPTER data structure.

This parameter points to the data structure receiving the desktop mode information.

rc(ULONG) - returns Return codes.

TRUE Function is successful
FALSE Function is unsuccessful.

GetCurrentDesktopMode - Remarks

None.

QueryNumMonitors

Description:

QueryNumMonitors queries 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 - 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.

SetCurrentCFG

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

*pAdapter(ADAPTERINFO) - input Pointer to the #ADAPTERINFO data structure.

This parameter points to the data structure that specifies the current adapter configuration to be set in the Registry.

*pMonitor(MONITORINFO) - input Pointer to the #MONITORINFO data structure.

This parameter points to the data structure that specifies the current monitor configuration to be set in the Registry.

rc(ULONG) - returns Return codes.

0 Function is successful
Nonzero Returns one of the following errors:


ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION

SetCurrentCFG - Remarks

None.

Generic Video Configuration Interface

The Video Configuration Manager supports a generic video configuration interface that allows any display driver to interface with the user via notebook settings in the System icon. The driver needs to export DevEscape calls that identify the capability. The driver also needs to provide DevEscape calls that allow the VIDEOCFG to query the current value and notify the driver when the user sets the value. The DevEscape functions are invoked as Ring3. The method of recording the current setting, as well as default values, is at the driver's discretion.

GreEscape DEVESC_QUERYDRIVERCAPS

Simulation support:

This function is optional for display drivers and has no simulation support .

Description:

GreEscape DEVESC_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 - Parameters

hdc(HDC) - input A handle to the device context.

lCode(LONG) - input DEVESC_QUERYDRIVERCAPS

lInCount(LONG) - input Not used.

pbInData(PBYTE) - input Not used.

plOutCount(PLONG) - output The number of bytes of data pointed to by pbOutData.

On return, this is updated to the number of bytes returned.

pbOutData(PBYTE) - output The address of a buffer that will contain a ULONG variable specifying the number of capabilities.

On return, this buffer contains a ULONG variable that specifies the number of capabilities that the driver supports, immediately followed by an array of #DRIVERCAPS structures.

Note:This allows a driver to export multiple capabilities (each, in turn, gets its own page in the System icon).

rc(LONG) - returns Return Code.

Returns NO_ERROR.

GreEscape DEVESC_QUERYDRIVERCAPSLIST

Simulation support:

This function is optional for display drivers and has no simulation support .

Description:

GreEscape DEVESC_QUERYDRIVERCAPSLISTfills the pValueList, pCurrentValue,and pDefaultValuein the #DRIVERCAPS data 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 - Parameters

hdc(HDC) - input A handle to the device context.

lCode(LONG) - input DEVESC_QUERYDRIVERCAPSLIST

lInCount(LONG) - input Number of bytes pointed to by pbInData.

pbInData(PBYTE) - input Pointer to a #DRIVERCAPS data structure.

The DRIVERCAPS data structure specifies the driver capability to query. Storage is already allocated for pValueList, pCurrentValue,and pDefaultValue.

When ulCapsType= CAPSTYPE_BOOLEAN, the driver does not have to fill pValueList.

plOutCount(PLONG) - output Not used.

pbOutData(PBYTE) - output Not used.

rc(LONG) - returns Return Code.

Returns NO_ERROR.

GreEscape DEVESC_SETDRIVERCAPSVALUE

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

hdc(HDC) - input A handle to the device context.

lCode(LONG) - input DEVESC_SETDRIVERCAPSVALUE

lInCount(LONG) - input Number of bytes pointed to by pbInData.

pbInData(PBYTE) - input Pointer to a #DRIVERCAPS data structure.

The DRIVERCAPS data structure specifies the driver capability to set.

plOutCount(PLONG) - output Not used.

pbOutData(PBYTE) - output Not used.

rc(LONG) - returns Return Code.

Returns NO_ERROR.

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 REA 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 ; 
Field - cb

cb(ULONG) Length of the structure.

Field - ulAdapterID

ulAdapterID(ULONG) Specifies the adapter by ID.

Field - szOEMString[MAX_OEM_STRING]

szOEMString[MAX_OEM_STRING](CHAR) Contains adapter information.

Valid value is as follows:

MAX_OEM_STRING 128

Field - szDACString[MAX_DAC_STRING]

szDACString[MAX_DAC_STRING](CHAR) Contains DAC information.

Valid value is as follows:

MAX_DAC_STRING 128

Field - szRevision[MAX_VERSION]

szRevision[MAX_VERSION](CHAR) Contains version information.

Valid value is as follows:

MAX_VERSION 128

Field - ulTotalMemory

ulTotalMemory(ULONG) Total video memory.

Field - ulMMIOBaseAddress

ulMMIOBaseAddress(ULONG) Base address for memory-mapped I/O registers.

Field - ulPIOBaseAddress

ulPIOBaseAddress(ULONG) Base address for I/O ports.

Field - bBusType

bBusType(BYTE) Type of bus (PCI, VLB, and so on.)

The valid values for this flag are as follows:

ISA_BUS 0
VLB_BUS 1
PCI_BUS 2
EISA_BUS 3
PCMCIA_BUS 4
MCA_BUS 5
ADAPTERINFO Field - bEndian

bEndian(BYTE) Big Endian or little Endian.

LITTLE_ENDIAN 0

BIG_ENDIAN 1

Field - usDeviceBusID

usDeviceBusID(USHORT) Reserved.

Field - usVendorBusID

usVendorBusID(USHORT) Reserved.

Field - usSlotID

usSlotID(USHORT) Reserved.

APIRET

Unsigned integer in the range 0 through 4 294 967 295.

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;
Field - miBank

miBank(MODEID) ID of the current mode.

Field - ulBank

ulBank(ULONG) Current bank number.

BITBLTINFO

BitBlt information structure. BitBlt information structure, used for the #GHI_CMD_BITBLT and #VMI_CMD_BITBLT functions.

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 ;
Field - ulLength

ulLength(ULONG) Length of the BITBLTINFO data structure, in bytes.

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.
Field - cBlits

cBlits(ULONG) Count of Blts to be performed.

Field - ulROP

ulROP(ULONG) Raster operation.

Field - ulMonoBackROP

ulMonoBackROP(ULONG) Background mix if B_APPLY_BACK_ROP is set.

Field - ulSrcFGColor

ulSrcFGColor(ULONG) Monochrome source Foreground color.

Field - ulSrcBGColor

ulSrcBGColor(ULONG) Monochrome source Background color and transparent color.

Field - ulPatFGColor

ulPatFGColor(ULONG) Monochrome pattern Foreground color.

Field - ulPatBGColor

ulPatBGColor(ULONG) Monochrome pattern Background color.

Field - abColors

abColors(PBYTE) Pointer to color translation table.

Field - pSrcBmapInfo

pSrcBmapInfo(PBMAPINFO) Pointer to source bit map (#BMAPINFO)

Field - pDstBmapInfo

pDstBmapInfo(#PBMAPINFO) Pointer to destination bit map (BMAPINFO).

Field - pPatBmapInfo

pPatBmapInfo(PBMAPINFO) Pointer to pattern bit map (BMAPINFO).

Field - aptlSrcOrg

aptlSrcOrg(PPOINTL) Pointer to array of source origin #POINTLs.

Field - aptlPatOrg

aptlPatOrg(PPOINTL) Pointer to array of pattern origin POINTLs.

Field - abrDst

abrDst(#PBLTRECT) Pointer to array of Blt rects.

Field - prclSrcBounds

prclSrcBounds(PRECTL) Pointer to source bounding rect of source Blts.

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 ; 
Field - ulXOrg

ulXOrg(ULONG) X origin of the destination Blt.

Field - ulYOrg

ulYOrg(ULONG) Y origin of the destination Blt.

Field - ulXExt

ulXExt(ULONG) X extent of the BitBlt.

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 ; 
Field - ulLength

ulLength(ULONG) Length of the BMAPINFO data structure, in bytes.

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.
Field - ulWidth

ulWidth(ULONG) Width in pels of the bit map.

Field - ulHeight

ulHeight(ULONG) Height in pels of the bit map.

Field - ulBpp

ulBpp(ULONG) Number of bits per pel/color depth.

Field - ulBytesPerLine

ulBytesPerLine(ULONG) Number of aligned bytes per line.

Field - pBits

pBits(PBYTE) Pointer to bit-map bits.

The scanlines of the bit map can be either byte-aligned or word-aligned.

BUFFER

Data structure inside #INTCRF containing the input/output buffers for the bios call.

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 ; 
Field - bBufferType ===

bBufferType(BYTE) Input buffer.

BUFFER_NONE 0

INPUT_BUFFER 1

OUTPUT_BUFFER 2

Field - bReserved

bReserved(BYTE) Reserved

Field - bSelCRF

bSelCRF(BYTE) CRF flag for the selector.

UlONG index into the CRF.

Field - bOffCRF

bOffCRF(BYTE) CRF flag for the offset.

ULONG index into the CRF.

Field - pAddress

pAddressLinear address of the 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:

  1. 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:

  1. 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_QUERYCHAININFO function.

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 #RGB array 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 #RGB triplets.

CLUTDATA Field - aRGB[1]

aRGB[1](SVGARGB) Start of #SVGARGB; one entry is allocated.

CODECINFO

Determines whether data is to be compressed or decompressed.

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_QUERYDRIVERCAPS functions.

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:

  1. 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_TEXT and #VMI_CMD_TEXT functions. The #TEXTBLTINFO structure 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;
Field - ulLength

ulLength(ULONG) Length of FBINFO data structure, in bytes.

Field - ulFlags

ulFlags(ULONG) Specifies the capabilities supported.

This flag has the following value:

FB_SUPPORTSVRAMALLOC 0x0010; supports allocation of on-card memory

Field - ulBPP

ulBPP(ULONG) Screen bits per pel.

This value may be 32 for some 24-bit color adapters.

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

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_TEXT and #VMI_CMD_TEXT functions.

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_TEXT and #VMI_CMD_TEXT functions.

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_EVENT function.

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_EXTENSION function.

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_PALETTE function.

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

HWREQIN

Input packet to the #GHI_CMD_REQUESTHW function.

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:

  1. 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 #COLORINFO data structures pointed to by pSrcColorInfo.

IMAGECAPS Field - pSrcColorInfo

pSrcColorInfo(#PCOLORINFO) Pointer to array of source COLORINFO data structures.

IMAGECAPS Field - ulNumDst

ulNumDst(ULONG) Number of destination COLORINFO data structures pointed to by pDstColorInfo.

IMAGECAPS Field - pDstColorInfo

pDstColorInfo(#PCOLORINFO) Pointer to array of destination COLORINFO data structures.

IMAGEPACK

Information pertaining to PutImage and GetImage.

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

LINEINFO Field - prclBounds

prclBounds(#PRECTL) Pointer to bounding rect of a clipped line.

LINEINFO2

Line information data structure for simple lines, used for #VMI_CMD_LINE and #GHI_CMD_LINE functions.

The LINEINFO2 structure will never be passed to a GRADD unless the GRADD indicates it can handle both LINEINFO and LINEINFO2 structures by setting the DS_SIMPLE_LINES flag in the ulFCFlags member of #CAPSINFO.

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 ; 
Field - ulLength

ulLength(ULONG) Length of LINEINFO2 data structure.

Field - ulType

ulType(ULONG) Defines line type.

LINE_SOLID Line will be solid in Foreground color.
LINE_INVISIBLE Line is not drawn.
LINE_ALTERNATE Line will be alternating Foreground and Background color; ignores style.

Field - ulStyleMask

ulStyleMask(ULONG) A 32-bit style mask.

Field - cLines

cLines(ULONG) Count of lines to be drawn.

Field - ulFGColor

ulFGColor(ULONG) Line Foreground color.

Field - ulBGColor

ulBGColor(ULONG) Line Background color.

Field - usForeROP

usForeROP(USHORT) Line Foreground mix.

Field - usBackROP

usBackROP(USHORT) Line Background mix.

The following flags apply to ulForeROP and ulBackROP:

  • LR_ZERO
  • LR_INVERTMERGEPAT
  • LR_MASKINVERTPAT
  • LR_INVERTCOPYPAT
  • LR_MASKPATINVERT
  • LR_INVERT
  • LR_XORPAT
  • LR_INVERTMASKPAT
  • LR_MASKPAT
  • LR_INVERTXORPAT
  • LR_LEAVEALONE
  • LR_MERGEINVERTPAT
  • LR_PATCOPY
  • LR_MERGEPATINVERT
  • LR_MERGEPAT
  • LR_ONE
Field - pDstBmapInfo

pDstBmapInfo(#PBMAPINFO) Pointer to destination surface bit map.

Field - ulFlags

ulFlags(ULONG) Flags used for the LINEINFO2 data structure.

LINE_DO_FIRST_PEL Draw first pel of first line if not clipped.
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.

Field - ulXYStyleStep

ulXYStyleStep(ULONG) Low byte of low word: x style, High byte of low word: y style.

The x style step is used for X-major lines where abs(dx) > abs(dy). The x style step is used for lines where abs(dx) < abs(dy).

The style step is added to the current style value for each pel.

Field - pulStyleValue

pulStyleValue(PULONG) Pointer to style value at current pel.

The style value is composed as an error value and a mask position, as follows:

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.

Field - ptlOrigin

ptlOrigin(#POINTL) Origin to be added to all coordinates.

Field - pptlStart

pptlStart(PPOINTL) Pointer to #POINTL defining start point of first line.

Field - pptlLines

pptlLines(PPOINTL) Pointer to #POINTLarray defining connected line endpoints.

The number of array entries is defined by #cLines.

Field - ptlClipStart

ptlClipStart(#POINTL) Clipped start point if it is clipped.

Field - ptlClipEnd

ptlClipEnd(POINTL) Clipped end point if it is clipped.

Field - lClipStartError

lClipStartError(LONG) Bresenham error at the clip start point for first line (not valid if first line is horizontal or vertical).

Field - prclBounds

prclBounds(#PRECTL) Pointer to bounding rect of a clipped line.

LINEPACK

Line information data structure on a per-line basis.

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 ; 
Field - ulStyleStep

ulStyleStep(ULONG) Value to be added to ulStyleValue.

The value to be added to ulStyleValue on each pel stepped along the style major direction.

Field - ulStyleValue

ulStyleValue(ULONG) Style value at the current pel.

The style value is composed of an error value and a mask position, as follows:

|high word      |3 bits         |5 bits         |8 bits         |
|---------------+---------------+---------------+---------------|
|not used       |not used       |mask pos       |error value    |
Field - ulFlags

ulFlags(ULONG) Flags used for the LINEPACK data structure.

LINE_DO_FIRST_PEL Draws the first pel.

LINE_DIR_Y_POSITIVE Indicates line direction is bottom-to-top.

LINE_HORIZONTAL Indicates line is horizontal. No Bresenham algorithm.

LINE_X_MAJOR Line is XMAJOR.

LINE_DIR_X_POSITIVE Indicates line direction is left-to-right.

LINE_VERTICAL Indicates line is vertical. No Bresenham algorithm.

LINE_STYLE_X_MAJOR Line style is XMAJOR.

LINE_DO_LAST_PEL Draws the last pel.

Field - plpkNext

plpkNext(LINEPACK) Pointer to next LINEPACK data structure.

Field - ulAbsDeltaX

ulAbsDeltaX(ULONG) Clipped Bresenham Delta X, absolute.

Field - ulAbsDeltaY

ulAbsDeltaY(ULONG) Clipped Bresenham Delta Y, absolute.

Field - ptlClipStart

ptlClipStart(#POINTL) Pointer to location for device to perform Bresenham algorithm.

Pointer to location where device performs the Bresenham algorithm. Sets only the pels from ptlClipStart to ptlClipEnd, inclusive.

Field - ptlClipEnd

ptlClipEnd(POINTL) Ending location for Bresenham algorithm (see ptlClipStart).

Field - ptlStart

ptlStart(POINTL) Pointer to starting location for line.

The device can perform the Bresenham algorithm from ptlStart or ptlClipStart.

Field - ptlEnd

ptlEnd(POINTL) Ending location for line.

Field - lClipStartError

lClipStartError(LONG) Standard Bresenham error at the clipped start point.

Error is calculated from the initial error and the error increments for major step and diagonal step. The initial error and the error increments are as follows:

MAX Maximum (ulAbsDeltaX, ulAbsDeltaY)
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 ; 
Field - ulPhysAddr

ulPhysAddr(ULONG)

Field - ulMemLen

ulMemLen(ULONG)

Field - ulVirtAddr

ulVirtAddr(ULONG)

MEMINFO Field - pNextMI

pNextMI(struct_MEMINFO)

MONITORINFO

The MONITORINFO data structure receives information for the current video monitor.

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 ; 
Field - szMonitor[MAX_MONITOR_LEN]

szMonitor[MAX_MONITOR_LEN](CHAR) Contains monitor information.

Field - MonitorModeInfo[MAX_MONITOR_MODES]

MonitorModeInfo[MAX_MONITOR_MODES](#MONITORMODEINFO) Contains information about the monitor mode.

MONITORMODEINFO

Contains information on the types of monitor modes.

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_TEXT and #VMI_CMD_TEXT functions. 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 ; 
Field - ulLength

ulLength(ULONG) Length of the TEXTBLTINFO structure, in bytes.

Field - flOptions

flOptions(ULONG) Not used.

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.

Field - pGlyphIndicies

pGlyphIndicies(PLONG) Pointer to glyph indices.

This string can also be modified based on lGlyphCnt conditions. Refer to #GLYPHINFO for example structures to access glyph information. The lowest byte is used to access the low byte table and the 2nd to lowest byte is used to access the high byte table.

Field - ulFGMix

ulFGMix(ULONG) Foreground mix mode.

Field - ulBGMix

ulBGMix(ULONG) Background mix mode.

Field - ulFGColor

ulFGColor(ULONG) Foreground colors.

Field - ulBGColor

ulBGColor(ULONG) Background colors.

Field - pDstBmapInfo

pDstBmapInfo(#PBMAPINFO) Pointer to destination physical surface descriptions.

Field - pDevFntInfo

pDevFntInfo(#PDEVFONTINFO) Pointer to P#DEVFONTINFO for additional font information.

Field - ulClpCnt

ulClpCnt(ULONG) Number of clip regions that intersect glyph data.

Field - abrClipRects

abrClipRects(#PBLTRECT) Array of ulClpCnt clip rectangles.

Field - aptlSrcOrg

aptlSrcOrg(#PPOINTL) Array of glyph origin points.

Field - abrDst

abrDst(#PBLTRECT) Array of destination rectangles.

USERCAPSIN

Information structure used for #GHI_CMD_USERCAPS and #VMI_CMD_USERCAPS functions.

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;
Field - ulLength

ulLength(ULONG) Length of the USERCAPSIN structure in bytes.

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 #DRIVERCAPS structures must not be filled in for this call.

The driver must ensure that the buffer area size, specified by ulSize, is sufficient for the supported number of capabilities. If not, the driver should return the number of capabilities supported in the first word of the buffer area and a return code of RC_ERROR. The driver will be reinvoked with a larger buffer area for QUERYCAPS. This allows a driver to export multiple capabilities (each, in turn, gets its own page in the System Object notebook).

QUERYCAPSLIST
#define  QUERYCAPSLIST   2L

QUERYCAPSLIST fills the pValueList, pCurrentValue, and pDefaultValue fields in the #DRIVERCAPS structure pointed to by pOut. The members must be 0 padded up to the length specified by ulValueMemberSize.

SETCAP
#define  SETCAP    3L

SETCAP sets a value that the user has selected. The value is specified in the pCurrentValue field of the #DRIVERCAPS structure pointed to by pOut.

Field - ulSize

ulSize(ULONG) Length, in bytes, of buffer area.

VCRF

Data structure inside #INTCRF containing the register values to be passed in the bios call.

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;
Field - reg_eax

reg_eax(ULONG)

Field - reg_ebx

reg_ebx(ULONG)

Field - reg_ecx

reg_ecx(ULONG)

Field - reg_edx

reg_edx(ULONG)

Field - reg_ebp

reg_ebp(ULONG)

Field - reg_esi

reg_esi(ULONG)

Field - reg_edi

reg_edi(ULONG)

Field - reg_ds

reg_ds(ULONG)

Field - reg_es ===

reg_es(ULONG)

Field - reg_fs

reg_fs(ULONG)

Field - reg_gs

reg_gs(ULONG)

Field - reg_cs

reg_cs(ULONG)

Field - reg_eip

reg_eip(ULONG)

Field - reg_eflag

reg_eflag(ULONG)

Field - reg_ss

reg_ss(ULONG)

Field - reg_esp

reg_esp(ULONG)

VIDEO_ADAPTER

The VIDEO_ADAPTER data structure receives information for the desktop mode.

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;
Field - hvideo ===

hvideo(HVIDEO) The handle for this adapter.

Field - Adapter ===

Adapter(#ADAPTERINFO) Hardware information for this adapter.

Field - ModeInfo ===

ModeInfo(#VIDEOMODEINFO) Information about the current video mode.

VIDEOMODEINFO

The VIDEOMODEINFO data structure receives information for the current video monitor.

Note: The 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;
Field - cb

cb(ULONG) Size of the structure.

Field - miModeId

miModeId(MODEID) Used to make a SetMode request.

Field - usType

usType(USHORT) Flag indicating mode type.

The following values are valid for this flag:

MODE_FLAG_NOT_MONO 0x0001; Mono-compatible

MODE_FLAG_GRAPHICS 0x0002; Text mode, Graphics

MODE_FLAG_NO_CLR_BRST 0x0004; Disable Color burst

MODE_FLAG_NATIVE 0x0008; Native (advanced function) mode

IGNORE_CLR_BRST 0x0010; Disable color burst; doesn't make sense for this mode

NOT_PLASMA 0x0020; will not work on plasma display

MODE_FLAG_VGA_ENTRY 0x0040; VGA mode, needs clean up

Field - usInt10ModeSet

usInt10ModeSet(USHORT) Interrupt 10 mode.

Field - usXResolution

usXResolution(USHORT) Horizontal pixels.

Field - usYResolution

usYResolution(USHORT) Vertical scanlines.

Field - ulBufferAddress

ulBufferAddress(ULONG) Physical address of VRAM.

Field - ulApertureSize

ulApertureSize(ULONG) VRAM aperture.

Field - ulColors

ulColors(ULONG) Color depth.

Field - bBitsPerPixel

bBitsPerPixel(BYTE) Pixel depth.

Field - bBitPlanes

bBitPlanes(BYTE) Number of planes.

Field - bXCharSize

bXCharSize(BYTE) Font width.

Field - bYCharSize

bYCharSize(BYTE) Font height.

Field - usBytesPerScanLine

usBytesPerScanLine(USHORT) Number of bytes per scan line.

Field - usTextRows

usTextRows(USHORT) Number of text rows.

Field - ulPageLength

ulPageLength(ULONG) Number of bytes to save a plane.

Field - ulSavesize

ulSavesize(ULONG) Total bytes of VRAM to save.

Field - bVrtRefresh

bVrtRefresh(BYTE) Vertical refresh rate.

Field - bHrtRefresh

bHrtRefresh(BYTE) Horizontal refresh rate.

Field - bVrtPolPos

bVrtPolPos(BYTE) Vertical polarity.

Field - bHrtPolPos

bHrtPolPos(BYTE) Horizontal polarity.

Field - usScrnTop

usScrnTop(USHORT) Vertical blanking away from the top, in line counts.

Field - usScrnBottom

usScrnBottom(USHORT) Vertical blanking away from the bottom, in line counts.

Field - usScrnLeft

usScrnLeft(USHORT) Horizontal blanking away from the left, in pixel counts.

Field - usScrnRight

usScrnRight(USHORT) Horizontal blanking away from the right, in pixel counts.

Field - szColorFormat[8]

szColorFormat[8](CHAR) Color format string for true color or high-color modes.

Field - szColorWeight[8]

szColorWeight[8](CHAR) Color weight string for true color or high-color modes.

VIDEORESOURCEPACK

The VIDEORESOURCEPACK data structure contains resource information and definitions.

typedef struct _VIDEORESOURCEPACK {
  ULONG     ConsRes;    /*  An array of resource definitions. */
  ULONG     ulNumCons;  /*  Number of resources. */
} VIDEORESOURCEPACK;

typedef   VIDEORESOURCEPACK   * FAR   * PVIDEORESOURCEPACK ; 
Field - ConsRes

ConsRes(ULONG) An array of resource definitions.

Field - ulNumCons

ulNumCons(ULONG) Number of resources.

VIDEOSTATE

The VIDEOSTATE data structure receives information for the mode to be saved .

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 ; 
Field - fStateFlags

fStateFlags(ULONG) Flag indicating what to save.

STATEFLAG_REGISTERS 0x0001

STATEFLAG_CLUT 0x0002

STATEFLAG_VRAM 0x0004

STATEFLAG_FONT 0x0008

Field - miState

miState(MODEID) Contains the mode ID for the mode to be saved.

Field - pModeData

pModeData(PVOID) Pointer to set mode command sequence.

Field - ulVRAMSaveSize

ulVRAMSaveSize(ULONG) Number of bytes per page to save.

Field - pVRAM

pVRAM(PVRAMDATA) Pointer to video memory.

Field - pCLUT

pCLUT(PCLUTDATA) Pointer to palette data.

Field - pFONT

pFONT(PFONTDATA) Pointer to font data.

VMIQCI

Output packet returned by the GRADD to the caller of the VMI_CMD_ QUERYCHAININFO function.

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;
Field - ulLength

ulLength(ULONG) Size of the VMIQCI data structure, in bytes.

Field - pciHead

pciHead(#PCHAININFO) Pointer to the head of the GRADD chain.

VRAMALLOCIN

Input packet to the GHI_CMD_VRAM function.

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;
Field - ulLength

ulLength(ULONG) Size of the VRAMALLOCIN data structure, in bytes.

Field - ulFlags

ulFlags(ULONG) Flag indicating type of VRAM allocation.

Values are as follows:

VRAM_ALLOC_SHARED 0x0001
VRAM_ALLOC_RECTANGLE 0x0002
VRAM_ALLOC_STATIC 0x1000

Field - ulID

ulID(ULONG) ID required as input only on deallocation.

Field - ulFunction

ulFunction(ULONG) Requested function: allocate, deallocate, or query.

Values are as follows:

VRAM_ALLOCATE 1
VRAM_DEALLOCATE 2
VRAM_QUERY 3

Field - ulHandle

ulHandle(ULONG) Handle returned from registering.

Field - ulSize

ulSize(ULONG) Requested allocation size in bytes.

Field - ulWidth

ulWidth(ULONG) Requested allocation width in pixels.

Field - ulHeight

ulHeight(ULONG) Requested allocation height in scanlines.

VRAMALLOCOUT

Output packet returned by the GRADD to the caller of the GHI_CMD_VRAM function.

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;
Field - ulLength

ulLength(ULONG) Size of the VRAMALLOCOUT data structure, in bytes.

Field - ulFlags

ulFlags(ULONG) Flag indicating type of VRAM allocation.

Value is as follows:

VRAM_ALLOC_WORKBUFFER 0x0004
Field - ulID

ulID(ULONG) ID returned on allocation.

Field - ptlStart

ptlStart(#POINTL) X and Y location of VRAM.

Field - ulSize

ulSize(ULONG) Requested size of VRAM, in bytes.

Field - ulScanLineBytes

ulScanLineBytes(ULONG) Length of scan line, in bytes.

VRAMDATA

The VRAMDATA data structure is a pointer to video memory.

typedef BYTE VRAMDATA;

VRAMIN

Input packet to the #GHI_CMD_VRAM function.

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

Field - pIn

pIn(PVOID) Pointer to an allocate or register packet.

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

If the ulFunction field of the VRAMIN structure is set to VRAM_REGISTER or VRAM_DEGISTER, then pIn points to a #VRAMREGISTERIN data structure.

VRAMREGISTERIN

Input packet to the GHI_CMD_VRAM function via the VRAMIN data structure.

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;
Field - ulLength

ulLength(ULONG) Size of the VRAMREGISTERIN data structure, in bytes.

Field - ulHandle

ulHandle(ULONG) Handle required as input on deregister.

Field - ulFlags

ulFlags(ULONG) Flag indicating type of VRAM registration.

Values are as follows:

VRAM_REGISTER_HANDLE 0x0001
VRAM_REGISTER_VRAMONLY 0x1000

VRAMREGISTEROUT

Output packet returned by the GRADD to the caller of the GHI_CMD_VRAM function via the VRAMIN data structure.

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;
Field - ulLength

ulLength(ULONG) Size of the VRAMREGISTEROUT data structure, in bytes.

Field - ulFlags

ulFlags(ULONG) Not used at this time.

Field - ulHandle

ulHandle(ULONG) Handle returned on register.

Notices

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.