DDDR/2 - VIDEOPMI.DLL Exported Functions

Display Device Driver Reference

Chapters 16-Bit VGA Display Driver 8514/A Display Driver 32-Bit VGA Display Driver 32-Bit Super VGA Display Driver SVGA Base Video Subsystem Physical Video Device Drivers Virtual Video Device Drivers Seamless Windows Support PM Palette Management Support Distributed Console Access Facility (DCAF) DBCS Video Driver Support Installing and Configuring Display Device Drivers Graphics Test Suites Display Test Tool VIDEOCFG.DLL Exported Functions VIDEOPMI.DLL Exported Functions VIDEO Protect-Mode Interface Appendixes Data Types S3 Display Driver OS/2 Version Compatibility Considerations‎ Glossary Notices

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

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 VIDEOMODEINFOstructures to desired values, even if they are the same as the mode ID values; otherwise, some mode parameters may not be set correctly.

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

Supported Functions

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

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

VIDEOPMI32Request

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_ADAPTERshould be set to sizeof(ADAPTERINFO) and sizeof(VIDEOMODEINFO). This way, VIDEOPMI can handle callers built from different sizes of ADAPTERINFOVIDEOMODEINFO 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_LOADPMIFILE

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 Adapter field in VIDEO_ADAPTER will be filled with the information from the .PMI file.

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

PMIREQUEST_SETMODE

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 pOutpoints is the maximum size of the hardware command list, which is obtained by the PMIREQUEST_QUERYMAXMODELISTSIZE function.

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

PMIREQUEST_SETMEMORYIOADDRESS

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_LOCKREGISTERS

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

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_UNLOCKREGISTERS

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_CLEANUP

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_SAVESTATE

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 fStateFlagsand 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_RESTORESTATE

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_GETBANK

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_SETBANK

PMIREQUEST_SETBANK sets 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_GETCLUT

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_SETCLUT

PMIREQUEST_SETCLUT sets 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_GETPALETTE

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_SETPALETTE

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_GETFONT

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_SETFONT

PMIREQUEST_SETFONT sets 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_TUNEDISPLAY

PMIREQUEST_TUNEDISPLAY executes 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.

PMIREQUEST_IDENTIFYADAPTER

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_QUERYMAXMODEENTRIES

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

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.

PMIREQUEST_QUERYMAXMODELISTSIZE

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_QUERYMODEINFODATA

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_QUERYMAXTRAPENTRIES

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_QUERYTRAPLISTDATA

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_QUERYMODEHRDWRLIST

PMIREQUEST_QUERYMODEHRDWRLIST returns the SetMode hardware command list of the passed mode ID.

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

PMIREQUEST_SOFTWAREINT

PMIREQUEST_SOFTWAREINT initializes 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_UNLOADPMIFILE

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 PMIFILE                 "\\os2\\svgadata.pmi"
#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 */
   rc = pfnPMIRequest (&AdapterInstance,
                       PMIREQUEST_UNLOCKREGISTERS,
                       NULL,
                       NULL);

   /*
    * 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;
}