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 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 for more information on the PMI subsystem.

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

The and  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 and  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
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
Description:
 * Syntax

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

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 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  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 for format and syntax information.

PMIREQUEST_CLEANUP
Description:
 * Syntax

PMIREQUEST_CLEANUP cleans up the settings in extended registers.
 * 1) include 

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 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
Description:
 * Syntax

PMIREQUEST_GETBANK gets current bank.
 * 1) include 

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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_GETBANK.
 * pIn(PVOID) - input NULL.
 * pOut(PVOID) - output Pointer to a 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 data structure. miBank in BANKDATA is the current mode ID.

PMIREQUEST_GETCLUT
Description:
 * Syntax

PMIREQUEST_GETCLUT gets a copy of Color Lookup Table from hardware.
 * 1) include 

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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_GETCLUT.
 * pIn(PVOID) - input NULL.
 * pOut(PVOID) - output Pointer to a data structure.
 * rc(APIRET) - returns Return codes.

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

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.
 * Remarks

PMIREQUEST_GETFONT
Description:
 * Syntax

PMIREQUEST_GETFONT reads current font from video memory.


 * 1) include 

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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_GETFONT.
 * pIn(PVOID) - input NULL.
 * pOut(PVOID) - output Pointer to a data structure.
 * rc(APIRET) - returns Return codes.

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

ulCharCount in the 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.
 * Remarks

PMIREQUEST_GETPALETTE
Description:
 * Syntax

PMIREQUEST_GETPALETTE gets a copy of palette registers from hardware.
 * 1) include 

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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_GETPALETTE.
 * pInput(PVOID) - input NULL.
 * pOut(PVOID) - output Pointer to a data structure.
 * rc(APIRET) - returns Return codes.

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

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

PMIREQUEST_IDENTIFYADAPTER
Description:
 * Syntax

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


 * 1) include 

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 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, has to be executed.

PMIREQUEST_LOADPMIFILE
Description: PMIREQUEST_LOADPMIFILE loads the specified .PMI file.
 * Syntax
 * 1) include 

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

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

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

PMIREQUEST_LOCKREGISTERS
Description:
 * Syntax

PMIREQUEST_LOCKREGISTERS locks extended registers.


 * 1) include 

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

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

PMIREQUEST_QUERYMAXMODEENTRIES
Description: PMIREQUEST_QUERYMAXMODEENTRIES returns the number of mode entries in the .PMI file.
 * Syntax
 * 1) include 

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 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
Description:
 * Syntax

PMIREQUEST_QUERYMAXMODELISTSIZE returns maximum size required to save a SetMode command list.
 * 1) include 

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

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

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
Description:
 * Syntax

PMIREQUEST_QUERYMAXTRAPENTRIES returns the maximum number of traplist entries in the [TRAPREGS] section of the .PMI file.


 * 1) include 

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

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.
 * Remarks

PMIREQUEST_QUERYMODEHRDWRLIST
Description:
 * Syntax

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


 * 1) include 

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
Description:
 * Syntax

PMIREQUEST_QUERYMODEINFODATA copies the PMI mode table to the caller.


 * 1) include 

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

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

PMIREQUEST_QUERYTRAPLISTDATA
Description:
 * Syntax

PMIREQUEST_QUERYTRAPLISTDATA returns an array of trap register information structures in the [TRAPREG] section of the .PMI file.
 * 1) include 

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

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

PMIREQUEST_RESTORESTATE
Description:
 * Syntax

PMIREQUEST_RESTORESTATE restores the state of the hardware from supplied data.


 * 1) include 

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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_RESTORESTATE.
 * pIn(PVOID) - input Pointer to a data structure.
 * pOut(PVOID) - output NULL.
 * rc(APIRET) - returns Return codes.

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

See.
 * Remarks

PMIREQUEST_SAVESTATE
Description:
 * Syntax

PMIREQUEST_SAVESTATE saves partial or complete state of the hardware.


 * 1) 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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_SAVESTATE.
 * pIn(PVOID) - input NULL.
 * pOut(PVOID) - output Pointer to a data structure.
 * rc(APIRET) - returns Return codes.

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

miState in the data structure is the current mode ID in.
 * Remarks

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.


 * 1) 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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_SETBANK.
 * pIn(PVOID) - input Pointer to a data structure.
 * pOut(PVOID) - output NULL.
 * rc(APIRET) - returns Return codes.

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

See PMIREQUEST_GETBANK.
 * Remarks

Before the [SETBANK] section in the .PMI file is executed, r0 is set to ulBank. in the 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.


 * 1) 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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_SETCLUT.
 * pIn(PVOID) - input Pointer to a data structure.
 * pOut(PVOID) - output NULL.
 * rc(APIRET) - returns Return codes.

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

See.
 * Remarks

PMIREQUEST_SETFONT
Description:

PMIREQUEST_SETFONTsets font to that supplied.


 * 1) 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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_SETFONT.
 * pIn(PVOID) - input Pointer to a 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.


 * 1) 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 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.

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

This function is also called implicitly when the 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.


 * 1) 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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMODE.
 * pIn(PVOID) - input Pointer to mode ID from the 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.

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.
 * Remarks

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


 * 1) 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 data structure.
 * ulFunction(ULONG) - input Set equal to PMIREQUEST_SETPALETTE.
 * pIn(PVOID) - input Pointer to a 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
Description:
 * Syntax

PMIREQUEST_SOFTWAREINTinitializes and/or executes a real-mode software interrupt.


 * 1) 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 data structure. INITVDM defines how the worker routine will be initialized; can be NULL.

pOut(PVOID) - output Pointer to an 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.

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.
 * Remarks

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.


 * 1) 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 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.


 * 1) 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 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.

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

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.


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

pAdapter(PVIDEO_ADAPTER) - input Pointer to a data structure.
 * Parameters

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.

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

Code Sample
The following code sample shows how to load the .PMI file, set up the mode table, and set the graphics mode.
 * 1) include <os2.h>
 * 2) include <svgadefs.h>

/* * Adapter instance. */ VIDEO_ADAPTER AdapterInstance;
 * 1) define DLLNAME                "videopmi"
 * 2) define REQUEST_ENTRYPOINT     "VIDEOPMI32Request"
 * 3) define FAIL_LENGTH            256
 * 4) define PMIFILE                "svgadata.pmi"

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