Display Device Driver Reference for OS/2

By IBM

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

About this Book

The device drivers described in the Display Device Driver Reference provide information and code to enable you to start developing your own OS/2 display device drivers.

Note: To verify that your driver signature is unique, contact the IBM Driver Development Support Center (DDSC) Bulletin Board System (the DUDE) on (407) 982-4239.

How This Book Is Organized

#16-Bit VGA Display Driver This chapter presents the 16-bit VGA driver, a dynamic link library that converts device-independent graphics calls into VGA-specific device instructions.

#8514/A Display Driver This chapter covers the differences between the 16- bit VGA display driver and the 8514.

#32-Bit VGA Display Driver This chapter presents the 32-bit VGA driver, contained in two Dynamic Link Libraries: one hardware-independent, the other hardware-dependent.

Also described are the responsibilities of the driver to the Presentation Manager graphics engine, which loads the Dynamic Link Libraries for the display driver.

#32-Bit Super VGA Display Driver This chapter discusses the differences between the VGA and the Super VGA device drivers.

#SVGA Base Video Subsystem This chapter has been rewritten and now describes how the SVGA base video subsystem handles all non-graphical primitive video device functions. It also describes how to handle the mode set function.

#Physical Video Device Drivers This chapter describes the Video Device handlers, and lists functions used to read and write to the EGA registers. The DPRINTF Print Formatting Package information has been moved from the end of SVGA Base Video Subsystem to the end of this chapter.

#Virtual Video Device Drivers This chapter describes the design, implementation, and interfaces of virtual video device drivers, including the virtualization and windowing of DOS sessions on an OS/2 platform. A virtual video device driver is required when it is necessary for multiple DOS sessions to share one or more video devices. "Super VGA Virtual Video Device Driver Support" describes how to add support for an Super VGA capable chip set.

#Seamless Windows Support This chapter provides information on how to execute Windows applications in one or more windows on the OS/2 desktop, and includes a Checklist for Palette Management Support in seamless display drivers. It also includes an overview of the Distributed Console Access Facility (DCAF), which provides remote console functions.

#PM Palette Management Support This chapter describes Presentation Manager Palette Management, special code that enables applications to specify exact color values for a drawing or image on a particular device. The application's color requests are mapped as closely as possible to the actual colors available in the device's hardware color palette. When possible, the hardware palette is modified to exactly provide the requested RGB values.

#Distributed Console Access Facility (DCAF) This chapter discusses the design and purpose of DCAF within the OS/2, DOS and WINDOWS environments.

#DBCS Video Driver Support This chapter describes double-byte character set (DBCS) video driver support.

#Installing and Configuring Display Device Drivers This chapter describes the OS/2 display driver installation utility program (DSPINSTL.EXE), which provides all the facilities for installing and configuring the IBM Operating System/2 and Presentation Manager display device drivers. This installation utility program also can install and configure WIN-OS/2 (both full-screen and windowed) display drivers, and can install base video service (VIO) and DOS virtual device drivers. A sample DSPINSTL Script is included to assist you in SVGA BBS installations.

#Graphics Test Suites This chapter describes test suites that are designed for System Verification Test and Function Verification Test.

#Display Test ToolThis chapter describes the Display Test Tool, a Presentation Manager application that enables the user to select one or more display tests and execute them.

#VIDEOCFG.DLL Exported FunctionsThis chapter describes the VIDEOCFG syntax as working samples, adhering to the style of the "C" programming language. The VIDEOCFG.DLL exported functions, formerly in Chapter 5, are now in this revamped and revised chapter. Also covered is a section on a Generic Video Configuration Interface.

#VIDEOPMI.DLL Exported Functions This chapter presents the VIDEOPMI syntax as working samples, adhering to the style of the "C" programming language.

#VIDEO Protect-Mode Interface This chapter discusses the format and syntax used to define the necessary data for setting a video mode while in OS/2 protect mode, and to enable virtualization in multiple DOS sessions. The objective is to achieve a protect-mode interface to Super VGA hardware.

Appendixes

Appendix A. OS/2 Version Compatibility Considerations This table describes information added to or changed since the availability of OS/2 Warp, Version 3 in terms of version compatibility.

Appendix B. GRE Function Tests (by Function Name) This appendix consists of a table that lists the various GRE function tests, organized by function name.

Appendix C. GRE Function Tests (by Test-Case Name) This appendix consists of a table that lists the various GRE function tests, organized by test-case name.

Appendix D. Graphics Engine Functions This appendix consists of several tables, each of which lists a different type of graphics engine function.

Appendix E. DTT Script File Command Summary This appendix contains a summary of the commands used in a DTT script file.

Appendix F. DTT Command-Line Options Summary This appendix contains a summary of the command-line options.

Appendix G. Sample DTT Script File This appendix contains the code for a sample script file.

Appendix H. Glyph Codes This appendix contains a table that lists the reserved glyph codes and the relationship between glyph pattern and glyph code ID in code page 932.

Appendix I. S3 Display Driver This appendix contains a discussion on the architecture of the S3 Display Device Driver and covers the portions of the driver that require modification in order to support other graphics accelerator chip sets.

Appendix J. S3.DSP (Sample File for Installation and Configuration) This appendix consists of a sample S3 display (DSP) file that contains DSPINSTL installation and configuration commands.

Appendix K. Deciphering File Names in the S3 Driver This appendix consists of a list of S3 file names with an explanation of how the file names are derived.

Appendix L. Color Palette Default Values This appendix contains tables listing the default values for VGA (4bpp), XGA (8bpp) and XGA (16bpp) color palettes.
Miscellaneous

A glossary and 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 Graphics Adapter Device Driver Reference
�The MMPM/2 Device Driver Reference (Multimedia)
To order the DDK call:

/----------------------------------------------------------------\
|U.S.A.:             |1-800-633-8266       |                     |
|--------------------+---------------------+---------------------|
|Canada:             |1-800-561-5293       |                     |
|--------------------+---------------------+---------------------|
|When calling from   |� English            |(+45) 48101500       |
|Europe, the Middle  |� French             |(+45) 48101200       |
|East, or Africa, the|� Italian            |(+45) 48101600       |
|number depends on   |� German             |(+45) 48101000       |
|the language you use|� Spanish            |(+45) 48101100       |
|to place the order: |� Dutch              |(+45) 48101400       |
|                    |� Danish             |(+45) 48101300       |
|                    |� Finish             |(+45) 48101650       |
|                    |� Swedish            |(+45) 48101150       |
|                    |� Norwegian          |(+45) 48101250       |
|                    |� FAX                |(+45) 48142207       |
|--------------------+---------------------+---------------------|
|When ordering from  |� Bolivia            |    02-35 1840       |
|Latin America or    |� Columbia           |   01-257-0111       |
|South America, the  |� Dominican Republic |      566-5161       |
|number depends on   |� El Salvador        |    02-98 5011       |
|the country from    |� Honduras           |       32-2319       |
|which you are       |� Paraguay           |   021-444 094       |
|calling:            |� Urugruay           |    02-923 617       |
|                    |� Chile              |   02-633-4400       |
|                    |� Costa Rica         |      223-6222       |
|                    |� Ecuador            |    02-56 5100       |
|                    |� Guatemala          |    02-31 5859       |
|                    |� Panama             |    02-639 977       |
|                    |� Peru               |   014-36 6345       |
|                    |� Venezuela          |   02-908-8901       |
|                    |� Argentina          |   01-313-0014       |
|--------------------+---------------------+---------------------|
|To order from Asia/ |� All except Japan   |(61) 2-354-7684      |
|Pacific:            |� Japan              |(81) 3-3495-2045(Fax)|
|                    |                     |Fax request to:      |
|                    |                     |DAP-J, IBM Japan     |
|--------------------+---------------------+---------------------|
|To order from SE    |(021) 800-6120(Voice)|                     |
|Brazil:             |(021) 800-6936(Fax)  |                     |
|--------------------+---------------------+---------------------|
|To order from       |� Mexico City        |627-2444             |
|Mexico:             |� Country            |91-800-00639         |
\----------------------------------------------------------------/

What's New

There were no major changes to this release of the Display Device driver Reference.

The table that appears in #OS/2 Version Compatibility Considerations identifies any compatibility issues associated with updates made to this book.

Try Our New Improved Model!

Are you tired of device-driving late into the night? You may want to consider using the new GRADD (short for GRaphics Adapter Device Driver) model to write your next video driver on OS/2 Warp, Beta Version 99.99.

The GRADD driver model, provided on this DDK CD, requires 10 times less lines of code than previously required to write an OS/2 video device driver. Some of the advantages incorporated in the GRADD model include the following:

• Simplifies development effort
• Reduces cycle time
• Allows incremental development; requires fewer mandatory functions
• Both This eliminates the need to write a seamless WinOS/2 driver.

If you are writing new video drivers for OS/2 Warp, Beta Version 99.99, you can take advantage of these development savings. Refer to the GRADD Device Driver Reference and code samples on this CD to get started today.

16-Bit VGA Display Driver

The 16-bit VGA display driver provides hardware independence to the application code that performs I/O to a display device. An application program need not be concerned with the hardware-specific requirements of the adapter card.

Overview

The 16-bit VGA display driver is a set of special-purpose I/O routines, operating at privilege level 2 (Ring 2). This driver, along with other presentation drivers, provides the link between the internal interface to display devices and the OS/2* interfaces to the kernel device drivers at Ring 0 (the highest privilege level) and the screen.

When an application needs to perform I/O to the screen, it calls a system DLL, which in turn calls the Presentation Manager* (PM) graphics engine, contained in PMGRE.DLL. The graphics engine then calls the display driver, contained in DISPLAY.DLL. The display driver can then access the adapter hardware directly through memory-mapped I/O, or can call the OS/2 kernel by way of the standard driver mechanism to perform the I/O.

When the display driver is loaded, the graphics engine allocates an internal dispatch table to process the functions. The dispatch table is an array of pointers to function-handling routines. The low-order byte of the function number identifies the member of the array that contains the pointer for the function. The first time that the display driver is called at its OS2_PM_DRV_ENABLE entry point, it replaces the graphics engine pointers in the dispatch table with pointers to the corresponding functions supported by the display driver. Some of the pointer replacements are mandatory; others are optional.

The graphics engine pointer to the dispatch table is passed to the display driver by way of a FillLogicalDeviceBlock call.

16-Bit VGA Architecture

The 16-bit VGA display driver consists of one component (DISPLAY.DLL). DISPLAY.DLL contains all entry points-both device-dependent and device-independent functions (including seamless support) - that the graphics engine calls.

All the fonts, cursors, and bit maps are included in a binary resource file (.RES) that is built and added to the driver by the resource compiler.

Functions

The following is a list of the functions in the graphics engine that are hooked by the 16-bit VGA display driver.

• Graphics Engine Attribute Functions
• Graphics Engine AVIO Functions
• Graphics Engine Bit-Map Functions
• Graphics Engine Color Table Functions
• Graphics Engine Device Functions
• Graphics Engine Escape Functions
• Graphics Engine Line Functions
• Graphics Engine Marker Functions
• Graphics Engine Miscellaneous Device Functions
• Graphics Engine Miscellaneous Screen Functions
• Graphics Engine Query Functions
• Graphics Engine String Functions

For more information about these functions and their descriptions, see #Graphics Engine Functions.

Debugging Support

Debugging support is provided through a macro, color_puts<>, contained in seamless.inc. This macro sends data through the kernel debugger port to a serial port. The kernel debugger and its related documentation is provided with the OS/2 2.X Toolkit. The input for the macro is foreground color, background color <string>, as follows:

ifdef FIREWALLS

        color_puts  BLUE,BLACK,< This message will be output to
                                        the debugging terminal >

endif ;FIREWALLS

Current debugging messages in the code are placed inside the conditional compilation ifdef FIREWALLS. This value is defined when compiling the debug version of the driver. Another example of this macro can be found in init.asm.

The BITBLT Function

One of the most important functions used in Presentation Manager is BITBLT (Bit Block Logical Transfer), which draws the rectangles that make up the PM Desktop, icons, and other bit maps. BITBLT is similar to a byte-block move operation except that blocks are moved on bit boundaries instead of byte boundaries. This could require that the bits of the source be aligned to the bits of the target (phase alignment). An example is moving all bits of a bit map left two pels. Once the bits are aligned, they are combined with an optional pattern and the target, as specified by the raster operation (ROP).

For arbitrary BLT processing, code is derived dynamically and written to a data segment. This segment is then aliased to a code segment, and executed. BITBLT functionality is the same for 16-bit VGA, 32-bit VGA, and 32-bit Super VGA.

For detailed information on BITBLT functionality, see VGA32\IBMDEV32\BITBLT .ASM and VGA32\IBMDEV32\CBLT.ASM.

The innermost functionality of BITBLT can be pictured as follows:

Bytes are fetched from a source. Color conversion is applied if the source and target are of different color formats. (See Color Conversionand XGA Support for Palette Management - Dithering and BITBLTingfor detailed information about color conversion.) The source bits then are aligned with the target. Bits from a previous phase alignment and the current phase alignment are combined to form one byte's worth of data. The unused bits from the phase alignment are saved for the next phase alignment.

The ROP is applied against the source bits, pattern, and target, as needed; the result replaces the target byte.

Overlapping BLTs

The following illustrations show possible overlaps that can occur when a BLT is performed. Since the source and target can overlap, the order in which bytes are processed must be chosen with care. If the order is wrong, a byte of the source might be overwritten (as a target) before the byte is used as a source. (You might remember propagating spaces through a field on the IBM* 360s and 370s).

In the following figures, S is the source, D is the target, and x is the corner from where the first byte will be fetched. The comments (on the right) tell in which directions (X and Y) the BLT must be performed to prevent the overwriting of a source byte before it is used as a source. The possible cases of overlap are as follows:

1. Disjointed (not special cased)
2. Identical (not special cased)
3. Overlapping

The following four examples are degenerate cases (along with identical and disjoint) and the directions are as shown:

Phase Relationship Between Source and Target Bit Maps

Since BLTs are performed on bit boundaries instead of byte boundaries, rotations of the source bit map bytes might have to be performed. Source data is always rotated to align with the target. The following describes how the phase relationship is determined and how to start the BLT. (Some phase relationships require a different number of initial source bit map fetches to acquire enough bits to satisfy the first store.)

The number of bytes separating the source and target in the following examples is irrelevant; only the relationship of the bits within the bytes is important. Saved and used masks are applied after rotating the source byte.

Saved bits mask A mask that gives the bit that must be carried over to the next byte BLTed.

Used bits mask A mask that gives the bits that are to be used for the current byte BLTed.

Old unused bits Bits that were not used in the last byte BLTed and, therefore, bits that must be used for the current byte BLTed.

First byte mask A mask that is used to mask the bits (of the very first byte BLTed) that are to be altered. The complement of this mask gives the bits of the target byte that are to remain unaltered.

The BLT is started based on the cases of overlap as previously specified.

For box cases 3, 4, 5, 6, 8, disjoint, and same (as shown previously), BLTs start at the left, stepping right. Calculations are based on the left side of the source and target rectangles. The starting mask is based on the leftmost byte of the target; the ending mask is based on the rightmost byte of the target, as follows:

For box cases 1, 2, and 7, BLT starting at the right, stepping left. Calculations are performed on the right side of the source and target rectangles. The starting mask is based on the rightmost byte of the target , and the ending mask is based on the leftmost byte of the target.

Raster Operation Codes And Definitions

Each raster operation code represents a Boolean operation in which the source, currently selected brush, and target are combined.

The operands used in the operations are:

S Source bit map
P Currently selected brush (also called pattern)
D Target bit map

The Boolean operators used in these operations are:

o Bitwise OR
x Bitwise Exclusive OR
a Bitwise AND
n Bitwise NOT (inverse)

All Boolean operations are presented in reverse Polish notation. For example, the operation:

PSo

replaces the target with a combination of the source and brush.

The operation:

DPSoo

combines the source and brush with the target. Because there are alternate spellings of the same function, although a particular spelling might not be in the list, an equivalent form will be.

Each raster operation code is an 8-bit integer value that represents the result of the Boolean operation on predefined brush, source, and target values. For example, the operation indexes for the PSoand DPSoooperations are:

In this case, PSohas the operation index 00FC (read from the bottom up); DPSoohas the index 00FE.

Color Conversion

Color conversion applies when the source and target color formats are not the same. Color conversion takes place prior to any mix mode. For additional information, see XGA Support for Palette Management - Dithering and BITBLTing.

�Mono � Color Conversion

Applied when the source is monochrome and the target is color.

When going from monochrome to color, 1 bits are converted to the target image foreground color, and 0 bits are converted to the target image background color.

�Color � Mono Conversion

Applied when the source is color and the target is monochrome.

When going from color to monochrome, all pels that match the passed background IPC (obba_bgndIPC) are converted to the target image background color; all other pels are converted to the target image foreground color.

8514/A Display Driver

The IBM 8514/A display driver shares its basic functionality with the 16- bit VGA display driver. See 16-Bit VGA Display Driverfor details about privilege levels, graphics engine interface, graphics engine functions, dispatch tables, and debugging. For the most part, these topics, as covered in that chapter, apply also to the 8514/A display driver.

Overview

This chapter covers the differences between the 16-bit VGA display driver and the 8514/A display driver, followed by 8514/A device-specific programming information.

Operating Modes

The 8514/A graphics adapter operates in the following modes:

• Video-graphics array (VGA)

This is the power-on mode; the functionality of the 16-bit VGA display driver is available.

• Advanced-function

This mode provides a programming interface for the adapter. The primary advantage of the 8514/A display driver over the 16-bit VGA display driver is that the advanced-mode adapter interface handles much of the hardware programming for you. Instead of programming directly into the bit-plane memory, the adapter provides an interface supporting most of the required display functions.

Both modes of operation are selectable under program control.

Macros for Utilizing Available Hardware Capabilities

The 8514/A display driver includes a set of macros to access the adapter interface. When called by the driver, through the entry points, the interface provides a set of functions to utilize the hardware capabilities of the display adapter. Each of the macros is addressed in detail in the sections that follow.

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitIO                                                |
|                                                          |
\----------------------------------------------------------/

Tests an I/O port for a particular value, as follows:

Port The port number to be polled. If not present, it is assumed that the port number is already loaded into the DX register.

Sense The sense of jump needed to remain in the polling loop.

Mask If present, the value that will be ANDed with the polled contents of Port.

EquVal If present, the value that must match the Portcontents, after masking (if Maskis present).

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitIO macro Port,Sense,Mask,EquVal,SaveRegs

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQIN                                               |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A graphics adapter output queue to contain available data.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQIN macro SaveRegs

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQOUT                                              |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A graphics adapter input queue to be ready to accept data.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQOUT macro SaveRegs

/--- MACRO ------------------------------------------------\
|                                                          |
|    ChkERRSTATUS                                          |
|                                                          |
\----------------------------------------------------------/

Check for the underrun or overrun state after execution of a variable data command to the 8514/A graphics adapter.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

ChkERRSTATUS macro SaveRegs

/--- MACRO ------------------------------------------------\
|                                                          |
|    WaitQ                                                 |
|                                                          |
\----------------------------------------------------------/

Waits for the 8514/A adapter input queue to have a minimum number of words of free space. The queue may contain up to eight words. The number of words still to be dequeued can be ascertained at any time.

MinQSpaceIf at least this many words are available in the queue, fall out of wait loop. This parameter must be present.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

WaitQ macro MinQSpace,SaveRegs

/--- MACRO ------------------------------------------------\
|                                                          |
|    outwQ                                                 |
|                                                          |
\----------------------------------------------------------/

Outputs a word value to the 8514/A input queue.

Port The port number for which written data will be queued. If this parameter is not present, it will be assumed that the port number is already loaded into the DX register.

Data The immediate or indirect specification of data that will be output to Port. If this parameter is not present, it will be assumed that the data is already loaded into the AX register.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

outwQ macro Port,Data,SaveRegs

/--- MACRO ------------------------------------------------\
|                                                          |
|    outbQ                                                 |
|                                                          |
\----------------------------------------------------------/

Outputs a byte value to the 8514/A input queue. This macro differs from outwQin that it is assumed that only the low half of the AX register needs to be loaded. A slight saving in code size is achieved thereby.

Port A port number for which written data will be queued. If this parameter is not present, it will be assumed that the port number is already loaded into the DX register.

Data An immediate or indirect specification of data that will be output to Port. If this parameter is not present, it will be assumed that the data is already loaded into the AX register.

SaveRegs This parameter is present if registers used in polling are to be saved and restored. The actual content of this parameter is ignored; only its presence matters.

outbQ macro Port,Data,SaveRegs

Bit-Plane Model

The bit-plane memory in the adapter is arranged in planes of 1024 x 1024 bits. The displayed data is taken from the low 1024 x 768 or 640 x 480 bits . The undisplayed bit-plane memory is used by the adapter as auxiliary storage for functions, like area-fill working storage, as a cache for programmable character sets and marker drawing.

The number of planes available depends on the adapter mode and the amount of video RAM installed, up to a maximum of 32 planes. They are numbered from 0 to 31, with plane 0 associated with bit 0 of the color index. The 8514 display driver provides the following memory mapping for high- resolution mode:

     /--------------------------------------------------------\
     |                                                        |
     |                                                        |
     |                   onscreen area                        |
     |                                                        |
     |                                                        |
     | (32x32)   64      128      196                         |
     | (40x40)   80      160      240                         |
     | (64x64)  128      256                                  |
 768 |--------------------------------------------------------|
     | ptr   | ptr   | ptr   | ptr   | work  |                |
     | and   | xor   | save  | color | area  | SaveScreenBits |
     | mask  | mask  | area  | bitmp |       | area           |
 848 |--------------------------------------------------------|
     |                      Pattern Cache                     |
 864 |--------------------------------------------------------|
     |                                                        |
     |                                                        |
     |     Font storage area and 3-op BLT temporary space     |
     |                                                        |
     |                                                        |
1023 \--------------------------------------------------------/

32-Bit VGA Display Driver

The 32-bit VGA display driver, like all display drivers, provides hardware independence for OS/2 application programs needing to perform I/O to a display device.

Overview

The 32-bit VGA display driver is contained in a pair of DLLs, which are divided into hardware-dependent and hardware-independent sections. When an application needs to perform I/O to a display device, it calls a system DLL , which in turn calls the OS/2 Presentation Manager graphics engine, PMGRE. DLL. PMGRE is the component that loads the display-driver DLLs.

The display driver has certain responsibilities to the graphics engine (GRE ). Specifically, there are a number of entry points (external functions) in the graphics engine that the display driver is required to hook and support . There are other entry points in the graphics engine that can be optionally hooked by the display driver, when required, for special processing.

Each entry point is a 32-bit pointer to a specific routine in the graphics engine. The graphics engine uses a dispatch tableto call the entry points within the display driver. Essentially, the dispatch table is a block of memory, allocated by the graphics engine, for the containment of entry points for use by a display driver. The graphics engine then refers to the dispatch table anytime it calls a function in the display driver.

Initially, however, the dispatch table entries point back to routines in the graphics engine. Therefore, the display driver must replace some of the existing pointers with new pointers that point to corresponding routines in the display driver. This action is mandatory for some routines, optional for others. The display driver hooks the entry points in the dispatch table the first time the driver is called at its OS2_PM_DRV_ENABLE entry point for the first subfunction, FillLogicalDeviceBlock.

The ring level(privilege level) of all the entries in the dispatch table can be selected by exporting a table called OS2_PM_DRV_RING_LEVELS. If this table is not exported, all 32-bit functions are dispatched as conforming to Ring 2.

32-Bit VGA Display Driver Architecture

The 32-bit VGA display driver consists of two fundamental components. They are:

• IBMVGA32.DLL
• IBMDEV32.DLL.

This architecture was chosen to make the driver more easily portable among various hardware video cards. Super VGA support is provided by using this architecture.

The device-independent functions of the driver are contained in the base DLL, IBMVGA32.DLL. This DLL satisfies entry points common to different hardware cards. The device-specific functions are contained in the device- specific DLL, IBMDEV32.DLL. This DLL satisfies entry points specific to video adapter cards. The graphics engine calls entry points in both DLLs. Also, the two DLLs call exported entry points within each other. In order to port this driver to other video cards, you must write code that supplies the functionality for the entry points in the device-specific DLL. Fonts are now built in a separate DLL, DSPRES.DLL.

DSPRES.DLL is the dynamic link library that supplies the resources such as fonts, pointers, etc. to the display driver. DSPRES.DLL includes resources for both high resolution and low resolution. The IBMDEV32.DLL exports the pointers to the structures for FONT_RES, defFontChar, and defFontMarker, which have the resource IDs of the necessary resources. IBMVGA32.DLL loads DSPRES.DLL, gets the resources with DosGetResource (using the resource ID in defFontXX imported from IBMDEV32.DLL) and saves the pointer to the resources in defFontXX.

The architecture of the 32-bit VGA display driver is illustrated in the following figure: [Artwork not shown]

Base DLL Function Imports

The GRE uses entry points in both IBMVGA32.DLL and IBMDEV32.DLL. IBMVGA32. DLL also calls entry points in IBMDEV32.DLL. The device-specific DLL contains a number of entry points required by the GRE and a number of device-specific API calls.

These device-specific API calls supply the functionality expected by the base DLL. In order to port this driver to other video cards, the developer must write code which supplies the functionality for the entry points in the device-specific API. These routines are discussed in the following pages.

Note:All functions in the base and device-specific DLLs run at Ring 2 with the exception of QueryDeviceBitmaps, QueryDeviceCaps, QueryHardcopyCaps,and QueryDevResource2, which run at Ring 3.

The following functions are imported by the base DLL from the device-specific DLL:

init_hw_regs =IBMDEV32.4000
rgb_to_ipc =IBMDEV32.4004
physical_enable =IBMDEV32.4011
physical_disable =IBMDEV32.4012
device_specific_init =IBMDEV32.4013
device_specific_post_init =IBMDEV32.4014
copy_bits_to_pattern =IBMDEV32.4017
PolyShortLine =IBMDEV32.4023
SaveScreenBits =IBMDEV32.4026
PolyScanline =IBMDEV32.4028
RestoreScreenBits =IBMDEV32.4030
Pixel =IBMDEV32.4034
far_exclude =IBMDEV32.4037
far_unexclude =IBMDEV32.4038
SetColorCursor =IBMDEV32.4039
DeviceSetCursor =IBMDEV32.4040
SetScreenBusy =IBMDEV32.4041
CharRect =IBMDEV32.4200
CharStr =IBMDEV32.4201
DeviceSetAVIOFont2 =IBMDEV32.4202
ScrollRect =IBMDEV32.4204
UpdateCursor =IBMDEV32.4205
DeviceSeamlessInit =IBMDEV32.4206
deselect_bitmap =IBMDEV32.4301
save_bitmap =IBMDEV32.4302
DeviceCreateBitmap =IBMDEV32.4303
DeviceSelectBitmap =IBMDEV32.4304
DeviceDeleteBitmap =IBMDEV32.4305
GetBitmapBits =IBMDEV32.4306
SetBitmapBits =IBMDEV32.4307
DrawLinesInPath =IBMDEV32.4308
DisJointLines =IBMDEV32.4309
PolyLine =IBMDEV32.4310
GetCurrentPosition =IBMDEV32.4311
SetCurrentPosition =IBMDEV32.4312
CharString =IBMDEV32.4313
Drawbits =IBMDEV32.4314
ImageData =IBMDEV32.4315
CharMarkerPos =IBMDEV32.4316
CharStringPos =IBMDEV32.4317
Bitblt =IBMDEV32.4318
DrawBorder =IBMDEV32.4319
PolyMarker =IBMDEV32.4320
alloc_brush =IBMDEV32.5201
free_brush =IBMDEV32.5202
copy_brush =IBMDEV32.5203
QueryRealColors =IBMDEV32.5300
QueryColorIndex =IBMDEV32.5301
QueryNearestColor =IBMDEV32.5302
QueryColorData =IBMDEV32.5303
UnrealizeColorTable =IBMDEV32.5304
RealizeColorTable =IBMDEV32.5305
deselect_lct =IBMDEV32.5306
QueryLogColorTable =IBMDEV32.5307
save_lct =IBMDEV32.5308
QueryRGBColor =IBMDEV32.5309
CreateLogColorTable =IBMDEV32.5310
PropagateSysClrChange =IBMDEV32.5311
MakeColorsValid =IBMDEV32.5312
MakeBrushValid =IBMDEV32.5313
MakePassedColorsValid =IBMDEV32.5314
device_enter_driver =IBMDEV32.5315
ResetLogColorTable =IBMDEV32.5316

Base DLL Function Exports

The following functions are exported by the base DLL. Exports beyond @1001 are also imported by the device-specific DLL.

MoveCursorDescription @103
OS2_PM_DRV_ENABLE @1 RESIDENTNAME
OS2_PM_DRV_ENABLE_LEVELS @998
OS2_PM_DRV_RING_LEVELS @999
CheckCursor @104
SEAMLESSTERMINATE @350 RESIDENTNAME 2
private_alloc @1000
private_free @1001
enter_driver @1002
leave_driver @1003
save_that_error @1004
perform_rip @1005
ddc_validate @1006
enter_driver_sem @1007
GetVRAMR0Pointer @1008
ring3_CriticalError @1010
InnerAccumulateBounds @1014
correlate_for_point_si @1016
enter_driver_sem_only @1017
leave_driver_sem_only @1018
do_sl_corr @1019
check_sem @1029
get_clip_rects @1031
ShortlineCorrelate @1032
far_clip_line @1033
ComputeShortlineBounds @1034
save_that_warning @1042
Force_Valid_CP @1202
Vio32SetState @3000
Vio32SetMode @3001
free_bm @4100
alloc_bm @4101
AllocMem @4102
FreeMem @4103
recalc_correlate_rect @4104
pfnDefDisJointLines @4105
pfnDefPolyLine @4106
pfnDefSetCurrentPosition @4107
convert_world_screen @4108
convert_screen_world @4109
pfnDefRectVisible @4110
pfnDefCharStringPos @4111
pfnDefBitblt @4112
pfnDefGetClipRects @4113
pfnDefQueryTextBox @4114
double_enter_driver @4115
validate_rectl @4116
intersect_rcl @4117
intersect_with_corr @4118
AccumBoundsInDevCoords @4119
pfnDefDrawbits @4120
convert_rectl @4121
pfnDefPolyMarker @4122

Device-Specific DLL Function Imports

The following functions are duplicates of the base DLL exports beyond @1001 . They are imported by the device-specific DLL from the base DLL.

enter_driver =IBMVGA32.1002
leave_driver =IBMVGA32.1003
save_that_error =IBMVGA32.1004
perform_rip =IBMVGA32.1005
ddc_validate =IBMVGA32.1006
enter_driver_sem =IBMVGA32.1007
GetVRAMR0Pointer =IBMVGA32.1008
ring3_CriticalError =IBMVGA32.1010
InnerAccumulateBounds =IBMVGA32.1014
correlate_for_point_si =IBMVGA32.1016
enter_driver_sem_only =IBMVGA32.1017
leave_driver_sem_only =IBMVGA32.1018
do_sl_corr =IBMVGA32.1019
check_sem =IBMVGA32.1029
get_clip_rects =IBMVGA32.1031
ShortlineCorrelate =IBMVGA32.1032
far_clip_line =IBMVGA32.1033
ComputeShortlineBounds =IBMVGA32.1034
save_that_warning =IBMVGA32.1042
Force_Valid_CP =IBMVGA32.1202
Vio32SetState =IBMVGA32.3000
Vio32SetMode =IBMVGA32.3001
free_bm =IBMVGA32.4100
alloc_bm =IBMVGA32.4101
AllocMem =IBMVGA32.4102
FreeMem =IBMVGA32.4103
recalc_correlate_rect =IBMVGA32.4104
pfnDefDisJointLines =IBMVGA32.4105
pfnDefPolyLine =IBMVGA32.4106
pfnDefSetCurrentPosition =IBMVGA32.4107
convert_world_screen =IBMVGA32.4108
convert_screen_world =IBMVGA32.4109
pfnDefRectVisible =IBMVGA32.4110
pfnDefCharStringPos =IBMVGA32.4111
pfnDefBitblt =IBMVGA32.4112
pfnDefGetClipRects =IBMVGA32.4113
pfnDefQueryTextBox =IBMVGA32.4114
double_enter_driver =IBMVGA32.4115
validate_rectl =IBMVGA32.4116
intersect_rcl =IBMVGA32.4117
intersect_with_corr =IBMVGA32.4118
AccumBoundsInDevCoords =IBMVGA32.4119
pfnDefDrawbits =IBMVGA32.4120
convert_rectl =IBMVGA32.4121
pfnDefPolyMarker =IBMVGA32.4122

Device-Specific DLL Function Exports

The following functions are duplicates of the base DLL import functions. They are exported by the device-specific DLL.

init_hw_regs @4000
rgb_to_ipc @4004
physical_enable @4011
physical_disable @4012
device_specific_init @4013
device_specific_post_init @4014
copy_bits_to_pattern @4017
PolyShortLine @4023
SaveScreenBits @4026
PolyScanline @4028
RestoreScreenBits @4030
Pixel @4034
far_exclude @4037
far_unexclude @4038
SetColorCursor @4039
DeviceSetCursor @4040
SetScreenBusy @4041
CharRect @4200
CharStr @4201
DeviceSetAVIOFont2 @4202
ScrollRect @4204
UpdateCursor @4205
DeviceSeamlessInit @4206
deselect_bitmap @4301
save_bitmap @4302
DeviceCreateBitmap @4303
DeviceSelectBitmap @4304
DeviceDeleteBitmap @4305
GetBitmapBits @4306
SetBitmapBits @4307
DrawLinesInPath @4308
DisJointLines @4309
PolyLine @4310
GetCurrentPosition @4311
SetCurrentPosition @4312
CharString @4313
Drawbits @4314
ImageData @4315
CharMarkerPos @4316
CharStringPos @4317
Bitblt @4318
DrawBorder @4319
PolyMarker @4320
alloc_brush @5201 NONAME
free_brush @5202 NONAME
copy_brush @5203 NONAME
QueryRealColors @5300
QueryColorIndex @5301
QueryNearestColor @5302
QueryColorData @5303
UnrealizeColorTable @5304
RealizeColorTable @5305
deselect_lct @5306
QueryLogColorTable @5307
save_lct @5308
QueryRGBColor @5309
CreateLogColorTable @5310
PropagateSysClrChange @5311
MakeColorsValid @5312
MakeBrushValid @5313
MakePassedColorsValid @5314
device_enter_driver @5315
ResetLogColorTable @5316

Base GRE Entry Points

The base DLL supplies functionality for the following calls from the Graphics Engine. For further information see the Presentation Device Driver Reference.

AccumulateBounds
Death
DeviceGetAttributes
DeviceInvalidateVisRegion
DeviceQueryFontAttributes
DeviceQueryFonts
DeviceSetAttributes
DeviceSetDCOrigin
DeviceSetGlobalAttribute
ErasePS
Escape
GetBoundsData
GetCodePage
GetCurrentPosition
GetDCOrigin
GetLineOrigin
GetPairKerningTable
GetPel
GetPickWindow
GetScreenBits
GetStyleRatio
LockDevice
NotifyClipChange
NotifyTransformChange
QueryDeviceBitmaps
QueryDeviceCaps
QueryDevResource2
QueryHardcopyCaps
RealizeFont
ResetBounds
Resurrection
SetCodePage
SetCurrentPosition
SetLineOrigin
SetPel
SetPickWindow
SetScreenBits
SetStyleRatio
UnLockDevice

Device-Specific GRE Entry Points

The device-specific DLL also supplies functionality for the following calls from the Graphics Engine.

Refer to the Presentation Device Driver Referencefor additional information on these calls.

Bitblt
CharRect
CharStr
CharString
CharStringPos
CreateLogColorTable
DeviceCreateBitmap
DeviceDeleteBitmap
DeviceSelectBitmap
DeviceSetCursor
DrawBits
DrawBorder
DrawLinesInPath
GetBitmapBits
ImageData
MoveCursor
Polyline
PolyMarker
PolyScanline
PolyShortLine
PropagateSysClrChange
QueryColorData
QueryColorIndex
QueryLogColorTable
QueryNearestColor
QueryRealColors
QueryRGBColor
RealizeColorTable
RestoreScreenBits
SaveScreenBits
ScrollRect
SetBitmapBits
SetColorCursor
StretchBlt
UnrealizeColorTable
UpdateCursor

The device-specific DLL also supplies functionality for the DeviceSetAVIOFontcall from GRE. In the device-specific DLL, the function must be named DeviceSetAVIOFont2.

Refer to the Presentation Device Driver Referencefor additional information.

The Device-Specific API

These are functions that are created by the developer of the device- specific driver:

copy_bits_to-pattern
deselect_bitmap
device_enter_driver
deselect_lct
device_specific_post_init
device_specific_init
far_exclude
far_unexclude
init_hw_regs
physical_disable
physical_enable
Pixel
PropagateSysClrChange
save_bitmap
save_lct

Each of these functions must behave exactly as described.

For the descriptions of the register contents, the equal " = " sign means that the register contains the value named. For example:

ECX = number of bytes per scanmeans that the register contains the actual number of bytes per scan.

The arrow " � " sign means that the register contains a pointer to the value, and not the actual value itself. For example:

ECX � number of bytes per scanmeans that the value in the register is a pointer to the memory location that contains the number of bytes per scan.

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    copy_bits_to_pattern                                  |
|                                                          |
|    void copy_bits_to_pattern(void)                       |
|                                                          |
\----------------------------------------------------------/

Description: Copy a source pattern bit map to a destination pattern bit map .

Entry:

AL  = Number of color planes in source bit map
AH  = Width of bit map in pels (significance through eight)
EBX � DDC
ECX = Number of bytes per scan of source bit map
EDX = Height of bit map
ESI � First byte of the destination buffer
EDI � First byte of the source buffer

Return Values: None

Error Returns: None

Registers Preserved: EBX, EBP, ESP

Registers Preserved: EAX, ECX, EDX, ESI, EDI, FLAGS

Invoked From:

SetPatternFont         (Winattrs.asm)

Routines Called: None

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    deselect_bitmap                                       |
|                                                          |
|    void deselect_bitmap(void)                            |
|                                                          |
\----------------------------------------------------------/

Description: Decrements selection count in the bit map, clears the pointer to the surface device, and clears the following DDC bits:

�DDC_PRESENT - indicating that there is no surface.
�DDC_CLIP_NOTIFY - indicating clipping is invalid
�DDC_VISIBLE - indicating nothing is showing.

If the selection count is 0, it clears the handle to DDC, indicating a free bit map.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EAX, ECX, EDX, ESI, EDI, ESP, EBP

Registers Destroyed: EBX, FLAGS

Invoked From:

restore_ddc_state      (Enable.asm)

Routines Called: None

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_enter_driver                                   |
|                                                          |
|    void device_enter_driver(void)                        |
|                                                          |
\----------------------------------------------------------/

Description: device_enter_driveris a null function.

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: EAX, ECX, EDX, ESI, EDI, ESP, EBP, FLAGS

Registers Preserved: None

Invoked From:

enter_driver (enter.asm)

Routines Called: Dependent on processing

Video Semaphore Required for Processing: Dependent on processing

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    deselect_lct                                          |
|                                                          |
|    void deselect_lct(void)                               |
|                                                          |
\----------------------------------------------------------/

Description: deselect_lctdecrements the usage count in the logical color table.

When the usage count is 0, deselect_lct frees the memory of the logical_ color_tableby calling private_freewith the ECX pointing to the memory to be released and sets the default color table.

private_freeis an exported function contained in IBMVGA32.DLL.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EAX, EDX, ESI, EDI, ESP, EBP, FLAGS

Registers Preserved: EBX, ECX

Invoked From:

disable_ddc            (Enable.asm)

Routines Called: None

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_specific_post_init                             |
|                                                          |
|    void device_specific_post_init(void)                  |
|                                                          |
\----------------------------------------------------------/

Description: device_specific_post_initis a null function.

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, ESP, EBP, FLAGS

Registers Preserved: None

Invoked From:

one_time_init       (init.asm)

Routines Called: Dependent on processing

Video Semaphore Required for Processing: Dependent on processing

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    device_specific_init                                  |
|                                                          |
|    void device_specific_init(void)                       |
|                                                          |
\----------------------------------------------------------/

Description: Initializes gsspScreen.cbto the size of screen memory (64KB), gsspScreen.pPhysMemto the address of screen memory (0A0000h). Sets the marker width and height in the device capabilities buffer (adDevCapsData[ CAPS_MARKER_WIDTH ], adDevCapsData[ CAPS_MARKER_HEIGHT ]). See the Presentation Manager Programming Reference, Volume 1, "DevQueryCaps", for additional information.

Set padBitmapFormatsto the address of the table containing bit map format types.

The table is in the form (# planes, bits/pel). The first pair in the table must be the format that most closely resembles the device.

(For additional information see the Presentation Device Driver Reference, " GreQueryDeviceBitmaps").

Get a Ring 0 alias for screen memory pointer and save in Curdata.pVRAMRing0 .

The following code segment illustrates the sequence described above:

Basically, you open PMDD.SYS via DosOpen and communicate with PMDD.SYS via DosDevIOCtl.

GetVRAMR0Pointer PROC SYSCALL USES EDI
        LOCAL   hSVGA:DWORD
        LOCAL   ulAction:DWORD
        LOCAL   scrnTx:SCRNTX
        LOCAL   scrnRx:SCRNRX
        LOCAL   fAttach:BYTE

        INVOKE  DosOpen,
                ADDR szSQ,         ;lpDevice � device
                                     name string
                ADDR hSVGA,        ;pass � handle
                                     return value
                ADDR ulAction,     ;dAction return value
                0,                 ;filesize (zero)
                0,                 ;file attribute (zero)
                1,                 ;open flag (open
                                     existing file)
                0000000011000000b, ;open mode
                0                  ;reserved
        or      eax,eax
        jnz     getvram_error
        mov     eax,gsspScreen.pPhysMem
        mov     scrnTx.stx_Address,eax
        mov     eax,gsspScreen.cb
        mov     scrnTx.stx_Size,eax
        mov     scrnTx.stx_flFlag,1
        INVOKE  DosDevIOCtl,
                hSVGA,             ;hDevice
                03h,               ; ulCat
                7eh,               ; ulFunction
                ADDR scrnTx,       ; pParmList
                SIZEOF scrnTx,     ; cbParmList
                0,                 ; plReserved
                ADDR scrnRx,       ; pData
                SIZEOF scrnRx,     ; cbData
                0                  ; plReserved
        mov     ebx,eax            ;save return code
        INVOKE  DosClose, hSVGA
        mov     eax,scrnRx.srx_ScrnPtr
@@:
;/*
;** check return from dosdevioctl call
;*/
        or      ebx,ebx
        jz      getvram_exit
getvram_error:
        mov     eax,0              ;error return
getvram_exit:
        ret

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: ESP, EBP

Registers Destroyed: EAX, EBX, ECX, EDX, ESI, EDI, FLAGS

Invoked From:

DllLoadProc            (Init.asm)

Routines Called:

CursorInit             (Cursor2.asm)

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    far_exclude                                           |
|                                                          |
|    void far_exclude(void)                                |
|                                                          |
\----------------------------------------------------------/

Description: Removes the pointer image if the exclusion area of the screen currently includes the pointer.

Entry:

ECX = X coordinate of left edge
EDX = Y coordinate of top edge
ESI = X coordinate of right edge (inclusive)
EDI = Y coordinate of bottom edge (inclusive)

Return Values: None

Error Returns: None

Registers Preserved: ESP, EBP

Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, FLAGS

Invoked From:

OemBitblt              (Bitblt.asm)
InvertClippedRect      (Celldraw.asm)
OEMDrawBits            (Drawbits.asm)
SaveScreenBits         (Ssb.asm)
OEMStretchBlt          (Strchblt.asm)
output_o_rect          (Strdraw.asm)
Pixel                  (Pixel.asm)
RELDrawBits            (Rlebm.asm)
scanline_device_init   (Scanline.asm)
PolyShartLine          (Shortln.asm)
DrawImageRect          (Cellscan.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine               (Major01.asm)

Routines Called:

pointer_off            (Pointer.asm)

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    far_unexclude                                         |
|                                                          |
|    void far_unexclude(void)                              |
|                                                          |
\----------------------------------------------------------/

Description: Removes the exclusion rectangle defined by far_exclude. Do not redraw the cursor because it might have to be removed for the next call. Redrawing the pointer is the responsibility of MoveCursor.

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, FLAGS

Registers Preserved: None

Invoked From:

OemBitblt              (Bitblt.asm)
InvertClippedRect      (Celldraw.asm)
OEMDrawBits            (Drawbits.asm)
SaveScreenBits         (Ssb.asm)
OEMStretchBlt          (Strchblt.asm)
output_o_rect          (Strdraw.asm)
Pixel                  (Pixel.asm)
RELDrawBits            (Rlebm.asm)
scanline_device_init   (Scanline.asm)
PolyShartLine          (Shortln.asm)
DrawImageRect          (Cellscan.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine               (Major01.asm)

Routines Called: None

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    init_hw_regs                                          |
|                                                          |
|    void init_hw_regs(void)                               |
|                                                          |
\----------------------------------------------------------/

Description: Initializes the state required to save and restore the VGA's registers and processor latches, and the default VGA state assumed by the rest of the display driver code. Call this code immediately after the VGA has been programmed for graphics mode and the palette registers set. This code is called at initialization, resurrection, and after a DOS session to ensure a known state of the VGA.

Entry: None

Return values: None

Error Returns: None

Registers Destroyed: EAX, ECX, EDX, FLAGS

Registers Preserved: EBX, ESI, EDI, EBP, ESP

Invoked From:

physical_enable        (Egainit.asm)
req_controller         (Enter.asm)

Routines Called:

set_test_locs          (Egastate.asm)
set_misc_regs          (Egastate.asm)

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    physical_disable                                      |
|                                                          |
|    void physical_disable(void)                           |
|                                                          |
\----------------------------------------------------------/

Description: Inhibits all drawing to the screen by the VDD and VDM and PM. physical_disableis called from Death, signifying a switch to a non-PM screen group. physical_disablesaves the physical screen and hardware state .

Entry: None

Return Values: None

Error Returns: None

Registers Preserved: ESI, EDI, EBP, ESP

Registers Destroyed: EAX, EBX, ECS, EDX, FLAGS

Invoked From:

Death                  (Winattrs.asm)

Routines Called:

enter_driver_sem_only  (Enter.asm)
leave_driver_sem_only  (Enter.asm)
notify_vdd             (Egainit.asm)
notify_vwin            (Egainit.asm)
save_textvram          (Egainit.asm)

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    physical_enable                                       |
|                                                          |
|    DWORD physical_enable (DWORD fInitMem, DWORD cbDirty) |
|                                                          |
\----------------------------------------------------------/

Description: Enables the appropriate graphics mode. Attempts a fast video ram restore if fInitMemdoes not equal INIT_VRAM.

Entry: fInitMemis a flag set by fill_phys_dev_blkor Resurrection.

A value of 1 indicates original initialization procedures, indicating that screen memory should be initialized to zeros. Any other value indicates restoration from a previously saved state. cbDirtyis the number of VRAM bytes to restore for a fast video restore. physical_enablereceives cbDirtyfrom resurrection. cbDirtyindicates the number of bytes of video RAM damaged since Death. If the amount dirtied is less than the amount saved at Death then a fast video RAM restore is performed.

Ignore this value if fInitMemcontains 1. physical_disablesaves the physical screen and hardware state to improve screen restoration performance. If the screen state remains unchanged at resurrection time, the driver can display a saved state quicker than it can reconstruct and redraw the previous state (fast video ram restore).

Return Values: EAX = 0 if successful

Error Returns:

EAX = Vio Error code if not successful (EAX <> 0)
      or result of video RAM restoration if fInitMem was FALSE

Registers Preserved: ESI, EDI, EBP, ESP

Registers Destroyed: EAX, EBX, ECX, EDX, FLAGS

Invoked From:

fill_phys_dev_blk      (Enable.asm)
Resurrection           (Winattrs.asm)

Routines Called:

Vga32CallBack          (32callbk.asm)
restore_textvram       (Egainit.asm)
init_hw_regs           (Egastate.asm)
notify_vdd             (Egainit.asm)
notify_vwin            (Egainit.asm)

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    Pixel                                                 |
|                                                          |
\----------------------------------------------------------/

LONG Pixel (LONG lX, LONG lY, LONG lPhysColor,
                     LONG lMixMode);

lx:                    x coordinate of pel
ly:                    y coordinate of pel
lPhysColor:            Physical color to set pel to
lMixMode:              Raster operation code or -1 if get pel

Description: Sets a pel to a given color or returns a pel's internal physical color. The physical device may be the screen, or a monochrome or color bit map.

If mix_modeequals -1, Pixel returns the pel's IPC (Internal Physical Color ). If mix_modeis any other value, the value indicates the Raster operation (ROP).

During a set pel operation, Pixel sets the pel to the color that corresponds to the internal physical color indicated in the lPhysColorparameter, combined with the internal physical color of the pel currently at that location. Pixel combines the colors according to the ROP in mix_ mode. Background and clipping are not a consideration.

Entry:

ESI � DDC
VGA registers in default state

Return Values: EAX = IPC if GetPixelor Positive if SetPixel

Error Returns: EAX = 080000000H

Registers Preserved: ESI, EDI, EBP, ESP

Registers Destroyed: EAX, EBX, ECX, EDX, FLAGS

Invoked From:

GetPel                 (Pelsup.asm)
SetPel                 (Pelsup.asm)

Routines Called:

far_exclude            (Cursor2.asm)
far_unexclude          (Cursor2.asm)
ipc_to_index           (Clrconv.asm)

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    PropagateSysClrChange                                 |
|                                                          |
|    void PropagateSysClrChange(void)                      |
|                                                          |
\----------------------------------------------------------/

Description: Called after at least one system color changes. Since the driver has no way of knowing which color changed, it must assume that all system colors have changed. Color table indices 0 and 7 default to certain system colors.

If these system colors change and the default mapping is still in effect, the driver must update the corresponding IPC (internal physical color) from the default color table.

The default mapping is in effect unless the driver explicitly changes it. In that case, DDC_CLR_0_USERS or DDC_CLR_7_USERS is set, as appropriate. The driver must update any attribute bundle that has a system color selected, by marking the IPC as invalid so that it won't be realized again until necessary.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EBX, ECX, EDX, ESI, EDI, EBP, ESP

Registers Destroyed: EAX, FLAGS

Invoked From:

GetPel                 (Pelsup.asm)
SetPel                 (Pelsup.asm)
DrawBorder             (Drawbord.asm)
DrawLinesInPath        (Drawline.asm)
PolyLine               (Polyline.asm)
Bitblt                 (Winbits . asm ) 
ImageData                 ( Winbits . asm ) 
CharStringPos            ( Winstr . asm ) 
CharMarkerPos            ( Winstr . asm ) 
CharString                ( Winstr . asm ) 
ipc _ to _ index              ( Clrconv . asm ) 
RGBToNearestIndex        ( Colortbl . asm ) 
QueryLogColorTable       ( Colortbl . asm ) 
QueryRGBColor            ( Colortbl . asm ) 
PolyScanline              ( Scanline . asm ) 
PolyShortline            ( Shortln . asm ) 

Routines Called: None

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    save_bitmap                                           |
|                                                          |
|    void save_bitmap(void)                                |
|                                                          |
\----------------------------------------------------------/

Description: Increments the select count in the bit map.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EAX, ECX, EDX, ESI, EDI, EBP, ESP

Registers Destroyed: EBX, FLAGS

Invoked From:

save_ddc_state         (Enable.asm)

Routines Called: None

Video Semaphore Required for Processing: No

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    save_lct                                              |
|                                                          |
|    void save_lct(void)                                   |
|                                                          |
\----------------------------------------------------------/

Description: Increments the usage count in the logical color table.

Entry: ESI � DDC

Return Values: None

Error Returns: None

Registers Preserved: EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP

Registers Destroyed: FLAGS

Invoked From:

save_ddc_state         (Enable.asm)

Routines Called: None

Video Semaphore Required for Processing: No

GRE Functions

The following is a list of the functions in the graphics engine that are hooked by the 32-bit VGA display driver.

�Graphics Engine Attribute Functions

�Graphics Engine AVIO Functions

�Graphics Engine Bit-Map Functions

�Graphics Engine Color Table Functions

�Graphics Engine Device Functions

�Graphics Engine Escape Functions

�Graphics Engine Line Functions

�Graphics Engine Marker Functions

�Graphics Engine Miscellaneous Device Functions

�Graphics Engine Miscellaneous Screen Functions

�Graphics Engine Query Functions

�Graphics Engine String Functions

For more information about these functions and their descriptions, see Graphics Engine Functions.

Debugging Support

Debugging support is provided through a macro that sends data through the kernel debugger port to a serial port. The kernel debugger and its related documentation is provided with the Developer's Toolkit for OS/2. By inserting the DebugMsg2<> macro, the supplied string will be routed to the debugging port.

ifdef FIREWALLS

        DebugMsg2       < This will be printed at the debugging terminal. >

endif ;FIREWALLS

Current debug messages in the code are placed inside the conditional compilation ifdef FIREWALLS. This value is defined when compiling the debug version of the driver.

Thunking

Although the display driver is written in 32-bit flat model, there still is a need to call certain 16-bit routines. To accommodate this need, thunk layerinterfaces are provided. The thunk layer converts 32-bit parameters to 16-bits, and maps linear addresses to segmented addresses. For detailed information about thunking and thunk layers, see the OS/2 Application Design Guide.

Thunk layers are provided for the 16-bit functions listed in the table below, so that they can be available to the 32-bit display driver.

/-------------------------------------------------------------\
|16-Bit Function         |32-Bit Function from VGA Display    |
|                        |Driver                              |
|------------------------+------------------------------------|
|VIS16REGIONCALLBACK     |Vis32RegionCallBack                 |
|------------------------+------------------------------------|
|GetPmddCodeSelector     |Get32PmddCodeSelector               |
|------------------------+------------------------------------|
|GetScreenSelector       |Get32ScreenSelector                 |
|------------------------+------------------------------------|
|VioGetPhysBuf           |Vio32GetPhysBuf                     |
|------------------------+------------------------------------|
|VioSetState             |Vio32SetState                       |
|------------------------+------------------------------------|
|VioSetMode              |Vio32SetMode                        |
|------------------------+------------------------------------|
|VioGetConfig            |Vio32GetConfig                      |
|------------------------+------------------------------------|
|VioGetPSAddress         |VioGetPSAddress32                   |
|------------------------+------------------------------------|
|FSRSemEnter             |FSRSemEnter32                       |
|------------------------+------------------------------------|
|FSRSemLeave             |FSRSemLeave32                       |
|------------------------+------------------------------------|
|FSRSemExit              |FSRSemExit32                        |
|------------------------+------------------------------------|
|FSRSemCheck             |FSRSemCheck32                       |
\-------------------------------------------------------------/

The 32-bit display driver functions listed in the table below have 16-bit thunk interfaces that are provided to the 16-bit WIN-OS/2 display driver so that it can cooperate with the 32-bit VGA display driver.

/-------------------------------------------------------------\
|16-bit Functions Called by    |32-Bit Functions in VGA       |
|WIN-OS/2                      |Display Driver                |
|------------------------------+------------------------------|
|far_unexclude16               |far_unexclude                 |
|------------------------------+------------------------------|
|FAR_EXCLUDE16                 |far_exclude                   |
\-------------------------------------------------------------/

32-Bit Super VGA Display Driver

The 32-bit Super VGA display driver, like all display drivers, provides hardware- independence for OS/2 application programs needing to perform I/O to a display device. While the general architecture and functionality of the Super VGA driver are the same as the 32-bit VGA driver, there are differences between the two. This chapter concentrates on those differences . See 32-Bit VGA Display Driverfor detailed information about 32-bit VGA display drivers.

Overview

The 32-bit Super VGA display driver dynamically supports the following chip sets:

/-------------------------------------------------------------\
|Vendor                  |Chip Set                            |
|------------------------+------------------------------------|
|ATI Technologies, Inc.**|ATI28800                            |
|------------------------+------------------------------------|
|Cirrus Logic, Inc.**    |CL-GD5422 and CL-GD5424             |
|------------------------+------------------------------------|
|Headland Technology,    |HT209 (VRAM II)                     |
|Inc.**                  |                                    |
|------------------------+------------------------------------|
|IBM Corporation         |VGA 256C or SVGA-NI                 |
|------------------------+------------------------------------|
|Trident Microsystems,   |TVGA 8900B and 8900C                |
|Incorporated**          |                                    |
|elink.                  |                                    |
|------------------------+------------------------------------|
|TSENG Laboratories,     |ET4000                              |
|Inc.**                  |                                    |
|------------------------+------------------------------------|
|Western Digital         |WD90C11 (PVGA1C), WD90C30 (PVGA1D), |
|Corporation**           |WD90C31 (in WD90C30 compatibility   |
|                        |mode)                               |
\-------------------------------------------------------------/

The hardware is queried at runtime, and separate code paths for each chip set are taken.

The Super VGA driver supports multiple resolutions for each chip set, including 640 x 480, 800 x 600, and 1024 x 768. Each of these resolutions is supported in 256-color mode. A separate driver is built for each resolution using conditional compilation.

The 32-bit Super VGA display driver also supports several new features:

�OS/2 Presentation Manager (PM) Palette Manager

�Two new background mix options:

-BM_SRCTRANSPARENT
-BM_DESTTRANSPARENT

These new functions permit transparent overlay and transparent underlay of BitBlt operations. See New Background Mix Supportfor details.

32-Bit Super VGA Display Driver Architecture

The 32-bit Super VGA display driver consists of two components: IBMVGA32. DLL and IBMDEV32.DLL. This architecture was chosen to make the driver more easily portable among various hardware video cards. The device-independent functions of the driver are contained in the base DLL, IBMVGA32.DLL; the device-specific functions are contained in the device-specific DLL, IBMDEV32.DLL. In order to be used in the system, individual Super VGA drivers must be renamed to IBMDEV32.DLL when they are built.

The graphics engine calls entry points in both DLLs. The two DLLs also call exported entry points within each other. If you want to port this driver to other video cards, you must write code that supplies the functionality for the entry points in the device-specific DLL. Notice that fonts are now built in the separate DLL called DSPRES.DLL. The following figure shows the 32-bit Super VGA display driver architecture. [Artwork not shown]

Building the 32-Bit Super VGA Display Driver

The supplied display drivers can be built using the NMAKE Utility in the IBM Developer Connection Device Driver Kit for OS/2. (The NMAKE Utility is particularly useful in programs consisting of several source files because it builds only those components that have changed since the program was compiled last.) The following six drivers can be built from the same source set:

640 x 480    256 colors   Debug version
640 x 480    256 colors   Retail version

800 x 600    256 colors   Debug version
800 x 600    256 colors   Retail version

1024 x 768   256 colors   Debug version
1024 x 768   256 colors   Retail version

Each of the drivers supports all six of the previously-mentioned chip sets. The debug versions of each driver have enabled all code within the ifdef FIREWALLS conditional compilation, which provides some extra error checking and messages through the kernel debugger.

By default, all the drivers are built just by typing the NMAKE command. Individual drivers can be built by passing the following parameters to NMAKE:

    NMAKE  [vertical resolution].[debug or retail flag]

    for example:

        NMAKE 768.ret
        - builds the 1024 x 768 retail driver.

        NMAKE 600.deb
        - builds the 800 x 600 debug driver.

        NMAKE 480
        - builds both the debug and retail 640 x 480 drivers.

        NMAKE retail
        - builds all resolutions of retail drivers.

New Background Mix Support

The background mix, BM_SRCTRANSPARENT, is used in calls to GpiBitBlt and GpiDrawBits so that pels in a source bit map that match pels in the target presentation space background color are not copied to the output bit map. Where source bit-map pels match the background color, target bit-map pels are left unchanged, which provides a transparent overlay function.

The background mix, BM_DESTTRANSPARENT, also is used in calls to GpiBitBlt and GpiDrawBits, to permit pels from the source bit map to be copied to only the target pels that match the background color of the presentation space. Pels in the target are changed where the source bit-map pels match the background color of the target, thus providing a transparent underlay function.

OS/2 PM Palette Manager Support

The supplied driver supports the OS/2 PM Palette Manager, which is a set of application-level APIs that enable an application to change a video board's palette look-up table. Refer to PM Palette Management Supportfor additional information. The driver must deal with logical color tables ( LCTs), as well as palettes, and must be able to convert between memory- memory, memory-screen, and screen-memory bit maps.

Screen bit-map pelsare physical indexes into the hardware palette, whether you are dealing with a device context (DC)that is using a palette or an LCT.

Memory bit-map pelscan be any of the following:

�Logical indexes into a palette if you are dealing with a DC that is using a palette

�Physical indexes into the device default palette if you are dealing with a DC that is using an LCT

�Physical indexes into the hardware palette if you are dealing with a DC that is using a realizableLCT

SVGA Base Video Subsystem

The base video handler (BVHx) display drivers handle all non-graphical primitive video device functions, such as mode set, palette loading, and all of the text-related functions. Base video handler architecture is described in full detail in Physical Video Device Drivers

Overview

The application interface to take advantage of the base video handler functions is the 16-bit VIO interface, which is also available to 32-bit applications via a thunking layer. Because most of the text-mode related functions are "VGA legacy," there is little need for customizing that part of the base video handler for each new device.

Most of the need for customization comes from the fact that set mode functions are widely different on today's SVGA devices, even across different adapter implementations of the same SVGA chip set. Historically, there was no system support for invoking the real-mode video BIOS for the purposes of the set mode. As a result, customization of the base video handler to handle different SVGA chip sets and their adapter implementations became a norm. The goal then became to externalize the device-specific programming into another 32-bit interface, which was done by the introduction of the VIDEOPMI handler and the SVGADATA.PMI file.

Hence, the SVGA base video handler (BVHSVGA) is a generic driver that imports device-specific functions from VIDEOPMI. VIDEOPMI's interface is also available to any other 16- or 32-bit application. For a full description of the VIDEOPMI's procedural interface, see VIDEOPMI.DLL Exported Functions. For a full description of the PMI subsystem see VIDEO Protect-Mode Interface.

Resolution, monitor, and refresh configuration in OS/2 are standardized and handled by the System icon's first two pages. Monitor and refresh configuration are available for both legacy and DDC-compliant monitors. The function is internally handled by a component called VIDEOCFG. The full specification of the VIDEOCFG's function and exported procedural interface is provided in VIDEOCFG.DLL Exported Functions.

Although most of today's display drivers rely on the VIO subsystem (BVH) to set the mode, that is not mandatory. The new display driver architecture ( GRADD) does use the VIDEOPMI's interface directly. When using VIDEOPMI's interface directly, the display driver is responsible for setting all of the mode parameters (there is a considerable difference in mode parameters between the VIO and VIDEOPMI). In such a case, the display driver has to do the following:

�Invoke VIDEOCFG to retrieve the current configuration

�Transverse the mode table as returned by the VIDEOPMI

�Find the most appropriate entry

�When setting the mode, supply any dynamic mode entry values in the VIDEO_ ADAPTER.MODEINFO structure on the call to VIDEOPMI's PMIREQUEST_SETMODE

Display drivers using the traditional VIO mode set do not need to use VIDEOCFG, provided that their base video support is using the generic IBM BVHSVGA and has externalized the device support via the PMI subsystem.

A display driver vendor may also opt to issue the mode set by using VIDEOPMI's software interrupt services (VIDEO BIOS mode set) without any customization of the PMI subsystem. This approach, however, does not allow for monitor and timing configuration, because VIDEOCFG bases the configuration on the existence of a mode table that includes timing parameters, which is imported from the PMI subsystem . For sample source on how to use VIDEOPMI's software interrupt, see src\oempmi sources and search for PMIREQUEST_SOFTWAREINT. For more specific information on the software interrupt service, see VIDEOPMI.DLL Exported Functionsand VIDEO Protect- Mode Interface.

Note:The PMI subsystem, including the video configurator VIDEOCFG, will run on both OS/2 Warp, Version 3 and the OS/2 2.x base. See Video Subsystem Binary Filesas well as Installing Video Configuration Manager for OS/2in VIDEOCFG.DLL Exported Functions.

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.

With the new feature install (OS/2 Warp, Version 3, PowerPC Edition) and GRADD architecture, these assumptions will be removed; that is, the SVGADATA.PMI file will no longer be assumed to exist. Existing support for flat PMI files remains intact and these files are fully supported as described in VIDEO Protect-Mode Interface.

The VIDEOPMI handler is maintained by IBM; it is shipped in the IBM Developer Connection Device Driver Kit for OS/2as 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/2was shipped.

It is not recommended that vendors 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".

Device Detection

Device detection is built into both SCREENx.SYS PDD and SVGA(OEM).EXE. SVGA (OEM).EXE does not need to have device detection added if the generic .PMI file is sufficient. However, as a courtesy to the customer running the drivers and a safeguard against running inappropriate drivers, some device detection should be built into either or both of the modules.

SCREENx.SYS PDD does not have to be modified to add device detection, unless the vendor wishes to use the default .DSC file-selection feature of the display driver installation utility. SVGADEFS.H contains _ADAPTER IDs that are reserved for vendor use for this purpose. For vendors who would like to have a new _ADAPTER ID allocated, a call to DUDE with the request and the name of the vendor is required. When adding device detection to SCREENx.SYS PDD, the allocated ID should be returned. Detection function IdentifySVGA in svgaid.asm is common to both SCREENx.SYS and SVGAOEM.EXE ( SVGA.EXE), with the exception that the PCI detection is invoked only in the PDD, not in the utility. The PCI interface, as used by the SCREENx.SYS, is exported by the OS/2 loader's OEMHLP PDD. Its full interface is documented in inc\pci.inc and samples PCITEST.C and PCITEST.H in src\oempmi. As code is added to SVGAID.ASM, it should be propagated to both SVGA.EXE and SCREENx.SYS PDD. The makefiles will take care of conditional compilation for both modules.

Video Subsystem Binary Files

The following is a complete list of base video modules. Those shipped in their source format, which can be optionally modified, are to be compiled by a vendor and are marked as such. Modules that do not require any vendor modification are also provided because they either did not exist in all of the previous OS/2 versions or they have been upgraded.

�SVGADEFS.H

This is the main header file for SVGA video support. It contains VIDEOPMI's structures and function table, VIDEOCFG structures, and function prototypes . It also contains the SCREEN PDD structures and function numbers, as well as device detection ID lists (Adapters and Chipsets structure). A vendor needs to update this file and add detection to SCREEN PDD only if automatic (machine key) selection of the .DSC file is desired during the display install. If a new device ID needs to be allocated, a request for new ID should be submitted to DUDE.

�SCREEN01.SYS

This is the base video physical device driver. Source can be found on src\ dev\screendd. This driver provides device detection and additional video services, such as linear buffer memory mapping. These services are part of Category 80 IOCTL functions. The list of functions and associated structures can be found in the OS/2 Physical Device Driver Reference, Chapter 11, "General IOCTL Commands" under "Category 80h Screen IOCTL Commands".

PCI processing in this physical device driver is limited only to finding devices of video class and their vendor IDs. For vendors who need to examine more of the PCI header, there is no need to expand this PDD - OEMHLP PDD IOCTLs, which provide the PCI functionality, can be called at ring3. See sample source src\oempmi\pcitest.c.

�BVHSVGA.DLL

The generic SVGA base video handler. This module is provided in source format in src\svdh directory. Modification is not required.

Attention

Do not mix this BVHSVGA with a VIDEOPMI from an older DDK. Some structures in h\svgadefs.h have been expanded; the modules using VIDEOPMI's structures -VIDEOCFG, VIDEOPMI, BVHSVGA and OEMPMI-should all be at the same level.

If a vendor needs to build BVHSVGA compatible with an older VIDEOPMI, a macro, VIDEOPMI_30_LEVEL, should be defined before including h\svgadefs.h and the component should be rebuilt.

�SVGAOEM.EXE

The generic SVGA.EXE utility for creation of an SVGADATA.PMI file. It is provided in source format in src\oempmi\svgautil directory. Modification is not required unless refresh support or a non-generic feature is desired.

�OEMPMI.DLL

A sample imported PMI library. It works with the SVGADATA.PMI file as created by SVGAOEM.EXE. OEMPMI.DLL is provided in source format on src\ oempmi directory. Modification is not required unless a vendor wishes to add refresh support. The source exemplifies the META-PMI chaining as well as usage of VIDEOPMI's software interrupt services.

�VIDEOPMI.DLL

The main PMI handler. Originally just a PMI language interpreter, it is now expanded to handle imported PMI libraries as well as META-PMI chaining. The driver is shipped as a binary file only and can be found in the video\bin directory. This version is the first to provide software interrupt services (calling real-mode BIOS). and should not be mixed with older BVHSVGA, IBMGPMI, or VIDEOCFG, due to changes in some structures in h\svgadefs.h.

�VPRPMI.SYS

A private PMI virtual device driver providing software interrupt services. It should be installed in CONFIG.SYS as DEVICE=X:\OS2\MDOS\VPRPMI.SYS. If a vendor is using software interrupt services, but has to ship its drivers to a customer who prefers to not install DOS support, a private kernel upgrade is available upon request to provide an alternate VDM service. In that case , the VPRPMI.SYS driver is not required. The driver is shipped as a binary file only and can be found in the video\bin directory.

�VIDEOCFG.DLL

The video configurator. This module handles the System icon notebook page 1 and page 2. These pages allow for monitor configuration, resolution and refresh configuration, as well as generic display driver settings configuration. The module is shipped as a binary file in the video\bin directory. The rest of the modules in this list are are support modules for VIDEOCFG.DLL. For a full functional description of VIDEOCFG, see VIDEOCFG.DLL Exported Functions.

Attention

Due to changes in some PMI structures in h\svgadefs.h, this module needs to be at the same level as the VIDEOPMI. As a result, an older VIDEOCFG, when mixed with a new VIDEOPMI, will not generate page 2 and refresh listbox. The same is true when a new VIDEOCFG is mixed with an older VIDEOPMI. Note that resolution dialog should not be affected in either case. No execution exceptions are expected when mixing components, only functional failures.

Note:Prior to the November 1995 IBM Developer Connection Device Driver Kit for OS/2, there was a VIDEOCFG.206 module that represented the 2.x version of VIDEOCFG.DLL. The VIDEOCFG.206 module is no longer needed, because its function has been consolidated into a single VIDEOCFG.DLL. Vendors who have already set up their install procedures to assume the existence of VIDEOCFG.206 should copy VIDEOCFG.DLL as VIDEOCFG.206. Using the older VIDEOCFG.206 will cause the incompatibility problem covered in Attentionabove.

�VCFGMRI.DLL

The resource module for VIDEOCFG.

�WPVIDSYS.DLL

This module is used when installing VIDEOCFG.DLL on OS/2 2.x. It replaces the class of WPSYSTEM in order to transfer ownership of the System icon pages from the Workplace shell to VIDEOCFG.DLL. Required only on 2.x. The subclassing becomes active only after this module is installed and the system is rebooted. The binary file is available in the video\bin directory .

�VCFGINST.EXE

This module is used to install WPVIDSYS.DLL on OS/2 2.x. VIDEOCFG.DLL will not be active on 2.x unless this utility is executed, WPVIDYS.DLL and VIDEOCFG.DLL are in the LIBPATH, and the system is rebooted following the execution of the utility. The binary file is available in the video\bin directory.

�MONITOR.DIF

The monitor database. This flat file contains timing descriptions for a large percentage of today's non-DDC-compliant monitors. The timings were obtained from the manufacturers' user manuals, and are not guaranteed to be correct or the most optimal. The entries can be added to or edited and, if new entries are submitted to the DUDE, they will be added to the master copy of the MONITOR.DIF. For vendors doing SID or RIPL install, new entries also can be placed in PRIVATE.DIF, which would leave MONITOR.DIF as read-only. MONITOR.DIF is available in the video\bin directory and should be placed into DPATH.

Physical Video Device Drivers

Video devices are accessed by using Base Video Handlers (BVHs). These BVHs consist of one or more Dynamic Link Libraries (DLLs). In the representative case of the VGA, BVHVGA.DLL manages the device for full-screen sessions, while DISPLAY.DLL (renamed from IBMVGA.DLL) manages the device for the Presentation Manager interface. Although these device handlers are initialized by different sections of the system at this time, they are architecturally compatible and can easily be combined at a later date.

Video Device Handler Identification

The list of the active video device handlers and their components resides in the CONFIG.SYS file as environment variables. To conserve environment space, these variables are removed from the environment during Shell Initialization. The VIDEO_DEVICES environment variable lists the names of the environment variables that describe each of the video device handlers. Commas are used to separate the names in this list. The following is an example of how to specify the environment variables ARTICHOKE and WATERMELON as those defining the active video device handlers, with ARTICHOKE used as configuration number one, and WATERMELON used as configuration number two.

      SET VIDEO_DEVICES=ARTICHOKE,WATERMELON

The value of each environment variable that describes a video device handler is composed of three keywords and the values associated with them. These keywords are separated by blanks and can be specified in any order and in any combination of upper and lower case characters. The DEVICE() keyword defines the list of names of the dynamic link libraries and physical device drivers which are combined to create the video device handler. The names are separated by commas, and their order determines the order in which the components will be initialized. These names represent only those parts of the BVH that need to be called to initialize the Call Vector Table. That is, physical device drivers should not be included in the list if they are only called by the dynamic link libraries and do not directly modify the Call Vector Table.

The default initialization entry point name for the dynamic link libraries is DEVENABLE. An alternate entry point name can be specified by following any DLL name with +AltName, where AltName is the entry point name.

The default initialization IOCtl for physical device drivers is Function 73h. An alternate function number and category can be specified by following the device name by +Func+Cat, where "Func" is the function number and "Cat" is the category. Both numbers must be specified in hexadecimal form. For details, see Function 73h under "Physical Device Driver Initialization" later in this chapter.

The following is an example of a device handler that is composed of two physical device drivers, DEV1 and DEV2, and three dynamic link libraries, DYN1 through DYN3. The second physical device driver uses an alternate initialization IOCtl and the third dynamic link library uses an alternate initialization entry point. POINTER$ is the default physical pointer device driver.

      SET ARTICHOKE=DEVICE(DEV1,DYN1,DEV2+74+05,DYN2,DYN3+OTHERENT)

DosOpenis called for each name in the list to check if it is a device driver with an associated "DEVICE=" statement in the CONFIG.SYS file. If the call fails, DosLoadModuleis called to check if it is a dynamic link library. If both of these calls fail for any name in the list, the entire device is ignored.

If the optional PTRDEVP() keyword is specified, it defines the names of the physical pointer device drivers. If it is not specified, it defaults to PTRDEVP(POINTER$). The following is an example of a device with only one dynamic link library component and a unique physical pointer device driver for protect mode.

      SET WATERMELON=DEVICE(SEEDLESS) PTRDEVP(PPOINT)

Note:This design is not limited strictly to physical video devices. By writing a device handler, video data could be written to any device, such as a printer or a plotter. In addition, by using alternate initialization entry points, multiple devices can be handled by the same physical device handler.

All of the video device handlers shipped with OS/2 2.1 are dynamic link libraries. They can be defined by the following environment variables, which use the default keywords of PTRDEVP(POINTER$) and PTRDEVR(POINTER$).

      SET VIO_IBMMPA=DEVICE(BVHMPA)
      SET VIO_IBMCGA=DEVICE(BVHCGA)
      SET VIO_IBMEGA=DEVICE(BVHEGA)
      SET VIO_IBMVGA=DEVICE(BVHVGA)
      SET VIO_IBM8514A=DEVICE(BVHVGA,BVH8514A)
      SET VIO_IBM8514A=DEVICE(BVH8514A)
      SET VIO_IBMXGA=DEVICE(BVHXGA)

The following statements define a system with an 8514 display attached to an 8514/A as the only active video device:

      SET VIDEO_DEVICES=VIO_IBM8514A
      SET VIO_IBM8514A=DEVICE(BVHVGA,BVH8514A)

However, the statement below defines a system with an 8514 display attached to an 8514/A, and another PS/2* display attached to the VGA connector, as independent video devices.

      SET VIDEO_DEVICES=VIO_IBMVGA,VIO_IBM8514A
      SET VIO_IBMVGA=DEVICE(BVHVGA)
      SET VIO_IBM8514A=DEVICE(BVH8514A)

Two other device handlers are provided with OS/2. The names of these device drivers are fixed. The Base Video Subsystem loads them automatically as they are needed.

BVHINIT.DLL is the generic device handler used by system installation and system initialization. It provides the minimum function necessary to support installation of the system and reporting of system errors during startup. It is loaded only if no other BVHs are successfully loaded.

BVHWNDW.DLL is the device handler that can support VIO window sessions and that provides the interface to the Presentation Manager interface by treating the PM interface as a virtual video device driver. BVHWNDW.DLL is loaded only for VIO window sessions.

Video Device Chaining

Video device handlers (BVHs) can be chained together when multiple BVHs share the responsibility of supporting a specific video adapter. This is accomplished by allowing previously loaded BVHs to attempt the handling of BVH functions. BVH8514A and BVHXGA are chained BVHs shipped with the product that provides this support.

A VGA and 8514A Scenario

During system initialization, BVHVGA is first called to initialize the Call Vector Table, that is, the table used by BVS to give control to the BVH routines. BVHVGA functions as though no other BVH will be handling the device. Next, BVH8514A is called to initialize the same Call Vector Table. However, BVH8514A saves a copy of the Call Vector Table before changing it.

When calls are made to this chained BVH, BVH8514A receives the call and passes it to the BVHVGA routine through the saved Call Vector Table. If an error occurs or if the results of the routine need to be modified, BVH8514A handles the call. Thus, BVH8514A uses the BVHVGA routines to perform all common functions. Device chainingcan be viewed as a mechanism to allow one BVH to filter function calls to another BVH.

Primary Display Identification

The primary display is the default display chosen by VIO for full-screen sessions. It is also the display on which VIO and hard error pop-ups are shown. Notice that the primary display used by VIO is not necessarily the display on which the Presentation Manager environment runs. The Presentation Manager interface normally runs on the highest resolution display. In a dual-display configuration, the highest resolution display is not necessarily a display that can be used in text mode.

The primary display is the pop-up display. A physical video device driver must determine if it represents the pop-up display. If so, the video device driver must specify that it represents the pop-up display configuration in Query Config Info.

WrtToScrn/Panic Write Support

Before the video subsystem is loaded, and when the system is about to abnormally terminate, messages are sent to the screen by the WrtToScrnfunction, also known as Panic Write. This function switches to real mode and executes the INT 10h function to set the video mode to a text mode ( BIOS mode 3). It then uses BIOS INT 10h, "Write TTY", to display the message.

However, adapters such as the 8514/A have native modes that cannot be changed by INT 10h. In such cases, the BVH must include a Level 0 device driver that hooks INT 10h to provide extended set mode support. This hook must force the adapter out of its native mode, and then pass control to the previous INT 10h support. If these conditions are not satisfied, the adapter should not drive the power up display.

System Installation

The generic device handler, BVHINIT.DLL, is used primarily by system installation. It is also used for those situations when video devices have not been identified in the CONFIG.SYS file. It provides only the functions required for system installation and is otherwise device-independent.

Through VioGetConfigBVHINIT.DLL reports the highest function video adapter and display it can identify. It can identify only the MPA, CGA, EGA, VGA, 8514A, and XGA, along with their respective displays. Although it does not support mode and font setting, it attempts to load the 850 code page for the current EGA or VGA mode during system initialization.

If video devices have not been identified in the CONFIG.SYS file, the generic device handler attempts to load each of the following devices, until one is successfully loaded:

        GENERIC=DEVICE(BVHVGA,BVH8514A)
        GENERIC=DEVICE(BVHVGA)
        GENERIC=DEVICE(BVHEGA)
        GENERIC=DEVICE(BVHCGA)
        GENERIC=DEVICE(BVHINIT)

Loadable Device Drivers

Loadable device drivers present a unique problem when used to support video devices because some video support can be required before the DEVICE= statements have been processed by system initialization. To handle this problem, two different initialization calls are made.

The Enable subfunction determines which type of initialization is to be done. If the subfunction is 1 (Fill Logical Device Block), the DevEnablefunction is requested to add all of the functions supported by the device handler to the Call Vector Table. If the subfunction is 3 (Fill Initialization Device Block), the InitEnablefunction is requested to add only those functions, that can be supported without the use of a loadable device driver to the Call Vector Table.

Regardless of the success of the InitEnablefunction, the DevEnablefunction is called at Shell Initialization time. See DevEnable, and InitEnablefor more information.

Video Device Handler Interfaces

The functions that follow are video primitives reserved for use by OS/2 system components. Unexpected results can occur if these functions are started by applications. All of the video device handler functions described below (except for the DLL Initialization function) use the same calling sequence. Parameters are passed to the routines on the stack. The entry point is found in the BVH Call Vector Table at the index of the function number. The calling sequence used to invoke all the routines is as follows:

     PUSH@    OTHER    Environment        ; Environment buffer
     PUSH@    OTHER    ParmBlock          ; Parameter block
     PUSH     DWORD    Function           ; Function number

     CALL     FAR      BVH Routine Entry Point

Environment:

The environment buffer. The format of this buffer is defined by the BVH developer. The selector is a huge selector.

ParmBlock:

A data structure containing all of the parameters of the operation to be performed. The general format of this structure is:

    Length of parameter block in bytes (=NN)  WORD
    Flags                                     WORD

    Bit 0 indicates whether the physical hardware is updated.

        OFF = Initialize only the environment buffer
        ON  = Initialize the environment buffer and the hardware state

    Bits 1 through 15 are reserved and must be OFF.

The length of the parameter block is the total length, including the length field itself. The number in parentheses ( =NN ) represents the value of this field, if it is a constant.

The first flag bit always indicates a background versus foreground state for this function. If the bit is ON, the adapter is actually updated, as it is when an application is in the foreground. If the bit is OFF, only the buffer that is used to shadow the adapter when an application is in the background is actually updated. All bits that are not currently defined as reserved must be OFF.

Function:

The function identifier for this routine. This corresponds to the offset into the Call Vector Table, and can be used to determine the number of parameters on the stack. This is consistent with the existing DDI used by the Presentation Manager interface. All routines are expected to return with AX = 0 if no error was detected. Otherwise, an error code is returned in AX. The following errors are common to all commands:

    ERROR_VIO_INVALID_LENGTH, if the parameter block length is incorrect.
    ERROR_VIO_INVALID_PARMS,  if a reserved flag bit is non-zero, or if
                              the function number does not match the routine.

DevEnable

This function fills the entries in the Call Vector Table for all of the functions supported by this BVH. It is called as a subfunction of the Presentation Manager enable function entry point. To initialize the Call Vector Table for dynamic link libraries:

    PUSH  DWORD   Parameter2    ; Variable parameter 2
    PUSH  DWORD   Parameter1    ; Variable parameter 1
    PUSH  DWORD   Subfunction   ; Enable subfunction

    CALL  FAR     DevEnable

Parameters

Parameter2 for Subfunction=1

A far pointer to this structure:

    DWORD   Flags Pointer
    DWORD   Call Vector Table

Flags Pointer

Pointer to where the flags that control calls to the Fill Physical Device Block function go.

Call Vector Table

Pointer to the default dispatch table containing the addresses of the default handler functions and the functions supported by this component. Each entry in the Call Vector Table is the far address of a Video Device Handler function, which must be callable from both Ring 2 and Ring 3. The far address of the nth BVH function is the nth DWORD in the table, beginning with Function 0.

The functions listed below are defined as follows:

000h-0FFh (000-255) Reserved for Presentation Manager interface

100h-11Fh (256-287) Reserved for BVS

120h-12Fh (288-303) Reserved for IBM JAPAN

130h-13Fh (304-319) Reserved for MSKK

100h (256) Function 100hText Buffer Update

101h (257) Function 101hInitialize Environment

102h (258) Function 102hSave Environment

103h (259) Function 103hRestore Environment

104h (260) Function 104hQuery Config Info

105h (261) Function 105hDBCS Display Info

106H (262) Function 106hQuery Color Lookup Table

107H (263) Function 107hSet Color Lookup Table

108H (264) Function 108hQuery Cursor Info

109H (265) Function 109hSet Cursor Info

10AH (266) Function 10AhQuery Font

10BH (267) Function 10BhSet Font

10CH (268) Function 10ChQuery Mode

10DH (269) Function 10DhSet Mode

10EH (270) Function 10EhQuery Palette Registers

10Fh (271) Function 10FhSet Palette Registers

110H (272) Function 110hQuery Physical Buffer

111H (273) Function 111hFree Physical Buffer

112H (274) Function 112hQuery Variable Info

113H (275) Function 113hSet Variable Info

114H (276) Function 114hTerminate Environment

115H (277) Function 115hPrint Screen

116H (278) Function 116hWrite TTY

117H (279) Function 117hQuery LVB Info
Parameter1 for Subfunction=1

Far pointer to this structure:

    DWORD   Engine Version
    DWORD   Count of Table Functions

Engine Version

Version of the Presentation Manager Graphics Engine.

Count of Table Functions

The number of entries in the passed dispatch table. The driver can write only this many entries into the table.

Subfunction

The Presentation Manager enable subfunction number. Its value must be 1 to start the Presentation Manager Fill Logical Device Block subfunction. All pieces of the BVH must support this function. Pieces of the BVH that do not support the Presentation Manager interface do not need to support the other functions. Any function not supported will return PMERR_DEV_FUNC_NOT_INSTALLED.

Remarks

This function is supported by the video dynamic link functions and is called only once for each adapter supported by the physical device driver. A video device handler determines if the display adapter and that which the adapter supports is present. If not present, this function returns an error . Every part of a BVH must successfully initialize the Call Vector Table for that device to be usable by the OS/2 operating system.

InitEnable

This function fills the entries in the Call Vector Table for all of the functions supported by this BVH using only SCREEN$ device driver. It is called with parameters similar to the DevEnableentry point specified in DevEnable, except for the Subfunction parameter.

To initialize the Call Vector Table for dynamic link libraries:

    PUSH  DWORD   Parameter2    ; Variable parameter 2
    PUSH  DWORD   Parameter1    ; Variable parameter 1
    PUSH  DWORD   Subfunction   ; Enable subfunction

    CALL  FAR     InitEnable

Parameters

Parameter2 for Subfunction=3

See DevEnable.

Parameter1 for Subfunction=

See DevEnable. Subfunction is the Presentation Manager enable subfunction number. Its value must be 3 to start the Presentation Manager Fill Initialization Device Block subfunction. The default entry point of DevEnablecan be overridden by specifying an alternate name in the DEVICE() parameter describing this BVH in the CONFIG.SYS file.

Remarks

This function is called only if video functions are required before Shell Initialization.

The BVH must be able to support the following subfunctions:

100h (256) Function 100hText Buffer Update

101h (257) Function 101hInitialize Environment

102h (258) Function 102hSave Environment (settable environment only)

103h (259) Function 103hRestore Environment (settable environment only)

104h (260) Function 104hQuery Config Info

105h (261) Function 105hDBCS Display Info

108H (264) Function 108hQuery Cursor Info

109H (265) Function 109hSet Cursor Info

10CH (268) Function 10ChQuery Mode (80x25 text or equivalent only)

10DH (269) Function 10DhSet Mode (80x25 text or equivalent only)

112H (274) Function 112hQuery Variable Info (code page only)

113H (275) Function 113hSet Variable Info (code page only)

See DevEnable.

Text Buffer Update - Function 100h

---

Category:

Function:
100h
Description:
Text Buffer Update

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function performs text updates to the logical and physical video buffers. All references to the buffer are made through the text row and column of each cell affected by the called function.

Function 100h - Description

This function performs text updates to the logical and physical video buffers. All references to the buffer are made through the text row and column of each cell affected by the called function.

Function 100h - Parmlength

Parmlength

Length of the data structure in bytes (greater than, or equal to, 26), including the Lengthfield itself. The maximum length is 44 bytes. Values not passed are assumed to be the default values for the environment.

Function 100h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical video buffer needs to be updated.

      OFF = The physical video buffer must not be updated.
      ON  = The physical video buffer must be updated.

Bit 1 indicates whether the logical video buffer needs to be updated.

      OFF = The logical video buffer may optionally be updated.
      ON  = The logical video buffer must be updated.

Bit 2 indicates that attribute information in the user buffer is in CGA
format and might need to be translated into the format used by the device.
This bit is set for VioWrtTTY calls any time that ANSI is active, because
ANSI recognizes only CGA format attributes.

      OFF = Use attributes in existing format.
      ON  = Translation to or from CGA format required.

Bits 3-15 are reserved and must be OFF.

Function 100h - Selector/Offset of the Application Data Area

Selector/Offset of the Application Data Area

Pointer to the application's data area, which provides either the source or the destination for the buffer operation.

Function 100h - Selector/Offset of the Secondary Data Area

Selector/Offset of the Secondary Data AreaPointer to the additional parameter required by this type of update operation. It is used to define, at most, one cell of information that is used repetitively as filler. This is used only with Index = 3, 4, 5, 6, or 9.

Function 100h - Index

Index

Defined as follows:

     0 = Read Cell Types from (Row,Col) as word of flags:

         Bit 0 indicates whether the cell is part of a single or
               double cell character.

               OFF = The cell represents a single cell character.
               ON  = The cell represents part of a double cell
                       character.  Bit 1 is examined for more
                       information.

         Bit 1 indicates whether the cell is a trailing cell of
               a double cell character.

               OFF = The cell represents the leading or only cell of a
                       character.
               ON  = The cell represents the trailing cell of a double
                       cell character.

         Bits 2 thru 15 are reserved and must be OFF.

     1 = Read Characters from (Row,Col)
     2 = Read Cells from (Row,Col)
     3 = Scroll (Row,Col) through (Row2,Col2) Up
     4 = Scroll (Row,Col) through (Row2,Col2) Down
     5 = Scroll (Row,Col) through (Row2,Col2) Left
     6 = Scroll (Row,Col) through (Row2,Col2) Right
     7 = Write Cells to (Row,Col)
     8 = Write Characters to (Row,Col)
     9 = Write Characters with Constant Attr to (Row,Col)
    10 = Write Repeated Character to (Row,Col)
    11 = Write Repeated Attribute to (Row,Col)
    12 = Write Repeated Cell to (Row,Col)
    13 = Copy LVB Rect to PVB

Function 100h - Starting Row

Starting Row

Defines the text location (row) in the Video Buffer at which the update is to be started. For Function 13, this is the upper-left corner of the rectangle to be written.

Function 100h - Starting Column

Starting Column

Defines the text location (column) in the Video Buffer at which the update is to be started. For Function 13, this is the upper-left corner of the rectangle to be written.

Function 100h - Secondary Row

Secondary Row

Defines the text location (row) in the Video Buffer to which cells will be moved. This is used only when moving cells from one location to another ( Index=3-6). For Function 13, this is the lower-right corner of the rectangle to be written.

Function 100h - Secondary Column

Secondary Column

Defines the text location (column) in the Video Buffer to which cells will be moved. This is used only when moving cells from one location to another (Index=3-6). For Function 13, this is the lower-right corner of the rectangle to be written.

Function 100h - Repeat Factor

Repeat Factor

Repeat factor used when updating the buffer. It represents the number of character cells to be updated, or the number of rows or columns to be scrolled. This is used for both input and output.

Function 100h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.

Function 100h - TouchXLeft

TouchXLeft

The X-coordinate of the upper-left corner of the tightest rectangle that circumscribes the cells touched by the current function. If no cells were touched (as in a Read), -1 is returned. Collectively, this field and the next three fields form an area of influence for the call. This field is returned by the BVH.

Function 100h - TouchYTop

TouchYTop

The Y-coordinate of the upper-left corner of the tightest rectangle that circumscribes the cells touched by the current function. If no cells were touched, -1 is returned. This field is returned by the BVH.

Function 100h - TouchXRight

TouchXRight

The X-coordinate of the lower-right corner of the tightest rectangle that circumscribes the cells touched by the current function. If no cells were touched, -1 is returned. This field is returned by the BVH.

Function 100h - TouchYBottom

TouchYBottom

The Y-coordinate of the lower-right corner of the tightest rectangle that circumscribes the cells touched by the current function. If no cells were touched, -1 is returned. This field is returned by the BVH.

Function 100h - LVBRowOff

LVBRowOff

The row offset of the upper-left corner of the LVB in PVB coordinates. All reads, writes, and scrolls are done in PVB coordinates.

Function 100h - LVBColOff

LVBColOff

The column offset of the upper-left corner of the LVB in PVB coordinates. All reads, writes, and scrolls are done in PVB coordinates.

Function 100h - LVBWidth

LVBWidth

The width of the LVB in cells. Must be greater than 0.

Function 100h - LVBHeight

LVBHeight

The height of the LVB in cells. Must be greater than 0.

Function 100h - LVBFormatID

LVBFormatID

The format ID of the LVB. If this value and attribute count are both 0, the Format ID and attribute count for the current mode are used.

Function 100h - LVBAttrCount

LVBAttrCount

The attribute count for the LVB.

Function 100h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Selector/Offset of the         DWORD     |
|Application Data Area                    |
|-----------------------------------------|
|Selector/Offset of the         DWORD     |
|Secondary Data Area                      |
|-----------------------------------------|
|Index                          WORD      |
|-----------------------------------------|
|Starting Row                   WORD      |
|-----------------------------------------|
|Starting Column                WORD      |
|-----------------------------------------|
|Secondary Row                  WORD      |
|-----------------------------------------|
|Secondary Column               WORD      |
|-----------------------------------------|
|Repeat Factor                  WORD      |
|-----------------------------------------|
|Logical Buffer Selector        WORD      |
|-----------------------------------------|
|TouchXLeft                     WORD      |
|-----------------------------------------|
|TouchYTop                      WORD      |
|-----------------------------------------|
|TouchXRight                    WORD      |
|-----------------------------------------|
|TouchYBottom                   WORD      |
|-----------------------------------------|
|LVBRowOff                      WORD      |
|-----------------------------------------|
|LVBColOff                      WORD      |
|-----------------------------------------|
|LVBWidth                       WORD      |
|-----------------------------------------|
|LVBHeight                      WORD      |
|-----------------------------------------|
|LVBFormatID                    BYTE      |
|-----------------------------------------|
|LVBAttrCount                   BYTE      |
\-----------------------------------------/

Function 100h - Returns

The Text Buffer Update routine returns with AX = 0, if no error was detected. Otherwise, the following error codes are returned in AX:

    ERROR_VIO_COL,              if an invalid column number was specified
    ERROR_VIO_INVALID_LENGTH,   if the ParmLength was incorrect
    ERROR_VIO_INVALID_PARMS,    if the Index was incorrect
    ERROR_VIO_MODE,             if updates are not supported in the
                                  current video mode
    ERROR_VIO_ROW,              if an invalid row number was specified.

Function 100h - Remarks

The Touchxxxxfields circumscribe the area of the LVB, or PVB, for a rectangle that was potentially changed by the given operation. For example, a Write that included the cells (10,12) to (79,12), (0,13) to (79,13), and (0,14) to (8,14) returns TouchXLeft=0, TouchYTop=12, TouchXRight=79, and TouchYBottom=14. Any new functions added to the BVH interface that can affect the data in the PVB or LVB must include a return area for the rectangle of the video buffer that was affected by the given call.

The LVBxxxxfields indicate that an LVB can differ from the normal LVB format. The information about the LVB is taken from these fields, if they are included. Notice that these fields allow an LVB to begin at a location other than (0,0) and allow LVBs of different row and column dimensions.

Function 100h -

Category:

Function:
100h
Description:
Text Buffer Update

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Initialize Environment - Function 101h

---

Category:

Function:
101h
Description:
Initialize Environment

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function causes the Environment Buffer and the video adapter (optional ) to be initialized.

Function 101h - Description

This function causes the Environment Buffer and the video adapter (optional ) to be initialized.

Function 101h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.

Function 101h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware is
      updated.

      OFF = Initialize only the environment buffer.
      ON  = Initialize the environment buffer and the
            hardware state.

Bit 1 indicates whether the 3xBox is being
      initialized.

      OFF = The 3xBox is not being initialized.
      ON  = The 3xBox is being initialized.

Bits 2 thru 15 are reserved and must be OFF.

Function 101h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.

Function 101h - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
\--------------------------------------/

Function 101h - Returns

This routine always returns with AX = 0.

Function 101h - Remarks

It must be possible to call Restore Environment before Save Environment.

Function 101h -

Category:

Function:
101h
Description:
Initialize Environment

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Save Environment - Function 102h

---

Category:

Function:
102h
Description:
Save Environment

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function is used to save all aspects of the video adapter, including the hardware state and the video buffers.

Function 102h - Description

This function is used to save all aspects of the video adapter, including the hardware state and the video buffers.

Function 102h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.

Function 102h - Flags

Flags

Defined as follows:

Bit 0 is reserved and must be Off.

Bit 1 indicates whether hardware state (mode,
      CLUT, everything except the buffer) is saved.

      OFF = The hardware state is not saved.
      ON  = The hardware state is saved.

Bit 2 indicates whether the physical display
      is fully saved for session switching.

      OFF = The physical display is not fully saved.
      ON  = The physical display is fully saved.

Bit 3 indicates whether the physical display
      is partially saved for pop-ups.

      OFF = The physical display is not partially saved.
      ON  = The physical display is partially saved.

Bits 4 thru 15 are reserved and must be OFF.

Function 102h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.

Function 102h - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
\--------------------------------------/

Function 102h - Returns

The Save Environment routine returns with AX = 0 if it can successfully save the environment to the Environment Block and the Logical Video Buffer. Otherwise, it returns with AX = ERROR_VIO_MODE.

Function 102h - Remarks

Bits 2 and 3 are mutually exclusive. If both are specified, bit 3 will be ignored. Bit 4 is used in combination with bits 2 and 3. The code and data segments referenced or accessed to perform the functions selected by bits 1 and 3 must be locked during device driver initialization. The format of the data saved in the segments passed as input is determined by the device handler.

Partial saves are started on VIO and hard error pop-ups. Pop-ups appear on the primary display configuration. The device driver must save whatever portion of the physical display buffer that is overlaid by the pop-up. To display a pop-up, OS/2 2.1 switches to the highest resolution 80 x 25 text mode supported by the primary display configuration (mode 3 or 7, whichever is listed first in the list of modes supported by the display configuration ). Alternatively, if a device driver's physical display buffer is not overlaid by a pop-up, the physical device driver returns zero for partial save size.

When a hard error pop-up occurs before a VIO pop-up has cleared, the Save Environment function is called twice before the Restore Environment is called. Therefore, the device handler must be prepared to handle both a partial save of a graphics mode and a full save of the text mode of the user pop-up.

OS/2 allocates the buffer in which the physical display buffer is saved by using DosAllocHuge. The selector to the Data Packet addresses the first of nsegments in which the physical display buffer is saved. (The offset to the Data Packet should be ignored.) The selector to the second segment can be calculated by adding the DosAllocHugeincrement to the first selector value. The third selector can similarly be calculated by adding the DosAllocHugeincrement to the second selector value, and so forth. Enough selectors are allocated to meet the full/partial buffer requirement specified by the physical device driver. The selectors each address 64KB except the last selector, which addresses the remainder.

Function 102h -

Category:

Function:
102h
Description:
Save Environment

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Restore Environment - Function 103h

---

Category:

Function:
103h
Description:
Restore Environment

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function is used to restore all aspects of the video adapter, including the hardware state and the video buffers.

Function 103h - Description

This function is used to restore all aspects of the video adapter, including the hardware state and the video buffers.

Function 103h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.

Function 103h - Flags

Flags

Defined as follows:

Bit 0 is reserved and must be Off.

Bit 1 indicates whether hardware state (mode,
      CLUT, everything except the buffer) is saved.

      OFF = The hardware state is not restored.
      ON  = The hardware state is restored.

Bit 2 indicates whether the physical display
      is fully restored for session switching.

      OFF = The physical display is not fully restored.
      ON  = The physical display is fully restored.

Bit 3 indicates whether the physical display
      is partially restored for pop-ups.

      OFF = The physical display is not partially restored.
      ON  = The physical display is partially restored.

Bits 4 thru 15 are reserved and must be OFF.

Function 103h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.

Function 103h - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
\--------------------------------------/

Function 103h - Returns

The Restore Environment routine returns with AX = 0 if it can successfully restore the environment to the Environment Block and the Logical Video Buffer. Otherwise, it returns with AX = ERROR_VIO_MODE. See Function 102hfor more information.

Function 103h - Remarks

None.

Function 103h -

Category:

Function:
103h
Description:
Restore Environment

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query Config Info - Function 104h

---

Category:

Function:
104h
Description:
Query Config Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function returns all of the information necessary to identify the current video adapter and display.

Function 104h - Description

This function returns all of the information necessary to identify the current video adapter and display.

Function 104h - Parmlength

Parmlength

Length of parameter block in bytes (=8) passed on input.

Function 104h - Flags

Flags

Must be zero.

Function 104h - Parameter Packet Format

/-------------------------\
|Field          Length    |
|-------------------------|
|Parmlength     WORD      |
|-------------------------|
|Flags          WORD      |
\-------------------------/

Function 104h - Returns

This function returns with AX = ERROR_VIO_INVALID_LENGTH only if the Length specified is less than 2.

Function 104h - Remarks

The Environment Buffer is not used by this function. The Environment Buffer address is passed as a DWORD of zero. If the Length specified in the Config Data is larger than the maximum possible length, or if the Length is specified as 2 (the length of Length field itself), it is replaced by the largest valid length.

Function 104h -

Category:

Function:
104h
Description:
Query Config Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

DBCS Display Info - Function 105h

---

Category:

Function:
105h
Description:
DBCS Display Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function returns various forms of DBCS information used by the display .

Function 105h - Description

This function returns various forms of DBCS information used by the display .

Function 105h - Parmlength

Parmlength

Length of parameter block in bytes. If Length is specified as 2, only the maximum length of the parameter block is returned in the length field. If the length is not 2, it defines the maximum amount of data returned.

Function 105h - Flags

Flags

Must be zero.

Function 105h - DBCS Table Length

DBCS Table Length

Length of double cell character table.

Function 105h - DBCS Table Offset

DBCS Table Offset

Offset of double-cell character table, which consists of WORD pairs that define the low and high limits (inclusive) of ranges of double-cell characters.

Function 105h - Parameter Packet Format

/--------------------------------\
|Field                 Length    |
|--------------------------------|
|Parmlength            WORD      |
|--------------------------------|
|Flags                 WORD      |
|--------------------------------|
|DBCS Table Length     WORD      |
|--------------------------------|
|DBCS Table Offset     WORD      |
\--------------------------------/

Function 105h - Returns

This function is used to get the DBCS display information associated with the given environment buffer, and returns with AX = ERROR_VIO_INVALID_ LENGTH if the Length specified is less than 2 or the buffer was too short to return all of the DBCS display information. Otherwise, Query DBCS Display Info returns with AX = 0.

Function 105h - Remarks

None.

Function 105h -

Category:

Function:
105h
Description:
DBCS Display Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query Color Lookup Table - Function 106h

---

Category:

Function:
106h
Description:
Query Color Lookup Table

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function reads the definitions of the colors from the Color Lookup Table.

Function 106h - Description

This function reads the definitions of the colors from the Color Lookup Table.

Function 106h - Parmlength

Parmlength

Length of parameter block in bytes (=12) passed on input.

Function 106h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

Bits 1-15 are reserved and must be OFF.

Function 106h - Color Lookup Table Far Address

Color Lookup Table Far Address

Far address of Color Lookup Table. The Table format is device-dependent. Three-byte table entries are returned for the VGA. Each table entry contains a red, green, and blue color index, respectively.

Function 106h - Index

Index

Index of the first table entry to get.

Function 106h - Table Entry Quantity

Table Entry Quantity

Number of table entries to get. Three-byte table entries are returned for the VGA. Each table entry contains a red, green, and blue color index, respectively.

Function 106h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Color Lookup Table Far Address DWORD     |
|-----------------------------------------|
|Index                          WORD      |
|-----------------------------------------|
|Table Entry Quantity           WORD      |
\-----------------------------------------/

Function 106h - Returns

This function returns with AX = 0 if it can successfully get all of the requested registers from the Color Lookup Table. Otherwise, this routine returns with AX = ERROR_VIO_INVALID_PARMS if an invalid color register was requested, or AX = ERROR_VIO_INVALID_LENGTH if too many registers were requested.

Function 106h - Remarks

None.

Function 106h -

Category:

Function:
106h
Description:
Query Color Lookup Table

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Set Color Lookup Table - Function 107h

---

Category:

Function:
107h
Description:
Set Color Lookup Table

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function loads the definitions of the colors from the Color Lookup Table.

Function 107h - Description

This function loads the definitions of the colors from the Color Lookup Table.

Function 107h - Parmlength

Parmlength

Length of parameter block in bytes (=12) passed on input.

Function 107h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware is
      updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

Bits 1-15 are reserved and must be OFF.

Function 107h - Color Lookup Table Far Address

Color Lookup Table Far Address

Far address of Color Lookup Table. The Table format is device-dependent. The VGA format has three bytes containing the red, green and blue indices, respectively, for each color being set.

Function 107h - Index

Index

Index of the first table entry to set.

Function 107h - Table Entry Quantity

Table Entry Quantity

Number of table entries to set.

Function 107h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Color Lookup Table Far Address DWORD     |
|-----------------------------------------|
|Index                          WORD      |
|-----------------------------------------|
|Table Entry Quantity           WORD      |
\-----------------------------------------/

Function 107h - Returns

This function returns with AX = 0 if it can successfully set all of the registers in the Color Lookup Table. Otherwise, it returns with AX = ERROR_ VIO_INVALID_PARMS if an invalid color register was requested, or AX = ERROR _VIO_INVALID_LENGTH if too many registers were requested.

Function 107h - Remarks

None.

Function 107h -

Category:

Function:
107h
Description:
Set Color Lookup Table

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query Cursor Info - Function 108h

---

Category:

Function:
108h
Description:
Query Cursor Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function returns all of the information related to the cursor.

Function 108h - Description

This function returns all of the information related to the cursor.

Function 108h - Parmlength

Parmlength

Length of parameter block in bytes (=16) passed on input.

Function 108h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

The remaining flags select the information to be
returned:

Bit 1 selects cursor position.
Bit 2 selects cursor type.
Bits 3-15 are reserved and must be Off.

Function 108h - Row

Row

0 is the top row.

Function 108h - Column

Column

0 is the left column.

Function 108h - Top Cursor Scan Line

Top Cursor Scan Line

If n scan lines, 0 is top scan line and n-1 is bottom scan line.

Function 108h - Bottom Cursor Scan Line

Bottom Cursor Scan Line

If n scan lines, 0 is top scan line and n-1 is bottom scan line.

Function 108h - Cursor Width

Cursor Width

Cursor width in columns, if text mode; in pels, if graphics mode.

Function 108h - Cursor Attribute

Cursor Attribute

Cursor attribute: -1 = hidden, if text mode; other values = color attribute, if graphics mode.

Function 108h - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Row                         WORD      |
|--------------------------------------|
|Column                      WORD      |
|--------------------------------------|
|Top Cursor Scan Line        WORD      |
|--------------------------------------|
|Bottom Cursor Scan Line     WORD      |
|--------------------------------------|
|Cursor Width                WORD      |
|--------------------------------------|
|Cursor Attribute            WORD      |
\--------------------------------------/

Function 108h - Returns

This function returns with AX = 0 if it can successfully get all of the cursor information requested. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS.

Function 108h - Remarks

None.

Function 108h -

Category:

Function:
108h
Description:
Query Cursor Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Set Cursor Info - Function 109h

---

Category:

Function:
109h
Description:
Set Cursor Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function sets all of the information related to the cursor.

Function 109h - Description

This function sets all of the information related to the cursor.

Function 109h - Parmlength

Parmlength

Length of parameter block in bytes (=16) passed on input.

Function 109h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware is
      updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

The remaining flags select the options to be set:

Bit 1 selects cursor position.
Bit 2 selects cursor type.
Bits 3-15 are reserved and must be OFF.

Function 109h - Row

Row

0 is the top row.

Function 109h - Column

Column

0 is the left column.

Function 109h - Top Cursor Scan Line

Top Cursor Scan Line

If n scan lines, 0 is top scan line and n-1 is bottom scan line.

Function 109h - Bottom Cursor Scan Line

Bottom Cursor Scan Line

If n scan lines, 0 is top scan line and n-1 is bottom scan line.

Function 109h - Cursor Width

Cursor Width

Cursor width in columns, if text mode; in pels, if graphics mode.

Function 109h - Cursor Attribute

Cursor Attribute

Cursor attribute: -1 = hidden, if text mode; other values = color attribute, if graphics mode.

Function 109h - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Row                         WORD      |
|--------------------------------------|
|Column                      WORD      |
|--------------------------------------|
|Top Cursor Scan Line        WORD      |
|--------------------------------------|
|Bottom Cursor Scan Line     WORD      |
|--------------------------------------|
|Cursor Width                WORD      |
|--------------------------------------|
|Cursor Attribute            WORD      |
\--------------------------------------/

Function 109h - Returns

This function returns with AX = 0 if it can successfully set all of the cursor information requested. Otherwise, it returns with AX equal to:

     ERROR_VIO_MODE if it cannot support the function
       in the current mode
     ERROR_VIO_ROW if the row number is out of range
     ERROR_VIO_COL if the column number is out of range

Function 109h - Remarks

None.

Function 109h -

Category:

Function:
109h
Description:
Set Cursor Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query Font - Function 10Ah

---

Category:

Function:
10Ah
Description:
Query Font

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function returns the current active font or a selected font for the current code page. The format of the font definition is determined by the type of adapter.

Function 10Ah - Description

This function returns the current active font or a selected font for the current code page. The format of the font definition is determined by the type of adapter.

Function 10Ah - Parmlength

Parmlength

Length of parameter block in bytes (=14) passed on input.

Function 10Ah - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer
            only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

Bit 1 indicates whether a specific font is to be
      returned instead of the current font.

      OFF = Return the current font.
      ON  = Return the selected font for the current code
            page.  Setting this flag indicates that the pel
            columns and rows are used as input to select
            the font.

Bits 2-15 are reserved and must be OFF.

Function 10Ah - Font Buffer Far Address

Font Buffer Far Address

Data area in which the font definition is returned.

Function 10Ah - Data Area Length

Data Area Length

Length of data area in which font table is returned.

Function 10Ah - Pel Columns

Pel Columns

Pel columns.

Function 10Ah - Pel Rows

Pel Rows

Pel rows.

Function 10Ah - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Font Buffer Far Address     DWORD     |
|--------------------------------------|
|Data Area Length            WORD      |
|--------------------------------------|
|Pel Columns                 WORD      |
|--------------------------------------|
|Pel Rows                    WORD      |
\--------------------------------------/

Function 10Ah - Returns

If the Length is specified as 0, no font is returned. Instead, the Length field returns the size needed to hold the font. Query Font returns with AX = 0 if it can successfully read the font. Otherwise, it returns with AX = ERROR_VIO_INVALID_PARMS.

Function 10Ah - Remarks

None.

Function 10Ah -

Category:

Function:
10Ah
Description:
Query Font

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Set Font - Function 10Bh

---

Category:

Function:
10Bh
Description:
Set Font

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function sends a user font definition to the device handler. If the font is appropriate for the current mode, it is loaded into the adapter. If not, it is saved for possible use on subsequent calls to SetMode. The format of the font definition is determined by the type of adapter.

Function 10Bh - Description

This function sends a user font definition to the device handler. If the font is appropriate for the current mode, it is loaded into the adapter. If not, it is saved for possible use on subsequent calls to SetMode. The format of the font definition is determined by the type of adapter.

Function 10Bh - Parmlength

Parmlength

Length of parameter block in bytes (=14) passed on input.

Function 10Bh - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

Bits 1-15 are reserved and must be OFF.

Function 10Bh - Font Buffer Far Address

Font Buffer Far Address

Far address of the font buffer containing the font set in compact form.

Function 10Bh - Data Area Length

Data Area Length

Length of data area containing the font table to be set.

Function 10Bh - Pel Columns

Pel Columns

Pel columns.

Function 10Bh - Pel Rows

Pel Rows

Pel rows.

Function 10Bh - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Font Buffer Far Address     DWORD     |
|--------------------------------------|
|Data Area Length            WORD      |
|--------------------------------------|
|Pel Columns                 WORD      |
|--------------------------------------|
|Pel Rows                    WORD      |
\--------------------------------------/

Function 10Bh - Returns

This function returns with AX = 0 if it can successfully load the font. Otherwise, it returns with AX = ERROR_VIO_INVALID_PARMS.

Function 10Bh - Remarks

None.

Function 10Bh -

Category:

Function:
10Bh
Description:
Set Font

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query Mode - Function 10Ch

---

Category:

Function:
10Ch
Description:
Query Mode

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function returns all of the information pertaining to the current video mode.

Function 10Ch - Description

This function returns all of the information pertaining to the current video mode.

Function 10Ch - Parmlength

Parmlength

Length of parameter block in bytes (=8) passed on input.

Function 10Ch - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware is to
      be read.

      OFF = Return data from the environment buffer only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

Bits 1-15 are reserved and must be OFF.

Function 10Ch - Mode Data Structure Far Address

Mode Data Structure Far Address

Far Address of the Mode data structure defined by VioGetMode.

Function 10Ch - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Mode Data Structure Far        DWORD     |
|Address                                  |
\-----------------------------------------/

Function 10Ch - Returns

If the Length specified in the Config Data is larger than the maximum possible length or if the Length is specified as 2, it is replaced by the largest valid length. This function returns with AX = ERROR_VIO_INVALID_ LENGTH only if the Length specified is less than 2.

Function 10Ch - Remarks

None.

Function 10Ch -

Category:

Function:
10Ch
Description:
Query Mode

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Set Mode - Function 10Dh

---

Category:

Function:
10Dh
Description:
Set Mode

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function sets the video mode of the video adapter. For text modes, it considers not only what display characteristics it can support but also what ROM, code page, and user-defined fonts it has available.

Function 10Dh - Description

This function sets the video mode of the video adapter. For text modes, it considers not only what display characteristics it can support but also what ROM, code page, and user-defined fonts it has available.

Function 10Dh - Datalength

Datalength

Length of the data structure in bytes, including Length itself (=8).

Function 10Dh - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

Bit 1 indicates whether the mode is changed
      or only validated.

      OFF = Perform normal mode setting.
      ON  = Perform only mode validation.

Bits 2-15 are reserved and must be OFF.

Function 10Dh - Mode Data Structure Far Address

Mode Data Structure Far Address

Far Address of the Mode data structure defined by VioSetMode.

Function 10Dh - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Datalength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Mode Data Structure Far        DWORD     |
|Address                                  |
\-----------------------------------------/

Function 10Dh - Returns

Set Mode returns with AX = 0 if it can set the requested mode. Otherwise, it returns with AX = ERROR_VIO_MODE.

Function 10Dh - Remarks

This function must validate the mode data without using the environment buffer, because it might not have been initialized or might not be valid for this device. This function implicitly initializes the environment buffer if it has not already been done.

Function 10Dh -

Category:

Function:
10Dh
Description:
Set Mode

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query Palette Registers - Function 10Eh

---

Category:

Function:
10Eh
Description:
Query Palette Registers

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function queries the relationship between the text attributes and the color registers.

Function 10Eh - Description

This function queries the relationship between the text attributes and the color registers.

Function 10Eh - Datalength

Datalength

Length of parameter block in bytes (=12) passed on input.

Function 10Eh - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer
            only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

Bits 1-15 are reserved and must be OFF.

Function 10Eh - Palette Buffer Far Address

Palette Buffer Far Address

Data area where a 1-WORD entry for each register containing its color value is returned.

Function 10Eh - Palette Register Index

Palette Register Index

Index of first palette register to get.

Function 10Eh - Register Quantity

Register Quantity

Number of registers to return.

Function 10Eh - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Datalength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Palette Buffer Far Address     DWORD     |
|-----------------------------------------|
|Palette Register Index         WORD      |
|-----------------------------------------|
|Register Quantity              WORD      |
\-----------------------------------------/

Function 10Eh - Returns

This function returns with AX = 0 if it can successfully get all of the requested palette registers. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS if an invalid color register was requested, or AX = ERROR_VIO _INVALID_LENGTH if too many registers were requested.

Function 10Eh - Remarks

None.

Function 10Eh -

Category:

Function:
10Eh
Description:
Query Palette Registers

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Set Palette Registers - Function 10Fh

---

Category:

Function:
10Fh
Description:
Set Palette Registers

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function defines the relationship between the text attributes and the color registers.

Function 10Fh - Description

This function defines the relationship between the text attributes and the color registers.

Function 10Fh - Parmlength

Parmlength

Length of parameter block in bytes (=12) passed on input.

Function 10Fh - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

Bits 1-15 are reserved and must be OFF.

Function 10Fh - Palette Buffer Far Address

Palette Buffer Far Address

Far address of palette register buffer. Data area with 1 WORD, containing the color value for each register set.

Function 10Fh - Palette Register Index

Palette Register Index

Index of first palette register to set. Data area with 1 WORD, containing the color value for each register set.

Function 10Fh - Register Quantity

Register Quantity

Number of registers to set.

Function 10Fh - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Palette Buffer Far Address     DWORD     |
|-----------------------------------------|
|Palette Register Index         WORD      |
|-----------------------------------------|
|Register Quantity              WORD      |
\-----------------------------------------/

Function 10Fh - Returns

This function returns with AX = 0 if it can successfully set all of the requested palette registers. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS if an invalid color register was requested, or AX = ERROR_VIO _INVALID_LENGTH if too many registers were requested.

Function 10Fh - Remarks

None.

Function 10Fh -

Category:

Function:
10Fh
Description:
Set Palette Registers

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query Physical Buffer - Function 110h

---

Category:

Function:
110h
Description:
Query Physical Buffer

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function returns an LDT selector that can be used to access the physical video buffer. The current physical video buffer is returned unless a specific address range is requested.

Function 110h - Description

This function returns an LDT selector that can be used to access the physical video buffer. The current physical video buffer is returned unless a specific address range is requested.

Function 110h - Parmlength

Parmlength

Length of parameter block in bytes (=12) passed on input.

Function 110h - Flags

Flags

Must be zero.

Function 110h - Query Physical Buffer Far Address

Query Physical Buffer Far Address

Far Address of the Query Physical Buffer data structure defined by VioGetPhysBuf.

Function 110h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Query Physical Buffer Far      DWORD     |
|Address                                  |
\-----------------------------------------/

Function 110h - Returns

Query Physical Buffer returns with AX = 0 if it can successfully allocate the LDT selector. Otherwise, it returns with AX set by the PhysToUVirtdevice helper function or with AX = ERROR_VIO_INVALID_PARMS if the requested buffer resides outside the valid range for the device.

Function 110h - Remarks

If the physical display buffer address and length passed on input are 0, this subfunction returns an LDT selector, that corresponds to the current mode.

A physical video device driver must provide Read/Write access to the physical address range where the physical display buffer is located. The physical device driver must provide Read-only access to the physical address range where the ROM fonts are located. If the physical address passed on input is not within the physical display buffer or ROM font ranges, an error is returned.

Function 110h -

Category:

Function:
110h
Description:
Query Physical Buffer

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Free Physical Buffer - Function 111h

---

Category:

Function:
111h
Description:
Free Physical Buffer

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function deallocates an LDT selector that was acquired by a call to the Query Physical Buffer routine.

Function 111h - Description

This function deallocates an LDT selector that was acquired by a call to the Query Physical Buffer routine.

Function 111h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.

Function 111h - Flags

Flags Must be zero.

Function 111h - LDT Selector

LDT Selector

LDT Selector.

Function 111h - Parameter Packet Format

/---------------------------\
|Field            Length    |
|---------------------------|
|Parmlength       WORD      |
|---------------------------|
|Flags            WORD      |
|---------------------------|
|LDT Selector     DWORD     |
\---------------------------/

Function 111h - Returns

This function always returns with AX = 0.

Function 111h - Remarks

None.

Function 111h -

Category:

Function:
111h
Description:
Free Physical Buffer

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query Variable Info - Function 112h

---

Category:

Function:
112h
Description:
Query Variable Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function reads various minor features of the video adapter, including the blink state, border color, underscore line, and scrollable rectangle of the screen.

Function 112h - Description

This function reads various minor features of the video adapter, including the blink state, border color, underscore line, and scrollable rectangle of the screen.

Function 112h - Parmlength

Parmlength

Length of parameter block in bytes (=26) passed on input.

Function 112h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is to be read.

      OFF = Return data from the environment buffer
            only.
      ON  = Read the hardware to update the environment
            buffer before returning the requested data.

The remaining flags select the information to be
returned:

Bit 1 selects blink versus background color.
Bit 2 selects overscan (border) color.
Bit 3 selects scan line for underscore.
Bit 4 selects video enable.
Bit 5 selects the display mask.
Bit 6 selects code page.
Bit 7 forces a code page set (used with 6).
Bit 8 gets the scrollable rectangle.
Bits 9-15 are reserved and must be OFF.

Function 112h - Blink/Background Intensity

Blink/Background Intensity

Blink versus background intensity:

        0 = blink.
        1 = background intensity.

Function 112h - Overscan (border) Color

Overscan (border) ColorOverscan (border) Color.

Function 112h - Scan Line

Scan Line

Scan line for underscore (0-31); 32 = no underscore.

Function 112h - Video Enable

Video Enable

Video enable: 0 = OFF and 1 = ON. OFF means off until the physical device driver is told to turn it back on. If the video signal is turned off and then the mode is set, the signal must remain off.

Function 112h - Display Mask

Display Mask

Display mask:

   bit 0  = plane 0
     �         �
     �         �
     �         �
   bit 31 = plane 31

   bit state = 0, plane disabled for display.
   bit state = 1, plane enabled for display.

   (Planes disabled for display result in 0 to palette.)

Function 112h - Code Page

Code Page

Code Page.

Function 112h - Scrollable Rectangle - Left

Scrollable Rectangle - Left

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.

Function 112h - Scrollable Rectangle - Top

Scrollable Rectangle - Top

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.

Function 112h - Scrollable Rectangle - Right

Scrollable Rectangle - Right

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.

Function 112h - Scrollable Rectangle - Bottom

Scrollable Rectangle - Bottom

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.

Function 112h - Screen Rows

Screen Rows

The number of text rows in the current mode.

Function 112h - Screen Columns

Screen Columns

The number of text columns in the current mode.

Function 112h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Blink/Background Intensity     WORD      |
|-----------------------------------------|
|Overscan (border) Color        WORD      |
|-----------------------------------------|
|Scan Line                      WORD      |
|-----------------------------------------|
|Video Enable                   WORD      |
|-----------------------------------------|
|Display Mask                   DWORD     |
|-----------------------------------------|
|Code Page                      WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Left    WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Top     WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Right   WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Bottom  WORD      |
|-----------------------------------------|
|Screen Rows                    WORD      |
|-----------------------------------------|
|Screen Columns                 WORD      |
\-----------------------------------------/

Function 112h - Returns

Query Variable Info returns with AX = 0 if it can successfully get the selected variable information. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS.

Function 112h - Remarks

None.

Function 112h -

Category:

Function:
112h
Description:
Query Variable Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Set Variable Info - Function 113h

---

Category:

Function:
113h
Description:
Set Variable Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function sets the minor features of the video adapter, including the blink state, border color, underscore line, and scrollable rectangle of the screen.

Function 113h - Description

This function sets the minor features of the video adapter, including the blink state, border color, underscore line, and scrollable rectangle of the screen.

Function 113h - Parmlength

Parmlength

Length of parameter block in bytes (=26) passed on input.

Function 113h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical hardware
      is updated.

      OFF = Update only the environment buffer.
      ON  = Update the environment buffer and the
            hardware state.

The remaining flags select the information to be set:

Bit 1 selects blink versus background color.
Bit 2 selects overscan (border) color.
Bit 3 selects scan line for underscore.
Bit 4 selects video enable.
Bit 5 selects the display mask.
Bit 6 selects code page.
Bit 7 forces a code page set (used with 6).
Bit 8 gets the scrollable rectangle.
Bits 9-15 are reserved and must be OFF.

Function 113h - Blink/Background Intensity

Blink/Background Intensity

Blink versus background intensity:

        0 = blink.
        1 = background intensity.

Function 113h - Overscan (border) Color

Overscan (border) Color

Overscan (border) Color.

Function 113h - Scan Line

Scan Line

Scan line for underscore (0-31); 32 = no underscore.

Function 113h - Video Enable

Video Enable

Video enable: 0 = OFF and 1 = ON. OFF means off until the physical device driver is told to turn it back on. If the video signal is turned off and then the mode is set, the signal must remain off.

Function 113h - Display Mask

Display Mask

Display mask:

   bit 0  = plane 0
     �         �
     �         �
     �         �
   bit 31 = plane 31

   bit state = 0, plane disabled for display.
   bit state = 1, plane enabled for display.

   (Planes disabled for display result in 0 to palette.)

Function 113h - Code Page

Code Page

Code Page.

Function 113h - Scrollable Rectangle - Left

Scrollable Rectangle - Left

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.

Function 113h - Scrollable Rectangle - Top

Scrollable Rectangle - Top

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.

Function 113h - Scrollable Rectangle - Right

Scrollable Rectangle - Right

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.

Function 113h - Scrollable Rectangle - Bottom

Scrollable Rectangle - Bottom

The scrollable rectangle fields indicate the area of the screen that can scroll during scroll and write TTY operations.

Function 113h - Screen Rows

Screen Rows

The number of text rows in the current mode. Reserved (0).

Function 113h - Screen Columns

Screen Columns

The number of text columns in the current mode. Reserved (0).

Function 113h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Blink/Background Intensity     WORD      |
|-----------------------------------------|
|Overscan (border) Color        WORD      |
|-----------------------------------------|
|Scan Line                      WORD      |
|-----------------------------------------|
|Video Enable                   WORD      |
|-----------------------------------------|
|Display Mask                   DWORD     |
|-----------------------------------------|
|Code Page                      WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Left    WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Top     WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Right   WORD      |
|-----------------------------------------|
|Scrollable Rectangle - Bottom  WORD      |
|-----------------------------------------|
|Screen Rows                    WORD      |
|-----------------------------------------|
|Screen Columns                 WORD      |
\-----------------------------------------/

Function 113h - Returns

Set Variable Info returns with AX = 0 if it can successfully set the selected variable information. Otherwise, it returns with AX = ERROR_VIO_ INVALID_PARMS.

Function 113h - Remarks

There are two types of code page sets. The first code page set allows a code page to be set while the mode of the display (as used by Function 10Dh ) remains the same. The other type of code page set causes a change in the display mode. This occurs when switching between DBCS and non-DBCS code pages.

If bit 6 of the flags WORD is set and bit 7 is clear, the code page is set when the adapter can use the code page without changing from DBCS mode to SBCS mode, or vice versa. The mode should be changed if both bits 6 and 7 of the flags WORD are set, and the code page is used when the mode is changed from SBCS mode to DBCS mode. Bit 7 is ignored if bit 6 is not set. This applies only to text modes. Graphics modes are not set to text modes by forcing a code page.

The BVH need not support any scrollable region other than the entire display area. The adapter may support any scrollable rectangle up to the size of the entire screen. All coordinates are in text display cells. This scrollable rectangle data is undefined for graphics modes.

Function 113h -

Category:

Function:
113h
Description:
Set Variable Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Terminate Environment - Function 114h

---

Category:

Function:
114h
Description:
Terminate Environment

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function is used to notify the BVH that the environment is about to be freed so that any required cleanup can be performed by the BVH. If no Terminate Environment processing is required, this function can be omitted. PMERR_DEV_FUNC_NOT_INSTALLED is then returned in AX, but it is ignored by the video subsystem.

Function 114h - Description

This function is used to notify the BVH that the environment is about to be freed so that any required cleanup can be performed by the BVH. If no Terminate Environment processing is required, this function can be omitted. PMERR_DEV_FUNC_NOT_INSTALLED is then returned in AX, but it is ignored by the video subsystem.

Function 114h - Parmlength

Parmlength

Length of parameter block in bytes (=6) passed on input.

Function 114h - Flags

Flags

Reserved, must be off.

Function 114h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.

Function 114h - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
\--------------------------------------/

Function 114h - Returns

None.

Function 114h - Remarks

None.

Function 114h -

Category:

Function:
114h
Description:
Terminate Environment

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Print Screen - Function 115h

---

Category:

Function:
115h
Description:
Print Screen

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function causes the contents of the current screen to be written to the printer handle provided. BVS provides a default routine that provides the same level of support as previous versions if the vector is not replaced.

Function 115h - Description

This function causes the contents of the current screen to be written to the printer handle provided. BVS provides a default routine that provides the same level of support as previous versions if the vector is not replaced.

Function 115h - Parmlength

Parmlength

Length of parameter block in bytes (=8) passed on input.

Function 115h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical video
      buffer should be printed.

      OFF = Print only the contents of the logical
            video buffer.
      ON  = Print the contents of the physical
            video buffer, if appropriate.

Bits 1-15 are reserved and must be OFF.

Function 115h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.

Function 115h - Print Device Handle

Print Device Handle

Print Device Handle. File handle of the print device to be used.

Function 115h - Parameter Packet Format

/--------------------------------------\
|Field                       Length    |
|--------------------------------------|
|Parmlength                  WORD      |
|--------------------------------------|
|Flags                       WORD      |
|--------------------------------------|
|Logical Buffer Selector     WORD      |
|--------------------------------------|
|Print Device Handle         WORD      |
\--------------------------------------/

Function 115h - Returns

None.

Function 115h - Remarks

None.

Function 115h -

Category:

Function:
115h
Description:
Print Screen

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Write TTY - Function 116h

---

Category:

Function:
116h
Description:
Write TTY

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function performs the functions of the call to VioWrtTTY. BVS provides a default routine that provides the same level of support as previous versions if the vector is not replaced.

Function 116h - Description

This function performs the functions of the call to VioWrtTTY. BVS provides a default routine that provides the same level of support as previous versions if the vector is not replaced.

Function 116h - Parmlength

Parmlength

Length of parameter block in bytes (=14) passed on input.

Function 116h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical video
      buffer needs to be updated.

      OFF = The physical video buffer must not be
            updated.
      ON  = The physical video buffer must be updated.

Bit 1 indicates whether the logical video buffer
      needs to be updated.

      OFF = The logical video buffer can optionally be
            updated.
      ON  = The logical video buffer must be updated.

Bit 2 indicates whether ANSI is active.

      OFF = ANSI is not active.  Escape sequences should
            be considered as text data.
      ON  = ANSI is active.  Escape sequences must be
            handled locally or passed to the default
            routine in BVS through device chaining.

Bit 3 indicates whether Ctrl_PrtSc is active.

      OFF = Ctrl_PrtSc is not active.
      ON  = Ctrl_PrtSc is active.  Characters need to
            be echoed to the printer locally or by the
            default routine in BVS through device chaining.

Bits 4-15 are reserved and must be OFF.

Function 116h - Logical Buffer Selector

Logical Buffer Selector

Selector used for the beginning of the logical video buffer. This selector is a huge selector with a maximum size of 1MB.

Function 116h - Character String Far Address

Character String Far Address

Far Address of character string to be written.

Function 116h - Character String Length

Character String Length

Length of character string to be written.

Function 116h - Print Device Handle

Print Device Handle

Print Device Handle. The file handle of the print device used for Ctrl_ PrtSc.

Function 116h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|Logical Buffer Selector        WORD      |
|-----------------------------------------|
|Character String Far Address   DWORD     |
|-----------------------------------------|
|Character String Length        DWORD     |
|-----------------------------------------|
|Print Device Handle            WORD      |
\-----------------------------------------/

Function 116h - Returns

None.

Function 116h - Remarks

None.

Function 116h -

Category:

Function:
116h
Description:
Write TTY

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Query LVB Info - Function 117h

---

Category:

Function:
117h
Description:
Query LVB Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

---

This function returns information associated with the LVB, such as the allocation size and default attribute for a specified LVB.

Function 117h - Description

This function returns information associated with the LVB, such as the allocation size and default attribute for a specified LVB.

Function 117h - Parmlength

Parmlength

Length of parameter block in bytes (=20) passed on input.

Function 117h - Flags

Flags

Defined as follows:

Bit 0 indicates whether the physical
      hardware is to be read.

      OFF = Read from the environment buffer.
      ON  = Read from the current state of the
            hardware state.

Bits 1-15 are reserved and must be OFF.

Function 117h - LVB Format ID

LVB Format ID

Format ID for LVB. If this and the attribute count are both 0, the current mode values are used.

Function 117h - LVB Attribute Count

LVB Attribute Count

Attribute Count for the LVB. If this and the format ID are both 0, the current mode values are used.

Function 117h - LVB Width

LVB Width

LVB Width in cells.

Function 117h - LVB Height

LVB Height

LVB Height in cells.

Function 117h - LVB Allocation Size

LVB Allocation Size

Allocation size of the LVB is returned here.

Function 117h - Attribute Return Buffer Size

Attribute Return Buffer Size

Size of the default attribute return buffer.

Function 117h - Attribute Return Buffer Pointer

Attribute Return Buffer Pointer

Pointer to the default attribute return buffer (passed). The default attribute is returned if the buffer is large enough. If this value is 0, the attribute is not returned.

Function 117h - Parameter Packet Format

/-----------------------------------------\
|Field                          Length    |
|-----------------------------------------|
|Parmlength                     WORD      |
|-----------------------------------------|
|Flags                          WORD      |
|-----------------------------------------|
|LVB Format ID                  BYTE      |
|-----------------------------------------|
|LVB Attribute Count            BYTE      |
|-----------------------------------------|
|LVB Width                      WORD      |
|-----------------------------------------|
|LVB Height                     WORD      |
|-----------------------------------------|
|LVB Allocation Size            DWORD     |
|-----------------------------------------|
|Attribute Return Buffer Size   WORD      |
|-----------------------------------------|
|Attribute Return Buffer        DWORD     |
|Pointer                                  |
\-----------------------------------------/

Function 117h - Returns

This function returns with AX = 0 if it can successfully calculate the LVB size and return the attribute information. Otherwise, it returns with AX = ERROR_VIO_INVALID_PARMS.

Function 117h - Remarks

None.

Function 117h -

Category:

Function:
117h
Description:
Query LVB Info

Select an item:

Description
Parameter Packet Format 
Returns 
Remarks 

Level 0 Physical Device Driver Interfaces

The strategy portion of the Level 0 physical device drivers that can be a component of any video device handler is called to handle I/O requests through a request packet interface with the OS/2 kernel. The strategy routine executes at task-time as a result of an application VIO request. The strategy routine is called with ES:BX pointing to the request packet ( the pointer is valid in both a DOS session and an OS/2 session). Only three command codes (passed in the request packet) are required to be supported by a video device driver. For any other command code the physical device driver does not support, the physical video device driver must return Unsupported Command and Done in the request packet status field.

The following are the physical device driver commands that are supported by the physical video device driver (the command codes are in parentheses):

INIT (00h) - Initialize the Device

On entry, the request block contains the following fields as inputs to the physical video device driver:

• Pointer to the DevHlp entry point
• Pointer to the INIT arguments

On exit, the physical video device driver sets the first pointer to the offsets of the code and data segments to release code and data needed only by the initialization routine. The second pointer is set to 0. If initialization is successful, the request packet status field is set to indicate No Error and Done; otherwise, the status is set to General Failure .

The physical video device driver can perform the following initialization:

�Obtain the DevHlp address from the request packet.
�Verify that the display adapter and the display that it supports are present. If not, it can fail initialization.

OPEN (0Dh) - Open the Device

This service routine does nothing but return with No Error status.

GENERIC IOCtl (10h) - Send I/O Requests to the Device

On entry, the request packet has the IOCtl category code and function code set. The parameter buffer and the data buffer addresses are set as virtual addresses. The physical video device driver performs the physical device driver initialization, when requested.

Physical Device Driver Initialization

The IOCtl described below supports the same class of functions as the Presentation Manager dynamic link enable entry point. It is called to fill in the Call Vector Table for the BVH. The call returns an error if the physical device driver detects that the adapter is not present.

Category 3

Function 73h

Purpose

To initialize the Call Vector Table.

Parameter Block Format

None.

Data Packet Format

     DWORD   Subfunction
     DWORD   Parameter1
     DWORD   Parameter2
     WORD    ReturnCode

Subfunction

The Presentation Manager enables the subfunction number. Its value must be 1 to start the Presentation Manager Fill Logical Device Block subfunction. All pieces of the BVH must support this function. Pieces of the BVH that do not support the Presentation Manager interface do not need to support the other functions. Any function not supported should return PMERR_DEV_FUNC_ NOT_INSTALLED.

Parameter1 for Subfunction = 1

Far pointer to this structure:

     DWORD   Engine Version
     DWORD   Count of Table Functions

Engine Version Version of the Presentation Manager Graphics Engine

Count of Table Functions Number of entries in the passed dispatch table. The physical device driver can only write this many entries into the table.

Parameter2 for Subfunction=1

Far pointer to this structure:

     DWORD   Flags Pointer
     DWORD   Call Vector Table

Flags Pointer Pointer to where the flags controlling calls to the Fill Physical Device Block function go.

Call Vector Table Pointer to the default dispatch table containing the addresses of the default handler functions and the functions supported by this component. Each entry in the Call Vector Table is the far address of a Video Device Handler function, which must be callable from Ring 3. The address of the nth BVH function is the nth DWORD in the table, beginning with Function 0. Refer to the DLL Initialization function for a description of the function numbers.

Remarks

This function is supported by the video device drivers and is called only once for each adapter to be supported by the BVH. A video device handler should determine if the display adapter and that which it supports is present. If not present, this function must return an error. Every part of a BVH must successfully initialize the Call Vector Table for that device to be used by OS/2.

EGA.SYS and INT 2Fh Screen Switch Notification

For some DOS EGA applications, OS/2 is not able to switch from a DOS session to an OS/2 session and then back again. Upon return to the DOS application, the screen will be incorrect. The DOS EGA applications that do not run successfully are:

• Applications that download fonts into a character generator block other than Block 0. Character Generator Block 0 is supported.
• Graphic mode applications that use more than one display page.
• Advanced graphics mode applications that write directly to the registers on the EGA adapter.

To supplement OS/2 screen switching support, a DOS application can be written to use the EGA register interface. Alternatively, a DOS application can be notified on a screen switch through multiplex interrupt 2Fh, AH = 40h. These two mechanisms are described in the following sections.

Note:On an IBM PS/2 personal computer the registers on the adapter are both readable and writable. For these configurations, OS/2 reads and saves the registers on a screen switch away from a DOS session, and restores the registers upon return to a DOS session.

For configurations including the IBM PS/2 Display Adapter 8514/A when the 8514/A display adapter is in an advanced function mode, the OS/2 operating system does not save the physical display buffer when switching away from a DOS session. Therefore, end users are cautioned to complete any 8514/A advanced function mode application before switching to OS/2 mode.

EGA.SYS Device Driver

EGA.SYS is a physical device driver that provides support for the EGA register interface in a DOS session. To support advanced graphics modes D, E, F, and 10 in a DOS session, the Mouse Pointer Draw device driver must save or restore the EGA registers. Because the EGA registers are not readable, this can be done only if the application assists in setting the registers initially. Rather than performing I/O directly to the registers on the adapter, the application sets the registers through the EGA register interface.

EGA Register Interface

The EGA register interface is a library of ten functions supported for a DOS session, advanced graphics applications (modes D, E, F, and 10). These functions do the following:

• Read from, or write to, one or more of the EGA write-only registers
• Define default values for the EGA write-only registers, reset the EGA registers to these default values, or return the default values
• Check whether the EGA register interface is present and, if so, return its version number.

When the application uses the EGA register interface, OS/2 2.1 maintains a backup copy or shadowshow the EGA registers are set. Then, if the operator switches away from (and later returns to) the application, the registers are restored properly. It is not necessary to use the EGA register interface to set the mode, color palette, or palette registers. Instead, use ROM BIOS function INT 10h with AH = 00h, 0Bh, or 10h, respectively.

Calling The EGA Register Interface

To call EGA register interface functions from an assembly language program, the following actions must be performed:

1.Load the registers with the required parameter values
2.Execute software interrupt 10h.

Values returned by the EGA register interface functions are placed in registers.

EGA Register Interface Restrictions

A list of areas where restrictions apply for the EGA Register Interface are shown below:

�Functions not supported
�Attribute Controller registers
�Sequencer Memory Mode register
�Input Status registers
�Graphics Controller Miscellaneous register

Functions Not Supported

Multiple display pages in graphics modes are not supported. Fonts can be loaded (by using ROM BIOS INT 10h with AH = 11h) only into Character Generator Block 0.

Attribute Controller Registers

Before your application program uses the Attribute Controller registers (I/ O address 3C0h) in an extended interrupt 10h call, it must set the flip- flopthat selects the address or data register so that it selects the address register (by doing an input from I/O port 3BAh or 3DAh). The flip- flop is always reset to this state upon return from the extended INT 10h call. Interrupt routines that access the attribute chip must also leave the flip-flop set to the address register upon return from the interrupt.

Note:If the application program sets the flip-flop so that it selects the Data register, and expects the flip-flop to remain in this state, the application must disable interrupts between the time it sets the flip-flop to the Data register state and the last time the flip-flop is assumed to be in this state.

Sequencer Memory Mode Register

When the Sequencer Memory Mode register (I/O address 3C5H, data register 4) is accessed, the sequencer produces a faulton the CAS lines that can cause problems with video random access memory. As a result, the application cannot use the EGA Register Interface to read from, or write to, this register. Instead, use the following procedure to safely alter this register:

1.Disable interrupts
2.Set Synchronous Reset (bit 1) in the Sequencer Reset register to 0
3.Read/modify/write the Sequencer Memory Mode register
4.Set Synchronous Reset (bit 1) in the Sequencer Reset register to 1
5.Enable interrupts

Input Status Registers

The application cannot use the EGA Register Interface to read Input Status registers 0 (I/O address 3C2h) and 1 (I/O address 3BAh or 3DAh). If the program must read these registers, it must do so directly.

Graphics Controller Miscellaneous Register

When the Graphics Controller Miscellaneous register (I/O address 3CFh, data register 6) is accessed, a glitchon the CAS lines occurs that can cause problems with video random access memory. As a result, the application should not use the EGA Register Interface to read from or write to this register.

EGA Register Interface Function F6h does not alter the state of the Graphics Controller Miscellaneous register. Instead, use the following procedure to safely alter this register:

1.Disable interrupts
2.Set Synchronous Reset (bit 1) in the Sequencer Reset register to 0
3.Read/modify/write the Graphics Controller Miscellaneous register
4.Set Synchronous Reset (bit 1) in the Sequencer Reset register to 1
5.Enable interrupts

EGA Register Interface Functions

This section describes each EGA Register Interface function in detail. The following list shows these functions by function number (hex):

F0 Read One Register
F1 Write One Register
F2 Read Register Range
F3 Write Register Range
F4 Read Register Set
F5 Write Register Set
F6 Revert to Default Registers
F7 Define Default Register Table
F8 Read Default Register Table
FA Interrogate Driver

Note:Function F9h, and Functions FBh through FFh are reserved.

Each function description includes:

�The parameters required to make the call (input) and the expected return values (output)
�Any special considerations regarding the function

If the function description does not specify an input for a parameter, it is not necessary to supply a value for that parameter before making the call. If the function description does not specify an output value for a parameter, the parameter's value is the same before and after the call.

Note:The EGA Register Interface does not check input values, so be sure that the values loaded into the registers before making a call are correct.

Function F0H - Read One Register

This function reads data from a specified register on the EGA.

Input

AH = F0h

BX = Pointer for:

Pointer/data chips

BH = 0

BL = Pointer

Single registers

BX ignored.

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

Output

AX: Restored
BH: Restored
BL: Data
DX: Restored

All other registers are restored.

Example

The following example saves the contents of the Sequencer Map Mask register in myvalue:

myvalue db   ?
        mov  ah, 0f0h        ; f0 = read one register
        mov  bx, 0002h       ; bh = 0 / bl = map mask index
        mov  dx, 0008h       ; dx = sequencer
        int  10h             ; get it!
        mov  myvalue, bl     ; save it!

The example below saves the contents of the Miscellaneous Output register in myvalue:

myvalue db   ?
        mov  ah, 0f0h        ; f0 = read one register
        mov  dx, 0020h       ; dx = miscellaneous output register
        int  10h             ; get it!
        mov  myvalue, bl     ; save it!

Function F1H - Write One Register

This function writes data to a specified register on the EGA. When an application program returns from a call to Function F1, the contents of registers BH and DX are not restored. The program must save and restore these registers.

Input

AH = F1h

BL = Pointer for pointer/data chips. Data for single registers.

BH = Data for pointer/data chips. Ignored for single registers.

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes or D for color modes

Output

AX: Restored
BL: Restored
BH: Not restored
DX: Not restored

All other registers are restored.

Example

The following example writes the contents of myvalueinto the CRT Controller Cursor Start register:

myvalue db   3h
        mov  ah, 0f1h        ; f1 = write one register
        mov  bh, myvalue     ; bh = data from myvalue
        mov  bl, 000ah       ; bl = cursor start index
        mov  dx, 0000h       ; dx = crt controller
        int  10h             ; write it!

The example below writes the contents of myvalueinto the Feature Control register:

myvalue db   2h
        mov  ah, 0f1h        ; f1 = write one register
        mov  bl, myvalue     ; bl = data from myvalue
        mov  dx, 0028h       ; dx = feature control register
        int  10h             ; write it!

Function F2H - Read Register Range

This function reads data from a specified range of registers on the EGA. A range of registers is defined to be several registers that have consecutive indexes, on a single chip. This function is applicable for pointer/data chips.

Input

AH = F2h

CH = Starting pointer value

CL = Number of registers (must be >1)

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

? = B for monochrome modes, or D for color modes

ES:BX = Points to table of one-byte entries (length = value in CL). On return, each entry is set to the contents of the corresponding register.

Output

AX: Restored
BX: Restored
CX: Not restored
DX: Restored
ES: Restored

All other registers are restored.

Example

The following example saves the contents of the Attribute Controller Palette registers in paltable:

paltable db  16 dup (?)
         mov  ax, ds               ; assume paltable in data segment
         mov  es, ax               ; es = data segment
         mov  bx, offset paltable  ; es:bx = paltable address
         mov  ah, 0f2h             ; f2 = read register range
         mov  cx, 0010h            ; ch = start index of 0
                                   ; cl = 16 registers to read
         mov  dx, 0018h            ; dx = attribute controller
         int  10h                  ; read them!

Function F3H - Write Register Range

This function writes data to a specified range of registers on the EGA. A range of registers is defined to be several registers that have consecutive indexes, on a single chip. This function is applicable for the pointer/data chips.

Input

AH = F3h

CH = Starting pointer value

CL = Number of registers (must be >1)

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

? = B for monochrome modes, or D for color modes

ES:BX = Points to table of one-byte entries (length = value in CL). Each entry contains the value to be written to the corresponding register.

Output

AX: Restored
BX: Not restored
CX: Not restored
DX: Not restored
ES: Restored.

All other registers are restored.

Example

The following example writes the contents of curslocinto the CRT Controller Cursor Location High and Cursor Location Low registers.

cursloc db   01h, 00h            ; cursor at page offset 0100h
        mov  ax, ds              ; assume cursloc in data segment
        mov  es, ax              ; es = data segment
        mov  bx, offset cursloc  ; es:bx = cursloc address
        mov  ah, 0f3h            ; f3 = write register range
        mov  cx, 0e02h           ; ch = start index of 14
                                 ; cl = 2 registers to write
        mov  dx, 0000h           ; dx = crt controller
        int  10h                 ; write them!

Function F4H - Read Register Set

This function reads data from a set of registers on the EGA. A set of registers is defined to be several registers that might have consecutive indexes and that might not be on the same chip.

Input

AH = F4h

CX = Number of registers (must be >1)

ES:BX = Points to table of records with each entry in this format:

Bytes 1-2: Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

Byte 3: Pointer value (0 for single registers)

Byte 4: EGA Register Interface fills in data read from register specified in bytes 1-3.

Output

AX: Restored
BX: Restored
CX: Not restored
ES: Restored.

All other registers are restored.

Example

The following example saves the contents of the Miscellaneous Output register, Sequencer Memory Mode register, and CRT Controller Mode Control register in results:

outvals dw   0020h               ; miscellaneous output register
        db   0                   ; 0 for single registers
        db   ?                   ; returned value
        dw   0008h               ; sequencer
        db   04h                 ; memory mode register index
        db   ?                   ; returned value
        dw   0000h               ; crt controller
        db   17h                 ; mode control register index
        db   ?                   ; returned value

results db   3 dup (?)
        mov  ax, ds              ; assume outvals in data segment
        mov  es, ax              ; es = data segment
        mov  bx, offset outvals  ; es:bx = outvals address
        mov  ah, 0f4h            ; f4 = read register set
        mov  cx, 3               ; number of entries in outvals
        int  10h                 ; get values into outvals
        mov  si, 3               ; move the returned values from
        add  si, offset outvals  ;  outvals
        mov  di, offset results  ;  to results
        mov  cx, 3               ; 3 values to move

loop:   mov  al, [si]            ; move one value from
        mov  [di], al            ;  outvals to results
        add  si, 4               ; skip to next source byte
        inc  di                  ; point to next destination byte
        loop loop

Function F5H - Write Register Set

This function writes data to a set of registers on the EGA. A set of registers is defined to be several registers that might have consecutive indexes, and that might be on the same chip.

Input

AH = F5h

CX = Number of registers (must be >1)

ES:BX = Points to table of values with each entry in this format:

Bytes 1-2: Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

Byte 3: Pointer value (0 for single registers)

Byte 4: Data to be written to register specified in bytes 1-3.

Output

AX: Restored
BX: Restored
CX: Not restored
ES: Restored.

All other registers are restored.

Example

The following example writes the contents of outvalsto the Miscellaneous Output register, Sequencer Memory Mode register, and CRT Controller Mode Control register:

outvals dw   0020h               ; miscellaneous output register
        db   0                   ; 0 for single registers
        db   0a7h                ; output value
        dw   0008h               ; sequencer
        db   04h                 ; memory mode register index
        db   03h                 ; output value
        dw   0000h               ; crt controller
        db   17h                 ; mode control register index
        db   0a3h                ; output value
        mov  ax, ds              ; assume outvals in data segment
        mov  es, ax              ; es = data segment
        mov  bx, offset outvals  ; es:bx = outvals address
        mov  ah, 0f5h            ; f5 = write register set
        mov  cx, 3               ; number of entries in outvals
        int  10h                 ; write the registers!

Function F6H - Revert to Default Registers

This function restores the default settings of any registers that the application program has changed through the EGA Register Interface. The default settings are defined in a call to Function F7 (described in the next section).

Input

AH = F6h

Output

All registers are restored.

Example

The following example restores the default settings of the EGA registers:

        mov  ah, 0f6h    ; f6 = revert to default registers
        int  10h         ; do it now!

Function F7H - Define Default Register Table

This function defines a table containing default values for any pointer/ data chip or single register. If default values are defined for a pointer/ data chip, they must be defined for all registers within that chip.

Input

AH = F7h

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

ES:BX = Points to table of one-byte entries. Each entry contains the default value for the corresponding register. The table must contain entries for all registers.

Output

AX: Restored
BX: Not restored
DX: Not restored
ES: Restored

All other registers are restored.

Example

The following example defines default values for the Attribute Controller:

attrdflt db  00h, 01h, 02h, 03h, 04h, 05h, 06h, 07h
         db  10h, 11h, 12h, 13h, 14h, 15h, 16h, 17h
         db  08h, 00h, 0fh, 00h
         mov  ax, ds              ; assume attrdflt in data segment
         mov  es, ax              ; es = data segment
         mov  bx, offset attrdflt ; es:bx = attrdflt address
         mov  ah, 0f7h            ; f7 = define default register table
         mov  dx, 0018h           ; dx = attribute controller
         int  10h                 ; do it!

The example below defines a default value for the Feature Control register:

featdflt db  00h
         mov  ax, ds              ; assume featdflt in data segment
         mov  es, ax              ; es = data segment
         mov  bx, offset featdflt ; es:bx = featdflt address
         mov  ah, 0f7h            ; f7 = define default register table
         mov  dx, 0028h           ; dx = feature control register
         int  10h                 ; do it!

Function F8H - Read Default Register Table

This function reads the table containing default register values for any pointer/data chip or single register.

Input

AH = 0F8H

DX = Port number:

Pointer/data chips

0h: CRT Controller (3?4H)
8h: Sequencer (3C4H)
10h: Graphics Controller (3CEH)
18h: Attribute Controller (3C0H)

Single registers

20h: Miscellaneous Output register (3C2H)
28h: Feature Control register (3?AH)
30h: Graphics 1 Position register (3CCH)
38h: Graphics 2 Position register (3CAH)

? = B for monochrome modes, or D for color modes

ES:BX = Points to a table into which the default values are returned. The table must have room for the full set of values for the pointer/data chip or single register specified.

Output

AX: Restored
BX: Not restored
DX: Not restored
ES: Restored

All other registers are restored.

Example

The following example reads the default values for the Miscellaneous Output register:

regdflt  db
         mov  ax, ds
         mov  es, ax               ; es = data segment
         mov  bx, offset regdflt   ; es:bx = regdflt address
         mov  ah, 0f8h             ; f8 = read default register table
         mov  dx, 0020h            ; dx = miscellaneous output register
         int  10h                  ; do it!

The following example reads the default values for the CRT Controller register:

regdflt  db   25 dup (?)
         mov  ax, ds
         mov  es, ax               ; es = data segment
         mov  bx, offset regdflt   ; es:bx = regdflt address
         mov  ah, 0f8h             ; f8 = read default register table
         mov  dx, 0000h            ; dx = crt controller register
         int  10h                  ; do it!

Function FAH - Interrogate Driver

This function returns a value specifying whether the EGA.SYS device driver is present.

Input

AH = FAh

BX = 0

Output

AX: Restored
BX: 0, if EGA.SYS driver is not present
ES:BX: Pointer to EGA Register Interface version number, if present
Byte 1: Major release number
Byte 2: Minor release number (in 1/100ths)

Example

The following example interrogates the driver and displays the results:

gotmsg  db   "EGA.SYS driver found", 0dh, 0ah, 24h
nopmsg  db   "EGA.SYS driver not found", 0dh, 0ah, 24h
revmsg  db   "revision $"
crlf    db   0dh, 0ah, 24h
ten     db   10
        mov  bx, 0              ; must be 0 for this call
        mov  ah, 0fah           ; fa = interrogate driver
        int  10h                ; interrogate!
        or   bx, bx             ; bx = 0 ?
        jnz  found              ; branch if driver present
        mov  dx, offset nopmsg  ; assume nopmsg in data segment
        mov  ah, 09h            ; 9 = print string
        int  21h                ; output not found message
        jmp  continue           ; that's all for now
found:  mov  dx, offset gotmsg  ; assume gotmsg in data segment
        mov  ah, 09h            ; 9 = print string
        int  21h                ; output found message
        mov  dx, offset revmsg  ; assume revmsg in data segment
        mov  ah, 09h            ; 9 = print string
        int  21h                ; output "revision "
        mov  dl, es:[bx]        ; dl = major release number
        add  dl, "0"            ; convert to ASCII
        mov  ah, 2              ; 2 = display character
        int  21h                ; output major release number
        mov  dl, "."            ; dl = "."
        mov  ah, 2              ; 2 = display character
        int  21h                ; output a period
        mov  al, es:[bx+1]      ; al = minor release number

        xor  ah, ah             ; ah = 0
        idiv ten                ; al = 10ths, ah = 100ths
        mov  bx, ax             ; save ax in bx
        mov  dl, al             ; dl = 10ths
        add  dl, "0"            ; convert to ASCII
        mov  ah, 2              ; 2 = display character
        int  21h                ; output minor release 10ths
        mov  dl, bh             ; dl = 100ths
        add  dl, "0"            ; convert to ASCII
        mov  ah, 2              ; 2 = display character
        int  21h                ; output minor release 100ths
        mov  dx, offset crlf    ; assume crlf in data segment
        mov  ah, 09h            ; 9 = print string
        int  21h                ; output end of line
continue:                       ; the end

INT 2Fh Screen Switch Notification

A new Multiplex Interrupt (INT 2Fh) is issued by OS/2 to signal either of the following two events:

�Switching the DOS application to the background (AX = 4001H)
�Switching the DOS application to the foreground (AX = 4002H)

A DOS application that receives this signal must hookthe Multiplex Interrupt vector. That is, when the application is started, it must save the current INT 2Fh vector and set this vector to point to the application' s interrupt handler.

When the notification is received, the application must save all registers, perform whatever processing is required, restore all registers, and issue the IRET instruction to return to the operating system. Only the following forms of processing are supported:

�Modifying application or video memory (or both)
�Issuing ROM BIOS video service calls (INT 10h)
�Issuing EGA Register Interface calls (INT 10h)
�Programming the EGA video card directly

Note:When an application is being switched to the background, and the application's INT 2Fh handler uses the EGA Register Interface to save the EGA registers, these registers are restored automatically when the application is returned to the foreground.

An application can receive notification that it is being switched to the background at any time. Code sequences that are sensitive to interruption can be protected with CLI/STI instructions. When the switch notification occurs, the application (other than its INT 2Fh handler) is frozen until it is returned to the foreground.

When an application's INT 2Fh handler receives notification with a value in AH other than 40H, the application must issue the JMP FAR instruction to branch to the previous INT 2Fh vector.

Using Extended Screen and Keyboard Control (ANSI.SYS, ANSICALL)

This section explains how to issue special control character sequences to:

�Control the position of the cursor
�Erase text from the screen
�Set the display mode
�Redefine the meaning of keyboard keys

ANSI extended screen and keyboard control sequences are supported in DOS sessions by ANSI.SYS, an installable device driver. In OS/2 sessions, these control sequences are supported by the ANSICALL component within OS/2 CHAR. DLL.

Note:In this section, unless otherwise specified, ANSI refers to both ANSI.SYS and ANSICALL.

Limitations and Restrictions

ANSI operates on a per-session basis. OS/2-mode ANSI is affected when keys are reassigned in a code page environment. ANSI does not provide code page support for key reassignment in a DOS session.

Control Sequence Syntax

Each of the cursor control sequences is in the format:

     ESC [ parameters COMMAND 

A cursor control sequence is defined as follows:

/-------------------------------------------------------------\
|Sequence            |Description                             |
|--------------------+----------------------------------------|
|ESC                 |The 1-byte ASCII code for ESC (1BH). It |
|                    |is not the three characters ESC.        |
|--------------------+----------------------------------------|
|[                   |The character [.                        |
|--------------------+----------------------------------------|
|parameters          |The numeric values specified for #. The |
|                    |# represents a numeric parameter that is|
|                    |an integer value specified with ASCII   |
|                    |characters. If a parameter value is not |
|                    |specified, or if a value of 0 (zero) is |
|                    |specified, the default value for the    |
|                    |parameter is used.                      |
|--------------------+----------------------------------------|
|COMMAND             |An alphabetic string that represents the|
|                    |command. It is case-specific.           |
\-------------------------------------------------------------/

For example, ESC [2;10Hcould be created using BASIC as shown below. Notice that "CHR$(27)" is ESC.

The IBM Personal Computer Basic Version 3.00 Copyright IBM Corp. 1981, 1982, 1983, 1984
xxxxx Bytes free

OK
open "sample" for output as 1
OK
print #1, CHR$(27);"[2;10H";"x row 2 col 10"
OK
close #1
OK

Cursor Control Sequences

The following tables contain the cursor control sequences used to control cursor positioning:

/-------------------------------------------------------------\
|Cursor Position     |Function                                |
|--------------------+----------------------------------------|
|ESC [#;#H           |Moves the cursor to the position        |
|                    |specified by the parameters. The first  |
|                    |parameter specifies the row number and  |
|                    |the second parameter specifies the      |
|                    |column number. The default value is 1.  |
|                    |If no parameter is given, the cursor is |
|                    |moved to the home position.             |
\-------------------------------------------------------------/

This example copies the file SAMPLE from the previous example to CON, that places the cursor on row 2, column 10 of the screen:

type sample

/-------------------------------------------------------------\
|Cursor Up           |Function                                |
|--------------------+----------------------------------------|
|ESC [#A             |Moves the cursor up one or more rows    |
|                    |without changing the column position.   |
|                    |The value of # determines the number of |
|                    |lines moved. The default value for # is |
|                    |1. This sequence is ignored if the      |
|                    |cursor is already on the top line.      |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Cursor Down         |Function                                |
|--------------------+----------------------------------------|
|ESC [#B             |Moves the cursor down one or more rows  |
|                    |without changing the column position.   |
|                    |The value of # determines the number of |
|                    |lines moved. The default value for # is |
|                    |1. The sequence is ignored if the cursor|
|                    |is already on the bottom line.          |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Cursor Forward      |Function                                |
|--------------------+----------------------------------------|
|ESC [#C             |Moves the cursor forward one or more    |
|                    |columns without changing the row        |
|                    |position. The value of # determines the |
|                    |number of columns moved. The default    |
|                    |value for # is 1. This sequence is      |
|                    |ignored if the cursor is already in the |
|                    |rightmost column.                       |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Cursor Backward     |Function                                |
|--------------------+----------------------------------------|
|ESC [#D             |Moves the cursor back one or more       |
|                    |columns without changing the row        |
|                    |position. The value of # determines the |
|                    |number of columns moved. The default    |
|                    |value for # is 1. This sequence is      |
|                    |ignored if the cursor is already in the |
|                    |leftmost column.                        |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Horizontal and      |Function                                |
|Vertical Position   |                                        |
|--------------------+----------------------------------------|
|ESC [#;#f           |Moves the cursor to the position        |
|                    |specified by the parameters. The first  |
|                    |parameter specifies the line number and |
|                    |the second parameter specifies the      |
|                    |column number. The default value is 1.  |
|                    |If no parameter is given, the cursor is |
|                    |moved to the home position.             |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Cursor Position     |Function                                |
|Report              |                                        |
|--------------------+----------------------------------------|
|ESC [#;#R           |The cursor sequence report reports the  |
|                    |current cursor position through the     |
|                    |standard input device. The first        |
|                    |parameter specifies the current line and|
|                    |the second parameter specifies the      |
|                    |current column.                         |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Device Status Report|Function                                |
|--------------------+----------------------------------------|
|ESC [6n             |The console driver gives a cursor       |
|                    |position report sequence on receipt of  |
|                    |device status report.                   |
\-------------------------------------------------------------/

Note:Do not use the Device Status Report as part of a prompt.

This example tells ANSI to put the current cursor position (row and column) in STDIN. Then the program reads it from STDIN and outputs it to STDOUT.

PROGRAM dsr(INPUT,OUTPUT);

  VAR
    f:FILE OF CHAR;
    key:CHAR;

  FUNCTION inkey:CHAR;                    { read character  }
    VAR                                   { from the  /Using a File
      ch:CHAR;                            { keyboard buffer }
    BEGIN
      READ(f,ch);
      inkey:=ch
    END;

  BEGIN
    ASSIGN(f,'user');
    RESET(f);
        WRITE(CHR(27),'[6n');             { issue a DSR,  }
        key:=inkey;                       { read up to    }
        key:=inkey;                       { first digit   }
        key:=inkey;                       { of the row    }
        WRITE('row ',inkey,inkey,'  column ');
        key:=inkey;                       { skip to column}
        WRITE(inkey,inkey)                { write column  }
  END.

/-------------------------------------------------------------\
|Save Cursor Position|Function                                |
|--------------------+----------------------------------------|
|ESC [s              |The current cursor position is saved.   |
|                    |This cursor position can be restored    |
|                    |with the restore cursor position        |
|                    |sequence (see below).                   |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Restore Cursor      |Function                                |
|Position            |                                        |
|--------------------+----------------------------------------|
|ESC [u              |Restores the cursor to the value it had |
|                    |when the console driver received the    |
|                    |save cursor position sequence.          |
\-------------------------------------------------------------/

Erasing

The following tables contain the control sequences used to erase text from the screen:

/-------------------------------------------------------------\
|Erase in Display    |Function                                |
|--------------------+----------------------------------------|
|ESC [2J             |Erases all of the screen, and the cursor|
|                    |goes to the home position.              |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Erase in Line       |Function                                |
|--------------------+----------------------------------------|
|ESC [K              |Erases from the cursor to the end of the|
|                    |line and includes the cursor position.  |
\-------------------------------------------------------------/

Controlling the Display Mode

The following tables contain the control sequences used to set the mode of operation:

�Set Graphics Rendition (SGR)
�Set Mode (SM)
�Reset Mode (RM)

/-------------------------------------------------------------\
|Set Graphics    |Function                                    |
|Rendition (SGR) |                                            |
|----------------+--------------------------------------------|
|ESC [#;...;#m   |Sets the character attribute specified by   |
|                |the parameters.  All of the following char- |
|                |acters have the attribute according to the  |
|                |parameters until the next occurrence of SGR.|
|                |                                            |
|                |Parameter  Meaning                          |
|                |                                            |
|                |    0      All attributes off (normal white |
|                |           on black                         |
|                |    1      Bold on (high intensity)         |
|                |    4      Underscore on (monochrome-       |
|                |           compatible modes)                |
|                |    5      Blink on                         |
|                |    7      Reverse video on                 |
|                |    8      Canceled on (invisible)          |
|                |   30      Black foreground                 |
|                |   31      Red foreground                   |
|                |   32      Green foreground                 |
|                |   33      Yellow foreground                |
|                |   34      Blue foreground                  |
|                |   35      Magenta foreground               |
|                |   36      Cyan foreground                  |
|                |   37      White foreground                 |
|                |   38      Reserved                         |
|                |   39      Reserved                         |
|                |   40      Black background                 |
|                |   41      Red background                   |
|                |   42      Green background                 |
|                |   43      Yellow background                |
|                |   44      Blue background                  |
|                |   45      Magenta background               |
|                |   46      Cyan background                  |
|                |   47      White background                 |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Set Mode (SM)   |      Function                              |
|----------------+--------------------------------------------|
|   ESC [=#h     |Invokes the screen width or type specified  |
|or ESC [=h      |by the parameter.                           |
|or ESC [=0h     |                                            |
|or ESC [?7h     |                                            |
|                |Parameter  Meaning                          |
|                |                                            |
|                |    0       40 x 25 black and white         |
|                |    1       40 x 25 color                   |
|                |    2       80 x 25 black and white         |
|                |    3       80 x 25 color                   |
|                |    4      320 x 200 color                  |
|                |    5      320 x 200 black and white        |
|                |    6      640 x 200 black and white        |
|                |    7      Wrap at end of line. Typing past |
|                |           end-of-line results in new line. |
\-------------------------------------------------------------/

/-------------------------------------------------------------\
|Reset Mode (RM) |      Function                              |
|----------------+--------------------------------------------|
|   ESC [=#l     |      Parameters are the same as Set Mode   |
|or ESC [=l      |      (SM) except that parameter 7 resets   |
|or ESC [=0l     |      wrap at end-of-line mode (characters  |
|or ESC [?7l     |      past end-of-line are discarded).      |
\-------------------------------------------------------------/

Keyboard Key Reassignment

The ANSI system can be used to reassign keys on the keyboard. When an application calls KbdStringIn, the reassigned key's ASCII code is converted to the specified string and is passed back to the calling application. For example, replace a with q so that whenever the a key is pressed, a q is passed to the application that is reading input.

In OS/2 2.1, keyboard remapping can be done only from an application calling KbdStringIn. In DOS, keyboard remapping must be done from the command line.

Note:Keyboard reassignment works only with OS/2 applications that use the KbdStringIncall to get input.

OS/2 mode ANSI is affected when keys are reassigned in a code-page environment. ANSI "remembers" the code page under which a key is reassigned . The keyboard subsystem checks for reassigned keys when the application calls the KbdStringInfunction. When a reassigned key is detected, the ANSI support:

1.Checks to see what code page the requestor is running under
2.Looks internally to see if the key has been reassigned under that code page
3.If there is a key reassignment for that code page, gives the reassignment string
4.Otherwise, gives the original ASCII codes.

A maximum storage of 64KB can be allocated to OS/2 mode ANSI-reassigned key definitions. The table shown below contains the control sequences used to redefine the meaning of keyboard keys:

/--------------------------------------------------------------\
| The control sequence is:     |Function                       |
|------------------------------+-------------------------------|
|    ESC [#;#;...#p            |The first ASCII code in the    |
|or  ESC ["string"p            |control sequence defines which |
|or  ESC [#;"string";#;#;      |code is being mapped.  The     |
|    "string";#p               |remaining numbers define the   |
|or  any other combination     |sequence of ASCII codes        |
|    of strings and decimal    |generated when this key is     |
|    numbers                   |intercepted.  However, if the  |
|                              |first code in the sequence is  |
|                              |0 (NULL), the first and second |
|                              |code make up an extended ASCII |
|                              |redefinition.                  |
\--------------------------------------------------------------/

To execute the examples below, either create a file that contains the following statements and then use the TYPE command to display the file that contains the statement, or execute the command at the OS/2 prompt:

�Assign the Aand akey to the Qand qkey, respectively.

�Assign the Qand qkey to the Aand akey, respectively:

Using a File:

ESC [65;8lp          A becomes Q
ESC [97;113p         a becomes q
ESC [81;65p          Q becomes A
ESC [113;97p         q becomes a

At the OS/2 Prompt:

prompt $e[65;8lp     A becomes Q
prompt $e[97;113p    a becomes q
prompt $e[81;65p     Q becomes A
prompt $e[113;97p    q becomes a

�Reassign the F10 key to a DIR command followed by a carriage return:

Using a File:

ESC [0;68;"dir";13p

At the OS/2 Prompt:

  prompt $e[0;68;"dir";13p

The $e is the prompt command characters for ESC. The 0;68 is the extended ASCII code for the F10 key; 13 decimal is a carriage return.

�The following example sets the prompt to display the current directory on the top of the screen and the current drive on the current line:

    prompt $e[s$e[1;30f$e[K$p$e[u$n$g

If the current directory is C:\FILES, and the current drive is C, this example would display:

             C:\FILES
C>

�The following DOS-compatible assembly language program reassigns the F10 key to a DIR B: command followed by a carriage return:

        TITLE SET ANSI.ASM - SET F10 TO STRING FOR ANSI.SYS 

CSEG      SEGMENT   PARA   PUBLIC   ' CODE ' 
         ASSUME   CS : CSEG , DS : CSEG 
         ORG       100H 
ENTPT :    JMP       SHORT   START 
STRING    DB        27 , ' [ 0 ; 68 ; " DIR   B : " ; 13P '   ; Redefine   F10   key 
STRSIZ    EQU       $ - STRING                   ; Length   of   above   message 
HANDLE    EQU       1                           ; Pre - defined   file . 
                                            ; Handle   for   standard   output 

START     PROC      NEAR 
         MOV       BX , HANDLE                  ; Standard   output   device 
         MOV       CX , STRSIZ                  ; Get   size   of   text   to   be   sent 
         MOV       DX , OFFSET   STRING          ; Pass   offset   of   string 
                                            ; To   be   sent 
         MOV       AH , 40H                     ; Function = " write   to   device " 
         INT       21h                         ; Call   DOS 
         RET                                 ; Return   to   DOS 
START     ENDP 

CSEG      ENDS 
         END       ENTPT 

DPRINTF Print Formatting Package

DPRINTF is a kernel-debugging print-formatting package. You can include this function in the code to test your display driver.

To use the DPRINTF function, you must have a second device attached to COM1 or COM2. Due to difficulties passing variable-length argument lists through a call-gate transition, only one argument, a 0-terminated string, is passed to this routine. The string is sent to either COM1 or COM2 depending on how the variable, UR_DAT, is defined.

The only checking that this routine performs is to process XON/XOFF characters from the equipment attached to the debug port. This guarantees that the output does not overrun the receiving device. However, after receiving XOFF, this routine spins in a loop, waiting for XON.

The string to be output is ASCIIZ. It may contain literal characters.

A literal character is defined as any character that is not part of a format specification. Special non-printing characters are listed as follows :

\n for CRLF (carriage return/linefeed)

\t for tab

\b for bell

\\ for \.

Virtual Video Device Drivers

This chapter describes the design, implementation, and interfaces of a virtual video device driver, including the virtualization and windowing of DOS session on an OS/2 platform. It is assumed that you are familiar with the terms and concepts in the OS/2 Virtual Device Driver Reference.

Overview

A virtual video device driver is used by the IBM Operating System/2 as a virtual display device for DOS applications executing in a DOS session by providing virtual hardware support. Virtual video device drivers are required when it is necessary for multiple DOS sessions to share one or more video devices.

The virtual video device driver manages access to video memory, video registers, and video adapter ROM BIOS. Special functions have been defined to permit other OS/2 Ring 3 components (such as the DOS Session Manager and the Presentation Manager display device driver) to obtain the vital video state information necessary to window a DOS session on the Presentation Manager Desktop.

For simplicity, a dedicated virtual video device driver should be targeted to a specific video device. This reference manual includes a set of virtual video device drivers that can be used as templates for enhancement modifications to any of the currently supported devices, or they can be used as samples to create a virtual device driver from scratchfor a similar but compatible device. For example, the OS/2 virtual Super VGA device driver (VSVGA.SYS) is a derivative of the virtual VGA device driver (VVGA.SYS).

The following virtual video device drivers, which cover an extensive range of the most commonly used video devices, are included in this reference manual:

Virtual CGA device driverVCGA
Virtual EGA device driverVEGA
Virtual MONO device driverVMONO
Virtual VGA device driverVVGA
Virtual XGA device driverVXGA
Virtual SVGA device driverSVGA
Virtual 8514/A device driverV8514A

The video devices for which OS/2 provides virtual video device drivers include:

�Western Digital
�ATI
�Cirrus Logic
�Headland
�IBM Super VGA
�Trident
�TSENG
�Video 7**

Note:Specific Super VGA chip revision/model support can be found in VVDP. H.

Installable Virtual Video Device Driver Architecture

The architecture of a virtual video device driver conforms to the architecture defined for all virtual device drivers. However, some parts of the multiple DOS session's architecture have been designed primarily for virtual video device drivers, as follows:

�Foreground and background notification hooks
�Freezeand thawservices
�Title change and code-page change notification hooks

A significant amount of the primary virtual video device driver code involves communication with the DOS Session Window Manager. A Remote Procedure Call (RPC) mechanism must be used to communicate between the DOS Session Window Manager and a virtual video device driver under the following conditions:

�The DOS Session Window Manager is a Ring 3 component (lowest privilege level);
�Virtual device drivers run at Ring 0 (highest privilege level);
�DOS sessions have no Local Descriptor Table (LDT) and therefore cannot attach to Dynamic Link Libraries (DLLs).

For this purpose the DOS Session Window Manager creates a thread that calls the virtual video device driver to wait for a video event from any of the currently windowed DOS sessions.

Design of Installable Virtual Video Device Drivers

A virtual video device driver is a basedevice driver, although a "DEVICE=" statement in the CONFIG.SYS file is used to specify one or more virtual video device drivers to load. The DOS Session Manager and DOS Session Window Manager identify a virtual video device driver by its registered name. For example, a virtual video device driver for the primary display would register as VVIDEO1$; a virtual video device driver for the secondary display device would register as VVIDEO2$; and so forth.

Note:Support of multiple DOS sessions is disabled if no virtual video device driver claims ownership of the primary display device after virtual video device driver loading and initialization is completed.

Supporting DOS-Standard Adapters and Modes

IBM-compatible CGA, EGA, VGA, XGA, and 8514/A adapters are supported as primary display devices; monochrome adapters are supported as secondary display devices. For these devices, the standard configurations (including the amount of video memory, type of monitor and so forth), are supported. However, there are a few exceptions. For example, support for other dual- adapter combinations, such as EGA/Monochrome with CGA/Color, or VGA/ Monochrome with CGA/Color, are not supported.

All EGA monitor combinations (RGB, ECD, and monochrome) and VGA, XGA, 8514/ A monitor combinations (i512/8513, 8514, and 8515), as well as all EGA memory combinations (64KB, 128KB, 192KB, and 256KB) of the 8514/A monitor are supported. The type of monitor used with a monochrome or CGA adapter is immaterial; that is, the behavior of the adapter is not affected.

There are some limitations, however. For example, an EGA, VGA, or Super VGA with a 2xxport configuration, instead of the standard 3xxAlso, an EGA display with only 64KB of display memory cannot support high-resolution graphic modes in a window, due, in part, to the video mode used concurrently by Presentation Manager (640 x 200, 16 colors), which consumes nearly all of the 64KB of on-board video memory. In addition, blinking attributes (whether in text or graphics modes) cannot be emulated in a DOS window.

A significant portion of the primary virtual video device driver involves communication with the DOS Session Window Manager. This includes providing a set of services to fully describe a DOS session's video state and a set of notifications to signal when the video state changes, so that a DOS session being windowed remains relatively synchronized with its associated DOS session that is executing in the background.

Because the DOS Session Window Manager, OS/2 Session Manager, and Presentation Manager display device driver execute in Ring 3, while the virtual video device driver runs in Ring 0, a system entry point is necessary for these Ring 3 components to communicate with the virtual video device driver. The virtual video device driver provides the following DosRequestVDDservice to:

�DOS Session Window Manager
-Set Access
-Set Focus
-Set Lock
-Query Mode Info
-Query Cursor Info
-Query Palette Info
-Copy LVB Content
-Copy Bit Map Content
-Wait for Video Event
-Control Event
�PM Display Device Driver
-Set Display Requirements
-Request off-screen VRAM
-Free off-screen VRAM
-Request VGA Controller
-Free VGA Controller
-Query VRAM Status

Note:See DOS Session Window Manager Servicesand Presentation Manager Display Driver Servicesfor a detailed explanation of the DosRequestVDDfunctions provided by the virtual video device driver.

There are two kinds of DOS session window support:

�Displaying a running image in a window
�Displaying a frozen image in a window

The latter is a subset of the former. The virtual video device driver always attempts to provide support for displaying a running image and for standard text and CGA graphics modes this is always possible, but there are graphics modes cases where that is not possible. One example is the 64KB EGA mode; other examples are the XGA and 8514/A modes.

Support for the XGA or 8514/A graphics modes is not a matter of sufficient memory but of the sheer complexity of virtualizing the 8514/A hardware. In addition, if a DOS application uses VGA graphics modes on an 8514/A system, it will not be able to use the VGA memory if a monitor, being used as a secondary display by other tasks in the system, is connected to the VGA.

There is no known reliable method of determining whether a monitor is connected to the VGA or Super VGA. The 8514/A can detect a limited set of IBM-compatible, fixed-frequency monitors, whereas the XGA, using DMQS, has the potential of identifying all monitor types, including OEMs.

In an 8514/A system, there is no architected way for the virtual video device driver to determine whether the VGA is in use by another process or session. Conversely, there is no way for the virtual video device driver to claim the device and prevent other processes or sessions from later acquiring the device.

Note:

256-color modes will not be rendered accurately in a window even when the PM display driver supports 256 colors, because the DOS Session Window Manager does not provide Palette Manager support.

High-resolution graphics modes on a 64KB EGA currently will not be rendered properly in a DOS window because the memory organization is substantially different (planes 0 and 1 and planes 2 and 3 are chained together).

OS/2 provides a single, generic Super VGA virtual device driver that supports the majority of the Super VGA video adapters made with the above- mentioned Super VGA chip sets. However, there are a small number of adapters that cannot be reliably virtualized due to the way they are designed. An example of this category is an adapter that requires multiple OUTs to a specific port before permitting the extended clock bits to be programmed.

Of the 8514/A graphics modes, only the 1024 x 768 256-color mode has been tested for accurate rendering in a window.

Virtualization Support Strategy

The virtualization support required for these devices varies, depending on the complexity, capability, and operational characteristics of the device. However, the approach to develop a high-level design should always be the same, regardless of the device involved. To illustrate, we will use the 8514/A and XGA devices as examples in the following sections.

Virtualization Support Requirements for 8514/A and XGA

The following sections describe the device description, functional requirements, and design tradeoffs for the 8514/A and XGA devices.

8514/A Device Description

�The majority of the I/O ports are either read-only or write-only.

�There is a multi-function register that requires special considerations because the functionality characteristics are totally different from the other I/O registers.

�The 8514/A internal RGB index of the DAC is not readable.

�The VRAM cannot be accessed directly. (It is not a dumb framedevice.)

�Special consideration must be given to handling the passthrough-modecapability of this device.

�Video memory size is assumed to be 1MB for the following reasons:

-The OS/2 PM Display Device Driver cannot function without it.

-It is not possible to configure a system with multiple 8514/A adapters.

�The 8514/A is not a Direct Memory Access (DMA) device.

XGA Device Description

�The I/O registers mostly are readable and writable, plus a few reserved registers.

�It is a BusMaster device, capable of DMA operations.

�DMA (co-processor) operations are initiated through memory-mapped I/O registers located in the adapter ROM area above C0000.

�The device can operate in a virtual memory (that is, a 386 environment).

�Video memory can be accessed by the DOS application through either an A0000 or B0000 aperture, without use of a co-processor.

�Multiple XGA configuration is possible.

�With built-in VGA hardware, the two operating environments are mutually exclusive even though they share the same DAC and VRAM.

�Planar VGA is disabled on a single display system (the display is attached to the XGA adapter).

�132-column text mode is supported.

�All graphics modes are packed-pel.

8514/A Functional Requirements

�Determine the existence of the device and the type of display attached.

�Trap all the write-only I/O ports, even if the DOS session executes in the foreground (full-screen); otherwise, the device cannot be saved or restored .

�No page-fault hook is required because the 8514/A is not a memory-mapped device.

�Establish a mechanism with the virtual VGA device driver to manage ownership of the shared device.

�Enable the DOS application that is INT 2Fh-aware to save and restore its own video state.

�Trap all I/O, whether or not I/O can be virtualized while the DOS session is executing in the background.

XGA Functional Requirements

�For every XGA configuration in the system, determine the physical location and size of VRAM, the type of display attached, and the location of the memory-mapped I/O registers.

�A page fault hook is required to detect the memory-mapped I/O registers used, because the affected system memory must be locked down before any DMA operations can occur.

�Notification of EMS, XMS, and DPMI memory allocations is required, so that the memory object can be locked down for DMA operations.

�Page-fault handling of A0000 and B0000 is not required because an I/O trap handler can be installed to monitor usage of the Aperture Control register.

Upon detection, the I/O handler can choose one of the following:

-When the DOS session is foreground, map the linear address to the physical location of the VRAM (that is, A000 or B000), giving a length of 64KB because that is the maximum size of the aperture.

This approach eliminates duplication of the page fault management logic of the virtual VGA device driver.

-When the DOS session is background, map the linear address to the appropriate location within the shadow buffer that was saved during the recent session switch. The displacement is 64KB-aligned, and it is computed using the content of the Aperture Index Register.

�The XGA-specific registers must be saved/restored to provide 132-column text mode support. The virtual VGA device driver is expected to handle the others. Enable the DOS application that is INT 2Fh-aware to save and restore its own video state.

8514/A Design Tradeoffs

�When save/restore of the complete video state is required, you have two choices for saving the 1MB VRAM:

-Allocate the 1MB shadow buffer during creation of the virtual DOS session, thus eliminating a potential problem with resource allocation during session switching.

-Delay allocation of the shadow buffer at the time of session switch, but risk the possibility of session termination because the required memory is not available.

�Software emulation of any hardware-assist operations to the video memory probably is too complex to achieve successfully. The only alternative available is to freeze the DOS application whenever these I/O ports are accessed in the background. A frozen image can be presented in a window if the complete video state and VRAM were saved for the DOS window session.

XGA Design Tradeoffs

�It is impossible to anticipate what the DOS application might do when the memory-mapped I/O register is touched; assume the worst. To preserve the integrity of the system by not permitting the DOS application to interfere with system operations, lock down the affected memory regions.

Although there are numerous ways to do this, there are penalties involved with each one. Some of the methods (and their possible drawbacks) are described following this table.

�In a multiple XGA configuration system, saving and restoring every XGA probably is desirable. Instead, you can let the DOS application take care of it, or you can selectively save/restore only one XGA device.

�Software emulating the XGA hardware operations is not desirable.

�The only apparent alternative is to freeze the DOS application when the I/ O ports are accessed in the background. A frozen image can be presented in a window if the complete video state and VRAM are saved for the DOS window session.

Methods of Locking Down Memory Regions

�Assume each full-screen DOS session is started in physical memory below 1MB by OS/2. This has the advantage of not having to specifically lock down the 640KB DOS region, and the memory, by default, is continuous. This is ideal for any XGA-specific DOS applications that do not require any extended memory, while achieving performance equal to DOS. The drawback here is that this type of session is not supported by OS/2.

�Assume each full-screen DOS session is started anywhere in system memory with the 640KB DOS region locked down discontiguously by OS/2. Here, the virtual memory mode of the XGA must be used. EMS, XMS, and DPMI memory allocation can be locked dynamically through the extended memory allocation notification interface. Putting the XGA in VM mode would result in a 10 to 15 per cent degradation in performance, depending on the type of operations involved. OS/2 does not support this type of session start.

�Assume that XGA will be operating in VM mode. The 640KB DOS region gets locked down discontiguously only when access to the memory-mapped I/O register is detected. EMS, XMS, and DPMI memory allocation is handled as in the second case above.

�While operating in VM mode, the XGA has the ability to generate an interrupt to the system processor whenever the memory object being referenced is not present. Assuming that the 640KB region can be selectively forced into a not-present state, a physical device driver can be written to avoid such interrupt and post the event. Although the event is posted at interrupt time, the actual lockdown of memory cannot take place until the virtual device driver gets a chance to execute at task time , when it can resume the XGA operation after successfully locking down the memory object.

Note:The second and third assumptions above require the generation of a Page Directory and Page Table in order for the XGA to access the DOS session's linear address space and VRAM.

Virtual and Non-Virtual (Full-Screen) Operations

For optimal performance and compatibility, the virtual video device drivers support full-screen operation. In this mode, there is no visual difference between DOS and DOS-session operation. For convenience, an option appears on the DOS session's system menu to convert the DOS session from windowed mode to full-screen mode and back again. Virtual video device drivers support full-screen by performing the following operations:

�Registering foreground and background VIDEO_SWITCH_NOTIFICATION hooks with the DOS Session Manager
�Allocating a Save and Restore video buffer
�Installing I/O hooks to shadow key video port accesses
�Mapping physical video memory into the appropriate video address space
�Coercing text-mode fonts to match the currently selected code page
�Providing pointer drawing services to the virtual mouse device driver to define, draw, and erase pointer images

When a DOS session does not own the physical display (that is, when it is in the background), the virtual video device drivers do the following:

�Install I/O hooks to track and emulate all video port accesses.
�Map appropriate system memory to the active portions of the video address space.
�Report video events to the DOS Session Window Manager (assuming the Presentation Manager is active and the DOS session is an unminimized window ). Such reporting includes changes to:
-Mode
-Palette
-Cursor
-Video memory
-Input events
-Scroll or string events
-Paste continue or terminate (through the virtual keyboard device driver)
-Session title change
-Screen-switch or video memory allocation errors

At any time, the DOS Session Window Manager (or other processes that have access to a DOS session's process ID) can update a DOS session's window state, as follows:

�Windowed or non-windowed
�Focused or non-focused
�Minimized or un-minimized
�Locked or unlocked

Any aspect of a DOS session's video state can be queried as follows:

�Mode
�Palette
�Cursor
�Video memory
�Wait for video events
�Cancel wait for video events

I/O Handler Installation

I/O port handlers are installed during the creation of a DOS session This is always required if the target device requires virtualization. The assembler-language hook interface is faster than its "C" language counterpart.

Whenever possible, avoid simulation by a lower-level I/O handler. For example, if the device is capable of word I/O, do not install just the byte I/O handlers, because your byte I/O handlers will be called twice for each word I/O issued by the DOS application.

I/O ports can be enabled or disabled dynamically on a per-DOS session basis except when the VDHIIH_ALWAYS_TRAP option is specified at port installation .

I/O trapping can be removed at any time, provided that it is called using the same port arguments passed to install the I/O ports.

Currently, I/O handlers may be preempted for the following reasons:

�The code is swappable.

�The data referenced by the handlers is swappable.

�The OS/2 kernel portions that route I/O traps, page faults, and so forth, are swappable as well.

There is a remote possibility that a DOS session screen-switch might occur while an I/O handler is blocked, meaning that there is a slight risk of a shadowed DOS session's I/O operation accessing the hardware when it is no longer owner of that hardware. At present, there is no satisfactory means of removing that possibility. Making all the necessary code and data resident-both in kernel and virtual device driver-is not acceptable, nor is the overhead of calling semaphore services in the I/O handlers.

Mouse-Independent Pointer Drawing Services

When the virtual video device driver creates a DOS session for the first time, it opens the virtual mouse device driver. If the OPEN is successful, it provides the virtual mouse device driver with the following entry points :

�Show Pointer
�Hide Pointer
�Define Text Pointer
�Define Graphics Pointer
�Set Video Page
�Set Light-Pen Emulation

Also, whenever the DOS session changes video modes (including the initial mode change during DOS-session creation), the virtual video device driver notifies the virtual mouse device driver of the new mode, screen dimensions , and so forth.

Built-in Extended INT 10h and INT 2Fh Services

The EGA Register interface is integrated into the virtual video device driver as part of its INT 10h interception logic. This interface is a set of INT 10h services that are used by applications to make possible drawing operations and simultaneous use of the mouse pointer on EGA and VGA hardware. The virtual video device driver's pointer drawing services are intended to replace this interface, but existing graphical applications still use it (generally when mouse support is also present). The interface must be present or these applications will not function correctly.

The INT 2Fh services notify applications when they are about to be switched to full-screen or background mode. Applications can use this notification to stop accessing video memory if they are using a video memory not supported for background operation. This prevents them from freezing and redraws their screen in the event the virtual video device driver fails to fully restore it.

/--- IMPLEMENTATION NOTE ----------------------------------\
|                                                          |
|   The EGA Register interface has not been integrated     |
|   into the virtual video device drivers. Until and       |
|   unless this is done, EGA.SYS must be supplied with     |
|   the system and loaded by EGA/VGA users on an           |
|   as-needed basis.                                       |
|                                                          |
\----------------------------------------------------------/

Virtual Video Device Driver Services

Multiple virtual device drivers can be installed for the same adapter. Usually, the second virtual device driver detects that the adapter's address space is already reserved, and so, fails to install. However, virtual video device drivers can be written to take control of a device from an owning virtual device driver when a certain event occurs and then to relinquish control later. This is accomplished by supporting the Release Device and Accept Device inter-virtual device driver requests in both virtual video device drivers. An owning virtual video device driver must unmap all video pages and uninstall all page-fault and I/O hooks upon receipt of a Release request, and later must reinstall all hooks upon receipt of an Accept request.

     VDHRequestVDD(
       HVDD hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_DEVACCEPT (5)            */
       PVOID pReqIn,    /* Undefined.                         */
       PVOID pReqOut    /* Undefined.                         */
     );

     VDHRequestVDD(
       HVDD hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_DEVRELEASE (6)           */
       PVOID pReqIn,    /* Undefined.                         */
       PVOID pReqOut    /* Undefined.                         */
     );

This support is provided for multiple virtual video device drivers installed for the same device but virtualizing different aspects of the hardware (for example, VGA and Super VGA virtual video device drivers for a single Super VGA adapter). A virtual video device driver that is not currently the owner must silently pass on any DosRequestVDD and VDHRequestVDD requests that it receives to the next virtual video device driver in the chain, using the VDDREQ_PASS return code.

In cases where multiple video adapters use the same physical monitor (such as VGA with 8514/A), there is no need to issue the device requests described previously because the devices are separate. Coordination of which virtual video device driver is currently the display owner must be accomplished by way of a similar pair of inter-virtual device driver requests: Release Display and Accept Display. Virtual video device drivers generally need not act except to update their own display ownership settings. Only the virtual video device driver that is currently the display owner for a given DOS session should respond to requests from the DOS Session Window Manager for that DOS session. The same is true of virtual mouse device driver pointer requests. For example, on a VGA and 8514/A single display system, only the virtual video device driver with display ownership should respond to certain system requests (that is, QUERYMODE, QUERYCURSOR, QUERYPALETTE, COPYLVB, and COPYBITMAP).

     VDHRequestVDD(
       HVDD hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_DSPACCEPT (7)            */
       PVOID pReqIn,    /* Undefined.                         */
       PVOID pReqOut    /* Undefined.                         */
     );

     VDHRequestVDD(
       HVDD hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_RELEASE (8)              */
       PVOID pReqIn,    /* Undefined.                         */
       PVOID pReqOut    /* Undefined.                         */
     );

For the VGA and 8514/A combination, the VGA virtual video device driver still manages all video event communication with the DOS Session Window Manager. This eliminates major duplicate functionality with the 8514/A. However, because the 8514/A virtual video device driver still must be able to post its own video events, a post event inter-virtual device driver request is supported by the VGA virtual video device driver.

     VDHRequestVDD(
       HVDM hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_POSTEVENT (9)            */
       PVVPOST pvvp,    /* Pointer to a VVPOST structure      */
       PVOID pReqOut    /* Undefined.                         */
     );

where VVPOST is a structure containing:

     typedef struct vvp_ { /* vvp (input for POSTEVENT request*/
       LONG  iEvent;    /* See the VVDEVENT_* constants below */
       PVOID pEvent;    /* Event data (varies by event type   */
       ULONG  flEvent;  /* See POSTEVENT_* constants below    */
     }VVPOST;

     #define VVDEVENT_NONE         0   / *   No   change                * / 
      # define   VVDEVENT _ MODE           1   / *   Change   in   DOS           * / 
                                         / *   session ' s   mode          * / 
      # define   VVDEVENT _ PALETTE        2   / *   Change   in   DOS           * / 
                                         / *   session ' s   palette       * / 
      # define   VVDEVENT _ LVB            3   / *   Change   in   DOS           * / 
                                         / *   session ' s   LVB           * / 
      # define   VVDEVENT _ SCROLL         4   / *   Scroll   of   DOS           * / 
                                         / *   session ' s   LVB           * / 
      # define   VVDEVENT _ STRING         5   / *   String   output           * / 
      # define   VVDEVENT _ CURSOR         6   / *   Cursor   position / type    * / 
                                         / *   change                   * / 
      # define   VVDEVENT _ INPUT          7   / *   DOS   session   is   check -   * / 
                                         / *   ing   for   input   data      * / 
      # define   VVDEVENT _ ENDPASTE       8   / *   DOS   session   has         * / 
                                         / *    cancelled   pasting      * / 
      # define   VVDEVENT _ PASTE          9   / *   DOS   session   is   ready    * / 
                                         / *   for   additional   pasting * / 
      # define   VVDEVENT _ SWITCHERROR   10   / *   DOS   session   cannot   be   * / 
                                         / *    switched   foreground    * / 
      # define   VVDEVENT _ TITLECHANGE   11   / *   DOS   session   title   has   * / 
                                            changed                  * / 
      # define   VVDEVENT _ DDE           12   / *   Set / Clear   DDE   flag      * / 
      # define   POSTEVENT _ ADD      0x0001   / *   Add   given   event .        * / 
      # define   POSTEVENT _ FLUSH    0x0002   / *   Flush   given   or          * / 
                                            existing   event .         * / 
      # define   POSTEVENT _ DELETE   0x0004   / *   Delete   existing   event . * / 

The XGA device has VGA device capability built into the hardware, but it is physically impossible to activate the functionality of both devices at the same time without another VGA-capable device installed. The extra VGA device can come in a form of a planar VGA with a display monitor attached, a VGA adapter, or another XGA device. In the event that the XGA device being targeted for save/restore by the XGA virtual device driver is also the startup device (that is, it comes up in VGA mode on system startup), a fast path can be used to temporarily stop the VGA virtual device driver from doing the save/restore of the same device without going through the preferred way of Releaseand Acceptdevice. In this case, the Save Restore request is supported by the VGA virtual video device driver.

     VDHRequestVDD(
       HVDD hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_SAVERESTORE (10)         */
       PVOID (0 or 1),  /* 1=yes, 0=no                        */
       PVOID pReqOut    /* Undefined.                         */
     );

The Repaint request is used by other virtual video device drivers (8514/A and XGA) to indicate whether the PM Desktop's screen image has been damaged by the full-screen DOS session. The virtual video device driver accepting this request must notify the PM display device driver, using QUERYVRAMSTATUS, that repaint of the Desktop is required when the PM becomes foreground.

     VDHRequestVDD(
       HVDD hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_REPAINT (11)             */
       PVOID(TRUE),     /* 1 = REPAINT required               */
       PVOID pReqOut    /* Undefined.                         */
     );

The Request Controller request is issued by the virtual Window device driver (VWIN.SYS) on behalf of the WIN-OS/2 display device driver to force the virtual video device driver to immediately release the VGA controller currently owned by a background or windowed DOS session.

     VDHRequestVDD(
       HVDD hvddVideo   /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_REQCTRL (12)             */
       PVOID PReqIn,    /* Undefined.                         */
       PVOID PReqOut    /* Undefined.                         */
     );

The Free Controller request is issued by the virtual Window device driver ( VWIN.SYS) on behalf of the WIN-OS/2 display device driver to notify the virtual video device driver that the VGA controller is now available. This request is issued only when the virtual video device driver requests notification on completion of the current PM operation.

     VDHRequestVDD(
       HVDD hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_FREECTRL   ( 13 )               * / 
        PVOID   PReqIn ,      / *   Undefined .                             * / 
        PVOID   pReqOut      / *   Undefined .                             * / 
      ) ; 

The Set PM Window request is issued by the virtual Window device driver ( VWIN.SYS) to permit the specified windowed DOS session access to the video device. It is up to the virtual video device driver servicing this request to remove all I/O hooks, map VRAM to physical A0000H as needed, and remove all pending window events for the target DOS session.

     VDHRequestVDD(
       HVDD hvddVideo,  /* Virtual video device driver handle */
       HVDM hvdm,       /* Screen group ID of the DOS session */
       INT  iFunc,      /* VVDDEVREQ_PM_WINDOW (14)           */
       PVOID(TRUE),     /* 1 = Enable WIN-OS/2                */
       PVOID pReqOut    /* Undefined.                         */
     );

8514/A and XGA Virtual Device Drivers

DOS applications currently written to the 8514/A adapter interface, XGA adapter interface, or directly to the 8514/A and XGA display adapters can run in a full-screen DOS session. This is due to the ability of each adapter's virtual device driver to:

�Grant I/O privilege
�Save or restore the video state
�Provide video bit-map images to the shield layer when the DOS session is being windowed.

A DOS application is permitted to run only in a full-screen foreground DOS session; it is frozen immediately if it attempts to access the hardware when switched to the background.

The virtual 8514/A device driver statements, which are required in the CONFIG.SYS file, are added during installation when the presence of an 8514 /A display adapter is detected:

        DEVICE=C:\OS2\MDOS\VVGA.SYS
        DEVICE=C:\OS2\MDOS\V8514A.SYS

The virtual XGA device driver statements, which are required in the CONFIG. SYS file, are added during installation when the presence of an XGA adapter is detected:

        DEVICE=C:\OS2\MDOS\VVGA.SYS
        DEVICE=C:\OS2\MDOS\VXGA.SYS

The following items should be set in DOS to enable a DOS session:

�Enable I/O trapping to permit the virtual video device driver to save and restore the hardware instance used by a DOS application when the application switches away from the foreground DOS session. The virtual video device driver allocates a buffer to save the video image. The maximum size of this buffer is 1MB and is obtained each time a full-screen DOS session is created.

Enabling I/O trapping is the default. Although multiple instances of XGA can be present on a system, the virtual XGA device driver saves or restores only the state of the first instance used by a DOS application. It is the application's responsibility to save or restore the other XGA instances.

�Register for screen switch notification. This implies that a DOS application has hooked INT 2Fh so as to be notified when it is to be switched to full-screen foreground or background. This notification informs the application that it must restore the screen when switched to full- screen foreground, and must stop accessing video memory (to avoid freezing) when switched to background.

An application that uses more than one instance of XGA must specify this option to save and restore the states of the other XGA adapters. The default is no VIDEO_SWITCH_NOTIFICATION.

Any DOS session that is not saved or restored by the virtual video device driver cannot be displayed in a window. DOS 8514/A and XGA applications are not interactive in a window; they can be viewed only.

Virtual Keyboard Device Driver Services

The virtual video device driver utilizes the Post Peek and Post Read requests from the virtual keyboard device driver to post events to the DOS Session Window Manager when the windowed DOS session video state changes. In addition to generating the VVDEVENT_INPUT event to the DOS Session Window Manager to adjust window orientation, these notifications also serve to suggest to the virtual video device driver when to check for palette and LVB changes, which generate VVDEVENT_PALETTE and VVDEVENT_LVB events.

The virtual keyboard device driver uses the Post Paste request to indicate whether paste operations can start or end. The virtual video device driver posts the VVDEVENT_PASTE or VVDEVENT_ENDPASTE event to the DOS Session Window Manager, based on the type of paste operation requested. The virtual video device driver provides the following VDHRequestVDDservices for the virtual keyboard device driver:

     VDHRequestVDD
     (
        HVDD hvddVideo,
        HVDM hvdm,
        INT  iFunc,     /* Virtual video device               */
                        /* driverEVREQ_POSTPEEK (1)           */
        BOOL fAvail,    /* TRUE if ROM BIOS buffer is not     */
                        /* empty.                             */
        PVOID pReqOut   /* Undefined.                         */
     );                 /* Returns TRUE.                      */

     VDHRequestVDD
     (
        HVDD hvddVideo,
        HVDM hvdm,
        INT  iFunc,     /* Virtual video device               */
                        /* driverEVREQ_POSTREAD (2)           */
        BOOL fAvail,    /* TRUE if ROM BIOS buffer is not     */
                        /* empty.                             */
        PVOID pReqOut   /* Undefined.                         */
     );                 /* Returns TRUE.                      */

     VDHRequestVDD
     (
        HVDD hvddVideo,
        HVDM hvdm,
        INT  iFunc,     /* Virtual video device               */
                        /* driverEVREQ_POSTPASTE (3)          */
        BOOL fContinue, /* TRUE to continue pasting,          */
                        /* FALSE to end.                      */
        PVOID pReqOut   /* Undefined.                         */
     );                 /* Returns TRUE.                      */

The PEEK and READ notifications occur prior to the actual operation; fAvailis TRUE if the ROM BIOS input buffer contains data, and FALSE if empty. In addition to generating VVDEVENT_INPUT events for the DOS Session Window Manager to adjust window orientation, these notifications also serve to suggest to the virtual video device driver when to check for changes in video context.

For the PASTE notification, fContinueis TRUE if pasting can continue (that is, buffer space is now available), and FALSE if pasting should be terminated (that is, the user pressed ESC). In the first case, the virtual video device driver posts VVDEVENT_PASTE to the DOS Session Window Manager, and in the second case, VVDEVENT_ENDPASTE.

/--- DESIGN NOTE ------------------------------------------\
|                                                          |
|   In the current implementation, the fAvail parameters   |
|   are ignored by the virtual video device driver.  It    |
|   matters only whether a PEEK or READ is occurring.      |
|                                                          |
\----------------------------------------------------------/

Virtual Mouse Device Driver Services

For the virtual mouse device driver, the virtual video device driver provides a VDHRequestVDDfunction, as well as several direct interfaces for pointer drawing operations.

The following VDHRequestVDDservice is provided:

     VDHRequestVDD
     (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT   iFunc,    /* Virtual video device               */
                        /* driverEVREQ_POSTMOUSE (4)          */
        PVOID pReqIn,   /* Undefined.                         */
        PVOID pReqOut   /* Undefined.                         */
     );                 /* Returns TRUE.                      */

The virtual mouse device driver must return the address of a function that permits the virtual video device driver to obtain mouse position and button status during processing of the INT 10h, Query Light Pen function, when light pen emulation is enabled for the active DOS session. Also, whenever the DOS session changes video modes (including the initial mode change that takes place during DOS-session creation), the virtual video device driver notifies the virtual mouse device driver driver of the new mode and screen dimensions.

The POSTMOUSE notification is intended to be called whenever the mouse is about to record a button transition event (that is, button going down or button coming up). Its purpose is to notify the virtual video device driver that a video event is likely to occur.

The direct-call interfaces are exported by way of the following VDHRequestVDDto the virtual mouse device driver during the creation of the first DOS session. (To avoid introducing a loading-order dependency, they are not exported during virtual device driver initialization.)

     VDHRequestVDD
     (
        HVDD  hvddMouse,
        HVDM  hvdm,
        INT   iFunc,    /* iFunc = VMDEVREQ_REGISTER (1)      */
        PVMREG pvmreg,  /* Pointer to VMREG structure         */
        PVMFUNC pvmfunc /* Pointer to VMFUNC structure        */
     );                 /* Returns TRUE                       */

where VMREG is a structure containing all the direct-call addresses:

     typedef struct vmreg_s
     {
        ULONG     nb;              /* Size of structure, in   */
                                   /*  bytes (24)             */
        PFNSHOWPTR  pfnShowPtr;    /* Ptr to show pointer fn. */
        PFNHIDEPTR  pfnHidePtr;    /* Ptr to hide pointer fn. */
        PFNDEFTEXT  pfnDefTextPtr; /* Ptr to define text
                                   /*  pointer fn.            */
        PFNDEFGRAPH pfnDefGraphPtr;/* Ptr to define graphics
                                   /*  pointer fn.            */
        PFNSETPAGE  pfnSetPtrPage; /* Ptr to set pointer      */
                                   /*  page fn.               */
        PFNSETLPEN  pfnSetLPenEm;  /* Ptr to enable/disable   */
                                   /*  lpen fn.               */
     }  VMREG;

and where VMFUNC is a structure in which the virtual mouse device driver must return the address of its own exported function to return mouse position and button status:

     typedef struct vmfunc_s
     {
        ULONG      nb;               /* Size of structure,    */
                                     /* in bytes (8)          */
        PFNQUERYSTAT pfnQueryStatus; /* Ptr to query virtual  */
                                     /* status proc.          */
     }  VMFUNC;

The virtual video device driver also uses VDHRequestVDDto notify the virtual mouse device driver of changes in video mode:

     VDHRequestVDD
     (
        HVDD  hvddMouse,
        HVDM  hvdm,
        INT   iFunc,              /* VMDEVREQ_SETSIZE (2)      */
        PVMSS pvmss,              /* Pointer to VMSS structure */
        PVOID pReqOut             /* Undefined                 */
     );

where VMSS is a structure containing the following information:

     typedef struct vmss_s
     {
        ULONG nb;          /* Size of structure, in bytes (36)*/
        LONG  lMode;       /* Video mode (for example,        */
                           /* 00h-13h, or -1)                 */
        ULONG ulWidth;     /* Width of screen, in pels        */
        ULONG ulHeight;    /* Height of screen, in pels       */
        ULONG ulCellWidth; /* Width of screen cells, in pels  */
        ULONG ulCellHeight;/* Height of screen cells, in pels */
        ULONG ulPtrWidth;  /* Width of pointer drawing size,  */
                           /* in pels                         */
        ULONG ulPtrHeight; /* Height of pointer drawing size, */
                           /* in pels                         */
        ULONG ulUnitWidth; /* Width of pointer drawing unit,  */
                           /* in pels                         */
     }  VMSS;

The direct-call interfaces supplied by virtual video device drivers are defined as follows:

     BOOL FNSHOWPTR VVShowPtr
     (
        HVDM hvdm,           /* DOS session handle,           */
                             /* or CURRENT_VDM                */
        ULONG xNew,          /* Horizontal pel (NOT cell)     */
                             /* coordinate                    */
        ULONG yNew           /* Vertical pel (NOT cell)       */
                             /* coordinate                    */
     );                      /* Returns TRUE unless ptr         * / 
                                / *   drawing   disabled                 * / 

      BOOL   FNHIDEPTR   VVHidePtr 
      ( 
         HVDM   hvdm               / *   DOS   session   handle ,   or          * / 
                                / *   CURRENT _ VDM                      * / 
      ) ;                          / *   Returns   TRUE   unless   ptr         * / 
                                / *   drawing   disabled * /               * / 

      BOOL   FNDEFTEXT   VVDefTextPtr 
      ( 
         HVDM   hvdm ,              / *   DOS   session   handle ,   or          * / 
                                / *   CURRENT _ VDM                      * / 
         ULONG   ulANDMask ,       / *   Screen   mask                      * / 
         ULONG   ulXORMask ,       / *   Pointer   mask                     * / 
         BOOL   fHW                / *   TRUE   to   use   hardware   cursor     * / 
      ) ;                          / *   Returns   TRUE                     * / 

      BOOL   FNDEFGRAPH   VVDefGraphPtr 
      ( 
         HVDM   hvdm ,              / *   DOS   session   handle ,   or          * / 
                                / *   CURRENT _ VDM                      * / 
         USHORT   ausMasks [ ] ,     / *   Screen   mask ,   followed   by        * / 
                                / *   pointer   mask                     * / 
         ULONG   xHot ,            / *   Relative   horizontal   hot - spot 
                                / *   coordinate                       * / 
         ULONG   yHot              / *   Relative   vertical   hot - spot      * / 
                                / *   coordinate                       * / 
      ) ;                          / *   Returns   TRUE                     * / 

      BOOL   FNSETPAGE   VVSetPtrPage 
      ( 
         HVDM   hvdm ,              / *   DOS   session   handle ,   or          * / 
                                / *   CURRENT _ VDM                      * / 
         ULONG   ulPage           / *   Video   page   number                * / 
      ) ;                          / *   Returns   TRUE                     * / 

      BOOL   FNSETLPEN   VVSetLPenEm 
      ( 
         HVDM   hvdm ,              / *   DOS   session   handle ,   or          * / 
                                / *   CURRENT _ VDM                      * / 
         BOOL   fEnable           / *   TRUE   to   enable   emulation        * / 
      ) ;                          / *   Returns   TRUE                     * / 

For reference, the function supplied by a virtual mouse device driver to a virtual video device driver is defined as follows:

     BOOL FNQUERYSTAT VMQueryStatus
     (
        HVDM hvdm,       /* DOS session handle, or            */
                         /* CURRENT_VDM                       */
        PVMSTAT pvmstat  /* Pointer to VMSTAT info structure  */
     );                  /* Returns TRUE                      */

where VMSTAT is a structure containing:

     typedef struct vmstat_s
     {
        BOOL  fPtrHidden;    /* Visual pointer status         */
        ULONG x;             /* Current virtual x position    */
        ULONG y;             /* Current virtual y position    */
        ULONG flButtons;     /* Current button status         */
     }  VMSTAT;

     /*
     ** Button status bit definitions
     */

     #define BUTBIT_LEFT     0x0001
     #define BUTBIT_RIGHT    0x0002
     #define BUTBIT_CENTER   0x0004

/--- DESIGN NOTE ------------------------------------------\
|                                                          |
|  The POSTMOUSE notification currently is not supplied by |
|  the virtual mouse device driver, nor is it currently    |
|  monitored by the virtual video device driver.           |
|                                                          |
\----------------------------------------------------------/

Virtual Video Device Driver Services for OS/2 Applications (DosRequestVDD)

The following services are intended to provide a method for any OS/2 Ring 3 application to manage or obtain the video state of a DOS session.

DOS Session Window Manager Services

For the DOS Session Window Manager, the virtual video device driver provides the following DOSRequestVDDservices:

�The Set Access request informs the virtual video device driver that the caller is interested in receiving video events for the requested DOS session, preventing future callers from obtaining the same privilege. It also declares the DOS session to be windowed. Under the cover, the virtual video device driver can initiate a global timer hook for the purpose of video event checking upon creation of the first DOS session. In addition, the same interface can be used by the OS/2 Session Window Manager to help the virtual video device driver track which sessions are being windowed by PM so that events are not reported when PM is not foreground. When PM returns to foreground, it is up to the virtual video device driver to post refreshedevents so that all DOS-session windows are repainted.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETACCESS (1)            */
        ULONG cbInput,  /* See the ACCESS_ constants          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     #define ACCESS_RELEASE   0 /* Release access             */
     #define ACCESS_REQUEST   1 /* Request access             */
     #define ACCESS_PMREQUEST 2 /* Request access made by PM  */

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_ACCESS_DENIED (Access already has been taken.)
        ERROR_INVALID_FUNCTION (iFunc invalid, or access
         already set.)

�The Set Focus request records the current DOS session as having or not having focus. Unlike the foreground/background notification hooks provided by the DOS Session Manager (which are supported only by the Session Manager ), this function is called by the DOS Session Window Manager as the user gives or takes focus to or from DOS sessions.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS Session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETFOCUS (2)             */
        ULONG cbInput,  /* TRUE if gaining focus,             */
                        /*   FALSE if losing                  */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid)

�The Set Lock request suspends and resumes the DOS session's video state. The virtual video device driver guarantees that the video state will not change following a LOCK until a corresponding UNLOCK is issued. Moreover, if a DOS session is locked multiple times, it must be unlocked an equivalent number of times before it is truly unlocked.

Implementation of this service currently is based on the VDHFreezeand VDHThawservices, instead of a lazylock, to avoid additional overhead in the interrupt and I/O handlers, and to make the lock implementation simple for both background and foreground DOS sessions. Consequently, callers should use the lock service sparingly and for as brief a time as possible to avoid communication problems due to line drop.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_SETLOCK (3)              */
        ULONG cbInput,  /* TRUE if locking,                   */
                        /*   FALSE if unlocking               */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid)
        ERROR_BUFFER_OVERFLOW (Too   many   freezes 
          outstanding . ) 

�The Query Mode request returns current mode information for the DOS session, such as screen dimensions, whether or not the DOS session is suspended, code-page ID, and so forth.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYMODE (4)            */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Sizeof(VVMODE)                     */
        PVOID pOutput   /* Pointer to a VVMODE structure      */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                           yet.)
        ERROR_ACCESS_DENIED        (User buffer could not
                                           be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                           outstanding.)

where VVMODE is a structure containing:

     /*
     ** Output for MODE event
     */

     typedef struct vvm_s
     {
        ULONG ulAdapter;    /* See the ADAPTER_* constants.   */
        ULONG ulFormat;     /* See the FORMAT_* constants.    */
        ULONG ulDDFormat;   /* See the DDFORMAT_* constants.  */
        ULONG flMode;       /* Mode descriptors (See MODE_*   */
                            /*  constants.)                   */
        ULONG nRows;        /* Height of screen in rows       */
                            /* (or y pels)                    */
        ULONG nCols;        /* Width of screen in columns     */
                            /* (or x pels)                    */
        ULONG nPlanes;      /* Number of planes (Must be 1    */
                            /*  for OS/2 2.0.)                */
        ULONG nBitCount;    /* If TEXT, zero;  if BITMAP,     */
                            /*  bits per pel).                */
        ULONG ulCellWidth;  /* Width of cells (normally 8;    */
                            /*  1 for BITMAPs)                */
        ULONG ulCellHeight; /* Height of cells (1 for         */
                            /*  BITMAPs)                      */
        ULONG fSuspended;   /* See the SUSPEND_* constants.   */
        ULONG cpID;         /* Current code-page ID           */
        ULONG FormatID;     /* Current format ID              */
     }  VVMODE;
     #define ADAPTER_MONO  0   /* Adapters supported          */
     #define ADAPTER_CGA   1   /* (Same as VioGetConfig       */
                               /*  constants)                 */
     #define ADAPTER_EGA   2
     #define ADAPTER_VGA   3
     #define ADAPTER_8514A 7

     #define FORMAT_CGA    2   /* LVB formats supported       */
     #define FORMAT_4BYTE  4
     #define FORMAT_BITMAP 0

     #define DDFORMAT_4PLANE 1 /* Display driver formats      */
                               /* supported                   */

     #define MODE_MONO        0x0001 /* Monochrome mode in    */
                                        effect                */
     #define MODE_UNDERLINE   0x0002 /* Underlining in effect */
     #define MODE_SUP_XSCALE2 0x1000 /* X scaling supported   */
                                     /* by factor of 2        */
     #define MODE_SUP_YSCALE2 0x2000 /* Y scaling supported   */
                                     /* by factor of 2        */
     #define MODE_SUP_PARTIALSCAN 0x4000 /* Partial scan line */
                                   /* copy requests supported */
     #define SUSPEND_NONE             0 /* DOS session running*/
                                           normally           */
     #define SUSPEND_OUT_OF_MEMORY    1 /* DOS session sus-   */
                                           pended due to low  */
                                        /* memory             */
     #define SUSPEND_UNSUPPORTED_MODE 2 /* DOS session sus-   */
                                           pended due to      */
                                        /* unsupported mode   */

�The Query Cursor request returns current cursor position and shape information for the DOS session:

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYCURSOR (5)          */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Sizeof(VVCURSOR)                   */
        PVOID pOutput   /* Pointer to a VVCURSOR structure    */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                    yet.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where VVCURSOR is a structure containing:

     /*
     ** Output for CURSOR event
     */

     typedef struct vvc_s
     {
        ULONG row;          /* Row (Y position) of DOS        */
                            /* session's cursor               */
        ULONG col;          /* Column (X position) of DOS     */
                            /* session's cursor               */
        ULONG ulScanStart;  /* Starting scan line for DOS     */
                            /* session's cursor               */
        ULONG ulScanEnd;    /* Ending scan line for DOS       */
                            /* session's cursor               */
        ULONG fVisible;     /* TRUE if DOS session cursor     */
                            /* visible,                       */
                            /* FALSE   if   not                      * / 
      }   VVCURSOR ; 

�The Query Palette request returns the RGB array for the DOS session. The RGB array contains 16 RGB entries for text modes and (2(n) bits per pel) entries for graphics modes:

     DosRequestVDD(
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_QUERYPALETTE (6)         */
        ULONG cbInput,  /* 0                                  */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Size of RGB array, in bytes        */
        PVOID pOutput   /* Pointer to RGB array               */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (VDM has no video state
                                    yet.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where the RGB array contains 16 RGB entries for text modes (FORMAT_CGA) and (2(n)BitCount) entries for graphics modes. RGB entries are packed on byte boundaries and have the following structure:

     typedef struct rgb_s
     {
        BYTE bBlue;
        BYTE bGreen;
        BYTE bRed;
     }  RGB;

�The Copy LVB request copies a rectangular portion of the DOS session's logical video buffer (that is, text-based LVB) to the specified output LVB. Using this call, the DOS Session Window Manager can keep a private copy of the LVB in sync with the virtual video device driver's LVB for a given DOS session:

     DosRequestVDD
     (
        HVDD  hvddVideo /* virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_COPYLVB (7)              */
        ULONG cbInput,  /*  Sizeof(RECTL)                     */
        PVOID pInput,   /* Pointer to RECTL structure         */
        ULONG cbOutput, /* Size of output LVB                 */
        PVOID pOutput   /* Pointer to output LVB              */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_NOT_READY            (DOS session has no video
                                    state yet.)
        ERROR_INVALID_DATA         (DOS session has changed
                                    video modes.)
        ERROR_NOT_LOCKED           (Caller must lock DOS
                                    session)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where RECTL is a structure defining the region to be copied:

     typedef struct rcl_s
     {
        LONG xLeft;     /* Left column (leftmost is 0)        */
        LONG yBottom;   /* Bottom row                         */
        LONG xRight;    /* Right column                       */
        LONG yTop;      /* Top row (topmost is 0)             */
     }  RECTL;

and where pOutputpoints to an output LVB. Using this call, the DOS Session Window Manager keeps a private LVB in sync with the virtual video device driver's LVB for a given DOS session. Arbitrary rectangles of the source LVB are copied to the same relative position in the target LVB.

ERROR_INVALID_DATA is returned to callers that have exclusive event access when a DOS session is in the process of changing video modes. It alleviates the need for a caller to constantly lock and unlock the DOS session to ensure a reliable transfer. Callers without exclusive event access have no alternative but to lock and unlock for each copy; otherwise, they run the risk of obtaining incorrect or obsolete information. The virtual video device driver enforces this, and will return ERROR_NOT_LOCKED if called without exclusive access and the DOS session unlocked.

�The Copy Bit Map request copies a rectangular portion of the DOS session's graphics video buffer to the specified output buffer. The output buffer is interpreted either as a device-dependent bit map(DDB) into which the requested region is copied at the same relative position, or as a device-independent bit map(DIB) intermediate buffer into which the region always is copied, starting at offset 0.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_COPYBITMAP (8)           */
        ULONG cbInput,  /* Sizeof(VVRECT)                     */
        PVOID pInput,   /* Pointer to VVRECT structure        */
        ULONG cbOutput, /* Size of output graphics buffer     */
        PVOID pOutput   /* Pointer to output graphics buffer  */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid)
        ERROR_INVALID_PARAMETER    (Pointers are invalid)
        ERROR_NOT_READY            (DOS session has no video
                                    state yet)
        ERROR_INVALID_DATA         (DOS session has changed
                                    video modes)
        ERROR_NOT_LOCKED           (Caller must lock DOS
                                    session)
        ERROR_ACCESS_DENIED        (User buffer could not
                                    be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where VVRECT is a structure defining the region to be copied and how it is to be copied:

     /*
     ** Input for COPYBITMAP request
     */

     typedef struct vvr_s
     {
        ULONG  ulDDFormat;  /* Display driver format          */
                            /* (0 if DIB used)                */
        ULONG  cx;          /* Target bit map width           */
        ULONG  cy;          /* Target bit map height          */
        RECTL  rcl;         /* Rectangle being requested      */
        PBYTE  pbColorXlate;/* Display driver color           */
                            /* translation table              */
     }  VVRECT;

and where pOutputpoints to an output graphics buffer. Using this call, the DOS Session Window Manager keeps a private bit map in sync with the virtual video device driver's graphics buffer for a given DOS session.

ulDDFormatin the VVRECT structure determines whether the request is a DIB transfer (zero) or a DDB transfer (nonzero). DIB transfers are supported for whole scan lines only (that is, xLeft and xRight are ignored). The first requested scan line must be copied to offset 0 of the bit-map buffer, and so on.

Only one DDB format, DDFORMAT_4PLANE (1), has been defined for the current release, but third parties that provide both new virtual video device drivers and new PM display drivers can define their own formats. The DOS Session Window Manager, in its capacity as mediator between the virtual video device driver and the Presentation Manager display driver, makes no interpretation of ulDDFormatin the VVMODE structure other than to initiate device-independent bit-map transfers for a zero format and device-dependent transfers for nonzero formats.

The DDFORMAT_4PLANE format requires a bit-map buffer that matches the dimensions of the DOS session's current graphics mode and has exactly four color planes (16 colors). The first scan line of the first plane is at offset 0, followed by the first scan line of the second plane at the next DWORD boundary, and so on. In addition, none of the four planes of data for a particular scan line can cross a 64KB boundary; instead, they must start at the next 64KB boundary.

For example, if the DOS session is in a 640 x 480 x 16 mode (that is, four planes of 480 80-byte scan lines), then only 204 complete scan lines will fit in each 64KB section of the buffer. The buffer must therefore be 128KB, plus 22.5KB for the 72 remaining scan lines, for a total of 150.5KB.

For this version of OS/2, DDFORMAT_4PLANE bit-map transfers are supported only for whole scan lines (vvr.rcl.xLeft and vvr.rcl.xRight are ignored). The buffer is assumed to be as large as the DOS session's current graphics screen dimensions, and the requested scan lines must be copied to the same relative position within the target buffer.

ERROR_INVALID_DATA is returned to callers that have exclusive event access when a DOS session is in the process of changing video modes. It alleviates the need to constantly lock and unlock the DOS session to ensure a reliable transfer. Callers without exclusive event access have no alternative but to lock and unlock for each copy; otherwise, they run the risk of obtaining incorrect or obsolete information. The virtual video device driver enforces this, and will return ERROR_NOT_LOCKED if called without exclusive access when the DOS session is unlocked.

�The Wait Event request returns the next windowed DOS session video event. The DOS Session Window Manager uses this interface to obtain video state changes for any unminimized windowed DOS sessions and calls the appropriate graphics engine or PM Window Manager interfaces to realize the changes:

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_WAITEVENT (9)            */
        ULONG cbInput,  /* Size of buffer for event data      */
        PVOID pInput,   /* Pointer to event buffer            */
        ULONG cbOutput, /* Sizeof(VVEVENT)                    */
        PVOID pOutput   /* Pointer to VVEVENT structure       */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Pointers are invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where VVEVENT is filled in with the following information:

     /*
     ** Output for VVDSYSREQ_WAITEVENT
     */

     typedef struct vve_s
     {
        LONG  iEvent;  /* One of the VVDEVENT_constants       */
        ULONG sgID;    /* Screen group ID of DOS session      */
        ULONG nData;   /* # of entries of information returned*/
     }  VVEVENT;

     /* Event IDs for VVDSYSREQ_WAITEVENT.                    */

     #define VVDEVENT_NONE     0  /* No change                 */
     #define VVDEVENT_MODE       1    / *   Mode   change                  * / 
      # define   VVDEVENT _ PALETTE    2    / *   Palette   change               * / 
      # define   VVDEVENT _ LVB        3    / *   Text   or   graphics   buffer 
                                      / *   change                       * / 
      # define   VVDEVENT _ SCROLL     4    / *   Scroll   change                * / 
      # define   VVDEVENT _ STRING     5    / *   String   output   change        * / 
      # define   VVDEVENT _ CURSOR     6    / *   Cursor   position / type 
                                      / *   change                       * / 
      # define   VVDEVENT _ INPUT      7    / *   DOS   session   is   input   ready * / 
      # define   VVDEVENT _ ENDPASTE   8    / *   Cancelled   pasting           * / 
      # define   VVDEVENT _ PASTE      9    / *   Start   pasting                * / 
      # define   VVDEVENT _ SWITCHERROR   10    / *   Session   switch   error    * / 
      # define   VVDEVENT _ TITLECHANGE   11    / *   Session   title   change    * / 
      # define   VVDEVENT _ DDE           12    / *    Set / Clear   DDE   flag     * / 

and the buffer addressed by pInputis filled in with:

     VVMODE structure,       if (iEvent == VVDEVENT_MODE)
     VVLVB structure(s),     if (iEvent == VVDEVENT_LVB)
     VVSCROLL structure,     if (iEvent == VVDEVENT_SCROLL)
     VVSTRING structure,     if (iEvent == VVDEVENT_STRING)
     VVCURSOR structure,     if (iEvent == VVDEVENT_CURSOR or
                                VVDEVENT_INPUT)
     null-terminated string, if (iEvent == VVDEVENT_TITLECHANGE)

For all the above events, nDatawill equal 1 (with the exception of the LVB event, which will return the number of VVLVB structures provided). For those events not listed (PALETTE, PASTE, ENDPASTE, SWITCHERROR, and NONE), nDatawill equal 0, as no additional data is returned with those notifications.

�The Control Eventrequest provides several subfunctions that control the event thread (that is, any thread dedicated to the WAITEVENT request).

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* DOS session screen group ID        */
        ULONG iFunc,    /* VVDSYSREQ_CONTROLEVENT (10)        */
        ULONG cbInput,  /* See the CONTROL_constants          */
        PVOID pInput,   /* Pointer to event buffer            */
        ULONG cbOutput, /* Sizeof(VVEVENT)                    */
        PVOID pOutput   /* Pointer to VVEVENT structure       */
     );

     #define CONTROL_RELEASE         0 /* Release event thread */
     #define CONTROL_VDMMINIMIZED    1 /* Disable video events */
                                       /* for DOS session      */
     #define CONTROL_VDMUNMINIMIZED  2 /* Enable video events  */
                                       /* for DOS session      */

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION  (iFunc is invalid)
        ERROR_INVALID_PARAMETER (parameter(s) are invalid)

The RELEASE function is used to unblock any threads blocked in the WAITEVENT request. The resulting event is NONE. The VDMMINIMIZED and VDMUNMINIMIZED functions disable and enable event reporting for the DOS session, respectively.

Presentation Manager Display Driver Services

The virtual device driver provides the following DOSRequestVDDservices for the PM display driver.

�The Set Display Requirements request is issued by a PM display driver whenever PM switches to or from full-screen operation (including the firsttime it initializes the display, during system initialization):

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_SETDRQ (11)              */
        ULONG cbInput,  /* Sizeof(VVDRQ)                      */
        PVOID pInput,   /* Pointer to VVDRQ structure         */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_PARAMETER    (Parameters are invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

where VVDRQ is a structure defining the region to be copied and how it is to be copied:

     /*
     ** Structure for VVDSYSREQ_SETDRQ
     */

     typedef struct vvdrq_s
     {
        PBYTE  pPhysVRAM;   /* Physical address of VRAM       */
        ULONG  nbReserved;  /* Number of reserved bytes       */
        ULONG  offLatchByte;/* Offset of available latch
                            /* storage                        */
        PBYTE  pfbDRQFlags; /* Pointer to flags (see DRQ_*    */
                            /* constants)                     */
        PBYTE  pfCtrlOwned; /* Addr. of display.dll's         */
                            /* fCtrlOwned flag                */
        PBYTE  pfCtrlNotify;/* Addr. of display.dll's         */
                            /* fCtrlNotify flag               */
        ULONG  nShadowRegs; /* Number of registers to shadow  */
        PVVREG pShadowData; /* Address of first entry in      */
                            /* shadow list                    */
     }  VVDRQ;

     #define DRQ_DIRTYREGS 0x01 /* Video controller registers */
                                /* modified                   */

and in which the PVVREG pointer points to one or more structures (as indicated by nShadowRegs) containing:

     /*
     ** Shadow entry for VVDSYSREQ_SETDRQ
     */

     typedef struct vvreg_s
     {
        USHORT port;    /* Port number                         */
        CHAR   indx;    /* Register index # (-1 if index reg)  */
        BYTE   value;   /* Last value written to register      */
                        /* by virtual video device driver      */
     } VVREG;

pPhysVRAM
indicates the starting physical address for VGA VRAM that the display driver will use (for example, A0000h).

nbReserved
is the number of bytes of display memory reserved exclusively for the PM display driver. It includes all the visible on-screen memory required, which must start at offset 0 from pPhysVRAM, as well as any off-screen memory needed for mouse pointer manipulation, latch storage, and so forth, immediately following. 64KB minus nbReservedyields the amount of off- screen memory to be managed by the virtual video device driver.

offLatchByte
is the offset (relative to pPhysVRAM) of a byte of video memory that the virtual video device driver can use at any (non-interrupt) time to temporarily save or restore VGA latches to and from system memory.

pfbDRQFlags
is a 16:16 pointer (Global Descriptor Table (GDT) alias selector:offset) to a byte of resident data containing inter-device driver communication bits. Currently, only one bit (bit 0) is defined, and it is set whenever the virtual video device driver has modified VGA Sequencer or Graphics Data Controller (GDC) registers. The PM display driver uses the bit to determine whether or not it must reinitialize any Sequencer or GDC registers it uses prior to the next PM drawing operation, after it has claimed ownership of the VGA controller.

pfCtrlOwned
is another 16:16 pointer-to-byte flag that is 0if the controller is currently unowned, or 1if owned. When either party sets the flag, the test and set must be done atomically (for example, XCHG and CMP) to avoid race conditions. If the PM display driver cannot set the flag, it must issue the REQCTRL function to force the virtual video device driver to clear the flag immediately. Similarly, if the virtual video device driver cannot set the flag, it must set the CtrlNotifybyte flag (the 16:16 address of which is in pfCtrlNotify) and wait for the PM display driver to finish the current drawing operation and issue the FREECTRL function.

pShadowData
is a 16:16 pointer to an array of entries specifying a VGA port (for example, 3C0H, 3CEH), a register index or -1 for the index itself, and a shadow byte in which any changes to that register or index must be stored. The virtual video device driver must update the shadow bytes in parallel with the actual OUT instructions, uninterrupted, so that interrupt-time PM pointer operations are not affected. The PM display driver also updates the shadow bytes, but it has no obligation to do so.

�The Request Off-screen Memory request is issued by a PM display driver when it wants to use some of the non-reserved off-screen memory.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_REQMEM (12)              */
        ULONG cbInput,  /* 1 implies WAIT, 0 implies NOWAIT   */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* # of bytes of off-screen memory    */
                        /* needed                             */
        PVOID pOutput   /* Address of DWORD to receive offset */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not be
                                    locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)
        ERROR_NOT_ENOUGH_MEMORY    (Off-screen memory
                                    allocation failed.)

On successful return, pOutputpoints to an offset (relative to pPhysVRAM) of one or more contiguous pages of off-screen VGA memory.

/--- IMPLEMENTATION NOTE ----------------------------------\
|                                                          |
|   The WAIT-NOWAIT parameter is not honored.  If suf-     |
|   ficient memory is not immediately available ,   an   error    | 
|     is   returned   ( that   is ,   behavior   is   always   NOWAIT ) .        | 
|     Current   display   driver   technology   uses   only   NOWAIT .      | 
|                                                                 | 
\ ---------- ---------- ---------- ---------- ---------- -------- / 

In the current virtual video device driver implementation, the request always fails if any DOS sessions currently exist. This way, if any background or windowed DOS sessions switch to a planar graphics mode, they will not be starved for VGA memory due to indeterminate memory consumption by PM (for example, Task Manager popped up, pull-down menu active, and so forth).

�The Free Off-screen Memory request is issued by a PM display driver to free memory allocated by the above request. It should do so in a timely manner, particularly if the memory was allocated by way of a WAIT request.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_FREEMEM (13)             */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* # of bytes of off-screen memory    */
                        /*   freeing                          */
        PVOID pOutput   /* Address of DWORD containing offset */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_ACCESS_DENIED        (User buffer could not
                                    be locked.)
        ERROR_LOCK_FAILED          (Too many VDD locks
                                    outstanding.)

�The Request VGA Controller request is issued by a PM display driver to force the virtual video device driver to immediately release ownership of the VGA controller. Ownership is indicated by the fCtrlOwnedbyte flag (see the VVDRQ data structure description in the section titled Presentation Manager Display Driver Services).

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_REQCTRL (14)             */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION (iFunc is invalid.)

�The Free VGA Controller request is issued by a PM display driver to notify the virtual video device driver that the VGA controller is now available. This request is not issued every time the display driver completes an operation, but rather when the virtual video device driver has requested notification by setting the fCtrlNotifybyte flag (see the VVDRQ data structure description in the section titled Presentation Manager Display Driver Services).

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_FREECTRL (15)            */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)

�The Query VRAM Status request is issued by the PM Session Manager during screen-switches back to PM. It indicates whether or not any intermediate full-screen switches to DOS sessions might possibly have invalidated PM's last video image. If no invalidation occurred, then certain expensive PM application repaints are avoided.

     DosRequestVDD
     (
        HVDD  hvddVideo,/* Virtual video device driver handle */
        SGID  sgID,     /* NULL (that is, none)               */
        ULONG iFunc,    /* VVDSYSREQ_QUERYVRAMSTATUS (16)     */
        ULONG cbInput,  /* Undefined                          */
        PVOID pInput,   /* Undefined                          */
        ULONG cbOutput, /* Undefined                          */
        PVOID pOutput   /* Undefined                          */
     );

     Returns:

        NO_ERROR
        ERROR_INVALID_HANDLE
        ERROR_INVALID_SCREEN_GROUP
        ERROR_INVALID_FUNCTION     (iFunc is invalid.)
        ERROR_INVALID_DATA         (Video memory has been invalidated.)

Success indicates that PM's memory image is intact; failure means that the image may or may not be intact.

Other Virtual Video Device Driver Services

A virtual video device driver provides many VDHRequestVDDservices for other virtual video device drivers. Some of the common services provided are listed below:

     VDHRequestVDD
     (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT   iFunc,    /* VVDDEVREQ_DEVACCEPT (5)            */
        PVOID pReqIn,   /* Undefined                          */
        PVOID pReqOut   /* Undefined                          */
     );                 /* Returns TRUE                       */

     VDHRequestVDD
     (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT   iFunc,    /* VVDDEVREQ_DEVRELEASE (6)           */
        PVOID pReqIn,   /* Undefined                          */
        PVOID pReqOut   /* Undefined                          */
     );                 /* Returns TRUE                       */
     VDHRequestVDD
     (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT   iFunc,    /* VVDDEVREQ_DSPACCEPT (7)            */
        PVOID pReqIn,   /* Undefined                          */
        PVOID pReqOut   /* Undefined                          */
     );                 /* Returns TRUE                       */

     VDHRequestVDD
     (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT   iFunc,    /* VVDDEVREQ_DSPRELEASE (8)           */
        PVOID pReqIn,   /* Undefined                          */
        PVOID pReqOut   /* Undefined                          */
     );                 /* Returns TRUE                       */

     VDHRequestVDD
     (
        HVDD  hvddVideo,
        HVDM  hvdm,
        INT   iFunc,    /* VVDDEVREQ_POSTEVENT (9)            */
        PVVPOST pvvp,   /* Pointer to event structure         */
        PVOID pReqOut   /* Undefined                          */
     );                 /* Returns TRUE                       */

Any virtual video device driver receiving a DEVRELEASE request that owns its respective device should release ownership (that is, uninstall all associated I/O hooks, page-fault hooks, page mappings, and so forth), so that an accompanying virtual device driver can manage the device in its stead.

This support is provided for multiple virtual video device drivers installed for the same device, but virtualizing different aspects of the hardware (for example, standard VGA and Super VGA virtual video device drivers for a single Super VGA adapter). A virtual video device driver that is not currently the owner must silently pass on any DosRequestVDDand VDHRequestVDDrequests that it receives, using the VDDREQ_PASS return code.

Similarly, any virtual video device driver receiving a DEVACCEPT request that does not already own its respective device and can currently accept ownership should take it (that is, install appropriate I/O hooks, page- fault hooks, page mappings, and so forth).

The DSPACCEPT and DSPRELEASE requests are similar to the preceding requests but much more restricted in scope. They are generally intended to determine which virtual video device driver (for one or more adapters) is managing the image currently displayed. For example, on VGA and 8514/A single- display systems, the display owner is the virtual video device driver that responds to certain system requests (that is, QUERYMODE to COPYBITMAP) and virtual mouse device driver drawing requests.

The Post Event request also passes the following structure:

     /*
     ** Input for POSTEVENT request
     */

     typedef struct vvp_s
     {
        LONG   iEvent;  /* See the VVDEVENT_* constants       */
        PVOID  pEvent;  /* Event data (varies from one event  */
                        /* to another)                        */
        ULONG  flEvent; /* Event posting flags                */
                                   /*   (See POSTEVENT_*
                                   /*    constants)           */
     }  VVPOST;

     #define VVDEVENT_NONE        0 /* No change              */
     #define VVDEVENT_MODE        1 /* Change in VDM's mode   */
     #define VVDEVENT_PALETTE     2 /* Change in VDM's palette*/
     #define VVDEVENT_LVB         3 /* Change in VDM's LVB    */
     #define VVDEVENT_SCROLL      4 /* Scroll of VDM's LVB    */
     #define VVDEVENT_STRING      5 /* String output          */
     #define VVDEVENT_CURSOR      6 /* Cursor position/type   */
                                    /* change                 */
     #define VVDEVENT_INPUT       7 /* DOS session is checking*/
                                    /* for input data         */
     #define VVDEVENT_ENDPASTE    8 /* DOS session has        */
                                    /* cancelled pasting      */
     #define VVDEVENT_PASTE       9 /* DOS session is ready   */
                                    /* for additional pasting */
     #define VVDEVENT_SWITCHERROR 10 /* DOS session cannot be */
                                     /* switched foreground   */
     #define VVDEVENT_TITLECHANGE 11 /* DOS session title has */
                                     /* changed               */
     #define VVDEVENT_DDE           12   / *   Set / Clear   DDE   flag      * / 
      # define   POSTEVENT _ ADD      0x0001   / *   Add   given   event .        * / 
      # define   POSTEVENT _ FLUSH    0x0002   / *   Flush   given   ( or         * / 
                                         / *   existing )   event         * / 
      # define   POSTEVENT _ DELETE   0x0004   / *   delete   existing   event   * / 

This gives a virtual video device driver (for example, 8514/A) that is operating cooperatively with another virtual video device driver (for example, CGA/EGA/VGA) the ability to post events to the DOS Session Window Manager without having to duplicate the event management.

Super VGA Virtual Video Device Driver Support

This section describes how to add support for a new chip set with Super VGA capability. The source code used is compiled conditionally to produce all the virtual video device drivers; care should be taken to ensure that additions are inserted into the appropriate driver.

Overview

The first goal of virtual video device driver support is to maintain the integrity of the operating system, and then to maintain the integrity of the DOS session. A DOS session has almost total access to the video hardware when running full-screen (foreground) and can put it into a state that prevents successful return to the desktop. An application can program registers into any state and use on-chip hardware-assist or coprocessed capabilities. A DOS session with full access to the video hardware can make use of all the capabilities provided.

While the DOS session remains full-screen, none of this is a problem. However, when a user wants to switch to another session, the adapter state must be saved and then restored accurately when it is brought into the foreground again. (Requirements for the application to continue to execute in the background will be addressed later in this chapter.) Assume that if the DOS session application is operating in an enhanced mode (above standard VGA), it is put into a suspendedstate, that is, it is not permitted to execute while in the background.

A virtual video device driver works hardest when switching from background to foreground, or the reverse. At these times, the entire state of the adapter, register, and video memory contents must be saved and restored.

In addition, if the base video subsystem is not adapter- or chip set-aware, the adapter must be placed (by default) into a cleanstate. A problem could occur if the new foreground session, after leaving an enhanced-mode DOS session, is a protect-mode session and no base video support exists for protect mode. Notice that the desktop is just another protect mode session that also might be running in an enhanced mode. This enhanced-mode support might be localized to the desktop display driver. Do not confuse this with protect-mode support.

CAUTION:
Anytimeavirtualvideodevicedriverrequiresregisteraccesstodeterminechip revisions ,orforwhateverreason ,thatprocesscanoccurinthebackground .All registersreadfromorwrittentoshouldberestored ,includingtheirindexes ,if appropriate .

Initial Considerations

The existing virtual video device driver, which forms the base for the new support, is aware of all VGA registers. Therefore, the first consideration is to identify the ranges of port addresses that are not part of the register set. All extended registers must be shadowed when a DOS session is in the background and saved/restored, including extensions to indexed registers already in the VGA range and non-indexed registers.

Currently, most chip sets have some means of mapping the video buffer into the A000-BFFF address range, or alternatively, access to video memory through port I/O. If the buffer is memory-mapped into some other region below 1MB, that part of the DOS session address space must be reserved by the virtual video device driver to handle the page faults generated as a result of access to those addresses by the DOS session.

Support for coprocessed chip sets requires even further consideration. A DOS session can switch from foreground to background at any time. If a DOS session application has initiated a coprocessor operation that has not completed when the virtual video device driver receives control to perform a switch to the background, some strategy must be adopted to ensure that, for instance, no data is lost by the DOS session. Obviously, this is relevant only if data is required from the application in a system memory- to-video memory transfer, or the reverse. Foreground and background switches are further described later in this chapter.

Initialization

During the creation of a DOS session, the virtual video device driver is called to perform certain tasks before the DOS session is permitted to execute.

Chip Set Identification

Before creating the first DOS session the chip set on which the device driver is running should be identified to ensure that virtual video support is provided for that chip set. (This task must be done only once and is not required for subsequent DOS sessions.)

Process PMI File

If this method is employed, the file must be read at this time. This is a once-only operation. Again, this cannot be performed during virtual video device driver initialization because the virtual device helper (VDH) services required to read the file are available only at DOS session task time.

The sections of the file required by the virtual video device driver are AdapterType, ChipSet, TrapRegs, Cleanup, and Lockand UnLock. A check against the adapter/chip set entries is used to confirm that the file is valid for the current configuration.

The list of entries in the TrapRegssection specifies the I/O port addresses and indexed ports that are to be saved and restored by the virtual video device driver. A bit mask for indexed registers is created and used for this purpose.

The Cleanup, Lock, and UnLocksections literally are used to perform the specified functions. Cleanupis required to put the adapter into a default clean state.

Install I/O Hooks

If the chip set uses port addresses that are not in the VGA range, I/O handlers must be installed to handle access to these ports when the DOS session is in the background. Otherwise, any Read or Write will be passed directly to the hardware or to a default handler. Hooks must be provided to take care of the accesses.

Registers with addresses outside the VGA range require individual treatment . Two arrays-ahleFgndwhen the DOS session is foreground, and ahleBgndwhen the DOS session is background-use a list of ports and their associated functions to handle Reads and Writes to the specified ports.

Initialize Shadow Register Data

The virtual video device driver retains sets of data on a per-DOS session basis. Copies of the contents of all the adapter registers should be stored in this area. All this data must be initialized, including data for extended registers. If the DOS session creation occurs while the DOS session is in the background, the same processing occurs as that for foreground, except that I/O port Reads and Writes are shadowed to and from instance data.

The first video-related operation is a BIOS call to set the initial video mode of the DOS session. If the BIOS expects certain configuration registers to contain information that is required when setting a mode, the shadow data must reflect this; therefore, before the DOS session executes, this shadow data must be set to some defaults - usually a simple case of reading the contents of all registers into the shadow data. This could occur while the hardware is set up in any particular mode; however, mode- specific data should be irrelevant.

Foreground/Background Processing

There are two main functions to be performed here: saving and restoring the contents of registers and video memory. All the information necessary to be able to restore a DOS session to the state at which it last executed should be available.

The ability to save and restore registers is dependent on two arrays of variable length - apleAlland apleNoTrap, which contain port addresses and pointers to data areas for each indexed and non-indexed port. apleNoTraphas entries for I/O ports not trapped when the DOS session is foreground. For example, if a write-only port address is always trapped, even when the DOS session is foreground, this permits its value to be restored from shadow data that is already valid; there is no need (or, in this case, possibility) to read the hardware. These entries in apleNoTrap, then, are for ports that must be read from the hardware. In contrast, the apleAllarray contains all port addresses and is used to restore the hardware state .

New port addresses that have not already been handled must be added to these array lists. Registers are restored in the order specified in the array. If there is some dependency as to the order of the programming registers on a restore, the array entries must reflect this dependency.

A number of flags are available when reading or writing registers, which is performed by a non-preemptible routine. One of the flags permits the Sequencer to be reset around the operation. This flag should be used where appropriate.

In any of the enhanced video modes, a shadow video buffer is required also to store all or part of video memory. The decision as to whether to save the entire contents of video memory, or only what is deemed to be in use, depends on two factors: what is known about the video mode in effect, or the default memory organization for that particular mode.

An additional problem that can be encountered when an enhanced mode is set and the DOS session is foreground is that there is no way to determine how much video memory the application has actually used. The only way to accurately determine this is to invalidate the address region occupied by video memory, trap bank selected registers, and handle page faults when this region is touched, invalidating the region with each change in bank. This constitutes background virtualization and is too costly for a foreground DOS session in terms of performance.

Saving all of the video memory all of the time could introduce a significant performance penalty: 1MB of shadow buffer must be kept somewhere and, with multiple DOS sessions in enhanced modes, this could become significant. Currently, a viable compromise is to save as much video memory as is calculated to be in use, using the mode data. (Mode data is determined by inspecting register values to get the display resolution. If this is not reflected in standard VGA registers, special handling is required.)

Upon notification that the DOS session is going into the background, that is, the DOS session is currently full-screen and has full hardware access, the DOS session is frozen to ensure that no further execution takes place. A snapshot of all the registers is thus saved by reading the hardware. As described previously, the apleNoTraparray triggers the saving of appropriate registers. Any special-case processing required to save register states should be a part of this process.

The video buffer contents are then saved in one of two ways:

�Linear modes are handled as straight transfers, 64KB at a time, by setting the appropriate bank and copying from video memory to the shadow buffer.

�Planar modes are copied, one plane at a time, and the 8514/A uses the graphics engine for the transfer.

The method used depends on the hardware capabilities. Some registers might need to be placed in a specific state before the video-memory transfer takes place to ensure that the memory organization does not interfere with what is saved. This shadow buffer will be used to create a bit map for the desktop, on request, if the DOS session becomes windowed.

Bringing a DOS session to the foreground is almost the reverse process. Registers first are restored to the saved state, and then video memory is restored, followed by another restore of the registers. Part of the memory transfer process involves setting registers to an appropriate state for transfer and could destroy the restored state.

Another important part of this foreground-background processing is the requirement to update data with only a best guessas to the current state of the DOS session. If the DOS session was permitted to run while in the background, its state could have changed from a text mode to graphics mode, or the type of graphics mode may have changed. It is important to be aware of this in order to successfully restore the state of the DOS session. VGA modes indicate their state through use of standard GDC, CRTC, or Sequencer registers, but such might not be the case for a particular chip set. Enhanced mode support could be enabled by the programming of some extended register. Awareness of this functionality must be included as part of updating the state information.

The situation that can arise when switching a DOS session that is using a graphics coprocessor to the background was described previously. The coprocessor could be in the process of accepting data from or passing data to the DOS session application. If, at this point, the DOS session is put into a suspended state, the coprocessor cannot complete the operation, and the DOS session will lose data. Any further attempt to use the DOS session will probably result in an error. The virtual video device driver could complete the operation on behalf of the application, but this might be too complex, unpredictable, or frankly impossible.

The most secure solution is to permit the DOS session to continue to execute until the coprocessor operation has completed. At that stage, before the DOS session is frozen, it is still going to be given an execution time slice. Therefore, you can block the virtual video device driver with a semaphore, effectively pausing the Set Backgroundprocess until the DOS session has completed its operation. One method of being notified that the operation is complete is to install I/O hooks for all ports and use them to clear the semaphore that blocked the virtual video device driver. Any subsequent port access then will permit the virtual video device driver to regain control to complete the background switch. Any number of hook types can be employed by the virtual video device driver. A coprocessor interrupt could be used, but that requires the use of a physical device driver and a communication mechanism between it and the virtual video device driver.

VGA Virtualization

In order for a DOS session to continue executing in the background while an enhanced video mode is set, some form of hardware emulation for that mode is required, if the hardware is not available. This might not always be possible. In the case of a coprocessed chip, some register accesses might be allowed, such as setting parameters for an impending coprocessor operation. The DOS session can be permitted to continue while this is the case; but if an operation is initiated requiring the coprocessor, DOS session execution must be suspended until the DOS session is brought to the foreground.

Dumb-frame buffer chip sets are easier to emulate in enhanced modes, particularly linear (packed-pel or 256-color) modes. Generally, any planar mode requires use of the hardware to achieve acceptable performance. VGA virtualization utilizes this when off-screen video memory is available. Linear modes can be virtualized as long as no hardware-assist functions are required. If the application restricts its operations to simply updating video memory by selecting banks and reading or writing data, it can continue to execute. All that is required in this case is to map the appropriate portion of the shadow video buffer to the expected part of the DOS session address space, usually the A000 region. Some level of support to achieve this already exists.

It is also possible that two or more distinct pieces of video hardware are available. If the desktop used one chip and a DOS session required use of a secondary chip, this would be possible. Multiple chip set scenarios such as this have many possibilities-beyond the scope of this document. If non- overlapping registers are used for each chip set, two distinct virtual video device drivers can be used; otherwise, the solution is more complex.

Chip Set-Specific Code

Although the PMI File attempts to encapsulate as much chip set-specific data as possible, some chip set-specific code is still required. Two elements, one to get or set the current video memory bank and another to determine the lock state of extended registers, are required.

The main function required is the ability to select banks of video memory for Save, Restore, and Memory-Management operations, requiring two routines : one to set a given bank, another to get the current bank. These routines must be operable from both the current hardware register state and shadow data, depending on whether called in a foreground or background context.

A similar problem involves determining the state of registers used to lock extended functionality, if applicable. The PMI File contains a sequence of I/O operations to be used to lock or unlock extended registers, but the current state of these register also must be determined. Often there is no direct mapping of what is written to these registers to lock or unlock them and what is read back when in either state. A necessary part of the save/ restore process is to retain the lock state.

Summary and Suggestions

The following is a guideline and list of files, with a brief summary of points as to what functionality, as described previously, is required in each.

vvuser.c

�Chip identification, PMI-File processing.

�Reserve the address space for mapping into other than A000-BFFF range.

vvstate.c

�Chip-specific Restore/UpdateSVGAIOState(), for example, Trident old and new register definitions that cannot be handled by way of PMI entries.

�Update memory state. If chip uses enhanced modes, use extended registers to determine if it is in enhanced mode.

�Check for greater than 16-color mode determination.

�Mode data structure setup, determining the number of horizontal and vertical scanlines and number of colors for current mode.

�Video memory state detection, 16-color, 256-color, or other modes.

�Restoring I/O state. Check if register ordering is important. Is Sequencer reset required around extended register update?

vvsvga.c

�Code routines for getting the register lock state.

�Code get and set bank routines.

�Ensure vvMaxBanks() routine returns appropriate data for allocating and saving the shadow video buffer.

vvdata.c

�Add entries to ahleFgnd, ahlBgnd, apleAll, apleNoTrap.

�Add get/set bank routine entries to apfnGetBank and apfnSetBank.

vvmode.c

�Cleanups, anything not handled by PMI-File cleandata.

vvpmi.c

�Add new token entries for PMI-File parsing.

vvport.c

�Install I/O hooks.

vvsvgaio.asm

�Routines to be called for new ports hooked in background.

vvsvgaid.asm

�Chip Set/Board identification code.

vvdp.h

�Create definitions for new adapter type and chip set.

�Add function prototypes for new functions defined.

Seamless Windows Support

Seamless support provides the ability to execute Windows applications in one or more windows on the OS/2 Desktop. The Windows applications run side by side with OS/2 Presentation Manager (PM) applications. To provide seamless support, you must modify both the PM and Windows display drivers.

Overview

Each seamless windows session is run as a protect-mode DOS session. The seamless session runs a copy of the Windows video display driver, modified to operate seamlessly. Seamless windows drivers write directly to the video display hardware, and must be modified to coordinate and serialize hardware access. As a result, a seamless windows driver actually "owns" a piece of the PM Desktop.

In addition to modifications to the PM and Windows drivers, the IBM Operating System/2 itself has been modified to support seamless operation. A special virtual device driver (VWIN) is used to establish limited addressability to a small set of key PM routines and data, as well as to provide services permitting hardware serialization and exchange of Windows state-change information.

[Artwork not shown]

Presentation Manager Display Device Driver

To enable a seamless session, the Presentation Manager display device driver must call the special virtual device driver, VWIN, using DOSRequestVDD. The PM driver passes initialization data to enable the seamless windows driver's access to necessary PM data and the shared data and code. After initialization, the PM driver again calls VWIN to define the current video mode and cursor size.

The PM display driver is responsible for initializing a fast safe RAM semaphore. (FSRamSemaphore) for synchronizing access to the video hardware. Both the PM and the seamless windows drivers must use the FSRamSemaphoreto coordinate video access. The PM driver can force release of this semaphore when necessary, for example, if the seamless DOS session stops with the Windows driver owning the semaphore. To avoid forcing an inappropriate semaphore release, heartbeat processinghas been incorporated into VWIN. The PM driver requests VWIN to initiate heartbeat processing when a timeout occurs on the PM driver's request for the FSRamSemaphore.

The PM Shield component, shown in the diagram in the previous figure, communicates with the PM driver, sending notifications whenever a seamless DOS session is created or destroyed. This enables the PM driver to modify its processing logic to be compatible with the seamless environment.

There are several other calls the PM video driver can issue to VWIN. At PM deathand resurrection(that is, on a switch to a full-screen DOS or WIN-OS /2 session), the driver calls VWIN to broadcast suspend/resume drawing messages to the seamless DOS sessions. These messages are transmitted to the DOS session's drivers by way of INT 2Fh.

Seamless Windows Display Device Driver

The seamless windows display device driver is usually derived from the standard Windows driver by conditional compilation. It must always start in the disabled state to establish all necessary addressability and data before beginning seamless operation. To start in a disabled state, the driver must simulate an INT 2Fh, Function 4001h, at startup. The seamless windows driver hooks INT 2Fh to receive all notifications of foreground- background switching. The Win Shieldcomponent, diagrammed in the previous figure, enables the seamless windows driver, using INT 2Fh, Function 4002h, when synchronized with the Presentation Manager Desktop.

Because the virtual display driver and the Win Shield have the ability to disable video output from the Windows driver (through INT 2FhH), a cumulative disable count must be kept in the driver. When a Disable occurs (INT 2Fh, AX=4001h), the count is incremented. On the first increment ( count = 1), output from the driver is disabled. Alternately, when an Enable occurs (INT 2Fh, AX=4002h), the count is decremented. When the count is 0, driver output can be enabled.

Most seamless processing and message handling is asynchronous; therefore, it is possible for multiple Disables to be received before any Enables take place. Events are posted to the DOS session and retained until a time sliceoccurs and they can be processed. As stated previously, a cumulative disable count is required.

At seamless windows driver startup, the driver must begin with a Disable count of 1 (in effect, forcing an INT 2Fh Disable on itself) to permit all the window shadowsfrom the desktop to be reflected to the DOS session's Win Shield. When this process is complete, the Win Shield enables the seamless windows driver by way of INT 2Fh.

When the first Enable() call is received, the seamless windows display driver must call VWIN, passing it a pointer to a WINDD_INIT structure. (The WINDD_INIT structure is described in detail later in the text.) VWIN completes this structure for the Windows driver.

It is critical for the seamless windows driver to coordinate all hardware access, using the video FSRamSemaphore, and it must always reset the video hardware to a default state upon release of the semaphore.

The seamless windows driver need not perform any cursor drawing operations, nor does it need to save and restore hardware registers when switched to the background. These functions are performed by the Presentation Manager driver. However, the seamless driver must call the PM cursor-exclusion routines when outputting to the screen, to protect the mouse pointer and prevent its erasure.

Presentation Manager Shield

The PM Shield maintains Workplace Shell windowing-state information, including that related to the seamless DOS sessions.

Upon creation of a seamless DOS session, the PM Shield notifies the virtual video device driver (for example, VVGA or VSVGA) to permit direct hardware access. Normally, the virtual video drivers control and intercept attempts to access the hardware. In a seamless DOS session, however, virtual video is modified to permit this hardware I/O.

As windowing-related events occur in the seamless DOS sessions, the PM Shield duplicates these events in the Workplace Shell to track the seamless DOS sessions. Examples of windowing events are:

�Create
�Destroy
�Move
�Resize

In addition to monitoring the seamless DOS sessions, the PM Shield registers with PMWIN to be posted whenever events occur that alter the state of the desktop. (Again, events such as Create and Destroy are monitored.) These events are forwarded to VWIN, which broadcasts them to the Win Shield in each seamless DOS session.

Windows Shield

The Windows (Win) Shield is the Windows counterpart of the PM Shield. It is both an executable file and a dynamic link library (WINSHELD.EXE and WINSMSG.DLL, respectively). Win Shield serves a complementary purpose, maintaining Workplace Shell windowing-state information for its DOS session .

Initial state information for the desktop is received when the Win Shield registers with VWIN. Subsequently, VWIN notifies the Win Shield whenever changes on the desktop occur. All the desktop information is received from the PM Shield and passed on by VWIN.

Additionally, the Win Shield registers with the Windows User component to obtain notification of internal Windows events. This information is then forwarded to VWIN to update the PM Shield.

VWIN Virtual Device Driver

VWIN is the special virtual device driver that lies at the heart of seamless operation. VWIN shares all Windows and PM Desktop windowing-state information, permits addressability to seamless data and code shared between the PM and Windows display drivers, and sends INT 2Fh notification to each seamless DOS session at PM death and resurrection, as described previously.

Interface to VWIN is achieved using the following two mechanisms:

�PM services are requested using DOSRequestVDD.

�Windows services are requested through INT 66h.

Note:The Windows services must be requested by an interrupt because VWIN executes at Ring 0 (the highest privilege level) and the seamless windows drivers do not.

Distributed Console Access Facility (DCAF)

Seamless Windows support is provided in DCAF for installations that require remote console functions between programmable workstations. See Distributed Console Access Facility (DCAF)for specific information.

In OS/2 2.1, Seamless Windows is supported by allowing the Windows display driver to draw directly on the Presentation Manager (PM) screen. This means that Seamless Windows updates do not go through the PM drawing functions and, therefore, will not update the active screen change area (SCA) in the usual way. As a result, Seamless Windows requires special treatment.

Prior to drawing on the PM screen, the Seamless Windows driver calls the PM driver through an exported entry point, SeamlessExcludeCursor. This call excludes the PM cursor from the area in which the Seamless Driver is about to draw. The modified XGA display driver intercepts this call and passes the rectangle coordinates to AccumulateScreenBounds.

Under DCAF, during PM display driver initialization, Seamless Windows must be granted addressability to all data and code that it will access during the call to SeamlessExcludeCursor. In order to add the supplied rectangle to all active SCAs, which can reside anywhere in the display driver heap, there is a single, static SSA (Seamless Screen Area called scaSeamless) used for this purpose. All Seamless bounding rectangles will be accumulated in scaSeamless; then, this SCA is merged with the other active SCAs when a query is issued via GreGetScreenChangeArea.

As a result, at initialization (in InitializeSeamless), the Seamless Windows driver is given access to AccumulateScreenBounds, to scaSeamless and to the DDT display driver control block, in order to retrieve the screen dimension at seamless time. The addresses of this data are stored in the SeamlessAddresses control block, owned by the Windows driver.

Before writing to the PM screen, the Seamless Windows driver will call SeamlessExcludeCursor. The exclusion rectangle will be passed in the following registers in so-called AI coordinates (i.e., 16-bit inclusive; 0, 0 is top left of screen):

Left cx
Top dx
Right si
Bottom di

The display driver will determine whether the new bounds accumulation is needed by checking the value of the pStartSCA pointer and, in SeamlessExcludeCursor32, will call AccumulateSeamlessBounds to initiate the bounds accumulation. AccumulateSeamlessBounds converts the passed rectangle to EXCLUSIVE SCREEN coordinates, clips the rectangle to the screen dimensions and calls AccumulateScreenBounds. This causes the rectangle supplied to SeamlessExcludeCursor to be added to only scaSeamless. When an SCA is queried using GreGetScreenChangeArea, the Seamless SCA is merged with the active SCAs and then reset to NULL.

Seamless Design Issues

There are multiple design issues in the seamless environment. The critical issues (those generating the most questions), are documented in the following sections:

�Determination of code and data to be shared between the PM and Windows display drivers

�Coordination of off-screen video RAM

�Save/restore processing of the video hardware registers/environment

�Implementation of semaphore and heartbeatprocessing

�Conversion of Windows cursors and icons in the PM environment

�Palette handling

�Sharing of cursor exclusion and Enable/Disable code, including problems to be avoided

�Setup and sharing of a pointer to video RAM.

Shared Data and Code between PM Drivers and Windows Drivers

Each design of seamless PM and Windows driver pairsrequires its own shared data/code structure, because each driver implementation and its underlying video hardware are unique. The contents of the structure varies across implementations. The shared data/code structure for seamless XGA is included in the following example:

  PMDD_IO_STRUC  struc
   LevelID                 dd  ?  ; 4 bytes to sync interface to PMDD.

     ; The following variables are in the PM DD's default data segment.
     ulMemRegBase          dd  ?  ; 16:16 addr of memory mapped XGA regs
     usIORegBase           dw  ?  ; Base of IO XGA regs
     ulVramBase            dd  ?  ; 32-bit physical memory addr of VRAM
     ulVramSize            dd  ?  ; Size of VRAM in bytes
     bfUseExternalPolling  db  ?  ; TRUE if external polling is supported

     usScreenWidthMM       dw  ?
     usScreenHeightMM      dw  ?
     usScreenWidthPels     dw  ?
     usScreenHeightPels    dw  ?
     bBitsPerPel           db  ?

     pSemaphore            dd  ?  ; Flat pointer to FSRamSemaphore
     pHeartBeat            dd  ?  ; Flat pointer to heartbeat counter

     pNumDefaultColors     dd  ?  ; Flat ptr to # of default colors in use

     pCursorStatus         dd  ?  ; Byte ptr: bit 0x80 set if sfw cursor
     pExcludeCursor        dd  ?  ; 16:16 addr of exclude cursor function
     pDisableCursor        dd  ?  ; 16:16 addr of disable cursor function
     pEnableCursor         dd  ?  ; 16:16 addr of enable cursor function

     WindowsPrivateArea    db WINDOWS_PRIVATE_AREA_SIZE dup (?)
  ;------------------------------------------------------------------
  ; Information shared among the XGA Windows' drivers.
  ; Multiple Windows drivers can exist, running in multiple DOS sessions.
  ; SecondaryFontStart     dd  ?
  ; SecondaryFontEnd       dd  ?
  ;
  ; SystemFontTable        dd  256 dup (?)
  ; SecondaryFontTable     dd  256 dup (?)
  ;
  ; SystemFontHeight       dw  ?
  ; SystemFontPoints       dw  ?
  ; SystemFontWidth        dw  ?
  ; SystemFontCached       db  0
  ;
  ; SecondaryFontName      db  0
  ;                        db  32 dup (?) ; Max facename length=32.
  ;
  ; SecondaryFontNameLen   dw  1
  ; SecondaryFontHeight    dw  0
  ; SecondaryFontPoints    dw  0
  ; SecondaryFontWidth     dw  0
  ;
  ; SecondaryFontHdr       db  32 dup(0)
  ; SystemFontHdr          dw  16 dup(0)
  ; PaddedField            db  32 dup(0) ; Remaining reserved.
  ;------------------------------------------------------------------
  ; Total 2200 bytes reserved by the PM driver for Windows' drivers.

     bfPaletteIsFixed      db  ;  TRUE if palette manager not enabled
     ulLastPalUpdate       dd  ;  Timestamp of last foreground realize
     pHWPalette            dd  ;  16:16 ptr to HWPalette structure
     PMKWSPhysicalBase     dw  ;  Physical addr of 64KB kernel workspace for
                               ;   bus-mastering into/out of system memory
     PMKWSLinearBAse       dd  ;  Linear addr of 64KB workspace

  PMDD_IO_STRUC ends

The initial entry in this shared structure must be a driver signature. For XGA, the signature is XG01. For VGA, the signature is VG01. This field must be checked by the Windows driver at initialization. If an incorrect entry is found, the Windows driver must report initialization failure to the GDI. This mechanism prohibits the running of non-compatible seamless driver pairs (for example, using a VGA seamless windows driver with a Presentation Manager XGA driver).

Coordination of Off-Screen Video RAM

A static division of off-screen video memory is typically employed to permit access to this resource for both the Presentation Manager and seamless windows drivers. Alternatively, dynamic allocation or total dedication of the memory to one driver is used. However, these alternatives could decrease performance.

At a minimum, both the PM and seamless windows drivers' character caches are maintained in off-screen video memory for the sake of performance.

Save/Restore Processing of Video Registers/Hardware

A straightforward approach to save/restore processing is to force both the PM and seamless windows drivers to explicitly set video hardware registers anytime the registers are required. Since the video FSRamSemaphoremust be used to coordinate hardware access, this semaphore can be obtained, the necessary register(s) set and used, and the semaphore released with no problem.

An alternative approach is to design the necessary save/restore processing and mark the associated registers and resources with handles(such as SessionIDs).

Implementation of Semaphore Processing

Most 16-bit presentation drivers use the FSRamSemaphoremechanism to serialize output. This same mechanism is used by the PM and seamless windows drivers in the 32-bit environment. FSRamSemaphoresuse the drivers' data area to store the semaphore. Therefore, the Presentation Manager driver must establish the semaphore and provide its address to the seamless windows driver in the shared data/code structure. This logic flow is true for both the 16-bit and 32-bit environments.

In the 32-bit environment, there are new FSRamSemaphoreentry points, and 16-bit drivers now have alternative entry points. The new entry points have been optimized for efficiency. The following is a list of both the new and alternative semaphore entry points:

/-------------------------------------------------------------\
|New and Alternative Entry     |Original Entry Points         |
|Points                        |                              |
|------------------------------+------------------------------|
|RAMSEMREQUEST16               |FSRSemEnter                   |
|------------------------------+------------------------------|
|RAMSEMCLEAR16                 |FSRSemLeave                   |
|------------------------------+------------------------------|
|RAMSEMREQUEST32               |                              |
|------------------------------+------------------------------|
|RAMSEMCLEAR32                 |                              |
\-------------------------------------------------------------/

The semaphore entry points all have one parameter-a pointer to a FSRamSemaphorestructure. The structure contains the following fields:

usLength           Length of structure
usPadding
usProcessID        ID of owning process
usThreadID         ID of owning thread
usUsage            Usage counter
usClient           Client field, see note below
ulTimeout          System default timeout value
ulRamSem           Semaphore

Note:The usClientfield is the only field that, for normal processing, the presentation driver should access directly. This field is initialized as 0 when the semaphore is first acquired and thereafter is controlled by the driver. The intention is to give a DC some way of flagging a semaphore to notify the driver's ExitList processing routine of any special action it needs to take when releasing the semaphores.

The RAMSEMREQUESTxx functions return 0 if successful, and a nonzero error code otherwise.

The RAMSEMCLEARxx functions have no return information, and are void functions.

To support FSRamSemaphores, 32-bit Presentation Manager drivers must link with the OS2386 library, and 16-bit drivers must link with the OS2286 library.

To use FSRamSemaphoresfor coordinating hardware access, the seamless windows drivers must implement request_semaphore() and clear_semaphore() code logic. The purpose of request_semaphore() is to own the semaphore; clear_semaphore() relinquishes ownership.

When requesting the semaphore (if it is already owned by the current process), the semaphore's usage count must be incremented. If the semaphore is available, it is marked as owned by the current process. However, if the semaphore is owned by a different process, a call is made (indirectly) to the OS/2 kernel to block the thread until the semaphore is released. The mechanism for calling the OS/2 block_semaphore function is to issue an INT 66h to VWIN with some parameters passed through registers. VWIN then calls OS/2 block_semaphore on behalf of the seamless windows driver to wait on the specified FSRamSemaphore. The following code section illustrates how to acquire the FSRamSemaphore:

     mov     ax, _DATA
     mov     ds, ax
     assumes   ds ,   Data 


; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
;   Get   our   process   ID   and   thread   ID 
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

      mov       cx ,   init _ struct . thread _ id           ;   Get   the   current   thread   ID 
      mov       dx ,   init _ struct . proc _ id              ;    and   current   process 

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
;   Get   addressability   to   the   hardware   semaphore   structure 
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

      mov       di ,    PMDD _ IO _ SEL                     ;   PM   selector 
      mov       fs ,    di 
      mov       edi ,   init _ struct . pmdd _ io            ;   FS : EDI   - >   pmdd _ io   struct 
      mov       edi ,   fs : [ edi ] . pSemaphore            ;   FS : EDI   - >   pSemaphore 

sem _ retry : 
      mov       ax ,   word   ptr   fs : [ edi ] . fs _ ProcID     ;   Touch   the   page 
      cli 
      mov       ax ,   word   ptr   fs : [ edi ] . fs _ ProcID     ;   Is   the   semaphore   owned ? 
      or        ax ,   ax 
      jnz       SHORT   sem _ owned                      ;   Yes ,   see   if   it   is   caller ? 

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
;   Here ,   if   the   semaphore   is   currently   unowned ,   marked   as   owned   by   the 
;   current   process   ID   and   thread   ID ;   set   the   usage   count   to   1   and   mark 
;   the   RAM   semaphore   as   SET . 
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

      mov       WORD   PTR   fs : [ edi ] . fs _ ProcID ,   dx 
      mov       WORD   PTR   fs : [ edi ] . fs _ ThrdID ,   cx 
      mov       ax ,   1 
      mov       fs : [ edi ] . fs _ Usage ,   ax                ;   Set   usage   count   to   1 . 
      mov       fs : [ edi ] . fs _ RAMSem . RamSemOwner , al   ;   Set   RAM   semaphore . 
      sti 
      jmp       SHORT   request _ semaphore _ exit 

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
;   Here ,   if   the   semaphore   is   currently   owned .    Check   to   see   if   current 
;   owner   is   the   caller . 
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
sem _ owned : 
      cmp       ax ,   dx                                ;   Is   the   semaphore   owned 
                                                      by   caller ? 
                                                    ;   Essentially ,   pidOwner 
                                                      = =   pidCaller ? 
      jne       SHORT   sem _ owned2                     ;   No ,   go   wait . 


; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
;   If   the   semaphore   is   already   owned   by   the   current   process   ID   and 
;   thread   ID ,   then   nothing   to   do   but   increment   the   usage   count . 
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

      inc       fs : [ edi ] . fs _ Usage 
      sti 
      jmp       SHORT   request _ semaphore _ exit 

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
;   If   the   semaphore   is   already   owned   by   some   other   process   ID   and 
;   thread   ID ,   then   perform   an   INT   66h   to   request   the   VDD   ( VWIN ) 
;   to   call   the   CPDOS   RAM   Semaphore   mechanism   on   our   behalf .    When 
;   it   returns ,   jump   back   to   the   beginning   of   this   function   to   try 
;   to   get   the   semaphore   again . 
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

sem _ owned2 : 
      sti 

; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
;   Block   this   thread   until   the   semaphore   is   available . 
; - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 

;   AH   =   82H   (   Function   Code   for   VWIN   ) 
      xor       ax ,   ax 
      mov       ah ,   VWIN _ SEM _ BLOCK                 ;   Block   for   semaphore   function 

;   ECX   - >   Semaphore   timeout 
      mov       ecx ,   fs : [ edi ] . fs _ Timeout 

;   EBX   - >   CPDOS   RAM   Semaphore 
      ; Thunk   the   high   word   of   the   32 - bit   offset   in   esi   into   16 : 16   addr   in   ebx 
      ; ie ,   multiply   high   word   by   8   and   set   the   LS   3   bits   on . 
      lea       esi ,   fs : [ edi ] . fs _ RAMSem 
      shld      ebx ,   esi ,   19 
      or        bx ,   7 
      shl       ebx ,   16 
      mov       bx ,   si 

;   Set   DS : SI   to   " VWIN " 
      mov       si ,   OFFSET   vwin _ id 

;   Block   on   the   semaphore 
      pushf 
      call       DWORD   PTR   init _ struct . pfvwin 
; * * * *     int       66h 

      jmp       sem _ retry                            ;   Go   back   and   try   to   get   it 

request _ semaphore _ exit : 
      mov       edi ,   Heartbeat 
      inc       DWORD   PTR   fs : [ edi ]                  ;   Increment   the   heartbeat   counter 
      . . . . . 

When clearing the semaphore, the seamless windows driver should decrement the FSRamSemaphore's usage count. When this usage count reaches 0 (after decrementing), the semaphore's RamSemFlagfield is saved, and then the entire semaphore structure is set as not owned. The saved RamSemFlagis checked (TRUE or FALSE) to determine whether any processes that are being blocked by the semaphore need to be unblocked. To unblock a requesting process, an INT 66h is issued to VWIN with the parameters passed in the appropriate registers. VWIN then invokes the OS/2 kernel wake_up function. The following code fragment shows how to clear the FSRamSemaphore:

     mov     ax, _DATA
     mov     ds, ax
     assumes ds, Data

;---------------------------------------------------------------------
; Get our process ID and thread ID
;---------------------------------------------------------------------

     mov     cx, init_struct.thread_id          ; Get current thread ID
     mov     dx, init_struct.proc_id            ; and current process ID

;---------------------------------------------------------------------
; Get addressability to the Hardware Semaphore structure
;---------------------------------------------------------------------

     mov     di, PMDD_IO_SEL                    ; PM selector
     mov     fs, di
     mov     edi, Init_struct.pmdd_io           ; FS:DI -> pmdd_io struct
     mov     edi, fs:[edi].pSemaphore           ; FS:DI -> pSemaphore

     mov     ax, fs:[edi].fs_ProcID             ; Touch the page
     cli

;---------------------------------------------------------------------
; See if semaphore is owned by calling process/thread
;---------------------------------------------------------------------

     cmp     fs:[edi].fs_Usage, 0               ; See if owned
     je      SHORT sem_leavebad                 ; No, declare an error

     mov     ax, fs:[edi].fs_ProcID
     cmp     dx, ax                             ; pidOwner == pidCaller?
     jne     SHORT sem_leavebad                 ; No, declare an error
     jmp     SHORT sem_leaveok                  ; Yes, proceed

sem_leavebad:

     sti
     jmp     SHORT exit_clear_semaphore

sem_leaveok:

;---------------------------------------------------------------------
; Decrement the usage count
;---------------------------------------------------------------------

     dec     fs:[edi].fs_Usage                  ; Decrement the usage count
     jz      SHORT release_sem
     sti
     jmp     exit_clear_semaphore

;---------------------------------------------------------------------
; Release the semaphore by setting the process ID and thread ID
; fields to 0, clearing the RAM semaphore and remembering if any
; other threads were waiting on the RAM semaphore.  If not, re-enable
; interrupts and return.
;---------------------------------------------------------------------

release_sem:

     xor     dx, dx
     mov     word ptr fs:[edi].fs_ProcID, dx     ; Clear pid
     mov     word ptr fs:[edi].fs_ThrdID, dx     ; Clear tid
     mov     fs:[edi].fs_Client, dx              ; Clear client
     mov     fs:[edi].fs_RAMSem.RamSemOwner, dl  ; Clear ramsemowner
     xor     cx, cx                              ; Clear the cx register
     xchg    fs:[edi].fs_RAMSem.RamSemFlag, cl   ; and set it to the sem flag
     or      cx, cx                              ; Is the sem being requested?
     jnz     SHORT sem_waiting                   ; Yes, call wakeup

     sti
     jmp     SHORT exit_clear_semaphore

;---------------------------------------------------------------------
; Some other process/thread is waiting for this semaphore.  Perform an
; INT 66h with the appropriate function, which will call the CPDOS
; wakeup code (done through the VDD) to unblock all of the waiting
; threads.  Non-deterministic as to which one will actually get the
; semaphore first.  The others will have to wait again.
;---------------------------------------------------------------------

sem_waiting:
     sti

;--------------------------------------------------------------------
; Issue the INT 66h call to wake up any threads that are blocked on
; the semaphore.
;--------------------------------------------------------------------

; AH = 83H ( Function Code for VWIN )
     xor     ax, ax
     mov     ah, VWIN_SEM_WAKE                   ; Wake function

; Set DI:SI to "VWIN"
     mov     si, OFFSET vwin_id

; EBX -> CPDOS RAM Semaphore
     ; Thunk the high word of the 32-bit offset in edit into 16:16 addr in ebx
     ; ie, multiply the high-word by 8 and set the LS 3 bits ON.
     lea     edi, fs:[edi].fs_RAMSem
     shld    ebx, edi, 19
     or      bx, 7
     shl     ebx, 16
     mov     bx, di

; Block on the semaphore.  CX should contain the old RamSemFlag value.
     pushf
     call     DWORD PTR init_struct.pfvwin
;****   int       66H 

exit _ clear _ semaphore : 
      . . . . . 

At times, the PM driver must free the video semaphore to continue processing. This might be required in the case of a DOS session failure when the seamless windows driver is the semaphore owner. Sample semaphore release processing is included in the following code fragment. It is important to note that, in freeing the semaphore, the PM driver's process ID and thread ID (PID/TID) must be placed in the semaphore structure.

VOID SeamlessForceSemRelease(VOID)

{

     PTIB pThreadInfo;
     PPIB pProcessInfo;

     /***********************************************************/
     /* Set the semaphore owner to be us.  The changing of the  */
     /* semaphore owner must be atomic to avoid letting in any  */
     /* other threads.                                          */
     /***********************************************************/
      DosGetInfoBlocks(&pThreadInfo,
                &pProcessInfo);
  //  FSRDriverSem.ProcID = (USHORT) pProcessInfo->pib_ulpid;
  //  FSRDriverSem.ThrdID = (USHORT) pThreadInfo->tib_ptib2->tib2_ultid;

      *((PULONG)&FSRDriverSem.ProcID) =
      ((pThreadInfo->tib_ptib2->tib2_ultid) << 16) |
      (pProcessInfo->pib_ulpid);

/****************************************************************/
/* Free the semaphore.                                          */
/****************************************************************/
      while (FSRDriverSem.Usage != 0)
      {
  ReleaseDriverSemaphore();
      }
  }

Implementation of Heartbeat Processing

For seamless windows drivers, the only heartbeat processing required is to increment the heartbeat counter in the PM and Windows shared data/code structure. This counter must be incremented after obtaining the video hardware semaphore and prior to accessing the hardware.

The counter is checked by the PM driver as part of its semaphore timeout logic. Upon a second timeout, if the semaphore owner is unchanged and the heartbeat counter also is unchanged, the Presentation Manager driver will assume that the DOS session is hung and try to force release of the video semaphore. The following code sequence demonstrates this processing logic:

  /********************************************************************/
  /* This function carries out PM Heartbeat Processing.               */
  /* It detects when the Windows driver has stopped while             */
  /* holding the semaphore and tidies up if need be.                  */
  /********************************************************************/
  VOID SeamlessHeartbeat(VOID)
  {
    HVDD  hSeamlessVDD;
    ULONG ulReturnCode;

    /******************************************************************/
    /* If seamless windows is not enabled, we do nothing.             */
    /******************************************************************/
    if (fSeamlessEnabled)
    {
        /**************************************************************/
        /* See if we are timing out for the second time with the same */
        /* PID, TID, and heartbeat.                                   */
        /**************************************************************/
        if (   (usHeartBeatPID == FSRDriverSem.ProcID)
            && (usHeartBeatTID == FSRDriverSem.ThrdID)
            && (ulHeartBeat == 0))
        {
            /**********************************************************/
            /* This is the second time we have timed out with the     */
            /* same PID and TID owning the semaphore and the heart    */
            /* beat has not changed.  We must call VWIN to see if a   */
            /* clean up is required.                                  */
            /**********************************************************/
            /**********************************************************/
            /* Open the seamless VDD ("VWIN").                        */
            /**********************************************************/
            ulReturnCode = DosOpenVDD("VWIN", &hSeamlessVDD);

            if (ulReturnCode != 0)
            {
                /******************************************************/
                /* The DosOpenVDD call encountered an error of some   */
                /* sort!                                              */
                /******************************************************/
                LogDosError(ulReturnCode);
                return;
            }

            /**********************************************************/
            /* Send VWIN the timeout on semaphore signal.             */
            /**********************************************************/
            ulReturnCode = DosRequestVDD(hSeamlessVDD,
                                NULL,
                                VWIN_HEARTBEAT,
                                FSRDriverSem.ProcID,
                                NULL,
                                FSRDriverSem.ThrdID,
                                NULL);

            if ((ulReturnCode == 0) || (ulReturnCode == 2))
            {


                /******************************************************/
                /* The return code indicates that we should clean up. */
                /******************************************************/
                SeamlessForceSemRelease();

                /******************************************************/
                /* Clean up other heartbeat stuff.                    */
                /******************************************************/
                usHeartBeatPID = 0;
                usHeartBeatTID = 0;
                ulHeartBeat = 0;
            }

            /**********************************************************/
            /* Close the handle to VWIN.                              */
            /**********************************************************/
            DosCloseVDD(hSeamlessVDD);
        }
        else
        {
            /**********************************************************/
            /* Just record the PID and TID of the semaphore owner and */
            /* reset the heartbeat counter.                           */
            /**********************************************************/
            usHeartBeatPID = FSRDriverSem.ProcID;
            usHeartBeatTID = FSRDriverSem.ThrdID;
            ulHeartBeat = 0;
        }
    }
  }

Windows Cursors and Icons in the PM Environment

The Windows standard cursors (crossbar, arrow, etc.) have been converted to PM resources as part of the seamless VGA and XGA development. These resources are used, unchanged, by the PM driver. It is important to notice that when the cursor is over a seamless windows application, Windows cursors should appear, not Presentation Manager resources. The converted standard Windows cursors are provided as PM resource files.

Non-standard Windows cursors and icons are passed by the Win Shield component to the PM Shield and, ultimately, to the PM driver, for conversion when they are created by an application.

Palette Handling

Seamless palette management is achieved using the existing seamless components, hardware synchronization, and event-flow mechanisms. Currently, the Windows GDI component handles all palette issues, calling the Windows driver only to actually set the hardware registers. This processing must be modified for seamless palette management. to permit only palette realizations by PM, using the PM driver palette logic.

Note:PM Palette Management is actually a superset of Windows Palette Management in that PM must coordinate logical color table processing ( default palette) as well as permit palette changes by way of the Palette Management interface. There is so much similarity in the PM and Windows palette application calls and processing that permitting PM to process a Windows palette realization is quite straightforward.

The Windows GDI has been modified to request palette entries and changes through normal OS/2 GPI/GRE processing. Also, the color mapping of the 20 Windows system colors must be supported in the PM driver palette. This requires a remapping of the PM palette, moving the 20 Windows colors to the top 10 slots and bottom 10 slots of the physical palette. Remapping the PM palette involves moving entries such that the closest entry to the Windows default color is at the specified location. Later, a translation table is used by PM when the driver selects a "closest fit" color, using its algorithms. The result of the algorithms is run through the translation table to determine the selected color's actual palette location. This has a negligible effect (fewer than 50 clock cycles) on performance.

The key item is that seamless palette management can exist because the Windows and PM palette APIs, and associated functionality are so similar. In both Windows and PM, an application creates, selects, and realizes a palette (in that order). In addition, there is a concept of palette animation in both Windows and PM. Animation permits a palette entry's color to be changed quickly, without affecting the rest of the palette or redrawing the image. Therefore, all Windows palette manipulation can be requested through normal GPI/PMWIN APIs, with the exception of animation. Animation is even simpler. It can be handled directly by the Windows GDI once PM has defined the animateable palette slot and returned this information to GDI.

The most straightforward way to describe the design of seamless palette management is to look at the processing flow:

1.At PM seamless startup, a PM and Windows shared memory area is established and initialized. Several entries are added to this shared area for seamless palette management, as follows:

�FixedPMPalette (Boolean, indicating a non-Palette Management PM Driver)

-If the PM Driver is not palette-aware, the GDI will operate, assuming a fixed palette. This assumption is accounted for in the GDI code, since Windows drivers exist for fixed palette hardware.

-For XGA and SVGA, because the drivers incorporate palette management, the flag is always FALSE.

�TimeLastPalUpdate(timestamp of the last reorganization of the palette due to focus change and resultant realize request)

-When the focus changes and the application now in focus realizes, the entire palette is reshuffled. This invalidates the current GDI palette entries. The time stamp is a mechanism for the GDI to be instantly aware of this change.

Note:For simplicity, this could also be implemented as a counter.

�PtrPhysicalPalette (Pointer to a shadow of the physical hardware palette)

2.After Windows driver initialization, the GDI issues a Driver Control() call requesting the address of the data described above. (A Control() call is really the end result of an application deviceescape. The GDI is responsible for translating Escape() calls to Windows Driver Control() functions.) After this call, the GDI has addressability to all the necessary PM palette information.

The format of the Control() function is:

     rc = Control ( lpDevice, SEAMLESS_PAL_INIT, lpInDate, lpOutData)

     where

     lpDevice = a long pointer to a data structure of type PDEVICE,
        the destination device bit map

     SEAMLESS_PAL_INIT = a word of value 6010
     lpInData  = NULL
     lpOut Data = a long pointer to a structure that contains:

        bfPaletteIsfixed
        ulLastPalUpdate
        pHWPalette

     (These are the palette-related entries in the PM/Windows shared
     data/code area).

3.In the course of normal seamless processing, if the GDI requires a hardware palette change, the GDI requests this change through PM's GPI/GRE, using the Windows and PM Shields. However, the GDI also issues a standard call to OEMSetPalettein the seamless windows driver. In this call, a null pointer is passed, instead of a pointer to a valid palette, to notify the seamless windows driver that a palette change has occurred through PM. In this case, the seamless windows driver updates only its private image copy of the palette, using the data pointed to by the 16:16 hardware palette address (pHWPalette) in the PM and Windows shared data/code area.

Note:The first 10 entries and last 10 entries of the palette in the shared data/code area are not exact matches to the static Windows** colors set forth by Microsoft**. They are the closest fitcolors available in the PM default palette. Therefore, these 20 entries must never be modified in the seamless windows driver private image.

When the palette address pointer in OEMSetPaletteis not NULL (that is, when a valid color table is passed), the seamless windows driver must update the video hardware palette as usual, as well as update its private image copy of the palette. This only occurs in seamless processing when a Windows application is animating the palette. It is important that the seamless windows driver first requests the video semaphore and then clears the semaphore after updating the hardware palette.

4.The Win Shield and PM Shield are responsible for forwarding all RealizePaletterequests to the Windows DOS sessions and Presentation Manager applications. These requests are received and processed as usual.

5.On a palette realization for GDI, the PM Shield returns the logical-to- physical mapping of the requested color table to the DOS session's Windows GDI. This information is obtained from the PM driver using a GRE call that is hooked by the PM driver - GREQueryPaletteRealization. When the PM Shield calls this function and passes a device context and a pointer to an array of ULONGS, the PM driver returns the mapping from the logical color table to the hardware palette in the ULONG array. Seamless operation requires no special flags or different processing.

6.There is one additional requirement in seamless Presentation Manager. In the Windows OEMUpdateColorsfunction, the seamless windows driver must add the hardware serialization code to its processing logic before performing any video hardware access. The video FSRamSemaphoremust be requested, and cleared upon exit of this routine. If this is not done, screen and font damage can occur.

As always, before requesting the video fSRamSemaphore, the seamless windows driver should check the hardware access state. If the driver is not enabled , the Windows driver should call Win Shield, requesting a repaint of the Windows Desktop.

Sharing Cursor Exclusion and Enable/Disable Code

Cursor exclusion or disable code is always required when software cursors are in use. The seamless windows driver must use the PM cursor routines. Even when hardware cursors are used, it is recommended that the PM cursor routines be called by the seamless windows driver. This enables the PM driver to accumulate bounding rectangles of modified areas of the screen to support applications such as remote help-desk screen access.

The example of a PM and Windows shared data/code area given previously for XGA demonstrates how cursor exclusion and enable/disable can be implemented .

That example includes the following entries in the shared structure:

     pCursorStatus        dd  ?       ; Byte ptr: bit 0x80 set if sfw cursor
     pExcludeCursor       dd  ?       ; 16:16 addr of exclude cursor function
     pDisableCursor       dd  ?       ; 16:16 addr of disable cursor function
     pEnableCursor        dd  ?       ; 16:16 addr of enable cursor function

In this example, the seamless windows driver has the option of calling the PM cursor routines, but only when a software cursor is in use (by checking the CursorStatus byte). However, in the current XGA implementation, the seamless windows driver calls the PM routines whenever it requests the video FSRamSemaphore and the destination is the screen. (This enables the XGA PM driver to accumulate bounding rectangles of all screen windows.) The seamless windows driver calls the PM ExcludeCursor routine when a hardware cursor is in use, DisableCursor when a software cursor is in use, and EnableCursor whenever the video FSRamSemaphore is cleared and the destination is the screen. For XGA, the cursor exclusion rectangle coordinates are passed on the stack.

The PM cursor functions are accessed by a 16:16 address (entry point) that is exported by the PM driver. At this address is the PM thunk code and the call to the actual PM 32-bit cursor function. The thunk is not compiled but done by hand in the code itself. Sample code from the XGA PM driver is included in the following code fragment:

  ;-----------------------------------------------------------------------
  ;
  ; SeamlessExcludeCursor is the thunked entry point to eddm_ExcludeCursor.
  ; The exclusion rectangle is passed in the following registers in AI coords
  ; (that is, 0,0 is top left of screen).
  ;
  ;       left    top     right   bottom
  ;       cx      dx      si      di
  ;
  ;-----------------------------------------------------------------------
        align   4
  _SeamlessExcludeCursor   proc far

        ; If we are not using a software cursor, we can go for a
        ; fast exit.  We know that the Windows driver always has
        ; fs set up to be the flat selector, so we use it here to
        ; access our 32-bit data.

        mov     eax, offset FLAT:_cursor_data.cd_cursor_status
        test    byte ptr fs:[eax], CURSOR_SOFTWARE
        jz      short SEC_exit

        ; Save ds and es on the 16-bit stack.

        push    ds
        push    es

        ; Get the FLAT selector into ds and es.

        mov     ax, SEG FLAT:_DATA
        mov     ds, ax
        mov     es, ax

        ; Before we start using esp and eip, we must disable interrupts.
        ; An interrupt can damage the top half of the registers
        ; because it thinks we are 16-bit. Touch all the pages we might
        ; access before disabling interrupts (a page fault is non-maskable
        ; and will re-enable interrupts).

        call    SeamlessTouchPages
        cli

        ; Save ss:sp (that is, 16-bit stack) in ebx.

        mov     bx, ss
        rol     ebx, 16
        mov     bx, sp

        ; Set up the 32-bit stack.

        mov     ax, SEG FLAT:_DATA
        mov     ss, ax
        mov     esp, offset FLAT:_SeamlessStack+SEAMLESS _ STACK _ SIZE 

         ;   Now   on   32 - bit   stack , 
         ;   save   the   16 - bit   ss : sp   on   the   32 - bit   stack . 

         push      ebx 

         ;   Jump   into   the   32 - bit   code ,   which   will   call   the   32 - bit   exclusion   code . 

         jmp       far   ptr   FLAT : SeamlessExcludeCursor32 

   ret _ from _ exclude32 : 
         pop       eax 
         mov       dx , ax 
         rol       eax , 16 
         mov       ss , ax 
         movzx     esp , dx 

         ;   Now   on   16 - bit   stack 

         sti 

         pop       es 
         pop       ds 

   SEC _ exit : 
         retf 
   _ SeamlessExcludeCursor   endp 

Note:

Interrupts must be disabled before setting and using esp and eip. This is done to prevent entering 32-bit interrupt handling code when the current task, the DOS session, is known to be 16-bit. In this case, the ip and sp pointers would be set for a 16-bit environment, not 32-bit.

All code pages that might be required by the execution of the shared seamless functions must be present in memory before disabling interrupts. A page fault cannot be taken while in the seamless shared code.

Care must be taken that an STI instruction is not included in the PM cursor routines when executed by a DOS session. Interrupts must remain disabled ( when executed by a DOS session) until returning through the thunk logic and being enabled.

Care also must be taken not to cause any ring transitions (from Ring 3) within the PM code executed from a DOS session. Therefore, there cannot be any operating system calls, etc. executed.

Set Up and Sharing of a Pointer to Video RAM

A shared pointer to video memory might be required in a seamless environment.

To establish the pointer in a 32-bit environment, the PM display driver calls PMDD.SYS (using DOSDevIOCtl) at initialization. The PM driver passes in the physical address of video RAM and its size, and gets back a Ring 2- or Ring 3-accessible linear address for the video memory. This address is then included and initialized in the seamless shared data/code area. VWIN handles the sharing requests necessary to access the pointer from the seamless windows driver.

To support the allocation of the global pointer to VRAM, the function AllocGlobalVRAM has been added to PMDD.SYS:

     AllocGlobalVRAM - (Function 0x7E)
     Called via:  DosDevIOCtl( pData, pParms, 0x7E, 3, hDev )

     where:

         pData points to a ULONG in which the flat address to
         VRAM will be returned.
         pParms points to a structure of the following type:
               struct _PARMS {
                   ULONG PhysicalAddress;
                   ULONG Length;
                   ULONG Flags;
                } PARMS;
               where:
                   PhysicalAddress is the beginning of the
                   video RAM.
                   Length is the length of video RAM in bytes.
                   Flags is a field of flags of which only the
                         least significant bit is currently
                         defined.  If the first bit is set, the
                         pointer returned will be shareable and
                         can be used to access VRAM at any
                         privilege level.  If the first bit is
                         0, the pointer returned will be global
                         and only accessible from Ring 0.  All
                         other bits are reserved and should be 0.
               (For the seamless environment, Flags should be 1.)
        hDev is the handle returned from a DosOpen call of the
              SINGLEQ$ device.
    Returns:  0 if successful, or a non-zero error code on failure.

As mentioned above, all addressability to the video memory for the seamless windows drivers is handled by VWIN. However, if additional PM processes also require addressability, they must issue an AccessGlobalVRAM call to PMDD.SYS. (Please note that the process that allocates the pointer does not require this AccessGlobal call. The AllocGlobalVRAM function performs all necessary processing to allow the calling process' access of video memory.)

     AccessGlobalVRAM - (Function 0x7F)
     Called via:  DosDevIOCtl( NULL, pParms, 0x7F, 3, hDev )
     Where:
         pParms points to a structure of the following type:
               struct _PARMS {
                   ULONG FlatAddress;
                   ULONG Length;
                } PARMS;
               where:
                    FlatAddress is a pointer that was returned
                          from a previous call to
                          AllocGlobalVRAM.
                    Length is the length of Video Memory in
                          bytes.
         hDev is the handle returned from a DosOpen call of the
             SINGLEQ$ device.
   Returns:  0 if successful, or a non-zero error code on failure.

PM Driver Calls to VWIN - Accessed via DOSRequestVDD

�Function = Pass initialization structure

     HVDD  = Handle of VDD (returned from DosOpenVDD)
     SGID  = NULL
     ULONG = 0x000000C0
     ULONG = Number of array elements
     PVOID = Pointer to array of SM_PMDISP structures
     ULONG = 0
     PVOID = NULL

     typedef struct _SM_PMDISP
     {
       ULONG  flOptions;/* BIT1 BIT0=xx ring level if BIT3=1  */
                        /* BIT2=0 for DATA    BIT2=1 for CODE */
                        /* BIT3=0 for 16:16   BIT3=1 for 0:32 */
                        /* BIT4=0 for mapping BIT4=1 for      */
                        /* passthru; if passthru, VWIN does   */
                        /* not touch                          */
                        /* BIT5=1 to force linear addresses   */
                        /* to match otherwise, 16:16 addrs    */
                           are remapped in the DOS session    */
                        /* BIT6 - BIT31 reserved (must be 0)  */

       ULONG  ulLength; /* Length of the data in bytes        */

       union            /* Pointer to the beginning address   */
                        /* of shared memory structure         */
       {
         PVOID  p16;    /* for 16:16 (BIT3=0)                 */
         ULONG  p32;    /* for  0:32 (BIT3=1)                 */
       } Start;

     } SM_PMDISP;

�Function = Signal timeout of the hardware semaphore

    HVDD  = Handle of VDD (returned from DosOpenVDD)
    SGID  = NULL
    ULONG = 0x000000C1
    ULONG = PID to test/kill
    PVOID = NULL
    ULONG = TID to test/kill
    PVOID = NULL

    Returns 0 for "valid Seamless VDM PID/TID was killed"
            1 for "valid PID/TID was not killed" (held by a PM driver)
            2 for "non-valid PID/TID" (went away or is going away)

�Function = DOS session Dirtynotification (Send)

    HVDD  = Handle of VDD (returned from DosOpenVDD)
    SGID  = -1 indicates broadcast; the PM display driver
            always broadcasts
    ULONG = 0x000000C2
    ULONG = Function code to use for the interrupt ( 0x4001
            or 0x4002 )
    PVOID = NULL
    ULONG = Force Repaint ( 0 = NO, 1 = YES )
    PVOID = NULL

Sends VWIN a DOS session Dirtynotification. This is used at PM death and resurrection to indicate to the DOS sessions to suspend drawing or resume redrawing and repainting.

�Function = Set VMOUSE Display Resolution

    HVDD  = Handle of VDD (returned from DosOpenVDD)
    SGID  = NULL
    ULONG = 0x000000C4
    ULONG = sizeof(VMSSIZE structure)
    PVOID = pointer to VMSSIZE structure
    ULONG = NULL
    PVOID = NULL

    typedef struct vmss_s {
      ULONG  vmss_nb;             // Size of structure, in bytes (36)
      LONG   vmss_lMode;          // Video mode (eg, 00h-13h, or -1)
      ULONG  vmss_ulWidth;        // Width of screen, in pels
      ULONG  vmss_ulHeight;       // Height of screen, in pels
      ULONG  vmss_ulCellWidth;    // Width of screen cells, in pels
      ULONG  vmss_ulCellHeight;   // Height of screen cells, in pels
      ULONG  vmss_ulPtrWidth;     // Width of ptr drawing size, pels
      ULONG  vmss_ulPtrHeight;    // Height of ptr drawing size, pels
      ULONG  vmss_ulPtrUnitWidth; // Width of ptr drawing unit, pels
    } VMSSIZE;

Windows Driver Calls to VWIN - Accessed via INT 66h

�Windows DD - Initialization

    Input:
    AH    = 0x81 - VWIN_INITIALIZE
    DS:SI = "VWIN"
    CX    = SIZEOF windd_init
    EBX   = windd_init struc

    WINDD_INIT  struc
        proc_id      dw  0   ; (out) WinDD's process id
        thread_id    dw  0   ; (out) WinDD's thread id
        pfvwin       dd  ?   ; (out) VWIN's interrupt handler
        pmdd_io      dd  0   ; (out) pointer to pmdd_io structure
    WINDD_INIT  ends

Note:

After this initialization call, instead of issuing INT 66H, the seamless windows driver can call directly into VWIN's interrupt handler using the pfvwin function pointer, passed in the WINDD_INIT structure. If this mechanism is used, the seamless windows driver must first perform a "pushf" before calling VWIN's handler.

The pmdd_iofield is a pointer passed directly from the PM display driver. This pointer addresses a structure of values that are shared between the PM and seamless windows display drivers. The definition of this structure is set by the display driver pair. However, as noted above, the first four bytes of the structure must contain some type of signature value agreed on by the display driver pair.

    Output:
    AX    = 0... success
            n... failure code defined by VWIN

�Windows DD - Block on FSRamSemaphore

    Input:
    AH    = 0x82 - VWIN_SEM_BLOCK
    EBX   = CPDOS RAM Semaphore
    ECX   = Timeout value
    DS:SI = "VWIN"

    Output:
    AX    = 0... success
            n... failure

Note:Most of the driver semaphore handling is at Ring 3. However, this exception (interrupt) is necessary because the seamless windows driver DOS session cannot make a kernel call. When the video hardware semaphore is in use, the Driver must block, and this requires a call to the kernel through VWIN.

�Windows DD - Wakeup FSRamSemaphore request

    Input:
    AH    = 0x83 - VWIN_SEM_WAKE
    EBX   = CPDOS RAM Semaphore
    CX    = old RamSemFlag value
    DS:SI = "VWIN"

Note:When freeing and resetting the FSRamSemaphore, the seamless windows driver first checks whether RamSemFlag in the semaphore structure is 0. If the flag is nonzero, the seamless windows driver must call INT 66h, VWIN_ SEM_WAKE. The RamSemFlag value before being reset is the "old RamSemFlag value".

    Output:
    AX    = 0. . . success (call cannot fail)

�Windows DD - Request hardware

    Input:
    AH    = 0x84 - VWIN_REQUEST_VVIDEO
    DS:SI = "VWIN"

    Output:
    AX    = 0. . . success (call cannot fail; call will block
                  until hardware is available)

Note:In seamless processing, three components share the video hardware. These are:

VVIDEO

PM

Windows

PM and Windows coordinate access to the hardware via a FSRamSemaphore. However, virtual video drivers do not have this mechanism available. A virtual driver is never sure when a DOS application is finished accessing the screen; therefore, this interrupt exists to signal to VWIN (which forwards the request to the virtual video driver) that the seamless windows driver needs hardware access. Before making the call, the driver must obtain the hardware semaphore. Upon return, the seamless windows driver is guaranteed exclusive use of the video. (This mechanism of obtaining the semaphore and checking with VVIDEO already exists in the PM Driver code and is not unique to seamless operation.)

�Windows DD - Notify that hardware is available.

    Input:
    AH    = 0x85 - VWIN_NOTIFY_VVIDEO
    DS:SI = "VWIN"

    Output:
    AX    = 0. . . success (call cannot fail)

�Windows DD - Critical section processing

    Input:
    AH    = 0x86 - VWIN_WINDD_ENTERCRITSEC
    DS:SI = "VWIN"

    Output:
    AX    = 0. . . success (call cannot fail)

    Input:
    AH    = 0x87 - VWIN_WINDD_EXITCRITSEC
    DS:SI = "VWIN"

    Output:
    AX    = 0. . . success (call cannot fail)

Note:The enter/exit critical section calls can be nested and, therefore, must come in pairs. This interrupt usually is issued as part of INT 2Fh processing, when nonreentrant code is being executed. It requests VWIN to temporarily stop sending interrupts to the DOS session.

Device Escapes() from Win Shield and GDI to Seamless Windows Driver

�rc = Escape( hDC, SEAMLESS_ESC_INIT, nCount, lpInData, lpOutData )

    hDC       = GetDC( hWnd )
    nEscape   = 6000 - SEAMLESS_ESC_INIT
    nCount    = 0
    lpInData  = Pointer to Win Shield "call-back" entry point
    lpOutData = NULL

    On Exit: rc = negative......Error
             rc = positive......Success

The SEAMLESS_ESC_INIT call is made by Win Shield at initialization time. On input, Win Shield provides the address of a call-back entry point. The seamless windows driver uses this entry point, in addition to passing a clip region, to cause an area of the Windows Desktop to be repainted. This function is used whenever the seamless windows driver is disabled but must write to the screen. Win Shield is responsible for accumulating the clip regions passed to it.

Note:

1.This call is made before the screen is enabled by the Win Shield via INT 2Fh.

2.The seamless driver must always invalidate the Windows Desktop when OEMUpdateColorsis called and the driver is in the disabled state. Miscellaneous translation table and color-mapping problems can otherwise occur.

�rc = Escape( hDC, SEAMLESS_ESC_ENABLE, nCount, lpInData, lpOutData )

    hDC       = GetDC( hWnd )
    nEscape   = 6002 - SEAMLESS_ESC_ENABLE
    nCount    = 0
    lpInData  = NULL
    lpOutData = Pointer to hw_access

    On Exit: rc = negative......Error
             rc = positive......Success

SEAMLESS_ESC_ENABLE permits a Windows program to determine the current hardware state. The escape returns the address of the driver's internal variable, hw_access, which reflects the hardware state at any time.

�rc = Escape( hDC, SEAMLESS_ESC_EXIT, nCount, lpInData, lpOutData )

    hDC       = GetDC( hWnd )
    nEscape   = 6001 - SEAMLESS_ESC_EXIT
    nCount    = 0
    lpInData  = NULL
    lpOutData = NULL

    On Exit: rc = negative......Error
             rc = positive......Success

Win Shield issues this call, requesting the seamless windows driver to reset its Win Shield call-back entry point. This is performed when the seamless windows DOS session is closing.

�rc = Escape( hDC, SEAMLESS_ESC_REQSEM, nCount, lpInData, lpOutData )

    hDC       = GetDC( hWnd )
    nEscape   = 6004 - SEAMLESS_ESC_REQSEM
    nCount    = 0
    lpInData  = NULL
    lpOutData = NULL

    On Exit: rc = negative......Error
             rc = positive......Success

SEAMLESS_ESC_REQSEM requests the seamless windows driver to obtain the FSRamSemaphore on behalf of Win Shield.

�rc = Escape( hDC, SEAMLESS_ESC_CLRSEM, nCount, lpInData, lpOutData )

    hDC       = GetDC( hWnd )
    nEscape   = 6005 - SEAMLESS_ESC_CLRSEM
    nCount    = 0
    lpInData  = NULL
    lpOutData = NULL

    On Exit: rc = negative......Error
             rc = positive......Success

SEAMLESS_ESC_CLRSEM requests the seamless windows driver to clear the FSRamSemaphore on behalf of Win Shield.

�rc = Escape( hDC, SEAMLESS_ESC_PALINIT, nCount, lpInData, lpOutData )

    hDC       = GetDC( hWnd )
    nEscape   = 6010 - SEAMLESS_ESC_PALINIT
    nCount    = 0
    lpInData  = NULL
    lpOutData = Pointer to the start of the palette-related data in the
                PM and Windows shared data/code area

    On Exit: rc = negative......Error
             rc = positive......Success

SEAMLESS_ESCAPE_PALINIT permits the Windows GDI component to obtain the address of the palette-related data in the PM and Windows shared data/code area. There are three palette-related entries in this shared area, arranged in the following sequence:

   bfPaletteIsFixed   db  ?   ; TRUE if Palette Manager not enabled
   ulLastPalUpdate    dd  ?   ; Timestamp of last foreground realize
   pHWPalette         dd  ?   ; 16:16 ptr to HWPalette structure

Windows INT 2Fh Support

�Windows DD - Notify Background Switch

    AX    = 4001H
    CX    = Seamless identifier "SM"
    DX    = Seamless sub-function

          0100H....disable hardware Write access
          0101H....disable hardware Read/Write access

�Windows DD - Notify Foreground Switch

    AX    = 4002H
    CX    = Seamless identifier "SM"
    DX    = Seamless sub-function

          0200H....enable hardware Write access
          0201H....enable hardware Read/Write access
          0202H....enable hardware Read/Write access and
                   force repaint

Miscellaneous Windows Driver Information

�In addition to the enabled and disabled states, the Windows driver also can be in a Read-onlystate, for example, when the Windows driver is disabled, yet can legitimately transfer bit-map data from video memory to system memory.

These various states are normally used to optimize execution speed, based on the needs of the calling application.

When processing INT 2Fh/disable from the PM Display Driver, it is important for the Windows driver to remain disabled until notified (again, via INT 2Fh) by the PM driver. The PM driver is notifying of its death and resurrection. Alternately, if enabled by the PM driver but otherwise INT 2Fh disabled, then the Windows driver can optimize processing and enter the read-only state.

�The seamless windows driver must always check the hardware state before requesting the video FSRamSemaphore. If the hardware is disabled or in the "read-only" state, and the output destination is the screen, the driver should call Win Shield, requesting Win Shield to accumulate the screen areas (rectangles) requiring update.

There are two options when calling Win Shield for a repaint:

SEAMLESS_FORCEPAINT  To cause the entire Windows desktop to be repainted.
SEAMLESS_POSTPAINT   To repaint the accumulated area collected by Win Shield.

�Normally, when a Windows session is switched to the background, its output is disabled. Then, when switched to the foreground, a repaint is forced, even if no modifications were made to the current screen. This is acceptable when running a full-screen Windows session. However, when running seamlessly, the PM Driver automatically saves the contents of the screen when it is switched to the background.

When Presentation Manager returns to foreground, the whole screen is restored (including the seamless windows). As a result, no refreshes from the seamless windows will be necessary unless the Windows program attempted a repaint while output was disabled. As a performance improvement, a repaint flag is implemented in Win Shield, which is set initially to FALSE. When the seamless windows driver is in the background, this flag is set by Win Shield to TRUE if any refresh of the screen is attempted by the driver (for example, if the driver calls-back to the Win Shield, passing a clip region). When the seamless driver is switched to the foreground, a repaint is forced only if the flag is TRUE.

�Errors have been observed in seamless windows due to the Windows driver's failure to account for being in the Disabled state. For example, damage to the Min/Max buttons for a seamless window was observed. This occurred because the Min/Max button conversion was performed in the DIBtoScreenfunction. In some scenarios, when this function was invoked, the seamless windows driver was disabled. In this case, the Windows driver could not process the DIBtoScreenand ignored it. However, when finally enabled, the driver was told only to do a block logical transfer (Blt) and not a DIBtoScreen. The solution was for the seamless windows driver to store a flag indicating that the button conversion had not been performed, and to process it at a later time, when enabled.

�The SaveScreenBitmapentry in the seamless windows driver should be disabled because the driver does not have full information of the Desktop when running seamlessly.

�The seamless windows driver must not issue any INT 10h calls.

�Previous seamless windows design assumed that the FS and GS registers were not modified once loaded. Under Windows 3.1 this is no longer a valid assumption. The seamless windows driver must save the FS and GS contents to global variables when FS and GS are initially loaded. Then, before these registers are used, the seamless driver should compare the contents to the global variables. If the contents have been modified, the registers must be reloaded.

�It is important to modify the virtual video device driver, as well as the PM and Windows drivers, to operate seamlessly. The virtual video driver, which normally traps all hardware I/O, must be modified to permit the seamless windows driver to access the hardware. If the virtual video changes are not complete, you will see the following error message box:

�ååå Error Message åååååååååååååååååååååååååååååååà
�                                                          �
�   System does not support this session's video mode in   �
�   a window.  The program cannot continue running in a    �
�   window.                                                �
�                                                          �
�ååååååååååååååååååååååååååååå�

Seamless Testing

The essence of seamless windows testing is to run both OS/2 Presentation Manager and Windows applications together on the OS/2 Desktop. The tests should execute as many different Windows functions and options as possible, to stress the seamless drivers and environment.

The following situations and scenarios should be considered for seamless testing:

�Execute standard Presentation Manager and Windows functionality - move, resize, minimize, maximize and overlay windows of both PM and Windows applications. When minimizing, minimize to the OS/2 Desktop, to the Minimized Window Viewer and hide the applications. Open and close several PM and Windows applications.

When closing applications, exercise various mechanisms (close from the Window List, double click in the window's upper left corner, etc.). For the Windows applications, test within the same DOS session and in different DOS sessions.

�Use the Window List, mouse pointer and hot-key sequences (for example, Alt +Esc) to change window focus. Include full-screen, and DOS and OS/2 windowed sessions in some test scenarios.

�Verify application functionality - pull-down and pop-up menus, control keys, radio buttons, and so on. Are text font and positioning correct? Are valid colors displayed?

Actual Windows and PM applications should be executed to exercise seamless modifications.

A verification of Windows driver functionality can be obtained using the driver test routines from the Microsoft Windows Device Driver Kit. These tests should execute seamlessly.

�Drag both PM and Windows icons and move the cursor over the application windows. Test both hardware and software cursors if available. Exercise various bit map formats - device dependent (DDB), device independent (DIB) and run length encoded (RLE).

�Transfer data between Presentation Manager and Windows applications using the Clipboard and DDE.

�Exercise all supported hardware resolutions and bits per pels. A different set of problems may be detected at different resolutions and numbers of colors.

Three possible test scenarios are outlined below:

�Scenario A(Initial seamless verification):

Two passes:

-Pass One uses a single instance of Windows Clock on the OS/2 Desktop

-Pass Two has multiple instances

Active Sessions:

-Windows Clock

Move, resize, attempt both analog and digital display, overlay OS/2 folder icon view, clip by icon view, minimize, maximize.

�Scenario B:

Two passes:

-Pass One with one DOS session for both Windows applications

-Pass Two uses separate DOS sessions.

Exercise the outlined functionality by performing some tasks within an application, then change focus to the next application and continue to test , ultimately returning to the first application.

Active Sessions:

-PM - Jigsaw

Minimize, maximize, move, resize, overlay Windows applications, clip by Windows applications, play the game.

-Windows - Excel

Change fonts, copy data to Clipboard, resize, display chart, minimize, maximize, move, close, cut/paste, overlay PM and Windows applications, clipped by Presentation Manager and Windows applications, change height and width of cells, change colors in cells.

-Windows - Paintbrush

Select color, draw, fill, cut/paste, rotate, edit palette, view bit map, minimize, maximize, move, resize, clipped by and overlay other windows.

�Scenario C:

This scenario includes multiple focus changes between the various windows, and exercises hardware palette updates and switching to/from a full-screen session.

The functionality discussed (minimize, maximize, resize, clipping, etc.) should be exercised while changing focus and performing the session switches.

Active Sessions:

-PM - PalDisp

Display hardware palette for verification.

-PM - PalTest

Display bit map using PM Palette Management, and verify palette update.

-PM - Solitaire

Continuous play.

-Windows - ShowDIB

Display bit map using seamless windows Palette Management, and verify palette update.

-Windows - Clock

Analog and digital display.

-DOS Window - batch file in loop, text mode

Run batch file printing text messages, coded in an endless loop.

-DOS Full-Screen - graphics application

Run graphics application program.

Checklist for Palette Management Support

To enable current Windows driver palette management support in a seamless display driver, follow the steps below:

1.Make sure that the following structure is part of the PM-SL share data, that is, the PMDD_IO_STRUC structure defined in IPC.INC.

     SL_PaletteData struc
        bfPaletteIsFixed     db  ?       ;TRUE if palette manager not enabled.
        ulLastPalUpdate      dd  ?       ;Time stamp of last foreground realize.
        pHWPalette           dd  ?       ;16-bit pointer to HWPalette structure.
     SL_PaletteData ends

2.Add SEAMLESS_ESC_PALINIT function support in Windows entry Control ( lpDevice, Function, lpInData, lpOutData), do the following:

a.Claim the support of SEAMLESS_ESC_PALINIT when this function is being queried.

b.When Function = SEAMLESS_ESC_PALINIT, return the address of init_Struct- >pmdd_io.SL_PaletteData in the buffer whose address is in lpOutData.

This address, &(init_Struct->pmdd_io.SL_PaletteData), must be in 16-bit sel :offset format.

Note:

If init_Struct->pmdd_io is a 32-bit address of the PM-SL share area, you have to thunk the &(init_Struct->pmdd_io.SL_PaletteData) 32-bit address to 16-bit sel:off format, using the following algorithm:

         sel = (high word of the 32-bit address * 8) | 7 
         off = the low word of the 32-bit address.

If this function is not implemented, or not correctly implemented, a General Protection Fault will occur.

3.Change Windows entry SetPalette() as follows:

   if( lpPalette != NULL ) {
     a) Request_Semaphore(..)
     b) Update the hardware palette in exactly the same way as you do in
        regular Windows driver.
     c) Clear_Semaphore(..)
   } else {
     Update the private copy of the hardware palette image if there is one being
     kept in the data segment.
   }

4.Change Windows entry UpdateColors() as follows:

�Call check_hw_access() for HW_FORCEREADWRITE hardware state before any screen update.

�If check_hw_access() returns Success, call request_semaphore() as you do before all hardware access and clear_semaphore() after you are done updating the screen.

5.Change check_hw_access() in IPC.ASM as follows:

Add HW_FORCEREADWRITE as one of the possible values in AL when this call is made. Here is an example of code needed to add to check_hw_access():

   check_hw_access PROC FAR

         .....

         cmp     al, HW_READWRITE        ;Request for HW_READWRITE access?
         jnz     check_forcereadwrite    ;No, go check for HW_FORCEREADWRITE
                                         ;access.
         .....

   check_forcereadwrite:
         cmp     al, HW_FORCEREADWRITE   ;Request for HW_FORCEREADWRITE access?
         jnz     check_write_access      ;No, go check for HW_WRITEONLY access.

         VWIN_ENTER_CRITSEC              ;Turn off interrupts from VWIN.

         mov     hw_virgin, HW_DOREPAINT ;Repaint when HW_READWRITE allowed.
         mov     ax, SEAMLESS_FORCEPAINT ;Paint the whole VDM.
         call    winshield_callback      ;

         VWIN_EXIT_CRITSEC               ;Turn on interrupts from VWIN.

         jmp     check_exit_bad          ;We are done. Exit.

         ....
   check_hw_access ENDP

6.Remarks

Values for symbolic names used above are as follows:

   SEAMLESS_ESC_PALINIT    equ  6010     ;Pass back address of 1st entry of the
                                         ;palette-related data in PM-SL share
                                         ;area.

   HW_FORCEREADWRITE       equ   'F'     ;Request R/W hardware state. If not
                                         ;available, ask winshield to do force
                                         ;repaint when the driver is once again
                                         ;allowed to draw the screen.

PM Palette Management Support

This chapter is a brief guide to Presentation Manager Palette Management. Palette support is an optional functionality that can be provided by a presentation device driver.

Introduction

If the driver does not, or cannot provide this functionality, it is simulated in the graphics engine. An application writer accesses palette function via Graphics Programming Interface (GPI) APIs.

The following topics are described:

�Palette Management Overview
�Color Support in OS/2 Version 1.3 - Logical Color Tables
�Palette Management Functionality
�Palette Management Conflicts
�XGA Support for Palette Management
-Terminology
-Default Palettes
-Realizing Palettes
-Seamless Modifications
-Dithering and BITBLTing
�Miscellaneous Palette Management Information

Overview

Palette Management is special code, enabling applications to specify exact RGB (color) values for a drawing or image on a particular device. The application's color requests are mapped as closely as possible to the actual colors available in the device's hardware color palette. When possible, the hardware palette is modified to provide the requested RGB values exactly.

Code supporting Palette Management is responsible for arbitrating the conflicting color requests that may occur between different applications running simultaneously. These conflicts arise when more colors are requested than can actually be physically displayed at one time, on the device.

For example, if applications request a total of 350 different RGB values, but the device supports only a 256-color hardware palette, then only a subset of the applications' color requests can be satisfied exactly. The Palette Management code must handle setting the hardware palette to satisfy the color requests, and mapping the remainder of the requests to the closest available color in the hardware palette. The application is relieved of the responsibility of managing its environment at the same time as ensuring that its color requests are satisfied to the best of the ability of the hardware.

Color Support in OS/2 Version 1.3 - Logical Color Tables

With OS/2 1.3, application colors can be specified by means of Logical Color Tables (LCTs), and their more powerful (but very dangerous) variant, the realizable Logical Color Table.

The use of Logical Color Tables to specify colors is limited. Although an application can request RGB color values, these requests are simply mapped to the default colors defined in the device's hardware palette. The color mapping is a nearest color search. The colors in the device's hardware palette are not modified. Consequently, the accuracy of colors obtained using Logical Color Tables is limited on devices which do not have a large number of default colors.

For example, an eight-bit-per-pel device has a maximum of 256 colors available. Such a device may have 20 to 30 red or orange shades defined in its default hardware palette. For most applications, this is an acceptable number. However, to display a sunset in varying shades of red and orange might require 150 different shades in the palette. This would not be possible with Logical Color Tables.

To address this problem in OS/2 1.3, the application used a realizable Logical Color Table. In this case, the application makes a GpiRealizeLCTcall, which forces the colors from the realizable Logical Color Table into the device's hardware palette, overwriting the default colors. This has the effect that the image created using the realizable Logical Color Table obtains the exact colors requested. However, the remainder of the desktop is repainted using a color mapping from the original default palette to the new colors in the device palette.

Unfortunately, some desktop objects (such as buttons, icons and bit maps created by other applications) do not repaint correctly. This is because these objects are "BLTed" to the screen, with no color conversion. Given this, it is strongly recommended that an application only make the GPIRealizeLCTcall when maximized, and then always restore the default palette before exiting.

Further limitations of realizable Logical Color Tables are that only one can be realized correctly at a time, and there is no method of arbitration. If a second application realizes a different Logical Color Table than a first application, the first application will draw with the wrong colors.

Lastly, it should be noted that the concept of Logical Color Tables has no corollary in Windows 3.0 or 3.1. Windows uses a Palette Management scheme as discussed in the preceding Overview.

Palette Management Functionality

This section describes the following:

Creating and Selecting Palettes

Realizing Palettes

Animating Palettes

BITBLT Conversions

Other Palette Operations

Creating and Selecting Palettes

A palette is created by passing an array of RGBs to the GpiCreatePalettefunction in a similar manner to creating a Logical Color Table. This call returns a handle to the palette created. This handle must be used to address the palette in all other related calls.

Unlike LCTs, palettes are global objects and are not confined to a particular presentation space. An application can create multiple palettes and use a different one for each of its tasks. Palette handles can even be passed between different applications to enable them to share the color palettes.

To start drawing with a particular palette in a Presentation Space (PS), the palette must be selected into the PS using the GpiSelectPalettefunction. This function associates the PS with the palette, and all subsequent color information is taken from the RGB values in the palette. The colors are addressed by an application in the same way as the colors within an LCT-by specifying indexes into the array of RGBs originally used to create the palette.

Realizing Palettes

If the Presentation Space being used is associated with a Direct Device Context (DC) such as the screen, then the application must call WinRealizePalette, passing the palette handle obtained in the GpiCreatePalettecall, before drawing using the palette. It is the WinRealizePalettefunction call that filters to the presentation driver to update the colors in the device's hardware palette. At this time, any palette/color conflicts that occur should be resolved.

Whenever the colors in the device's hardware palette are changed, a WM_ REALIZEPALETTE message is sent to every application. When an application that is using Palette Management APIs receives the WM_REALIZEPALETTE message, it should in turn call WinRealizePalette. The application uses WinRealizePaletteto re-realize every currently active (ie, realized) palette. In this way, WinRealizePaletteacquires information about the color requirements of the whole system and can resolve any conflicts.

WinRealizePaletteprocessing may cause a remapping of the colors that an application is using for an existing palette. This occurs as a result of another application realizing a new palette or as a result of a conflict. In this case, an indication will be returned to the application in one of the WinRealizePalettefunction parameters (pcclr). If pcclr is greater than 0, the application should invalidate its window and redraw its image to use the correct colors/color mapping.

For Presentation Spaces associated with Memory DCs such as bit maps, there is never a need to call WinRealizePalette. Memory DCs are not shared. Therefore, there can never be any palette conflicts. The application always gets the exact colors it requests (up to the limits of the bit map format).

Animating Palettes

If an application wishes to change the colors within its palette often and quickly, then it can use calls to GpiAnimatePalette. This function causes the colors within the application's array of RGBs and the device's hardware palette to change almost simultaneously. The call is filtered to the presentation driver in order to update the device's hardware palette. Changing both the application's colors and the device's palette simultaneously ensures that no repainting is required by the application. The image on the screen is updated by virtue of updating the underlying hardware palette.

To ensure that this process does not produce conflicts, a special flag is used when creating the palette. A palette entry can be marked PC_RESERVED, which indicates that the entry may be animated in the future. This prevents the PC_RESERVED palette entry from being shared with other applications. Therefore, the presentation driver can safely change the hardware entry without side effects in other applications.

BITBLT Conversions

As mentioned earlier, one of the problems with realizable LCTs is that there is no color conversion carried out during a BLT. Under Palette Manager, color conversions are automatically performed when "BLTing" between different color palette definitions in the source and destination. In this way, color consistency is maintained when transferring images between any LCT or palette combination by using a nearest color mapping.

Other Palette Operations

Other operations associated with Palette Manager include resizing palettes, changing the colors within palettes, deselecting palettes, and deleting palettes. Each of these operations is fairly straightforward.

Palette Management Conflicts

There are basically three types of conflict that can occur within a Palette Management system:

�The first type of conflict, and the easiest to resolve, occurs when different palettes are realized by various applications. In this case, the WinRealizePalettefunction (ultimately, the presentation driver) must choose which colors the device will display. If the device is capable of displaying all the colors requested, then there is no conflict. Otherwise, it must be decided which of the requested colors will be displayed exactly and which will be mapped to the nearest color. This conflict is easily resolved by giving priority to the palette associated with the application in focus. This ensures that the application with which the user is currently interacting, will get the exact colors it requests (up to the device palette color limit).

�The second type of conflict involves the relative priority of palette- aware versus Logical Color Table-based applications, when obtaining and using palette entries for drawing. An attempt is always made to grant the exact RGB color requests of a palette-aware application. On the other hand, the color requests of an LCT application are satisfied from the portion of the hardware palette designated as the "default palette". WinRealizePaletteprocessing degrades the number of colors in the default palette to grant the color requests of a palette-aware application. Potentially, the number of default palette entries can be degraded to the set of 20 OS/2 and Windows system colors. This situation is not corrected until the palette- aware application(s) stop processing WM_REALIZEPALETTE messages, as will be discussed in XGA Support for Palette Management - Realizing Palettes, below . Note that even on a focus change to the LCT application, the default palette remains degraded if a palette-aware application is processing WM_ REALIZEPALETTE messages.

�The third type of conflict derives from the second conflict. The manner in which Logical Color Tables are (and must be) handled affects how Palette Manager's default palette is defined. To understand this conflict, it is important to note that an LCT-based application is not limited to using only the colors in its logical color table. For example, an image composed of many colors may be BLTed to a PS associated with an LCT, perhaps specifying only 16 colors. The image is to be drawn using the nearest colors that are available on the device (defined by the device context associated with the PS). The image is not defined using the colors specified in the Logical Color Table. This is very different from BLTing to a PS associated with a palette. In this case, the colors in the image are mapped to the nearest colors available in the palette. In other words, if an application is using LCTs, there is no way of knowing exactly what colors will be used.

Palette Manager must ensure that there is always as wide a range of colors as possible in the default palette. This will in turn ensure that LCTs can be mapped to the nearest color with minimum color degradation. To further complicate the conflict, the entries in the device's hardware palette used to support LCTs (the entries in the default palette) must have physical indexes such that mixing default palette colors produces another default palette color (ie, mixing LCT-mapped colors produces another LCT-mapped color).

XGA Support for Palette Management - Terminology

The following sections address the XGA implementation of Palette Management .

Palette Manager for XGA is only implemented for systems supporting eight bits per pel (256 colors). At four bits per pel (16 colors), there are insufficient colors to make a Palette Management implementation worthwhile. At 16 bits per pel (64K colors), there are sufficient colors available to an application without requiring Palette Management.

To clarify the following discussion, it is necessary to define exactly what is meant by the following terms: Hardware Palette, Physical Index, Logical Palette, Logical Index, and Default Palette.

Hardware Palette:the array of RGBs that the physical device is displaying . It is the exact RGB values that the hardware's digital-to-analog converter uses when displaying each pel on the screen.

Physical Index:a value stored in memory (either video memory (VRAM) or system memory) which represents a single pel. A physical index stored in VRAM is an index into the Hardware Palette. The color information for each pel on the display screen is referenced by a physical index. By using this index into the hardware palette, a driver obtains the exact RGB value for the pel. A physical index stored in a system memory bit map is an index into whatever color information is associated with the bit map. This color information is defined by a Logical or a Default Palette.

Logical Palette:an array of RGB and mapping index pairs created by the device driver when defining a palette (as a result of a GpiCreatePalettecall). For each RGB in the Logical Palette, when the RGB is drawn to a direct DC, the corresponding mapping index is the Physical Index for the color (or nearest color) in the Hardware Palette. These indexes are generated when the Logical Palette is realized and are known collectively as the palette mapping. Note that a logical palette is not the same as a Logical Color Table.

Logical Index:an index into a Logical Palette. It is logical indexes that an application uses to address the colors within a Logical Palette that it has created.

Default Palette:an array of RGBs that specify the colors available for use by LCTs and LCT-based applications.

XGA Support for Palette Management - Default Palettes

The XGA solution for Palette Manager uses five default palettes. Each palette supports a different number of colors and can be distinguished by its size. The default palettes supported are the 256, 128, 64, 32 and 16 entry palettes.

Each default palette is designed to give the best possible range of colors for its size. For example, the 256 entry palette contains the colors used by the 8514/A display adapter in OS/2, Version 1.3. (This has proven to be a good palette for displaying color images and has become the standard for Presentation Manager 256 color bit maps and images defined using 256 color Logical Color Tables.) At the opposite end of the scale, the 16-entry default palette contains the standard VGA colors.

Which default palette is used in a presentation space depends on whether the device context associated with the PS is a Memory DC (a bit map) or a Direct DC (the screen).

Memory DCs

Color handling within a Memory DC is easy. There are never any color request conflicts because DCs are not shared, and bit maps can only be selected into one DC at a time. Therefore, only one application can be drawing into a particular bit map within the memory DC at a time. The color information associated with the bit map is inherited from whatever LCT or Palette is currently associated with the presentation space.

If the PS is using a Logical Color Table, the physical indexes in the bit map are indexes into the 256 entry default palette. This gives as broad a range of colors as possible for the application to use. (Remember that the colors used by an LCT application are not limited to the colors in the logical color table.)

If the PS is using a logical palette, then the physical indexes in the bit map are indexes into this logical palette. This means that the physical indexes are the same as the logical indexes used to draw into the bit map.

One important point to note is that because the color information within the bit map is obtained from the PS, changing the presentation space to be associated with a different logical palette (or switching between an LCT and a logical palette) actually changes the meaning of the indexes in the bit map.

Direct DCs

In a direct DC, the physical indexes stored for an image are indexes into the hardware palette. The hardware palette can be viewed as a combination of a default palette and a number of logical palettes.

At the "start of day" (that is, at power-on, when no Palette Manager applications are running and therefore no logical palettes are in existence ), the hardware palette contains the 256 entry default palette. This makes the best possible range of colors available to LCT applications.

Later, when applications are using logical palettes, any one of the smaller default palettes may be in use, leaving room in the hardware palette for color requests to support multiple logical palettes. For example, the hardware palette may contain the 128-entry default palette and (up to) 128 colors requested from several logical palettes. If the combination of logical palette color requests exceeds 128, the default palette must be reduced further in size to support these requests.

Using this scheme, a maximum of 240 colors in the hardware palette can be allocated to support logical palettes' color requests. The remaining 16 entries in the hardware palette are used for the 16 entry default palette, ensuring that LCT applications will always have available a sensible, minimum number of colors.

Note:The 16-color default palette can also be overwritten if an application creates its logical palette using the flag, LCOL_OVERRIDE_ DEFAULT_COLORS. When this flag is specified, the presentation driver should grant the full hardware palette to an application when it is in the foreground and when its color requests exceed 240.

The driver keeps track of which entries in the hardware palette are allocated to colors from logical palettes, using a set of flags associated with each hardware palette entry. These flags are stored in the fcOptions byte of the RGB2 structure of the hardware palette. (The XGA driver defines new flags in the high order nibble of the fcOptions byte. Doing this does not conflict with the system-defined fcOptions flags in the low order nibble.) Entries in the hardware palette that are allocated to logical palette requests are marked as PC_USED, while entries that are allocated to the default palette are marked PC_DEFAULT.

Each logical palette also keeps track of which entries it has been allocated using the its array of mapping indexes (known as the palette mapping, as discussed above).

The default palette is always divided in half when placed in the hardware palette. The two halves are placed at opposite ends of the palette leaving the central region for logical palette colors. This guarantees that logical mixes of the default colors, mapped to by LCTs, will always result in another LCT-mapped color. In other words, all the colors obtainable when using LCTs are in a closed set. This in an important aspect of the XGA Palette Manager implementation. For example, if this were not the case, a mix may result in an entry in the hardware palette that is allocated to an animating logical palette. This would be very dangerous!

The process of changing the default palette in use with a Direct DC, and allocating entries to logical palettes is described in more detail below under XGA Support for Palette Management - Realizing Palettes.

XGA Support for Palette Management - Realizing Palettes

Applications realize their palettes using the WinRealizePalettefunction. This function is passed to the graphics engine and onto the presentation driver through the RealizePalettedriver entry point. The driver returns values to WinRealizePaletteto indicate what actions are required to keep the system consistent. This makes the RealizePalettefunction the heart of the Palette Manager system.

Three values are returned from the driver's RealizePalettefunction to WinRealizePalette:

�Number of hardware palette entries changed. (A pointer to a ULONG, pcSlotsChanged, is passed as one of the function parameters).

�Number of logical palette mapping indexes changed. (This is the function's return value).

�Flag indicating that the default colors have changed. (A pointer to a set of flags defined as a ULONG, pflType, is passed as one of the function parameters. The flag, RP_DEFAULTSCHANGED, must be set to indicate a change in the default colors.)

The actions taken by WinRealizePaletteprocessing depend on the return values as follows:

�If the hardware palette is changed, WinRealizePalettewill invalidate any saved screen bits. (See the OS/2 Presentation Device Driver Referencefor details on saved screen bits).

�If the hardware palette is changed and the new logical palette is being realized in the foreground, WinRealizePalettewill send a WM_REALIZEPALETTE message to every application.

�If the logical palette mapping indexes are changed, the number of changed indices are passed back to the application to indicate that a repaint is required.

�If the default colors are changed, WinRealizePalettewill invalidate the entire desktop (forcing everything to be repainted).

When a logical palette is realized in the foreground (ie, the application making the WinRealizePalettecall has the focus), then that palette receives priority over any other palettes that were previously realized. To satisfy the color requests of the foreground WinRealizePalette, the driver should overwrite entries in the hardware palette that are allocated to other applications, if necessary.

If the hardware palette is changed, then all the palette mappings for the other logical palettes in the system are invalidated. The return value ( hardware palette entries changed in pcSlotsChanged) will trigger the WinRealizePalettefunction to send WM_REALIZEPALETTE messages to every other application. Each application will then re-realize its palette (in the background) and repaint if any of its palette color mappings differ from its previously realized mappings. As mentioned above, this is indicated by WinRealizePalette's return value.

When a palette is realized in the background (ie, the application making the WinRealizePalettecall does not have the focus), then the driver should not change any entries in the hardware palette that are already mapped by other logical palettes. The presentation driver must either modify hardware palette entries that are currently unused, modify the default palette size to make additional slots available, or locate nearest color matches.

When there are no unused entries in the hardware palette for either foreground or background WinRealizePalette requests, the size of the default palette currently in use is reduced. This makes additional hardware palette entries available to logical palettes. Obviously, the minimum default palette size is 16 entries.

A valid question to ask at this point is: "What do non-palette-aware applications do when they receive a WM_REALIZEPALETTE message?" Whenever a non-palette aware application receives this message, it is not expecting it and does not know how to process it. Traditionally, these types of messages are forwarded to the default window procedure for handling. In the default window procedure, the message processing for WM_REALIZEPALETTE makes a call to realize the default palette. This is not a signal, however, to the driver to actually realize the default 256-color palette. It is a signal that the driver uses to determine when to load the appropriately sized default palette and also to determine when to increase the default palette size. This is discussed in more detail below, but we first must understand how the default palette is established, loaded and decreased in size.

The XGA display driver has a number of default palettes, of varying sizes ( as discussed above), and the realization code is responsible for determining which is the appropriate default palette to use.

Actually realizing the default palette (or rather realizing the appropriate one of the default palettes) is extremely simple. The default palette is realized whenever the foreground application requests a "realize default palette" in response to the WM_REALIZEPALETTE message, and either of the following conditions is met:

�The default palette was not the last palette realized.

�The size of the default palette has changed.

To realize the default palette, the data is merely copied from the first half of the appropriate default palette structure to the start of the hardware palette, and from the last half of the default palette to the end of the hardware palette. (To ensure that mixing operations form a closed set, the default palette must occupy the extreme ends of the hardware palette). The data in the default palettes is preset, so that both the RGB data and the options field can be placed directly into the hardware palette structure.

A driver enabled for seamless operation also has to consider whether it needs to force additional Windows colors into the default palette, as detailed in XGA Support for Palette Management - Seamless Modifications, below.

It is easy to determine when to move from a larger to a smaller default palette. Simply, if a logical palette is being realized which requires more slots than are currently free in the hardware palette, and the default palette is not at its minimum size, then the presentation driver should move to the next smaller default palette. This process may need to be repeated if the smaller default palette still does not provide sufficient free slots to satisfy the logical palette's requirements.

Movement through the default palettes in the opposite direction (from smaller to larger) is not nearly as straight forward.

It is not enough to simply reinstate the 256-entry default palette as soon as the driver thinks that no logical palettes are in use, since the device driver has a very poor picture of when logical palettes are in effect. (For example, assume that an image is drawn on the screen using a logical palette, but that logical palette is no longer selected into any of the display drivers' presentation spaces, perhaps because a cached-micro PS was used. Then, even though the driver is still showing the image drawn with the logical palette, the driver is unaware that the palette is still active .) Therefore, the movement through progressively larger default palettes must be based on different criteria. It is designed to be closely tied to the driver's receipt of "realize default palette" requests.

Whenever XGA is asked to realize the default palette from a foreground application, it counts the number of unused slots in the hardware palette. If there were enough free slots the last time that the default palette was realized (to allow the next larger default palette to be used), and there are still enough free slots, then the size of the default palette is increased. (It may not always be the case, however, that the number of free slots remains unchanged. Some slots could have been taken by WinRealizePaletterequests from non-foreground palette aware applications. This is why there is a delay in increasing the default palette size.) Dependent on the number of free slots, the default palette size can be increased several times-until there are insufficient free slots to move to the next larger default palette, or until the maximum default palette (256 colors) is reached.

In order to prevent prematurely increasing the default palette size, whenever a logical palette is realized in the foreground, the value for "free slots the last time that the default palette was realized" is reset. This ensures that the next "realize default palette" request does not increase the size of the default palette.

If a call to realize the default palette in the foreground causes no increase in the default palette size, the XGA driver reports that there are no mapping changes, but that the hardware palette is changed. This causes the system to send WM_REALIZEPALETTE messages to all applications, and allows the driver to be notified of all logical palettes still in use. However, no repainting is needed since no color mapping changes are reported.

If realizing the default palette causes the default palette size to change, a flag is passed back to WinRealizePaletteto force a repaint of the entire desktop.

XGA Support for Palette Management - Seamless Modifications

Supporting seamless windows operation requires some redesign of the Palette Manager code. Briefly, the seamless windows modifications involve making the default Windows system colors available at all times. This is discussed in greater detail in Seamless Windows Support. In overview, seamless support requires the following changes to the Palette Manager design:

�The default palettes are modified so that the 20 Windows colors are moved to the first and last ten entries in the palettes. This modification does not update the default color entries to exactly match the 20 Windows colors , but moves the closest match to these colors to the top and bottom ten hardware palette entries. Also, the driver's search algorithms for the closest color match are not changed. After a color match has been calculated, a translation table is checked to determine if the location of the color has been modified due to seamless operation.

�The 32-color default palette is never used, since it does not contain the required 20 Windows colors. Therefore, the sequence of sizes for the default palettes in a seamless implementation are 256, 128, 64, and then 16 .

�Whenever the 16-color default palette (the VGA palette) is in effect, the four additional Windows colors are placed in the hardware palette in locations 8, 9, 246 and 247. The dithering algorithm (discussed below) is unchanged, and still behaves as if there are only 16 colors.

�Whenever a call to the presentation driver causes a change to be made to the hardware palette, a counter accessible to the seamless windows driver and Windows kernel is incremented. This allows the seamless windows driver and kernel to determine when their internal palette mappings are invalid. Both this counter and the hardware palette structure are part of the PM/WIN -OS/2 shared data area. Using the hardware palette structure, Windows code can determine the exact contents of the palette.

�The maximum number of colors available for a logical palette's color requests (without the application specifying the flag, LCOL_OVERRIDE_ DEFAULT_COLORS) is now 236.

XGA Support for Palette Management - Dithering and BITBLTing

The implementation of the dithering code in the XGA driver is simplified by the decision that only Logical Color Table-related requests are dithered. This is justified for two reasons:

�Applications that use logical palettes usually get the exact colors that they request. Therefore, dithering with logical palettes is not required.

�Dithering with an arbitrary set of colors (as is usually found in a logical palette) is a complex and time-consuming task. The loss in performance due to dithering would not balance the color quality gain.

Dither patterns used to satisfy LCT requests are made up of colors from the current default palette. There is a separate dither scheme for each default palette, specifically tuned to give the best dithering results and performance.

BLT (Block Logical Transfer) color conversions are done on the fly by the XGA's software drawing code. (The software drawing code is essentially a simulation of the XGA drawing hardware, and is used extensively within the XGA driver to avoid the performance costs due to the XGA hardware requiring access to arbitrary system memory). In the case of BLT color conversions, the software drawing code is used because the XGA hardware does not support these conversions. A performance gain is achieved using the simulation code over copying the data into a temporary buffer, converting it, and then BLTing it to its destination.

In all cases, the most accurate BLT conversion is always calculated. However, there are several instances when a conversion is not needed. This is true when converting:

�From a logical palette memory DC to a logical palette memory DC with the same logical palette.

�From an LCT memory DC to an LCT memory DC.

�From an LCT memory DC to an LCT direct DC when the hardware palette contains the 256-entry default palette.

�From or to a realizable LCT DC.

�From a bit map which is not associated with a DC.

The destination of the block transfer affects the color conversion scheme as follows:

�If the destination is an LCT direct DC, the converted colors are limited to those in the default palette currently selected into the hardware palette.

�If the destination is a logical palette direct DC, then the converted colors are limited to the colors mapped by the logical palette.

For example, an application might be BLTing from a color image in a memory DC to a logical palette direct DC. If the logical palette contains only shades of grey, then it is important that the image is converted to only those greys, even though other colors in the hardware palette may match the colors in the original image exactly.

As a simple optimization, the last conversion table used is cached and is reused if the next requested color conversion is identical. This saves having to recalculate the conversion table for each BLT. Even though only one conversion table is cached, this scheme is quite effective. For example , when the desktop is repainted, all the icons are BLTed to the screen in turn. Each will use the same conversion table resulting in a marked performance improvement. Obviously, the conversion table is invalidated if either the source or destination colors are changed.

Several operations are not supported in the XGA driver as such, but are simulated using the BITBLT primitive. These operations are SaveScreenBitsand RestoreScreenBits. Since the purpose of these operations is to save an area of the screen and restore it later, it is important that no color translation is performed during either the save BITBLT, or during the restore BITBLT. To accomplish this, a new option flag, BBO_NO_COLOR_INFO, is provided which informs the driver that color translation is not required on the BITBLT.

Miscellaneous Palette Management Information

�When an application defines a logical palette, it is assumed to be defined in priority order. In other words, entry 0 is the most important color, and subsequent entries are of decreasing importance. This means that the display driver should allocate hardware slots in order of the entries in the logical palette, rather than trying to match the most logical entries to physical ones. An extreme example of this is a palette with only two distinct RGB values in it, one in the first entry, and one in each of the other 255 entries, with no entry marked as PC_RESERVED or PC_NOCOLLAPSE.

If there is only one slot in the hardware palette, then this slot will be assigned the color of the logical palette's first entry only matching just one of the 256 entries, whereas the remaining 255 entries could have mapped to that same one slot, providing hardware backing for a much higher proportion of the logical palette. Although obviously contrived, similar situations can occur when the color table of an external bit map is used as a palette, where the color table is not subject to any prioritization of its entries.

�Although an application realizes a logical palette with entries in a specific order, the presentation driver does not guarantee that these logical palette entries are loaded into the hardware palette in this same order. In fact, as an optimization, the driver searches the current hardware palette for a match to a logical palette's color request and maintains the position/entry in the hardware palette, if a match is found. An application should not assume any particular hardware mapping order based on its logical palette definition.

�A degradation of the OS/2 desktop and LCT applications may occur when color tables from external bit maps are used as logical palettes. This occurs when an eight-bit-per-pel bit map actually uses far less than 256 colors, but the full 256 colors are used to define its palette. In this case, the Palette Management code will degrade the default palette to 16 entries, when (for example) only 64 distinct colors are used within the bit map. Ideally, a logical palette with only 64 entries should be defined, and the default palette degraded to only 128 (assuming that the default palette previously contained 256 entries).

�Although not specifically prohibited, it is strongly advised that palette operations are not performed via cached-micro presentation spaces. The problem from the display driver's viewpoint is that a cached-micro Presentation Space provides no continuity for the driver's view of the logical palette. The display driver is only asked to create its device palette when a logical palette is selected into a presentation space, and is then told to destroy its device palette when the logical palette is deselected from the Presentation Space (which for a cached-micro Presentation Space is normally very soon after it is selected). Consequently, if Palette Management functions are issued within cached- micro Presentation Spaces, the driver is continually creating and deleting palettes-even though the application has only created the palette once. In addition, this lack of continuity implies that palette animation within a cached-micro PS is impossible.

Distributed Console Access Facility (DCAF)

This chapter explains, in addition to the fundamentals of the Distributed Console Access Facility (DCAF), DCAF environment and its various components . It is important to understand this information if you are installing DCAF .

The IBM Distributed Console Access Facility (DCAF) product provides a remote console function that allows one programmable workstation, called a controllingworkstation, to control the keyboard and mouse input and monitor the display output of another programmable workstation, called a targetworkstation.

Operating States

The DCAF product has two main operating states: monitoring and active.

Monitoring State

When the DCAF session is in the monitoring state, the controlling- workstation user (hereafter referred to as the controller) sees a screen image of the target workstation's display. The target workstation user ( hereafter referred to as the target user) has complete control of the target workstation operations.

Active State

When the DCAF session is in the active state, the controller operates and controls the target workstation. The keystrokes typed by the controller are relayed to the target workstation and acted upon as if they were typed by the target user. The keystroke input and the resulting screen image are seen on both the controlling and target workstations.

During the active state, keystroke input from the target workstation is not accepted. However, if the hot key combination is enabled for the target workstation, the target user can invoke this key combination to regain control of the target workstation. The target user also can choose to change the session state (for example, from active to monitoring).

The controller can establish concurrent sessions with multiple target workstations and can access each session by switching to a different window . Multiple controlling workstations can be defined within the network, however, only one of them at a time can establish a session with any single target workstation.

The controlling and target workstations are connected by a communication link. [Artwork not shown]

The Sample DCAF Direct Connectionfigure above shows a direct connection between the controlling workstation and the OS/2 target workstation. Direct modem connections can be established between OS/2 workstations or between OS/2 controlling workstations and Windows Version 3.1 target workstations. [Artwork not shown]

The Sample DCAF Connectionfigure above shows a connection via a DCAF Gateway workstation that acts as an interface between the controlling workstation and the target workstations on a Local Area Network (LAN). Connections through the DCAF Gateway can be established from a DCAF controlling workstation to any kind of DCAF target (OS/2, DOS or Windows).

Benefits of using DCAF

Within a customer's network, DCAF's ability to monitor or control a remote workstation from a central site makes it a powerful tool for network management, network administration, network security, problem determination and diagnosis, and application assistance in the form of Help Desk functions.

This remote capability can save time and money, as well as increase the productivity of the administration and support personnel. Technical expertise can be centralized at the controlling site, reducing the need for highly skilled personnel at remote locations. Reduced operational requirements will decrease costs and allow for faster growth of distributed applications within the distributed intelligent workstation environment.

System management of a secure-session environment is streamlined and made easier with the location of the DCAF Security Administrator component at the controlling site. The DCAF secure-session security helps protect the customer's software assets because DCAF's logged connections create a security audit trail.

Typical Uses of DCAF

�View and control another PC

�Control unattended PCs remotely

�Support customers and provide help remotely

�Diagnose and solve problems on another PC by modem or over a LAN

�Transfer text and data between PCs

�Run DOS, Windows and OS/2 on an unattended PC by modem or over a LAN

�Remote Help Desk assistance for applications, online education, and maintenance of application programs.

�Remote problem determination for trace and dump analysis, including file transfer of data.

�Remote control of unattended workstations (for example, LAN servers).

�Remote management of Personal System/2 (PS/2) workstations and accessibility to data and programs stored on a PS/2 (for example, in the home or in the office)

�Remote access to system consoles when they are implemented on PS/2s.

Here is a typical scenario of the DCAF Help Desk function:

�A target user is having difficulty understanding the company's new accounting program.

�The target user contacts the Help Desk person who, in turn, opens a session with that particular target workstation.

�With the target workstation accounting program on the screen, the controller (Help Desk person) switches to active state and types the correct keystrokes to run the accounting program.

�The target user observes this process and learns how to use the new accounting program.

�After demonstrating how to use the accounting program, the controller switches to the monitoring state and returns control to the target user.

Understanding the DCAF Environment

DCAF offers two main levels of security, which limit users' ability to take over your target workstations. These levels, basic DCAF (or nonsecure) and secure DCAF, offer protection for your workstations to varying degrees. For typical nonsecure environments that deal with nonconfidential information, basic DCAF provides adequate protection. Secure DCAF is more complex and caters to environments, such as banks and insurance companies, that work with confidential material and require greater protection.

In order to be part of the DCAF environment, the workstations must have DCAF components installed.

The DCAF Components

Before you begin the installation, you should be familiar with the DCAF components. The role of each workstation in your network determines the component(s) you install on that workstation. All components, except targets, run on OS/2 workstations only.

You can install one or more components on the same workstation, but it is recommended that you install only the necessary components on each workstation. For example, on one workstation you might install a controller , on another, the gateway and LAN directory, and on a third, a target component.

The Controller

The controller enables you to control the keyboard and mouse input and monitor the display output of a target workstation. It enables you to transfer files between the controller and target.

The Target

The target runs on three kinds of operating systems:

�The OS/2target enables an OS/2 workstation to be monitored and controlled by the controller.

�The Windowstarget enables a Windows workstation to be monitored and controlled by the controller. The controller connects to the workstation whether it is operating in DOS full-screen mode or in a Windows graphic environment.

�The DOStarget enables a DOS workstation to be monitored and controlled by the controller. To install the DOS target, either create an installation package or use the CID method. Use the packager on an OS/2 workstation to create a DOS target installation package and then install the target on the DOS workstation.

In each case, the controller connects to the target directly if it is a basic DCAF target, or through a gateway if the workstation is secure.

The Gateway

The gateway links a controller with secure targets or with targets connected through an SNA backbone. The gateway always requires that you install a LAN directory on a workstation-any workstation-on the same LAN.

The gateway connects to all targets using the NetBIOS communication protocol. Therefore, install the gateway only in those parts of your network that use NetBIOS.

The gateway supports more than one session at a time so you probably need one gateway per logical LAN. To connect to secure targets, the gateway must be secure as well.

The LAN Directory

The LAN directory provides a list of the targets on a LAN that are available to the controller. When the controller connects directly with the targets via IPX/SPX, NetBIOS, or TCP/IP, the LAN directory is optional. When the controller connects with the targets through a gateway, the LAN directory is required.

Install one LAN directory per logical LAN. If you install more than one LAN directory on a logical LAN, give each a unique name.

The LAN directory also keeps a list that associates the workstation's physical address on the LAN with a nickname that makes the target name easy to remember. This list also enables the controller to find targets quickly. You can install the LAN directory on the target, gateway (if present), or on any workstation on the same LAN as the target.

The Security Administrator

The security administrator is necessary for secure DCAF only. It provides centralized maintenance of the databases for controllers, target access tables, secure target workstations, and security authenticators. Install one security administrator, typically on a controller, for your entire network if you are using secure DCAF. Safeguard this workstation from unauthorized access.

The security administrator keeps an encrypted database of authorized users, as well as an audit log file, EQNADMN.LOG. To be able to transfer security database files to the security authenticator, you must install either the security authenticator or a controller on the same workstation as the security administrator.

The Security Authenticator

The security authenticator is necessary for secure DCAF only. It authenticates sessions with secure targets. The security authenticator also gives access to secure targets based on security profiles for authorized controllers that it receives from the security administrator.

Install the security authenticator on an OS/2 target on the same LAN. Install it either on the security administrator workstation or on the secure OS/2 target workstation, so that it can receive security information from the security administrator.

If you install the security administrator on the LAN, you can install the security authenticator on the same workstation. Install at least one security authenticator for each logical LAN in your network.

The Packager

The packager is an installation aid only. It creates installation packages of DCAF components that you can install on other workstations. In addition, the packager enables you to prepare a component with the same personalization features to be installed in large numbers all over your network. Always install DOS targets using the packager.

The DCAF Network

The DCAF network includes the workstations that have DCAF installed and the communications that link them.

The Example of a Distributed Console Access Facility Environmentfigure, which follows, is one example of a basic DCAF environment. [Artwork not shown]

The DCAF workstations communicate with the following communication protocols:

• Advanced Peer-to-Peer Networking (APPN)
• Advanced Program-to-Program Communication or APPC); more specifically, Logical Unit Type 6.2
• Asynchronous (also called Asynchronous Communications Device Interface or ACDI)
• IPX/SPX (except for DOS targets)
• NetBIOS
• TCP/IP (except for DOS targets)

Controller Acommunicates directly with target E and with gateway B using switched asynchronous communication.

Controller Aalso communicates, via LU 6.2 over a Systems Network Architecture (SNA) network or backbone, through gateway Bto the targets on the LAN. The SNA backbone represents the part of the network that connects (via switched lines, leased lines, or satellite communications) host computers, communication controllers, and other computer hardware. Any connections over an SNA backbone must go through a gateway.

Controller Acommunicates directly with target Fvia LU 6.2. For LU 6.2 communications, the physical unit type for the controller, target workstation, and DCAF gateway workstation must be configured as a type 2.1 (PU2.1).

Controller Acommunicates via TCP/IP through a router with LAN directory Iand with target H.

Controller Acommunicates via IPX/SPX through a router with LAN directory Kand with target J.

Controller Acommunicates via NetBIOS directly with LAN directory Mand with targets L, N,and Oon the LAN.

OS/2 target workstations on the LAN require that OS/2 Communications Manager, LAN Adapter and Protocol Support (LAPS) from NTS/2, or the LAN Server 2.0 be installed to provide the NetBIOS device drivers. In order to run DCAF with other applications that require NetBIOS services, you may need to increase the NetBIOS resources via the OS/2 Communications Manager or LAN Services.

DOS target workstations on the LAN require that a LAN support program be installed, such as the IBM LAN Support product. DCAF supports DOS target workstations on the LAN only.

Levels of DCAF Security

DCAF provides the following levels of security:

�Basic (Nonsecure)

-No password

-Password-only

�Secure

-Secure session

Basic (Nonsecure) Level

A no passwordsession exists between a controlling workstation and a gateway or target workstation for which a password is not defined and, therefore, is not necessary.

A password-onlysession exists between a controlling workstation and a gateway or target workstation for which a password is defined. The controller must type the password before the session can be established.

In both the no passwordand password-onlycases, the target component was installed as basic, or nonsecure. Basic DCAF provides adequate protection for nonsecure environments that deal with nonconfidential information.

Secure Level

Secure DCAF offers a higher and more advanced level of security for environments such as banks and insurance companies that work with confidential material. You can make a target workstation almost impregnable to intruders by designating it as a secure target. The controller must access the secure target through a secure gateway.

A securesession exists between a controlling workstation and a gateway or target workstation that has been installed as a secure gateway or target. These secure workstations do not have passwords. Instead, the controller, authorized to access a secure gateway or target, has a personal pass phrase (a compound password) and an access-level profile for a specific secure workstation.

DCAF security works with the following communication connections only:

�A controller can connect to a secure gateway via APPC/APPN or asynchronous .

�The secure Gateway can connect to a secure target via NetBIOS only.

The Example of a DCAF Environment with Session Securityfigure shows some workstations in a secure DCAF environment. The gateway can use only NetBIOS to communicate with the secure targets. Secure targets must be on a LAN ( see targets Cand Din the following figure.) [Artwork not shown]

Controller Acommunicates via secure gateway Bwith the secure targets on the LAN. When the controller wants to take over secure target C,security authenticator Dverifies that the controller is authorized to access that workstation.

DOS or Windows target Eon the LAN is not secure and does not require authentication. It has password-only security. Controller Acan also establish a session with secure target workstation F.Typically, the secure DCAF gateway, LAN directory, and security authenticator reside on target workstation F.In this case, controller Aconnects to gateway Fvia APPC, and gateway Fconnects internally to target Fvia NetBIOS.

The security administrator is typically installed on a controller workstation. It provides security file maintenance, a message log file, and control access information used by the DCAF security authenticators, all in a central location. Security files are transferred from the security administrator via a secure session to all of the remote security authenticators. Security administrator workstation Gtransfers new or updated security files to security authenticators Dand F.

When the controller wants to change a pass phrase, the security authenticator verifies the authorization before a session is allowed, and keeps a log file of the authentication activity. The verification compares the controller's input with the ciphered data stored on the security authenticator. The advantage of this mechanism is that there is no way to intercept or discover the pass phrase during transmission, because only the ciphered data is sent.

For auditing purposes, the gateway logs all session connections and the communication errors that it filters.

Entry Points from DCAF to OS/2 Presentation Manager

This portion of the chapter describes the additional entry points that implement the new capabilities of the XGA Display Driver in order to efficiently track the screen region that is updated by Presentation Manager drawing functions and to handle the related data.

Modifications to the XGA Display Driver fall into two distinct areas:

�Efficient accumulation maintenance and querying of clipped screen bounds of all screen drawing operations. This is provided by the following new functions:

-GreOpenScreen Change Area

-GreGetScreenChangeArea

-GreCloseScreenChangeArea

�Compression of data from a specified area of the screen into a memory buffer and, usually after transmission over network, decompression of that data into an internal memory bit map. This is accomplished by the following new functions:

-GreGetScreenBits

-GreSetScreenBits

Data conversion must be performed between the different modes (bpp) and the different data formats (planar or packed), in order to allow the data interchange between XGA and VGA, between XGAs working in different internal formats and, in general, between all the display drivers providing these entry points.

GreOpenScreenChangeArea

Description:

GreOpenScreenChangeAreaallocates a data area internal to the display driver, in which the driver will accumulate screen changes. GreOpenScreenChangeArea returns a 32-bit handle that is required to identify the area in GreGetScreenChangeArea and GreCloseScreenChangeArea calls.

Parameters:

HDC hdc
PDC pdcArg
ULONG FunN
Refer to the chapter regarding mandatory and simulated graphics engine functions in the OS/2 Presentation Device Driver Referencefor details on this function.

GreGetScreenChangeArea

Description:

GreGetScreenChangeAreatakes an SCA handle and, for the identified SCA, adds its rectangles to the region pointed to by the phrgnfield. The SCA is reset to NULL as a result of this call.

Parameters:

HDC hdc
HSCA hsca
PHRGN phrgn
PDC pdcArg
ULONG FunN
Refer to the chapter regarding mandatory and simulated graphics engine functions in the OS/2 Presentation Device Driver Referencefor details on this function.

GreCloseScreenChangeArea

Description:

GreCloseScreenChangeAreafrees the data area internal to the display driver , identified by the SCA handle, that was accumulating screen changes.

Parameters:

HDC hdc
HSCA hsca
PDC pdcArg
ULONG FunN
Refer to the chapter regarding mandatory and simulated graphics engine functions in the OS/2 Presentation Device Driver Referencefor details on this function.

GreGetScreenBits

Description:

GreGetScreenBitsqueries a region of screen pixel data and saves it in the memory provided by the caller. The data is compressed, and can be converted into a format suitable for another supported display device. The process will stop when either of the following situations occurs:

�The supplied memory area is full

�The requested region has been returned

Parameters:

HDC hdc
HRGN hrgnApp
PBYTE pDest
PULONG pulLength
ULONG flCmd
PDC pdcArg
ULONG FunN
Refer to the chapter regarding mandatory and simulated graphics engine functions in the OS/2 Presentation Device Driver Referencefor details on this function.

GreSetScreenBits

Description:

GreSetScreenBitstakes compressed data, generated by a previous call to GreGetScreenBits, from a buffer and decompresses it into the currently selected memory bit map. The call is only valid for a memory DC that has a bit map selected that is the same size as the screen of the machine on which the GreGetScreenBits call was performed. There is no clipping; if a rectangle exceeds the bit-map dimensions, the function will terminate immediately with an error logged. The bit map may be left in a partially drawn state as prior rectangles may have been copied into it.

The function may be passed a region handle, in which case the area defined by the set bits will be added to the region.

The XGA driver may be passed 4bpp planar, 4bpp packed, 8bpp packed and 16bpp packed data.

Parameters:

HDC hdc
PBYTE pBuffer
ULONG cBytes
HRGN hrgn
PDC pdcArg
ULONG FunN
Refer to the chapter regarding mandatory and simulated graphics engine functions in the OS/2 Presentation Device Driver Referencefor details on this function.

Code Modifications Required in Base Driver for DCAF

The majority of the new code is contained within new modules that are simply linked with the base driver. The areas of the base driver code that must be modified include the following:

�The Dispatch Table, which contains the new Entry Points

�All drawing functions, which contain extra tests to determine whether they should accumulate clipped screen bounds and, if necessary, code to calculate the clipped bounding rectangle

�Seamless Windows cursor exclusion code, which is modified to call the new bounds accumulation routine.

Dispatch Table

In the EDDEFLDB.C, where the dispatch table is filled in with the display driver entry points, the five new entry points are included in the Driver Dispatch Table with the following function numbers:

GreOpenScreenChangeArea 0x4012
GreGetScreenChangeArea 0x4013
GreCloseScreenChangeArea 0x4014
GreGetScreenBits 0x401D
GreSetScreenBits 0x401E

Accumulating and Querying Screen Bounds

TraditionalPresentation Manager bounds are unclipped, and use a single rectangle to define their limits. In order to better define the bounding area, the DCAF-enabled display driver now has the ability to maintain one or more clipped, multirectangle regions (Screen Change Areas or SCAs) that are updated to indicate areas on the screen that have been drawn to.

This ability is provided by the following changes to the base driver:

�Three new entry points or functions to create, query and delete Screen Change Areas, as follows:

-GreOpenScreenChangeArea

-GreGetScreenChangeArea

-GreCloseScreenChangeArea

�Two bounds accumulation internal routines, which add a single rectangle to all of the currently active SCAs.

�An extra flag test in the path of every display driver drawing function ( for COM_SCR_BOUND in the high-order word in the last parameter of the GreXX calls, FunN).

If this flag is set and the drawing operation is going to the screen, the drawing function passes a clipped bounding rectangle of the drawing primitive to the bounds accumulation functions described above. The code required to do this is driver-specific.

�Interception of Windows cursor exclusion calls and passing the supplied exclusion rectangle to the new bounds accumulation function.

Compressing and Decompressing Data

The bounding routines described above and under Performing the Bounding Accumulationefficiently track the regions on the screen that are updated by Presentation Manager drawing functions. The DCAF-enabled display driver also provides the ability to compress, decompress and, if necessary, convert the format of screen data.

This ability is provided by the following two new entry points or functions :

• GetScreenBits
• SetScreenBits

The task is performed by the internal routine CompressRect in COMPRESS.ASM. The compressed data that is passed between display drivers uses a private format (that is, no external application or program has the right to examine, alter or make any assumptions about the content of the data). This allows the compression method to be improved in later versions of the driver. Definitions of the data structures are as follows:

1.PACKET HEADER

dd total_data_packet_length (including header)

dw data_format

2.RECTANGLE HEADER

dw xLeft

dw yBottom

dw xRight

dw yTop

3.RECTANGLE DATA

The rectangle data is split into individual rows. Each row is split into run-length encoded blocks (cells), each of which comprises a length field followed by one or more data fields. The sizes of both the length and data fields vary according to the format of the data being transmitted (as specified by the data_format field in the packet header), as follows:

4bpp field size is one byte (8 bits)
8bpp, 16bpp field size is two bytes (16 bits)

The following encoding rules are used:

�If the length field contains a positivevalue (most significant bit notset), then the following single data field is repeated (length) times. If the data field size is 8 bits, this value will be limited to a maximum of 127.

�If the length field contains a negativevalue (most significant bit set), then (length - most significant bit) fields of nonrepeating data follow. If the data field size is 8 bits, this value will be limited to a maximum of 127.

�If the length field is zero and the following field is nonzero, the nonzero field is a count of the number of times that the single previous row is repeated. If the data field size is 8 bits, this value will be limited to a maximum of 127. This will only appear as the first cell in a row, and only after there has been at least onerow of data.

�If the length field is zero and the following field is zero, the next ( third) field is a count of the number of times that the previous pair of rows are repeated. If the data field size is 8 bits, this value will be limited to a maximum of 127. This will only appear as the first cell in a row, and only after there have been at least tworows of data.

The following example shows the hexadecimal values of an 8bpp compressed bitmap:

 0003 0004  00FA 0405 0706 0802 0104 0903 0001  ...........  0000 0003  0000 0000 0004  ...
  lf   df    lf   df   df   df   df   df   df                lf    df    lf   df   df
   cell1                cell2                                 celln      celln+1

This bitmap would expand as follows (two-digit values represent a color index for a single pixel):

 00 04 00 04 00 04 04 05 07 06 08 02 01 04 09 03 00 01 ............ row1

                                                do three more identical rows (celln):

 00 04 00 04 00 04 04 05 07 06 08 02 01 04 09 03 00 01 ............ row2
 00 04 00 04 00 04 04 05 07 06 08 02 01 04 09 03 00 01 ............ row3 
  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row4 

                                                     do   four   pairs   of   identical   couples   ( celln + 1 ) : 

  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row5 
  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row6 

  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row7 
  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row8 

  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row9 
  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row10 

  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row11 
  00   04   00   04   00   04   04   05   07   06   08   02   01   04   09   03   00   01   . . . . . . . . . . . .   row12 

The following example shows the hexadecimal values of a 4bpp compressed bitmap:

 03 04  FA 04 05 07 06 08 02 ...........  00 03  00 00 04  ...
 lf df  lf df df df df df df              lf df  lf df df
 cell1        cell2                       celln  celln+1

This bitmap would expand as follows (one-digit value represents a color index for a single pixel):

 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row1

                                      do three more identical rows (celln):

 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row2
 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row3
 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row4

                                      do four pairs of identical couples (celln+1):

 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row5
 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row6

 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row7
 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row8

 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row9
 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row10

 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row11
 0 4 0 4 0 4 0 4 0 5 0 7 0 6 0 8 0 2 ............ row12

Standard Golomb Run Length Encoding compression is inefficient at compressing 2x2 dither patterns, which are commonly used by Presentation Manager Display Drivers. The modified compression algorithm handles these patterns efficiently for the following reasons:

�For 4bpp and 8bpp, the data field size is such that, when a row is compressed, pairs of adjacent pels are put in each data field. Note that there is no dithering at 16bpp.

�When searching for duplicate scanlines, the algorithm also searches for duplicate scanline pairs that will match and compress patterns that repeat on alternate scanlines.

The actual pixel data is stored in Motorola format; that is, the most significant bits of a byte contain the leftmost pels. An example is shown below for a pair of pixels (PEL1,PEL2):

for the 4bpp format:
                     - PEL1 goes in bits 7..4
                     - PEL2 goes in bits 3..0

for the 8bpp format:
                     - PEL1 goes in bits 15..8
                     - PEL2 goes in bits  7..0

All 4bpp data is defined as indices into the standard VGA palette. All 8bpp data is defined as indices into the standard XGA palette. All 16bpp data is defined as XGA-format 16-bit color values. (See the appendix regarding default color palettes in the IBM OS/2 Display Device Driver Referencefor details of these formats).

All changed drivers must convert their own internal format into one of these standard formats before transmission. Refer to the section on Converting Datalater in this chapter.

Maintaining and Tracking Screen Change Areas (SCAs)

A key part of the modifications concerns the maintenance and tracking of SCAs.

SCA Definition

These areas track, as efficiently as possible, regions of the screen that are altered by display driver drawing routines. This tracking is done by using multiple rectangles to define the area, rather than the usual single bounding rectangle provided by traditionalPresentation Manager bounding functions.

SCAs are maintained within the driver in an SCA data structure, defined in the new DCAF.H file. For details, refer to the SCA data structure in the Appendixes of the OS/2 Presentation Device Driver Reference. Instances of this structure are dynamically created and destroyed upon calls to GreOpenScreenChangeArea and GreCloseScreenChangeArea, respectively. For details, refer to these functions in the chapter of the OS/2 Presentation Device Driver Referencethat discusses mandatory and simulated graphics engine functions.

A global variable, pStartSCA,points to the latest SCA instance created. If pStartSCAis null, there are no active SCAs. All SCA instances are linked together in a list using the pscaNextfield of the SCA data structure. A null value in this field indicates the end of the list (the earliest created SCA). For example:

Memory loc.
              -------------------       pStartSCA = 250;
              | pscaNext = 200  |
              |                 |
              |      4th SCA    |
   0x250      -------------------

              -------------------
              | pscaNext = 150  |
              |                 |
              |      3th SCA    |
   0x200      -------------------

              -------------------
              | pscaNext = 100  |
              |                 |
              |      2nd SCA    |
   0x150      -------------------

              -------------------
              | pscaNext = 0    |
              |                 |
              |      1st SCA    |
   0x100      -------------------

Each SCA instance can store multiple rectangles, up to MAX_SCA_RECTS (14), which define the area on the screen that has changed since the SCA was created or last queried. These rectangles are stored in the array arcl[]. The number of rectangles stored within the array is kept in the cRectsfield, which will never exceed MAX_SCA_RECTS. If cRectsis zero, the SCA is a null area - the initial state.

The remaining field in the SCA data structure, aulRectSize[],is an array containing the sizes of the rectangles in arcl[]. This is not strictly necessary, because the sizes can be calculated on the fly using the dimensions in arcl[]. However, when accumulating a rectangle into a SCA, the size of each of the rectangles is frequently needed. Caching the rectangle sizes in this array saves having to recalculate the sizes every time, resulting in better performance.

The SCA data structure defines space for (MAX_SCA_RECTS+1) rectangles, but only MAX_SCA_RECTS are ever used to define the SCA. The extra rectangle is used to simplify the routine that accumulates rectangles into the SCA.

Creating a new SCA

Creating a new SCA, accomplished by GreOpenScreenChangeArea (SCRAREA.C), requires the following steps:

�Allocate memory for the new SCA instance

�Set the cRectsfield to be zero

�Set the pStartScaglobal variable to point to the new SCA address

�Link the instance to the linked list of SCAs

The newly created SCA will be identified by a 32-bit handle, which is the address of the SCA location in the display driver.

Accumulating a Rectangle into an SCA

All display driver functions that draw to the screen are modified to accumulate clipped bounding rectangles into all active SCAs when necessary. The drawing functions determine whether they should do this by examining the FunN (Function Number/COM_ flags) parameter. If the COM_SCR_BOUND flag is set, and the function is drawing to the screen, then bounding rectangles are accumulated into the active SCAs; otherwise, no accumulation takes place. The setting of COM_SCR_BOUND is controlled by the GreOpenScreenChangeArea and GreCloseScreenChangeArea functions. For details , refer to these functions in the chapter of the OS/2 Presentation Device Driver Referencethat discusses mandatory and simulated graphics engine functions.

In every drawing call, the following test is performed:

    if (DCAFBoundsRequired(FunN))
    {
      accumulate the bound

    }

where the DCAFBoundsRequired macro is defined in DCAFEXTF.H as follows:

#define DCAFBoundsRequired(FunN)      \
    ( (FunN & COM_SCR_BOUND) &&       \    /* COM_SCR_BOUND is set   */
      (FunN & COM_DRAW) &&            \    /*  COM_DRAW is set    */
      (pdc->DCIDCType == OD_DIRECT) )      /*  the destination is the screen */

When change-area tracking is not needed, COM_SCR_BOUND will never be set. The difference in operation and performance of the DCAF-enabled base driver will be negligible-one additional check of the COM_SCR_BOUND flag per drawing function.

Performing the Bounding Accumulation

Two routines (in SCBOUNDS.C) perform the bounding accumulation:

�VOID AccumulateScreenBounds( PRECTL prclArgBound);

�VOID AccumulateScreenBoundsThroughClips( pDevRect pBoundCoords, ULONG ulCoordType );

AccumulateScreenBounds

This routine is called by GreSetPel and GrePolyShortLine, the drawing functions that are able to pass preclipped bounding rectangles. Its task is to take the passed rectangle and accumulate it into all the current SCAs. The passed rectangle is in exclusive SCREEN coordinates.

AccumulateScreenBoundsThroughClips

This routine takes the supplied (unclipped) bounding rectangle, intersects it with each of the clip rectangles in the DC and accumulates each of the clipped bounds into the active SCAs. The supplied bounding rectangle can be in one of the following types of coordinates:

16-bit AI coordinates (COORD_AI) Origin is top-left of screen
16-bit Device coordinates (COORD_DEVICE_WORD) Origin is current DC origin
32-bit Screen Coordinates Origin is bottom-left of screen

The ulCoordtypefield specifies which of these coordinates is being supplied.

AccumulateScreenBoundsThroughClips can be called from the same point in drawing functions as the ordinary (unclipped) bounds are accumulated. This minimizes the complexity and number of changes required in the main drawing code. Before accumulating the bounding rectangle, according to the following accumulation algorithm, the coordinate conversion (if required) to exclusive SCREEN coordinates and the clipping of the passed rectangle must be performed. The clipping can be done against the DC cache clip rectangles, or it may require a call back to the Graphics Engine to get the clip set. When a rectangle is added into an SCA, it is done in such a way as to minimize the increase in area of the SCA.

The following accumulation algorithm accomplishes this:

for (pscaCurrent = each SCA in the linked list)
:
: // First check whether the new rect is already contained within this SCA
: for (rclCurrent = each rectangle in current SCA)
: : if rclNew lies completely within rclCurrent
: : : no more work - skip straight to next SCA
: : endif
: endfor

: // We have to add the rectangle to the SCA.
: // First see if there is free space for the rectangle within the SCA.
: if pscaCurrent->cRects < MAX_SCA_RECTS
: : copy rect into SCA
: : calculate size and store in SCA
: : increment pscaCurrent->cRects
: else
: : // All of the SCA rects are used.
: : // Copy the new rect into the SCA at position (MAX_SCA_RECTS+1) and the
: : // problem then becomes:
: : // We have MAX_SCA_RECTS+1 rectangles, which we have to reduce
: : // to MAX_SCA_RECTS by merging two of the rectangles into a single rectangle.
: : // The pair of rects that we merge are the two that will cause the smallest
: : // increase in area.
: : initialize ulSmallestAreaIncrease to be maximum possible value
: : for (iRect1 = each rectangle in the SCA)
: : : for (iRect2 = iRect1+1 to MAX_SCA_RECTS+1)
: : : // This inner loop is the performance bottleneck.
: : : // Make it as fast as possible, if you can!!
: : : : if area increase of (iRect1,iRect2) merged < ulSmallestAreaIncrease
: : : : : set ulSmallestAreaIncrease to be area increase of (iRect1,iRect2) merged
: : : : : set best pair of rects to be (iRect1,iRect2)
: : : : endif
: : : endfor
: : endfor
: :
: : merge best pair of rects found into the slot originally occupied by Rect1
: : if rclNew was not one of those merged
: : : copy rclNew into vacant slot made by merging pair
: : endif

: endif
endfor

When change-area tracking is active, this routine is called by every function that draws to the screen. Therefore, the routine must be as efficient as possible (particularly in the inner loop) to minimize the hit on performance.

Deleting an SCA

This task is performed by GreCloseScreenChangeArea (SCRAREA.C), as follows:

�Unlink the SCA instance from the linked list of SCAs

�Free the memory for the SCA instance

In a typical example, if we close the second SCA:

Memory loc.
              -------------------       pStartSCA = 250;
              | pscaNext = 200  |
              |                 |
              |      4th SCA    |
   0x250      -------------------

              -------------------
              | pscaNext = 150  |
              |                 |
              |      3th SCA    |
   0x200      -------------------

              -------------------
              | pscaNext = 100  |
              |                 |
              |      2nd SCA    |
   0x150      -------------------

              -------------------
              | pscaNext = 0    |
              |                 |
              |      1st SCA    |
   0x100      -------------------

we will get:

Memory loc.
              -------------------       pStartSCA = 250;
              | pscaNext = 200  |
              |                 |
              |      4th SCA    |
   0x250      -------------------

              -------------------
              | pscaNext = 100  |
              |                 |
              |      3th SCA    |
   0x200      -------------------

              -------------------
              | pscaNext = 0    |
              |                 |
              |      1st SCA    |
   0x100      -------------------

If the last remaining SCA is being freed, pStartSCA is set to NULL. If the latest SCA created is being freed, pStartSCA is set to the address of the SCA created immediately prior to it (the previous SCA).

Converting Data

The changed display drivers use different internal data formats:

�VGA 4bpp planar

�XGA 4bpp packed, 8bpp packed, 16bpp packed

When data is transmitted between display drivers, it is done at the lower bpp of the two drivers (or at the lowest bpp; for example, a pair of 16bpp DCAF-enabled drivers could communicate at 4bpp to reduce the amount of data transmitted). Therefore, the following conversion routines are required by the display driver:

XGA (4bpp, 8bpp, 16bpp packed)

internal format     required format 

16bpp packed  ->  8bpp packed (compression)
16bpp packed  ->  4bpp packed (compression)
16bpp packed  ->  4bpp planar (compression)
 8bpp packed  ->  8bpp packed (compression)
 8bpp packed  ->  4bpp packed (compression)
 8bpp packed  ->  4bpp planar (compression)
 4bpp packed  ->  4bpp planar (compression)


               external data format     internal format 

(decompression)  8bpp packed -> 16bpp packed 
(decompression)  8bpp packed ->  8bpp packed 
(decompression)  4bpp packed -> 16bpp packed 
(decompression)  4bpp packed ->  8bpp packed 
(decompression)  4bpp planar -> 16bpp packed 
(decompression)  4bpp planar ->  8bpp packed 
(decompression)  4bpp planar ->  4bpp packed 

The conversions from packed to planar and vice versa are assisted by the use of a lookup table to split packed bytes into bits that can be conveniently reassembled into planar format (and vice versa).

All conversions to planar format are done by first converting the bits per pel to 4 (still in packed format) and then performing an optimized 4bpp packed-to-planar conversion. In conversions from 4bpp planar a similar, but reverse, process is performed- converting from 4bpp planar to 4bpp packed and then to the required packed destination format.

Conversions from 4bpp and 8bpp use a lookup table to efficiently translate the colors. Conversions from 16bpp cannot use a direct lookup table because the size is prohibitive. Therefore, colors have to be searched for on a nearest colorbasis in the destination color table. This is much slower than a simple table lookup. To improve performance, a cache of the most recently calculated colors is kept, which saves having to repeatedly recalculate commonly used colors.

Seamless Windows Support

In OS/2 2.1, Seamless Windows is supported by allowing the Windows display driver to draw directly on the Presentation Manager (PM) screen. This means that Seamless Windows updates do not go through the PM drawing functions and, therefore, will not update the active screen change area (SCA) in the usual way. As a result, Seamless Windows requires special treatment.

Prior to drawing on the PM screen, the Seamless Windows driver calls the PM driver through an exported entry point, SeamlessExcludeCursor. This call excludes the PM cursor from the area in which the Seamless Driver is about to draw. The modified DCAF-enabled display driver intercepts this call and passes the rectangle coordinates to AccumulateScreenBounds.

Under DCAF, during PM display driver initialization, Seamless Windows must be granted addressability to all data and code that it will access during the call to SeamlessExcludeCursor. In order to add the supplied rectangle to all active SCAs, which can reside anywhere in the display driver heap, there is a single, static SSA (Seamless Screen Area), called scaSeamless, used for this purpose. All Seamless bounding rectangles will be accumulated in scaSeamless; then, this SCA is merged with the other active SCAs when a query is issued via GreGetScreenChangeArea.

As a result, at initialization (in InitializeSeamless), the Seamless Windows driver is given access to AccumulateScreenBounds, to scaSeamless and to the DDT display driver control block, in order to retrieve the screen dimension at seamless time. The addresses of this data are stored in the SeamlessAddresses control block, owned by the Windows driver.

Before writing to the PM screen, the Seamless Windows driver will call SeamlessExcludeCursor. The exclusion rectangle will be passed in the following registers in so-called AI coordinates (i.e., 16-bit inclusive; 0, 0 is top left of screen):

Left cx
Top dx
Right si
Bottom di

The display driver will determine whether the new bounds accumulation is needed by checking the value of the pStartSCA pointer and, in SeamlessExcludeCursor32, will call AccumulateSeamlessBounds to initiate the bounds accumulation. AccumulateSeamlessBounds converts the passed rectangle to EXCLUSIVE SCREEN coordinates, clips the rectangle to the screen dimensions and calls AccumulateScreenBounds. This causes the rectangle supplied to SeamlessExcludeCursor to be added to only scaSeamless. When an SCA is queried using GreGetScreenChangeArea, the Seamless SCA is merged with the active SCAs and then reset to NULL.

DBCS Video Driver Support

This chapter describes double-byte character set (DBCS) video driver support. It covers:

�Developing PM display drivers and making the modifications to implement DBCS enabling

-The device driver font manager and the device font drivers

-Font manager functions

-Font driver functions

�Modifications to the physical device driver (SCREENDD)

�Modifications to the base video subsystem components

The glyph points, IDs, and character descriptions for all double-byte character sets except for Kanji pattern and SBCS characters are in Glyph Codes.

PM Display Drivers

DBCS PM display drivers are International Language Support drivers, which means they support both SBCS and DBCS. The PM display driver developed from the DBCS sample code can run on both the SBCS and DBCS versions of OS/2. Developers whose target is a worldwide market (DBCS as well as SBCS countries) can use the DBCS sample code as the base code.

The IBM Developer Connection Device Driver Kit for OS/2includes samples of 32-bit PM display drivers for VGA and Super VGA. The 32-bit display driver runs only with the 32-bit graphics engine (GRE), but a 16-bit display driver will work with both the 32-bit and 16-bit GREs.

For detailed information on the 32-bit PM display drivers for VGA and Super VGA, see 32-Bit VGA Display Driverand 32-Bit Super VGA Display Driver.

Development of PM Display Drivers

This section covers the development of DBCS 16-bit and 32-bit PM display drivers and the modifications necessary for the display adapter cards and for DBCS enabling. The developer should have a basic knowledge of the PDI ( Presentation Driver Interface), which defines the interface between the graphics engine and the presentation driver. For further information on the PDI, refer to the OS/2 Presentation Device Driver Reference.

Overview of Modifications

There are two kinds of modifications to consider:

�Modifications to the display hardware

�Modifications to implement enabling of DBCS, which allows the DBCS characters to be displayed on the screen

There are three types of character sets:

�DBCS (Double-Byte Character Set)-2-byte Kanji, Hiragana, and Katakana (etc .) character set

�SBCS (Single-Byte Character Set)-1-byte alphanumeric (and special characters) character set

�MBCS (Mixed-Byte Character Set)-character set containing both DBCS and SBCS characters

Hardware modifications are required when developing a PM display driver for a display card that is not supported by the IBM PM display drivers. If the developer models the display driver design on the VGA/SVGA drivers supplied , then further modifications for DBCS enabling are not necessary because these are provided in the device-independent component.

Hardware Modifications

Generally to support any kind of display card besides VGA, hardware modifications will be required. Most of the functions will need to be checked and modified when a hardware modification is made. Performance may be improved by using the functions supported by the hardware for each individual card.

A PM display driver must support the memory for a bit map and the physical display screen as the target device context. The format of the memory bit map is tailored to the definition of the video memory structure to improve performance. For example, VGA has a four-plane memory structure, and it has the reflective memory bit-map format. This is called planer pixel. There is also a format where one pixel consists of multiple bits in one plane as in the 8514/A. This is called packed pixel. The BITBLT routine for the memory bit map in the sample code does not have any dependencies on the hardware. If the appropriate base code is selected, then it does not have to be modified for differences in the hardware. The BITBLT routine for the physical display screen must be modified depending on the display adapter card.

DBCS Enabling

The sample code (IBMVGA32.DLL) already includes DBCS enabling. If the VGA/ SVGA driver is chosen as the base code then no adaptation for DBCS enabling is required. This is because this code does not have any hardware dependencies. To maintain compatibility among display drivers DO NOT change the enabled code for DBCS. If the VGA/SVGA driver is not used as the base code, then modifications will be necessary to provide DBCS enabling.

The PM display driver handles DBCS characters by calling the font manager ( PMNLSFM.DLL). Using the font manager and font driver (PMNLSFD.FDR) for DBCS fonts results in the handling of SBCS proportional fonts. The interface for the font manager is described in Device Driver Font Manager Interface.

Modification Note

It is expected that the modified PM display driver will work in an SBCS environment. This means that the driver will work as an SBCS driver when the OS/2 U.S. version is installed. The following table explains how the PM display driver works under various environments.

/----------------------------------------------------------\
| Environment              |(1)|   |   |   |(2)|   |   |(3)|
|--------------------------+---+---+---+---+---+---+---+---|
| DBCS system code page    | � | � | � | � |   |   |   |   |
|--------------------------+---+---+---+---+---+---+---+---|
| PMNLS.DLL available      | � | � |   |   | � | � |   |   |
|--------------------------+---+---+---+---+---+---+---+---|
| PMNLSFM.DLL available    | � |   | � |   | � |   | � |   |
\----------------------------------------------------------/

DBCS system code page The primary code page in CONFIG.SYS is the DBCS code page

PMNLS.DLL available PMNLS.DLL is loaded

PMNLSFM.DLL available The font manager, PMNLSFM.DLL, is loaded

(1) The PM display driver works as a DBCS driver. The default font is the DBCS font.

(2) The PM display driver works as an SBCS driver. The default font is the SBCS font. When the application requests DBCS fonts, using the appropriate API, like GpiCreateLogFont, DBCS fonts will be displayed.

(3) The PM display driver works as an SBCS driver. The default font is the SBCS font.

PMNLS.DLL This component is unique in the OS/2 DBCS version. It handles unique things for DBCS, such as the code page range of DBCS characters.

Change Items for OS/2 J2.0

This section describes new features added since OS/2 J1.X.

The following changes are common to both SBCS and DBCS.

�Multiple Virtual DOS Machine (MVDM) is supported.

-Sharing the video resource with the virtual video device driver. ( Coexistence of PM and multiple DOS graphics.) Development of the virtual video device driver is required.

-Seamless Windows is supported. Development of a Windows display driver is required.

�The bit-map function is extended.

-Windows-compatible bit map format is supported (including run length encoded bit map).

-Changing the size of the bit map is supported.

�The line mix attribute is extended.

-PolyLine

-PolyShortLine

-PolyScanLine

�The Palette Manager is supported.

(This function is available only in the 32-bit 256-color display driver.)

-It is possible to program palette functions, like creating, selecting, and realizing palettes.

-Palette color animation is provided.

�Some parts of the source code are translated to 80386.

-32-bit data handling

-Use of 80386 instructions

-Use of the GS segment register

-Use of the FS segment register (Refer to the OS/2 J2.0 Technical Library Control Program Programming Reference.)

�The Presentation Driver Interface (PDI) data structure is modified and extended.

-The device context (DC) data structure is modified (the DxxBUNDLE structure is extended).

-The FONTMETRICS data structure is changed.

-The PDI function entries are added.

-Device caps definition is extended. (CAPS_LINE_WIDTH_THICK 3)

�The size of the device standard icon is changed.

-On a VGA system, it is 32 x 32 dot.

-On a high resolution system (ex. 8514), it is 40 x 40 dot. (In the U.S. OS /2 version, it has been 40 x 40 since OS/2 1.3. On OS/2 1.2, it was 64 x 64 dot.)

�The font resolution is changed.

-In the VGA system, it is 96 dpi.

-In the high-resolution system (8514, for example), it is 120 dpi.

To support this resolution, the font point size is changed.

The following changes are unique to DBCS.

�Font support is expanded.

-Proportional fonts are supported.

-Non-zero descender fonts are supported.

-The font selection has expanded (8, 10, 12, 14, 18, and 24 point fonts are provided for each typeface and display resolution).

-The standard point size of the system default font is changed (from 18 point to 12 point).

-Switching to a different system default font is now supported (to support the old applications which have dependencies on fixed pitch fonts).

-Switching VIO fonts (for example, switching between MINCHO and GOTHIC) is supported.

�DBCS character handling

-More logical handling of MBCS character strings in the PM display driver is supported. (The handling of MBCS characters results in the handling of SBCS proportional fonts by the font manager.)

�Font Manager is supported. (The part that handles DBCS is separated from the PM display driver and becomes one component.) It handles:

-Management of the font segments for both SBCS and DBCS.

-Management of the font cache.

-Management of the font drivers.

Font drivers are required to support EFDI (Extended Font Drivers Interface) Version 3.

PM Display Driver Fonts

In PM, there are basically two kinds of fonts-raster fonts and outline fonts. Outline fonts are processed by the graphics engine (GRE) using the Intelligent Font Interface (IFI). The images of DBCS raster fonts are managed by the PM device font drivers. These font drivers are managed by the device driver font manager (PMNLSFM.DLL). A PM display driver can process DBCS characters by communicating with the font manager. The font manager was included in PM display drivers to process fonts in versions prior to OS/2 2.0. The following is a description of the relationship between the PM display driver and the font manager.

PM Display Driver and Font Manager Interface

There is no initialization interface between the PM display driver and the font manager. When the PM display driver loads the font manager (using DosLoadModule), the initialization routine runs automatically in the font manager. At initialization the font manager loads the system default fonts. When the PM display driver gets the request to load/unload the font driver from the application, the PM display driver calls the font manager using the load/unload font drivers requests.

To call the font manager, the PM display driver has to get the address of the dispatch table using DosGetProcAddr and then use the function addresses provided in this table. Refer to Device Driver Font Manager Interfacefor details on this process.

Glyphs

The following section gives an overview of managing the DBCS font environment by using the universal glyph list (UGL) concept.

The glyph codes are defined in the chapter titled Glyph Codes.

UGL Font Resources

PM worldwide version assumes that all countries can manage the font environment by using the UGL (universal glyph list) concept. To implement this concept in a DBCS environment, a DBCS glyph index and UGL MBCS font resources are defined, which consists of 383 SBCS characters and all of the DBCS characters. It is the same as the worldwide versions of DBCS country- unique SBCS characters like KATAKANA. PM already has UGL SBCS font resources, which include 383 characters (for example, Courier, Roman, Swiss ).

DBCS/PM implements multiple code page fonts using glyph lists of 383 SBCS characters and DBCS glyphs. DBCS glyph lists extend the glyph set of 'PM383 ' to support the DBCS character set. DBCS glyph list names are defined as follows.

�PMJPN-Japanese glyph base

�PMKOR-Korean glyph base

�PMCHT-Taiwan glyph base
The following figure shows the PM font resources. [Artwork not shown]

PM Device Font Drivers

The PM device font driver is the 16-bit DLL that supplies SBCS and DBCS fonts to a PM display driver. The IBM Developer Connection Device Driver Kit for OS/2includes source code for the following font drivers:

�PMNLSFD1.FDR-MINCHO System Font Driver

�PMNLSFD2.FDR-MINCHO Draft Font Driver

�PS55DM28.FDR-MINCHO 28-dot Font Driver

�PS55DM32.FDR-MINCHO 32-dot Font Driver

�PS55DM36.FDR-MINCHO 36-dot Font Driver

�PMNLSFD3.FDR-GOTHIC System Font Driver

�PS55DG28.FDR-GOTHIC 28-dot Font Driver

�PS55DG32 FDR-GOTHIC 32-dot Font Driver

�PS55DG36.FDR-GOTHIC 36-dot Font Driver

Refer to Device Driver Font Manager Interfacefor details of the interface to the font drivers.

Gaiji Fonts Support

Gaiji means the font image that the user defines. Sometimes it is referred to as "User Fonts" or "User Defined Fonts."

The Gaiji font support in the PM display driver is actually handled by the font drivers. This is because it is easy to make the font typeface correspond to the Gaiji font resource in the font driver. The font driver has information on handling Gaiji fonts.

The font driver provides the following general functions:

�Returning SBCS and DBCS font metrics information

�Supplying SBCS font images

�Supplying DBCS font images excluding Gaiji

�Supplying DBCS Gaiji font images

By expanding the font driver's functions, one PM font can have multiple font data resources. Since Gaiji support is handled by the font driver, it picks up these expanded functions. In OS/2 2.0, the font driver returns the Gaiji font using the following rule: The standard Gaiji data is Gaiji fonts resources for the system default font in OS/2 fullscreen mode (16-dot and 24-dot fonts).

Gaiji font data is handled as follows:

�If there is private Gaiji font data, the font driver returns private Gaiji font data.

�If there is a standard same-size Gaiji font data, the font driver returns standard Gaiji font data.

�If there is standard different-size font data, the font driver returns standard Gaiji font data after scaling.

�If there is no Gaiji font data, the font driver returns the default character (double byte space character).

Device Driver Font Manager Interface

This section provides:

�An overview of font management

�Programming information on the PM display driver, the device driver font manager, and DBCS device font drivers.

�Descriptions of the programming interfaces and functions

Overview

The DBCS device font is the font that was originally provided by the font driver and managed by the PM display driver. The device driver font manager provides a basic function set to load and manage those DBCS device fonts.

Once a font is loaded, there are no differences between the engine font and the DBCS device font. If the function request is for a DBCS device font, the graphics engine also makes queries for details to the display device driver.

The following figure shows how the PM font management mechanism works with the device driver font manager: The following figure shows the PM font management mechanism. [Artwork not shown]

Programming Information

The following sections contain DBCS-related information about the PM display driver, the device driver font manager, and the device font drivers .

PM Display Driver

The PM display driver no longer has any DBCS device fonts. All of the DBCS device fonts are provided by the font drivers and supplied to the PM display driver by the font manager.

The PM display driver needs to handle:

�Notification to the engine to handle device font management on the device driver side. (This is not true for SBCS drivers.)

�Font manager initialization at startup time

�Default font selection for GPI and VIO fonts

�Font manager invocation according to the PDI (Presentation Driver Interface) function called

�SBCS device fonts (system proportional fonts) management

Additionally, the display device driver should include the following functions:

�Text query functions (such as TextBox, CharPositions, and WidthTable functions, which are not included in SBCS drivers)

�Text parsing according to the code page to use (the parser must call the font manager to construct a valid fontseg when the string includes DBCS code points)

The following functions are no longer needed:

�Loading and unloading DBCS device font drivers

�Creating and destroying DBCS logical fonts. (These functions are handled by the font manager.)

�DBCS handling in text output routine. (The fontseg passed from the font manager is always in the form of SBCS proportional.)

Device Driver Font Manager

The font manager pulls the requested character image from the font driver, caches the image locally, and constructs the SBCS proportional fontseg for the display device driver. The font index for DBCS characters is assigned in the reserved area of the glyph list index space (256 indexes are reserved). The list of font indexes (virtual font indexes) translated by the font manager is then returned to the display device driver.

DBCS Device Font Drivers

Because the font manager requires both the SBCS and DBCS portions of the DBCS device fonts, the font driver must provide both SBCS and DBCS characters for the font.

The DBCS-only font drivers are no longer supported by the font manager for system font purposes.

Initialization

The DBCS device fonts for display device drivers are provided by DBCS font drivers through the device driver font manager. Any DBCS-unique font resources are not bound in the display device driver in resource form.

The system font drivers for system fonts are loaded at initialization time by the font manager. The other optional font drivers can be registered and loaded by the user with WinDBCS APIs. The font drivers to be loaded are described in the OS2.INI profile as follows:

System Font Drivers

ApplicationName: PMNLSFNT

KeyName: font_driver_filename#1

String fully_qualified_pathname#1

KeyName: font_driver_filename#2

String: fully_qualified_pathname#2

Optional Public Font Drivers

ApplicationName: PMNLSFNT_FD

KeyName: font_driver_filename#1

String fully_qualified_pathname#1

KeyName: font_driver_filename#2

String: fully_qualified_pathname#2

The default settings for system font drivers are:

ApplicationName: PMNLSFNT

KeyName: PMNLSFD1

String C:\OS2\DLL\PMNLSFD1.FDR

Note that the device driver font manager supports only font drivers that provide both SBCS and DBCS font resources.

FMDISPATCH

This is the exported address that points to the function dispatch table of the font manager APIs.

             DispatchTable

             typedef struct _FMDISPATCH {
                 LONG (FAR PASCAL*)()    FmQueryFonts;
                 LONG (FAR PASCAL*)()    FmOpenFont;
                 LONG (FAR PASCAL*)()    FmCloseFont;
                 LONG (FAR PASCAL*)()    FmQueryCharAttr;
                 LONG (FAR PASCAL*)()    FmCharStr;
                 LONG (FAR PASCAL*)()    FmMapCharGlyph;
                 LONG (FAR PASCAL*)()    FmLoadFontDriver;
                 LONG (FAR PASCAL*)()    FmUnloadFontDriver;
                 LONG (FAR PASCAL*)()    FmFlushCache;
             } FMDISPATCH;

Remarks

This entry point is exported because the ordinal linking method to the font manager APIs is by DosloadModule / DosGetProcAddr. This entry saves runtime linking operation steps. Do not modify the table content.

Font Manager Functions

This section covers the font manager functions that are pointed to from the dispatch table, FMDISPATCH. They are presented in alphabetic order.

�FmCharStr-prepares the font segment for a given list of glyph list indexes

�FmCloseFont-notifies the font manager that the font will not be used again until another FmOpenFont is issued for this font

�FmFlushCache-flushes the cache for a specified font

�FmLoadFontDriver-loads the specified font driver

�FmMapCharGlyph-converts the list of code points into glyph list indexes

�FmOpenFont-searches for and returns the matching font, using specified font attributes

�FmQueryCharAttr-returns the font for the specified glyph list index

�FmQueryFonts-returns an array of currently loaded font information that belongs to the set specified

�FmUnloadFontDriver-unloads the specified font driver

FmCharStr

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL                                       |
|                                                          |
|    FmCharStr (hfm, flOptions, pIndex, count)             |
|                                                          |
\----------------------------------------------------------/

Description: This function prepares the font segment for a given list of glyph list indexes. After that, the font segment will be the same as an SBCS proportional PM font. This is a privileged interface only for a display device driver.

hfm(HFM) (in) The font handle returned by FmOpenFont

flOptions(BIT32) (in) Option flags

�FM_WITH_FONT-Updates glyph list indexes and font definitions. The font images are not constructed.

�FM_WITHOUT_FONT-Updates glyph list indexes and font definitions. The font images are also loaded and constructed.

count(LONG) (in) Count of indexes. Must be less than or equal to 256. When the font is FM_CACHE_FONT, the length is limited by cbCachein the FMFONTINFO structure, returned by FmOpenFont and FmQueryFonts.

RETURN (LONG) Return Codes

�FM_ERROR

�FM_SUCCESS

Remarks The purpose of this function is to improve display device driver performance. The display device driver has a privilege level that can use the font segment as a cache without copying its contents into the data area locally allocated in the display device driver.

The Font Manager replaces DBCS glyph indexes (and SBCS indexes when FM_ CACHE_FONT is selected) by dynamically defining new SBCS glyph list indexes . Also DBCS font images at the offset address where the new SBCS glyph list index points must be prepared.

After that, the display device driver can treat all of the font images as PM font SBCS proportional characters.

FmCloseFont

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FmCloseFont (hfm)                     |
|                                                          |
\----------------------------------------------------------/

Description: This function notifies the font manager that the font will no longer be used until FmOpenFont is issued for this font.

hfm(HFM) (in) The font handle returned by FmOpenFont

RETURN (LONG) Return Codes

�FM_ERROR

�FM_SUCCESS

FmFlushCache

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FmFlushCache (hfm, index)             |
|                                                          |
\----------------------------------------------------------/

Description: This function flushes the cache for a specified font.

hfm (HFM) (in) The font handle returned by FmOpenFont

index (ULONG) (in) Font glyph list index or -1

�Glyph index Flush cache for specified code point

�-1 Flush cache for all code points

RETURN (LONG) Return Codes

�FM_ERROR

�FM_SUCCESS

FmLoadFontDriver

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL                                       |
|                                                          |
|    FmLoadFontDriver (flOptions, szFontDriver)            |
|                                                          |
\----------------------------------------------------------/

Description: This function loads the specified font driver.

flOptions (BIT32) (in) Option flags

�FM_PUBLIC loads the font driver as public

�FM_PRIVATE loads the font driver as private

szFontDriver (PSZ) (in) The full path name of the font driver. The maximum length is 128 bytes.

RETURN (LONG) Return Codes

�FM_ERROR

�FM_SUCCESS

FmMapCharGlyph

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL                                       |
|                                                          |
|    FmMapCharGlyph (hfm, codepage, pStr, pIndex, strlen)  |
|                                                          |
\----------------------------------------------------------/

Description: This function converts the list of code points into glyph list indexes. It is an optional function because the device driver can do it by itself.

hfm(HFM) (in) The font handle returned by FmOpenFont

codepage (LONG) (in) The code page of the character string

pStr (PBYTE) (in) The address of the character string

pIndex (PINDEX) (in/out) The address of the buffer to receive the list of glyph list indexes that was converted. The buffer length is at least two times longer than the string length. This is because the 1-byte SBCS code points are converted to the word glyph indexes.

strlen (LONG) (in) The character string length in bytes.

RETURN (LONG) Return Codes

�FM_ERROR

�FM_SUCCESS

FmOpenFont

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FmOpenFont (pfat, pfmFont)            |
|                                                          |
\----------------------------------------------------------/

Description: This function searches for and returns the matching font using specified font attributes, such as facename, average width, and maximum height.

pfat(PFATTR) (in) The address of the font attributes. The font attributes structure is the same structure that is passed by Gpi/VioCreateLogFont.

             typedef struct _FATTRS  {
                 USHORT  usRecordLength;            /* length of record        */
                 USHORT  fsSelection;               /* selection indicator     */
                 LONG    lMatch;                    /* match identifier        */
                 CHAR    szFacename[FACESIZE];      /* typeface name           */
                 USHORT  idRegistry;                /* registry identifier     */
                 USHORT  usCodePage;                /* code page               */
                 LONG    lMaxBaselineExt;           /* maximum baseline extent */
                 LONG    lAveCharWidth;             /* average character width */
                 USHORT  fsType;                    /* type indicators         */
                 USHORT  fsFontUse;                 /* font use indicators     */
             } FATTRS;

pfmFont(PFMFONTINFO) (in/out) The address of the buffer to receive the matching font information. The font handle is saved in the hfmfield, and the handle value is always the same as pFont (font segment address).

RETURN (LONG) Return Codes

�FM_ERROR

�FM_SUCCESS

Remarks All of the size values returned in font metrics are in device coordinates.

FmQueryCharAttr

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FmQueryCharAttr (hfm, index, pfmData) |
|                                                          |
\----------------------------------------------------------/

Description: This function returns the font for the specified glyph list index.

hfm(HFM) (in) The font handle returned by FmOpenFont

index Font glyph list index

pfmData(PFMQUERYDATA) (in/out) The address of query data. There are three types of query that should be specified in lQuery.

�FM_FONT_SIZE-Queries how many bytes the device driver has to allocate to receive the font image and font size. For example, the device driver can get cell width, cell height, and cbLen for a fixed-pitch font.

�FM_FONT_IMAGE-Requests font image. The device driver has to allocate the buffer (pointed to by pBuffer) for a font.

�FM_FONT_NULL-Requests the null character image. The device driver has to allocate the buffer (pointed to by pBuffer) for a font.

             typedef struct _FMQUERYDATA {
                 BIT32   lQuery;           /* query type                      */
                 LONG    sizl_cx;          /* cell width                      */
                 LONG    sizl_cy;          /* cell height                     */
                 LONG    a_space;          /* A space                         */
                 LONG    b_space;          /* B space                         */
                 LONG    c_space;          /* C space                         */
                 ULONG   cbLen;            /* buffer length for font image    */
                 PBYTE   pBuffer;          /* address of font image buffer    */
             } FMQUERYDATA

RETURN (LONG) Return Codes

• FM_ERROR
• FM_SUCCESS

FmQueryFonts

Description: This function returns an array of currently loaded font information that belongs to the set specified.

flOptions(BIT32) (in) Enumeration options

• FM_PUBLIC Enumerate public fonts
• FM_PRIVATE Enumerate private fonts

pfmFont(PFMFONTINFO) (in/out) The address of the buffer to receive an array of font information. If a NULL is specified for this parameter, the function returns the number of fonts currently loaded by the font manager. The returned font segments always have PM font compatible font metrics. The accessibility of font definitions is dependent on the font segment type returned in flType.

FM_PM_FONT-Indicates that the returned font segment is SBCS/PM font compatible. When the font is opened by FmOpenFont, the device driver can read both font metrics and SBCS font definitions directly. The DBCS font definitions are valid just after the font segment is validated with specified glyph indexes by FmCharstr.

FM_CACHE_FONT-Indicates that the font definitions are not resident in this segment. The font definitions are valid just after the font segment is validated with specified glyph indexes by FmCharStr.

The cbCache shows the number of fonts that can be loaded in this font segment at once. This value limits the length of the glyph list index array to be passed to the FmCharStr call. Note that this field is valid only when the font is FM_CACHE_FONT.

             typedef struct _FMFONTINFO {
                 HFM     hfm;                /* font manager font handle        */
                 PBYTE   pFont;              /* pointer to the font segment     */
                 ULONG   ulLen;              /* length of font segment          */
                 BIT32   flType;             /* type flag                       */
                 CHAR    szGlyphlist[16];    /* glyph list name                 */
                 LONG    lMatch;             /* match identifier                */
                 USHORT  cbCache;            /* cache size (FM_CACHE_FONT only) */
             } FMFONTINFO;

hfm (HFM) (in) The font handle returned by FmOpenFont. This parameter is used to get the specified font information. When this parameter is specified, it is not necessary to fill the startFontand reqFontparameters . The flOptionsparameter should also be specified in this case.

startFont (LONG) (in) Starting number of the font that the device driver requests. It begins at 1.

reqFont (LONG) (in) The number of fonts that the device driver requests.

RETURN (LONG) The number of fonts (if NULL specified for pfmFont) or return codes:

�FM_ERROR

�FM_SUCCESS

Remarks All of the size values returned in font metrics are in device coordinates. The device driver must select GPI/VIO default fonts from the returned list of fonts at initialization time.

FmUnloadFontDriver

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL                                       |
|                                                          |
|    FmLoadFontDriver (flOptions, szFontDriver)            |
|                                                          |
\----------------------------------------------------------/

Description: This function unloads the specified font driver.

flOptions (BIT32) (in) Option flags

�FM_PUBLIC loads the font driver as public

�FM_PRIVATE loads the font driver as private

szFontDriver (PSZ) (in) The full path name of the font driver. The maximum length is 128 bytes.

RETURN (LONG) Return Codes

�FM_ERROR

�FM_SUCCESS

PM Device Font Driver Interface

A PM device font driver (hereafter referred to as font driver) is a 16-bit ring 3 DLL that supplies DBCS/SBCS raster fonts to the font manager. A font driver expects to be called only from the font manager. The behavior of a font driver is unpredictable when it is called from other modules. Extended Font Driver Interface (EFDI) version 3 is defined as the interface between font drivers and the font manager. EFDI version 1 was used for OS/2 J1.1 and version 2 was used for OS/2 J1.2 and J1.3.

Font drivers are initialized as DLLs at system initialization by the font manager. The entry point name is DynaLinkInit (dllinit.asm).

FONT_ENABLE is the only call gate in the font driver that communicates with the font manager. The font manager loads the font drivers with DosLoadModule and gets each FONT_ENABLE address with DosGetProcAddr.

The following is the general sequence of calling the font drivers.

   ...

   /* Load a font driver. */

   Num = FONT_ENABLE (DBE_FD_OPEN,,,);

   ...

   /* Get information for each font.  */

   for (i = 1; i < Num; i++) {

      ...

      FONT_ENABLE (DBE_FD_GET_INFO,,,i);

      ...

   }

   /* Call each function, specifying the ResourceID for requested fonts */

   ...

   FONT_ENABLE (DBE_FD_GET_INFO,,,);

   ...

   FONT_ENABLE (DBE_FD_QUERY,,,);

   ...

   FONT_ENABLE (DBE_FD_READ,,,);

   ...

   /* Unload a font driver  */

   FONT_ENABLE (DBE_FD_CLOSE,,,);

FONT_ENABLE Function Call Description

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
\----------------------------------------------------------/

Description: FONT_ENABLE is the call gate in the font driver that communicates with the font manager

ul1 (ULONG) (in) The first input parameter. The meaning of this parameter will change depending on ulFunction.

ul2 (ULONG) (in) The second input parameter. The meaning of this parameter will change depending on ulFunction.

ul3 (ULONG) (in) The third input parameter. The meaning of this parameter will change depending on ulFunction.

ulFunction (ULONG) (in) Function name.

�DBE_FD_CLOSE-Closes the font driver

�DBE_FD_GET_INFO-Returns information about the fonts specified

�DBE_FD_GET_VERSION-Returns the version of the font driver

�DBE_FD_OPEN-Opens the font driver

�DBE_FD_QUERY-Returns information about the cell of the font specified

�DBE_FD_READ-Returns the image of the font specified

�DBE_FD_WRITE-Renews the image of the font specified

RETURN (ULONG) Return Codes

�DBE_FD_NORMAL-Success

�DBE_FD_NO_MORE_FONT-No more fonts to return

�DBE_FD_ERROR-Error

DBE_FD_CLOSE

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
\----------------------------------------------------------/

Description: The DBE_FD_CLOSE function closes the font driver.

ul1 (ULONG) (in) It is not used and will be ignored.

ul2 (ULONG) (in) It is not used and will be ignored.

ul3 (ULONG) (in) It is not used and will be ignored.

ulFunction (ULONG) (in) Function name-DBE_FD_CLOSE

RETURN (ULONG) Return codes

�DBE_FD_NORMAL-Success

�DBE_FD_ERROR-Error

DBE_FD_GET_INFO

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
\----------------------------------------------------------/

Description: The DBE_FD_GET_INFO function returns the attributes of the specified fonts.

ul1 (ULONG) (in) Font resource ID.

ul2 (ULONG) (in/out) Pointer(PFONT_INFO).

The structure name FONT_INFO is defined in the H_DBCS\OS2NLSFD.H file as follows:

                       typedef struct _FONT_INFO {
                           PFOCAFONT font_info_ptr;
                           ULONG     option;
                       } FONT_INFO, FAR *PFONT_INFO

_FONT_INFO Struct Values of option

         #define DBE_FD_FONT_DEFAULT    0x00000000
         #define DBE_FD_FONT_NO_CACHE   0x00000004

ul3 (ULONG) (in) It is not used and will be ignored.

ulFunction (ULONG) (in) Function name-DBE_FD_GET_INFO

RETURN (ULONG) Return codes

�DBE_FD_NORMAL-Success

�DBE_NO_MORE_FONT-No font to return

�DBE_FD_ERROR-Error

DBE_FD_GET_VERSION

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
\----------------------------------------------------------/

Description: The DBE_FD_GET_VERSION function returns the version of the font driver.

ul1 (ULONG) (in) It is not used and will be ignored.

ul2 (ULONG) (in/out) Pointer(PFONT_DRIVER_VERSION)

The structure name FONT_DRIVER_VERSION is defined in H_DBCS\OS2NLSFD.H file as follows:

                       typedef struct _FONT_DRIVER_VERSION {
                           ULONG     version_number;
                           PFD_DESC  fd_desc;
                       } FONT_DRIVER_VERSION, FAR *PFONT_DRIVER_VERSION;

The FD_DESC structure is defined in H_DBCS\OS2NLS.H as follows:

                       typedef struct _FD_DESC {
                           ULONG     flType;
                           CHAR      str64Desc[64];
                       } FD_DESC, FAR *PFD_DESC;

ul3 (ULONG) (in) It is not used and will be ignored.

ulFunction (ULONG) (in) Function name-DBE_FD_GET_VERSION

RETURN (ULONG) Return codes

�DBE_FD_NORMAL-Success

�DBE_FD_ERROR-Error

DBE_FD_OPEN

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
\----------------------------------------------------------/

Description: The DBE_FD_OPEN function opens the font driver.

ul1 (ULONG) (in) It is not used and will be ignored.

ul2 (ULONG) (in) It is not used and will be ignored.

ul3 (ULONG) (in) It is not used and will be ignored.

ulFunction (ULONG) (in) Function name-DBE_FD_OPEN

RETURN (ULONG) The number of fonts that can be used.

DBE_FD_QUERY

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
\----------------------------------------------------------/

Description: The DBE_FD_QUERY function returns information about the font cell specified by the glyph index.

ul1 (ULONG) (in) Font resource ID

ul2 (ULONG) (in/out) Pointer(PFONT_QUERY)

The structure name FONT_QUERY is defined in the H_DBCS\OS2NLSFD.H file as follows:

             typedef struct _FONT_QUERY {
                 ULONG     QueryID;
                 ULONG     xCellWidth;
                 ULONG     yCellHeight;
                 ULONG     xCellA;
                 ULONG     xCellB;
                 ULONG     xCellC;
                 ULONG     date_length;
             } FONT_QUERY, FAR *PFONT_QUERY;

The values of QueryID are defined as follows:

                       #define DBE_FD_QUERY_WIDTHHEIGHT   0x00000001L
                       #define DBE_FD_QUERY_ABC           0x00000002L
                       #define DBE_FD_QUERY_LENGTH        0x00000004L

ul3 (ULONG) (in) Glyph index.

ulFunction (ULONG) (in) Function name-DBE_FD_QUERY

RETURN (ULONG) Return codes

�DBE_FD_NORMAL-Success

�DBE_FD_ERROR-Error

DBE_FD_READ

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
\----------------------------------------------------------/

Description: The DBE_FD_READ function returns the font specified by the glyph index.

ul1 (ULONG) (in) Font resource ID. This value should be from 1 to the value returned by DBE_FD_OPEN.

ul2 (ULONG) (in/out) Pointer(PFONT_MAP).

The structure name FONT_MAP is defined in the H_DBCS\OS2NLSFD.H file as follows:

                       typedef struct _FONT_MAP {
                           USHORT    buffer_length;
                           PUSHORT   buffer_ptr;
                           USHORT    reserved1;
                           PVOID     reserved2;
                           ULONG     input_width;
                           ULONG     input_height;
                           ULONG     output_width;
                           ULONG     output_height;
                       } FONT_MAP, FAR *PFONT_MAP

ul3 (ULONG) (in) Glyph index.

�For SBCS, the character code should be in the low byte, and 0x00 should be in the high byte.

�For DBCS, the leading byte should be in the low byte, and the trailing byte should be in the high byte.

ulFunction (ULONG) (in) Function name-DBE_FD_READ

RETURN (ULONG) Return codes

�DBE_FD_NORMAL-Success

�DBE_FD_ERROR-Error

DBE_FD_WRITE

/--- FUNCTION ---------------------------------------------\
|                                                          |
|    LONG FAR PASCAL FONT_ENABLE                           |
|                                                          |
|    (ULONG ul1, ULONG ul2, ULONG ul3, ulFunction)         |
|                                                          |
\----------------------------------------------------------/

Description: The DBE_FD_WRITE function renews the image of the font specified by the glyph index.

ul1 (ULONG) (in) Font resource ID.

ul2 (ULONG) (in/out) Pointer(PFONT_MAP).

ul3 (ULONG) (in) Glyph index.

ulFunction (ULONG) (in) Function name-DBE_FD_WRITE

RETURN (ULONG) Return codes

�DBE_FD_NORMAL-Success

�DBE_FD_ERROR-Error

Using the Accelerator Function Between PM and WIN-OS2

When both your PM display driver and your WIN-OS/2 seamless display driver use the graphic accelerator function, you need a proper semaphore control.

The supplement file HWS2S.BLT is the sample for BitBlt handling using hardware assist. HWS2S.BLT is in the \DDK_x86\SRC_DBCS\SEAMLESS directory. The WIN-OS2 display driver should wait until the RAM semaphore pmdd_screen_ busy is not zero before doing BitBlt handling. (The pmdd_screen_busy sempahore is common to the PM display driver and the WIN-OS2 display driver .) After BitBlt handling completes, the hardware-busy flag is set to let the PM display driver use the hardware assist.

It is possible to make a semaphore common to the PM driver and the WIN-OS/2 driver as shown in the sample that follows, where the pmdd_screen_busy semaphore is in the structure PMDD_IO in IPC.INC for the WIN-OS2 driver and in the structure _SM_WINDRV for the PM driver. The sample shows "pmdd_ screen_busy" in a shared RAM area between the PM driver and the WIN-OS2 driver.

Shared RAM Area of PM side (in \DDK_x86\SRC_DBCS\VGA32\VGAINC\SEAMLESS.INC file):

 _SM_WINDRV      struct
     signature           db  "VG01" ; string to synchronize interface to VDM
     exclude             dd  ?      ; pointer to cursor far_exclude() function
     .
     .
     .
     ulLastPalUpdate     dd  ?      ; time stamp of last palette update
     pHWPalette          dd  ?      ; 16:16 ptr to copy of PM driver
HWPalette

     pmdd_screen_busy    dd  ?      ; 16:16 ptr of screen_busy.
<==SEMAPHORE      .
     .
 _SM_WINDRV      ends

Shared RAM Area of WIN-OS2 side (in IPC.INC file):

 PMDD_IO  struc
     signature           dd  ?       ; 4bytes to synch interface to PMDD
     pfexclude           dd  ?       ; ptr to PMDD's exclude() function
     .
     .
     .
     ulLastPalUpdate     dd  ?       ; time stamp of last palette update
     pHWPalette          dd  ?       ; 16:16 ptr to copy of PM's HWPalette

     pmdd_screen_busy    dd  ?       ; 16:16 ptr of screen_busy. <==SEMAPHORE
     .
 PMDD_IO  ends

By using the pmdd_screen_busy semaphore field, you can implement exclusive access of the accelerator function as follows:

       .
       .
       .
       mov     ax,DataBASE
       mov     ds,ax
       assumes ds,Data
       lds     si,init_struct.pmdd_io
       lds     si, [si].pmdd_screen_busy
       xor     ax, ax
@@:
       xchg    al, [si]         ; Get the access right.
       or      al, al                     ; Check
       jz      @B                         ; If 1 then OK, else loop.
       .
       .
       .
     ********************************
     * Access Accelerator Function  *
     ********************************
       .
       .
       .
       mov     byte ptr [si], 1 ; Release the access right.

The Physical Device Driver-SCREENDD

To build SCREEN01.SYS and SCREEN02.SYS, run NMAKE.EXE in the DDK_x86\SRC_ DBCS\ DEV\SCREENDD directory.

All source code is included in the IBM Developer Connection Device Driver Kit for OS/2, so modifications to any code can be done, if necessary.

MEMHELP.ASM and DDK_x86\INC_DBCS\MEMHELP.INC are the files newly added for DBCS support.

To support BVHVGA2.DLL, FNTCALLS.DLL and VFNTV.SYS, the new IOCtl and interface to the virtual device driver are added. The following section describes the interfaces added to SCREENDD.

Modifications to SCREENDD for IBM Japan

The following are the major modifications done for DBCS support. In the future, the code may be changed without notice.

�A new IOCtl is added to allocate a BVHVGA2.DLL shadow buffer and DBCS font buffer in the global memory. There is no API that allocates the ring 3 global memory from the ring 3 program. By using this IOCtl, it is possible to get global memory for a ring 3 program.

�The interface that maps the local memory to global and releases the global memory called from VDD are added. They are used for sharing the DBCS font resource between VFNTV.SYS and FNTCALLS.DLL.

�The new IOCtl is added to access the ROM font in the DOS/V machine from ring 3 FNTCALLS.DLL.

IOCtl Added to SCREENDD

The following functions in category 03h IOCtl are added. In the future, the number and function of this IOCtl may be changed.

�function 7Eh-Allocate video buffer

�function 7Fh-Get address to ROM font

For information on these IOCtl functions, see OS/2 Physical Device Driver Reference.

Interface to VDD Added to SCREENDD

For VFNTV.SYS, the following interface is added. In the future, the number and function of this interface may be changed.

�Function 0h Register VDD entry point

�Function 1h Map local memory to global

�Function 2h Release global memory

Register VDD Entry Point (function 00H)

The "success" return code (AX=1) will always be returned.

Map Local Memory to Global (function 01H)

Parameter 1 (Input):

    /--------------------------------------\
    |Field                        Length   |
    |--------------------------------------|
    |Linear address to be mapped  DWORD    |
    |--------------------------------------|
    |Length of memory             DWORD    |
    \--------------------------------------/

Parameter 2 (Output):

    /--------------------------------------\
    |Field                        Length   |
    |--------------------------------------|
    |Linear address mapped        DWORD    |
    \--------------------------------------/

Return: AX = 1 Success

AX = 0 Error

Release Global Memory (function 02H)

Parameter 1 (Input):

    /--------------------------------------\
    |Field                          Length |
    |--------------------------------------|
    |Linear address to be released  DWORD  |
    \--------------------------------------/

Parameter 2 (Output): None

Return: AX = 1 Success

AX = 0 Error

Base Video Subsystem

The following sections describe changes to the base video subsystem for Japanese support.

Base Video Handler

The Base Video Handler controls the video hardware in OS/2 protect mode. It means that all applications that set the video mode call BVH indirectlty. BVH consists of multiple DLLs.

When the display adapter is VGA, the BVH consists of BVHVGA.DLL and BVHVGA2 .DLL. BVHVGA2.DLL handles the DBCS fonts and BVHVGA.DLL handles the other functions. BVHVGA2I.DLL is the mini BVH used only at system installation.

BVHSVGA.DLL is the BVH for super VGA and is compatible with many kinds of the super VGA chip sets.

BVHWNDW.DLL is the BVH for windowed VIO session.

For more details see OS/2 Physical Device Driver Reference.

Virtual Video Device Driver

The virtual video device driver (Video VDD) handles the virtualization of the video hardware and INT 10H BIOS function for each DOS session.

VVGA.SYS is the video VDD for VGA.

VSVGA.SYS is the video VDD for super VGA.

V8514A.SYS is the video VDD for 8514/A.

SVGA.EXE is the utility program executed from a DOS full screen session. It supplies the mode data, trap register, lock and unlock data to the BVH and VSVGA.SYS.

VVGA.SYS and VSVGA.SYS are enabled for Japanese DBCS and DOS-V support. The combined source can generate both SBCS and DBCS versions. For more details, see Using OS/2 J 2.0. V8514A.SYS is not enabled for Japanese support. For SVGA.EXE, it does not need to be enabled. The DBCS source files contain no adapter-specific references. Enabling new adapters requires changes only to an adapter-specific file such as VVS3.C.

SVGA.EXE sets all possible video modes for BIOS in the video adapter and writes the value of the registers into the \boot drive\OS2\SVGADATA.PMI file.

The statement is as follows:

  SVGA ON|OFF

ON means creating \OS2\SVGADATA.PMI and enabling SVGA support, and OFF means deleting SVGADATA.PMI. When SVGA ON is executed from the DOS window, BIOS cannot set the appropriate SVGA mode because of the virtualization being done by the system. Therefore SVGA.EXE should be run in DOS full screen mode.

The DOS session needs the SVGADATA.PMI file. When the first DOS session is created, the system reads the SVGADATA.PMI file. The existence of this file means that SVGA support is enabled by the SVGA ON command.

SVGADATA.PMI includes the following information.

�The current SVGA adapter chip set

�SVGA mode that the adapter can set

The following modes are supported:

-640 x 480 / 256 colors

-800 x 600 / 16 colors

-800 x 600 / 256 colors

-1024 x 768 / 16 colors

-1024 x 768 / 256 colors

-132 x 25 text (See Note)

-132 x 43 or 44 text (See Note)

Note:It is text mode on an SBCS code page. Text mode on a DBCS code page will be done by simulation in graphics mode.

�The values of the video register for each mode. This data will be used for the save and restore of the registers when the session is switched to a different SVGA mode.

For more the details about video VDD, see OS/2 Virtual Device Driver Referenceand OS/2 Version 2.0 Volume 2: DOS and Windows Environment. For more details about the Japanese virtual device drivers and the DOS session window manager, see Using OS/2 J2.0.

BVHWNDW.DLL

BVHWNDW.DLL is the module called from BVSCALLS.DLL when a VioXXX API is called in AVIO and the window session (OS/2 Window). It emulates the Vio API call to the Gpi API call on the PM desktop.

Installing and Configuring Display Device Drivers

The OS/2 Display Driver Installation utility program (DSPINSTL.EXE) provides all the facilities to install and configure OS/2 display drivers. In addition, DSPINSTL installs and configures Presentation Manager (PM) display drivers. It also can install and configure WIN-OS/2 (both full- screen and windowed) display drivers and install base video service (VIO) drivers and DOS virtual device drivers (VDDs).

Display-driver installation and configuration is more complex than it is for standard device drivers. Typically, display-driver installation and configuration includes the following activities:

�Selecting the OS/2 display-driver characteristics

The user can specify the type and resolution of the display driver to be installed.

�Copying display driver-related files

The user can copy display driver-related files from source directories ( usually on diskettes) to target directories on the user's hard disk. (See Copying Display Driver-Related Files.)

�Updating the system configuration files

The user can update some of the OS/2 and WIN-OS/2 configuration files to prepare a new display driver for subsequent execution when the user's system is restarted. (See Updating System Configuration Files.)

These activities are described in detail in the following overview of display-driver installation and configuration.

Overview

In some ways, DSPINSTL is similar to the OS/2 Device Driver Installation utility program, DDINSTAL.EXE, but DSPINSTL contains some extensions specifically designed to simplify the steps the user must perform to install and configure OS/2 display drivers. Different types of OS/2 display drivers can have radically different installation and configuration requirements; therefore, DSPINSTL has a set of features that enables you to customize the installation process to meet the user's needs.

Selecting OS/2 Display-Driver Characteristics

The user must specify whether the display driver being installed will be used for a primary or secondary display adapter. The user must then specify the type of display driver to install, because many types of display- adapter hardware can support a number of different display drivers. For instance, Extended Graphics Array (XGA) display-adapter hardware can be operated using either a high-resolution XGA display driver or a lower- resolution standard display driver such as Video Graphics Array (VGA) or Enhanced Graphics Adapter (EGA).

Some display drivers can support more than one graphics resolution, so the user might have to specify the display resolution at which the driver is to be operated. Typically, display resolutions are specified by supplying the width and height of the display (in pels) and the maximum number of colors that can be displayed simultaneously.

The user's choices for display resolution often are governed by the type of video hardware attached to the user's system. For example, both the size and type of the user's display and the amount of video RAM on the display adapter affect which display resolutions will run.

Copying Display Driver-Related Files

Several factors can complicate the copying of display driver-related files from source directories to target directories. Display-driver files might be sufficiently large and numerous to fill more than one source diskette. This can easily occur when several display drivers, supporting different display resolutions, are bundled together on the same diskettes (along with their associated font and resource files).

To save space in the source directory, it might be desirable to use packed files. If so, however, the packed files must be unpacked when they are copied to the target directory. The display driver packager can specify file version checks to be made before the files are copied, because the checks can prevent the inadvertent replacement of updated display-driver files by older versions.

Updating System Configuration Files

After display driver-related files are copied to the user's system, the display-driver developer must update the different system configuration files to complete the installation. Frequently, the CONFIG.SYS and OS2.INI files must be updated to complete Presentation Manager display-driver installation, and the SYSTEM.INI and WIN.INI files must be updated to complete WIN-OS/2 display-driver installation. Depending on the driver being installed, other configuration files might also need updating.

DSPINSTL Installation Script Example

The installation of display drivers on OS/2 is done, in most cases, using IBM's display configuration tool DSPINSTL.EXE. When installing SVGA support , DSPINSTL.EXE calls a DOS program, SVGA.EXE, to create an SVGADATA.PMI file. The .PMI file is a data file containing all the information about the SVGA display adapter installed. DSPINSTL.EXE also uses SCREEN01.SYS for its detection; SVGA.EXE has some limited dependencies on SCREEN01.SYS as well. Because of these dependencies, installing BBS drivers is a two part process , as discussed below.

SVGA BBS Installations

Follow these steps to install BBS drivers:

�Installation Part 1

1.Replace both the base video and SVGA.EXE files.

2.Copy the .DSC file used by DSPINSTL.EXE to the \OS2\INSTALL directory.

3.Reboot the system.

You must reboot because you replaced the base video (SCREEN01.SYS and SCREEN02.SYS).

�Installation Part 2

1.After the reboot is completed, run DSPINSTL.EXE and select the correct display driver to install.

Installation will then proceed as normal.

2.When installation is completed, reboot again for the changes to take affect.

There is no standard way for IHVs to install Part 1 of the BBS installation process. Each vendor has their own command file that copies some files and tells the user to reboot and run DSPINSTL.EXE. In many cases, the video drivers that ship with the BBS diskette may work on OS/2 Warp, Version 3.0 only, not on OS/2 Version 2.1. In other words, it is currently difficult for vendors to install their drivers on different versions of OS/2.

There are two areas that need to be addressed:

1.Create a standard way to accomplish part 1 of the installation of video drivers.

2.Provide tools, such as a TESTVER.EXE and PRODUCT.EXE, along with a sample SETUP.CMD file for version-specific BBS installations.

The TESTVER program is used to test the version of the operating system installed. The PRODUCT program is used to inform the user what to do next at the end of part 1 of the BBS Installation process. PRODUCT is a PM program that brings up a dialog that can be customized by IHVs.

SETUP.CMD File Example

This example uses DSPINSTL.EXE to install part 1 of the BBS driver- installation process. The SETUP.CMD file is new. DSPINSTL.EXE was changed in OS/2 Warp, Version 3, to handle some new command-line parameters. As a result, DSPINSTL.EXE is now able to function more generically as an installation tool, not specific to display drivers.

The new command-line parameters in OS/2 Warp, Version 3, are case- insensitive and are as follows:

     /PD:<path\dsc file name>                       -  Primary .DSC file to install 
     /SD:<path\dsc file name>                       -  Secondary .DSC file to install 
     /RES:<resolution for display driver to default to>
     /u                                                         -  Run unattended 

Existing command-line parameters are case-insensitive and are as follows:

     /PK:<primary adapter type>
     /SK:<secondary adapter type>
     /S:<source path>
     /T:<target drive>
     /L1:<path to log file>

The sample SETUP.CMD file is shown below:

     Sample SETUP.CMD
     -------------------

     @if not exist echo.on ECHO OFF
     IF .%1. == .. GOTO USAGE
     IF .%2. == .. GOTO USAGE
     set src=%1
     set trg=%2
     set log=%trg%\os2\install\display.log
     set ver=3.0,2.11,2.1
     %src%\testver > %log%
     IF ERRORLEVEL 300 set dsc=%src%\v3.dsc&& GOTO VER_OK
     IF ERRORLEVEL 211 set dsc=%src%\pre_v3.dsc GOTO VER_OK
     IF ERRORLEVEL 210 set dsc=%src%\pre_v3.dsc GOTO VER_OK
     GOTO VER_NOT_OK
     :VER_OK
     set apath=%path%
     set  path=%src%;%path%
     if .%3. == .. set cid=&& goto skipcid
     set cid=/u
     :skipcid
     %src%\dspinstl.exe /s:%src% /t:%trg%\ /pd:%dsc% /l:%log% %cid%
     %src%\product.exe %src% %trg% %cid%
     set  path=%apath%
     GOTO END
     :VER_NOT_OK
     @ECHO This fixpack is intended for OS/2 versions %ver% only !
     @ECHO This fixpack is intended for OS/2 versions %ver% only ! >> %log%
     goto end
     :USAGE
     ECHO.
     ECHO Usage: %0 [SOURCE_PATH:] [BOOTDRIVE:] {[CID]}
     ECHO.
     ECHO Use the optional CID parameter for CID installs
     :END

As you can see from the sample SETUP.CMD, it is intended to be installed on OS/2 Warp, Version 3.0, and OS/2 Versions 2.11 and 2.1. When installing SETUP.CMD on OS/2 Warp, Version 3.0, use the V3.DSC file. When installing SETUP.CMD on OS/2 Versions 2.11 or 2.1, use PRE_V3.DSC file.

Examples of both V3.DSC and PRE_V3.DSC are shown below:

�V3.DSC Example

     V3.DSC
     ---------------
     * Title
     "V3 files"

     * Action routine DLL
     ""

     * Type key
     "OTHER"

     * # additional parameters specific to SVGA
     "0"

     * # of chain elements
     "1"

     ***********************
     * chain element = key, general prompt, diskette prompt, vol label, resolution
     ***********************
     "V3PREREQS"
     "Prerequisite files"
     "BBS Diskette 1"
     "WD2431 1"
     ""

�PRE_V3.DSC Example

     PRE_V3.DSC
     ----------
     * Title
     "Pre-V3 files"

     * Action routine DLL
     ""

     * Type key
     "OTHER"

     * # additional parameters specific to SVGA
     "0"

     * # of chain elements
     "1"

     ***********************
     * chain element = key, general prompt, diskette prompt, vol label, resolution
     ***********************
     "PREV3PREREQS"
     "Prerequisite files"
     "BBS Diskette 1"
     "WD2431 1"
     ""

DSPINSTL Architecture

DSPINSTL consists of the following major components:

�DSPINSTL Configuration File Interpreter

�Initial User Interface PM Panels

A set of standard Presentation Manager panels that serve as a basic front- end user interface. (See User Interface PM Panelsfor details.)

�Action Routine Interface

A function that provides the optional addition of custom-control logic. ( See Action Routine Interfacefor more information.)

�Service Functions

A set of standard service functions that can be called from within an action routine. (See DSPINSTL Service Functions.)

�Command Language PM Panels

A set of standard PM panels that act as the front end to the DSPINSTL Command Language Interpreter as described in Command Language PM Panels.

�Command Language Interpreter

The final stage of DSPINSTL, which executes the installation and configuration commands packed in the display-driver profile (DSP) files. ( See DSPINSTL Command Language Interpreterfor details.)

DSPINSTL Configuration File Interpreter

The DSPINSTL Configuration File Interpreter enables you to specify, within the configuration files, high-level knowledge that characterizes one or more display driver packages. The information contained in the display configuration (DSC) files determines the values of some of the fields in the set of standard PM panels provided. It also initializes a chain of data elements that subsequently will be passed to the DSPINSTL Command Language Interpreter that executes as the final stage of the DSPINSTL operation.

Display configuration files are identifiable by a file-name extension of ". DSC". The DSC files are the key to DSPINSTL's ability to act as a generalized installation tool that can install many different types of display drivers.

A set of display drivers can be packaged in any of the following ways:

�Writing them to a diskette
�Creating one or more display (DSP) files containing DSPINSTL installation and configuration commands
�Creating a configuration file entry in a DSC file summarizing the key points concerning that display driver package
DSC files must be placed either in the directory containing the DSPINSTL utility program or in a directory contained in the user's DPATH. DSPINSTL checks its own directory first; then, if it cannot find a DSC file, it searches the DPATH, stopping when it finds a directory containing one or more DSC files. DSPINSTL reads all the DSC files it finds into that directory.

A configuration file entry includes the following information:

�A title string identifying the driver in the initial DSPINSTL PM panels, " Primary Video Adapter" and "Secondary Video Adapter". These two panels enable the users to explicitly select which display drivers to install.

�The name of the Dynamic Link Library (DLL) module, if any, containing action routines specific to the installation of that display-driver package .

�A keyword string identifying whether the display drivers can handle a standard type of display adapter.

The following table lists the supported keyword strings:

/-------------------------------------------------------------\
|Type of Adapter               |Keyword String                |
|------------------------------+------------------------------|
|Color Graphics Adapter        |CGA                           |
|------------------------------+------------------------------|
|Enhanced Graphics Adapter     |EGA                           |
|------------------------------+------------------------------|
|Video Graphics Adapter        |VGA                           |
|------------------------------+------------------------------|
|Display adapter 8514/A        |8514                          |
|------------------------------+------------------------------|
|Extended graphics adapter     |XGA                           |
|------------------------------+------------------------------|
|Super Video Graphics Adapter  |SVGA                          |
\-------------------------------------------------------------/

These keyword strings enable DSPINSTL to create a logical association with a display driver as a default type. The association is used if the user accepts DSPINSTL's default selection in the "Video Display Configuration" PM panel (the initial DSPINSTL PM panel).

For example, the panel shows that the user's system has an 8514/A adapter as its primary display. If a DSC file entry contains a string of 8514, that file entry is chosen automatically if the user accepts the default choice by selecting the OKpush button, without checking either the primary display or secondary display check boxes.

If more than one DSC file entry contains standard-type strings of 8514, DSPINSTL displays a PM panel to permit the user to resolve the ambiguity. If the user checks one of the two check boxes to indicate the desire to override the default logic and explicitly choose a driver, the PM panel that follows includes list-box choices for all the entries in the DSC files that DSPINSTL reads.

�A default chain of data elements characterizing a sequence of installation and configuration steps that, in total, constitute the entire installation and configuration process. Each chain element can include the following data:

-A required default keyword string that triggers the interpretation of one or more DSP files in a given source directory.

-A required default prompt string, displayed in a PM panel, informing the user of the purpose of the next installation step. This prompt string helps the user decide which device or directory to point the utility program toward to accomplish that part of the installation.

-An optional default prompt string that tells the user which diskette to insert (assuming the next part of the installation is being performed from a diskette). This feature enables the display-driver packager to inform the user of the exact title that is written on a diskette.

-An optional diskette volume label that enables DSPINSTL to verify that the user has inserted the correct diskette.

-An optional display resolution string that can be used to display a default display resolution for installation. This string can be passed by an action routine to the Select_Video_Resolution service function.

Typically, there will be one data element in the chain for each diskette in the package. However, as the display-driver developer, you can use the data elements in the chain any way you want. For example, one data element might handle file copy commands, while the next might be used for configuration file updates.

The chain of data elements first is passed to the action routines; then, it is interpreted by the DSPINSTL Command Language Interpreter in the last part of the process. In this manner, you can create a default series of installation steps, dynamically modify those steps, and have the DSPINSTL Command Interpreter execute all the sub-steps within each step you created.

DSC files are composed of lines containing character-string entries. The following syntax rules govern the lines in a DSC file:

�All character strings must be enclosed in double quotation marks ("string" ).
�The /"pair can be used to embed a double-quotation mark within a character string.
�Comment lines must start with an asterisk (*).

DSC files contain one or more display-driver package entries. Each entry has a header section containing general information about the package. The header is followed by one or more subsections that define the default values for a data-chain element. The following shows the format of the header:

<Adapter Type Title string>   /* Title strings are up to 256 characters.   */

<DLL Module Name string>      /* DLL module, containing action routines    */
                              /*   for that type of adapter                */

<Standard Type Key string>    /* Key string that DSPINSTL uses to identify */
                              /*   a type of adapter that it recognizes.   */
                              /*   Can be NULL. See below for the complete */
                              /*   set of standard keys.                   */
         "1"                  /* Required parameter; must be set to 1. */
         "0"                  /* Required parameter; must be set to 0.     */

<# of Parameter Sets in Entry>/* 'n'                                       */

The following shows the format of the data-chain element subsection:

<Default Key String>            /* Initial key string assigned to this     */
                                /*   DSPINSTL data-chain element           */

<Default General   Prompt   String >   / *   User   prompt   string   displayed   in   the       * / 
                                    / *     Specify   Source   Directory   panel   when     * / 
                                    / *     the   DSPINSTL   data - chain   element   is 
                                    / *     interpreted                               * / 

< Default   Diskette   Prompt   String > / *   User   prompt   displayed   in   the   Insert       * / 
                                    / *     Diskette   panel   displayed   by   the         * / 
                                    / *     Specify   Source   Directory   panel   logic    * / 

< Default   Volume   Label >            / *   Optional   volume   label   string   used   by      * / 
                                    / *     the   Specify   Source   Directory   panel      * / 
                                    / *     logic   to   verify   that   an   inserted        * / 
                                    / *     diskette   is   the   correct   diskette        * / 

< Resolution   String >                / *   Optional   string ,   which   indicates   a        * / 
                                    / *     display   driver   resolution .               * / 
                                    / *     The   string   can   be   passed   to   the         * / 
                                    / *     Select _ Display _ Resolutions               * / 
                                    / *     service   function   or   can   be   left   NULL .   * / 
                                    / *     SVGA   display   driver   sets   have   one       * / 
                                    / *     resolution   to   a   DSP   file .                * / 
                                    / *     Resolution   strings   should   always        * / 
                                    / *     be   of   the   form ,   # # # # x # # # # x # # # # ,   where   * / 
                                    / *     each   # # # #   field   is   a   separate   integer . * / 

There is no data element parameter indicating a default source directory choice; it is always assumed to be the logical A: drive. DSPINSTL provides a "Specify Source Directory" PM panel that enables the user to override the default source directory. The <Default General Prompt String> is displayed in that panel so the user knows the purpose of the source directory about to be searched.

If the user changes the source directory to a nonremovable device, the source files can exist in the specified directory directly or in a sub- directory under the specified directory. The sub-directory name must be the same as the volume label for the entry, with underscore characters ( _ ) replacing spaces. Volume labels are limited to 8 characters.

The following example is a typical Super VGA display adapter parameter entry:

"XYZ SVGA video adapter"
"XYZ.DLL"
"SVGA"
"1"
"0"
"3"
"XYZ1"
"XYZ SVGA display drivers (part 1)"
"XYZ SVGA drivers diskette #1"
"XYZ_1"
"640x480x256"
"XYZ2"
"XYZ SVGA display drivers (part 2)"
"XYZ SVGA drivers diskette #2"
"XYZ_2"
"1024x786x256"
"XYZ3"
"XYZ SVGA display drivers (part 3)"
"XYZ SVGA drivers diskette #3"
"XYZ_3"
"1024x768x256"

The above example includes three resolution strings that can be displayed in the scrolling list box in the "Select Display Resolutions" panel.

If DSPINSTL cannot identify the type of graphics adapter, it displays a default type of "Other" and sets the default internal key to Other. The user then can go to the "Primary Video Adapter" or "Secondary Video Adapter " Presentation Manager panels and select a display type that is included in one of the DSC file entries.

If DSPINSTL can identify the type of graphics adapter but finds no matching configuration file entry with a matching standard-type keyword string, it displays the default type name for the adapter (such as VGA) in the "Video Display Configuration" panel but does not permit the user to accept the default selection. The user must use either the primary display check box or the secondary display check box to override default DSPINSTL processing. This causes display of a secondary PM panel that permits the user to select a display-driver package from a list that includes all the packages described in the DSC files.

User Interface PM Panels

The front-end PM panels enable the user to specify whether primary or secondary display-driver installation is desired. The panels also permit the user to override the default display-driver type and specify which display-driver package to install (based on the set of packages defined in the relevant DSC files on the user's system).

Action Routine Interface

The action routine interface enables you to add optional custom-control logic that is executed after the user makes an initial selection. Action routines are supported so that the installation process can ask specialized questions of the user, through PM panels, or perform internal inquiries concerning the state of the hardware or software system. For example, an action routine can be used to ask the user what display resolution to configure. Action routines are packaged in OS/2 DLL files.

Action routines tailor a display-driver installation by modifying the chain of data elements initialized by the DSPINSTL Configuration File Interpreter . You package DSPINSTL action routines in a DLL file, then include the name of the DLL file in the DSC file entry for that display-driver package. The DLL itself must be put in a directory within the user's LIBPATH or in the directory containing the DSPINSTL.EXE file.

DSPINSTL can call specified action routines (if they are provided in a DLL that can be named in the controlling configuration file entry) at four particular points during the beginning of the installation process:

�When the user accepts DSPINSTL's selection in the initial "Video Display Configuration" PM panel of the primary display

�When the user accepts DSPINSTL's selection in the initial "Video Display Configuration" PM panel of the secondary display

�When the user overrides DSPINSTL's selection of the primary display by explicitly selecting a primary display on the "Primary Video Adapter" PM panel

�When the user overrides DSPINSTL's selection of the secondary display by explicitly selecting a secondary display on the "Secondary Video Adapter" PM panel

The four action routines must have the following names:

Default_Primary()
Default_Secondary()
Selected_Primary()
Selected_Secondary().

You can provide any subset of the four action routines that you deem appropriate. When DSPINSTL reaches a point at which it tries to call an action routine, it uses DosLoadModuleto attempt loading of the DLL module. If successful, DSPINSTL then uses DosGetProcAddrto obtain the address of the action routine. If this is successful, DSPINSTL passes control to the action routine. If the attempt to obtain the address of the action routine is unsuccessful, DSPINSTL continues.

DSPINSTL assists the action routines by providing a set of service functions that enables them to perform various actions such as data-chain maintenance. Because of this assistance, an individual action routine does not have to be aware of the specific structure of a data-element chain. DSPINSTL insulates action routines from the details of the utility program' s internal structure, which greatly simplifies action-routine creation.

Each action routine is passed a pointer to a global DSPINSTL data structure that contains values the action routine can use. This data structure includes a Revisionfield (whose value always is set to 1 by the utility program) so that future revisions of DSPINSTL are able to grow and evolve the data structure. Action routines always must check the Revisionfield to determine how to access the data structure.

Procedure Call Interface for Action Routines

The four action routines follow the same procedure call interface, which is illustrated in Default_Primary Action Routine.

Default_Primary Action Routine

ULONG Default_Primary (hWnd, dsp_struc_ptr)

The Default_Primary action routine is invoked when the user accepts the primary display selection of the "Video Display Configuration" Presentation Manager panel.

/--------------------------------------------------------------\
|Parameter      |Data Type      |Description                   |
|---------------+---------------+------------------------------|
|hWnd           |HWND           |Handle of the main DSPINSTL   |
|               |               |window                        |
|---------------+---------------+------------------------------|
|dsp_struc_ptr  |PDSPINSTL_DATA |Pointer to the DSPINSTL data  |
|               |               |structure (see the following  |
|               |               |structure definition).        |
\--------------------------------------------------------------/

The global DSPINSTL data structure is defined as follows:

struct dspinstl_global_data
{
ULONG rev_num;                     /* Global DSPINSTL data structure       */
                                   /*   revision number                    */
PFN Link_Chain_Element_Ptr;        /* Address of the Link_Chain_Element    */
                                   /*   service function                   */
PFN Unlink_Chain_Element_Ptr;      /* Address of the Unlink_Chain_Element  */
                                   /*   service function                   */
PFN Next_Chain_Element_Ptr;        /* Address of the Next_Chain_Element    */
                                   /*   service function                   */
PFN Reserved_PTR1;                 /* Reserved                             */
PFN Select_Display_Resolutions_Ptr;/* Address of Select_Display_Resolutions*/
                                   /*   service function                   */
PFN Reserved_PTR2;                 /* Reserved                             */
PFN Reserved_PTR3;                 /* Reserved                             */
PFN Reserved_PTR4;                 /* Reserved                             */
PDSPINSTL_GLOBAL_DATA              /* Pointer to head of data element chain*/
PDSPINSTL_CHAIN_head               /* Pointer to head of data element chain*/
BOOL Reserved_Book                 /* Reserved                             */
PSZ pszSourceDirectory             /* Source directory name (ASCIIZ string)*/
ULONG ulSizeSource                 /* Size of source directory name buffer */
};

The source directory name string is displayed in the "Specify Source Directory" Presentation Manager panel that enables the user to override the default source directory for a given DSPINSTL step. As a result, the source directory name string acts as the default source directory for that step. The string's inclusion in the global data structure enables the user to modify the default source directory name to all action routines.

Remarks

Action routines can perform whatever computation and decision-making is necessary to modify the DSPINSTL data chain for eventual execution. Typically, action routines modify a key field within a data element, or they can add or subtract data-chain elements.

Generally, action routines should not change external system values, such as OS2.INI entries, because there is no guarantee that the user will not end the installation process after the action routine returns. Therefore, it is recommended that the persistent statesetting be performed by the commands in DSP files rather than by action routines.

An action routine communicates with the DSPINSTL utility program by setting the data-chain element key values. If an action routine sets several alternative key values in different chain elements, an equivalent set of DSP files (at least one for each alternative key value) must be provided in the eventual source directories or diskettes.

Note:The other DSPINSTL action routines have identical calling sequences and return codes. For that reason, the details of the procedure call interface for Default_Secondary(), Selected_Primary(), and Selected_ Secondary() are not included here.

Three service routines are provided to manipulate the data element chain. The following data structure characterizes a DSPINSTL data element:

struct dspinstl_chain_element
{
 ULONG rev_num;        /* DSPINSTL data chain element revision number    */

 PDSPINSTL_CHAIN next; /* Pointer to next DSPINSTL data chain element    */

 PSZ key;              /* Pointer to keyword string associated with this */
                       /*   chain element                                */

 PSZ general_prompt;   /* Pointer to the prompt string to be written in  */
                       /*   the Specify Source Directory panel when this */
                       /*   chain element is interpreted.  A NULL value  */
                       /*   indicates that the previous source directory */
                       /*   should be used again and that this panel     */
                       /*   should be bypassed for this chain element.   */

 PSZ diskette_prompt;  /* Pointer to the prompt string to be written in  */
                       /*   the Insert Diskette prompt panel             */

 PSZ volume_label;     /* Pointer to the (optional) diskette volume      */
                       /*   label string that is used to verify the      */
                       /*   correct identity of a DSP diskette           */

 PSZ resolution_string;/* Optional string that indicates a display driver*/
                       /*   resolution.  The string can be passed to     */
                       /*   Select_Display_Resolutions or left NULL      */
};

Note:Typically, the various strings found in DSPINSTL data elements are initialized from string values found in DSPINSTL configuration file entries .

Return Codes

Action routines return the following values:

0 Indicates that no problems were encountered and DSPINSTL should proceed.

0xFFFFFFFF Indicates that the action routine is returning a Cancel indication, which might be triggered by the user pressing a Cancelpush button within a PM panel that was invoked by the action routine. Notice that the Cancel return code is supported so that DSPINSTL can back out of its current execution path.

0xFFFFFFFE A reserved return code.

All other non-zero values are interpreted as OS/2 system error codes.

DSPINSTL Service Functions

A set of standard service functions is provided to keep the action-routine developer from having to program commonly used functions. Service functions enable the user to examine and modify the DSPINSTL chain of data elements.

The global DSPINSTL data structure contains pointers to a set of DSPINSTL service functions that are available to all action routines. These service functions, listed below, are described in the pages that follow.

Link_Chain_Element
Unlink_Chain_Element
Next_Chain_Element
Select_Display_Resolutions

Link_Chain_Element

ULONG Link_Chain_Element (new_element_ptr, create_flag,
position_flag, existing_element_ptr)

This service function provides a standard mechanism for linking data-chain elements in the DSPINSTL data chain. Optionally, this function can be used to allocate a new element, which then is linked into the chain. The caller indicates where in the chain the data-chain element should be linked. Elements can be linked at the head of the chain, the end of the chain, or after a specified chain element. After the function returns a pointer to a new data-chain element, the action routine can fill in the element's fields as appropriate.

/----------------------------------------------------------------\
|Parameter           |Data Type      |Description                |
|--------------------+---------------+---------------------------|
|new_element_ptr     |PDSPINSTL_CHAIN|Pointer. See details below.|
|--------------------+---------------+---------------------------|
|create_flag         |USHORT         |Flag. See details below.   |
|--------------------+---------------+---------------------------|
|position_flag       |USHORT         |Flag. See details below.   |
|--------------------+---------------+---------------------------|
|existing_element_ptr|PDSPINSTL_CHAIN|Pointer to an existing data|
|                    |               |chain element. See details |
|                    |               |below.                     |
\----------------------------------------------------------------/

new_element_ptr If create_flagis set to 1, this argument returns a pointer to the new element. If create_flagis set to 0 on input, this argument points to an existing DSPINSTL data-chain element.

create_flag Flag that indicates whether the caller wants the function to create a new element, or link an element into the chain. A value of 1 indicates that a new element should be created and then linked into the chain. A value of 0 indicates that an existing element (pointed to by new_ element_ptr) should be linked into the chain.

position_flag Flag that indicates where the caller wants the data-chain element to be linked into the data chain. A value of 0 places the element at the head of the chain. A value of 1 places it at the end of the chain. A value of 2 indicates that the element should be linked in front of the chain element pointed to by existing_element_ptr. A value of 3 indicates that the element should be linked after the chain element pointed to by existing_element_ptr.

existing_element_ptr If position_flagis set to 2 or 3 on input, this argument points to another data element in the chain.

This service function returns the following values:

0 Success.
1 Element could not be linked into chain.
2 New chain element could not be allocated.

Unlink_Chain_Element

   ULONG Unlink_Chain_Element (element_ptr)

This service function provides a standard mechanism for unlinking data- chain elements from the chain. It does not deallocate the memory associated with the element.

/--------------------------------------------------------------\
|Parameter      |Data Type      |Description                   |
|---------------+---------------+------------------------------|
|element_ptr    |PDSPINSTL_CHAIN|Pointer to a DSPINSTL         |
|               |               |data-chain element            |
\--------------------------------------------------------------/

This service function returns the following values:

0 Success.
1 Element could not be unlinked from chain.

Next_Chain_Element

ULONG Next_Chain_Element (next_element_ptr,position_flag existing_element_ptr)

This service function provides a standard mechanism for returning the address of specified data elements within the chain.

/----------------------------------------------------------------\
|Parameter           |Data Type      |Description                |
|--------------------+---------------+---------------------------|
|next_element_ptr    |PDSPINSTL_CHAIN|Returns a pointer to the   |
|                    |               |specified chain element.   |
|--------------------+---------------+---------------------------|
|position_flag       |USHORT         |Flag. See details below.   |
|--------------------+---------------+---------------------------|
|existing_element_ptr|PDSPINSTL_CHAIN|Pointer to an existing data|
|                    |               |chain element. Used only if|
|                    |               |position_flag is set to 2  |
|                    |               |or 3.                      |
\----------------------------------------------------------------/

position_flag A flag that indicates which data-chain element was specified by the caller, as follows:

0 Indicates the head element of the chain.

1 Indicates the tail element of the chain.

2 Indicates the data element that follows the data element pointed to by the existing_element_ptr input argument.

3 Indicates the data element that precedes the data element pointed to by the existing_element_ptr input argument.

This service function returns the following values:

0 Success
1 Next element found within the chain

Select_Display_Resolutions

ULONG Select_Display_Resolutions (hWnd, resolutions, num_resolutions)

The Select_Display_Resolutions service function is used by an action routine to determine which display resolutions are desired by the user as a result of this installation. The service function displays a "Select Display Resolutions" Presentation Manager panel that lets the user choose from display-resolution strings displayed in a scrolling list box within the panel.

The strings are passed to the function in an array of structures. A flag that is passed to the function controls whether the panel permits the user to select multiple or single display resolutions. On return from the function, each structure in the array contains a flag value that indicates whether that array element was selected by the user.

/----------------------------------------------------------------\
|Parameter      |Data Type         |Description                  |
|---------------+------------------+-----------------------------|
|hWnd           |HWND              |Handle of the main DSPINSTL  |
|               |                  |window.                      |
|---------------+------------------+-----------------------------|
|resolutions    |struct            |Pointer to an array of       |
|               |resolutions_struct|display-resolution           |
|               |                  |structures. See details      |
|               |                  |below.                       |
|---------------+------------------+-----------------------------|
|num_resolutions|ULONG             |Number of display-resolution |
|               |                  |structures in the array.     |
|---------------+------------------+-----------------------------|
|fmultiple      |BOOL              |Flag that specifies whether  |
|               |                  |the user is permitted to     |
|               |                  |select multiple display      |
|               |                  |resolutions. True indicates  |
|               |                  |that multiple selections are |
|               |                  |permitted.                   |
\----------------------------------------------------------------/

The resolutions parameter points to an array of display resolution structures, where:

struct resolutions_struct
{
 UCHAR resolution_string[40]; /* String to go in multiple-selection list box. */
 USHORT selected;             /* Flag set by the service function.            */
                              /* If 0, this resolution was not selected.      */
                              /* If 1, this resolution was selected.          */
};

This service function returns the following values:

0 User selected an entry and exited the panel by selecting the OKpush button.
0xFFFFFFFF User exited the panel by selecting the Cancelpush button.

The action routine must create the array of display-resolution structures. It can use knowledge about the video hardware on the user's system to limit the resolution structures to only those that can be supported on the existing hardware.

Command Language PM Panels

During the final phase of DSPINSTL execution, each data-chain element triggers a separate DSPINSTL command-language interpretation step, using the command-language PM panels. One of these panels enables the user, optionally, to override the source directory to be used for this step. Another panel prompts the user to insert an appropriately labeled diskette. The remainder of the PM panels prompt the user when execution errors are encountered during this phase.

DSPINSTL Command Language Interpreter

The DSPINSTL Command Language Interpreter is used in the final phase of the DSPINSTL process. It interprets the contents of DSPINSTL display-driver profile (.DSP) files containing DSPINSTL commands. DSPINSTL commands specify the basic installation and configuration operations to be performed by the utility program. Each DSP file is tagged with a keyword string that identifies the file. To select a DSP file for interpretation, the DSPINSTL Command Language Interpreter traverses the data-element chain.

It is the DSPINSTL commands that do the actual work of display-driver installation and configuration. All the preceding DSPINSTL operations act to properly set up this final phase on a given user's system. In addition to commands that copy files and modify configuration files, there is a special RUN command that runs specified programs during DSP file interpretation. Among other things, such programs can generate DSPINSTL commands that are interpreted immediately by the DSPINSTL Command Language Interpreter. This is the final way that a display-driver developer can customize DSPINSTL execution.

DSPINSTL Command Language

The DSPINSTL Command Language is highly flexible so that it can accommodate the many different operations that must be performed during the installation and configuration of OS/2 display drivers.

A set of DSPINSTL commands is packaged as a DSP file. Each DSP file must contain a KEY command to tagthat DSP file. Then, when a data-chain element is interpreted by DSPINSTL, all DSP files in the current source directory that are tagged with that keyword are interpreted. This mechanism permits automatic execution.

The FILES command tells DSPINSTL which files to copy to the user's hard disk. Date/time checking and file-version checking can be performed as part of the FILES command processing; this helps prevent inappropriate copying of files, an important DSPINSTL safety feature. The FILES command supports the installation of both packed and unpacked files. Packed files can reduce greatly the amount of space consumed on the display-driver developer's diskettes.

The CONFIG, OS2INI, and WININI commands tell DSPINSTL how to update the configuration in the different types of system configuration files. Three separate commands are used because the different types of OS/2 system configuration files require different editing styles. Configuration of OS/2 display drivers is particularly tricky because of the coordinated updates needed in the different OS/2 configuration files.

The CONFIG command is used to update the CONFIG.SYS file. The OS2INI command is used to edit the various INI OS/2 system configuration files ( such as OS2.INI or OS2SYS.INI). The WININI command is used to update the different WIN-OS/2 configuration files (such as WIN.INI and SYSTEM.INI).

SET_DRIVER and SET_RESOLUTION also are configuration editing commands. With these two commands, rather than editing a specific configuration file, an OS/2 graphics engine (Gre) function updates the system configuration. This additional level of data abstraction is necessary to support the architecture of the graphics engine, which is yet another complexity supported by the DSPINSTL Command Language.

DSPINSTL Commands

The DSPINSTL Command Language is similar to the DDINSTAL Command Language, in that the DSPINSTL Command Language Interpreter accepts comments in the form of lines beginning with an asterisk (*). However, the DSPINSTL Command Language contains important keyword extensions.

/--- USAGE NOTE -------------------------------------------\
|                                                          |
|   All keywords must be in uppercase and preceded by a    |
|   full colon ( : ), as shown in the following list of    |
|   commands.                                              |
|                                                          |
\----------------------------------------------------------/

The DSPINSTL Command Language files support the following commands:

KEY
:FILES
:CONFIG
:DEL_CONFIG_LINE
:AUTO_EXEC
:OS2INI
:TITLE
:WININI
:RUN
:SET_DRIVER
:SET_RESOLUTION.

A MODEqualifier is valid on all DSPINSTL commands except :KEY. Valid MODEqualifier values and their descriptions are shown in the following list:

PRIMARY Execute this command only if the user is performing a primary display-driver installation.

SECONDARY Execute this command only if the user is performing a secondary display-driver installation.

DOS Execute this command if DOS support is installed on the OS/2 system.

WINDOWS Execute this command if WIN-OS/2 support is installed.

KEY Command

The KEY command identifies a DSP file with a unique keyword string so that it automatically can be selected for interpretation by DSPINSTL. The final phase of DSPINSTL processing consists of one or more steps of DSP-file interpretation. In each step, all the DSP files in the current source directory (whose keyword strings match the keyword string for that step) are interpreted.

The format of the KEY command line is :KEY.

The DSP file line immediately following the KEY command line contains a keyword string that begins with the first nonblank character in the line and ends at the first blank character or the end of the line. There can be no embedded blanks in a keyword string. Keyword strings can be up to 64 bytes in length. The following is an example of a KEY command line.

    :KEY
    XYZ_800x600x16

There must be only one :KEY command line in each DSP file.

FILES Command

The FILES command specifies the files that are to be copied from the source directory to different destination directories. It performs similarly to the DDINSTAL FILES command. Like its DDINSTAL counterpart, the DSPINSTL FILES command line is followed by a set of file-copy directives. However, unlike DDINSTAL, the DSPINSTL FILES command uses the UNPACK utility program to copy files, so that it can handle both packed and unpacked file formats.

The FILES command can be used to replace any executable modules (programs and DLLs) that currently are in use. The replacement occurs the next time the system is started up. DSPINSTL cannot replace non-executable files that are locked at the time DSPINSTL is run.

The format of the FILES command line is :FILES.

To protect against inadvertently copying an old version of a file over a newer version, all file copying is mediated by one of two different forms of file-version checks, as listed below:

�File-version field checking
�Date/Time checking

File-Version Field Checking

Executable files can be tagged with a file-version string in the descriptionfield of their executable file headers, which can be set during program linking. The following is an example of a file-version string:

   <header> <version string> <trailer>

where:

<header>is a 2-character string: @#.

<version string>is 12 characters defined as xxx:YYYYYYYY,where xxxis used to identify the vendor that created the file (for example, IBM) and YYYYYYYYis a file-version number (for example, 0006.307). The file-version number can be interpreted as a floating point number or an integer.

<trailer>is the 2-character string: #@.

An example of a file-version string is:

  @#IBM:0006.307#@.

If both the source and target versions of a file contain file-version strings, file-version checking is performed. For a file-version check to be considered successful, the vendor IDs of the source and target files must match; and the file-version number of the source file must be greater than, or equal to, the file-version number of the target file. If the file- version check succeeds, the source file is copied over the target file. If not, DSPINSTL prompts the user to decide whether to replace the target file . If the source file contains a file versionfield, but the target file does not, the source file is assumed to be more recent than the target file and is copied over the target file.

Date/Time Checking

DSPINSTL does not automatically copy an old version of a file over a newer version when the Date/Timeof the file to be copied is less recent than the Date/Timeof the file to be replaced. Instead, it prompts the user to decide whether to replace the newer version of the file with the older version.

The FILES command line is followed by one or more lines that name the files to be copied from the source directory and the destination directory to which they are to be copied. The following illustrates the format of these lines:

 <source file name> <destination directory pathname>

where:

<source file name>is the name of a file in the source directory that contains the DSP file. A source file can be packed or unpacked.

<destination directory pathname>can include an optional logical drive letter specification that always is overridden by the system's startup drive. The destination directory path name is not a complete file name, which means that the source file is never renamed when it is copied.

Note:The special term %BOOTDRIVE%can be used to replace the startup drive letter in all DSPINSTL commands that permit path names to be specified. %BOOTDRIVE%is a special drive designator that indicates the letter of the drive on which the OS/2 system was started.

If a destination directory is provided, the file is copied to that directory. If no destination directory is provided and the source file is packed, the file is copied to the directory specified in the source file's pack header. If there is no corresponding directory on the drive, a directory is created. If no destination directory is provided and the source file is unpacked, the file is copied to the current working directory.

The following examples illustrate DSP file command lines that can follow the FILES command line:

    :FILES   :MODE=PRIMARY
    IBMVGA32.DL@ %BOOTDRIVE%:\OS2\DLL
    BVHVGA.DLL %BOOTDRIVE%:\OS2|DLL

    :FILES  :MODE=PRIMARY  :MODE=DOS 
     VVGA . SY @   % BOOTDRIVE % : \ OS2 \ MDOS 

Note:Some of the source-file names are immediately followed by the "@" sign, indicating that these are packed files (packed by the OS/2 PACK utility program).

CONFIG Command

The CONFIG command specifies updates to the CONFIG.SYS file, functioning similarly to the DDINSTAL CONFIG command. Like its DDINSTAL counterpart, the DSPINSTL CONFIG command line is followed by a set of CONFIG.SYS statements that are to be added to the configuration file. However, the DSPINSTL CONFIG command attempts to replacecorresponding CONFIG.SYS statements instead of appending them to the file.

The format of the CONFIG command line is :CONFIG.

The following examples illustrate DSP file command lines that can follow the CONFIG command line:

    :CONFIG  :MODE=PRIMARY
    SET VIDEO_DEVICES=BIO_VGA
    SET VIO_VGA=DEVICE(BVHVGA)

    :CONFIG :MODE=PRIMARY :MODE=DOS
    DEVICE=%BOOTDRIVE%:\OS2\MDOS\VVGA.SYS

DEL_CONFIG_LINE Command

This command is used to delete specific lines in a CONFIG.SYS file.

The format of the DEL_CONFIG_LINE command line is :DEL_CONFIG_LINE.

The following examples illustrate DSP file command lines that can follow the DEL_CONFIG_LINE command line:

    :DEL_CONFIG_LINE  :MODE=PRIMARY
    SET VIDEO_DEVICES=BIO_VGA
    SET VIO_VGA=DEVICE(BVHVGA)

    :DEL_CONFIG_LINE :MODE=PRIMARY :MODE=DOS
    DEVICE=%BOOTDRIVE%:\OS2\MDOS\VVGA.SYS

AUTO_EXEC Command

This command is used to update the AUTOEXEC.BAT file.

OS2INI Command

The OS2INI command specifies updates to an OS/2 INI system configuration file, functioning similarly to the DDINSTAL OS2INI keyword. However, the DSPINSTL OS2INI command is more general in nature than DDINSTAL because it can be used to specify updates to any OS/2 INI file (such as OS2.INI or OS2SYS.INI).

The format of the OS2INI command lines is :OS2INI.

Like its DDINSTAL counterpart, the DSPINSTL OS2INI command line is followed by a set of INI line entries, which are added to the configuration file. The first line following the OS2INI command line specifies the complete path name of the OS/2 INI file to be modified. Like the FILES command, the optional drive specification in the complete path name always is overridden by the system's startup drive. If only a simple OS/2 INI file name is specified, the \OS2 directory on the system's startup drive is assumed.

The following examples illustrate the DSP file command lines that can follow the OS2INI command line:

    :OS2INI  :MODE=PRIMARY
    OS2.INI
    PM_DISPLAYDRIVERS IBMVGA32 IBMVGA32
    PM_DISPLAYDRIVERS CURRENTDRIVER IBMVGA32

TITLE Command

This command is not used.

WININI

The WININI command specifies updates to the WIN-OS/2 configuration file. It has no counterpart in DDINSTAL. Like the OS2INI keyword, the WININI keyword is followed by the name or complete path name of a WIN-OS/2 configuration file. If a simple file name is provided, it is assumed that the file resides in the \OS2\MDOS\WINOS2 directory on the system's startup drive.

The format of the WININI command lines is :WININI.

The file-name line is followed by a series of lines that will be placed in the specified WIN-OS/2 configuration file. Each WIN-OS/2 configuration line consists of three fields: <section>, <keyword> and <value>. Sectionidentifies a section in the WIN-OS/2 configuration file.

Similar to that for the CONFIG command, an attempt is made to replace corresponding lines in the file rather than appending the lines to the specified section of the file. Typically, WIN-OS/2 configuration lines are of the form:

    <keyword string> = <value string>

where the <value string> actually can be several sub-strings divided by spaces. Any of the fields (section, keyword, value) can contain spaces if the field is enclosed in double quotation marks (" "). The WININI command operates by replacing lines in the specified section that match <command string> fields, or (if no match is found) by appending the new line at the end of the specified section.

The following examples illustrate the DSP file command lines that can follow the WININI command line:

    :WININI :MODE=PRIMARY :MODE=WINDOWS
    SYSTEM.INI
    BOOT DISPLAY.DRV VGA.DRV
    BOOT SDISPLAY.DRV SWINVGA.DR

RUN Command

The RUN command is used to specify one or more programs to execute. The specified programs and their associated parameters are listed in the lines following the RUN command.

The format of the RUN command line is :RUN.

Each program that is run can create DSP commands dynamically by writing them to that program's standard output device. When the program terminates, any DSP commands written to the output device are interpreted immediately by DSPINSTL. The dynamically created DSP commands are interpreted before the DSP file lines following the RUN program line are interpreted. The program must use only its standard output device for writing DSP commands.

If a RUN-specified program generates output other than DSP lines, it must be redirected to another file or to NULL. (See the example below.)

    :RUN
     MYPROG.EXE >NUL 2>&1

The RUN command ignores the return code from the programs it executes. Each program specification line that follows the RUN keyword command must adhere to the following format:

    <program pathname> [<program parameters>]

The RUN command also can be used to execute OS/2 command files (.CMD).

SET_DRIVER

The SET_DRIVER command is used to configure a 32-bit display driver for use by the 32-bit graphics engine. The parameters associated with this keyword will be listed in the lines that follow the SET_DRIVER command. These parameters are passed to the DspSetDriverInfo function.

The format of the SET_DRIVER command line is :SET_DRIVER. Each parameter is specified as a <keyword> = <value> pair.

The following lists the parameters that must be specified in the lines following the SET_DRIVER command line. All the parameter values in this list are strings and must be enclosed in double quotation marks.

NAME = "<Name of display driver>"
DESC = "<String that describes display driver (can be NULL)>"
PATHNAME = "<Name of display driver>"
PARMS = "<String containing parameters for driver (can be NULL)>"

Following is an example of how to specify the parameter values used with the SET_DRIVER keyword command:

    :SET_DRIVER
    NAME="IBMVGA32"
    DESC="IBM VGA Display Driver"
    PATHNAME="IBMVGA32"
    PARMS=""

SET_RESOLUTION

The SET_RESOLUTION command informs the 32-bit graphics engine of the initial display resolution for the display driver being installed. This command is used only for display drivers that can support multiple display resolutions and that use the DspDefaultResolution function to determine, during initialization, which resolution to display.

The format of the SET_RESOLUTION command line is: SET_RESOLUTION.

The parameters associated with this command are listed in the lines following the SET_RESOLUTION command line. Each parameter is specified as a <keyword> = <value> pair.

The following lists the parameters that must be specified after the SET_ RESOLUTION command line. All the parameter values in this list are numeric values and are specified as unsigned decimal numbers.

WIDTH = <Width of the display resolution in pels>
HEIGHT = <Height of the display resolution in pels>
COLORS = <Number of colors supported in this display resolution>
PLANES = <Number of planes in this display resolution>

Following is an example of how to specify the parameters associated with the SET_RESOLUTION keyword command:

    :SET_RESOLUTION
    WIDTH=1024
    HEIGHT=768
    COLORS=256
    PLANES=1

Creating a Display-Driver Installation Package

A complete display-driver installation package usually will include the following types of files:

�DSPINSTL utility program

�DLL, including the action routines (if action routines are used)

�One or more DSC configuration files (containing DSC entries for each driver package)

�Display driver files (PM or WIN-OS/2)

�Other files to be copied (if necessary)

�One or more DSP files (containing DSPINSTL installation and configuration commands)

�Programs to be triggered by the :RUN commands in DSP files (as needed)

A display-driver package can span multiple diskettes. If so, each diskette must include the DSP files that explain what to do with the files on the diskette. The display driver files (and related files) can be packed (by the PACK.EXE utility program).

If the files are packed, their last file-name character must be set to the "@" character. DSC files, DSP files, the action-routine DLL, and the DSPINSTL utility program must not be packed.

Graphics Test Suites

This chapter describes test suites that are designed for device driver developers and testers. This chapter describes:

• Function Verification Tests (FVT)
• System Verification Tests (SVT)

Graphic View Of Directory

Following is the structure of the graphics subdirectory on the IBM Developer Connection Device Driver Kit for OS/2

   \TESTCERT\DISPLAY\
                     |----DATA
                     |----FUNCTION
                     |      |----COLORPT
                     |      |----CSHOW
                     |      |----DTT32
                     |      |----FRACTINT
                     |      |----FRACTWIN
                     |      |----GIFTEST
                     |      |----MODETEST
                     |      |           |--OS2
                     |      |           \---VDM
                     |      |----PALDISP
                     |      |----PMAN
                     |      |----PMVIEW
                     |      \----TESTCASE
                     |----SYSTEM
                     |----TESTCASE
                     |----OS2
                     |----VDM
                     \----WINOS2

Function Verification Test Overview

Function Verification Test (FVT) means to test the functionality of the object (in this case, the different video device drivers), using single- tasking, single-threaded applications, which use combinations of supported system Application Programming Interface (API) functions. The use of these APIs in combination with other APIs should create a functioning "mini" application (applet), which will exercise the functionality of the object under test and optionally generate a log file to be examined at a later time for proper return codes and overall program functionality. No other applications should run on the system concurrently.

A sample of FVT applets have been included on the CD-ROM, and are located in:

     ..\testcert\display\function

Some FVT applets were not included on the CD-ROM. They are available on CompuServe**. After downloading the applets, place them on the hard disk according to the path structure provided by the test cases.

The following describes the targeted scope of test coverage provided by the FVT test cases during the execution of a test plan.

Base Video Handler (BVH)

Following are the OS/2* (protect mode) scenarios that:

�Validate all modes referenced in the PMI file when applicable
-Supported and unsupported modes
-Mode system command for text
-GIF/BMP viewer applications for graphics
�Save and restore operations while in each mode
�132 column mode support verification
�Interlace and non-interlace configurations
�Multiple monitor refresh rates

Virtual Device Driver (VDD for VDM)

Following are the DOS scenarios that:

�Validate all modes supported by the hardware
-Mode system command for text
-GIF viewer applications for graphics
�Save and restore operations while in each mode
�Use of DOS settings
-DOS_BACKGROUND_EXECUTION
-VIDEO_RETRACE_EMULATION
�Virtualization
-320x200x256 versus greater than 640x480x16 modes

Presentation Manager*

Following are PM scenarios that:

�Validate support for Palette Manager
-Palette applications
-Device specific StretchBlit support
�Save and restore operations
-PM desktop to full screen with a different mode
�Clipping
-Combinations of PM, VDM, WIN-OS/2* Full Screen, WIN-OS/2 Seamless (on the desktop)
�Routine Desktop Operations
-Dragging, sizing, etc.
�Color Manipulation
-Color Palette
-Transparent background option
-Transparent underlay option
�Font Manipulation
�API level : The Display Driver Test (DTT) tool tests:
-Graphics Engine (GRE) API calls
-Mandatory functions for all display drivers
-Simulated functions by the Graphics Engine
-Multiple test categories
--Display intensive
--Return code (Rc) verification
--Exhaustive (Exh) limits validation
�Validate software motion video support
�Display Console Access Facility (DCAF) support

WIN-OS/2

Following are the WIN-OS/2 Full Screen and seamless scenarios that:

�Similar to PM scenarios
-Clipping
-Save and restore
-Color manipulation
-Desktop operations
�Seamless
-Separate session settings
-Multiple VDMs versus single VDM
�Full Screen
-WIN-OS/2 settings (VIDEO_SWITCH_NOTIFICATION)

System Verification Test Overview

System Verification Test (SVT) is a full function, full hardware environment test to utilize video device drivers. In Function Verification Test (FVT), only one application is run on OS/2, while in SVT, multiple applications are run simultaneously, which exercise the video device driver functions. Stress and cross product interaction are used to stress the video device drivers, by running combinations of existing industry applications (such as those used in FVT), product applets, system test developed applets, and SVT test cases, which will produce a multi-threaded multi-tasking use of the video device drivers.

Knowledge of several unique and a few odd terms are necessary for a proper understanding of the SVT process. These include:

PreconditionerAny other process run prior to a test to provide a certain stress or otherwise condition to the system environment.

ScriptA textual input script or 'program' for a test tool.

ScenarioA type of test - several 'variations' on the scenario may exist (i .e., running different preconditioners).

TestcaseFor SVT, a test case consists of a specific variation on a specific scenario run on a specific Device Under Test (DUT).

VariationA slightly different version of a scenario. Typically, each scenario will have several variations, each running different preconditioners.

FVT Test Cases

This section describes how to run different test suites for function verification test.

Since OS/2* can support applications written for DOS, Windows**, and OS/2, three types of FVT test cases must be run to properly test the different modes.

Several test cases have been included on the CD-ROM. These tests call FVT applications with proper syntax and parameters. These test cases are located in:

      ..\testcert\display\function\testcase

Some of the test cases assume working knowledge of applications, which are shipped with OS/2, such as the Win-OS/2 Clock. For information on usage of these programs, refer to the OS/2 User's Guide.

The following test suites are included on the CD-ROM:

�VDM Test Suite
�OS/2 Test Suite
�WIN-OS/2 Test Suite

VDM Test Suite

The VDM test suite includes:

�Test Case 1
�Test Case 2
�Test Case 3
�Test Case 4
�Test Case 5
�Test Case 6

Test Case 1

This test case displays a 1280x1024 with 256 color image in a full screen VDM, using the CompuShow shareware application.

For more information on CompuShow, please refer to the documentation provided with CompuShow.

Test Case 2

This test case displays a 1024x768 with 256 color image in a full screen VDM, using the CompuShow shareware application.

For more information on CompuShow, please refer to the documentation provided with CompuShow.

Test Case 3

This test case displays an 800x600 with 256 color image in a full screen VDM, using the CompuShow shareware application.

For more information on CompuShow, please refer to the documentation provided with CompuShow.

Test Case 4

This test case displays an 640x480 with 256 color image in a full screen VDM, using the CompuShow shareware application.

For more information on CompuShow, please refer to the documentation provided with CompuShow.

Test Case 5

This test case utilizes the OS/2's VDM MODE command to change different video MODEs:

        Mode: 40 , 12
        Mode: 40 , 25
        Mode: 40 , 43
        Mode: 40 , 50
        Mode: 80 , 12
        Mode: 80 , 25
        Mode: 80 , 43
        Mode: 80 , 50
        Mode: 132 , 25
        Mode: 132 , 43
        Mode: 132 , 44

For more information on how to use the MODE command, refer to the OS/2 Command Reference in the Information folder.

Test Case 6

This test case executes a demonstration of some of the capabilities of the FRACTINT program. The demo displays various fractal images. The demo is an automated way of directing the program to do various tasks. The user can create these kinds of scripts for FRACTINT to direct the program to perform various other tasks.

For more information on how to create scripts and how to use the FRACTINT program, please refer to the file fractint.doc provided with FRACTINT.

OS/2 Test Suite

The OS/2 test suite includes:

�Test Case 7
�Test Case 8
�Test Case 9
�Test Case 10
�Test Case 11
�Test Case 12
�Test Case 13
�Test Case 14
�Test Case 15

Test Case 7

This test case utilizes the OS/2 Full Screen MODE command to change different video MODEs.

        Mode: 40 , 12
        Mode: 40 , 25
        Mode: 40 , 43
        Mode: 40 , 50
        Mode: 80 , 12
        Mode: 80 , 25
        Mode: 80 , 43
        Mode: 80 , 50
        Mode: 132 , 25
        Mode: 132 , 43
        Mode: 132 , 44

For more information on how to use the MODE command, refer to the OS/2 Command Reference in the Information folder.

Test Case 8

This test case displays a 1280x1024 with 256 color image on the Desktop using the PMView 0.86b shareware application.

For more information on PMView, refer to the documentation provided with PMView.

Test Case 9

This test case displays a 1024x768 with 256 color image on the Desktop, using the PMView shareware application.

For more information on PMView, refer to the documentation provided with PMView.

Test Case 10

This test case displays an 800x600 with 256 color image on the Desktop, using the PMView shareware application.

For more information on PMView, refer to the documentation provided with PMView.

Test Case 11

This test case displays an 640x480 with 256 color image on the Desktop, using the PMView shareware application.

For more information on PMView, refer to the documentation provided with PMView.

Test Case 12

PALDISP - Hardware Palette Display

This OS/2 PM program displays the hardware palette on the OS/2 desktop. When observing the display, the program should produce a spectrum of multicolored bars.

Test Case 13

GIFTEST is an application which displays GIF images in an OS/2 full screen mode.

Usage:

       giftest xxxxx.gif hor_res ver_res bitsperpix_colors

Example:

       giftest 1024x768.gif 1024 768 8

Test Case 14

This test case automatically runs the Display Test Tool (DTT) program using a predefined test script file SAMPLE.SCR. DTT writes information to a log file. A path and file name for the DTT log file can be specified on the DTT command line using the -F option. In our example the default file name for log file, DTT_LOG, was created and located in the current directory.

For more information on Display Test Tool, refer to the documentation provided with DTT.

Test Case 15

COLORPT is an OS/2 Presentation Manager program that continually reports the name and value of the color of the pel (pixel) that is under your OS/2 PM mouse pointer. The color value can be displayed in several different color models. COLORPT is especially targeted to users of PCs with grayscale video or LCD displays.

WIN-OS/2 Test Suite

The WIN-OS/2 test suite consists of the following tests:

�Test Case 16
�Test Case 17
�Test Case 18
�Test Case 19
�Test Case 20

Test Case 16

This test case displays a 1280x1024 with 256 color image in a full screen WIN-OS/2, using the Picture Man shareware application.

For more information on Picture Man, refer to the documentation provided with Picture Man.

Test Case 17

This test case displays a 1024x768 with 256 color image in a full screen WIN-OS/2, using the Picture Man shareware application.

For more information on Picture Man, refer to the documentation provided with Picture Man.

Test Case 18

This test case displays an 800x600 with 256 color image in a full screen WIN-OS/2, using the Picture Man shareware application.

For more information on Picture Man, refer to the documentation provided with Picture Man.

Test Case 19

This test case displays an 640x480 with 256 color image in a full screen WIN-OS/2, using the Picture Man shareware application.

For more information on Picture Man, refer to the documentation provided with Picture Man.

Test Case 20

This test case executes a demonstration of some of the capabilities of the FRACTINT program. The demo is an automated way of directing the program to do various tasks. The user can create these kinds of scripts for FRACTINT to direct the program to perform various other tasks.

For more information on how to create scripts and how to use the FRACTINT program, refer to the file fractint.doc provided with FRACTINT.

SVT Test Cases

SVT applications were not included on the CD-ROM.

Use of existing industry applications, such as Ami Pro** 3.0, are required for SVT efforts. Included SVT test cases reference these applications and are located in:

               ..\testcert\display\system\vdm
               ..\testcert\display\system\os2
               ..\testcert\display\system\winos2

The three test suites for SVT are:

�VDM Test Suite
�OS/2 Test Suite
�WIN-OS/2 Test Suite

VDM Test Suite

The VDM test suite consists of:

�Communication Ports Test Cases
�DOS Compatibility Application Test

Communication Ports Test Cases

The communication ports test cases are used to execute different applications which will use the communication driver to test the video device drivers.

This test runs on two machines 386/486 with communication ports and modems attached. Various communication applications are run on these machines. Different files are uploaded and downloaded in this test.

The following applications are tested:

�Procomm** Plus
�DynaComm**

Two machines are necessary for this test. A hostmachine and a remotemachine. The remote machine will be calling the host machine to receive data.

For this test, a clean OS/2 install should be done for every video device driver tested (or press [Ctrl+Alt+F1] during boot-up to reset the desktop). Make sure to press [Ctrl+Esc] to switch between the desktop and the applications while running the test. Repeat the process at different stages of the application.

Verify that both machines are connected to analog telephone lines.

Procomm Plus

The following procedure explains how to test Procomm Plus:

1. Open an DOS full screen session (VDM) to run Procomm Plus. If you do not have Procomm Plus installed, refer to your Procomm Plus Installation Manual for instructions.
2. At the Procomm Plus screen, press [Enter] to go to terminal mode.
3. Press [Alt+D] for dial mode.
4. Type the number and start the call.
5. When the connection has been established perform login.
6. Type a "U" to upload a file or a "D" to download a file.
7. Type the modem protocol type. The most common protocols are Kermit, Xmodem and Ymodem. Use these protocols along with a mixture of the others.
8. Type the file name.
9. To begin the file transfer, press Page Down to download files or Page Up to upload files.
10. Verify that the file transfer has completed.
11. Send or receive at least three files changing modem types.

Note: Verify that video corruption does not occur in all operations.

Dynacomm

The following procedure explains how to test Dynacomm:

1. Open an OS/2 full screen session to run DynaComm. If you do not have DynaComm installed, refer to your DynaComm Installation Manual for instructions.

2.Select serial port.

3.Click on Settings, select Communication and Phone Number.

4.Select for Baud Rate and click on OK.

5.Click on Setting and select Binary Transfer.

6.Select the type of transfer to be done.

7.Click on Phone and select Dial.

8.When the connection has been established perform login.

9.Type a "U" to upload a file or a "D" to download a file.

10.Type the modem protocol type. The most common protocols are Kermit, Xmodem and Ymodem. Use these protocols along with a mixture of the others.

11.Type the file name.

12.To begin the file transfer, click on Transfers. Select Send Binary Files for uploads or Receive Binary Files for downloads.

13.Verify that the file transfer has completed.

14.From the OS/2 session of the receiving machine, verify that the date/ time stamp of the file just received is current and the size of the file has not changed.

15.Send and receive at least three files changing modem types.

Note:Verify that video corruption does not occur in all operations.

DOS Compatibility Application Test

The following test performs OS/2 video device driver testing using DOS- applications (DOOM**)

Note:In this scenario, selectingmeans using the arrow keys and [Enter] to select.

1.Install DOOM (if not previously installed).

Note:If you do not have DOOM installed, refer to your DOOM Installation Manual for installation instructions.

2.Start the application by typing DOOM on OS/2 command line.

3.Press [ENTER] or [ESC] to get to the main menu.

4.Select READ THIS to get information about the application and then press [ENTER] to see instructions of the control keys.

5.Press [ENTER] to get back to the main menu.

6.Select NEW GAME.

7.Select episode.

8.Select skill level.

9.Use the arrow keys for moving and [Ctrl] key for shooting.

Note:Try also switching to the OS/2 desktop by pressing [Ctrl+Esc] and then come back by selecting DOOM.EXE from the window list. Verify that in all above operations, video corruption does not occur.

10.Press [F7] to quit (and "Y" to confirm).

11.To exit, press [F10] or select QUIT GAME from the main menu.

Note:Verify that in all above operations, video corruption does not occur .

OS/2 Test Suite

The OS/2 test suite consists of

1.Multimedia Compatibility Application Test
2.Multiple OS/2 Applications test

Multimedia Compatibility Application Test

Multimedia compatibility application test tests Multimedia applications to ensure compatibility.

Applications

Digital Video applet, included in OS/2 Multimedia. For this test, a clean OS/2 install should be done for every video device driver tested (or press [Ctrl+Alt+F1] during boot-up to reset the desktop). During the test session , make sure to press [Ctrl+Esc] to switch between the desktop and the applications while running test. Repeat the process at different stages of the application.

Required Hardware

�An 80386 SX (or higher) 32-bit microprocessor.

�At least 4MB of random access memory (RAM). The recommended size is 6MB or greater. In addition to the recommended 6MB of system memory to install OS/ 2, you need another 2MB to install multimedia support. You also need up to an additional 5MB of hard disk space.

For additional information on MMPM/2 installation and usage, refer to the OS/2 Installation Guide and OS/2 Using The Operating System manual. If you install the Software Motion Video feature, you can play movie files.

To play a movie

1.Open the Multimedia folder.

2.Select the Digital Video icon.

3.Select File from the Menu bar.

4.Select Open... from the File menu.

5.Select a file with the extension .AVI (for example, MACAW.AVI).

6.Select OK to load file.

7.Select the Play button to play file.

8.Move the window to different positions while the movie is playing.

9.Continue to monitor and verify that video corruption does not occur.

Multiple OS/2 Applications test

This test group executes different OS/2 applications to test the OS/2 video device driver.

The following applications are tested:

�CorelDRAW** Version 2.5

�Lotus** 123 Version 2.0

�AutoCAD** Release 10 c-14

Testing Video Device Drivers using CorelDraw Version 2.5

CorelDRAW version 2.5 is a 32-bit Presentation Manager* application that has multiple graphical tools. Corel** provides utilities such as CorelCHART **, CorelTRACE**, and CorelPAINT**. It also accepts various import and export formats such as PCX, TIFF, BMP, PIC, and GEM**. A mosaic visual file manager lets the user see the files in a bit map before opening them.

Conventions

�Throughout this scenario, keys to be pressed are denoted by brackets ([ ]) , such as [F9], [Ctrl+PgDn].

�Cursor keys are denoted by [Up], [Down], [Left] and [Right].

�A string of characters is denoted by quotations (" "), such as "CD\FP".

�Typographical mistakes can be fixed with the backspace key.

�If the instructions state to selectan item, move the cursor to that item and press [Enter].

�When asked to select an item such as Menu | Item, click on each item in left to right order.

Begin Test

Corel Utilities

1.Open the folder with the Windows Corel icon. If you do not have CorelDRAW installed, refer to your CorelDRAW Installation Manual for instructions.

2.Open and close every icon in the folder except CorelDRAW and MOSAIC.EXE. Note that CCAPTURE.EXE has no menu bar. To close CCAPTURE.EXE, press [Alt+ F4].
Mosaic and CorelDraw

1.Double-click on MOSAIC.EXE.

2.Double-click on DART.CDR. CorelDRAW is started.

3.Select Display | Show Preview.

4.Press [F9] to see the full screen view. Press [Enter] to continue.

5.Click on the maximize button to maximize the screen.

6.Select File | Open...

7.Scroll and select SEASIDE.CDR. A sketch of the drawing is displayed on the right side.

8.Click on Open to display the drawing.

Verify that video corruption does not occur in all operations.

Edit

Importing a GIF File

1.Select File | New...

2.Select File | Import...

3.Scroll and select .GIF format; select OK.

4.Change to the \TESTBETA\GRAPHICS\PICTURES directory.

5.Select 800x600.GIF and select Open.

6.Drag the bottom-right dot toward the lower-right corner of the drawing. The picture is enlarged.

Adding Text to Drawing

1.Select File | Open...

2.Scroll and select SEASIDE.CDR. A sketch of the drawing is displayed on the right side.

3.Click on Open to display the drawing.

4.Click on the text icon (the letter A) in the toolbox. The word Text is displayed at the top.

5.Move the '+' pointer to the top middle of the drawing and click at that location. A TEXT dialog box appears.

6.Type "This is my drawing" at the cursor in the input box.

7.Highlight Avalon as the font name. Try a different font each time.

8.Click on Bold-Italic at(?) bottom.

9.Scroll up the point size to 40. Try a different point size each time.

10.Finally, select OK to show the text. The preview screen will show the text in bold, italic, and 40-point size.

11.Click on the arrow icon in the toolbox. The text is selected.

12.Drag the left middle dot to the left edge on the drawing. The words are stretched out.

Verify that video corruption does not occur in all operations.

Graphical Editing

1.Select the light pole (left of the .CDR file).

2.Select Edit | Duplicate. There are two light poles together. One pole is still selected.

3.Drag the selected pole to about half way toward the left side of the drawing.

4.Select Transform | Rotate and Skew...

5.Change the Rotation Angle to 90.0 degree and select OK. The pole should be sideways.

6.Select Edit | Select All...

7.Select Transform | Stretch and Mirror...

8.Change both horizontal and vertical to 75% and then select OK. The picture is resized.

Save and Retrieve a Drawing

1.Select File | Save As...

2.Type "MINE.CDR" as the file name and click on Save.

3.Select File | Exit.

4.Make the Mosaic window active. MINE.CDR is one of the selections.

5.Double-click on MINE.CDR to bring it up.

6.Press [F9] to view the file in full screen.

7.Press [Enter] to continue.

8.Select Edit | Select All.

9.Select Arrange | Group. There are over 100 objects in the drawing.

10.Select File | About CorelDraw!...

11.Select OK to remove the title page.

Finishing

Exiting and Cleaning Up

1. Select File | Exit to exit CorelDRAW.
2. Select NO to save changes in MINE.CDR.
3. Make the MOSAIC window active.
4. Select File | Exit to exit MOSAIC.
5. Open a OS/2 Full Screen or OS/2 Window.
6. Change to the \COREL32 directory.
7. Delete the file MINE.CDR.

Verify that video corruption does not occur in all operations.

Testing Video Device Drivers Using LOTUS 123

This section describes a nonexhaustive test of the 16-bit Lotus 123 for OS/ 2.

Conventions

• Throughout this procedure, keys to be pressed are denoted by brackets ([ ] ), such as [F9], [Ctrl+PgDn].
• A string of characters is denoted by quotations (" "), such as "\FIRST". If instructed to type "string", type the string without the quotes.
• Directory references are relative to the root directory, and are not drive -specific. The drive on which the application is installed is implied.
• Lotus 123 for OS/2 uses a graphical user interface with window and menu displays. This test case uses the convention MainMenuItem | SubMenuItem. Select the MainMenuItem first, the SubMenuItem second.

Installing LOTUS 123

Note:If you do not have LOTUS 123 installed, refer to your LOTUS 123 Installation Manual for instructions.

Starting Lotus 123

1.Double-click on the 123 folder on the desktop.

2.Double-click on the 123 icon to start the program.

3.Click on the Maximize button once the application appears on the screen.

Getting Help

1.Select Help. A help window appears with WORKSHEET on the menu bar.

2.Click on How do I...; the text screen displays the information.

3.Click on Previous to go back.

4.Click on Graph Tool. The mouse pointer changes to a ? on the text screen .

5.Click on Cancel to exit the help window.

Working with a Spreadsheet

Create a Spreadsheet

1.Make A1 the active cell.

Note:To make a cell active, click once on that cell.

2.Type "Salary" and press [Down] to enter text for A1.

3.Type "Inventory" and press [Down] to enter text for A2.

4.Type "Overhead" and press [Down] to enter text for A3.

5.Press [Down], type "Total Expenses" and press [Down] to enter text for A5.

6.Press [Down], type "Revenues" and press [Down] to enter text for A7.

7.Press [Down], type "Operating Income" and press [Enter] to enter text for A9.

8.Make B1 the active cell.

9.Type "192000" and press [Down] to enter a value for B1.

10.Type "95000" and press [Down] to enter a value for B2.

11.Type "87000" and press [Enter] to enter a value for B3.

12.Make B7 the active cell.

13.Type "995000" and press [Enter] to enter a value for B7.

Verify that video corruption does not occur in all operations.

Formatting the Spreadsheet

1.Select cells B1-B9 by dragging from B1 to B9.

2.Select Copy...

3.Click on the To: box.

4.Type "A: C1" and select OK.

5.Select the first column by clicking on the letter A at top of the column .

6.Select Worksheet | Column...

7.Click on the box with the current column width. The default should be 9.

8.Change the width to 18 and then select OK. The text should fit properly in the column.

9.Select columns B and C by clicking on the letter B and dragging across to the letter C.

10.Repeat steps 5 and 6 and change the column width to 12.

11.Select Range | Format...

12.Select Currency and then select OK. The cells are formatted as currency.

Building a Formula

1.Make B5 the active cell.

2.Type "+b1+b2+b3" and press [Enter]. B5 should contain the sum of b1 through b3.

3.Make B9 the active cell.

4.Type "+b7-b5" and press [Enter]. B9 should contain the updated income. B9 should still be active.

5.Select Copy...

6.Click on the To: box.

7.Change the entry to "A: C9" and click on Options.

8.Make sure Formulas is selected and select OK.

9.Select OK to complete the copy. Note that B9 and C9 are different.

10.Follow steps 5 and 6 to copy B5 to C5. C9 has changed.

Editing Information

1.Select row 1 by clicking on the number 1 on the first row.

2.Select Worksheet | Insert...

3.Select Row and select OK.

4.Make B1 the active cell.

5.Type " '1992 Forecast" and press [Right].

6.Type " '1992 Actual" and press [Enter].

7.Make C2 the active cell.

8.Type "195000" and press [Down].

9.Type "96000" and press [Enter]. The Total Expenses and Operating Income changed each time.

Working with Graphs

Creating a Graph

1.Select cells A1 to C10 by dragging the mouse from A1 through C10.

2.Select Graph | Options | Titles...

3.Click on the First box and type "Test Graph".

4.Press [Tab], type "Lotus 123", and then select OK.

5.Select Graph | View. The SHEET.GPH is shown. Note that the blue line is not visible because it is overlapped by the red line.

Changing a Graph Type

1.Resize both the worksheet and the graph window so that both of them are side by side.

2.Make sure the highlighted area (A1 to C10) is shown in the smaller window.

3.Make the graph window active.

4.Select Type | Bar to see a bar graph.

5.Select Type | Area to see a area graph.

6.Select Type | Pie to see a pie graph.

7.Select Type | 3-D Bar to see a 3-D bar graph. The legends are tangled together.

8.Select Type | Bar to show a bar graph again.

9.Make the worksheet window active.

10.Make C8 the active cell.

11.Type "600000" and press [Enter]. The red bar in the bar graph is shorter .

12.Make B8 the active cell.

13.Type "300000" and press [Enter]. The blue bar of Operating Income is negative.

14.Make the graph window active.

15.Select Layout | Printer View. The window will show a full page preview of the graph.

16.Select Type | Horizontal. The graph is flipped sideways.

17.Select Layout | Window View to get a closer look.

18.Close the SHEET1.GPH without saving any changes.

Macro

Creating a Macro

1.Maximize the worksheet window.

2.Make E1 the active cell.

3.Select Range | Name | Create...

4.Type "\A" and select OK. [Ctrl + A] is the hot key for this macro. E1 should still be active.

5.Type " '/rgb2~20000{D}1500{D}2000{R}3500{U}5000{U}55000~" and press [ Down].

6.Type " '/rga12~Macro is finished!!!~" and press [Down].

7.Type " '{QUIT}" and press [Enter] to indicate the end of this macro.

Running the Macro

1.Make A1 the active cell.

2.Press [Ctrl+A] to start the macro. Cells B2 through C4 are changed and the totals are updated.

Finishing

Exiting and Cleaning Up

1.Click on the system icon and select Close.

2.Select NO to not save SHEET1.WG2.

Verify that video corruption does not occur in all operations.

Testing Video Device Drivers Using AutoCAD Release 10 c-14

AutoCAD is a general purpose Computer Aided Design (CAD) program. Use AutoCAD to create a variety of two-dimensional drawings and three- dimensional models. Drawings prepared with AutoCAD are stored in data files that contain information about locations, sizes, colors, and attributes of objects you draw. These data files can be easily retrieved for viewing, editing, or plotting.

AutoCAD provides simple commands (such as "circle" and "line") to let you construct your drawing. The program also prompts you for information it needs to place an object at a specific location in the drawing. Commands are also provided to edit drawings and to view objects from different perspectives.

The OS/2 version of AutoCAD is designed to work with the window-based graphics interface of the Presentation Manager.

System Requirements

�OS/2 (version 1.1 or later with Presentation Manager)

�At least 4 megabytes of memory (6MB is recommended)

�An Intel** 80387 Numeric Coprocessor.

�A mouse is strongly recommended (but not required).

Conventions

�Throughout this scenario, keys to be entered are denoted by brackets ([ ]) , such as [F9], [Ctrl+PgDn].

�Cursor keys are denoted by [Up], [Down], [Left] and [Right].

�A string of characters is denoted by quotations (" "), such as "CD\FP" and "C: \FIRST".

�Any typographical mistakes can be fixed with the Backspace key.

�If the instructions state to selectan item, move the cursor to that item and press [Enter].

�When asked to select an item such as menu | item, click on each item in left to right order.

Note:If you do not have AutoCAD installed, refer to your AutoCAD Installation Manual for instructions.

Starting and Testing AutoCAD

1.Reboot your system and select OS/2 Full Screen when the Group-Main menu is displayed.

2.At the OS/2 prompt, change to the drive where AutoCAD is, and type "CD\ ACAD".

3.Press [Enter].

4.Type "ACAD" and press [Enter] to load AutoCAD. The AutoCAD drawing screen is displayed.

5.Select File from the action bar.

6.Select Open from the pull-down menu.

7.Select COLORWH.DWG from the list of files in the right column of the dialog box.

8.Press [OK] The AutoCAD Color Wheel should be displayed.

9.Select File from the action bar, and select Close from the pull-down menu.

10.Select DISCARD from the dialog box.

Viewing Existing Drawings

Using ZOOM

1.Select File from the action bar, then select Open... from the pull-down menu. The Select drawing file dialog box is displayed.

2.Select the file AIRPLANE.DWG. A 3D wireframe model of an airplane is displayed in plane view(as if you are looking from above, straight down on the airplane).

3.At the Command: prompt, type "ZOOM" and press [Enter].

4.At the All/Center... prompt, type "W" and press [Enter]. This will let you enclose the area to be zoomed in a window.

5.At the First Corner: prompt, move the crosshairs to the upper left of the airplane's tail. The coordinates displayed on the status line above the drawing should be approximately 13,23.

6.Press the left button of the mouse to select this point.

7.At the Other Corner: prompt, move the cursor until the box encloses a portion of the airplane's tail. The coordinates displayed on the status line above the drawing should be approximately 22,18.

8.Press the left button of the mouse to select this point. The screen is redrawn with only the zoomed portion of the tail of the airplane shown.

9.At the Command: prompt, type "ZOOM" and press [Enter].

10.At the All/Center... prompt, type "P" to display the previous view of the airplane and press [Enter]. The original view of the airplane is displayed.

Using VPOINT

1.At the Command: prompt (with the airplane still displayed), type " VPOINT" and press [Enter].

2.At the Rotate... prompt, type "1,-1,1" and press [Enter]. These values represent x, y and z coordinates. The airplane is redrawn with the nose pointing in a southwest direction.

3.At the Command: prompt, type "VPOINT" and press [Enter].

4.At Rotate... prompt, type "0,1,1" and press [Enter]. The airplane is redrawn with the nose pointing north.

5.At the Command: prompt, type "VPOINT" and press [Enter].

6.At the Rotate... prompt, type "R" to select rotate.

7.At the Enter angle... prompt, type "30" and press [Enter].

8.At the next Enter angle... prompt, type "50" and press [Enter]. The airplane is redrawn with the nose pointing in a northwest direction.

9.At the Command: prompt, type "QUIT" and press [Enter].

10.Type "Y" to discard changes. The AutoCAD drawing screen is blanked.

Verify that video corruption does not occur in all operations.

Using DVIEW

1.Select File from the action bar of the AutoCAD drawing screen, and select Open... from the pull-down menu.

2.Select the file HOUSE.DRW from the file list in the Select drawing file dialog box. A hip-roofed house is displayed.

3.At the Command: prompt, type "DVIEW" and press [Enter].

4.At the Select objects... prompt, select a point below and to the left of the lower left-hand corner of the roof edge. The coordinates on the status line above the drawing should be approximately 27'-0",25'-0".

5.At the next Select objects... prompt, select a point above and to right of the upper right-hand corner of the roof edge. The coordinates on the status line above the drawing should be approximately 80'-0",64'-0".

6.At the next Select Objects... prompt, press [Enter].

7.At the Camera/Target... prompt, type "PO" to select target points.

8.At the Enter target point... prompt, select a point at the middle of the house. The coordinates on the status line above the drawing should be approximately 55'-7", 41'-11".

9.At the Enter camera point... prompt, type "@35' < 270" to indicate a distance of 35 feet at a 270 degree rotation and press [Enter].

10.At the Camera/Target ... prompt, press [Enter]. The house is redrawn as if you were facing the front of the house with the door directly in front of you and the chimney at the right edge of the house.

Using VPorts

1.At the Command: prompt, type "VPORTS" and press [Enter].

2.At the Save/Restore... prompt, type "4" and press [Enter]. The screen is redrawn, divided into separate viewports containing the same drawing.

3.At the Command: prompt, type "QUIT" and press [Enter].

4.At the Really want to quit.. prompt, type "Y" and press [Enter].

Preparing a 2-D Drawing

Note: Making Corrections:In the sections that follow, you will create a 2 -dimensional drawing and add dimensions to it. If you make an error while entering information for a command, you can cancel that command by pressing [Ctrl+C]. If you have completed a command and you wish to undo it, type "U" .

Drawing a Border

1.On the AutoCAD drawing screen, select Utilities from the action bar.

2.Select File Utilities from the File pull-down menu. The File Utility Menu is displayed.

3.At the Enter selection... prompt, type "2" and press [Enter].

4.At the Enter file search specification... prompt, type "*.DWG" and press [Enter]. If the name D1.DWG appears on the list, go to step 5. Otherwise, skip step 5 and go to step 6.

5.At the Enter selection prompt, type "3" and press [Enter].

6.At the Enter file deletion specification... prompt, type "D1.DWG" and press [Enter]. The file is now deleted.

7.Press [Enter] and the File Utility Menu is redisplayed.

8.At the Enter selection prompt, press [Enter] to take the default.

9.On the AutoCAD drawing screen, select File from the action bar, and then select New from the pull-down menu. The Create drawing file dialog box is displayed.

10.At the Current file line, backspace over the name (if any) that is in the Current file field and type "D1" ; then press [Enter].

11.At the Command: prompt, type "UNITS" and press [Enter]. The AutoCAD Text -D1 screen is displayed.

12.At the Enter choice... prompt, press [Enter] to accept the default ( decimal).

13.At the Number of digit... prompt, type "1" and press [Enter].

14.Press [Ctrl+Break] to skip the rest of the questions. The AutoCAD-D1 drawing screen is redisplayed.

15.At the Command: prompt, type "SNAP" and press [Enter].

16.At the Snap spacing... prompt, type "0.5" and press [Enter].

17.At the Command: prompt, type "GRID" and press [Enter] to set the grid spacing.

18.At the Grid spacing... prompt, type "S" and press [Enter] to set the grid spacing to the snap spacing. Now when you move the cursor, it will snap between points on the grid.

19.At the Command: prompt, type "UCSICON" and press [Enter].

20.Then type "OFF" and press [Enter] to remove the icon at the far left of your drawing.

21.At the Command: prompt, type "ORTHO" and press [Enter].

22.At the ON/OFF prompt, type "ON" and press [Enter.].

23.Press [F3] to turn on the coordinates on the status line.

24.At the Command: prompt, type "PLINE" and press [Enter].

25.At the From point: prompt, move the cursor until the coordinates on the status line read 0.5,0.5 and select that point.

26.At the Arc/Close.. prompt, type "W" to set the width of the line and press [Enter].

27.At the Starting width... prompt, type "0.03" and press [Enter]. Press [ Enter] on the Ending width prompt.

28.At the Arc/Close... prompt, move the cursor to the right until the coordinates on the status line above the drawing read 11.0<0 and select that point.

29.At the next Arc/Close... prompt, move the cursor straight up until the coordinates on the status line above the drawing read 8.0<90, and select that point.

30.At the next Arc/Close... prompt, move the cursor horizontally to the left until the coordinates on the status line read 11.0<180, and select that point.

31.At the next Arc/Close... prompt, type "C" and press [Enter]. The rectangular border is now complete.

Drawing Rectangles and Squares

1.At the Command: prompt, type "LINE" and press [Enter].

2.At the From point: prompt, move the cursor to the lower left hand of the rectangular box until the coordinates read 2.5, 2.0, and select that point.

3.At the To point: prompt, move the cursor to the right until coordinates read 3.0 < 0 and select that point.

4.Execute different OS/2 applications to test the OS/2 video device driver .

5.At the next To point: prompt, move the cursor up until the coordinates read 0.5<90 and select that point.

6.At the next To point: prompt, move the cursor to the left until the coordinates read 2.5<180 and select that point.

7.At the next To point: prompt, move the cursor upward until the coordinates read 1.5<90 and select that point.

8.At the next To point: prompt, move the cursor to the left until the coordinates read 0.5<180 and select that point.

9.At the next To point: prompt, type "C" and press [Enter] to close the outline. The front view of the drawing is complete.

10.To start drawing the right view, at the Command: prompt, type "POLYGON" and press [Enter].

11.At the Number of sides: prompt, type "4" and press [Enter].

12.At the Edge/Center... prompt, type "E" and press [Enter].

13.At the First endpoint.. prompt, move the cursor along the lower edge of the right view you just drew until the coordinates read 7.5,2.0 and select that point.

14.At the Second endpoint... prompt, move the cursor until the coordinates read 9.5,2.0 and select that point. The square part of the right view is completed.

15.At the Command: prompt, press [Enter] to use the polygon command again.

16.At the Polygon Number of sides... prompt, type "4" and press [Enter].

17.At the Edge/Center.. prompt, type "E" and press [Enter].

18.At the First endpoint... point prompt, move the cursor to the upper left until the coordinates read 2.5,5.0 and select that point.

19.At the Second endpoint... point prompt, move the cursor to the right until the coordinates read 4.5,5.0 and select that point. The figure is completed.

Using the Explode Command

1.At the Command: prompt, type "SNAP" and press [Enter].

2.At the Snap spacing... prompt, type "OFF" and press [Enter].

3.At the Command: prompt, type "ZOOM" and press [Enter].

4.At the All/Center... prompt, type "W" and press [Enter].

5.At the First corner... prompt, move the cursor to just below and to the lower left corner of the top view until coordinates read 2.0,4.5 and select that point.

6.At the Other corner... prompt, move the cursor to the upper right until the coordinates read approximately 5.0,7.5 and select that point. The screen is redrawn with the square enlarged.

7.At the Command: prompt, type "EXPLODE" and press [Enter].

8.At the Select block... prompt, use the cursor to move the tiny selection box to any side of the square and select the side. The square is now " exploded" so you can erase individual parts of the square without erasing all of it.

9.At the Command: prompt, type "ERASE" and press [Enter].

10.At the Select objects... prompt, move the cursor to the right side of the square and select it. The side becomes a dotted line.

11.At the Select objects... prompt, press [Enter] and the right edge is erased.

12.At the Command: prompt, type "SNAP" and press [Enter].

13.At the Snap spacing... prompt, type "ON" and press [Enter].

14.At the Command: prompt, type "LINE" and press [Enter].

15.At the From point... prompt, move the cursor to the lower left corner of the top view until the coordinates read 3.0,5.0 and select that point.

16.At the To point... prompt, move the cursor up until the coordinates read 2.0<90 and select that point.

17.Press [Enter].

18.At the Command: prompt, press [Enter] to use the line command again.

19.At the Line From... prompt, move the cursor downward until the coordinates read 3.0,6.5 and select that point.

20.At the To point... prompt, move the mouse to the left until the coordinates read 0.5<180 and select that point.

21.Press [Enter].

22.At the Command: prompt, press [Enter] to use the line command again.

23.At the Line From point... prompt, move the cursor down the left edge of the figure until the coordinates read 2.5,5.5 and select that point.

24.At the To point... prompt, move the cursor to the right until the coordinates read 0.5<0 and select that point.

25.Press [Enter].

26.At the Command: prompt, type "ZOOM" and press the spacebar.

27.At the All/Center... prompt, type "D" and press [Enter]. The entire 3- part drawing will be displayed with a large selection box with an X at the center.

28.Move the cursor to the lower right until the box with the X is centered over the right view square. When the coordinates read 8.5,3.0, select this point.

29.Press [Enter]. The screen is redrawn to display an enlarged view of the right view square.

30.At the Command: prompt, type "EXPLODE" and press [Enter].

31.At the Select block... prompt, move the cursor to any side of the square and select that side.

32.At the Command: prompt, type "LINE" and press [Enter].

33.At the From point... prompt, move the cursor toward the lower left corner of the right view until the coordinates read 7.5,2.5, and select that point.

34.At the To point... prompt, move the cursor to the right until the coordinates read 2.0<0, and select that point.

35.Press [Enter] to end that line command.

36.At the Command: prompt, press [Enter] to use the line command again.

37.At the Line from point: prompt, move the cursor toward the upper left corner of the figure until the coordinates read 8.0,4.0, and select that point.

38.At the To point: prompt, move the cursor down one grid point until the coordinates read 0.5<270, and select that point.

39.Press [Enter] to end the line command.

40.At the Command: prompt, press [Enter] to use the line command again.

41.At the Line from point: prompt, move the cursor across the top of the figure until the coordinates read 9.0,4.0, and select that point.

42.At the To point: prompt, move the cursor down one grid point until the coordinates read 0.5<270, and select that point.

43.Press [Enter] to end the line command.

44.At the Command: prompt, type "ZOOM" and press the spacebar.

45.At the All/Center... prompt, type "A" and press [Enter].

Verify that video corruption does not occur in all operations.

Drawing Arcs and Circles

1.At the Command: prompt, type "ELLIPSE" and press [Enter].

2.At the Axis endpoint 1 prompt, move the cursor toward the lower-right edge of the top view until the coordinates read 4.5,5.5, and select that point.

3.At the Axis endpoint 2 prompt, move the cursor up two grid points until the coordinates read 1.0<90, and select that point. You will see the outline of a small circle.

4.At the Other axis.. prompt, select the same point as in the preceding step.

5.At the Command: prompt, type "ARC" and press [Enter].

6.At the Center/start point prompt, type "C" and press [Enter].

7.At the Center: prompt, move the cursor to the center of the circle until the coordinates read 4.5,6.0, and select that point.

8.At the Start point: prompt, move the cursor until the coordinates read 4 .5,5.0, and select that point.

9.At the Angle/Length... prompt, move the cursor upward through the circle until the coordinates read 1.0<90 and select that point. The arc is completed.

10.At the Command: prompt, press [Enter] to use the arc command again.

11.At the Arc: Center/Start... prompt, move the cursor toward the right view until the coordinates read 8.0,3.5 and select that point.

12.At the Center/End... prompt, type "C" and press [Enter].

13.At the Center: prompt, move the cursor to the right until the coordinates read 8.5,3.5, and select that point.

14.At the Angle/Length... prompt, move the cursor to the right until the coordinates read 0.5<0 and select that point. The arc is completed.

15.At the Command: prompt. type "ZOOM" and press spacebar.

16.At the All/Center... prompt, type "W" and press [Enter].

17.At the First corner... prompt, move the cursor toward the lower right corner of the right view until the coordinates read 7.0,1.5, and select that point.

18.At the Other corner... prompt, move the cursor until the coordinates read 10.0,4.5, and select that point. The screen is redrawn with the figure enlarged.

19.At the Command: prompt, type "ARC" and press [Enter].

20.At the Center/Start.. prompt, type "C" and press [Enter].

21.At the Center: prompt, move the cursor until the coordinates read 8.0,3. 5, and select that point.

22.At the Start point: prompt, move the cursor until the coordinates read 8 .0,4.0 and select that point.

23.At the Angle/Length... prompt, move the cursor until the coordinates read 0.5<180 and select that point. The arc is completed.

24.At the Command: prompt, press [Enter.] to use the arc command again.

25.At the ARC Center/Start... prompt, type "C" and press [Enter].

26.At the Center: prompt, move the cursor to the right until the coordinates read 9.0,3.5 and select that point.

27.At the Start point: prompt, move the cursor until the coordinates read 9 .5,3.5, and select that point.

28.At the Angle/Length... prompt, move the cursor up and to the left until the coordinates read 0.5<90, and select that point. The arc is completed.

29.At the Command: prompt, type "SNAP" and press [Enter].

30.At the Snap spacing... prompt, type "OFF" and press[Enter].

31.At the Command: prompt, type "ERASE" and press [Enter].

32.At the Select objects: prompt, move the cursor to the middle of the top line ( at approximately 8.5,4.0) select that line. The line becomes dotted.

33.At the next Select objects: prompt, press [Enter] and the line is erased .

34.At the Command: prompt, type "TRIM" and press [Enter].

35.At the Select cutting... Select objects... prompt, type "l" (to select the last item drawn) and press [Enter].

36.At the Select objects: prompt, move the cursor to the upper left corner (at approximately 7.7,3.8), and select that arc.

37.Press [Enter] to complete selection of the boundaries for the trim.

38.At the Select object to trim: prompt, move the cursor to the top of the line at the upper right edge of the figure (at approximately 9.5,4.0) and select that point. The line is now trimmed back to the arc.

39.At the next Select object to trim: prompt, move the cursor to the top of the line at the upper left edge of the figure (at approximately 7.5,4.0) and select that point. That line is now trimmed back to the arc.

40.At the next Select object to trim: prompt, press [Enter] to end the trim command.

41.At the Command: prompt, type "ZOOM" and press the spacebar.

42.At the All/Center.. prompt, type "A" and press [Enter]. The figure is redrawn with all three views shown.

Using Layers and Hidden Lines

1.At the Command: prompt, type "LAYER" and press [Enter].

2.At the ?/Make... prompt, type "M" and press [Enter].

3.At the New current layer: prompt, type "HIDDEN" and press [Enter].

4.At the ?/Make... prompt, type "l" ( for line type ) and press [Enter].

5.At the Linetype (or ?)... prompt, type "OHIDDEN" and press [Enter] to select the hidden line type.

6.At the Layer name(s)... prompt, press [Enter] to set the line type hidden.

7.At the ?/Make... prompt, press [Enter] to end the layer command.

8.At the Command: prompt, type "SNAP" and press [Enter].

9.At the Snap spacing... prompt, type "ON" and press [Enter].

10.At the Command: prompt, type "LINE" and press [Enter].

11.At the From point: prompt, move the cursor to the lower left corner of the right view until the coordinates read 8.0,2.0, and select that point.

12.At the To point: prompt, move the cursor up until the coordinates read 0 .5<90, and select that point.

13.At the next To point: prompt, press [Enter] to end the line command.

14.At the Command: prompt, press [Enter] to use the line command again.

15.At the LINE from point: prompt, move cursor to the right until the coordinates read 9.0,2.5,and select that point.

16.At the To point: prompt, move the cursor down until the coordinates read 0.5<270, and select that point.

17.At the next To point: prompt, press [Enter] to end the line command.

18.At the Command prompt, press [Enter] to use the line command again.

19.At the LINE from point: prompt, move the cursor toward the lower right edge of the front view until the coordinates read 5.0,2.0, and select that point.

20.At the To point: prompt, move the cursor up until the coordinates read 0 .5<90, and select that point.

21.At the next To point: prompt, press [Enter] to end the line command.

22.At the Command: prompt, press [Enter] to use the line command again.

23.At the Line from point: prompt, move the cursor to the left until the coordinates read 4.0,2.5, and select that point.

24.At the To point: prompt, move the cursor down until the coordinates read 0.5 < 270, and select that point.

25.At the next To point: prompt, press [Enter] to end the line command.

26.At the Command: prompt, press [Enter] to use the line command again.

27.At the LINE from point: prompt, move the cursor until the coordinates read 2.5,3.0, and select that point.

28.At the To point: prompt, move the cursor until the coordinates read 0.5< 0, and select that point.

29.At the next To point: prompt, press [Enter] to end the line command.

30.At the Command: prompt, type "SNAP" and press [Enter].

31.At the Snap spacing... prompt, type "OFF" and press [Enter].

32.At the Command: prompt, type "TSCALE" and press [Enter].

33.At the New scale... prompt, type "0.6" and press [Enter].

34.At the Command: prompt, type "LAYER" and press [Enter].

35.At the ?/Make... prompt, type "S" and press [Enter].

36.At the New current layer... prompt, type "0" and press [Enter].

37.At the ?/Make... prompt, press [Enter] to end the layer command. The layer shown on the status line should now be 0 instead of HIDDEN.

38.Select the AutoCAD pull-down menu from the title bar icon, and select Close from the pull-down menu.

39.Select Save from the QUIT AutoCAD window.

Adding Dimensions to a Drawing

1.From the Group-Main menu, select AutoCAD.

2.From the AutoCAD drawing screen, select File from the action bar, and then select Open from the pull-down menu.

3.From the Select drawing file dialog box, select D1.DWG.

4.At the Command: prompt, type "LAYER" and press [Enter].

5.At the ?/Make... prompt, type "M" and press [Enter].

6.At the New current layer: prompt, type "DIM" and press [Enter].

7.At the ?/Make... prompt, press [Enter]. The word DIM is now next to Layer on the status line above the drawing.

8.At the Command: prompt, type "ZOOM" and press [Enter].

9.At the All/Center... prompt, type "W" and press [Enter].

10.At the First corner: prompt, move the cursor toward the left edge of the drawing until the coordinates read 1.2, 5.7, and select that point.

11.At the Other corner: prompt, move the cursor toward the right until the coordinates read 7.3, 1.5, and select that point. The screen is redrawn with an enlarged view of the front view and part of the top view.

12.At the Command: prompt, type "DIM" and press [Enter].

13.At the Dim: prompt, type "VER" and press [Enter].

14.At the First extension... prompt, press [Enter].

15.At the Select line... prompt, move the cursor toward the left edge of the front view until the coordinates read 2.5, 2.5, and select that point.

16.At the Dimension line location: prompt, move the cursor until the coordinates read 1.8, 3.0, and select that point.

17.At the Dimension text <2.0>... prompt, press [Enter] to accept the value of 2.0 for the dimension. The vertical dimension command is now completed.

18.At the Dim: prompt, type "HOR" and press [Enter].

19.At the First extension... prompt, press [Enter].

20.At the Select line... prompt, move the cursor until the coordinates read 2.7, 4.0, and select that point.

21.At the Dimension line... prompt, move the cursor until the coordinates read 2.7, 4.3, and select that point.

22.At the Dimension text <0.5>... prompt, press [Enter] to accept the value of 0.5 for the dimension.

23.At the Dim: prompt, type "VER" and press [Enter].

24.At the First extension... prompt, press [Enter].

25.At the Select line... prompt, move the cursor toward the right edge of the front view until the coordinates read 5.5, 2.2, and select that point.

26.At the Dimension line... prompt, move the cursor until the coordinates read 6.0, 2.7, and select that point.

27.At the Dimension text <0.5>... prompt, press [Enter] to accept the value of 0.5 for dimension.

28.At the Dim: prompt, press [Ctrl+C] to leave the Dim subcommands.

Verify that video corruption does not occur in all operations.

Adding Center Lines

1.At the Command: prompt, type "SNAP" and press [Enter].

2.At the Snap spacing... prompt, type "ON" and press [Enter].

3.At the Command: prompt, type "GRID" and press [Enter].

4.At the Grid spacing... prompt, type "S" and press [Enter].

5.At the Command: prompt, type "LAYER" and press [Enter].

6.At the ?/Make... prompt, type "M" and press [Enter].

7.At the New current layer... prompt, type "CENTER" and press [Enter].

8.At the ?/Make... prompt, type "l" and press [Enter].

9.At the Linetype... prompt, type "CENTER" and press [Enter].

10.At the Layer Names(s)... prompt, press [Enter].

11.At the ?/Make... prompt, press [Enter]. The status line above the drawing now shows CENTER following Layer.

12.At the Command: prompt, type "SNAP" and press [Enter].

13.At the Snap spacing... prompt, type "OFF" and press [Enter].

14.At the Command: prompt, type "LINE" and press [Enter].

15.At the From point: prompt, move the cursor until the coordinates read 4. 5,3.0, and select that point.

16.At the To point: prompt, move the cursor until the coordinates read 1.4< 270, and select that point.

17.At the next To point: prompt, press [Enter] to end the line command.

18.At the Command: prompt, press [Enter] to use the line command again.

19.At the LINE from point: prompt, move the cursor until the coordinates read 3.5,3.5, and select that point.

20.At the To point: prompt, move the cursor until the coordinates read 1.4< 180, and select that point.

21.At the next To point: prompt, press [Enter] to end the line command.

22.Select Settings from the action bar to change back to DM layer. Then select Modify layer from the pull-down menu.

23.When the Modify layer dialog box is displayed, select the Current box to the left of DIM, and then select OK.

24.The word DIM is now displayed next to layer on the status line above the drawing.

25.At the Command: prompt, type "ZOOM" and press [Enter].

26.At the All/Center... prompt, type "D" and press [Enter]. The screen is redrawn showing all three views.

27.Move the cursor until the box with X is positioned over the top view ( the coordinates read approximately 4.5,6.0) and press [Enter]. The screen is redrawn showing the top view enlarged.

28.At the Command: prompt, type "DIM" and press [Enter].

29.At the Dim: prompt, type "DIMCEN" and press [Enter]. The current value displayed is <0.1>.

30.At the New value: prompt, type "-0.1" and press [Enter].

31.At the Dim: prompt, press [Ctrl+C].

32.At the Command: prompt, type "ORTHO" and press [Enter].

33.At the ONOFF prompt, type "OFF" and press [Enter].

34.At the Command: prompt, type "DIM" and press [Enter].

35.At the Dim: prompt, type "RAD" and press [Enter].

36.At the Select arc... prompt, move the cursor toward the upper right edge of the figure until the coordinates read approximately 5.2,6.7, and select that point.

37.At the Dimension text <1.0>...prompt, type "1.0R" and press [Enter].

38.At the Dim: prompt, type "DIA" and press [Enter].

39.At the Select arc... prompt, move the cursor toward the lower right edge of the circle until the coordinates read approximately 4.9,5.7, and select that point.

40.At the Dimension text <1.0>: prompt, press [Enter] to accept the value 1 .0 for the diameter.

41.At the [Enter] leader... prompt, type "0.9" and press [Enter].

42.At the Dim: prompt, type "HOR" and press [Enter].

43.At the First extention... prompt, press [Enter].

44.At the Select line prompt, move the cursor until the coordinates read 3. 5,7.0, and select that point.

45.At the Dimension line... prompt, move the cursor until the coordinates read 3.5,7.5, and select that point.

46.At the Dimension text <2.0>: prompt, press [Enter] to accept the value of 2.0.

47.Press [Ctrl+C] to end the command.

48.At the Command: prompt, type "ZOOM" and press [Enter].

49.At the All/Center... prompt, type "D" and press [Enter]. The screen is redrawn to show all three views of the drawing.

50.Move the cursor toward the right of the drawing until the coordinates read approximately 8.5,3.5, and press [Enter]. The screen is redrawn to show an enlarged view of the right view.

51.At the Command: prompt, type "DIM" and press [Enter].

52.At the Dim: prompt, type "CENTER" and press [Enter].

53.At the Select arc... prompt, move the cursor until the coordinates read 8.9,3.2, and select that point.

54.At the Dim: prompt, type "HOR" and press [Enter].

55.At the First extention line... prompt, type "INT" and press [Enter].

56.At the of: prompt, move the cursor until the coordinates read 8.0,4.0, and select that point.

57.At the Second extension... prompt, type "INT" and press [Enter].

58.At the Of: prompt, move the cursor until the coordinates read 9.0,4.0, and select that point.

59.At the Dimension line location: prompt, move the cursor to 8.5,4.2, and select that point.

60.At the Dimension text <1.0>: prompt, press [Enter] to accept the value 1 .0.

61.If Ortho is displayed on the status line, set Ortho off by typing "ORTHO " at the Command: prompt; then press [Enter].

62.Type "OFF" and press [Enter] at the ON/OFF prompt.

63.At the Dim: prompt, type "LEA" and press [Enter].

64.At the Leader start: prompt, type "NEA" and press [Enter].

65.At the To: prompt, move the cursor until the coordinates read 7.7,3.8 and select that point.

66.At the To point: prompt, move the cursor until the coordinates read 0.5< 130, and select that point.

67.At the next To point: prompt, press [Enter].

68.At the Dimension text <>... prompt, type "0.5R" and press [Enter].

69.Press [Ctrl+C] to end the Dim command.

70.At the Command: prompt, type "ORTHO" and press [Enter].

71.At the ON/OFF prompt, type "ON" and press [Enter].

72.Select Settings from the action bar to change to the Center layer. Then select Modify Layer from the pull-down menu. The Modify Layer dialog box is displayed.

73.Select the Current box to the left of CENTER and then select OK. When the screen is redrawn, the word Center is displayed next to Layer on the status line above the drawing.

74.At the Command: prompt, type "LINE" and press [Enter].

75.At the From point: prompt, type "END" and press [Enter].

76.At the Of: prompt, move the cursor until the coordinates read 8.5,2.9, and select that point.

77.At the To point: prompt, move the cursor until the coordinates read 1.2< 270 and select that point.

78.At the next To point: prompt, press [Enter] to complete the line command .

79.Select Settings from the action bar. Then select Modify Layer from the pull-down menu.

80.Select the Current box to the left of 0 and then select OK. When the screen is redrawn, 0 is displayed to the right of Layer on the status line above the drawing.

81.At the Command: prompt, type "ZOOM" and press [Enter].

82.At the All/Center... prompt, type "A" and press [Enter]. When the screen is redrawn you will see all three views of the bracket.

83.At the Command: prompt, type "END" to save the drawing.

84.Pull down the AutoCAD menu from the title bar icon and select Close from the pull-down.

85.On the Group-main menu, select OS/2 Full screen.

86.At the OS/2 prompt, type "CD \ACAD" to change to the ACAD directory. Type "ERASE D1.DWG" and press [Enter].

Verify that video corruption does not occur in all operations.

WIN-OS/2 Test Suite

This test suite executes different Win-OS/2 applications to test the OS/2 video device drivers. The following applications are tested:

�CorelDRAW** Version 4.0

�Ami Pro** Release 3.0

�Aldus PageMaker** Version 5.0

Testing Video Device Drivers Using CorelDRAW 4.0

CorelDRAW 4.0 for Windows** is a graphics presentation package.

Note:If you do not have CorelDRAW installed, refer to your CorelDRAW Installation Manual for instructions.

To Begin Testing in Full Screen Mode

1.Open the settings notebook to load CorelDRAW in full screen mode.

2.Double-click on the icon with the Balloon.

3.Select File | New and click on the 5th smart icon (square box).

4.Move the cursor to the worksheet and hold down the left mouse button while dragging the mouse to form a box.

5.Select any color from the color palette to add color to the box.

6.Click on the smart icon, click the left mouse button on the box created, and type "THIS IS A TEST".

7.Click on the first smart icon (arrow), and select the box created.

8.Select Effects | Rotate/Skew.

9.Type "45" in Rotation angle box.

10.Check "Leave Original" and select OK. The selected box should rotate.

11.Select the text "THIS IS A TEST."

12.Select Text | Character and then select Times New Roman**.

13.Change the size to 54.0 and the style to Bold-Italic, then select OK.

14.Select File | Save As and type "TEST.CDR".

Using Help Utilities

1.Select Help | Contents and then select the Search button.

2.Type "Plotters" and press [Enter].

3.Select the Go To button.

4.Double-click on the control menu option to close the help dialog box.

Using Cut and Paste

1.Press [Alt+Esc] to display the OS/2 desktop.

2.Open an OS/2 Window and type "PBRUSH".

3.Once the Paintbrush applet is open, click on the sixth smart icon ( square) in the second column. The cursor changes to a cross. Hold down the left mouse button while dragging the mouse to form a square.

4.Click on the first smart icon in the second column (scissors and square) .

5.Place the cursor over the square created.

6.Hold down the left mouse button and drag mouse to form a square with perforated lines.

7.Go back to CorelDRAW and select Edit | Paste. A square appears.

8.Select File | Save to save the file.

9.Select File | Print to print the file.

To Resize Window and Switching Between OS/2 Desktop and Win-OS2 Full Screen

1.Press [Alt+Esc] to display the OS/2 desktop.

2.Press [Alt+Esc] again to return to Win-OS/2. The CorelDRAW window reappears.

3.Click on the resize button in the upper right hand corner (arrow pointing up or double arrow). You should see the desktop icon.

4.Press the resize button again to return the window to its Full Screen position.

5.Click on the Minimize button (the one to the left of the resize button).

6.Double-click on the CorelDRAW icon to maximize the application.

7.Select File | Exit to close CorelDRAW.

To Open CorelDraw Seamlessly

1.Open the notebook settings of the CorelDRAW icon.

2.Select the session tab and then select the Win-OS/2 window.

3.Close the notebook and double-click on the CorelDRAW icon to open the application seamlessly.

4.Select File | Exit to close CorelDRAW.

To Test the Remaining CorelDRAW Applications

Testing CorelTRACE

1. Open CorelTRACE** in a seamless mode.
2. Select Help | Contents.
3. Select File | Exit to close the help window.
4. Select File | Exit to close CorelTRACE.
5. Open CorelTRACE in a full screen mode.
6. Close CorelTRACE.

Testing CorelCHART

1. Open CorelCHART** in a seamless mode.
2. Select File | Open and double-click on the Chart subdirectory.
3. Select 3DRISER and click on 3D0005.CCH. It appears in the preview window .
4. Press OK.
5. Select Help | Content.
6. Select File | Exit to close the help window.
7. Select File | Exit to close CorelCHART.
8. Open CorelCHART in a full screen mode.
9. Close CorelCHART.

Testing CCapture

1.Open CCapture in seamless mode.

2.Make sure Ccapture appears.

3.Press both mouse buttons to open the window list and highlight Ccapture.

4.Press mouse button 2 and select Close to close Ccapture.

5.Change notebook settings in Ccapture to open it in a Full Screen mode.

6.Make sure Ccapture appears.

7.Close Ccapture.

Testing CorelPAINT

1.Open CorelPAINT** in seamless mode.

2.Select File | Open and then select BALLOON.PCX.

3.Two display menus should be present: Color Selection and Canvas.

4.Select Help | Contents.

5.Select File | Exit to close the help window.

6.Select File | Exit again to close CorelPAINT.

7.Open CorelPAINT in a full screen mode.

8.Close CorelPAINT.

Testing CorelMOVE

1.Open CorelMOVE** in seamless mode.

2.Select File | Open and then select SAMPLE.CMV.

3.Once the picture appears, click on the play button (right arrow button). The animation should begin.

4.Click on the stop button (square button).

5.Select Help | Contents.

6.Select File | Exit to close the help window.

7.Select File | Exit to close CorelMOVE.

8.Open CorelMOVE in full screen mode.

9.Close CorelMOVE.

Testing CorelSHOW

1.Open CorelSHOW** in seamless mode and select OK.

2.Double-click on the Background subdirectory and select file type "*.SHB" in the List of Files type box. The file "SAMPLE.SHB" should appear in the File Name box.

3.Double-click on the SAMPLE.SHB file. Wait until the picture finishes painting the screen.

4.Select Help | Contents and close the help window after it appears.

5.Select File | Exit to close CorelSHOW.

6.Open CorelSHOW in full screen mode.

7.Close CorelSHOW.

Verify that video corruption does not occur in all operations.

Testing Video Device Drivers Using AMI PRO 3.0

Ami Pro 3.0 for windows is a word processing package that allows the user to create sophisticated text/graphics documents. This scenario is a nonexhaustive test of Ami Pro 3.0.

Note:If you do not have AMIPRO 3.0 installed, refer to your AMIPRO Installation Manual for instructions.

Starting Ami Pro in a Full Screen Mode

1.Open the notebook settings for Ami Pro and select the session tab.

2.Click on Win-OS/2 Full Screen and close the settings notebook.

3.Double-click on the Ami Pro icon.

4.Press [Alt+Esc] twice to switch from full-screen mode to the desktop and back to full-screen mode.

Selecting a Style Sheet

1.Select File | New from the main menu.

2.Select Default style sheet and then select OK.

3.Type the following sentence and five questions:

The following questions pose intellectual debate which, in some cases, causes a wide array of conflicting viewpoints:

a.Can you imagine a world without hypothetical situations?

b.Why isn't the word phonetic spelled the way it sounds?

c.When driving around and looking for an address, why do people turn the radio volume down?

d.If driving at the speed of light, what happens when turning on the headlights?

e.Certain convenience stores are open 24 hours per day, 7 days per week, 365 days per year. Why do these stores have locks on their doors?

4.Press and hold mouse button 1 and drag the mouse over the entire paragraph.

5.Select TEXT | FONT, select Roman in the font box, 18 in the points box, and the color green.

6.Select OK.

7.Move the mouse away from the text and click mouse button 1 once. The letter turns green.

8.Select File | Import Picture.

9.Under the file type box, select AmiDraw.

10.Double-click on 4BOXES.SDW in the Files box and observe that the pic file appears.

11.Select File | Save to save the file.

Using Help Files

1.Select Help | Contents and then select the Search button.

2.Type the word "PICTURE."

3.Click on SHOW Topics and then select the Go To button.

4.Select File | Exit to close the help window.

Opening or Closing a File

1.Select File | Close to save any changes and close a file.

2.Select File | Open and then select the file name to open.

Viewing Documents in a Different Way

1.Select View | Outline Mode and notice the changes on the screen.

2.Select View | Draft Mode and notice the changes.

3.Select View | Layout Mode to return to layout mode.

Creating a Table

1.Select Tools | Tables and then select OK.

2.In the first cell, type "Apple".

3.Press the tab key and type "Pear".

4.Press [SHIFT+Tab] to go back to "Apple".

Spell Checking

1.Go to the word "headlights" and delete the letter 'g'.

2.Select Tools | Spell Check.

3.In the Alternatives Box, select the word "headlights" and select the Replace button.

Manually Creating a Frame

1.Select Frame | Create Frame. Select the Manual button with mouse button 1. The cursor changes.

2.Hold down mouse button 1 and drag the mouse until a rectangle takes shape. Release the mouse button. A frame surrounded by tiny squares is created.

3.Press [Enter] and type, "I dislike writing this."

Using the Cut and Paste Option

1.Open the Paintbrush applet.

2.Click on the sixth smart icon in the second column.

3.Hold down mouse button 1 and drag the mouse to create a small square.

4.Move the cursor to the square you just created.

5.Hold down mouse button 1 and drag the mouse. A square with dashed lines appears.

6.Select Edit | Cut.

7.Minimize Paintbrush, select Ami Pro, and select Edit | Paste.

Viewing a Window

1.Select Window | Tile, and then select Window | Cascade.

2.Minimize | Maximize the window.

Printing a File

1.Click on the title bar to select the window you want to print.

2.Select File | Print to print the file.

Starting Ami Pro in a Seamless Session

1.Open the settings notebook for Ami Pro and select the session tab.

2.Click on Win-OS/2 seamless and close the settings notebook.

3.Select the Ami Pro icon.

Verify that video corruption does not occur in all operations.

Testing Video Device Drivers Using ALDUS PageMaker 5.0

Starting PageMaker

Note:If you do not have Aldus Pagemaker installed, refer to your Aldus Pagemaker Installation Manual for instructions.

1.Change to the \PM directory (or other directory where you installed PageMaker).

2.At the command prompt, type "WIN PM5".

3.Press [Enter].

Opening an Existing Publication

1.Select File | Open....

2.Click on the file name, or type the file name in the text box. If necessary, also type the name of the drive and directory.

3.Under Open..., select Original or Copy.

4.Select OK.

Verify that video corruption does not occur in all operations.

Moving to Another Page

1.If you have scroll arrows, click the left (backward) or right (forward) scroll arrow at either end of the page icons to display the icon you want. If you do not have scroll arrows, skip to Step 2.

2.Point to the icon of the page you want.

3.Click the left mouse button.

Moving to Another Page using "Go to page..."

1.Select "Go to page..." from the layout menu.

2.Click the option you want for either a master page or a regular page.

3.If you selected Page number, type the number of the page you want in the text box.

4.Select OK.

Moving to the Next Page or the Previous Page using Key Combinations

1.To move to the next page (or pair of pages), press [Ctrl+Tab].

2.To move the previous page (or pair of pages), hold down [Ctrl+Shift] and then press [Tab].

Inserting One or More Pages

1.Move to the page(s) before, after, or between which you want to insert a page(s).

2.Select "Insert pages..." from layout.

3.In the dialog box, type the number of pages you want to insert.

4.Select the option you want: before, after, or between (for double-sided publications with facing pages) the current page(s).

5.Select OK.

Removing One or More Pages

1.Use the pointer tool to drag off the page to the pasteboard any text or graphics that you do not want to delete.

2.Select "Remove pages..." from the Page menu.

3.Type the numbers of the pages you want to remove in the "Remove page(s)" and "through" fields.

4.Select OK.

5.Select OK to remove the page(s).

Saving a Publication or Template using "Save"

1.Select File | Save.

2.Continue working on the publication, close it, or quit the PageMaker session.

Saving a Publication or Template using "Save as..."

1.Select File | Save as....

2.In the text box, type the name you want for the publication. Do not type a new name if you are using this procedure to compress a publication.

3.Change to another disk drive if you do not want to save the publication on the active disk drive.

4.Select Publication or Template, and then select OK.

5.Either continue working on the publication, close it, or quit the PageMaker session.

Closing Your Publication

1.Select File | Close.

2.If PageMaker prompts whether to save changes before closing, select an option.

Verify that video corruption does not occur in all operations.

Quitting PageMaker

1.Select File | Exit, or System | Close..

2.If PageMaker prompts whether to save changes before quitting, select an option.

Creating a New Publication using a Template

1.Select File | Open...

2.In the list box, select the template you want to use.

3.Select OK.

4.Add text and graphics to the publication.

5.If your text doesn't look the way you want, use the Styles palette to apply the text styles you want.

6.Select "Save As..." and type the name of your new publication.

7.Select OK.

Creating a New Publication from Scratch

1.Select File | New.

2.In the Page setup... dialog box, select from the options listed to specify the page setup you want to use.

3.Select OK.

Creating a Master Page

1.Click either the "L" (left) or "R" (right) page icon in the lower corner of the publication window.

2.Create a page number marker and layout grid with nonprinting guides.

3.Add the graphics you want repeated on every page.

4.Add the text you want repeated on every page.

Creating an Arabic Page Number

1.Select the text tool.

2.Select an insertion point for the page marker on either a regular page or a master page.

3.Press [Ctrl+Shift+3].

4.As necessary, change the page number's type specifications or move the number (on a master page, its marker).

Creating a Composite Page Number

1.Create a text block to hold the composite page number by using the text tool to click an insertion point anywhere outside existing text blocks.

2.In that text block, type the number(s) or word(s) you want as part of the composite page number.

3.If necessary, move the insertion point to where you want the page number marker, either preceding or following the number(s) or word(s) you typed in the previous step.

4.Press [Ctrl+Shift+3] to create a page number marker.

5.As necessary, change the composite page number.

Defining a Style Sheet from Scratch

1.If the Styles palette is displayed in the publication window, hold down [Ctrl] and select No style.

2.Skip to Step 4.

If the Styles palette is not displayed, select Define styles... from the Type menu. The Define styles... dialog box is displayed.

3.Select New... to display the Edit style... dialog box.

4.In the Edit style... dialog box, type the name of the new style in Name.

5.If a name appears in Based on, delete it.

6.Select one of the four buttons, as appropriate: Type..., Para..., Tabs. .., Hyph...

7.Select OK.

8.If you started in the Define styles... dialog box rather than the Styles palette, select Close, Cancel or OK.

Creating a Style Sheet based on an Existing Style

1.If the Styles palette is displayed in the publication window, hold down [Ctrl] and select No style.

2.Skip to Step 4.

If the Styles palette is not displayed, select Define styles... from the Type menu.

3.Select New... to display the Edit style... dialog box.

4.In the Edit style... dialog box, type the name of the new style in Name.

5.In Based on, type the name of the existing style on which the new style is based.

6.Modify the Based on style specifications by following steps 5 through 7 in the preceding section, To Define a Style Sheet from Scratch.

Copying an Existing Style Sheet from Another Publication

1.Select Define styles... from the Type menu. The "efine styles... dialog box appears.

2.Select Copy... to display the Copy styles... dialog box.

3.Select the publication or template that contains the style sheet you want to copy.

4.Select OK.

5.In the Define styles... dialog box, select Close or Cancel.

Adding Text to a Publication

Adding a Word-Processed File

1.If you want text to flow automatically, make sure Autoflow is checked on the Options menu.

2.Select File | Place.... A dialog box shows a list of the text and graphics file formats that PageMaker can read directly from the current disk or directory.

3.Select the name of the file you want to place. If necessary, scroll to find the name of the file you want. If the file name is not in the list, switch to another directory or disk.

4.To retain the text formatting and styles of a word-processed file, convert regular quotation marks to typesetting quotation marks, or read style tags, make sure the appropriate options are checked. Otherwise, make sure no options are checked.

5.Select OK.

6.Position the text icon where you want the upper left corner of the text to start. This can be anywhere within column guides or elsewhere on the page or on the pasteboard.

7.Click the left mouse button to place the text.

8.Look at the bottom of the last handle, and select one: # or +.

Placing New Text

1.Select File | Place.

2.Select the name of the file you want to place.

3.To retain the text formatting and styles of a word-processed file, convert regular quotation marks to typesetting quotation marks, or read style tags, make sure the appropriate options are checked. Otherwise, make sure no options are checked.

4.Select OK.

5.Position the icon where you want to start placing the text.

6.Hold the left mouse button down and drag the icon diagonally until the box you're creating is the size you want.

7.Release the mouse button.

Pasting Text from the Clipboard using the Pointer Tool

1.Cut or copy the text to the Clipboard.

2.In the publication you want to paste to, make sure the pointer is selected.

3.Select Edit | Paste.

4.Reposition and, if necessary, resize the text block.

5.If the bottom handle of the text block shows a "+," continue flowing the pasted text until no + is showing in the bottom handle.

Pasting Text from the Clipboard using the Text Tool

1.Cut or copy the text to the clipboard.

2.Select and place the text tool where you want to paste the copied text.

3.Either click or drag a bounding box to place an insertion point outside existing text blocks.

4.Select Edit | Paste.

5.If necessary, use the pointer tool to reposition and resize the text block.

Creating a New Text Block and Typing Text

1.Use the text tool to select an insertion point outside existing text blocks .

2.Type the new text.

Editing Text

Positioning an Insertion Point

1.Select the text tool.

2.Position the I-beam where you want the insertion point to be. This can be inside or outside existing text blocks.

3.Click the left mouse button.

Placing an Insertion Point by Dragging

1.Select the text tool.

2.Position the I-beam where you want the first character of text to be placed, outside existing text blocks.

3.Drag a bounding box diagonally, making it the width you want for the line of text.

4.Release the mouse button.

Selecting a Range of Text

Selecting a Range of Text using Shift and a Beginning and Ending Insertion Point

1.Use the text tool to select the beginning insertion point, which acts as an anchor point for selection.

2.Hold down [Shift].

3.Position an insertion point where you want the selection to end.

Selecting Text Using Shift, a Beginning Insertion Point, and the Cursor Keys

1.Use the text tool to select the beginning insertion point, which acts as an anchor point for the selection.

2.Hold down [Shift].

3.Use the cursor keys or any of the key combinations listed under Moving the insertion pointto either extend or shorten the selection.

Copying, Cutting and Pasting Text

Copying or Cutting Text to the Clipboard

1.Select the text you want to move using either the pointer tool or text tool.

2.Select File | Copy or File | Cut.

Inserting Clipboard Text into an Existing Text Block

1.Using the text tool, position an insertion point in the text block where you want to paste the text.

2.Select Edit | Paste.

Replacing Selected Text with the Contents of the Clipboard

1.Use the text tool to select any amount of text you want to replace.

2.Select File | Paste.

Pasting the Clipboard Contents into another PageMaker Publication

1.Copy or cut the text you want to move to the Clipboard.

2.Close the current publication.

3.At PageMaker's desktop, open the publication in which you want to paste the text from the Clipboard.

4.Select Edit | Paste.

Inserting Text

Inserting Text into an Existing Text Block

1.Use the text tool to click an insertion point where you want to insert the text.

2.Select File | Place....

3.In the Place... dialog box, select the word-processed file you want to insert.

4.Make sure any format options you want are selected.

5.Select Inserting text.

6.Select OK.

Deleting Text

Deleting a Range of Text

1.Use the text tool to select the text you want to delete.

2.Select Edit | Clear, or press [Backspace] or [Delete].

Deleting Text Character by Character

1.Use the text tool to select an insertion point after the character(s) you want to delete.

2.Press [Backspace], as necessary to remove the characters.

Applying Styles

Applying a Style from the Styles Palette

1.Use the text tool to select one or more paragraphs where you want to apply a style.

2.If the Styles palette isn't showing, select Options | Style palette....

3.In the Styles palette, select the name of the style you want to apply.

Applying a Style while Preserving an Earlier Override

1.Use the text tool to select one or more paragraphs where you want to apply a style.

2.If the Styles palette isn't showing, select Options | Style palette....

3.Hold down [Shift], and select the name of the style you want to apply.

Applying a Style from the Define styles ... Dialog Box

1.Use the text tool to select one or more paragraphs where you want to apply a style.

2.Select Type | Define styles....

3.In the Define styles... dialog box, select the style you want to apply.

4.Select OK.

Removing a Style from a Style Sheet

1.Select Type | Define styles....

2.In the Define styles... dialog box, select the name of the style you want to remove.

3.Select Remove.

4.Select OK.

Renaming a Style

1.If the Styles palette isn't showing, select Options | Style palette from the Options menu.

2.In the Styles palette, hold down [Ctrl] and select the style name you want to change. The Edit style... dialog box is displayed.

You could also select Type | Define styles..., select the style name, and then select Edit....

3.In Name, delete the current name and type the new style name.

4.Select OK.

5.If you started from Define styles..., select OK in the Define styles... dialog box to return to your publication.

Editing a Style

1.In the Styles palette, hold down [Ctrl] and select the style name you want to edit The Edit style... dialog box is displayed.

You could also select Type | Define styles..., select the style name, and then select Edit....

2.Select the command button you want: Type..., Para.., Tabs..., or Color.. ..

3.In any of the above dialog boxes you use, select OK to return to the Edit style... dialog box.

4.When you've finished editing the style, select OK in the Edit style... dialog box.

5.If you started from Define styles..., select OK.

Changing Paragraph Specifications

Aligning Paragraphs

Changing Paragraph Alignment from the Type Menu

1.Use the text tool to select a range of text, or position an insertion point from which you'll be typing new text (using the changed alignment specifications).

2.Select Align left, Align center, Align right or Justify.

Changing Paragraph Alignment using the Paragraph.. Dialog Box

1.Use the text tool to select a range of text or, position an insertion point and type new text (using the changed alignment specifications).

2.Select Type | Paragraph....

3.In Alignment, select the alignment you want the selected text to have.

4.Select OK.

Setting Indents and Tabs

Setting Right or Left Indents

1.To set the indent for existing text only, use the text tool to select either the paragraph(s) you want or an insertion point.

2.Select Type | Indents/tabs....

3.In the Indents/tabs... dialog box, drag the left indent icon (bottom icon) or right indent icon (right icon) along the ruler to where you what the left or right side of your paragraph(s) to align.

4.Select OK.

Setting a First-Line Indent

1.To set the indent for existing text only, use the text tool to select either the paragraph(s) you want or an insertion point.

2.Select Type | Indents/tabs....

Setting a Negative (Hanging) First-Line Indent

1.To set the indent for existing text only, use the text tool to select either the paragraph(s) you want or an insertion point.

2.Select Type | Indents/tabs....

3.In the Indents/tabs... dialog box, drag the left margin icon (bottom icon) along the ruler to where you want all but the first line of your text left-aligned.

4.Drag the first-line indent icon along the ruler to the left, where you want your first line of text aligned.

Setting a Tab Stop

1.Use the text tool to select either the paragraph(s) you want or an insertion point.

2.Select Type | Indents/tabs....

3.In the Indents/Tabs... dialog box, select Left, Right, Center, or Decimal for the new tab's alignment.

4.Either select None or click on a pattern for the tab's leader. You can also create your own leader by clicking the last leader option button and typing any one or two characters in the text box.

5.Click anywhere along the tab ruler to set the tab's position.

6.To set another tab with the same alignment and leader, repeat Step 5. To set another tab with a different alignment and leader, repeat Steps 3 through 5.

7.If necessary, reposition any of the indents by dragging their triangle- shaped icons to new positions on the ruler.

8.Select OK.

Moving a Tab Stop

1.Use the text tool to select the paragraph(s) you want or an insertion point.

2.Select Type | Indents/tabs....

3.On the ruler in the Indents/tabs... dialog box, reposition the tab stop' s arrow marker to where you want it. You can drag it over other tab stops without affecting them.

4.Select OK.

Changing the Alignment or Leader of a Tab Stop

1.Use the text tool to select either the paragraph(s) you want or an insertion point.

2.Select Type | Indents/tabs....

3.On the ruler in the Indents/tabs... dialog box, specify the alignment and leader you want.

4.Select a new tab on top of the tab you are modifying. You could also delete the tab by dragging the tab arrow below the ruler; then specify the new alignment and leader you want.

5.Select OK.

Aligning Text at the Next Tab Stop

1.Place an insertion point to the left of the text that you want moved to the next tab stop.

2.Press [Tab].

Typing Text at a Tab Stop

1.Press [Tab].

2.Begin typing text.

Deleting a Tab Stop

1.Select Type | Indents/tabs....

2.In the Indents/tabs... dialog box, drag the tab arrow below the ruler.

3.If necessary, reposition any indents by dragging their icons to new positions on the tab ruler.

4.Select OK.

Clearing All Tab Stops

1.Use the text tool to select the paragraph(s) you want.

2.Using the text tool, select Type | Indents/tab....

3.In the Indents/tabs... dialog box, select Clear.

4.If necessary, reposition any of the indents by dragging their icons to new positions on the ruler.

5.Select OK.

Exporting Text from a PageMaker Publication

1.Use the text tool to select the text or story you want to export.

2.Select File | Export....

3.In the Export.. dialog box, specify under Export whether to export the entire story or just selected text.

4.In the text box, type the file name to which you want to export the text .

5.In File format, select the format you want for the file.

6.As necessary, define the drive and directory where you want to store the export file.

7.Select OK.

Using Graphics in a Publication

Placing a Graphic in a Publication

1.Select File | Place....

2.If necessary, scroll to find the name of the graphics file you want to place.

3.Double-click on the name of the graphics file.

4.Position the upper-left corner of the icon where you want the upper-left corner of the graphic to be.

5.Click the left mouse button. Or, drag the mouse from the upper-left to the lower-right corner to draw a bounding box the size you want the graphic , then release the mouse button.

Pasting a Graphic From the Clipboard

1.From the other application or publication, cut and paste the graphic to the Clipboard.

2.Select Edit | Paste....

3.Drag the graphic to where you want it in your publication.

General Techniques for Modifying any Graphic

Moving a Graphic

1.Use the pointer tool to select the graphic(s).

2.Point anywhere on the selected graphic except on a handle.

3.To move the graphic in just one direction (either horizontally or vertically), hold down [Shift].

4.Hold down the left mouse button.

5.After the pointer changes to four arrows, drag the graphic(s) to the desired location.

Cutting, Copying and Pasting a Graphic

1.Using the pointer tool, select the graphic(s) you want to cut or copy to the Clipboard.

2.Select Edit | Copy or Edit | Cut.

Pasting One or More Copies of a Graphic

1.Select Edit | Paste.

2.Drag the graphic or group of graphics to the desired location.

Deleting a Graphic

1.Use the pointer tool to select the graphic(s) you want to delete.

2.Select Edit | Clear, or press [Backspace] or [Delete].

Modifying a Graphic

1.Use the pointer tool to point to the graphic you want to select.

2.Click the left mouse button.

Drawing with Pagemaker Tools

Drawing a Straight Line

1.Click either the diagonal-line or perpendicular-line tool.

2.Position the center of the crossbar where you want the line to start.

3.Drag until the center of the crossbar is where you want the line to end, then release the mouse button.

Drawing a Rectangle or Square

1.Click either the square-corner or rounded-corner tool.

2.Position the center of the crossbar where you want a corner of the rectangles or square to start.

3.Drag the crossbar diagonally until the box or rectangle is the size you want, then release the mouse button. To draw a square, hold down [Shift] as you drag the crossbar.

Drawing an Oval or Circle

1.Select the circle/oval tool.

2.Position the center of the crossbar where you want the oval or circle to start.

3.Drag in any direction until the oval or circle is the size you want, then release the mouse button. To draw a circle, hold down [Shift] as you drag the crossbar.

Verify that video corruption does not occur in all operations.

Selecting a Combination of Text Blocks and Graphics

Drawing a Selection Box

1.If you want any previously selected items to remain selected, hold down [Shift].

2.Starting on a blank area of the page, use the pointer tool to point to any corner of an imaginary rectangle that surrounds the text and graphics.

3.Drag diagonally until the flashing selection box completely surrounds all items you want to select.

Selecting a Group, Item by Item

1.Hold down [Shift].

2.Use the pointer tool to click each text block or graphic you want to select.

Canceling the Selection of Individual Items in a Group Selection

1.Hold down [Shift].

2.Use the pointer tool to click each item whose selection you want to cancel.

Text Flow Behavior

Flowing Text Through a Graphic

1.Use the pointer tool to select the graphic you want text to flow through .

2.Select Options | Text wrap....

3.In Wrap option, select the None icon.

4.Select OK.

Splitting Text with a Graphic

1.Use the pointer tool to select the graphic you want to use to split or divide the text block.

2.Select Options | Text wrap....

3.In Wrap option, select the icon for a rectangular graphic boundary.

4.To change the amount of space between the graphic and its graphic boundary, type appropriate values in the Standoff in inches text boxes.

5.In Text flow, select the split text icon.

Wrapping Text Around a Graphic

1.Use the pointer tool to select the graphic you want text to flow around.

2.Select Options | Text wrap....

3.In Wrap option, select the icon for a rectangular graphic boundary.

4.To change the amount of space between the graphic and its graphic boundary, type appropriate values in the Standoff in inches text boxes.

5.In Text flow, select the wrap around icon.

6.Select OK.

Verify that video corruption does not occur in all operations.

Display Test Tool

The Display Test Tool (DTT) is a Presentation Manager application that enables the user to select and display one or more display tests. A script interface permits DTT to automatically run predefined test scripts.

Overview

The DTT provides a mechanism for testing video device drivers by exercising them through graphics engine (GRE) API calls. As each test is run, the DTT monitors the return codes from the GRE calls and writes the results in a log file. The current log file can be displayed at any time during manual testing.

DTT Architecture

The DTT is comprised of two major components:

�A Presentation Manager master program (DTT.EXE) that provides the user interface for test selection and execution

�Test-case dynamic-link libraries (DLLs) that contain the actual test-case executable code

DTT Master Program

DTT.EXE enables the user to do the following:

�Select one or more tests from the available test cases
�Execute the selected test cases on demand
�Specify a test-case Presentation Manager environment (PS units, PS types, and so forth)
�Display the DTT test log
�Set the DTT test-logging level
�Display the DTT release level
�Exit DTT

Command-line options enable the user to specify the following:

�Output log file name
�Input script file name
�Level of logging to capture
�Output test case index file name
�Input test case index file names
�Option to search LIBPATH for DLLs
�Search patterns for DLLs to be preloaded

Test-Case DLLs

Each test-case DLL contains tests for a family of GRE calls. See GRE Function Tests (By Function Name)and GRE Function Tests (By Test-Case Name )for descriptions of the supplied test-case DLLs and GRE functions called.

Operating DTT

DTT can be started from the command line in either an OS/2 window or a full -screen session. DTT also can be started from the OS/2 desktop or any other folder by using the DTT icon. When using the icon, command-line options are specified in the Optional Parametersfield of the Settings menu for the icon.

Specifying Command Options

All command-line options are specified with either a hyphen (-) or a slash (/) prefix, followed by an alphabetic character (not case-sensitive), followed immediately by the option value, if any, with no intervening spaces. The hyphen and slash can be used interchangeably. Following are examples of DTT command lines:

  Load all DLLs in the current directory and set the logging level:

      DTT -T*..DLL -L8

   Preload the GRELINE DLL; also load a test-case index.
   Search LIBPATH to locate the DLLs.

      DTT /tgreline.dll -ntestindx.ndx -s

See DTT Command-Line Options Summaryfor a summary of DTT command-line options. Executing DTT with the -? command-line option displays a list of the valid command-line options.

Locating, Preloading, and Loading Test-Case DLLs

DTT uses the following sequence to locate test-case DLLs:

1.DLLs specified using the -T command-line option are preloaded during DTT startup. Preloaded DLLs remain resident for the duration of the DTT session .

The -T command-line option specifies a search pattern for locating the test -case DLLs to be preloaded. The -T option value can contain global file- name characters (wildcards) in the file name. If the -S option also is specified on the command line, test-case DLL names are located using the same search pattern, but the DLLs found are loaded by searching LIBPATH. Following are examples of how to preload DLLs:

  Preload GREBTMP.DLL from LIBPATH.

     DTT /tgrebtmp.dll /s


  On the currrent drive, preload all DLLs in the DTT\DLL directory.

      DTT -T\DTT\DLL\*.DLL

The -T command-line option can be specified multiple times.

2.Test-case index files specified using the -N command-line option are loaded. (See Creating a Test-Case Index Filefor information on creating test-case index files.)

A DLL containing a specific test case is loaded only when that test case is executed; the DLL remains resident only until a test case resident in another DLL is executed. If the -S option also is specified on the command line, DTT uses LIBPATH to locate the test-case DLLs specified in a test- case index file. Following are examples of how to load test-case index files:

  Load the testndx1.ndx and testndx2.ndx test case index files.

     DTT /NE:\DTT\INDEX\testndx1.ndx -nC:\COMMON\testndx2.ndx

  Load the testindx.ndx from the current directory.

The -N command-line option can be specified multiple times.

3.At this point, if no test cases have been identified to DTT, DTT attempts to load a test-case index file named TESTINDX.NDX from the current directory.

4.Then, if test cases still have not been identified to DTT, DTT attempts to preload any test-case DLLs it locates, using an "*.DLL" search pattern. The search pattern searches the current directory, if the -S command-line option is not specified, or LIBPATH, if the -S option is specified.

5.If DTT fails to locate any test cases, a message to that effect is issued.

The -S command-line option orders DTT to search LIBPATH when attempting to load a test-case DLL. If the -S option is not specified, DTT searches only the specified path (or current directory if no path is specified) to locate test-case DLLs.

The -S command-line option is most useful when using a test-case index file , as shown in the following example:

     DTT -Ntestindx.ndx -S

The names of all test cases must be made known to DTT during startup. This can be accomplished in the following ways:

�Loading test-case index files
�Preloading test-case DLLs

Loading Test-Case Index Files

A test-case index file associates each test-case name with the DLL that contains it. When a duplicate test case is encountered while loading a test -case index file, only the first instance of a test case is retained. Each test-case DLL passes a list of the test cases it contains to DTT when DTT initializes the DLL.

Creating a Test-Case Index File

A test-case index file enables DTT to start up without having to preload all of the test-case DLLs. To create a test-case index file, use the -K command-line option. When the -K command-line option is specified, DTT starts up normally, loading the specified test-case DLLs and index files. Once startup is complete, DTT writes a test-case index file, for all the loaded test cases, to the file specified in the -K command-line option, then terminates.

If the -S command-line option is specified along with the -K option, the new test-case index file always causes DTT to search LIBPATH when loading the DLLs for the test cases in the index. If the -S command-line option is not used with the -K option, the test-case index file contains the full path to each of the DLLs. A new test-case index file has to be created if the test-case DLLs are moved.

If the -S option is specified when creating a test-case index file, LIBPATH is searched to locate test-case DLLs when using that test-case index file.

DTT Log File

DTT writes information to a log file. The information to be logged is determined by the current logging level, which is hierarchical. At any given logging level, all information at that level and below is logged.

Specifying the DTT Log File Name

A path and file name for the DTT log file can be specified on the DTT command-line using the -F option. If no log file name option is given on the command line, the default file name, DTT_LOG, is used in the current directory.

If a log file does not exist when DTT is started, the log file is created automatically. If the log file does exist, the new log is appended to the existing log file.

Specifying DTT Logging Levels

The DTT logging level can be specified on the DTT command line or changed from the Options pull-down menu after DTT has started. To set the logging level on the command line, specify a -Lxoption, where xis the desired logging level, using a number in the range 1 - 9. To change the logging level after DTT has started, select Change logging levelfrom the Options pull-down menu or use Alt+L. The default DTT logging level is 1, L_HDR.

The following table describes the logging levels supported by DTT:

/--------------------------------------------------------------\
|Level No. |Level Name|Description                             |
|----------+----------+----------------------------------------|
|1         |L_HDR     |Test Pass/Fail logging only.            |
|----------+----------+----------------------------------------|
|2         |L_ABORT   |Test case failed. Test is incomplete.   |
|----------+----------+----------------------------------------|
|3         |Reserved  |Do not use.                             |
|----------+----------+----------------------------------------|
|4         |L_FAIL    |Internal test-case failure. An interface|
|          |          |other than the call currently being     |
|          |          |tested has experienced a functional or  |
|          |          |other type of failure.                  |
|----------+----------+----------------------------------------|
|5         |Reserved  |Do not use.                             |
|----------+----------+----------------------------------------|
|6         |L_WARN    |Warning: The presentation space is      |
|          |          |improperly configured for the test case |
|          |          |(or similar error).                     |
|----------+----------+----------------------------------------|
|7         |L_TRACE   |Trace script commands, incorrect values,|
|          |          |or other unexpected results.            |
|----------+----------+----------------------------------------|
|8         |L_LOTRACE |Location trace. Log entries and exits of|
|          |          |internal test-case routines.            |
|----------+----------+----------------------------------------|
|9         |L_DEBUG   |Debugging. Test-case debugging          |
|          |          |information, internal test-case results,|
|          |          |errors, and other information.          |
\--------------------------------------------------------------/

Displaying the DTT Log File

To display the DTT log file for the current session, select Display log windowfrom the Options pull-down menu or use Alt+D.

Operating DTT Automatically

The following provides instructions for specifying a script file, the script file structure, and the script commands DTT supports.

Specifying a Script File

If the name of a DTT script file is provided, DTT executes the supplied script automatically. To specify a script file, use the -I command-line option, as in the following example:

     DTT -IC:\DTT\SCRIPTS\bittests.scr

Script File Structure

A script file is a list of DTT commands that are executed, one at a time, in the order that the commands appear in the script file. When the end of the script file is reached, DTT terminates. Any DTT script command can appear anywhere in a script file. See Sample DTT Script Filefor an example of a DTT script file.

Script commands are not case-sensitive, except for the test-case name operand of the CHOOSE script command.

Script Commands

/--- Usage Notes ------------------------------------------\
|                                                          |
|  1. Blank lines and comments can appear anywhere in a    |
|     script file.                                         |
|                                                          |
|  2. Comments must be preceded by an asterisk (*) as the  |
|     first non-blank character on the line.               |
|                                                          |
\----------------------------------------------------------/

CHOOSE (Test-Case Selection Command)

The operand of the CHOOSE script command specifies the test case to be executed when a DISPLAY script command is encountered. The test-case name operand is case-sensitive and must match the specified test-case name exactly. In script files, test cases are selected by their test-case name only; the test-group name is not used. If the test-case name is not found, the CHOOSE command is ignored.

DCTYPE (Device Context Selection Command)

The operand of the DCTYPE script command identifies the device context to be used for subsequent test cases. Valid operands are:

OD_QUEUED Output is to be queued. (This is the default.)

OD_DIRECT Output is not to be queued.

OD_INFO The device context is to be used only to retrieve information.

OD_METAFILE The device context is to be used to write a metafile.

OD_METAFILE_NOQUERY Same as OD_METAFILE, except querying of the attributes is not permitted.

OD_MEMORY A device context that is used to contain a bit map.

DELAY (Pause Script File Execution Command)

When a DELAY command is encountered in a DTT script file, execution of the script is suspended for five seconds. The DELAY script command has no operand.

DISPLAY (Execute a Test Case Command)

The DISPLAY script command initiates immediate execution of the test case selected by the most recent CHOOSE command.

If the DISPLAY command is not preceded by a CHOOSE command anywhere in the script file, the first test case identified during DTT startup is executed. The DISPLAY script command has no operand.

EXIT (Terminate DTT Command)

When an EXIT command is encountered in a DTT script file, DTT immediately terminates. The EXIT script command has no operand.

PSTYPE (Presentation Space Type Selection Command)

The operand of the PSTYPE script command identifies the presentation space type to be used for subsequent test cases. Valid operands are:

GPIT_MICRO Micro-presentation space.

GPIT_NORMAL Normal presentation space. (This is the default.)

PSUNITS (Presentation Space Units Selection Command)

The operand of the PSUNITS script command identifies the presentation space units to be used for subsequent test cases.

Valid operands are:

PU_ARBITRARY Application-convenient units.

PU_PELS Pel coordinates. (This is the default.)

PU_LOMETRIC Units of 0.1 mm.

PU_HIMETRIC Units of 0.01 mm.

PU_LOENGLISH Units of 0.01 inch.

PU_HIENGLISH Units of 0.001 inch.

PU_TWIPS Units of 1/1440 inch.

Configuring the Device Context and Presentation Space

DTT enables you to specify the device context, presentation-space type, and presentation-space units to use when executing test cases. These parameters can be changed during manual testing or through script commands during automated testing.

To change the configuration manually, select Configurationfrom the Options pull-down menu or use Alt+C. See Operating DTT Automaticallyfor information about changing the configuration using script commands.

Setting the Device Context

To change the device context, select one of the following options from the Device Context section of the DTT Configuration dialog panel:

OD_QUEUED Output is to be queued. (This is the default.)

OD_DIRECT Output is not to be queued.

OD_INFO The device context is to be used only to retrieve information.

OD_METAFILE The device context is to be used to write a metafile.

OD_METAFILE_NOQUERY The same as OD_METAFILE, except the querying of attributes is not permitted.

OD_MEMORY A device context that is used to contain a bit map.

Setting the Presentation-Space Type

To select the presentation-space type to be used when executing test cases, choose one of the following options from the PS Type section of the DTT Configuration dialog panel:

GPIT_MICRO Micro-presentation space.

GPIT_NORMAL Normal presentation space. (This is the default.)

Setting Presentation-Space Units

To set the presentation-page size units for test-case execution, select one of the following from the PS Units section of the DTT Configuration dialog panel:

PU_ARBITRARY Application-convenient units.

PU_PELS Pel coordinates. (This is the default.)

PU_LOMETRIC Units of 0.1 mm.

PU_HIMETRIC Units of 0.01 mm.

PU_LOENGLISH Units of 0.01 inch.

PU_HIENGLISH Units of 0.001 inch.

PU_TWIPS Units of 1/1440 inch.

Selecting and Executing Test Cases

The test cases to be executed are selected from the Test Case Selection dialog panel. Select Testcasefrom the DTT menu bar or use ALT+T. One or more test cases can be selected for execution during manual operation. Use script commands to select individual test cases during automated operation. See Operating DTT Automaticallyfor information on test-case selection and execution using script commands.

Test Group Selection

There is a 1:1 relationship between test groups and test-case DLLs. Each test group represents a specific DLL. Before a test case can be selected, the test group containing the test case must be selected from the Test Groups section of the DTT Test Case Selection dialog panel. When you select a test group, the list of test cases it contains is added to the Test Cases section of the dialog panel. Deselecting a test group removes the list of test cases it contains from the Test Cases section.

Note:Test groups must be specifically deselected. DTT never automatically deselects a test group.

Test Case Selection

Once the test groups are selected, the individual test cases can be selected from the Test Cases section of the DTT Test Case Selection dialog panel. Test cases can be selected and deselected individually, or groups of test cases can be selected with the match patterns provided using the Add Matchand Delete Matchpush buttons.

Note:Test cases must be specifically deselected. DTT never automatically deselects a test case.

Saving Selected Test Cases

After selecting one or more test cases, use the Savepush button or Alt+Sto close the Test Case Selection dialog panel.

Executing Test Cases

After selecting and saving one or more test cases, select Displayfrom the DTT menu bar or use Alt+Sto begin test-case execution. Each test case selected is executed in the order it appeared in the Test Cases section of the Test Case Selection dialog panel.

During test execution, DISPLAY TEST TOOL: Test Running appears in the DTT window title bar. When the test is complete, the name of the individual test selected reappears in the title bar if a single test was selected. DISPLAY TEST TOOL: Multiple Tests Selected appears if more than one test is selected.

Displaying the DTT Release and Revision Levels

To display the current DTT release and revision levels, select Aboutfrom the DTT menu bar or use ALT+A.

Exiting DTT

To terminate DTT, select Exitfrom the DTT menu bar or use ALT+X.

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.

Installing Video Configuration Manager for OS/2

There are different files required for installing the Video Configuration Manager, depending on the version of OS/2 you are using.

Files Required for OS/2 Warp, Version 3 and Above

Your installation must identify the OS/2 version and copy the following files for OS/2 Warp, Version 3 and above:

• os2\dll\videopmi.dll
• os2\dll\videocfg.dll
• os2\dll\vcfgmri.dll
• os2\monitor.dif

Files Required for OS/2 V2.1 and 2.11

Your installation must identify the OS/2 version and copy the following files for OS/2 V2.1 and V2.11:

• os2\dll\videopmi.dll
• os2\dll\videocfg.dll
• os2\dll\vcfgmri.dll
• os2\dll\wpvidsys.dll
• os2\monitor.dif

After copying the files, you must run VCFGINST.EXE.

Exported Functions

The following API services are exported by VIDEOCFG.DLL:

• AddMonitorData
• GetAllMonitors
• GetCurrentCFG
• GetCurrentDesktopMode

�QueryNumMonitors

�SetCurrentCFG

The format and syntax of each of the above functions is shown on the following pages.

AddMonitorData

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

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

#include <svgadefs.h>

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

rc = AddMonitorData(*pNewMonitorInfo);

AddMonitorData - Syntax

Description:

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

#include <svgadefs.h>

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

rc = AddMonitorData(*pNewMonitorInfo);

AddMonitorData Parameter - *pNewMonitorInfo

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

This parameter points to the MONITORINFOdata structure that specifies the new monitor definition to add to the database.

AddMonitorData Return Value - rc

rc(ULONG) - returns Return codes.

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

ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT

AddMonitorData - Parameters

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

This parameter points to the MONITORINFOdata structure that specifies the new monitor definition to add to the database.

rc(ULONG) - returns Return codes.

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

ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT

AddMonitorData - Remarks

None.

AddMonitorData - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

GetAllMonitors

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

GetAllMonitorsretrieves all monitor definitions. These monitor definitions are defined in the MONITOR.DIF file.

#include <svgadefs.h>

MONITORINFO    *pMonitors;     /*  Pointer to the array of MONITORINFO data structures. */
PULONG         pulBufferSize;  /*  Specifies the size of the pMonitors buffer, in bytes. */
ULONG          rc;             /*  Return codes. */

rc = GetAllMonitors(*pMonitors, pulBufferSize);

GetAllMonitors - Syntax

Description:

GetAllMonitorsretrieves all monitor definitions. These monitor definitions are defined in the MONITOR.DIF file.

#include <svgadefs.h>

MONITORINFO    *pMonitors;     /*  Pointer to the array of MONITORINFO data structures. */
PULONG         pulBufferSize;  /*  Specifies the size of the pMonitors buffer, in bytes. */
ULONG          rc;             /*  Return codes. */

rc = GetAllMonitors(*pMonitors, pulBufferSize);

GetAllMonitors Parameter - *pMonitors

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

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

GetAllMonitors Parameter - pulBufferSize

pulBufferSize(PULONG) - output Specifies the size of the pMonitorsbuffer, in bytes.

If the buffer size is too small to contain all monitor definitions, the ERROR_NOT_ENOUGH_MEMORY error is returned. The variable is then given the size of the buffer required in order to contain all monitor definitions.

GetAllMonitors Return Value - rc

rc(ULONG) - returns Return codes.

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

ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT
ERROR_NOT_ENOUGH_MEMORY

GetAllMonitors - Parameters

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

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

pulBufferSize(PULONG) - output Specifies the size of the pMonitorsbuffer, in bytes.

If the buffer size is too small to contain all monitor definitions, the ERROR_NOT_ENOUGH_MEMORY error is returned. The variable is then given the size of the buffer required in order to contain all monitor definitions.

rc(ULONG) - returns Return codes.

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

ERROR_INVALID_PARAMETER
ERROR_NO_MONITOR_SUPPORT
ERROR_NOT_ENOUGH_MEMORY

GetAllMonitors - Remarks

None.

GetAllMonitors - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

GetCurrentCFG

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

GetCurrentCFGgets the current video configuration stored in the Registry.

#include <svgadefs.h>

ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;         /*  Return codes. */

rc = GetCurrentCFG(*pAdapter, *pMonitor);

GetCurrentCFG - Syntax

Description:

GetCurrentCFGgets the current video configuration stored in the Registry.

#include <svgadefs.h>

ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;         /*  Return codes. */

rc = GetCurrentCFG(*pAdapter, *pMonitor);

GetCurrentCFG Parameter - *pAdapter

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

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

GetCurrentCFG Parameter - *pMonitor

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

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

GetCurrentCFG Return Value - rc

rc(ULONG) - returns Return codes.

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

ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION

GetCurrentCFG - Parameters

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

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

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

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

rc(ULONG) - returns Return codes.

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

ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION

GetCurrentCFG - Remarks

None.

GetCurrentCFG - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

GetCurrentDesktopMode

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

GetCurrentDesktopModeretrieves the current desktop mode information stored in the Registry. The desktop mode information includes X and Y resolutions, bits per pixel, vertical and horizontal refresh rates, vertical and horizontal polarity positives, and screen top, bottom, left, and right.

#include <svgadefs.h>

VIDEO_ADAPTER    *pVideoAdapter;  /*  Pointer to the VIDEO_ADAPTER data structure. */
ULONG            rc;              /*  Return codes. */

rc = GetCurrentDesktopMode(*pVideoAdapter);

GetCurrentDesktopMode - Syntax

Description:

GetCurrentDesktopModeretrieves the current desktop mode information stored in the Registry. The desktop mode information includes X and Y resolutions, bits per pixel, vertical and horizontal refresh rates, vertical and horizontal polarity positives, and screen top, bottom, left, and right.

#include <svgadefs.h>

VIDEO_ADAPTER    *pVideoAdapter;  /*  Pointer to the VIDEO_ADAPTER data structure. */
ULONG            rc;              /*  Return codes. */

rc = GetCurrentDesktopMode(*pVideoAdapter);

GetCurrentDesktopMode Parameter - *pVideoAdapter

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

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

GetCurrentDesktopMode Return Value - rc

rc(ULONG) - returns Return codes.

TRUE Function is successful
FALSE Function is unsuccessful.

GetCurrentDesktopMode - Parameters

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

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

rc(ULONG) - returns Return codes.

TRUE Function is successful
FALSE Function is unsuccessful.

GetCurrentDesktopMode - Remarks

None.

GetCurrentDesktopMode - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

QueryNumMonitors

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

QueryNumMonitorsqueries the number of monitor defintions available.

#include <svgadefs.h>

PULONG    pulNumMonitors;  /*  Pointer to variable receiving the number of monitor definitions. */
ULONG     rc;              /*  Return codes. */

rc = QueryNumMonitors(pulNumMonitors);

QueryNumMonitors - Syntax

Description:

QueryNumMonitorsqueries the number of monitor defintions available.

#include <svgadefs.h>

PULONG    pulNumMonitors;  /*  Pointer to variable receiving the number of monitor definitions. */
ULONG     rc;              /*  Return codes. */

rc = QueryNumMonitors(pulNumMonitors);

QueryNumMonitors Parameter - pulNumMonitors

pulNumMonitors(PULONG) - output Pointer to variable receiving the number of monitor definitions.

QueryNumMonitors Return Value - rc

rc(ULONG) - returns Return codes.

0 Function is successful
Nonzero Returns the following error:

ERROR_NO_MONITOR_SUPPORT

QueryNumMonitors - Parameters

pulNumMonitors(PULONG) - output Pointer to variable receiving the number of monitor definitions.

rc(ULONG) - returns Return codes.

0 Function is successful
Nonzero Returns the following error:

ERROR_NO_MONITOR_SUPPORT

QueryNumMonitors - Remarks

None.

QueryNumMonitors - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

SetCurrentCFG

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

SetCurrentCFGsets the current video configuration in the Registry.

#include <svgadefs.h>

ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;         /*  Return codes. */

rc = SetCurrentCFG(*pAdapter, *pMonitor);

SetCurrentCFG - Syntax

Description:

SetCurrentCFGsets the current video configuration in the Registry.

#include <svgadefs.h>

ADAPTERINFO    *pAdapter;  /*  Pointer to the ADAPTERINFO data structure. */
MONITORINFO    *pMonitor;  /*  Pointer to the MONITORINFO data structure. */
ULONG          rc;         /*  Return codes. */

rc = SetCurrentCFG(*pAdapter, *pMonitor);

SetCurrentCFG Parameter - *pAdapter

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

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

SetCurrentCFG Parameter - *pMonitor

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

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

SetCurrentCFG Return Value - rc

rc(ULONG) - returns Return codes.

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

ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION

SetCurrentCFG - Parameters

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

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

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

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

rc(ULONG) - returns Return codes.

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

ERROR_INVALID_PARAMETER
ERROR_INVALID_CONFIGURATION

SetCurrentCFG - Remarks

None.

SetCurrentCFG - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

Generic Video Configuration Interface

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

GreEscape DEVESC_QUERYDRIVERCAPS

---

Select an item:

Syntax
Parameters 
Returns 
Glossary 

---

Simulation support:

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

Description:

GreEscape DEVESC_QUERYDRIVERCAPSreturns the capabilities descriptions. The values for each capability are not yet allocated and are queried later. The #define DEVESC_QUERYDRIVERCAPS (4010L) is defined in SVGADEFS.H.

#define INCL_GRE_DEVICE
#include <svgadefs.h>

HDC      hdc;         /*  A handle to the device context. */
LONG     lCode;       /*  DEVESC_QUERYDRIVERCAPS */
LONG     lInCount;    /*  Not used. */
PBYTE    pbInData;    /*  Not used. */
PLONG    plOutCount;  /*  The number of bytes of data pointed to by pbOutData. */
PBYTE    pbOutData;   /*  The address of a buffer that will contain a ULONG variable specifying the number of capabilities. */
LONG     rc;          /*  Return Code. */

rc = GreEscape(hdc, lCode, lInCount, pbInData,
       plOutCount, pbOutData);

GreEscape DEVESC_QUERYDRIVERCAPS - Syntax

Simulation support:

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

Description:

GreEscape DEVESC_QUERYDRIVERCAPSreturns the capabilities descriptions. The values for each capability are not yet allocated and are queried later. The #define DEVESC_QUERYDRIVERCAPS (4010L) is defined in SVGADEFS.H.

#define INCL_GRE_DEVICE
#include <svgadefs.h>

HDC      hdc;         /*  A handle to the device context. */
LONG     lCode;       /*  DEVESC_QUERYDRIVERCAPS */
LONG     lInCount;    /*  Not used. */
PBYTE    pbInData;    /*  Not used. */
PLONG    plOutCount;  /*  The number of bytes of data pointed to by pbOutData. */
PBYTE    pbOutData;   /*  The address of a buffer that will contain a ULONG variable specifying the number of capabilities. */
LONG     rc;          /*  Return Code. */

rc = GreEscape(hdc, lCode, lInCount, pbInData,
       plOutCount, pbOutData);

GreEscape DEVESC_QUERYDRIVERCAPS Parameter - hdc

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

GreEscape DEVESC_QUERYDRIVERCAPS Parameter - lCode

lCode(LONG) - input DEVESC_QUERYDRIVERCAPS

GreEscape DEVESC_QUERYDRIVERCAPS Parameter - lInCount

lInCount(LONG) - input Not used.

GreEscape DEVESC_QUERYDRIVERCAPS Parameter - pbInData

pbInData(PBYTE) - input Not used.

GreEscape DEVESC_QUERYDRIVERCAPS Parameter - plOutCount

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

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

GreEscape DEVESC_QUERYDRIVERCAPS Parameter - pbOutData

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

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

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

GreEscape DEVESC_QUERYDRIVERCAPS Return Value - rc

rc(LONG) - returns Return Code.

Returns NO_ERROR.

GreEscape DEVESC_QUERYDRIVERCAPS - Parameters

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

lCode(LONG) - input DEVESC_QUERYDRIVERCAPS

lInCount(LONG) - input Not used.

pbInData(PBYTE) - input Not used.

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

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

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

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

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

rc(LONG) - returns Return Code.

Returns NO_ERROR.

GreEscape DEVESC_QUERYDRIVERCAPS - Topics

Select an item:

Syntax
Parameters 
Returns 
Glossary 

GreEscape DEVESC_QUERYDRIVERCAPSLIST

---

Select an item:

Syntax
Parameters 
Returns 
Glossary 

---

Simulation support:

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

Description:

GreEscape DEVESC_QUERYDRIVERCAPSLISTfills the pValueList, pCurrentValue,and pDefaultValuein the DRIVERCAPSdata structure. The members must be 0 padded up to the ulValueMemberSizein the pValueList.

There are three kind of data types that we are supporting at the present time-boolean, aggregate of int values, and aggregate of strings. These data types are defined as follows:

   #define  CAPSTYPE_BOOLEAN                   1L 
   #define  CAPSTYPE_AGGREGATE_INT         2L 
   #define  CAPSTYPE_AGGREGATE_STRING    3L

#define INCL_GRE_DEVICE
#include <svgadefs.h>

HDC      hdc;         /*  A handle to the device context. */
LONG     lCode;       /*  DEVESC_QUERYDRIVERCAPSLIST */
LONG     lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;   /*  Not used. */
LONG     rc;          /*  Return Code. */

rc = GreEscape(hdc, lCode, lInCount, pbInData,
       plOutCount, pbOutData);

GreEscape DEVESC_QUERYDRIVERCAPSLIST - Syntax

Simulation support:

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

Description:

GreEscape DEVESC_QUERYDRIVERCAPSLISTfills the pValueList, pCurrentValue,and pDefaultValuein the DRIVERCAPSdata structure. The members must be 0 padded up to the ulValueMemberSizein the pValueList.

There are three kind of data types that we are supporting at the present time-boolean, aggregate of int values, and aggregate of strings. These data types are defined as follows:

   #define  CAPSTYPE_BOOLEAN                   1L 
   #define  CAPSTYPE_AGGREGATE_INT         2L 
   #define  CAPSTYPE_AGGREGATE_STRING    3L

#define INCL_GRE_DEVICE
#include <svgadefs.h>

HDC      hdc;         /*  A handle to the device context. */
LONG     lCode;       /*  DEVESC_QUERYDRIVERCAPSLIST */
LONG     lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;   /*  Not used. */
LONG     rc;          /*  Return Code. */

rc = GreEscape(hdc, lCode, lInCount, pbInData,
       plOutCount, pbOutData);

GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - hdc

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

GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - lCode

lCode(LONG) - input DEVESC_QUERYDRIVERCAPSLIST

GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - lInCount

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

GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - pbInData

pbInData(PBYTE) - input Pointer to a DRIVERCAPSdata structure.

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

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

GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - plOutCount

plOutCount(PLONG) - output Not used.

GreEscape DEVESC_QUERYDRIVERCAPSLIST Parameter - pbOutData

pbOutData(PBYTE) - output Not used.

GreEscape DEVESC_QUERYDRIVERCAPSLIST Return Value - rc

rc(LONG) - returns Return Code.

Returns NO_ERROR.

GreEscape DEVESC_QUERYDRIVERCAPSLIST - Parameters

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

lCode(LONG) - input DEVESC_QUERYDRIVERCAPSLIST

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

pbInData(PBYTE) - input Pointer to a DRIVERCAPSdata structure.

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

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

plOutCount(PLONG) - output Not used.

pbOutData(PBYTE) - output Not used.

rc(LONG) - returns Return Code.

Returns NO_ERROR.

GreEscape DEVESC_QUERYDRIVERCAPSLIST - Topics

Select an item:

Syntax
Parameters 
Returns 
Glossary 

GreEscape DEVESC_SETDRIVERCAPSVALUE

---

Select an item:

Syntax
Parameters 
Returns 
Glossary 

---

Simulation support:

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

Description:

GreEscape DEVESC_SETDRIVERCAPSVALUEwill set the value that user has selected. The new value is specified in pCurrentValue.

When the Video Configuration Manager presents the interface to the user, each capability is presented in a separate window page of the capabilities notebook in System Object. The window layout depends on the capability type -Boolean type is represented by a check box and aggregate type is represented by a listbox. The capability description appears as the title for that control.

If the driver is going to support these capabilities in multiple languages, it must get the capability description (szCapsDesc) and capability aggreate strings, if applicable, from a resource module that contains already- translated strings.

#define INCL_GRE_DEVICE
#include <svgadefs.h>

HDC      hdc;         /*  A handle to the device context. */
LONG     lCode;       /*  DEVESC_SETDRIVERCAPSVALUE */
LONG     lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;   /*  Not used. */
LONG     rc;          /*  Return Code. */

rc = GreEscape(hdc, lCode, lInCount, pbInData,
       plOutCount, pbOutData);

GreEscape DEVESC_SETDRIVERCAPSVALUE - Syntax

Simulation support:

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

Description:

GreEscape DEVESC_SETDRIVERCAPSVALUEwill set the value that user has selected. The new value is specified in pCurrentValue.

When the Video Configuration Manager presents the interface to the user, each capability is presented in a separate window page of the capabilities notebook in System Object. The window layout depends on the capability type -Boolean type is represented by a check box and aggregate type is represented by a listbox. The capability description appears as the title for that control.

If the driver is going to support these capabilities in multiple languages, it must get the capability description (szCapsDesc) and capability aggreate strings, if applicable, from a resource module that contains already- translated strings.

#define INCL_GRE_DEVICE
#include <svgadefs.h>

HDC      hdc;         /*  A handle to the device context. */
LONG     lCode;       /*  DEVESC_SETDRIVERCAPSVALUE */
LONG     lInCount;    /*  Number of bytes pointed to by pbInData. */
PBYTE    pbInData;    /*  Pointer to a DRIVERCAPS data structure. */
PLONG    plOutCount;  /*  Not used. */
PBYTE    pbOutData;   /*  Not used. */
LONG     rc;          /*  Return Code. */

rc = GreEscape(hdc, lCode, lInCount, pbInData,
       plOutCount, pbOutData);

GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - hdc

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

GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - lCode

lCode(LONG) - input DEVESC_SETDRIVERCAPSVALUE

GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - lInCount

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

GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - pbInData

pbInData(PBYTE) - input Pointer to a DRIVERCAPSdata structure.

The DRIVERCAPS data structure specifies the driver capability to set.

GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - plOutCount

plOutCount(PLONG) - output Not used.

GreEscape DEVESC_SETDRIVERCAPSVALUE Parameter - pbOutData

pbOutData(PBYTE) - output Not used.

GreEscape DEVESC_SETDRIVERCAPSVALUE Return Value - rc

rc(LONG) - returns Return Code.

Returns NO_ERROR.

GreEscape DEVESC_SETDRIVERCAPSVALUE - Parameters

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

lCode(LONG) - input DEVESC_SETDRIVERCAPSVALUE

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

pbInData(PBYTE) - input Pointer to a DRIVERCAPSdata structure.

The DRIVERCAPS data structure specifies the driver capability to set.

plOutCount(PLONG) - output Not used.

pbOutData(PBYTE) - output Not used.

rc(LONG) - returns Return Code.

Returns NO_ERROR.

GreEscape DEVESC_SETDRIVERCAPSVALUE - Topics

Select an item:

Syntax
Parameters 
Returns 
Glossary 

How to Write to Windows Profiling Files in OS/2

Some display drivers must perform windows profiling (updates to SYSTEM.INI or WIN.INI file). The following sample source file can be included in display driver source and executed at ring 3 only.

     typedef ULONG APIENTRY WPF1(VOID);
     typedef WPF1 *PWPF1;
     typedef BOOL  APIENTRY WPF2(ULONG, BOOL);
     typedef WPF2 *PWPF2;
     typedef BOOL  APIENTRY WPF3(ULONG, PSZ);
     typedef WPF3 *PWPF3;
     BOOL UpdateWindowsIniFiles(VOID)
     {
       BOOL    result = TRUE;
       BOOL    res1;
       ULONG   hWpf;
       CHAR    szUpdateString[256];
       PWPF1   pWpfOpenProfileList;
       PWPF2   pWpfCloseProfileList;
       PWPF3   pWpfWriteProfileListLine;
       HMODULE hMod;
       if (DosLoadModule(NULL, 0, "WINPRF", &hMod) ||
           DosQueryProcAddr(hMod, 0, "WPFOPENPROFILELIST", (PFN *)&pWpfOpenProfileList) ||
           DosQueryProcAddr(hMod, 0, "WPFCLOSEPROFILELIST", (PFN *)&pWpfCloseProfileList) ||
           DosQueryProcAddr(hMod, 0, "WPFWRITEPROFILELISTLINE", (PFN *)&pWpfWriteProfileListLine))
       {
          return FALSE;
       }

       // Open the profile handler.
       if (hWpf = (*pWpfOpenProfileList)())
       {
       /*
       ** szUpdateString has the following format
       **
       ** <profile name>  <section>  <keyword>  [value]
       **
       ** ex.   "system.ini boot sdisplay.drv wd3116sl.drv"  will insert the line
       **    sdisplay.drv=wd3116sl.drv in the boot section of system.ini
       **
       ** if [value] is omitted, the <keyword> is deleted from the section
       */
          if (!(*pWpfWriteProfileListLine)(hWpf, szUpdateString))
          {
             result = FALSE;          // Win Ini update failed!
          }

          res1 = (*pWpfCloseProfileList)(hWpf, result); // Close or abort the updates
          result &= res1;
       }
       else
       {
          result = FALSE;
       }

       return result;
   }

Most Frequently Asked Video Configuration Questions and Answers

How does the user configure monitor, resolution, and refresh in OS/2? The user interface for video configuration is located in the System object member of the System Setup folder, which can be brought up by clicking the right mouse button on the desktop area.

Why use the System Icon monitor configuration vs. custom configuration? System Icon provides a large pool of legacy monitors and a consistent device-independent resolution/refresh/monitor configuration. The OS/2 Warp, Version 3.0 System Icon configuration support can be installed on OS/2 2.1 and will be supported on future versions of OS/2. The Sysem Icon's initial configuration reflects the configuration that was performed by the BIOS.

What other video configuration features are supported by the System Icon? VIDEOCFG, the binary module that owns the System's video pages, also has a generic capability interface. This generic interface allows for expansion of configuration if a vendor needs additional pages, such as a page for font selection, orientation selection, or any other discrete value configuration.

What is needed to get the System Icon to display the monitor list? The mode table exported by the PMI subsystem has to have at least one graphics mode with a [MonitorModeInfo] section. The presence of this graphics mode indicates that the base video system can take into account monitor capabilities.

What is needed to get the System Icon to display the Monitor size button? The PMI subsystem mode table has to have at least one mode with startup values for ScreenLeftEdge, ScreenRightEdge and so forth. The support for monitor sizing is disabled in the DDK version of the VIDEOCFG, but a refresh of the VIDEOCFG is available on request.

How are monitor capabilities described in OS/2? OS/2 has a pre-built database of about 300 monitors. The list is ordered alphabetically by monitor manufacturer name. Each monitor is described in terms of the resolutions it supports and the maximum refresh value for each resolution. The syntax does not allow for optimum or multiple timing choices. The database is a flat file, MONITOR.DIF, that can be modified. VIDEOCFG.DLL exports APIs that allow for monitor database queries and expansion.

Where is the current configuration stored? Current monitor configuration capabilities, as well as the current refresh for each mode and screen sizing information, are stored in a flat file, VIDEO.CFG, whose syntax is very similar to PMI. The content can be queried or changed by calling VIDEOCFG.DLL's configuration APIs.

Where does the default monitor come from? SVGA.EXE (SVGAOEM.EXE) formats the very first VIDEO.CFG that communicates to the configurator the current refresh configuration, as left by the BIOS. We have assembled per-adapter information that lets us understand how each vendor records its refresh configuration. These values are formatted into the VIDEO.CFG. If SVGA.EXE does not format the file, the very first monitor from the MONITOR.DIF database is chosen. Otherwise, the original (default) VIDEO.CFG monitor capabilities are added to the MONITOR.DIF so that the customer can go back to the BIOS-configured monitor capabilities.

Is there DDC support? SVGA.EXE (and SVGAOEM.EXE) and the configuration do support the DDC1 standard. SVGA.EXE formats the VIDEO.CFG with the DDC1- queried capabilities and marks the monitor as DDC. This automatically excludes any monitor from the database. As a result, the customer is not offered monitor selection page, but does have refresh choices per mode on Page 1. In order to change from a DDC monitor to a non-DDC monitor, the customer has to do one of the following:

�Change the current VIDEO.CFG's monitor name from the "DDC" keyword to anything else

�Issue a SetCurrentCFG API into the VIDEOCFG.DLL and specify a name other than DDC for the current monitor's name

�Remove VIDEO.CFG will also enable the monitor selection.

Where do the refresh values in the refresh listbox on Page 1 come from? The resolutions offered represent the resolutions returned by the display driver that are also available from the PMI subsystem. The match is done on horizontal and vertical resolution and color depth (NOT pixel depth).

If at least one of the resolutions in this group has a [MonitorModeInfo] section, the refresh box will be offered. The content of the refresh box is tied into the currently selected resolution. The refresh values are those found in the VIDEOPMI's mode query list that are within the range of the currently selected monitor. The highlight (default) is on the highest value in the listbox (unless overridden by the customer). Changing the selected monitor affects the range and elicits immediate change if the range has been diminished. If the range is increased, the configured refresh remains the same and has to be increased by the customer, if so desired.

What does "DEFAULT" entry in the refresh listbox mean? If the very first VIDEO.CFG has 0xFF for the resolutions vertical refresh, the entry "DEFAULT " will be highlighted in the refresh box. The actual set mode will also pass the 0xFF in the mode structure, so that the selection of the refresh is entirely up to the PMI subsystem (PMI file or imported binary that handles the setmode function). The "DEFAULT" can be used in places where the startup configuration of an adapter is not known at first, but the base video subsystem has ways of setting appropriate (non-harmful) refresh values. If the SVGADATA.PMI contains [MonitorModeInfo] sections with refresh entries other than 0xFF, the refresh listbox will also contain those, but the customer has to override the default highlight. As soon as an actual (non-DDC) monitor is chosen, the DEFAULT will no longer be a valid option in the refresh listbox. Going back to the original monitor " DEFAULT" would put the "DEFAULT" refresh entry into the listbox.

How could a vendor be noncommittal about the refresh values it supports? The vendor could provide a single [MonitorModeInfo] section that represent its highest refresh capability. This information will be filtered against the monitor's capabilities (the monitor's range is always the highest refresh entry), which effectively notifies the customer that only one ( highest capability of the monitor) refresh can be offered. The vendor could specify its [MonitorModeInfo] entry to be so high that no monitor is discriminated against. However, we strongly recommend that the monitor's refresh value passed into the setmode be respected and set as close as possible. There is the potential for some legal problems if the values requested are not within a margin. Regulations, such as ISO 9000 specifications, are established and enforced by countries where our product is sold, not by IBM.

Could the OS/2 configuration serve to configure BIOS/WIN-OS2? If the setmode function servicing the requested refresh also sets configuration registers used by the BIOS / WIN-OS2 driver before or after it changes the clock registers, this will affect non-OS2 mode sets as well. It is not recommended that non-OS2 applications read the VIDEO.CFG, as its format is open to change. The GetCurrentCFG and GetCurrentDesktopMode APIs are exported by the VIDEOCFG.DLL for OS/2 applications so that the current monitor capabilities and current resolution/refresh/monitor sizing values can be read.

How can new monitors be added to the list? A new monitor can be added by using the AddMonitorData API exported by the VIDEOCFG or by manually editing the MONITOR.DIF file. A PRIVATE.DIF file with new monitor entries will accomplish the same thing while keeping MONITOR.DIF as read-only.

Are customers configuring their monitors or the refresh in OS/2? The answer is both, if the vendor's PMI file has more than one [MonitorModeInfo] section per mode. In other words, after selecting the monitor, the customer still has multiple refresh choices if the PMI file had multiple refresh entries for the current mode below the monitor's end-of-range. Some vendors have utilities that are geared towards monitor configuration (a somewhat limited monitor list is usually the problem) and some are geared towards the refresh value setting (most users have a hard time understanding what the refresh means). We have a two-pronged configuration which, in the absence of DDC, lets the user choose a monitor as a way of limiting the highest refresh, and still select one of the more standard timings for a given resolution.

How can the System Icon refresh support be installed on OS/2 2.1? In order to install VIDEOCFG on OS/2 2.x, the VCFGINST.EXE utility provided in the video\bin directory should be executed first. This utility installs WPVIDSYS.DLL, which subclassed WPSYSTEM class to VIDEOCFG.DLL. Both WPVIDSYS.DLL and VIDEOCFG.DLL should be copied into the LIBPATH and will become active upon a reboot following the VCFGINST.EXE. There used to be a version of VIDEOCFG for OS/2 2.x called VIDEOCFG.206. This version is now consolidated into VIDEOCFG.DLL, so a single library can be installed on both versions of the operating system.

You can also download the S3_864.ZIP from CompuServe, OS2SUP library 23 ( search for 86C84 and UPGRADE keywords). This package supports S3 864/964 and 764 and showcases the installation on OS/2 2.x. The 764 driver also uses VIDEOPMI's software interrupt services.

VIDEOPMI.DLL Exported Functions

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

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

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

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

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

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

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

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

Supported Functions

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

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

VIDEOPMI32Request

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

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

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to the current VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set to appropriate PMIREQUEST_ function. */
PVOID             pIn;         /*  Pointer to applicable data structure. */
PVOID             pOut;        /*  Pointer to applicable data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

VIDEOPMI32Request - Syntax

Description:

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

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to the current VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set to appropriate PMIREQUEST_ function. */
PVOID             pIn;         /*  Pointer to applicable data structure. */
PVOID             pOut;        /*  Pointer to applicable data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

VIDEOPMI32Request Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - in/out Pointer to the current VIDEO_ADAPTERdata structure.

VIDEOPMI32Request Parameter - ulFunction

ulFunction(ULONG) - input Set to appropriate PMIREQUEST_ function.

VIDEOPMI32Request Parameter - pIn

pIn(PVOID) - input Pointer to applicable data structure.

VIDEOPMI32Request Parameter - pOut

pOut(PVOID) - output Pointer to applicable data structure.

VIDEOPMI32Request Return Value - rc

rc(APIRET) - returns Return codes.

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

VIDEOPMI32Request - Parameters

pAdapter(PVIDEO_ADAPTER) - in/out Pointer to the current VIDEO_ADAPTERdata structure.

ulFunction(ULONG) - input Set to appropriate PMIREQUEST_ function.

pIn(PVOID) - input Pointer to applicable data structure.

pOut(PVOID) - output Pointer to applicable data structure.

rc(APIRET) - returns Return codes.

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

VIDEOPMI32Request - Remarks

When issuing this VIDEOPMI32Request, AdapterInfo_cp and VideoModeInfo_cp in VIDEO_ADAPTERshould be set to sizeof(ADAPTERINFO) and sizeof(VIDEOMODEINFO ). This way, VIDEOPMI can handle callers built from different sizes of ADAPTERINFOVIDEOMODEINFOand included in different versions of OS/2 Warp.

There is a 16-bit entry point, VIDEOPMI16Request, from VIDEOPMI.DLL for 16- bit callers. It functions exactly the same as its 32-bit counterpart VIDEOPMI32Request. Refer to the VIDEO_ADAPTERdata structure in Data Typesfor format and syntax information.

VIDEOPMI32Request - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_LOADPMIFILE

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_LOADPMIFILEloads the specified .PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_LOADFILE. */
PVOID             pIn;         /*  Pointer to the ASCII string of the .PMI file. */
PVOID             pOut;        /*  Pointer to BOOL; can be NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_LOADPMIFILE - Syntax

Description:

PMIREQUEST_LOADPMIFILEloads the specified .PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_LOADFILE. */
PVOID             pIn;         /*  Pointer to the ASCII string of the .PMI file. */
PVOID             pOut;        /*  Pointer to BOOL; can be NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_LOADPMIFILE Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_LOADPMIFILE Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_LOADFILE.

PMIREQUEST_LOADPMIFILE Parameter - pIn

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

PMIREQUEST_LOADPMIFILE Parameter - pOut

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

PMIREQUEST_LOADPMIFILE Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_LOADPMIFILE - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_LOADFILE.

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

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

rc(APIRET) - returns Return codes.

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

PMIREQUEST_LOADPMIFILE - Remarks

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

If pOutis not NULL, *pOutis set to TRUE if the .PMI file is already loaded; FALSE, otherwise. Refer to ADAPTERINFOand VIDEO_ADAPTERdata structures in Data Typesfor format and syntax information.

PMIREQUEST_LOADPMIFILE - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_SETMODE

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_SETMODEsets requested video mode through the passed mode ID.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETMODE. */
PVOID             pIn;         /*  Pointer to mode ID from the VIDEOMODEINFO data structure. */
PVOID             pOut;        /*  Pointer to the SetMode hardware command list. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETMODE - Syntax

Description:

PMIREQUEST_SETMODEsets requested video mode through the passed mode ID.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETMODE. */
PVOID             pIn;         /*  Pointer to mode ID from the VIDEOMODEINFO data structure. */
PVOID             pOut;        /*  Pointer to the SetMode hardware command list. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETMODE Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_SETMODE Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMODE.

PMIREQUEST_SETMODE Parameter - pIn

pIn(PVOID) - input Pointer to mode ID from the VIDEOMODEINFOdata structure.

PMIREQUEST_SETMODE Parameter - pOut

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

PMIREQUEST_SETMODE Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETMODE - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMODE.

pIn(PVOID) - input Pointer to mode ID from the VIDEOMODEINFOdata structure.

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

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETMODE - Remarks

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

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

PMIREQUEST_SETMODE - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_SETMEMORYIOADDRESS

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_SETMEMORYIOADDRESSsets the linear aperture to the passed address.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETMEMORYIOADDRESS. */
PVOID             pIn;         /*  Pointer to the address to be set. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETMEMORYIOADDRESS - Syntax

Description:

PMIREQUEST_SETMEMORYIOADDRESSsets the linear aperture to the passed address.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETMEMORYIOADDRESS. */
PVOID             pIn;         /*  Pointer to the address to be set. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETMEMORYIOADDRESS Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_SETMEMORYIOADDRESS Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMEMORYIOADDRESS.

PMIREQUEST_SETMEMORYIOADDRESS Parameter - pIn

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

PMIREQUEST_SETMEMORYIOADDRESS Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_SETMEMORYIOADDRESS Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETMEMORYIOADDRESS - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETMEMORYIOADDRESS.

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

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETMEMORYIOADDRESS - Remarks

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

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

PMIREQUEST_SETMEMORYIOADDRESS - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_LOCKREGISTERS

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_LOCKREGISTERSlocks extended registers.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_LOCKREGISTERS. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_LOCKREGISTERS - Syntax

Description:

PMIREQUEST_LOCKREGISTERSlocks extended registers.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_LOCKREGISTERS. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_LOCKREGISTERS Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_LOCKREGISTERS Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_LOCKREGISTERS.

PMIREQUEST_LOCKREGISTERS Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_LOCKREGISTERS Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_LOCKREGISTERS Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_LOCKREGISTERS - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_LOCKREGISTERS.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_LOCKREGISTERS - Remarks

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

PMIREQUEST_LOCKREGISTERS - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_UNLOCKREGISTERS

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_UNLOCKREGISTERSunlocks extended registers.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_UNLOCKREGISTERS. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_UNLOCKREGISTERS - Syntax

Description:

PMIREQUEST_UNLOCKREGISTERSunlocks extended registers.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_UNLOCKREGISTERS. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_UNLOCKREGISTERS Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_UNLOCKREGISTERS Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_UNLOCKREGISTERS.

PMIREQUEST_UNLOCKREGISTERS Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_UNLOCKREGISTERS Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_UNLOCKREGISTERS Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_UNLOCKREGISTERS - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_UNLOCKREGISTERS.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_UNLOCKREGISTERS - Remarks

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

PMIREQUEST_UNLOCKREGISTERS - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_CLEANUP

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_CLEANUPcleans up the settings in extended registers.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_CLEANUP. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_CLEANUP - Syntax

Description:

PMIREQUEST_CLEANUPcleans up the settings in extended registers.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_CLEANUP. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_CLEANUP Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_CLEANUP Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_CLEANUP.

PMIREQUEST_CLEANUP Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_CLEANUP Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_CLEANUP Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_CLEANUP - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_CLEANUP.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_CLEANUP - Remarks

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

PMIREQUEST_CLEANUP - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_SAVESTATE

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_SAVESTATEsaves partial or complete state of the hardware.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SAVESTATE. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a VIDEOSTATE data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SAVESTATE - Syntax

Description:

PMIREQUEST_SAVESTATEsaves partial or complete state of the hardware.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SAVESTATE. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a VIDEOSTATE data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SAVESTATE Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_SAVESTATE Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_SAVESTATE.

PMIREQUEST_SAVESTATE Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_SAVESTATE Parameter - pOut

pOut(PVOID) - output Pointer to a VIDEOSTATEdata structure.

PMIREQUEST_SAVESTATE Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SAVESTATE - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SAVESTATE.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a VIDEOSTATEdata structure.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SAVESTATE - Remarks

miStatein the VIDEOSTATEdata structure is the current mode ID in VIDEOMODEINFO.

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

�Video mode (STATEFLAG_REGISTERS)

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

�Video Memory (STATEFLAG_VRAM)

Video memory of size ulVRAMSaveSizeis saved to pVRAMin saving state or restored from pVRAMin restoring state.

�Color Lookup Table (STATEFLAG_CLUT)

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

�Font (STATEFLAG_FONT)

Font can be saved to or restored from pFont.

PMIREQUEST_SAVESTATE - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_RESTORESTATE

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_RESTORESTATErestores the state of the hardware from supplied data.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_RESTORESTATE. */
PVOID             pIn;         /*  Pointer to a VIDEOSTATE data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_RESTORESTATE - Syntax

Description:

PMIREQUEST_RESTORESTATErestores the state of the hardware from supplied data.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_RESTORESTATE. */
PVOID             pIn;         /*  Pointer to a VIDEOSTATE data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_RESTORESTATE Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_RESTORESTATE Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_RESTORESTATE.

PMIREQUEST_RESTORESTATE Parameter - pIn

pIn(PVOID) - input Pointer to a VIDEOSTATEdata structure.

PMIREQUEST_RESTORESTATE Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_RESTORESTATE Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_RESTORESTATE - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_RESTORESTATE.

pIn(PVOID) - input Pointer to a VIDEOSTATEdata structure.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_RESTORESTATE - Remarks

See PMIREQUEST_SAVESTATE.

PMIREQUEST_RESTORESTATE - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_GETBANK

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_GETBANKgets current bank.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_GETBANK. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a BANKDATA data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_GETBANK - Syntax

Description:

PMIREQUEST_GETBANKgets current bank.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_GETBANK. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a BANKDATA data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_GETBANK Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_GETBANK Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETBANK.

PMIREQUEST_GETBANK Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_GETBANK Parameter - pOut

pOut(PVOID) - output Pointer to a BANKDATAdata structure.

PMIREQUEST_GETBANK Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_GETBANK - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETBANK.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a BANKDATAdata structure.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_GETBANK - Remarks

The bank number is obtained by executing the [GETBANK] section in the .PMI file. The bank number is saved in r0 in the .PMI file. It is then saved in ulBankin the BANKDATAdata structure. miBankin BANKDATA is the current mode ID.

PMIREQUEST_GETBANK - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_SETBANK

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_SETBANKsets bank to requested value.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETBANK. */
PVOID             pIn;         /*  Pointer to a BANKDATA data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETBANK - Syntax

Description:

PMIREQUEST_SETBANKsets bank to requested value.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETBANK. */
PVOID             pIn;         /*  Pointer to a BANKDATA data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETBANK Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_SETBANK Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETBANK.

PMIREQUEST_SETBANK Parameter - pIn

pIn(PVOID) - input Pointer to a BANKDATAdata structure.

PMIREQUEST_SETBANK Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_SETBANK Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETBANK - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETBANK.

pIn(PVOID) - input Pointer to a BANKDATAdata structure.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETBANK - Remarks

See PMIREQUEST_GETBANK.

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

PMIREQUEST_SETBANK - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_GETCLUT

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_GETCLUTgets a copy of Color Lookup Table from hardware.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_GETCLUT. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a CLUTDATA data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_GETCLUT - Syntax

Description:

PMIREQUEST_GETCLUTgets a copy of Color Lookup Table from hardware.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_GETCLUT. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a CLUTDATA data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_GETCLUT Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_GETCLUT Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETCLUT.

PMIREQUEST_GETCLUT Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_GETCLUT Parameter - pOut

pOut(PVOID) - output Pointer to a CLUTDATAdata structure.

PMIREQUEST_GETCLUT Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_GETCLUT - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETCLUT.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a CLUTDATAdata structure.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_GETCLUT - Remarks

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

PMIREQUEST_GETCLUT - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_SETCLUT

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_SETCLUTsets Color Lookup Table to supplied values.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETCLUT. */
PVOID             pIn;         /*  Pointer to a CLUTDATA data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETCLUT - Syntax

Description:

PMIREQUEST_SETCLUTsets Color Lookup Table to supplied values.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETCLUT. */
PVOID             pIn;         /*  Pointer to a CLUTDATA data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETCLUT Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_SETCLUT Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETCLUT.

PMIREQUEST_SETCLUT Parameter - pIn

pIn(PVOID) - input Pointer to a CLUTDATAdata structure.

PMIREQUEST_SETCLUT Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_SETCLUT Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETCLUT - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETCLUT.

pIn(PVOID) - input Pointer to a CLUTDATAdata structure.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETCLUT - Remarks

See PMIREQUEST_GETCLUT.

PMIREQUEST_SETCLUT - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_GETPALETTE

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_GETPALETTEgets a copy of palette registers from hardware.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_GETPALETTE. */
PVOID             pInput;      /*  NULL. */
PVOID             pOut;        /*  Pointer to a PALETTEDATA data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pInput, pOut);

PMIREQUEST_GETPALETTE - Syntax

Description:

PMIREQUEST_GETPALETTEgets a copy of palette registers from hardware.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_GETPALETTE. */
PVOID             pInput;      /*  NULL. */
PVOID             pOut;        /*  Pointer to a PALETTEDATA data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pInput, pOut);

PMIREQUEST_GETPALETTE Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_GETPALETTE Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETPALETTE.

PMIREQUEST_GETPALETTE Parameter - pInput

pInput(PVOID) - input NULL.

PMIREQUEST_GETPALETTE Parameter - pOut

pOut(PVOID) - output Pointer to a PALETTEDATAdata structure.

PMIREQUEST_GETPALETTE Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_GETPALETTE - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETPALETTE.

pInput(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a PALETTEDATAdata structure.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_GETPALETTE - Remarks

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

PMIREQUEST_GETPALETTE - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_SETPALETTE

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_SETPALETTEsets palette registers to supplied values.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETPALETTE. */
PVOID             pIn;         /*  Pointer to a PALETTEDATA data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETPALETTE - Syntax

Description:

PMIREQUEST_SETPALETTEsets palette registers to supplied values.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETPALETTE. */
PVOID             pIn;         /*  Pointer to a PALETTEDATA data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETPALETTE Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_SETPALETTE Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETPALETTE.

PMIREQUEST_SETPALETTE Parameter - pIn

pIn(PVOID) - input Pointer to a PALETTEDATAdata structure.

PMIREQUEST_SETPALETTE Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_SETPALETTE Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETPALETTE - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETPALETTE.

pIn(PVOID) - input Pointer to a PALETTEDATAdata structure.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETPALETTE - Remarks

See PMIREQUEST_GETPALETTE.

PMIREQUEST_SETPALETTE - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_GETFONT

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_GETFONTreads current font from video memory.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_GETFONT. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a FONTDATA data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_GETFONT - Syntax

Description:

PMIREQUEST_GETFONTreads current font from video memory.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_GETFONT. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a FONTDATA data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_GETFONT Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_GETFONT Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETFONT.

PMIREQUEST_GETFONT Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_GETFONT Parameter - pOut

pOut(PVOID) - output Pointer to a FONTDATAdata structure.

PMIREQUEST_GETFONT Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_GETFONT - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_GETFONT.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a FONTDATAdata structure.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_GETFONT - Remarks

ulCharCountin the FONTDATAdata structure is the number of characters in the font. ulFontHeightis the number of scanlines per character. bFontDatais the start of the font data. The size is (ulCharCount * ulFontHeight) bytes.

PMIREQUEST_GETFONT - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_SETFONT

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_SETFONTsets font to that supplied.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETFONT. */
PVOID             pIn;         /*  Pointer to a FONTDATA data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETFONT - Syntax

Description:

PMIREQUEST_SETFONTsets font to that supplied.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SETFONT. */
PVOID             pIn;         /*  Pointer to a FONTDATA data structure. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SETFONT Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_SETFONT Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETFONT.

PMIREQUEST_SETFONT Parameter - pIn

pIn(PVOID) - input Pointer to a FONTDATAdata structure.

PMIREQUEST_SETFONT Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_SETFONT Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETFONT - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_SETFONT.

pIn(PVOID) - input Pointer to a FONTDATAdata structure.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_SETFONT - Remarks

See PMIREQUEST_GETFONT.

PMIREQUEST_SETFONT - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_TUNEDISPLAY

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_TUNEDISPLAYexecutes the [TuneDisplay] section in the .PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_TUNEDISPLAY. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_TUNEDISPLAY - Syntax

Description:

PMIREQUEST_TUNEDISPLAYexecutes the [TuneDisplay] section in the .PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_TUNEDISPLAY. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_TUNEDISPLAY Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_TUNEDISPLAY Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_TUNEDISPLAY.

PMIREQUEST_TUNEDISPLAY Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_TUNEDISPLAY Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_TUNEDISPLAY Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_TUNEDISPLAY - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_TUNEDISPLAY.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_TUNEDISPLAY - Remarks

None.

PMIREQUEST_TUNEDISPLAY - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_IDENTIFYADAPTER

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_IDENTIFYADAPTERexecutes the [IdentifyAdapter] section in the specified .PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_IDENTIFYADAPTER. */
PVOID             pIn;         /*  Pointer to the ASCII string of the .PMI file. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_IDENTIFYADAPTER - Syntax

Description:

PMIREQUEST_IDENTIFYADAPTERexecutes the [IdentifyAdapter] section in the specified .PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_IDENTIFYADAPTER. */
PVOID             pIn;         /*  Pointer to the ASCII string of the .PMI file. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_IDENTIFYADAPTER Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_IDENTIFYADAPTER Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_IDENTIFYADAPTER.

PMIREQUEST_IDENTIFYADAPTER Parameter - pIn

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

PMIREQUEST_IDENTIFYADAPTER Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_IDENTIFYADAPTER Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_IDENTIFYADAPTER - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_IDENTIFYADAPTER.

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

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_IDENTIFYADAPTER - Remarks

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

PMIREQUEST_IDENTIFYADAPTER - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_QUERYMAXMODEENTRIES

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_QUERYMAXMODEENTRIESreturns the number of mode entries in the . PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXMODEENTRIES. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYMAXMODEENTRIES - Syntax

Description:

PMIREQUEST_QUERYMAXMODEENTRIESreturns the number of mode entries in the . PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXMODEENTRIES. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYMAXMODEENTRIES Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_QUERYMAXMODEENTRIES Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODEENTRIES.

PMIREQUEST_QUERYMAXMODEENTRIES Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_QUERYMAXMODEENTRIES Parameter - pOut

pOut(PVOID) - output Pointer to a ULONG.

PMIREQUEST_QUERYMAXMODEENTRIES Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMAXMODEENTRIES - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODEENTRIES.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a ULONG.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMAXMODEENTRIES - Remarks

None.

PMIREQUEST_QUERYMAXMODEENTRIES - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_QUERYMAXMODELISTSIZE

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_QUERYMAXMODELISTSIZEreturns maximum size required to save a SetMode command list.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXMODELISTSIZE. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYMAXMODELISTSIZE - Syntax

Description:

PMIREQUEST_QUERYMAXMODELISTSIZEreturns maximum size required to save a SetMode command list.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXMODELISTSIZE. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYMAXMODELISTSIZE Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_QUERYMAXMODELISTSIZE Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODELISTSIZE.

PMIREQUEST_QUERYMAXMODELISTSIZE Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_QUERYMAXMODELISTSIZE Parameter - pOut

pOut(PVOID) - output Pointer to a ULONG.

PMIREQUEST_QUERYMAXMODELISTSIZE Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMAXMODELISTSIZE - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXMODELISTSIZE.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a ULONG.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMAXMODELISTSIZE - Remarks

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

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

PMIREQUEST_QUERYMAXMODELISTSIZE - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_QUERYMODEINFODATA

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_QUERYMODEINFODATAcopies the PMI mode table to the caller.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYMODEINFODATA. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a MODEINFO data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYMODEINFODATA - Syntax

Description:

PMIREQUEST_QUERYMODEINFODATAcopies the PMI mode table to the caller.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYMODEINFODATA. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a MODEINFO data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYMODEINFODATA Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_QUERYMODEINFODATA Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMODEINFODATA.

PMIREQUEST_QUERYMODEINFODATA Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_QUERYMODEINFODATA Parameter - pOut

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

PMIREQUEST_QUERYMODEINFODATA Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMODEINFODATA - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMODEINFODATA.

pIn(PVOID) - input NULL.

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

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMODEINFODATA - Remarks

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

PMIREQUEST_QUERYMODEINFODATA - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_QUERYMAXTRAPENTRIES

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

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

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXTRAPENTRIES. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYMAXTRAPENTRIES - Syntax

Description:

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

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYMAXTRAPENTRIES. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  Pointer to a ULONG. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYMAXTRAPENTRIES Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_QUERYMAXTRAPENTRIES Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXTRAPENTRIES.

PMIREQUEST_QUERYMAXTRAPENTRIES Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_QUERYMAXTRAPENTRIES Parameter - pOut

pOut(PVOID) - output Pointer to a ULONG.

PMIREQUEST_QUERYMAXTRAPENTRIES Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMAXTRAPENTRIES - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMAXTRAPENTRIES.

pIn(PVOID) - input NULL.

pOut(PVOID) - output Pointer to a ULONG.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMAXTRAPENTRIES - Remarks

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

PMIREQUEST_QUERYMAXTRAPENTRIES - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_QUERYTRAPLISTDATA

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

PMIREQUEST_QUERYTRAPLISTDATAreturns an array of trap register information structures in the [TRAPREG] section of the .PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYTRAPLISTDATA. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYTRAPLISTDATA - Syntax

Description:

PMIREQUEST_QUERYTRAPLISTDATAreturns an array of trap register information structures in the [TRAPREG] section of the .PMI file.

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_QUERYTRAPLISTDATA. */
PVOID             pIn;         /*  NULL. */
PVOID             pOut;        /*  NULL. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_QUERYTRAPLISTDATA Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_QUERYTRAPLISTDATA Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYTRAPLISTDATA.

PMIREQUEST_QUERYTRAPLISTDATA Parameter - pIn

pIn(PVOID) - input NULL.

PMIREQUEST_QUERYTRAPLISTDATA Parameter - pOut

pOut(PVOID) - output NULL.

PMIREQUEST_QUERYTRAPLISTDATA Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYTRAPLISTDATA - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYTRAPLISTDATA.

pIn(PVOID) - input NULL.

pOut(PVOID) - output NULL.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYTRAPLISTDATA - Remarks

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

PMIREQUEST_QUERYTRAPLISTDATA - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_QUERYMODEHRDWRLIST

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

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

PMIREQUEST_QUERYMODEHRDWRLIST - Syntax

Description:

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

PMIREQUEST_QUERYMODEHRDWRLIST Parameter - pAdapter

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

PMIREQUEST_QUERYMODEHRDWRLIST Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMODEHRDWRLIST.

PMIREQUEST_QUERYMODEHRDWRLIST Parameter - pIn

pIn(PVOID) - input Pointer to a ULONG.

PMIREQUEST_QUERYMODEHRDWRLIST Parameter - pOut

pOut(PVOID) - output Pointer to VOID.

PMIREQUEST_QUERYMODEHRDWRLIST Return Value - rc

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMODEHRDWRLIST - Parameters

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

ulFunction(ULONG) - input Set equal to PMIREQUEST_QUERYMODEHRDWRLIST.

pIn(PVOID) - input Pointer to a ULONG.

pOut(PVOID) - output Pointer to VOID.

rc(APIRET) - returns Return codes.

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

PMIREQUEST_QUERYMODEHRDWRLIST - Remarks

None.

PMIREQUEST_QUERYMODEHRDWRLIST - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_SOFTWAREINT

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

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

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Can be NULL. If not NULL, the adapter must have been loaded. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SOFTWAREINT. */
PVOID             pIn;         /*  Pointer to an INITVDM data structure. */
PVOID             pOut;        /*  Pointer to an INTCRF data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SOFTWAREINT - Syntax

Description:

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

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Can be NULL. If not NULL, the adapter must have been loaded. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_SOFTWAREINT. */
PVOID             pIn;         /*  Pointer to an INITVDM data structure. */
PVOID             pOut;        /*  Pointer to an INTCRF data structure. */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_SOFTWAREINT Parameter - pAdapter

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

PMIREQUEST_SOFTWAREINT Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_SOFTWAREINT.

PMIREQUEST_SOFTWAREINT Parameter - pIn

pIn(PVOID) - input Pointer to an INITVDMdata structure.

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

PMIREQUEST_SOFTWAREINT Parameter - pOut

pOut(PVOID) - output Pointer to an INTCRFdata structure.

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

PMIREQUEST_SOFTWAREINT Return Value - rc

rc(APIRET) - returns Return codes.

Possible values follow:

NO_ERROR

ERROR_INADEQUATE_VDM_SUPPORT Make sure vprpmi.sys is installed.

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

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

PMIREQUEST_SOFTWAREINT - Parameters

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

ulFunction(ULONG) - input Set equal to PMIREQUEST_SOFTWAREINT.

pIn(PVOID) - input Pointer to an INITVDMdata structure.

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

pOut(PVOID) - output Pointer to an INTCRFdata structure.

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

rc(APIRET) - returns Return codes.

Possible values follow:

NO_ERROR

ERROR_INADEQUATE_VDM_SUPPORT Make sure vprpmi.sys is installed.

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

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

PMIREQUEST_SOFTWAREINT - Remarks

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

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

1.Full VDM.

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

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

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

Attention: LIMITATION

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

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

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

ERROR_INADEQUATE_VDM_SUPPORT Make sure vprpmi.sys is installed.

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

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

2.Mini VDM

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

Attention: LIMITATION

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

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

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

PMIREQUEST_SOFTWAREINT - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

PMIREQUEST_UNLOADPMIFILE

---

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

---

Description:

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

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_UNLOADFILE. */
PVOID             pIn;         /*  Pointer to the ASCII string of the .PMI file. */
PVOID             pOut;        /*  NULL */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_UNLOADPMIFILE - Syntax

Description:

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

#include <svgadefs.h>

PVIDEO_ADAPTER    pAdapter;    /*  Pointer to a VIDEO_ADAPTER data structure. */
ULONG             ulFunction;  /*  Set equal to PMIREQUEST_UNLOADFILE. */
PVOID             pIn;         /*  Pointer to the ASCII string of the .PMI file. */
PVOID             pOut;        /*  NULL */
APIRET            rc;          /*  Return codes. */

rc = VIDEOPMI32Request(pAdapter, ulFunction,
       pIn, pOut);

PMIREQUEST_UNLOADPMIFILE Parameter - pAdapter

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

PMIREQUEST_UNLOADPMIFILE Parameter - ulFunction

ulFunction(ULONG) - input Set equal to PMIREQUEST_UNLOADFILE.

PMIREQUEST_UNLOADPMIFILE Parameter - pIn

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

PMIREQUEST_UNLOADPMIFILE Parameter - pOut

pOut(PVOID) - output NULL

PMIREQUEST_UNLOADPMIFILE Return Value - rc

rc(APIRET) - returns Return codes.

Values are as follows:

NO_ERROR Successful completion

ERROR_ADAPTER_NOT_SUPPORTED The PMI file wasn't loaded.

PMIREQUEST_UNLOADPMIFILE - Parameters

pAdapter(PVIDEO_ADAPTER) - input Pointer to a VIDEO_ADAPTERdata structure .

ulFunction(ULONG) - input Set equal to PMIREQUEST_UNLOADFILE.

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

pOut(PVOID) - output NULL

rc(APIRET) - returns Return codes.

Values are as follows:

NO_ERROR Successful completion

ERROR_ADAPTER_NOT_SUPPORTED The PMI file wasn't loaded.

PMIREQUEST_UNLOADPMIFILE - Remarks

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

PMIREQUEST_UNLOADPMIFILE - Topics

Select an item:

Syntax
Parameters 
Returns 
Remarks 
Glossary 

Code Sample

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

#include <os2.h>

#include <svgadefs.h>


#define DLLNAME                 "videopmi"

#define REQUEST_ENTRYPOINT      "VIDEOPMI32Request"

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

}

VIDEO Protect-Mode Interface

This chapter describes the VIDEO Protect-Mode-Interface (VIDEOPMI) in OS/2 Warp. This interface is an extension of the 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:

�Limitations of the PMI

�Code vs. PMI

�How to Customize the PMI Subsystem for Your Device

�Supported Modes

�Monitor Timings Support

�Save and Restore State

�Adapter Configuration

�PMI Language Elements

�PMI Sections

Overview

The VIDEOPMI interface is procedurally represented by the exported functions of its main handler-VIDEOPMI.DLL. This handler provides both 32- bit and 16-bit entry points for setting a video mode, loading fonts, and saving and restoring the video state. The handler provides a mode query function and a software interrupt function, which allows for execution of real-mode software interrupts, such as VIDEO BIOS, from the protect mode.

VIDEOPMI.DLL imports the device-specific function from the underlying vendor- or IBM-provided PMI subsystem. This subsystem is comprised of any of the following:

1.Flat .PMI file with no code imports.

Although VIDEOPMI does not mandate the .PMI file name, at the moment SVGA Install and Configuration mandates \OS2\SVGADATA.PMI. Example: Any OS/2 2. x .PMI file.

2.Flat .PMI file with imported code sections from a dynamic link library ( DLL).

This is called a HYBRID.PMI file. Imported functions are private to the PMI subsystem and conform to the IMPORTPMI prototype as described in the SVGADEFS.H header file. Example: Any OS/2 3.x .PMI file.

3.Flat .PMI file with imported code sections from a DLL that chains into VIDEOPMI.

This is called a META-HYBRID.PMI file. The shared library exports a " LoadAdapter" function, which signals to VIDEOPMI that the handler wishes to engage in chaining VIDEOPMI's calls. The handler is passed the VIDEOPMI's calling function table and can modify the table by replacing entries with its own entry points. When these entry points are invoked, the handler can implement the call or pass it back to VIDEOPMI. Example: A .PMI file generated by SVGAOEM.EXE in the DDK.

4.META handler alone, without a flat file.

When VIDEOPMI's PMIREQUEST_LOADPMIFILE is passed a .DLL name and the specified shared library exports and successfully handles the "LoadAdapter" call, the PMI subsystem requires no flat file. This method of customizing the PMI subsystem is not in use because SVGA install, video configuration, and the virtual driver still make assumptions and use the flat .PMI file. Example: OEMPMI.DLL in the DDK.

For a full description of VIDEOPMI's procedural interface, see VIDEOPMI.DLL Exported Functions.

SVGADATA PMI file

The VIDEOPMI interface is driven by the sections of the 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 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. PMI language or as a call to an externally defined function. The two implementations are discussed in detail under Code vs. PMIin this chapter.

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

files are to be provided by the video chip or adapter manufacturers or by the providers of the display drivers. The file should be part of the video adapter installation kit, either as a pre-manufactured flat file or one created by the OEM's installation utility.

Limitations of the PMI

The following limitations exist in the PMI:

�.PMI does not provide a graphical interface.

�.PMI does not provide a means of accessing addresses that are internal to the video controller and are not mappable into the CPU space.

�Save and Restore Hardware State Services have certain limitations (see " Save and Restore State" in this chapter).

�.PMI does not provide the means to manipulate certain video parameters outside the context of the SetMode section.

.PMI does allow, and it requires, indirect management of all of the parameters within the Mode Set sections. For example, there are no services for the manipulation of the hardware cursor or RAMDAC outside the context of a mode set. These services are an integral part of the SetMode.

Programming of the monitor timing is considered a special case. It is an integral part of the SetMode, but it also can be independently invoked, if the .PMI file defines a SetMonitorTimings section. The same is true for manipulation of the active display size. If the PMI file contains a TuneDisplay section, this manipulation is offered independently.

�Port descriptions have some limitations, as follows:

-Ports that require double or triple indirection cannot be adequately described in the PMI language.

-I/O addresses that serve as latches, or flip-flops, cannot be successfully described.

-There are no provisions for describing port addresses that define different registers depending on the read or write access.

These limitations have an influence on the level and success of the adapter virtualization using the system-provided virtual driver. See [TrapRegs] in PMI Sections.

Code vs. PMI

The Set type of sections can be implemented as pure PMI language constructs , as pure imported functions from an external binary object or as a mixture of the two. Each implementation has its benefits and its drawbacks. The vendor creating the PMI file should carefully evaluate which method is the most appropriate and beneficial.

.PMI Language Constructs only

Full use of the PMI language hides the implementation of the I/O and MMIO access on a particular hardware and operating system platform from the vendor creating the PMI file. This method provides good portability and code reuse. The initial cost in creating the SVGADATA.PMI file is mainly in rewriting the existing source into the PMI sequences.

Another benefit of this implementation is tighter execution control. Since the VIDEOPMI would be totally data-driven, the chances for memory violations and other execution hazards are minimized.

This implementation should not be used for timing-sensitive hardware, since the interpretation of PMI sequences creates an execution overhead that cannot be fine-tuned at the current time.

Note:SVGADATA.PMI files created internally by IBM are written either in full PMI language or in a mixture of PMI language and imported functions to cover as many chip sets as possible.

Imported Functions only

This implementation provides the greatest code reuse of the source objects already created and used elsewhere by the vendors. It also provides the performance needed in programming the timing-sensitive chip sets. Importing code also allows the vendor to call VIDEO BIOS as as means of implementing the exported function. This can be achieved only from a shared library. A flat .PMI file will not call VIDEOPMI's entry point. Provided that the shared library exports the "Load Adapter" API and conforms to the META-PMI definition, this method also allows for modifying VIDEOPMI's function by chaining into its calling table.

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

.PMI Language Constructs + Imported Functions

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

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

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

Note:The imported library (OEMPMI.DLL) that is shipped with the IBM Developer Connection Device Driver Kit for OS/2illustrates the importing functions.

Sample .PMI File Using Imported PMI Binary Object

This section diagrams a sample .PMI file. The sample file is shipped by a chip-set vendor and supports a number of adapter implementations of the vendor's chip set. All of the adapter-specific functions are handled by the imported PMI functions from the VENDOR.DLL dynamic link library. The adapter-specific [Hardware] section, which provides the description for the specific implementation identified on the user's machine, is provided in the VENDOR.PMI Include file.

Thus, by copying different Include files, together with the master SVGADATA .PMI and VENDOR.DLL files, specific adapter installation is covered with minimum investment in a utility for formatting the .PMI file.

The generic PMI file lists all of the modes possible, with the maximum memory configuration for the chip. It also lists reasonable timing limits per mode that should be supported by all adapters. This information provides the filtering service to the configuration utility, which presents the timing choices to the user. Should a particular adapter's capabilities be lower than the timing values set, the SetMonitorTimings function should perform verification of the input parameters in order to protect the hardware. If the adapter's capabilities vary greatly, the PMI file should be formatted to reflect the correct MonitorModeInfo for the adapter.

/*
** Vendor include PMI file VENDOR.PMI
*/
BusType             = ADAPTER_BUS_TYPE
OEMString           = "CHIPSET_NAME ADAPTER_NAME, ADAPTER_MANUFACTURER_NAME"
DACString           = "DAC_MANUFACTURER_NAME, DAC_NAME"
Version             = "3.2"
TotalMemory         = ACTUAL_VRAM_MEMORY_SIZE
MemoryIOAddress     = MMIO_ADDRESS
PortIOAddress       = PIO_ADDRESS
Endian              = LITTLE

/*
** Generic PMI file
*/
[PMIVersion]        2.2
#includecode        "vendor.DLL"   //exports all fnPMI entry points used
in this PMI file
#include            "vendor.PMI"

/*
 *        List of declared ports. Required if adapter is dynamically
 *        configurable
*/
[Declarations]
MRegisterA =MMIO{0x00180298}
...
/*
 *    List of I/O and MMIO ports to be trapped
*/

[TrapRegs]
DWORD_MMIOPORT RW ACCEL MRegisterA;
...

[EnableController]
call fnPMIEnableController;

[DisableController]
call fnPMIDisableController;

[UnLock]
call fnPMIUnlock;

[Cleanup]
call fnPMICleanup;

[GetBank]
call fnPMIGetBank;

[SetBank]
call fnPMISetBank;

[SetMonitorTimings]
call fnPMIProgramTimings;

[TuneDisplay]
call fnPMITuneDisplay;

[comment]
Graphics Mode: 640 x 480 x 16 colors.
[ModeInfo]
ModeAttributes      = 0x18
BytesPerScanLine    = 640
XResolution         = 640
YResolution         = 480
TextRows            = 30
BitsPerPixel        = 4
NumberOfPlanes      = 4
PageLength          = 38400
SaveSize            = 153600
Int10ModeSet        = 0x012
BufferAddress       = 0x000a0000
ApertureSize        = 0x00010000
[MonitorModeInfo]
VerticalRefresh     = 72
HorizontalRefresh   = 38
ScreenLeftEdge      = 0x00000021
ScreenRightEdge     = 0x000000C1
ScreenTopEdge       = 0x00000019
ScreenBottomEdge    = 0x000001F9 

[ comment ] 
Graphics   Mode :   640   x   480   x   256   colors . 
[ ModeInfo ] 
ModeAttributes        =   0x18 
BytesPerScanLine      =   640 
XResolution           =   640 
YResolution           =   480 
TextRows               =   30 
BitsPerPixel          =   8 
NumberOfPlanes        =   1 
PageLength            =   307200 
SaveSize               =   307200 
BufferAddress         =   LinearWindowAddress 
ApertureSize          =   0x00200000 
[ MonitorModeInfo ] 
VerticalRefresh       =   72 
HorizontalRefresh     =   38 
ScreenLeftEdge        =   0x00000021 
ScreenRightEdge       =   0x000000C1 
ScreenTopEdge         =   0x00000019 
ScreenBottomEdge      =   0x000001F9 

[ comment ] 
Graphics   Mode :   640   x   480   x   64K   colors . 
[ ModeInfo ] 
ModeAttributes        =   0x18 
BytesPerScanLine      =   1280 
XResolution           =   640 
YResolution           =   480 
TextRows               =   30 
BitsPerPixel          =   16 
NumberOfPlanes        =   1 
PageLength            =   614400 
SaveSize               =   614400 
ColorFormat           =   " RGB " 
ColorWeight           =   " 5 : 6 : 5 " 
BufferAddress         =   LinearWindowAddress 
ApertureSize          =   0x00200000 
[ MonitorModeInfo ] 
VerticalRefresh       =   72 
HorizontalRefresh     =   38 
ScreenLeftEdge        =   0x00000021 
ScreenRightEdge       =   0x000000C1 
ScreenTopEdge         =   0x00000019 
ScreenBottomEdge      =   0x000001F9 

[ comment ] 
Graphics   Mode :   800   x   600   x   256   colors . 
[ ModeInfo ] 
ModeAttributes        =   0x18 
BytesPerScanLine      =   800 
XResolution           =   800 
YResolution           =   600 
TextRows               =   37 
BitsPerPixel          =   8 
NumberOfPlanes        =   1 
PageLength            =   480000 
SaveSize               =   480000 
BufferAddress         =   LinearWindowAddress 
ApertureSize          =   0x00200000 
[ MonitorModeInfo ] 
VerticalRefresh       =   72 
HorizontalRefresh     =   48 
ScreenLeftEdge        =   0x0000002B 
ScreenRightEdge       =   0x000000F3 
ScreenTopEdge         =   0x0000001D 
ScreenBottomEdge      =   0x00000275 

[ comment ] 
Graphics   Mode :   1024   x   768   x   256   colors . 
[ ModeInfo ] 
ModeAttributes        =   0x18 
BytesPerScanLine      =   1024 
XResolution           =   1024 
YResolution           =   768 
TextRows               =   48 
BitsPerPixel          =   8 
NumberOfPlanes        =   1 
PageLength            =   786432 
SaveSize               =   786432 
BufferAddress         =   LinearWindowAddress 
ApertureSize          =   0x00200000 
[ MonitorModeInfo ] 
VerticalRefresh       =   72 
HorizontalRefresh     =   58 
ScreenLeftEdge        =   0x00000041 
ScreenRightEdge       =   0x00000141 
ScreenTopEdge         =   0x00000021 
ScreenBottomEdge      =   0x00000321 

[ SetMode ] 
call   fnPMISetMode ; 
[ comment ] 
Text   Mode :   80   cols ,   25   rows . 
[ ModeInfo ] 
ModeAttributes        =   0x08 
BytesPerScanLine      =   80 
XResolution           =   720 
YResolution           =   400 
XCharSize              =   9 
YCharSize              =   16 
TextRows               =   25 
BitsPerPixel          =   4 
NumberOfPlanes        =   1 
PageLength            =   4000 
SaveSize               =   4000 
Int10ModeSet          =   0x003 
VerticalRefresh       =   60 
BufferAddress         =   0x000b8000 
ApertureSize          =   0x00008000 

[ SetMode ] 
call   fnPMISetTextMode ; 

How to Customize the PMI Subsystem for Your Device

The VIDEO PMI subsystem consists of VIDEOPMI-the main PMI handler, a flat PMI file, and optional imported library modules. The imported library modules may optionally chain into VIDEOPMI and provide a filter or replacement for VIDEOPMI's entry points. Such a library is called a META- PMI handler. Although the VIDEO PMI subsystem places no requirements on the existence of a flat PMI file (it is possible to provide all functions with a META-PMI handler alone), the SVGA installation, SVGA virtual video driver , BVHSVGA, and VIDEOCFG all make assumptions that the PMI subsystem is represented by SVGADATA.PMI.

The VIDEOPMI handler is maintained by IBM; it is shipped in the IBM Developer Connection Device Driver Kit for OS/2 as a binary file. See Video Subsystem Binary Files. The SVGADATA.PMI file is either provided or can be created at install time by running a utility. The SVGA installation action routine DLL (SVGA.DLL) assumes that a DOS utility called SVGA.EXE is used to generate the SVGADATA.PMI. A vendor wishing to modify the SVGADATA.PMI can provide its own action routine DLL or create the SVGA.EXE DOS utility. DDK sources include two different sources of a utility that generates the SVGADATA.PMI file, as follows:

�src\svdh\svgautil\svga.exe

src\svdh\svgautil sources are those of the SVGA.EXE as shipped by IBM. It is a very large and complex source that generates a .PMI file for all of the devices supported by the IBM BBS display driver packages at the time the IBM Developer Connection Device Driver Kit for OS/2 was shipped.

Vendors should not modify this source; it is shipped so that vendors can create sample .PMI files for legacy hardware. PMI files created by this utility use IBMGPMI.DLL as an imported PMI library. The source for IBMGPMI .DLL is not available for vendor modification, but a binary file can be extracted from the most current IBM BBS video driver package. An older version of IBMGPMI can be found in previous DDKs.

For purposes of documenting an imported PMI library, an alternate library source in src\oempmi for OEMPMI.DLL is provided. This PMI library exemplifies both internal PMI calls and the META-PMI interface (chaining into VIDEOPMI). It also provides an example of using the VIDEOPMI's software interrupt API to call the VIDEO BIOS directly.

�src\oempmi\svgautil\svgaoem.exe

src\oempmi\svgautil sources are the recommended sources for vendor modification. The makefile will generate an SVGAOEM.EXE, which should be renamed to SVGA.EXE if the SVGA.DLL action routine DLL is to be used. The utility will create a generic SVGADATA.PMI file based solely on VESA mode support without any vendor modifications. This generic .PMI file depends on the OEMPMI.DLL META-PMI handler, referred to in the previous bullet, for successful VESA BIOS calls. If there is no VESA support for the adapter, or vendors wish to add refresh support or customize the generic sections, the SetupChipInfo function in SVGAOEM.C needs to be modified. The header of the SVGAOEM.C source file includes the "ROADMAP to CHANGES" instructions.

src\oempmi sources are open to vendor modification, and its headers also include extensive instructions on the recommended changes. However, for a vendor with VESA mode set support and a display driver that can run on top of the hardware state as left by the VESA mode set, the quickest results are obtained by doing the following:

-Install all of the Base Video Subsystem files.

-Create a .PMI file by running the unmodified SVGAOEM.EXE with command line argument "ON".

Supported Modes

This section lists the OS/2 Warp requirements for the modes included in 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.

VGA modes

adapter in question (or on its VGA daughter card). If the modes are not included, they are set by first invoking the Cleanup function and then letting the base video handler set the standard VGA mode. If the Cleanup function is not successful, the mode set may fail to set the adapter to a stable state. Therefore, It is suggested that VGA modes be handled by the same PMI file.

Suggested modes include the following:

�640x480x16 graphics

�40x25 and 80x25 text

Extended modes

Extended modes include the following:

�At least one of the 132-column text modes (if applicable).

�At best, all of the supported 256-color modes with respective refresh rates (see Monitor Timings Supportin this chapter).

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

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

�At best, all of the supported hi-color and true-color modes with respective refresh rates (see Monitor Timings Supportin this chapter).

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

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

Custom modes

Custom modes are those modes that use non-RGB color formats, as well as modes that target a special monitor.

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.

For a full description of Video Configuration, see

Save and Restore State

VIDEOPMI does not have dedicated SaveState or RestoreState sections. The VIDEOPMI engine does offer those services. PMIREQUEST_SAVESTATEin VIDEOCFG .DLL Exported Functions.

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. function calls become a no-op.

The virtual video driver and desktop driver do perform their own Save and Restore of the state and are not dependent on the service. The PMI-enabled base video handler uses the Save and Restore State service and, in case of a partial restore, 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.

There are two basic types of adapters:

�those that support Plug and Play (PCI, PnP-ISA) and allow the device to define the resources and to be programmed dynamically to use the resources

�those called Legacy hardware (MC-A, ISA, EISA), which use predefined system resources

There also are adapters that are configurable in terms of the memory range and that coexist with a Legacy VGA controller; these will be referred to as Configurable Legacy adapters. Another type of Configurable Legacy adapter can co-reside with properly configured instances of the same adapter, such as MC-A XGA*.

Three PMI sections, IdentifyAdapter, EnableController and DisableController , are used to identify, configure and enable video adapters in conjunction with any PnP configuration BIOS services available to the operating system' s configuration manager. The identification function verifies if hardware matching the OEMString description is present on the system. It does not verify if the configuration is set to the default Hardware values specified in the PMI file.

The primary functions of EnableController and DisableController are to control the sync generation for controllers sharing the sync generation function with a VGA chip. The secondary function of the EnableController is to provide configuration for the Configurable Legacy adapters and to verify if the configuration matches the passed hardware values for Static Legacy and PnP hardware.

For a static Legacy adapter, where the configuration is hard-wired, there is no need to declare its I/O and Memory base addresses, nor is there a need to declare its registers. The EnableController and DisableController should only ensure that the device acquires and relinquishes control over the sync generation. For coprocessors that co-reside with VGA chips, EnableController should disable VGA and enable the coprocessor. DisableController enables the VGA chips.

For a Configurable Legacy adapter, in which a configurable memory-mapped coprocessor co-resides with a hard-wired VGA controller, the MemoryIOAddress and memory-mapped registers of the coprocessor should be declared, not hardcoded. DisableController enables the VGA chip and EnableController configures and enables the coprocessor at the current MemoryIOAddress, if this can be done through software. If it cannot be done, the EnableController function should verify whether the hardware is configured for the passed MemoryIOAddress. If it is not so configured, the return code is set to reflect that situation.

In the case of Configurable Legacy adapters that can co-reside, the PortIO and MemoryIO addresses are used to provide addressability to different instances. The EnableController function verifies if the configuration for a particular instance is complete and, if not, completes it. For example, a user may have run the Reference diskette to configure 3 XGAs, so the instances are already configured in terms of their I/O space. However, the user may not have configured the Memory-mapped portion, which is required for the desktop driver. The PMI file's EnableController should complete the configuration.

For PnP adapters, the configuration is performed through the PnP BIOS, if such BIOS is available. If it is not available, the EnableController can be used to configure the controller as well as enable its sync generation. Consequently, DisableController disables the coprocessor and enables the sync generation by a co-residing VGA chip (if one exists). See [ EnableController] and [DisableController] in PMI Sections.

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 all of which must conform to the PMI language. The include files should be in the same directory as 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.

1. include "filename" //.PMI extension assumed

1. includecode "filename" //DLL extension assumed

Constants, String-Literals, Identifiers, and Keywords

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

<digit>  ::= '0'..'9'
<hexdigit> ::= <digit>  |  'a'..'f'
<character> ::= 'a'..'z' |  'A'..  'Z'|  '_' |  '.'
<decimal number>  ::= <digit>  |  <decimal number> <digit>
<hexadecimal number>  ::= '0x' <hexdigit>  |
                         <hexadecimal number>  <hexdigit>
<constant>  ::= <decimal number>  |  <hexadecimal number>

Any combination of printable ASCII characters in quotes is considered a string-literal. String-literals are not parsed in any way. They are stored in their uppercase format and are passed on query-style calls, converting both source and target to uppercase. String-literals are limited to 128 characters in length, including 0 at the end. Binary strings are also limited to 128 bits (4 doublewords).

<string>  ::= "<ASCII character> [<string>.]"
<binary-string>  ::= " <'0'|'1'> | <'0'|1'> [<binary-string>.]"

An Identifier, or a name, is a sequence of letters and digits. The first character must be a letter. The underscore (_) and point (.) count as a letter, but point (.) cannot be used in the first position. Maximum length of an identifier is 32 characters.

<name>  ::= <character>  <token>
<token>  ::= {<character>  |  [<digit> <token>.]}

Reserved identifiers are called keywords. Keywords are divided into three groups:

�.PMI keyvariables, which are keywords representing configuration and mode parameters

�.PMI constants, backed by system-wide definitions

�All other reserved identifiers

All of the PMI keyvariables are available through the VIDEOPMI programming interface as fields of the video instance structure. They are also available to all of the PMI sections and functions and can be used in conditional statements or expressions. At run time, during a SetMode, some of the ModeInfo PMI keyvariables could differ from the values assigned by the .PMI file. These PMI keyvariables can be modified at the user or system level and are therefore regarded as Dynamic. Others are called Static. At the procedural level, static PMI keyvariables are fixed to the values specified in the .PMI file and cannot be changed for a given mode. Some dynamic variables have a limited set of possible values; others are valid in a range that should be verified by dedicated sections. See [ ModeInfo], [Hardware] and [TuneDisplay] in PMI Sectionsfor more information on dynamic vs. static keyvariables.

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

.PMI Keyvariables

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

/-------------------------------------------------------------\
|Name                          |Section                       |
|------------------------------+------------------------------|
|ApertureSize                  |ModeInfo                      |
|------------------------------+------------------------------|
|BitsPerPixel                  |ModeInfo                      |
|------------------------------+------------------------------|
|BufferAddress                 |ModeInfo                      |
|------------------------------+------------------------------|
|BusType                       |Hardware                      |
|------------------------------+------------------------------|
|BytesPerScanLine              |ModeInfo                      |
|------------------------------+------------------------------|
|ColorFormat                   |ModeInfo                      |
|------------------------------+------------------------------|
|ColorWeight                   |ModeInfo                      |
|------------------------------+------------------------------|
|DACString                     |Hardware                      |
|------------------------------+------------------------------|
|Endian                        |Hardware                      |
|------------------------------+------------------------------|
|HorizontalRefresh             |MonitorModeInfo               |
|------------------------------+------------------------------|
|HPolarityPositive             |MonitorModeInfo               |
|------------------------------+------------------------------|
|Int10ModeSet                  |ModeInfo                      |
|------------------------------+------------------------------|
|MemoryIOAddress               |Hardware                      |
|------------------------------+------------------------------|
|ModeAttributes                |ModeInfo                      |
|------------------------------+------------------------------|
|NumberOfPlanes                |ModeInfo                      |
|------------------------------+------------------------------|
|OEMString                     |Hardware                      |
|------------------------------+------------------------------|
|PageLength                    |ModeInfo                      |
|------------------------------+------------------------------|
|PortIOAddress                 |Hardware                      |
|------------------------------+------------------------------|
|SaveSize                      |ModeInfo                      |
|------------------------------+------------------------------|
|ScreenLeftEdge                |MonitorModeInfo               |
|------------------------------+------------------------------|
|ScreenRightEdge               |MonitorModeInfo               |
|------------------------------+------------------------------|
|ScreenBottomEdge              |MonitorModeInfo               |
|------------------------------+------------------------------|
|ScreenTopEdge                 |MonitorModeInfo               |
|------------------------------+------------------------------|
|SlotID                        |EnableController              |
|------------------------------+------------------------------|
|TextRows                      |ModeInfo                      |
|------------------------------+------------------------------|
|TotalMemory                   |Hardware                      |
|------------------------------+------------------------------|
|VerticalRefresh               |MonitorModeInfo               |
|------------------------------+------------------------------|
|VPolarityPositive             |MonitorModeInfo               |
|------------------------------+------------------------------|
|XCharSize                     |ModeInfo                      |
|------------------------------+------------------------------|
|XResolution                   |ModeInfo                      |
|------------------------------+------------------------------|
|YCharSize                     |ModeInfo                      |
|------------------------------+------------------------------|
|YResolution                   |ModeInfo                      |
\-------------------------------------------------------------/

.PMI Constants

The following table lists the constants used by the Protect Mode Interface (PMI).

/-------------------------------------------------------------\
|Name                          |Section                       |
|------------------------------+------------------------------|
|BIG                           |Hardware                      |
|------------------------------+------------------------------|
|EISA                          |Hardware                      |
|------------------------------+------------------------------|
|ISA                           |Hardware                      |
|------------------------------+------------------------------|
|LITTLE                        |Hardware                      |
|------------------------------+------------------------------|
|MCA                           |Hardware                      |
|------------------------------+------------------------------|
|MMIO                          |Declarations                  |
|------------------------------+------------------------------|
|PCI                           |Hardware                      |
|------------------------------+------------------------------|
|PCMCIA**                      |Hardware                      |
|------------------------------+------------------------------|
|PIO                           |Declarations                  |
|------------------------------+------------------------------|
|VLB                           |Hardware                      |
\-------------------------------------------------------------/

.PMI Keywords

The following table lists the reserved identifiers, called Keywords, used by the Protect Mode Interface (PMI).

/-------------------------------------------------------------\
|Name                          |Section                       |
|------------------------------+------------------------------|
|[Cleanup]                     |.PMI sections                 |
|------------------------------+------------------------------|
|[Comment]                     |.PMI sections                 |
|------------------------------+------------------------------|
|[Declarations]                |.PMI sections                 |
|------------------------------+------------------------------|
|[GetBank]                     |.PMI sections                 |
|------------------------------+------------------------------|
|[Hardware]                    |.PMI sections                 |
|------------------------------+------------------------------|
|[IdentifyAdapter]             |.PMI sections                 |
|------------------------------+------------------------------|
|[ModeInfo]                    |.PMI sections                 |
|------------------------------+------------------------------|
|[MonitorModeInfo]             |.PMI sections                 |
|------------------------------+------------------------------|
|[PMIVersion]                  |.PMI sections                 |
|------------------------------+------------------------------|
|[SetBank]                     |.PMI sections                 |
|------------------------------+------------------------------|
|[SetMode]                     |.PMI sections                 |
|------------------------------+------------------------------|
|[SetMemoryIOAddress]          |.PMI sections                 |
|------------------------------+------------------------------|
|[TrapRegs]                    |.PMI sections                 |
|------------------------------+------------------------------|
|[TuneDisplay]                 |.PMI sections                 |
|------------------------------+------------------------------|
|[UnLock]                      |.PMI sections                 |
|------------------------------+------------------------------|
|ABOUTDW                       |.PMI commands                 |
|------------------------------+------------------------------|
|ABOUTW                        |.PMI commands                 |
|------------------------------+------------------------------|
|BINB                          |.PMI commands                 |
|------------------------------+------------------------------|
|BOUTB                         |.PMI commands                 |
|------------------------------+------------------------------|
|CALL                          |.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>  = <'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

There are two types of functions, internalPMI functions and importedPMI functions. The Internalfunction is defined as a PMI Section with a user- defined name other than one of the predefined Section names. ImportedPMI functions are not declared, but are assumed, to be of the IMPORTPMI prototype. They are imported from external binary objects that have been included using the #includecode directive.

�Internal PMI functions

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

�Imported PMI functions

The IMPORTPMI function entry point is defined as follows:

(APIRET APIENTRY
*fnImportPMI)(VIDEO_ADAPTER
*pVideoInstance,
               PULONG (pRegisters)

APIRET returns 0 for success and nonzero (DOS errors) for failure.

APIENTRY refers to the _Syscall (C) calling convention.

-Functions are invoked using the PMI CALL command; for example, call fnFunctionName;.

-Current VIDEO_ADAPTERaddress and the start address of the registers are passed on the stack.

-A return value of 0 indicates success (r0 should also be set if subsequent PMI command sequences will need to evaluate the return code).

-Registers should be used to pass values from the PMI command sequences preceding the function call, if that is necessary.

-Full programming and development specifications for the imported binary objects will be available with the device driver development kit.

.PMI functions should be used extensively to create commonality and to encapsulate related operations. This use will reduce development costs, support more adapter-specific variations, reduce the size of the .PMI file, and improve performance.

The VIDEO_ADAPTERstructure is passed by PMI procedural callers at every PMI entry point and is available to all of the PMI functions other than IdentifyAdapter. All PMI functions have addressability to the current state of the PMI registers and care should be taken in using the registers.

.PMI Commands

PMI commands are divided into several categories, as follows:

�Simple I/O commands

�Block I/O commands

�Read/Modify/Write commands

�Simple memory access commands

�WAIT command

INx Commands

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

INB( destination, source);
INW( destination, source);
INDW( destination, source);

<destination>  ::= <register>
<source> ::= <constant>  |  <pio variable>

OUTx Commands

OUTx commands perform an I/O output from the source into the destination. Width can be byte, word, or doubleword. The syntax is as follows:

OUTB( destination, source);
OUTW( destination, source);
OUTDW( destination, source);

<destination>  ::= <pio variable>  |  <constant>
<source>  ::= {<constant>  |  <register>}

For example:

outb(seq_address,r1);              //seq_address must have been declared.
outw(0x3c4,0x5520);

Block I/O Commands

Block I/O commands are designed for indexed ports. Byte-indexed access requires both index and data port values. Word and Dword block I/O is implemented as autoincrement block I/O, which causes no explicit modification to the index register. Word and Dword block I/O assumes that the hardware either implements autoincrementing or that the values being written specify both index and data. The startindexfield is used as the index of the first PMI register in the set and as the first indexed port value. If the hardware's autoincrementing feature needs to be programmed explicitly, it should be done prior to calling the block I/O and should be left enabled upon completion of the mode set. See "Save and Restore State" , and [TrapRegs] in PMI Sections.

BINB( count, startindex, indexport, dataport );
BOUTB( count,startindex, indexport, dataport );

<startindex>  ::= <constant>
<count>  ::= <constant>
<indexport>  ::= <pio variable>  |  <constant>
<dataport>  ::= <pio variable>  |  <constant>
<port>  ::= <pio variable>  |  <constant>

For example:

r0 = 0x11; r1 = 0x12; r2 = 0x13;
boutb(0x03, 0x00, seq_address, seq_data);   //seq_address and seq_data
                                            //already declared.

RMWx Commands

RMWx (Read/Modify/Write) commands are available in byte format (indexed or nonindexed) and in word format (nonindexed). A nonindexed port RMWx can be used for ports that have different read and write access I/O addresses. The syntax is as follows:

RMWBI( indexport, dataport, index, andmask, ormask );
RMWB( bytereadport, bytewriteport, andmask, ormask );
RMWW( wordreadport, wordwriteport, andmask, ormask );

<indexport>  ::= <pio variable>  |  <constant>
<dataport>  ::= <pio variable>  |  <constant>
<bytereadport>  ::= <pio variable>  |  <constant>
<bytewriteport>  ::= <pio variable>  |  <constant>
<wordreadport>  ::= <pio variable>  |  <constant>
<wordwriteport>  ::= <pio variable>  |  <constant>
<index>  ::= <constant>
<andmask>  ::= <constant>
<ormask>  ::= <constant>

For example:

rmww(0x4ae8, 0x4ae8, 0x01, 0x00);

Note:Old PMI syntax (PMIVersion prior to 2.2) had ambiguous definitions for RMWW and RMWB. RMWB was used for indexed, RMWW for nonindexed, both byte and word access. The old definitions are no longer supported.

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>

CALL Command

The CALL command performs a call to an imported PMI function entry point. Function entry point addresses are resolved at parsing (loading) time, by querying the procedural entry points of the dynamic libraries that were imported by the #includecode directive. Failing to resolve the addresses fails the loading of the PMI file. The calling convention is _Syscall (C). A return value of 0 denotes success; otherwise, an error applicable to the operating system should be returned.

Internal PMI functions are called implicitly by specifying the function's name. See PMI Sectionsfor more information.

CALL function;
<function>  ::= identifier

For example:

[SetMode]        //set mode section
call fnPMISetMode;                      //call imported fnPMISetMode function

.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. functions or by using a mix of the two. See "Code vs. PMI" for an illustration of the PMI sections using imported functions.

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 is used to describe the PMI language revision level used. PMI files with older revisions (or no PMIVersion level) will not be supported by the VIDEOPMI interpreter.

[Hardware]

�BusType = { ISA | VLB | PCI | EISA | PCMCIA | MCA }

The hardware description is available through a system query function. Any other definition is regarded as a user definition.

�OEMString = "CHIPNAME ADAPTERNAME, ADAPTER MANUFACTURER NAME"

OEMString has an internal length of 128 chars, 0 ended. This string should be sufficient to uniquely describe the video adapter. The string will be presented to the user at configuration and installation and is the key element of the system's description of the adapter. It is regarded as a user definition, meaning that no translation of this information to any other format is performed. Any trademark information should be provided as a comment in the PMI file.

If the PMI file is not specifically written for an adapter, the ADAPTERNAME GENERIC is suggested (such files may be shipped by the chip manufacturers or software vendors). CHIPNAME is a required token and is used as a key in the display driver installation process to find a corresponding display driver for a given PMI file (and vice versa).

�DACString = "MANUFACTURER NAME [, DACNAME]"

DACNAME, such as Bt485 or AT&T 491 is optional. Regarded as a user definition. Any trademark information should be provided as a comment.

�Version = <string>

User-defined. Should represent the version of the manufacturer's .PMI file , rather than the revision level of the hardware. If multiple versions of the .PMI file exist for the same OEMString description, and all respective IdentifyAdapter function calls were successful, the file with the greater Version string is assumed to be the more appropriate one and is offered at the top of the PMI list during the video configuration.

The user, however, does have a choice of selecting a different PMI file. Note that the PMIVersion section is used to describe the PMI language revision level used, not the version of the PMI file.

�TotalMemory = <constant>

This represents the total size of the currently installed VRAM memory in bytes.

�MemoryIOAddress = <constant> [`{.' <mmio list> `}.'] <mmio list> : := <constant> | <constant> [`,' <mmio list>.]

Specifies the default base memory address for memory mapped I/O and a list of possible base addresses. The default value should match the value set by the configuration performed at the time of the adapter's installation. It is possible to reconfigure the adapter's address at a later time without modifying the .PMI file.

If this address is specified and is not zero, the BufferAddress fields in the [ModeInfo] sections of all graphics modes with more than 256 colors will be replaced by this address and the usFlag in the VIDEOMODEINFOstructure will have MODE_FALG_LINEAR_BUFFER flag set to on, indicating that this mode can be set to linear aperture mode. [SetMemoryIOAddress] should also be provided to handle the address setting.

�PortIOAddress = <constant> [`{.' <pio list> `}.'] <pio list> ::= < constant> | <constant> [`,' <pio list>.]

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

�Endian = {BIG | LITTLE}

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

-The device can conform to the endian type of the platform, such as WEITEK or XGA.

-The device cannot conform to the endian type but is of the same endian type as the platform.

-The device is of a different endian type than the platform on which it is installed.

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

Here is a sample 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 file for a Viper VLB card:

sysconfig   = MMIO{0x00100004}
interrupt_en= MMIO{0x0010000c}
x0y0        = MMIO{0x00181018}
x1y1        = MMIO{0x00181028}
x2y2        = MMIO{0x00181048}
x3y3        = MMIO{0x00181068}
cindex      = MMIO{0x0018018c}
w_off.xy    = MMIO{0x00180190}
fground     = MMIO{0x00180200}
bground     = MMIO{0x00180204}
pmask       = MMIO{0x00180208}
draw_mode   = MMIO{0x0018020c}
pat_originx = MMIO{0x00180210}
pat_originy = MMIO{0x00180214}
raster      = MMIO{0x00180218}
pixel8_reg  = MMIO{0x0018021c}
w_min       = MMIO{0x00180220}
w_max       = MMIO{0x00180224}
pattern0    = MMIO{0x00180280}
pattern2    = MMIO{0x00180284}
pattern4    = MMIO{0x00180288}
pattern6    = MMIO{0x0018028c}
pattern8    = MMIO{0x00180290}
patternA    = MMIO{0x00180294}
patternC    = MMIO{0x00180298}
patternE    = MMIO{0x0018029c}

[TrapRegs]

Currently, the [TrapRegs] section is only parsed and used by virtual video driver (vsvga.sys). videopmi.dll does not interpret the contents.

[IdentifyAdapter]

This is a required section and should perform the adapter identification. Recommended identification steps depend on the bus architecture and hardware support for the identification. For example, on a PCI adapter, a positive check of the PCI device ID, revision ID, and vendor ID would be sufficient. On an ISA card, a physical memory location can be read and compared against a string or a binary key, using MEMCMP and STRCMP PMI commands. Or, an identification port could be read in order to confirm the adapter type and revision level. The dependency on familiar port response should be minimal and resorted to only if more reliable checks do not exist . For vendors writing .PMI files for generic adapter support, however, this may be the only option, and it should be implemented with great care.

Register r0 is used to hold the function result. The register should contain zero if the adapter matches its Hardware description (OEMString and DACString in its entirety) or nonzero otherwise.

The purpose of the IdentifyAdapter function is to verify that an instance of the adapter is found that matches the OEMString and Version string from the .PMI file's Hardware section. Whether multiple instances exist, or if the instance found is not configured to the passed MemoryIOAddress and PortIOAddress, is of no consequence.

An adapter is considered available if its IdentifyAdapter section returns success. Consequently, if the .PMI file contains the minimum VIDEOPMI content, its .PMI file will be loaded.

Attention:

It is essential that any I/O or MMIO registers modified in this section be saved and restored! This is of great importance, as IdentifyAdapter sections from a .PMI file will be executed on nonrelated hardware in an attempt to find the corresponding .PMI file.

[SetMemoryIOAddress]

This section provides a way to set the linear apertures after the mode set. It can be executed through PMIREQUEST_SETMEMORYIOADDRESS. The passed address in that function will replace r0 in the PMI commands. Please see MemoryIOAddress under the [Hardware] section and PMIREQUEST_SETMODEfor details.

[UnLock]

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

Here is a sample 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 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 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 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. VIDEOCFG.DLL Exported Functionsfor information on video configuration.

Here is a sample 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 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 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 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 The settings are also available as PMI keyvariables to the PMI language On dynamic Legacy and PnP hardware, or when a coprocessor co-resides with a VGA chip, the SetMode has to ensure that the setup is configured appropriately for the mode to be set. This should be facilitated by an embedded EnableController call, which is sensitive to the current Hardware PMI keyvariable values.

Vendors who provide the TuneDisplay section for sizing of the active display and the SetMonitorTimings section for manipulation of the timing PMI keyvariables should ensure that the SetMode section has the ability to set the run-time values for the timing PMI keyvariables. The easiest way to ensure this is by making the SetMode section use the SetMonitorTimings and TuneDisplay sections.

See Supported Modesand [EnableController] in this chapter for more information. VIDEOCFG.DLL Exported Functionsfor information on video configuration.

Here is a sample 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).

OS/2 Version Compatibility Considerations

The following table lists information that has been added to or changed in this documentation since the availability of OS/2 Warp, Version 3. When writing a device driver, you will want to take into consideration these particular changes, which may affect the downward compatibility of these items.

/--------------------------------------------------------------\
|Item Added or       |Date Item Added or  |Compatibility of    |
|Changed             |Changed             |Addition or Change  |
|--------------------+--------------------+--------------------|
|Virtual Video Device|March 1996          |OS/2 Warp, Version  |
|Driver in DBCS      |                    |3.1 and higher      |
|chapter             |                    |                    |
|--------------------+--------------------+--------------------|
|DSPINSTL Script     |November 1995       |OS/2 Warp, Version 3|
|                    |                    |and higher          |
|--------------------+--------------------+--------------------|
|Checklist for       |November 1995       |OS/2 Warp, Version 3|
|Palette Management  |                    |and higher          |
|Support             |                    |                    |
|--------------------+--------------------+--------------------|
|Protect-Mode        |April 1995          |OS/2 Warp, Version 3|
|Interface (entire   |                    |and higher          |
|PMI architecture)   |                    |                    |
|--------------------+--------------------+--------------------|
|Protect-Mode        |September 1994      |OS/2, Version 2.1   |
|Interface           |Revised November    |                    |
|(architecture for   |1995                |                    |
|the .PMI file, a    |                    |                    |
|subset of PMI)      |                    |                    |
|--------------------+--------------------+--------------------|
|VIDEOPMI.DLL        |April 1995 Revised  |OS/2 Warp, Version 3|
|Information         |November 1995       |and higher          |
|--------------------+--------------------+--------------------|
|VIDEOPMI.DLL        |April 1995          |OS/2 Warp, Version 3|
|Exported Functions, |Reformatted as APIs |and higher          |
|descriptions in     |November 1995 and 2 |                    |
|Chapter 16          |new APIs added      |                    |
\--------------------------------------------------------------/

Data Types

A description of each data type follows.

ADAPTERINFO

The ADAPTERINFO data structure receives information for the current video adapter.

typedef struct _ADAPTERINFO {
  ULONG      cb;                           /*  Length of the structure. */
  ULONG      ulAdapterID;                  /*  Specifies the adapter by ID. */
  CHAR       szOEMString[MAX_OEM_STRING];  /*  Contains adapter information. */
  CHAR       szDACString[MAX_DAC_STRING];  /*  Contains DAC information. */
  CHAR       szRevision[MAX_VERSION];      /*  Contains version information. */
  ULONG      ulTotalMemory;                /*  Total video memory. */
  ULONG      ulMMIOBaseAddress;            /*  Base address for memory-mapped I/O registers. */
  ULONG      ulPIOBaseAddress;             /*  Base address for I/O ports. */
  BYTE       bBusType;                     /*  Type of bus (PCI, VLB, and so on.) */
  BYTE       bEndian;                      /*  Big Endian or little Endian. */
  USHORT     usDeviceBusID;                /*  Reserved. */
  USHORT     usVendorBusID;                /*  Reserved. */
  USHORT     usSlotID;                     /*  Reserved. */
} ADAPTERINFO;

typedef   ADAPTERINFO   * FAR   * PADAPTERINFO ; 

ADAPTERINFO Field - cb

cb(ULONG) Length of the structure.

ADAPTERINFO Field - ulAdapterID

ulAdapterID(ULONG) Specifies the adapter by ID.

ADAPTERINFO Field - szOEMString[MAX_OEM_STRING]

szOEMString[MAX_OEM_STRING](CHAR) Contains adapter information.

Valid value is as follows:

MAX_OEM_STRING 128

ADAPTERINFO Field - szDACString[MAX_DAC_STRING]

szDACString[MAX_DAC_STRING](CHAR) Contains DAC information.

Valid value is as follows:

MAX_DAC_STRING 128

ADAPTERINFO Field - szRevision[MAX_VERSION]

szRevision[MAX_VERSION](CHAR) Contains version information.

Valid value is as follows:

MAX_VERSION 128

ADAPTERINFO Field - ulTotalMemory

ulTotalMemory(ULONG) Total video memory.

ADAPTERINFO Field - ulMMIOBaseAddress

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

ADAPTERINFO Field - ulPIOBaseAddress

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

ADAPTERINFO Field - bBusType

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

The valid values for this flag are as follows:

ISA_BUS 0

VLB_BUS 1

PCI_BUS 2

EISA_BUS 3

PCMCIA_BUS 4

MCA_BUS 5

ADAPTERINFO Field - bEndian

bEndian(BYTE) Big Endian or little Endian.

LITTLE_ENDIAN 0

BIG_ENDIAN 1

ADAPTERINFO Field - usDeviceBusID

usDeviceBusID(USHORT) Reserved.

ADAPTERINFO Field - usVendorBusID

usVendorBusID(USHORT) Reserved.

ADAPTERINFO Field - usSlotID

usSlotID(USHORT) Reserved.

BANKDATA

The BANKDATA data structure contains the current mode ID and the bank number.

typedef struct _BANKDATA {
  MODEID     miBank;  /*  ID of the current mode. */
  ULONG      ulBank;  /*  Current bank number. */
} BANKDATA;

typedef   BANKDATA   * FAR   * PBANKDATA ; 

BANKDATA Field - miBank

miBank(MODEID) ID of the current mode.

BANKDATA Field - ulBank

ulBank(ULONG) Current bank number.

CLUTDATA

The CLUTDATA data structure receives information for the number of RGBarray entries.

typedef struct _CLUTDATA {
  ULONG       ulRGBCount;  /*  Number of aRGB entries that follow. */
  ULONG       ulRGBStart;  /*  Start index for RGB triplets. */
  SVGARGB     aRGB[1];     /*  Start of SVGARGB; one entry is allocated. */
} CLUTDATA;

typedef   CLUTDATA   * FAR   * PCLUTDATA ; 

CLUTDATA Field - ulRGBCount

ulRGBCount(ULONG) Number of aRGB entries that follow.

CLUTDATA Field - ulRGBStart

ulRGBStart(ULONG) Start index for RGBtriplets.

CLUTDATA Field - aRGB[1]

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

DRIVERCAPS

Information structure used for GreEscape DEVESC_QUERYDRIVERCAPSLISTand GreEscape DEVESC_QUERYDRIVERCAPSfunctions.

typedef struct _DRIVERCAPS {
  ULONG     ulCb;                    /*  Length of the source structure in bytes. */
  CHAR      szCapsDesc[256];         /*  Capability description. */
  CHAR      szHelpFileName[256];     /*  Help file name. */
  ULONG     ulHelpId;                /*  Help resource id. */
  ULONG     ulCapsType;              /*  Defines the returned data type. */
  ULONG     ulValueMemberSize;       /*  Size of each member. */
  ULONG     ulNumValueMember;        /*  Number of members if aggregate. */
  PVOID     pValueList;              /*  Pointer to storage for the members data. */
  PVOID     pCurrentValue;           /*  Pointer to the current selected value descriptions. */
  PVOID     pDefaultValue;           /*  Pointer to the default (reset) value information. */
  BOOL      bDefaultValueSupported;  /*  Return TRUE if driver supports default. */
  BOOL      bStaticCaps;             /*  Return TRUE if need to reboot for the new capability. */
} DRIVERCAPS;

typedef   DRIVERCAPS   * PDRIVERCAPS ; 

DRIVERCAPS Field - ulCb

ulCb(ULONG) Length of the source structure in bytes.

DRIVERCAPS Field - szCapsDesc[256]

szCapsDesc[256](CHAR) Capability description.

DRIVERCAPS Field - szHelpFileName[256]

szHelpFileName[256](CHAR) Help file name.

DRIVERCAPS Field - ulHelpId

ulHelpId(ULONG) Help resource id.

DRIVERCAPS Field - ulCapsType

ulCapsType(ULONG) Defines the returned data type.

This field defines the datatype returned in pValueList, pCurrentValue, and pDefaultValue.

There are three data types currently supported, specified by the ulCapsType field: boolean, aggregate of int values, and aggregate of strings. These data types can be defined as follows:

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.

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.

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.

MONITORINFO

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

typedef struct _MONITORINFO {
  CHAR                szMonitor[MAX_MONITOR_LEN];          /*  Contains monitor information. */
  MONITORMODEINFO     MonitorModeInfo[MAX_MONITOR_MODES];  /*  Contains information about the monitor mode. */
} MONITORINFO;

typedef   MONITORINFO   * FAR   * PMONITORINFO ; 

MONITORINFO Field - szMonitor[MAX_MONITOR_LEN]

szMonitor[MAX_MONITOR_LEN](CHAR) Contains monitor information.

MONITORINFO Field - MonitorModeInfo[MAX_MONITOR_MODES]

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

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.

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.

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.

VIDEO_ADAPTER

The VIDEO_ADAPTER data structure receives information for the desktop mode.

typedef struct _VIDEO_ADAPTER {
  HVIDEO            hvideo;    /*  The handle for this adapter. */
  ADAPTERINFO       Adapter;   /*  Hardware information for this adapter. */
  VIDEOMODEINFO     ModeInfo;  /*  Information about the current video mode. */
} VIDEO_ADAPTER;

typedef   VIDEO _ ADAPTER   * FAR   * PVIDEO _ ADAPTER ; 

VIDEO_ADAPTER Field - hvideo

hvideo(HVIDEO) The handle for this adapter.

VIDEO_ADAPTER Field - Adapter

Adapter(ADAPTERINFO) Hardware information for this adapter.

VIDEO_ADAPTER Field - ModeInfo

ModeInfo(VIDEOMODEINFO) Information about the current video mode.

VIDEOMODEINFO

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

Note:The cband ulColorsfields are new to VIDEDOMODEINFO. The color depth field (ulColors) was introduced to differentiate between pixel and color depth.

typedef struct _VIDEOMODEINFO {
  ULONG      cb;                  /*  Size of the structure. */
  MODEID     miModeId;            /*  Used to make a SetMode request. */
  USHORT     usType;              /*  Flag indicating mode type. */
  USHORT     usInt10ModeSet;      /*  Interrupt 10 mode. */
  USHORT     usXResolution;       /*  Horizontal pixels. */
  USHORT     usYResolution;       /*  Vertical scanlines. */
  ULONG      ulBufferAddress;     /*  Physical address of VRAM. */
  ULONG      ulApertureSize;      /*  VRAM aperture. */
  ULONG      ulColors;            /*  Color depth. */
  BYTE       bBitsPerPixel;       /*  Pixel depth. */
  BYTE       bBitPlanes;          /*  Number of planes. */
  BYTE       bXCharSize;          /*  Font width. */
  BYTE       bYCharSize;          /*  Font height. */
  USHORT     usBytesPerScanLine;  /*  Number of bytes per scan line. */
  USHORT     usTextRows;          /*  Number of text rows. */
  ULONG      ulPageLength;        /*  Number of bytes to save a plane. */
  ULONG      ulSavesize;          /*  Total bytes of VRAM to save. */
  BYTE       bVrtRefresh;         /*  Vertical refresh rate. */
  BYTE       bHrtRefresh;         /*  Horizontal refresh rate. */
  BYTE       bVrtPolPos;          /*  Vertical polarity. */
  BYTE       bHrtPolPos;          /*  Horizontal polarity. */
  USHORT     usScrnTop;           /*  Vertical blanking away from the top, in line counts. */
  USHORT     usScrnBottom;        /*  Vertical blanking away from the bottom, in line counts. */
  USHORT     usScrnLeft;          /*  Horizontal blanking away from the left, in pixel counts. */
  USHORT     usScrnRight;         /*  Horizontal blanking away from the right, in pixel counts. */
  CHAR       szColorFormat[8];    /*  Color format string for true color or high-color modes. */
  CHAR       szColorWeight[8];    /*  Color weight string for true color or high-color modes. */
} VIDEOMODEINFO;

typedef   VIDEOMODEINFO   * FAR   * PVIDEOMODEINFO ; 

VIDEOMODEINFO Field - cb

cb(ULONG) Size of the structure.

VIDEOMODEINFO Field - miModeId

miModeId(MODEID) Used to make a SetMode request.

VIDEOMODEINFO Field - usType

usType(USHORT) Flag indicating mode type.

The following values are valid for this flag:

MODE_FLAG_NOT_MONO 0x0001; Mono-compatible

MODE_FLAG_GRAPHICS 0x0002; Text mode, Graphics

MODE_FLAG_NO_CLR_BRST 0x0004; Disable Color burst

MODE_FLAG_NATIVE 0x0008; Native (advanced function) mode

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

NOT_PLASMA 0x0020; will not work on plasma display

MODE_FLAG_VGA_ENTRY 0x0040; VGA mode, needs clean up

VIDEOMODEINFO Field - usInt10ModeSet

usInt10ModeSet(USHORT) Interrupt 10 mode.

VIDEOMODEINFO Field - usXResolution

usXResolution(USHORT) Horizontal pixels.

VIDEOMODEINFO Field - usYResolution

usYResolution(USHORT) Vertical scanlines.

VIDEOMODEINFO Field - ulBufferAddress

ulBufferAddress(ULONG) Physical address of VRAM.

VIDEOMODEINFO Field - ulApertureSize

ulApertureSize(ULONG) VRAM aperture.

VIDEOMODEINFO Field - ulColors

ulColors(ULONG) Color depth.

VIDEOMODEINFO Field - bBitsPerPixel

bBitsPerPixel(BYTE) Pixel depth.

VIDEOMODEINFO Field - bBitPlanes

bBitPlanes(BYTE) Number of planes.

VIDEOMODEINFO Field - bXCharSize

bXCharSize(BYTE) Font width.

VIDEOMODEINFO Field - bYCharSize

bYCharSize(BYTE) Font height.

VIDEOMODEINFO Field - usBytesPerScanLine

usBytesPerScanLine(USHORT) Number of bytes per scan line.

VIDEOMODEINFO Field - usTextRows

usTextRows(USHORT) Number of text rows.

VIDEOMODEINFO Field - ulPageLength

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

VIDEOMODEINFO Field - ulSavesize

ulSavesize(ULONG) Total bytes of VRAM to save.

VIDEOMODEINFO Field - bVrtRefresh

bVrtRefresh(BYTE) Vertical refresh rate.

VIDEOMODEINFO Field - bHrtRefresh

bHrtRefresh(BYTE) Horizontal refresh rate.

VIDEOMODEINFO Field - bVrtPolPos

bVrtPolPos(BYTE) Vertical polarity.

VIDEOMODEINFO Field - bHrtPolPos

bHrtPolPos(BYTE) Horizontal polarity.

VIDEOMODEINFO Field - usScrnTop

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

VIDEOMODEINFO Field - usScrnBottom

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

VIDEOMODEINFO Field - usScrnLeft

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

VIDEOMODEINFO Field - usScrnRight

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

VIDEOMODEINFO Field - szColorFormat[8]

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

VIDEOMODEINFO Field - szColorWeight[8]

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

VIDEOSTATE

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

typedef struct _VIDEOSTATE {
  ULONG         fStateFlags;     /*  Flag indicating what to save. */
  MODEID        miState;         /*  Contains the mode ID for the mode to be saved. */
  PVOID         pModeData;       /*  Pointer to set mode command sequence. */
  ULONG         ulVRAMSaveSize;  /*  Number of bytes per page to save. */
  PVRAMDATA     pVRAM;           /*  Pointer to video memory. */
  PCLUTDATA     pCLUT;           /*  Pointer to palette data. */
  PFONTDATA     pFONT;           /*  Pointer to font data. */
} VIDEOSTATE;

typedef   VIDEOSTATE   * FAR   * PVIDEOSTATE ; 

VIDEOSTATE Field - fStateFlags

fStateFlags(ULONG) Flag indicating what to save.

STATEFLAG_REGISTERS 0x0001

STATEFLAG_CLUT 0x0002

STATEFLAG_VRAM 0x0004

STATEFLAG_FONT 0x0008

VIDEOSTATE Field - miState

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

VIDEOSTATE Field - pModeData

pModeData(PVOID) Pointer to set mode command sequence.

VIDEOSTATE Field - ulVRAMSaveSize

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

VIDEOSTATE Field - pVRAM

pVRAM(PVRAMDATA) Pointer to video memory.

VIDEOSTATE Field - pCLUT

pCLUT(PCLUTDATA) Pointer to palette data.

VIDEOSTATE Field - pFONT

pFONT(PFONTDATA) Pointer to font data.

GRE Function Tests (By Function Name)

Additional information can be found in Display Test Tool. See also GRE Function Tests (By Test-Case Name).

/---------------------------------------------------------------------------------------------\
|GRE Function                     |Test Group    |Test-Case Name                 |DLL Name    |
|---------------------------------+--------------+-------------------------------+------------|
|GreAccumulateBounds              |GRE Bounds    |GreAccumulateBoundsRc          |GREBNDS.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreBitblt                        |GRE BitMaps   |GreBitPre2                     |GREBTMP.DLL |
|                                 |              |GreBitBltExh                   |            |
|                                 |              |GreBitbltRc                    |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreCharString                    |GRE Text      |GreTextApp1                    |GRETXTST.DLL|
|                                 |              |GreCharStringExh               |            |
|                                 |              |GreCharStringRc                |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreCharStringPos                 |GRE Text      |GreTextApp2                    |GRETXTST.DLL|
|                                 |              |GreCharStringPosExh            |            |
|                                 |              |GreCharStringPosRc             |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreCloseDC                       |GreDevContext |GreOpenAndCloseDCExh           |GREDVCON.DLL|
|                                 |              |GreCloseDCRc                   |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreCopyClipRegion                |GreClip       |GreClipPre                     |GRECLIP.DLL |
|                                 |              |GreCopyClipRegionExh           |            |
|                                 |              |GreCopyClipRegionRc            |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreCopyDCLoadData                |GreBitMaps2   |GreCopyDCLoadDataExh           |GREBIT2.DLL |
|                                 |              |GreCopyDCLoadDataRc            |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreCreateBitmap                  |GreBitMaps2   |GreBitApp1                     |GREBIT2.DLL |
|                                 |              |GreBitApp2                     |            |
|                                 |              |GreBitApp3                     |            |
|                                 |              |GreCreateBitmapRc              |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreCreateLogColorTable           |GRE Color     |GreColorApp                    |GRECOLR.DLL |
|                                 |              |GreCreateLogColorTableRc       |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeath                         |GreMDev       |GreDeathRc                     |GREMDEV.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeleteBitmap                  |GreBitMaps2   |GreBitApp1                     |GREBIT2.DLL |
|                                 |              |GreBitApp2                     |            |
|                                 |              |GreBitApp3                     |            |
|                                 |              |GreDeleteBitmapRc              |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeleteSetId                   |GreBitMaps2   |GreBitApp1                     |GREBIT2.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceCreateBitmap            |GRE BitMaps   |GreBitPre2                     |GREBTMP.DLL |
|                                 |              |GreDeviceCreateBitmapRc        |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceDeleteBitmap            |GRE BitMaps   |GreBitPre2                     |GREBTMP.DLL |
|                                 |              |GreDeviceDeleteBitmapRc        |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceGetAttributes           |GRE Attr      |GreDeviceGetAttributesRC       |GREATTR.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceInvalidateVisRegion     |GreMDev       |GreDeviceInvalidateVisRegionExh|GREMDEV.DLL |
|                                 |              |GreDeviceInvalidateVisRegionRc |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceQueryFontAttributes     |GRE Text      |GreDeviceQueryFontAttributesExh|GRETXTST.DLL|
|                                 |              |GreDeviceQueryFontAttributesRc |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceQueryFonts              |GRE Text      |GreDeviceQueryFontsExh         |GRETXTST.DLL|
|                                 |              |GreDeviceQueryFontsRc          |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceSelectBitmap            |GRE BitMaps   |GreBitPre2                     |GREBTMP.DLL |
|                                 |              |GreDeviceSelectBitmapRc        |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceSetAVIOFont             |GreMDev       |GreDeviceSetAVIOFontRc         |GREMDEV.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceSetAttributes           |GRE Attr      |GreDeviceSetGetAttrExh         |GREATTR.DLL |
|                                 |              |GreSetLineAttrExh              |            |
|                                 |              |GreDeviceSetAttributesRC       |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceSetCursor               |GreBitMaps2   |GreDeviceSetCursorRc           |GREBIT2.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceSetDCOrigin             |GreMDev       |GreDeviceSetDCOriginExh        |GREMDEV.DLL |
|                                 |              |GreDeviceSetDCOriginRc         |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDeviceSetGlobalAttribute      |GRE Attr      |GreDeviceSetGlobalAttributesExh|GREATTR.DLL |
|                                 |              |GreDeviceSetGlobalAttributesRC |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDisjointLines                 |GreGen2       |GreDisjointLinesPre            |GREGEN2.DLL |
|                                 |              |GreDisjointLinesExh            |            |
|                                 |              |GreDisjointLinesRc             |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDrawBorder                    |GRE BitMaps   |GreDrawBorderExh               |GREBTMP.DLL |
|                                 |              |GreDrawBorderRc                |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreDrawLinesInPath               |GRE Line      |GreDrawLinesInPathExh          |GRELINE.DLL |
|                                 |              |GreDrawLinesInPathRC           |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreErasePS                       |GRE General   |GreErasePSExh                  |GREGENFC.DLL|
|                                 |              |GreErasePSRC                   |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreEscape DEVESC_ABORTDOC        |GRE Escape    |GreAbortDocRc                  |GREESC.DLL  |
|GreEscape DEVESC_DRAFTMODE       |              |GreDraftModeRc                 |            |
|GreEscape DEVESC_ENDDOC          |              |GreEndDocRc                    |            |
|GreEscape DEVESC_FLUSHOUTPUT     |              |GreFlushOutputRc               |            |
|GreEscape DEVESC_GETSCALINGFACTOR|              |GreGetScalingFactorRc          |            |
|GreEscape DEVESC_NEWFRAME        |              |GreNewFrameRc                  |            |
|GreEscape DEVESC_NEXTBAND        |              |GreNextBandRc                  |            |
|GreEscape DEVESC_QUERYESCSUPPORT |              |GreEscapeApp                   |            |
|GreEscape DEVESC_QUERYESCSUPPORT |              |GreQueryEscapeSupportRc        |            |
|GreEscape DEVESC_RAWDATA         |              |GreRawDataRc                   |            |
|GreEscape DEVESC_STARTDOC        |              |GreStartDocRc                  |            |
|GreEscape DEVESC_STD_JOURNAL     |              |GreStdJournalRc                |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreExcludeClipRectangle          |GreClip       |GreClipPre                     |GRECLIP.DLL |
|                                 |              |GreExcludeClipRectangleExh     |            |
|                                 |              |GreExcludeClipRectangleRc      |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetAttributes                 |GreAttributes2|GreSetAndGetAttributesExh1     |GREATT2.DLL |
|                                 |              |GreSetAndGetAttributesExh2     |            |
|                                 |              |GreSetAndGetAttributesExh3     |            |
|                                 |              |GreSetAndGetAttributesExh4     |            |
|                                 |              |GreSetAndGetAttributesExh5     |            |
|                                 |              |GreSetAndGetAttributesExh6     |            |
|                                 |              |GreGetAttributesRc             |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetBitmapBits                 |GRE BitMaps   |GreGetBitmapBitsRc             |GREBTMP.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetBitmapDimension            |GreBitMaps2   |GreBitApp3                     |GREBIT2.DLL |
|                                 |              |GreGetBitmapDimensionRc        |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetBitmapParameters           |GreBitMaps2   |GreBitApp3                     |GREBIT2.DLL |
|                                 |              |GreGetBitmapParametersExh      |            |
|                                 |              |GreGetBitmapParametersRc       |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetBoundsData                 |GRE Bounds    |GreBoundsApp                   |GREBNDS.DLL |
|                                 |              |GreGetBoundsDataRc             |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetClipBox                    |GreClip       |GreClipPre                     |GRECLIP.DLL |
|                                 |              |GreGetClipBoxAndRctsAndVChkExh |            |
|                                 |              |GreGetClipBoxRc                |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetClipRects                  |GreClip       |GreGetClipBoxAndRctsAndVChkExh |GRECLIP.DLL |
|                                 |              |GreGetClipRectsRc              |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetCodePage                   |GRE Text      |GreGetCodePageExh              |GRETXTST.DLL|
|---------------------------------+--------------+-------------------------------+------------|
|GreGetCurrentPosition            |GRE Line      |GreGetCurrentPositionRC        |GRELINE.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetDCOrigin                   |GRE Attr      |GreGetDCOriginRC               |GREATTR.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetDefaultAttributes          |GreAttributes2|GreSetAndGetDefaultAttrsExh1   |GREATT2.DLL |
|                                 |              |GreSetAndGetDefaultAttrsExh2   |            |
|                                 |              |GreSetAndGetDefaultAttrsExh3   |            |
|                                 |              |GreSetAndGetDefaultAttrsExh4   |            |
|                                 |              |GreSetAndGetDefaultAttrsExh5   |            |
|                                 |              |GreSetAndGetDefaultAttrsExh6   |            |
|                                 |              |GreGetDefaultAttributesRc      |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetHandle                     |GreDevContext |GreSetAndGetHandleExh          |GREDVCON.DLL|
|                                 |              |GreGetHandleRc                 |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetLineOrigin                 |GRE Line      |GreLineOriginExh               |GRELINE.DLL |
|                                 |              |GreGetLineOriginRC             |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetPairKerningTable           |GRE Text      |GreGetPairKerningTableExh      |GRETXTST.DLL|
|                                 |              |GreGetPairKerningTableRc       |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetPel                        |GRE BitMaps   |GreGetPelRc                    |GREBTMP.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetPickWindow                 |GreGen2       |GreGetandSetPickWindowExh      |GREGEN2.DLL |
|                                 |              |GreGetPickWindowRc             |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetProcessControl             |GreDevContext |GreSetAndGetProcessControlExh  |GREDVCON.DLL|
|                                 |              |GreGetProcessControlRc         |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreGetStyleRatio                 |GRE Line      |GreGetStyleRatioRC             |GRELINE.DLL |
|---------------------------------+--------------+-------------------------------+------------|
|GreImageData                     |GRE BitMaps   |GreBitPre1                     |GREBTMP.DLL |
|                                 |              |GreImageDataExh                |            |
|                                 |              |GreImageDataRc                 |            |
|---------------------------------+--------------+-------------------------------+------------|
|GreInitializeAttributes          |GreAttributes2|GreInitializeAttributesExh1      | GREATT2 . DLL   | 
|                                      |                 | GreInitializeAttributesExh2      |               | 
|                                      |                 | GreInitializeAttributesRc        |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreIntersectClipRectangle          | GreClip         | GreClipPre                         | GRECLIP . DLL   | 
|                                      |                 | GreIntersectClipRectangleExh     |               | 
|                                      |                 | GreIntersectClipRectangleRc      |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreLockDevice                       | GRE   General     | GreLockDeviceExh                  | GREGENFC . DLL | 
|                                      |                 | GreLockDeviceRC                   |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreNotifyClipChange                 | GRE   Attr        | GreNotifyClipChangeExh           | GREATTR . DLL   | 
|                                      |                 | GreNotifyClipChangeRC            |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreNotifyTransformChange           | GRE   Attr        | GreNotifyTransformChangeExh      | GREATTR . DLL   | 
|                                      |                 | GreNotifyTransformChangeRC       |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreOffsetClipRegion                 | GreClip         | GreClipPre                         | GRECLIP . DLL   | 
|                                      |                 | GreOffsetClipRegionExh           |               | 
|                                      |                 | GreOffsetClipRegionRc            |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreOpenDC                            | GreDevContext   | GreOpenAndCloseDCExh              | GREDVCON . DLL | 
|                                      |                 | GreOpenDCRc                       |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GrePolyLine                          | GRE   Line        | GreLinePre                         | GRELINE . DLL   | 
|                                      |                 | GrePolyLineExh                    |               | 
|                                      |                 | GrePolyLineRC                     |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GrePolyMarker                       | GRE   Marker      | GreMarkerPre                      | GREMARK . DLL   | 
|                                      |                 | GreMarkerExh                      |               | 
|                                      |                 | GreMarkerRC                       |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GrePolyScanLine                     | GRE   Line        | GrePolyScanLineRC                 | GRELINE . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GrePolyShortLine                    | GRE   Line        | GrePolyShortLineRC                | GRELINE . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GrePtVisible                         | GreClip         | GreGetClipBoxAndRctsAndVChkExh   | GRECLIP . DLL   | 
|                                      |                 | GrePtVisibleRc                    |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryBitmapHandle                | GreBitMaps2     | GreBitApp1                         | GREBIT2 . DLL   | 
|                                      |                 | GreQueryBitmapHandleRc           |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryCharPositions               | GRE   Text        | GreTextApp1                       | GRETXTST . DLL | 
|                                      |                 | GreTextApp2                       |               | 
|                                      |                 | GreQueryCharPositionsExh         |               | 
|                                      |                 | GreQueryCharPositionsRc          |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryClipRegion                  | GreClip         | GreSelectAndQueryClipRegionExh   | GRECLIP . DLL   | 
|                                      |                 | GreQueryClipRegionRc              |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryColorData                   | GRE   Color       | GreQueryColorDataRc               | GRECOLR . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryColorIndex                  | GRE   Color       | GreQueryColorIndexRc              | GRECOLR . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryDevResource                 | GreDevContext   | GreQueryDevResourceExh           | GREDVCON . DLL | 
|                                      |                 | GreQueryDevResourceRc            |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryDeviceBitmaps               | GRE   Query       | GreQueryApp                       | GREQURY . DLL   | 
|                                      |                 | GreQueryDeviceBitmapsRc          |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryDeviceCaps                  | GRE   Query       | GreQueryApp                       | GREQURY . DLL   | 
|                                      |                 | GreQueryDeviceCapsRc              |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryEngineVersion               | GreDevContext   | GreQueryEngineVersionExh         | GREDVCON . DLL | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryHardcopyCaps                | GRE   Query       | GreQueryHardcopyCapsRc           | GREQURY . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryLogColorTable               | GRE   Color       | GreColorApp                       | GRECOLR . DLL   | 
|                                      |                 | GreQueryLogColorTableRc          |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryNearestColor                | GRE   Color       | GreQueryNearestColorRc           | GRECOLR . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryRGBColor                    | GRE   Color       | GreQueryRGBColorRc                | GRECOLR . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryRealColors                  | GRE   Color       | GreQueryRealColorsRc              | GRECOLR . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryTextBox                     | GRE   Text        | GreTextApp1                       | GRETXTST . DLL | 
|                                      |                 | GreTextApp2                       |               | 
|                                      |                 | GreQueryTextBoxExh                |               | 
|                                      |                 | GreQueryTextBoxRc                 |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreQueryWidthTable                  | GRE   Text        | GreQueryWidthTableExh            | GRETXTST . DLL | 
|                                      |                 | GreQueryWidthTableRc              |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreRealizeColorTable                | GRE   Color       | GreColorApp                       | GRECOLR . DLL   | 
|                                      |                 | GreRealizeColorTableRc           |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreRealizeFont                      | GRE   Text        | GreRealizeFontRc                  | GRETXTST . DLL | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreRectVisible                      | GreClip         | GreGetClipBoxAndRctsAndVChkExh   | GRECLIP . DLL   | 
|                                      |                 | GreRectVisibleRc                  |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreRegionSelectBitmap               | GreClip         | GreRegionSelectBitmapRc          | GRECLIP . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreResetBounds                      | GRE   Bounds      | GreBoundsApp                      | GREBNDS . DLL   | 
|                                      |                 | GreResetBoundsRc                  |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreRestoreRegion                    | GreClip         | GreRestoreRegionRc                | GRECLIP . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreRestoreScreenBits                | GreBitMaps2     | GreRestoreScreenBitsRc           | GREBIT2 . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreResurrection                     | GreMDev         | GreResurrectionRc                 | GREMDEV . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSaveRegion                       | GreClip         | GreSaveRegionRc                   | GRECLIP . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSaveScreenBits                   | GreBitMaps2     | GreSaveScreenBitsRc               | GREBIT2 . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSelectBitmap                     | GreBitMaps2     | GreBitApp2                         | GREBIT2 . DLL   | 
|                                      |                 | GreBitApp3                         |               | 
|                                      |                 | GreSelectBitmapExh                |               | 
|                                      |                 | GreSelectBitmapRc                 |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSelectClipRegion                 | GreClip         | GreClipPre                         | GRECLIP . DLL   | 
|                                      |                 | GreSelectClipRegionRc            |               | 
|                                      |                 | GreSelectAndQueryClipRegionExh   |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSelectPathRegion                 | GreClip         | GreClipPre                         | GRECLIP . DLL   | 
|                                      |                 | GreSelectPathRegionExh           |               | 
|                                      |                 | GreSelectPathRegionRc            |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetAttributes                    | GreAttributes2 | GreSetAndGetAttributesExh1       | GREATT2 . DLL   | 
|                                      |                 | GreSetAndGetAttributesExh2       |               | 
|                                      |                 | GreSetAndGetAttributesExh3       |               | 
|                                      |                 | GreSetAndGetAttributesExh4       |               | 
|                                      |                 | GreSetAndGetAttributesExh5       |               | 
|                                      |                 | GreSetAndGetAttributesExh6       |               | 
|                                      |                 | GreSetAttributesRc                |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetBitmapBits                    | GRE   BitMaps     | GreSetBitmapBitsExh               | GREBTMP . DLL   | 
|                                      |                 | GreSetBitmapBitsRc                |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetBitmapDimension               | GreBitMaps2     | GreBitApp3                         | GREBIT2 . DLL   | 
|                                      |                 | GreSetBitmapDimensionExh         |               | 
|                                      |                 | GreSetBitmapDimensionRc          |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetBitmapID                      | GreBitMaps2     | GreBitApp1                         | GREBIT2 . DLL   | 
|                                      |                 | GreSetBitmapIDExh                 |               | 
|                                      |                 | GreSetBitmapIdRc                  |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetCodePage                      | GRE   Text        | GreSetCodePageExh                 | GRETXTST . DLL | 
|                                      |                 | GreSetCodePageRc                  |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetColorCursor                   | GreGen2         | GreSetColorCursorExh              | GREGEN2 . DLL   | 
|                                      |                 | GreSetColorCursorRc               |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetCurrentPosition               | GRE   Line        | GreSetCurrentPositionRC          | GRELINE . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetCursor                         | GreAttributes2 | GreSetCursorRc                    | GREATT2 . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetDefaultAttributes            | GreAttributes2 | GreSetAndGetDefaultAttrsExh1     | GREATT2 . DLL   | 
|                                      |                 | GreSetAndGetDefaultAttrsExh2     |               | 
|                                      |                 | GreSetAndGetDefaultAttrsExh3     |               | 
|                                      |                 | GreSetAndGetDefaultAttrsExh4     |               | 
|                                      |                 | GreSetAndGetDefaultAttrsExh5     |               | 
|                                      |                 | GreSetAndGetDefaultAttrsExh6     |               | 
|                                      |                 | GreSetDefaultAttributesRc        |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetGlobalAttribute               | GreAttributes2 | GreSetGlobalAttributeExh         | GREATT2 . DLL   | 
|                                      |                 | GreSetGlobalAttributeRc          |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetHandle                         | GreDevContext   | GreSetAndGetHandleExh            | GREDVCON . DLL | 
|                                      |                 | GreSetHandleRc                    |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetLineOrigin                    | GRE   Line        | GreLineOriginExh                  | GRELINE . DLL   | 
|                                      |                 | GreSetLineOriginRC                |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetPel                            | GRE   BitMaps     | GreBitApp                          | GREBTMP . DLL   | 
|                                      |                 | GreSetPelExh                      |               | 
|                                      |                 | GreSetPelRc                       |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetPickWindow                    | GreGen2         | GreGetandSetPickWindowExh        | GREGEN2 . DLL   | 
|                                      |                 | GreSetPickWindowRc                |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetProcessControl                | GreDevContext   | GreSetAndGetProcessControlExh    | GREDVCON . DLL | 
|                                      |                 | GreSetProcessControlRc           |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetStyleRatio                    | GRE   Line        | GreSetStyleRatioRC                | GRELINE . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetXformRect                     | GreClip         | GreClipPre                         | GRECLIP . DLL   | 
|                                      |                 | GreSetXformRectExh                |               | 
|                                      |                 | GreSetXformRectRc                 |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreSetupDC                           | GRE   Attr        | GreSetupDCRC                      | GREATTR . DLL   | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreUnlockDevice                     | GRE   General     | GreUnlockDeviceExh                | GREGENFC . DLL | 
|                                      |                 | GreUnlockDeviceRC                 |               | 
| ---------- ---------- ---------- --- + ---------- ---- + ---------- ---------- ---------- - + ---------- -- | 
| GreUnrealizeColorTable              | GRE   Color       | GreColorApp                       | GRECOLR . DLL   | 
|                                      |                 | GreUnRealizeColorTableRc         |               | 
\ ---------- ---------- ---------- --- - ---------- ---- - ---------- ---------- ---------- - - ---------- -- / 

GRE Function Tests (By Test-Case Name)

Additional information can be found in Display Test Tool. See also GRE Function Tests (By Function Name).

/----------------------------------------------------------------------------------------\
|Test Case Name                 |Test Group    |DLL Name    |Gre Function                |
|-------------------------------+--------------+------------+----------------------------|
|GreAbortDocRc                  |GRE Escape    |GREESC.DLL  |GreEscape DEVESC_ABORTDOC   |
|-------------------------------+--------------+------------+----------------------------|
|GreAccumulateBoundsRc          |GRE Bounds    |GREBNDS.DLL |GreAccumulateBounds         |
|-------------------------------+--------------+------------+----------------------------|
|GreBitApp                      |GRE BitMaps   |GREBTMP.DLL |GreSetPel                   |
|-------------------------------+--------------+------------+----------------------------|
|GreBitApp1                     |GreBitMaps2   |GREBIT2.DLL |GreCreateBitmap             |
|                               |              |            |GreDeleteBitmap             |
|                               |              |            |GreDeleteSetId              |
|                               |              |            |GreQueryBitmapHandle        |
|                               |              |            |GreSetBitmapID              |
|-------------------------------+--------------+------------+----------------------------|
|GreBitApp2                     |GreBitMaps2   |GREBIT2.DLL |GreCreateBitmap             |
|                               |              |            |GreDeleteBitmap             |
|                               |              |            |GreSelectBitmap             |
|-------------------------------+--------------+------------+----------------------------|
|GreBitApp3                     |GreBitMaps2   |GREBIT2.DLL |GreCreateBitmap             |
|                               |              |            |GreDeleteBitmap             |
|                               |              |            |GreGetBitmapDimension       |
|                               |              |            |GreGetBitmapParameters      |
|                               |              |            |GreSelectBitmap             |
|                               |              |            |GreSetBitmapDimension       |
|-------------------------------+--------------+------------+----------------------------|
|GreBitBltExh                   |GRE BitMaps   |GREBTMP.DLL |GreBitblt                   |
|-------------------------------+--------------+------------+----------------------------|
|GreBitPre1                     |GRE BitMaps   |GREBTMP.DLL |GreImageData                |
|-------------------------------+--------------+------------+----------------------------|
|GreBitPre2                     |GRE BitMaps   |GREBTMP.DLL |GreBitblt                   |
|                               |              |            |GreDeviceCreateBitmap       |
|                               |              |            |GreDeviceDeleteBitmap       |
|                               |              |            |GreDeviceSelectBitmap       |
|-------------------------------+--------------+------------+----------------------------|
|GreBitbltRc                    |GRE BitMaps   |GREBTMP.DLL |GreBitblt                   |
|-------------------------------+--------------+------------+----------------------------|
|GreBoundsApp                   |GRE Bounds    |GREBNDS.DLL |GreGetBoundsData            |
|                               |              |            |GreResetBounds              |
|-------------------------------+--------------+------------+----------------------------|
|GreCharStringExh               |GRE Text      |GRETXTST.DLL|GreCharString               |
|-------------------------------+--------------+------------+----------------------------|
|GreCharStringPosExh            |GRE Text      |GRETXTST.DLL|GreCharStringPos            |
|-------------------------------+--------------+------------+----------------------------|
|GreCharStringPosRc             |GRE Text      |GRETXTST.DLL|GreCharStringPos            |
|-------------------------------+--------------+------------+----------------------------|
|GreCharStringRc                |GRE Text      |GRETXTST.DLL|GreCharString               |
|-------------------------------+--------------+------------+----------------------------|
|GreClipPre                     |GreClip       |GRECLIP.DLL |GreCopyClipRegion           |
|                               |              |            |GreExcludeClipRectangle     |
|                               |              |            |GreGetClipBox               |
|                               |              |            |GreIntersectClipRectangle   |
|                               |              |            |GreOffsetClipRegion         |
|                               |              |            |GreSelectClipRegion         |
|                               |              |            |GreSelectPathRegion         |
|                               |              |            |GreSetXformRect             |
|-------------------------------+--------------+------------+----------------------------|
|GreCloseDCRc                   |GreDevContext |GREDVCON.DLL|GreCloseDC                  |
|-------------------------------+--------------+------------+----------------------------|
|GreColorApp                    |GRE Color     |GRECOLR.DLL |GreCreateLogColorTable      |
|                               |              |            |GreQueryLogColorTable       |
|                               |              |            |GreRealizeColorTable        |
|                               |              |            |GreUnrealizeColorTable      |
|-------------------------------+--------------+------------+----------------------------|
|GreCopyClipRegionExh           |GreClip       |GRECLIP.DLL |GreCopyClipRegion           |
|-------------------------------+--------------+------------+----------------------------|
|GreCopyClipRegionRc            |GreClip       |GRECLIP.DLL |GreCopyClipRegion           |
|-------------------------------+--------------+------------+----------------------------|
|GreCopyDCLoadDataExh           |GreBitMaps2   |GREBIT2.DLL |GreCopyDCLoadData           |
|-------------------------------+--------------+------------+----------------------------|
|GreCopyDCLoadDataRc            |GreBitMaps2   |GREBIT2.DLL |GreCopyDCLoadData           |
|-------------------------------+--------------+------------+----------------------------|
|GreCreateBitmapRc              |GreBitMaps2   |GREBIT2.DLL |GreCreateBitmap             |
|-------------------------------+--------------+------------+----------------------------|
|GreCreateLogColorTableRc       |GRE Color     |GRECOLR.DLL |GreCreateLogColorTable      |
|-------------------------------+--------------+------------+----------------------------|
|GreDeathRc                     |GreMDev       |GREMDEV.DLL |GreDeath                    |
|-------------------------------+--------------+------------+----------------------------|
|GreDeleteBitmapRc              |GreBitMaps2   |GREBIT2.DLL |GreDeleteBitmap             |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceCreateBitmapRc        |GRE BitMaps   |GREBTMP.DLL |GreDeviceCreateBitmap       |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceDeleteBitmapRc        |GRE BitMaps   |GREBTMP.DLL |GreDeviceDeleteBitmap       |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceGetAttributesRC       |GRE Attr      |GREATTR.DLL |GreDeviceGetAttributes      |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceInvalidateVisRegionExh|GreMDev       |GREMDEV.DLL |GreDeviceInvalidateVisRegion|
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceInvalidateVisRegionRc |GreMDev       |GREMDEV.DLL |GreDeviceInvalidateVisRegion|
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceQueryFontAttributesExh|GRE Text      |GRETXTST.DLL|GreDeviceQueryFontAttributes|
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceQueryFontAttributesRc |GRE Text      |GRETXTST.DLL|GreDeviceQueryFontAttributes|
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceQueryFontsExh         |GRE Text      |GRETXTST.DLL|GreDeviceQueryFonts         |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceQueryFontsRc          |GRE Text      |GRETXTST.DLL|GreDeviceQueryFonts         |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSelectBitmapRc        |GRE BitMaps   |GREBTMP.DLL |GreDeviceSelectBitmap       |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSetAVIOFontRc         |GreMDev       |GREMDEV.DLL |GreDeviceSetAVIOFont        |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSetAttributesRC       |GRE Attr      |GREATTR.DLL |GreDeviceSetAttributes      |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSetCursorRc           |GreBitMaps2   |GREBIT2.DLL |GreDeviceSetCursor          |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSetDCOriginExh        |GreMDev       |GREMDEV.DLL |GreDeviceSetDCOrigin        |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSetDCOriginRc         |GreMDev       |GREMDEV.DLL |GreDeviceSetDCOrigin        |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSetGetAttrExh         |GRE Attr      |GREATTR.DLL |GreDeviceSetAttributes      |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSetGlobalAttributesExh|GRE Attr      |GREATTR.DLL |GreDeviceSetGlobalAttribute |
|-------------------------------+--------------+------------+----------------------------|
|GreDeviceSetGlobalAttributesRC |GRE Attr      |GREATTR.DLL |GreDeviceSetGlobalAttribute |
|-------------------------------+--------------+------------+----------------------------|
|GreDisjointLinesExh            |GreGen2       |GREGEN2.DLL |GreDisjointLines            |
|-------------------------------+--------------+------------+----------------------------|
|GreDisjointLinesPre            |GreGen2       |GREGEN2.DLL |GreDisjointLines            |
|-------------------------------+--------------+------------+----------------------------|
|GreDisjointLinesRc             |GreGen2       |GREGEN2.DLL |GreDisjointLines            |
|-------------------------------+--------------+------------+----------------------------|
|GreDraftModeRc                 |GRE Escape    |GREESC.DLL  |GreEscape DEVESC_DRAFTMODE  |
|-------------------------------+--------------+------------+----------------------------|
|GreDrawBorderExh               |GRE BitMaps   |GREBTMP.DLL |GreDrawBorder               |
|-------------------------------+--------------+------------+----------------------------|
|GreDrawBorderRc                |GRE BitMaps   |GREBTMP.DLL |GreDrawBorder               |
|-------------------------------+--------------+------------+----------------------------|
|GreDrawLinesInPathExh          |GRE Line      |GRELINE.DLL |GreDrawLinesInPath          |
|-------------------------------+--------------+------------+----------------------------|
|GreDrawLinesInPathRC           |GRE Line      |GRELINE.DLL |GreDrawLinesInPath          |
|-------------------------------+--------------+------------+----------------------------|
|GreEndDocRc                    |GRE Escape    |GREESC.DLL  |GreEscape DEVESC_ENDDOC     |
|-------------------------------+--------------+------------+----------------------------|
|GreErasePSExh                  |GRE General   |GREGENFC.DLL|GreErasePS                  |
|-------------------------------+--------------+------------+----------------------------|
|GreErasePSRC                   |GRE General   |GREGENFC.DLL|GreErasePS                  |
|-------------------------------+--------------+------------+----------------------------|
|GreEscapeApp                   |GRE Escape    |GREESC.DLL  |GreEscape                   |
|                               |              |            |DEVESC_QUERYESCSUPPORT      |
|-------------------------------+--------------+------------+----------------------------|
|GreExcludeClipRectangleExh     |GreClip       |GRECLIP.DLL |GreExcludeClipRectangle     |
|-------------------------------+--------------+------------+----------------------------|
|GreExcludeClipRectangleRc      |GreClip       |GRECLIP.DLL |GreExcludeClipRectangle     |
|-------------------------------+--------------+------------+----------------------------|
|GreFlushOutputRc               |GRE Escape    |GREESC.DLL  |GreEscape DEVESC_FLUSHOUTPUT|
|-------------------------------+--------------+------------+----------------------------|
|GreGetAttributesRc             |GreAttributes2|GREATT2.DLL |GreGetAttributes            |
|-------------------------------+--------------+------------+----------------------------|
|GreGetBitmapBitsRc             |GRE BitMaps   |GREBTMP.DLL |GreGetBitmapBits            |
|-------------------------------+--------------+------------+----------------------------|
|GreGetBitmapDimensionRc        |GreBitMaps2   |GREBIT2.DLL |GreGetBitmapDimension       |
|-------------------------------+--------------+------------+----------------------------|
|GreGetBitmapParametersExh      |GreBitMaps2   |GREBIT2.DLL |GreGetBitmapParameters      |
|-------------------------------+--------------+------------+----------------------------|
|GreGetBitmapParametersRc       |GreBitMaps2   |GREBIT2.DLL |GreGetBitmapParameters      |
|-------------------------------+--------------+------------+----------------------------|
|GreGetBoundsDataRc             |GRE Bounds    |GREBNDS.DLL |GreGetBoundsData            |
|-------------------------------+--------------+------------+----------------------------|
|GreGetClipBoxAndRctsAndVChkExh |GreClip       |GRECLIP.DLL |GreGetClipBox               |
|                               |              |            |GreGetClipRects             |
|                               |              |            |GrePtVisible                |
|                               |              |            |GreRectVisible              |
|-------------------------------+--------------+------------+----------------------------|
|GreGetClipBoxRc                |GreClip       |GRECLIP.DLL |GreGetClipBox               |
|-------------------------------+--------------+------------+----------------------------|
|GreGetClipRectsRc              |GreClip       |GRECLIP.DLL |GreGetClipRects             |
|-------------------------------+--------------+------------+----------------------------|
|GreGetCodePageExh              |GRE Text      |GRETXTST.DLL|GreGetCodePage              |
|-------------------------------+--------------+------------+----------------------------|
|GreGetCurrentPositionRC        |GRE Line      |GRELINE.DLL |GreGetCurrentPosition       |
|-------------------------------+--------------+------------+----------------------------|
|GreGetDCOriginRC               |GRE Attr      |GREATTR.DLL |GreGetDCOrigin              |
|-------------------------------+--------------+------------+----------------------------|
|GreGetDefaultAttributesRc      |GreAttributes2|GREATT2.DLL |GreGetDefaultAttributes     |
|-------------------------------+--------------+------------+----------------------------|
|GreGetHandleRc                 |GreDevContext |GREDVCON.DLL|GreGetHandle                |
|-------------------------------+--------------+------------+----------------------------|
|GreGetLineOriginRC             |GRE Line      |GRELINE.DLL |GreGetLineOrigin            |
|-------------------------------+--------------+------------+----------------------------|
|GreGetPairKerningTableExh      |GRE Text      |GRETXTST.DLL|GreGetPairKerningTable      |
|-------------------------------+--------------+------------+----------------------------|
|GreGetPairKerningTableRc       |GRE Text      |GRETXTST.DLL|GreGetPairKerningTable      |
|-------------------------------+--------------+------------+----------------------------|
|GreGetPelRc                    |GRE BitMaps   |GREBTMP.DLL |GreGetPel                   |
|-------------------------------+--------------+------------+----------------------------|
|GreGetPickWindowRc             |GreGen2       |GREGEN2.DLL |reGetPickWindow             |
|-------------------------------+--------------+------------+----------------------------|
|GreGetProcessControlRc         |GreDevContext |GREDVCON.DLL|GreGetProcessControl        |
|-------------------------------+--------------+------------+----------------------------|
|GreGetScalingFactorRc          |GRE Escape    |GREESC.DLL  |GreEscape                   |
|                               |              |            |DEVESC_GETSCALINGFACTOR     |
|-------------------------------+--------------+------------+----------------------------|
|GreGetStyleRatioRC             |GRE Line      |GRELINE.DLL |GreGetStyleRatio            |
|-------------------------------+--------------+------------+----------------------------|
|GreGetandSetPickWindowExh      |GreGen2       |GREGEN2.DLL |GreGetPickWindow            |
|                               |              |            |GreSetPickWindow            |
|-------------------------------+--------------+------------+----------------------------|
|GreImageDataExh                |GRE BitMaps   |GREBTMP.DLL |GreImageData                |
|-------------------------------+--------------+------------+----------------------------|
|GreImageDataRc                 |GRE BitMaps   |GREBTMP.DLL |GreImageData                |
|-------------------------------+--------------+------------+----------------------------|
|GreInitializeAttributesExh1    |GreAttributes2|GREATT2.DLL |GreInitializeAttributes     |
|-------------------------------+--------------+------------+----------------------------|
|GreInitializeAttributesExh2    |GreAttributes2|GREATT2.DLL |GreInitializeAttributes     |
|-------------------------------+--------------+------------+----------------------------|
|GreInitializeAttributesRc      |GreAttributes2|GREATT2.DLL |GreInitializeAttributes     |
|-------------------------------+--------------+------------+----------------------------|
|GreIntersectClipRectangleExh   |GreClip       |GRECLIP.DLL |GreIntersectClipRectangle   |
|-------------------------------+--------------+------------+----------------------------|
|GreIntersectClipRectangleRc    |GreClip       |GRECLIP.DLL |GreIntersectClipRectangle   |
|-------------------------------+--------------+------------+----------------------------|
|GreLineOriginExh               |GRE Line      |GRELINE.DLL |GreGetLineOrigin            |
|                               |              |            |GreSetLineOrigin            |
|-------------------------------+--------------+------------+----------------------------|
|GreLinePre                     |GRE Line      |GRELINE.DLL |GrePolyLine                 |
|-------------------------------+--------------+------------+----------------------------|
|GreLockDeviceExh               |GRE General   |GREGENFC.DLL|GreLockDevice               |
|-------------------------------+--------------+------------+----------------------------|
|GreLockDeviceRC                |GRE General   |GREGENFC.DLL|GreLockDevice               |
|-------------------------------+--------------+------------+----------------------------|
|GreMarkerExh                      | GRE   Marker      | GREMARK . DLL   | GrePolyMarker                  | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreMarkerPre                      | GRE   Marker      | GREMARK . DLL   | GrePolyMarker                  | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreMarkerRC                       | GRE   Marker      | GREMARK . DLL   | GrePolyMarker                  | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreNewFrameRc                     | GRE   Escape      | GREESC . DLL    | GreEscape   DEVESC _ NEWFRAME     | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreNextBandRc                     | GRE   Escape      | GREESC . DLL    | GreEscape   DEVESC _ NEXTBAND     | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreNotifyClipChangeExh           | GRE   Attr        | GREATTR . DLL   | GreNotifyClipChange           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreNotifyClipChangeRC            | GRE   Attr        | GREATTR . DLL   | GreNotifyClipChange           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreNotifyTransformChangeExh      | GRE   Attr        | GREATTR . DLL   | GreNotifyTransformChange      | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreNotifyTransformChangeRC       | GRE   Attr        | GREATTR . DLL   | GreNotifyTransformChange      | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreOffsetClipRegionExh           | GreClip         | GRECLIP . DLL   | GreOffsetClipRegion           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreOffsetClipRegionRc            | GreClip         | GRECLIP . DLL   | GreOffsetClipRegion           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreOpenAndCloseDCExh              | GreDevContext   | GREDVCON . DLL | GreCloseDC                     | 
|                                    |                 |               | GreOpenDC                      | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreOpenDCRc                       | GreDevContext   | GREDVCON . DLL | GreOpenDC                      | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GrePolyLineExh                    | GRE   Line        | GRELINE . DLL   | GrePolyLine                    | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GrePolyLineRC                     | GRE   Line        | GRELINE . DLL   | GrePolyLine                    | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GrePolyScanLineRC                 | GRE   Line        | GRELINE . DLL   | GrePolyScanLine                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GrePolyShortLineRC                | GRE   Line        | GRELINE . DLL   | GrePolyShortLine               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GrePtVisibleRc                    | GreClip         | GRECLIP . DLL   | GrePtVisible                   | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryApp                       | GRE   Query       | GREQURY . DLL   | GreQueryDeviceBitmaps         | 
|                                    |                 |               | GreQueryDeviceCaps            | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryBitmapHandleRc           | GreBitMaps2     | GREBIT2 . DLL   | GreQueryBitmapHandle          | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryCharPositionsExh         | GRE   Text        | GRETXTST . DLL | GreQueryCharPositions         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryCharPositionsRc          | GRE   Text        | GRETXTST . DLL | GreQueryCharPositions         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryClipRegionRc              | GreClip         | GRECLIP . DLL   | GreQueryClipRegion            | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryColorDataRc               | GRE   Color       | GRECOLR . DLL   | GreQueryColorData              | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryColorIndexRc              | GRE   Color       | GRECOLR . DLL   | GreQueryColorIndex            | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryDevResourceExh           | GreDevContext   | GREDVCON . DLL | GreQueryDevResource           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryDevResourceRc            | GreDevContext   | GREDVCON . DLL | GreQueryDevResource           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryDeviceBitmapsRc          | GRE   Query       | GREQURY . DLL   | GreQueryDeviceBitmaps         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryDeviceCapsRc              | GRE   Query       | GREQURY . DLL   | GreQueryDeviceCaps            | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryEngineVersionExh         | GreDevContext   | GREDVCON . DLL | GreQueryEngineVersion         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryEscapeSupportRc          | GRE   Escape      | GREESC . DLL    | GreEscape                      | 
|                                    |                 |               | DEVESC _ QUERYESCSUPPORT        | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryHardcopyCapsRc           | GRE   Query       | GREQURY . DLL   | GreQueryHardcopyCaps          | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryLogColorTableRc          | GRE   Color       | GRECOLR . DLL   | GreQueryLogColorTable         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryNearestColorRc           | GRE   Color       | GRECOLR . DLL   | GreQueryNearestColor          | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryRGBColorRc                | GRE   Color       | GRECOLR . DLL   | GreQueryRGBColor               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryRealColorsRc              | GRE   Color       | GRECOLR . DLL   | GreQueryRealColors            | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryTextBoxExh                | GRE   Text        | GRETXTST . DLL | GreQueryTextBox                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryTextBoxRc                 | GRE   Text        | GRETXTST . DLL | GreQueryTextBox                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryWidthTableExh            | GRE   Text        | GRETXTST . DLL | GreQueryWidthTable            | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreQueryWidthTableRc              | GRE   Text        | GRETXTST . DLL | GreQueryWidthTable            | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreRawDataRc                      | GRE   Escape      | GREESC . DLL    | GreEscape   DEVESC _ RAWDATA      | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreRealizeColorTableRc           | GRE   Color       | GRECOLR . DLL   | GreRealizeColorTable          | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreRealizeFontRc                  | GRE   Text        | GRETXTST . DLL | GreRealizeFont                 | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreRectVisibleRc                  | GreClip         | GRECLIP . DLL   | GreRectVisible                 | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreRegionSelectBitmapRc          | GreClip         | GRECLIP . DLL   | GreRegionSelectBitmap         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreResetBoundsRc                  | GRE   Bounds      | GREBNDS . DLL   | GreResetBounds                 | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreRestoreRegionRc                | GreClip         | GRECLIP . DLL   | GreRestoreRegion               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreRestoreScreenBitsRc           | GreBitMaps2     | GREBIT2 . DLL   | GreRestoreScreenBits          | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreResurrectionRc                 | GreMDev         | GREMDEV . DLL   | GreResurrection                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSaveRegionRc                   | GreClip         | GRECLIP . DLL   | GreSaveRegion                  | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSaveScreenBitsRc               | GreBitMaps2     | GREBIT2 . DLL   | GreSaveScreenBits              | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSelectAndQueryClipRegionExh   | GreClip         | GRECLIP . DLL   | GreQueryClipRegion            | 
|                                    |                 |               | GreSelectClipReqion           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSelectBitmapExh                | GreBitMaps2     | GREBIT2 . DLL   | GreSelectBitmap                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSelectBitmapRc                 | GreBitMaps2     | GREBIT2 . DLL   | GreSelectBitmap                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSelectClipRegionRc            | GreClip         | GRECLIP . DLL   | GreSelectClipRegion           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSelectPathRegionExh           | GreClip         | GRECLIP . DLL   | GreSelectPathRegion           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSelectPathRegionRc            | GreClip         | GRECLIP . DLL   | GreSelectPathRegion           | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetAttributesExh1       | GreAttributes2 | GREATT2 . DLL   | GreGetAttributes               | 
|                                    |                 |               | GreSetAttributes               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetAttributesExh2       | GreAttributes2 | GREATT2 . DLL   | GreGetAttributes               | 
|                                    |                 |               | GreSetAttributes               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetAttributesExh3       | GreAttributes2 | GREATT2 . DLL   | GreGetAttributes               | 
|                                    |                 |               | GreSetAttributes               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetAttributesExh4       | GreAttributes2 | GREATT2 . DLL   | GreGetAttributes               | 
|                                    |                 |               | GreSetAttributes               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetAttributesExh5       | GreAttributes2 | GREATT2 . DLL   | GreGetAttributes               | 
|                                    |                 |               | GreSetAttributes               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetAttributesExh6       | GreAttributes2 | GREATT2 . DLL   | GreGetAttributes               | 
|                                    |                 |               | GreSetAttributes               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetDefaultAttrsExh1     | GreAttributes2 | GREATT2 . DLL   | GreGetDefaultAttributes       | 
|                                    |                 |               | GreSetDefaultAttributes       | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetDefaultAttrsExh2     | GreAttributes2 | GREATT2 . DLL   | GreGetDefaultAttributes       | 
|                                    |                 |               | GreSetDefaultAttributes       | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetDefaultAttrsExh3     | GreAttributes2 | GREATT2 . DLL   | GreGetDefaultAttributes       | 
|                                    |                 |               | GreSetDefaultAttributes       | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetDefaultAttrsExh4     | GreAttributes2 | GREATT2 . DLL   | GreGetDefaultAttributes       | 
|                                    |                 |               | GreSetDefaultAttributes       | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetDefaultAttrsExh5     | GreAttributes2 | GREATT2 . DLL   | GreGetDefaultAttributes       | 
|                                    |                 |               | GreSetDefaultAttributes       | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetDefaultAttrsExh6     | GreAttributes2 | GREATT2 . DLL   | GreGetDefaultAttributes       | 
|                                    |                 |               | GreSetDefaultAttributes       | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetHandleExh            | GreDevContext   | GREDVCON . DLL | GreGetHandle                   | 
|                                    |                 |               | GreSetHandle                   | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAndGetProcessControlExh    | GreDevContext   | GREDVCON . DLL | GreGetProcessControl          | 
|                                    |                 |               | GreSetProcessControl          | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetAttributesRc                | GreAttributes2 | GREATT2 . DLL   | GreSetAttributes               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetBitmapBitsExh               | GRE   BitMaps     | GREBTMP . DLL   | GreSetBitmapBits               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetBitmapBitsRc                | GRE   BitMaps     | GREBTMP . DLL   | GreSetBitmapBits               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetBitmapDimensionExh         | GreBitMaps2     | GREBIT2 . DLL   | GreSetBitmapDimension         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetBitmapDimensionRc          | GreBitMaps2     | GREBIT2 . DLL   | GreSetBitmapDimension         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetBitmapIDExh                 | GreBitMaps2     | GREBIT2 . DLL   | GreSetBitmapID                 | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetBitmapIdRc                  | GreBitMaps2     | GREBIT2 . DLL   | GreSetBitmapID                 | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetCodePageExh                 | GRE   Text        | GRETXTST . DLL | GreSetCodePage                 | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetCodePageRc                  | GRE   Text        | GRETXTST . DLL | GreSetCodePage                 | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetColorCursorExh              | GreGen2         | GREGEN2 . DLL   | GreSetColorCursor              | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetColorCursorRc               | GreGen2         | GREGEN2 . DLL   | GreSetColorCursor              | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetCurrentPositionRC          | GRE   Line        | GRELINE . DLL   | GreSetCurrentPosition         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetCursorRc                    | GreAttributes2 | GREATT2 . DLL   | GreSetCursor                   | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetDefaultAttributesRc        | GreAttributes2 | GREATT2 . DLL   | GreSetDefaultAttributes       | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetGlobalAttributeExh         | GreAttributes2 | GREATT2 . DLL   | GreSetGlobalAttribute         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetGlobalAttributeRc          | GreAttributes2 | GREATT2 . DLL   | GreSetGlobalAttribute         | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetHandleRc                    | GreDevContext   | GREDVCON . DLL | GreSetHandle                   | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetLineAttrExh                 | GRE   Attr        | GREATTR . DLL   | GreDeviceSetAttributes        | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetLineOriginRC                | GRE   Line        | GRELINE . DLL   | GreSetLineOrigin               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetPelExh                      | GRE   BitMaps     | GREBTMP . DLL   | GreSetPel                      | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetPelRc                       | GRE   BitMaps     | GREBTMP . DLL   | GreSetPel                      | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetPickWindowRc                | GreGen2         | GREGEN2 . DLL   | GreSetPickWindow               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetProcessControlRc           | GreDevContext   | GREDVCON . DLL | GreSetProcessControl          | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetStyleRatioRC                | GRE   Line        | GRELINE . DLL   | GreSetStyleRatio               | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetXformRectExh                | GreClip         | GRECLIP . DLL   | GreSetXformRect                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetXformRectRc                 | GreClip         | GRECLIP . DLL   | GreSetXformRect                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreSetupDCRC                      | GRE   Attr        | GREATTR . DLL   | GreSetupDC                     | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreStartDocRc                     | GRE   Escape      | GREESC . DLL    | GreEscape   DEVESC _ STARTDOC     | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreStdJournalRc                   | GRE   Escape      | GREESC . DLL    | GreEscape   DEVESC _ STD _ JOURNAL | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreTextApp1                       | GRE   Text        | GRETXTST . DLL | GreCharString                  | 
|                                    |                 |               | GreQueryCharPositions         | 
|                                    |                 |               | GreQueryTextBox                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreTextApp2                       | GRE   Text        | GRETXTST . DLL | GreCharStringPos               | 
|                                    |                 |               | GreQueryCharPositions         | 
|                                    |                 |               | GreQueryTextBox                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreUnRealizeColorTableRc         | GRE   Color       | GRECOLR . DLL   | GreUnrealizeColorTable        | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreUnlockDeviceExh                | GRE   General     | GREGENFC . DLL | GreUnlockDevice                | 
| ---------- ---------- ---------- - + ---------- ---- + ---------- -- + ---------- ---------- -------- | 
| GreUnlockDeviceRC                 | GRE   General     | GREGENFC . DLL | GreUnlockDevice                | 
\ ---------- ---------- ---------- - - ---------- ---- - ---------- -- - ---------- ---------- -------- / 

Graphics Engine Functions

The following tables list and briefly describe the graphics engine functions: The first table shows the graphics engine attribute functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreDeviceGetAttributes      |Queries the attribute values      |
|                            |currently set in the device.      |
|----------------------------+----------------------------------|
|GreDeviceSetAttributes      |Sets attributes in the attribute  |
|                            |bundle specified by IBType.       |
|----------------------------+----------------------------------|
|GreDeviceSetGlobalAttribute |Sets the individual primitive     |
|                            |attributes to the specified values|
|                            |in the line, area, character,     |
|                            |image, and marker bundles.        |
|----------------------------+----------------------------------|
|GreGetPairKerningTable      |Stores the kerning pairs of the   |
|                            |current font to the buffer        |
|                            |addressed by pKernPairs.          |
\---------------------------------------------------------------/

This table shows the graphics engine AVIO functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreCharRect                 |Draws a rectangle of character    |
|                            |cells from the logical video      |
|                            |buffer (LVB) to the device        |
|                            |context.                          |
|----------------------------+----------------------------------|
|GreCharStr                  |Draws a string of character cells |
|                            |from the LVB to the device        |
|                            |context.                          |
|----------------------------+----------------------------------|
|GreDeviceSetAVIOFont        |Loads or deletes an image font    |
|                            |used by the AVIO presentation     |
|                            |space associated with the device  |
|                            |context.                          |
|----------------------------+----------------------------------|
|GreScrollRect               |Scrolls the contents of the LVB   |
|                            |through the device context.       |
|----------------------------+----------------------------------|
|GreUpdateCursor             |Updates the drawn alphanumeric    |
|                            |cursor to match the cursor state  |
|                            |information contained in the      |
|                            |presentation space.               |
\---------------------------------------------------------------/

This table shows the graphics engine bit-map functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreBitblt                   |Modifies bit-map data at a target |
|                            |rectangle in the current device   |
|                            |context.                          |
|----------------------------+----------------------------------|
|GreDeviceCreateBitmap       |Creates a bit map and obtains its |
|                            |handle.                           |
|----------------------------+----------------------------------|
|GreDeviceDeleteBitmap       |Destroys a bit map.               |
|----------------------------+----------------------------------|
|GreDeviceSelectBitmap       |Informs the device driver that a  |
|                            |new bit map is selected into the  |
|                            |device context.                   |
|----------------------------+----------------------------------|
|GreDrawBorder               |Draws an internal border in a     |
|                            |rectangular frame.                |
|----------------------------+----------------------------------|
|GreGetBitmapBits            |Transfers bit-map data from a bit |
|                            |map to application storage, or    |
|                            |fills in the RGB values in the    |
|                            |BITMAPINFO or BITMAPINFO2 data    |
|                            |structures and returns 0.         |
|----------------------------+----------------------------------|
|GreGetPel                   |Returns the color of a pel at a   |
|                            |specified position.               |
|----------------------------+----------------------------------|
|GreImageData                |Draws a single row of image data  |
|                            |with one bit per pel by using the |
|                            |current image foreground and      |
|                            |background color and mix          |
|                            |attributes.                       |
|----------------------------+----------------------------------|
|GreSetBitmapBits            |Transfers bit-map data from       |
|                            |application storage into the      |
|                            |specified bit map of a device     |
|                            |context.                          |
|----------------------------+----------------------------------|
|GreSetPel                   |Sets a pel to the current line    |
|                            |attribute, color, and mix.        |
\---------------------------------------------------------------/

This table shows the graphics engine color functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreCreateLogColorTable      |Defines the entries in the logical|
|                            |color table.                      |
|----------------------------+----------------------------------|
|GreQueryColorData           |Stores an array of information    |
|                            |about the currently available     |
|                            |logical color table and device    |
|                            |colors at the location addressed  |
|                            |by pArray.                        |
|----------------------------+----------------------------------|
|GreQueryColorIndex          |Returns the logical color index   |
|                            |that is closest to the specified  |
|                            |RGB color representation for the  |
|                            |device.                           |
|----------------------------+----------------------------------|
|GreQueryLogColorTable       |Stores an array of the current    |
|                            |logical color values at the       |
|                            |location addressed by pArray.     |
|----------------------------+----------------------------------|
|GreQueryNearestColor        |Returns the available color       |
|                            |nearest to the specified color on |
|                            |the currently associated device,  |
|                            |even if it is not available in the|
|                            |logical color table.              |
|----------------------------+----------------------------------|
|GreQueryRealColors          |Stores the RGB values of the      |
|                            |distinct colors available on the  |
|                            |currently associated device.      |
|----------------------------+----------------------------------|
|GreQueryRGBColor            |Returns the actual RGB color that |
|                            |results from the specified color  |
|                            |index for the specified device.   |
|----------------------------+----------------------------------|
|GreRealizeColorTable        |Causes the system to ensure that, |
|                            |for a realizable color table, the |
|                            |device physical color table is set|
|                            |to the closest possible match to  |
|                            |the logical color table.          |
|----------------------------+----------------------------------|
|GreUnrealizeColorTable      |Reverses GreRealizeColorTable by  |
|                            |causing the default physical color|
|                            |table for the device to be        |
|                            |reinstated.                       |
\---------------------------------------------------------------/

This table shows the graphics engine device functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreDrawBits                 |Draws a rectangle of bits.        |
\---------------------------------------------------------------/

This table shows the graphics engine escape functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreEscape DEVESC_ABORTDOC   |Aborts the current document.      |
|----------------------------+----------------------------------|
|GreEscape DEVESC_ACQUIREFB  |Reserves a video adapter by       |
|                            |acquiring the necessary PM driver |
|                            |resources.                        |
|----------------------------+----------------------------------|
|GreEscape DEVESC_DEAQUIREFB |Releases the PM driver resources. |
|----------------------------+----------------------------------|
|GreEscape DEVESC_EXTGET     |Called by EnDIVE users to copy an |
|                            |image from the screen to system   |
|                            |memory or to off-screen video     |
|                            |memory.                           |
|----------------------------+----------------------------------|
|GreEscape DEVESC_EXTPUT     |Called by EnDIVE users to copy an |
|                            |image to the screen.              |
|----------------------------+----------------------------------|
|GreEscape DEVESC_EXTQUERY   |Called by EnDIVE users to get     |
|                            |information describing            |
|                            |characteristics of the motion     |
|                            |video accelerator .                   | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreEscape   DEVESC _ GETAPERTURE | Returns   the   size   and   physical       | 
|                                | address   of   the   video   aperture .      | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreEscape   DEVESC _ HWREQUEST    | Called   by   EnDIVE   users   to   take      | 
|                                | advantage   of   enhanced   aquire        | 
|                                | functions .                            | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreEscape                      | Queries   whether   a   particular        | 
| DEVESC _ QUERYESCSUPPORT        | escape   code   is   implemented   by   the   | 
|                                | PM   driver .                            | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreEscape   DEVESC _ QUERYFB      | Called   by   EnDIVE   users   to   get       | 
|                                | information   describing   the          | 
|                                | characteristics   of   the   frame        | 
|                                | buffer .                               | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreEscape                      | Obtains   the   details   of   the   VIO      | 
| DEVESC _ QUERYVIOCELLSIZES      | cell   sizes   supported   by   the   PM      | 
|                                | driver .                               | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreEscape   DEVESC _ REGISTER     | Called   by   EnDIVE   users   to   register | 
|                                | and   unregister   use   with   the         | 
|                                | driver .                               | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreEscape   DEVESC _ SWITCHBANK   | Changes   which   bank   of   memory   is     | 
|                                | mapped   to   the   aperture .              | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreEscape   DEVESC _ VRAMALLOC    | Called   by   EnDIVE   users   to   allocate | 
|                                | off - screen   video   memory ,   into       | 
|                                | which   the   function   puts   images .     | 
\ ---------- ---------- -------- - ---------- ---------- ---------- ---- / 

This table shows the graphics engine line functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreDisjointLines            |Draws a sequence of disjoint      |
|                            |straight lines using the end-point|
|                            |pairs specified.                  |
|----------------------------+----------------------------------|
|GreDrawLinesInPath          |Draws one line or a sequence of   |
|                            |straight lines from the sequence  |
|                            |of structures linked by pLine.    |
|----------------------------+----------------------------------|
|GreGetCurrentPosition       |Takes the current (X,Y) position  |
|                            |in world coordinates from the     |
|                            |device context instance data      |
|                            |structure and stores it at the    |
|                            |location addressed by pptlPosition|
|                            |.                                 |
|----------------------------+----------------------------------|
|GrePolyLine                 |Draws one line or a sequence of   |
|                            |lines starting at the current     |
|                            |(X,Y) position.                   |
|----------------------------+----------------------------------|
|GrePolyScanline             |Fills an area between             |
|                            |polyshortline pairs by using the  |
|                            |current pattern attribute.        |
|----------------------------+----------------------------------|
|GrePolyShortLine            |Draws a series of short lines.    |
|----------------------------+----------------------------------|
|GreSetCurrentPosition       |Sets the current (x,y) position   |
|                            |and resets the line type sequence.|
\---------------------------------------------------------------/

This table shows the graphics engine marker functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GrePolyMarker               |Draws one marker or a sequence of |
|                            |markers.                          |
\---------------------------------------------------------------/

This table shows the graphics engine miscellaneous device functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreAccumulateBounds         |Merges bounds into the total      |
|                            |bounds held by the driver         |
|----------------------------+----------------------------------|
|GreDeviceQueryFontAttributes|Stores the metrics of the         |
|                            |currently selected font at the    |
|                            |location addressed by pfmMetrics. |
|----------------------------+----------------------------------|
|GreDeviceQueryFonts         |Returns the characteristics of    |
|                            |device fonts in an array of       |
|                            |FONTMETRICS structures, if the    |
|                            |QF_PUBLIC option flag is set.     |
|----------------------------+----------------------------------|
|GreErasePS                  |Resets the presentation space of  |
|                            |the device context to the         |
|                            |background color.                 |
|----------------------------+----------------------------------|
|GreGetBoundsData            |Stores the bounding rectangle of  |
|                            |previous drawing primitives at the|
|                            |address indicated by pBoundsData. |
|----------------------------+----------------------------------|
|GreGetCodePage              |Returns the current code page.    |
|----------------------------+----------------------------------|
|GreGetStyleRatio            |Stores the style ratio X-direction|
|                            |and Y-direction step values at the|
|                            |location addressed by pRatio.     |
|----------------------------+----------------------------------|
|GreLineOrigin               |Returns the current line style    |
|                            |from the device context instance  |
|                            |data, and stores the current      |
|                            |position to the address indicated |
|                            |by pptlXY.                        |
|----------------------------+----------------------------------|
|GreLockDevice               |Locks a device for use by a single|
|                            |thread.                           |
|----------------------------+----------------------------------|
|GreNotifyClipChange         |Called when there is any change to|
|                            |the device context region. Gives  |
|                            |the driver an opportunity to      |
|                            |optimize clipping by enumerating  |
|                            |the clip rectangles and caching   |
|                            |them when they change.            |
|----------------------------+----------------------------------|
|GreNotifyTransformChange    |Notifies the driver of a change in|
|                            |the transform from world          |
|                            |coordinates to device coordinates.|
|----------------------------+----------------------------------|
|GreRealizeFont              |Requests the driver to realize or |
|                            |delete a font.                    |
|----------------------------+----------------------------------|
|GreResetBounds              |Resets the bounds to their initial|
|                            |values.                           |
|----------------------------+----------------------------------|
|GreSetCodePage                 | Sets   the   current   code   page   for      | 
|                                | characters   written   with   the   base    | 
|                                | ( default )   font .                      | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreSetLineOrigin               | Sets   the   current   line   style   and     | 
|                                | current   position .                    | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreSetStyleRatio               | Sets   the   style   ratio   used   by   the    | 
|                                | driver ' s   line - drawing   algorithm   to | 
|                                | determine   which   pels   should   be   set | 
|                                | ON   for   a   sloping   line .               | 
| ---------- ---------- -------- + ---------- ---------- ---------- ---- | 
| GreUnlockDevice                | Permits   the   continuation   of   all     | 
|                                | pending   screen   input   or   output      | 
|                                | operations   blocked   by                | 
|                                | GreLockDevice .                       | 
\ ---------- ---------- -------- - ---------- ---------- ---------- ---- / 

This table shows the graphics engine miscellaneous screen functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreDeath                    |Informs the driver that the entire|
|                            |screen is required by another     |
|                            |screen group (that is, an         |
|                            |application that is not running   |
|                            |under Presentation Manager).      |
|----------------------------+----------------------------------|
|GreDeviceInvalidateVisRegion|Notifies the driver that the      |
|                            |visible region and device context |
|                            |region of one or more device      |
|                            |contexts has changed and that the |
|                            |affected device contexts must     |
|                            |revalidate their visible regions  |
|                            |before drawing in them.           |
|----------------------------+----------------------------------|
|GreDeviceSetCursor          |Sets the cursor bit map that      |
|                            |defines the cursor shape.         |
|----------------------------+----------------------------------|
|GreDeviceSetDCOrigin        |Sets the origin of the device     |
|                            |context.                          |
|----------------------------+----------------------------------|
|GreGetDCOrigin              |Queries the origin of the device  |
|                            |context that defines the          |
|                            |bottom-left drawing origin for a  |
|                            |display device or banded hardcopy |
|                            |device.                           |
|----------------------------+----------------------------------|
|GreGetPickWindow            |Stores a RECTL structure at the   |
|                            |location addressed by pPick,      |
|                            |giving the position and size of   |
|                            |the pick window in page-coordinate|
|                            |space.                            |
|----------------------------+----------------------------------|
|GreRestoreScreenBits        |Restores a rectangle of bits to a |
|                            |screen rectangle; also can free   |
|                            |the handle of the saved bits.     |
|----------------------------+----------------------------------|
|GreResurrection             |Reverses the condition set by     |
|                            |GreDeath and restores the screen  |
|                            |to the Presentation Manager       |
|                            |interface.                        |
|----------------------------+----------------------------------|
|GreSaveScreenBits           |Saves a rectangle of screen bits. |
|----------------------------+----------------------------------|
|GreSetColorCursor           |Sets the bit maps that define a   |
|                            |color cursor or pointer.          |
|----------------------------+----------------------------------|
|GreSetPickWindow            |Sets the position and size of the |
|                            |pick window in page-coordinate    |
|                            |space for subsequent correlation  |
|                            |operations.                       |
\---------------------------------------------------------------/

This table shows the graphics engine query functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreQueryDeviceBitmaps       |Stores a list of bit-map formats  |
|                            |supported by the device in the    |
|                            |array addressed by paOutData.     |
|----------------------------+----------------------------------|
|GreQueryDeviceCaps          |Supports GreDevQueryCaps at the   |
|                            |API.  Returns the required        |
|                            |information in the device         |
|                            |capabilities buffer addressed by  |
|                            |paOutData.                        |
|----------------------------+----------------------------------|
|GreQueryDevResource         |Indicates whether a specified     |
|                            |resource is available.            |
|----------------------------+----------------------------------|
|GreQueryHardcopyCaps        |Stores information about the      |
|                            |hardcopy capabilities of the      |
|                            |device in the buffer addressed by |
|                            |pInfo.                            |
\---------------------------------------------------------------/

This table shows the graphics engine string functions.

/---------------------------------------------------------------\
|Function Name               |Description                       |
|----------------------------+----------------------------------|
|GreCharString               |Draws a character string starting |
|                            |at the current (x,y) position.    |
|----------------------------+----------------------------------|
|GreCharStringPos            |Draws a character string from     |
|                            |either the current (x,y) position |
|                            |or a specified position.          |
\---------------------------------------------------------------/

DTT Script File Command Summary

CHOOSE Select the next test case to be executed. The operand is the case- sensitive name of the test case to be selected.

DCTYPE Specify the device context for subsequent test cases.

The operand is one of the following:

OD_QUEUED Output is to be queued. (This is the default.)

OD_DIRECT Output is not to be queued.

OD_INFO The device context is to be used only to retrieve information.

OD_METAFILE The device context will be used to write a metafile.

OD_METAFILE_NOQUERY The same as OD_METAFILE, except the querying of attributes is not permitted.

OD_MEMORY A device context that is used to contain a bit map.

DELAY Delay script execution for five seconds.

DISPLAY Execute the currently selected test case.

EXIT Terminate DTT immediately.

PSTYPE Specify the presentation-space type to be used for subsequent test cases.

The operand is one of the following:

GPIT_MICRO Micro-presentation space.

GPIT_NORMAL Normal presentation space. (This is the default.)

PSUNITS Specify the presentation-space units to be used for subsequent test cases.

The operand is one of the following:

PU_ARBITRARY Application-convenient units.

PU_PELS Pel coordinates. (This is the default.)

PU_LOMETRIC Units of 0.1 mm.

PU_HIMETRIC Units of 0.01 mm.

PU_LOENGLISH Units of 0.01 inch.

PU_HIENGLISH Units of 0.001 inch.

PU_TWIPS Units of 1/1440 inch.

/--- Usage Notes ------------------------------------------\
|                                                          |
|  �  Blank lines and comments can appear anywhere in a    |
|     script file.                                         |
|                                                          |
|  �  Comments must be preceded by an asterisk (*) as the  |
|     first non-blank character on a line.                 |
|                                                          |
\----------------------------------------------------------/

DTT Command-Line Options Summary

-F Specify the path and file name for the DTT log file.

-I Specify the path and file name for a DTT script file.

-L Specify the logging level for the DTT session.

-K Specify the path and file name for a DTT test-case index file to be created.

-N Specify the path and file name for a DTT test-case index file to be loaded.

-S Search LIBPATH for test-case DLLs.

-T Specify a search pattern to locate test case DLLs to be preloaded.

-? Display the DTT command-line options.

Sample DTT Script File

--------------------------------------------------------------------------

*  Sample DTT script file

*  Select a device context.
DCTYPE OD_QUEUED

*  Set the presentation space type.
PSTYPE GPIT_NORMAL

*  Set the presentation space units.
PSUNITS PU_PELS

*  Select test cases and execute them; pause five
*    seconds between each test.

   Choose GreBitPre1
   Display
   Delay

   Choose GreDisjointLinesExh
   Display
   Delay

   Choose GrePolyLineExh
   Display
   Delay

   Choose GreMarkerExh
   Display
   Delay

   Choose GreTextApp1
   Display
   Delay

   Choose GreBitApp1
   Display
   Delay

   Choose GreCharRectExh
   Display
   Delay

   Choose GreIntersectClipRectangleExh
   Display
   Delay

   Choose GreSetAndGetAttributesExh1
   Display
   Delay

*  Terminate DTT.
EXIT


--------------------------------------------------------------------------

Glyph Codes

DBCS PM has reserved glyphs 768 - 1023 for DBCS glyphs. The following list shows the relationship between glyph pattern and glyph code ID in code page 932, except kanji patterns.

  #define UGL_DBCSFIRST            0x0300      /* 256 reserved */
  #define UGL_DBCSLAST             0x03FF

The following is a Glyph Code Table.

/--------------------------------------------------------------\
|Glyph Pt.      |ID             |Description                   |
|---------------+---------------+------------------------------|
|009            |SM750000       |black circle on white         |
|               |               |background                    |
|---------------+---------------+------------------------------|
|015            |SM690000       |sun                           |
|---------------+---------------+------------------------------|
|018            |SM760000       |up/down arrow                 |
|---------------+---------------+------------------------------|
|024            |SM320000       |up arrow                      |
|---------------+---------------+------------------------------|
|025            |SM330000       |down arrow                    |
|---------------+---------------+------------------------------|
|026            |SM310000       |right arrow                   |
|---------------+---------------+------------------------------|
|027            |SM300000       |left arrow                    |
|---------------+---------------+------------------------------|
|032            |SP010000       |( ) space                     |
|---------------+---------------+------------------------------|
|033            |SP020000       |(!) exclamation mark          |
|---------------+---------------+------------------------------|
|034            |SP040000       |(") double quote              |
|---------------+---------------+------------------------------|
|035            |SM010000       |(#) sharp sign                |
|---------------+---------------+------------------------------|
|036            |SC030000       |($) dollar sign               |
|---------------+---------------+------------------------------|
|037            |SM020000       |(%) percent sign              |
|---------------+---------------+------------------------------|
|038            |SM030000       |(&) ampersand                 |
|---------------+---------------+------------------------------|
|039            |SP050000       |(') single quote              |
|---------------+---------------+------------------------------|
|040            |SP060000       |(() left parenthesis          |
|---------------+---------------+------------------------------|
|041            |SP070000       |()) right parenthesis         |
|---------------+---------------+------------------------------|
|042            |SM040000       |(*) asterisk                  |
|---------------+---------------+------------------------------|
|043            |SA030000       |(+) plus                      |
|---------------+---------------+------------------------------|
|044            |SP080000       |(,) comma                     |
|---------------+---------------+------------------------------|
|045            |SP100000       |(-) minus                     |
|---------------+---------------+------------------------------|
|046            |SP110000       |(.) period                    |
|---------------+---------------+------------------------------|
|047            |SP120000       |(/) slash                     |
|---------------+---------------+------------------------------|
|048            |ND100000       |(0) digit                     |
|---------------+---------------+------------------------------|
|049            |ND010000       |(1) digit                     |
|---------------+---------------+------------------------------|
|050            |ND020000       |(2) digit                     |
|---------------+---------------+------------------------------|
|051            |ND030000       |(3) digit                     |
|---------------+---------------+------------------------------|
|052            |ND040000       |(4) digit                     |
|---------------+---------------+------------------------------|
|053            |ND050000       |(5) digit                     |
|---------------+---------------+------------------------------|
|054            |ND060000       |(6) digit                     |
|---------------+---------------+------------------------------|
|055            |ND070000       |(7) digit                     |
|---------------+---------------+------------------------------|
|056            |ND080000       |(8) digit                     |
|---------------+---------------+------------------------------|
|057            |ND090000       |(9) digit                     |
|---------------+---------------+------------------------------|
|058            |SP130000       |(                             |
|---------------+---------------+------------------------------|
|059            |SP140000       |(;) semi-colon                |
|---------------+---------------+------------------------------|
|060            |SA030000       |(<) left angle bracket        |
|---------------+---------------+------------------------------|
|061            |SA040000       |(=) equal sign                |
|---------------+---------------+------------------------------|
|062            |SA050000       |(>) right angle bracket       |
|---------------+---------------+------------------------------|
|063            |SP150000       |(?) question mark             |
|---------------+---------------+------------------------------|
|064            |SM050000       |(@) at sign                   |
|---------------+---------------+------------------------------|
|065            |LA020000       |(A) uppercase character       |
|---------------+---------------+------------------------------|
|066            |LB020000       |(B) uppercase character       |
|---------------+---------------+------------------------------|
|067            |LC020000       |(C) uppercase character       |
|---------------+---------------+------------------------------|
|068            |LD020000       |(D) uppercase character       |
|---------------+---------------+------------------------------|
|069            |LE020000       |(E) uppercase character       |
|---------------+---------------+------------------------------|
|070            |LF020000       |(F) uppercase character       |
|---------------+---------------+------------------------------|
|071            |LG020000       |(G) uppercase character       |
|---------------+---------------+------------------------------|
|072            |LH020000       |(H) uppercase character       |
|---------------+---------------+------------------------------|
|073            |LI020000       |(I) uppercase character       |
|---------------+---------------+------------------------------|
|074            |LJ020000       |(J) uppercase character       |
|---------------+---------------+------------------------------|
|075            |LK020000       |(K) uppercase character       |
|---------------+---------------+------------------------------|
|076            |LL020000       |(L) uppercase character       |
|---------------+---------------+------------------------------|
|077               | LM020000         | ( M )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 078               | LN020000         | ( N )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 079               | LO020000         | ( O )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 080               | LP020000         | ( P )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 081               | LQ020000         | ( Q )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 082               | LR020000         | ( R )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 083               | LS020000         | ( S )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 084               | LT020000         | ( T )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 085               | LU020000         | ( U )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 086               | LV020000         | ( V )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 087               | LW020000         | ( W )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 088               | LX020000         | ( X )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 089               | LY020000         | ( Y )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 090               | LZ020000         | ( Z )   uppercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 091               | SM060000         | ( [ )   left   bracket                 | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 092               | SM070000         | ( \ )   backslash                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 093               | SM080000         | ( ] )   right   bracket                | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 094               | SD150000         | ( ^ )   caret                         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 095               | SP090000         | ( _ )   underscore                   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 096               | SP130000         | ( ' )   back - quote                   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 097               | LA010000         | ( a )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 098               | LB010000         | ( b )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 099               | LC010000         | ( c )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 100               | LD010000         | ( d )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 101               | LE010000         | ( e )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 102               | LF010000         | ( f )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 103               | LG010000         | ( g )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 104               | LH010000         | ( h )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 105               | LI010000         | ( i )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 106               | LJ010000         | ( j )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 107               | LK010000         | ( k )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 108               | LL010000         | ( l )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 109               | LM010000         | ( m )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 110               | LN010000         | ( n )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 111               | LO010000         | ( o )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 112               | LP010000         | ( p )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 113               | LQ010000         | ( q )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 114               | LR010000         | ( r )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 115               | LS010000         | ( s )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 116               | LT010000         | ( t )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 117               | LU010000         | ( u )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 118               | LV010000         | ( v )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 119               | LW010000         | ( w )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 120               | LX010000         | ( x )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 121               | LY010000         | ( y )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 122               | LZ010000         | ( z )   lowercase   character         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 123               | SM110000         | ( { )   left   brace                   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 124               | SM130000         | ( | )   vertical   bar                 | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 125               | SM140000         | ( } )   right   brace                  | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 126               | SD190000         | ( ~ )   tilde                         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 127               | SM790000         | home - plate ( small   house )         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 176               | SF140000         | light   grey   block                 | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 177               | SF150000         | medium   grey   block                | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 178               | SF160000         | dark   grey   block                  | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 185               | SF230000         | double   line   join   double         | 
|                  |                  | vertical                          | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 186               | SF240000         | double   vertical                  | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 187               | SF250000         | double   bottom   left   corner       | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 188               | SF260000         | double   top   left   corner          | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 200               | SF380000         | double   top   right   corner         | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 201               | SF390000         | double   bottom   right   corner      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 202               | SF400000         | double   horz .   join   double   line   | 
|                  |                  | above                             | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 203               | SF410000         | double   horz .   join   double   line   | 
|                  |                  | below                             | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 204               | SF420000         | double   vertical   join   double     | 
|                  |                  | line                              | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 205               | SF430000         | double   line                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 206               | SF440000         | double   vertical   cross   double    | 
|                  |                  | line                              | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 254               | SM470000         | small   block                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 257               | SC050000         | Yen   sign                          | 
\ ---------- ----- - ---------- ----- - ---------- ---------- ---------- / 

The following is a Glyph Code Table, reserved by DBCS.

/--------------------------------------------------------------\
|Glyph Pt.      |ID             |Description                   |
|---------------+---------------+------------------------------|
|768            |SP500000       |0x0B for code page 897/1      |
|---------------+---------------+------------------------------|
|769            |SM720000       |0x1B for code page 897/1      |
|---------------+---------------+------------------------------|
|770            |JQ700000       |Katakana Full Stop            |
|---------------+---------------+------------------------------|
|771            |JQ710000       |Katakana Left Bracket         |
|---------------+---------------+------------------------------|
|772            |JQ720000       |Katakana Right Bracket        |
|---------------+---------------+------------------------------|
|773            |JQ730000       |Katakana Comma                |
|---------------+---------------+------------------------------|
|774            |JQ740000       |Katakana Conjunctive Symbol   |
|---------------+---------------+------------------------------|
|775            |JW500000       |WO, Katakana Participle       |
|---------------+---------------+------------------------------|
|776            |JA010000       |a, Katakana                   |
|---------------+---------------+------------------------------|
|777            |JI010000       |i, Katakana                   |
|---------------+---------------+------------------------------|
|778            |JU010000       |u, Katakana                   |
|---------------+---------------+------------------------------|
|779            |JE010000       |e, Katakana                   |
|---------------+---------------+------------------------------|
|780            |JO010000       |o, Katakana                   |
|---------------+---------------+------------------------------|
|781            |JY110000       |ya, Katakana                  |
|---------------+---------------+------------------------------|
|782            |JY310000       |yu, Katakana                  |
|---------------+---------------+------------------------------|
|783            |JY510000       |yo, Katakana                  |
|---------------+---------------+------------------------------|
|784            |JT310000       |tu, Katakana                  |
|---------------+---------------+------------------------------|
|785            |JX700000       |Katakana Prolonged Sound      |
|               |               |Symbol                        |
|---------------+---------------+------------------------------|
|786            |JA000000       |A, Katakana                   |
|---------------+---------------+------------------------------|
|787            |JI000000       |I, Katakana                   |
|---------------+---------------+------------------------------|
|788            |JU000000       |U, Katakana                   |
|---------------+---------------+------------------------------|
|789            |JE000000       |E, Katakana                   |
|---------------+---------------+------------------------------|
|790            |JO000000       |O, Katakana                   |
|---------------+---------------+------------------------------|
|791            |JK100000       |KA, Katakana                  |
|---------------+---------------+------------------------------|
|792            |JK200000       |KI, Katakana                  |
|---------------+---------------+------------------------------|
|793            |JK300000       |KU, Katakana                  |
|---------------+---------------+------------------------------|
|794            |JK400000       |KE, Katakana                  |
|---------------+---------------+------------------------------|
|795            |JK500000       |KO, Katakana                  |
|---------------+---------------+------------------------------|
|796            |JS100000       |SA, Katakana                  |
|---------------+---------------+------------------------------|
|797            |JS200000       |SI, Katakana                  |
|---------------+---------------+------------------------------|
|798            |JS300000       |SU, Katakana                  |
|---------------+---------------+------------------------------|
|799            |JS400000       |SE, Katakana                  |
|---------------+---------------+------------------------------|
|800            |JS500000       |SO, Katakana                  |
|---------------+---------------+------------------------------|
|801            |JT100000       |TA, Katakana                  |
|---------------+---------------+------------------------------|
|802            |JT200000       |TI, Katakana                  |
|---------------+---------------+------------------------------|
|803            |JT300000       |TU, Katakana                  |
|---------------+---------------+------------------------------|
|804            |JT400000       |TE, Katakana                  |
|---------------+---------------+------------------------------|
|805            |JT500000       |TO, Katakana                  |
|---------------+---------------+------------------------------|
|806            |JN100000       |NA, Katakana                  |
|---------------+---------------+------------------------------|
|807            |JN200000       |NI, Katakana                  |
|---------------+---------------+------------------------------|
|808            |JN300000       |NU, Katakana                  |
|---------------+---------------+------------------------------|
|809            |JN400000       |NE, Katakana                  |
|---------------+---------------+------------------------------|
|810            |JN500000       |NO, Katakana                  |
|---------------+---------------+------------------------------|
|811            |JH100000       |HA, Katakana                  |
|---------------+---------------+------------------------------|
|812            |JH200000       |HI, Katakana                  |
|---------------+---------------+------------------------------|
|813            |JH300000       |HU, Katakana                  |
|---------------+---------------+------------------------------|
|814            |JH400000       |HE, Katakana                  |
|---------------+---------------+------------------------------|
|815            |JH500000       |HO, Katakana                  |
|---------------+---------------+------------------------------|
|816            |JM100000       |MA, Katakana                  |
|---------------+---------------+------------------------------|
|817            |JM200000       |MI, Katakana                  |
|---------------+---------------+------------------------------|
|818            |JM300000       |MU, Katakana                  |
|---------------+---------------+------------------------------|
|819            |JM400000       |ME, Katakana                  |
|---------------+---------------+------------------------------|
|820            |JM500000       |MO, Katakana                  |
|---------------+---------------+------------------------------|
|821            |JY100000       |YA, Katakana                  |
|---------------+---------------+------------------------------|
|822            |JY300000       |YU, Katakana                  |
|---------------+---------------+------------------------------|
|823            |JY500000       |YO, Katakana                  |
|---------------+---------------+------------------------------|
|824            |JR100000       |RA, Katakana                  |
|---------------+---------------+------------------------------|
|825            |JR200000       |RI, Katakana                  |
|---------------+---------------+------------------------------|
|826            |JR300000       |RU, Katakana                  |
|---------------+---------------+------------------------------|
|827            |JR400000       |RE, Katakana                  |
|---------------+---------------+------------------------------|
|828            |JR500000       |RO, Katakana                  |
|---------------+---------------+------------------------------|
|829            |JW100000       |WA, Katakana                  |
|---------------+---------------+------------------------------|
|830            |JN000000       |N, Katakana                   |
|---------------+---------------+------------------------------|
|831            |JX710000       |Katakana Voiced Sound Symbol  |
|---------------+---------------+------------------------------|
|832            |JX720000       |Katakana Semi-Voiced Sound    |
|               |               |Symbol                        |
|---------------+---------------+------------------------------|
|833            |RA010000       |a, Hiragana                   |
|---------------+---------------+------------------------------|
|834            |RI010000       |i, Hiragana                   |
|---------------+---------------+------------------------------|
|835            |RU010000         | u ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 836               | RE010000         | e ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 837               | RO010000         | o ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 838               | RY110000         | ya ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 839               | RY310000         | yu ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 840               | RY510000         | yo ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 841               | RT310000         | tu ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 842               | RA000000         | A ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 843               | RI000000         | I ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 844               | RU000000         | U ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 845               | RE000000         | E ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 846               | RO000000         | O ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 847               | RK100000         | KA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 848               | RK200000         | KI ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 849               | RK300000         | KU ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 850               | RK400000         | KE ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 851               | RK500000         | KO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 852               | RS100000         | SA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 853               | RS200000         | SI ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 854               | RS300000         | SU ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 855               | RS400000         | SE ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 856               | RS500000         | SO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 857               | RT100000         | TA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 858               | RT200000         | TI ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 859               | RT300000         | TU ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 860               | RT400000         | TE ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 861               | RT500000         | TO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 862               | RN100000         | NA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 863               | RN200000         | NI ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 864               | RN300000         | NU ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 865               | RN400000         | NE ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 866               | RN500000         | NO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 867               | RH100000         | HA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 868               | RH200000         | HI ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 869               | RH300000         | U ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 870               | RH400000         | E ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 871               | RH500000         | HO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 872               | RM100000         | MA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 873               | RM200000         | MI ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 874               | RM300000         | MU ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 875               | RM400000         | ME ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 876               | RM500000         | MO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 877               | RY100000         | YA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 878               | RY300000         | YU ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 879               | RY500000         | YO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 880               | RR100000         | RA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 881               | RR200000         | RI ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 882               | RR300000         | RU ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 883               | RR400000         | RE ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 884               | RR500000         | RO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 885               | RW100000         | WA ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 886               | RW500000         | WO ,   Hiragana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 887               | RN000000         | N ,   Hiragana                      | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 888               | JQ710010         | Katakana   Left                    | 
|                  |                  | Bracket , Alternate                | 
|                  |                  | Representation                   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 889               | JQ720010         | Katakana   Right                   | 
|                  |                  | Bracket , Alternate                | 
|                  |                  | Representation                   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 890               | JK410000         | ke ,   Katakana                     | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 891               | SS770000         | Kanji   Reiterative   Symbol        | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 892               | SP010000         | reserved   by   Japan   ( now   Space )   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 893               | SP010000         | reserved   by   Japan   ( now   Space )   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 894               | SP010000         | reserved   by   Japan   ( now   Space )   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 895               | SP010000         | reserved   by   Japan   ( now   Space )   | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 896 ( 0x380 )       | OG000000         | 0xC1   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 897               | OG100000         | 0xC2   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 898               | OG200000         | 0xC3   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 899               | ON000000         | 0xC4   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 900               | ON150000         | 0xC5   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 901               | ON100000         | 0xC6   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 902               | OD000000         | 0xC7   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 903               | OD100000         | 0xC8   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 904               | OL000000         | 0xC9   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 905               | OL200000         | 0xCA   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 906               | OL400000         | 0xCB   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 907               | OL100000         | 0xCC   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 908               | OL600000         | 0xCD   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 909               | OL700000         | 0xCE   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 910               | OL500000         | 0xCF   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 911               | OL300000         | 0xD0   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 912               | OM000000         | 0xD1   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 913               | OB000000         | 0xD2   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 914               | OB100000         | 0xD3   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 915               | OB200000         | 0xD4   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 916               | OS000000         | 0xD5   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 917               | OS100000         | 0xD6   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 918               | ON200000         | 0xD7   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 919               | OJ000000         | 0xD8   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 920               | OJ100000         | 0xD9   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 921               | OC200000         | 0xDA   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 922               | OK000000         | 0xDB   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 923               | OT000000         | 0xDC   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 924               | OP000000         | 0xDD   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 925               | OH000000         | 0xDE   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 926               | OA000000         | 0xE2   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 927               | OA200000         | 0xE3   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 928               | OY200000         | 0xE4   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 929               | OY250000         | 0xE5   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 930               | OE200000         | 0xE6   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 931               | OE000000         | 0xE7   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 932               | OY400000         | 0xEA   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 933               | OY300000         | 0xEB   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 934               | OO000000         | 0xEC   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 935               | OO100000         | 0xED   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 936               | OO200000         | 0xEE   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 937               | OO300000         | 0xEF   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 938               | OY500000         | 0xF2   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 939               | OU000000         | 0xF3   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 940               | OU300000         | 0xF4   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 941               | OU200000         | 0xF5   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 942               | OU400000         | 0xF6   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 943               | OY600000         | 0xF7   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 944               | OE300000         | 0xFA   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 945               | OE400000         | 0xFB   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 946               | OI000000         | 0xFC   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 947               | SC140000         | 0x5C   for   code   page               | 
|                  |                  | 891 ( Korea - PC )                    | 
| ---------- ----- + ---------- ----- + ---------- ---------- ---------- | 
| 948               | SC120000         | 0x5C   for   code   page   903 ( PRC - PC ) | 
\ ---------- ----- - ---------- ----- - ---------- ---------- ---------- / 

S3 Display Driver

This chapter explains the architecture of the S3 display device driver. Because the S3 driver was originally developed from the XGA and 8514 driver source code, their features will be explained. The purpose of this document is for you to have an understanding of the portions of the driver that must be modified to support other graphics-accelerator chip sets.

Overview

The S3 display device driver for OS/2 2.1 (and later) consists of approximately 5.8MB of C-language and assembler-language source code spread over approximately 263 files.

Use the S3 display driver as a starting point when developing a presentation display driver for a graphics chip. The S3 driver is written in a combination of C and assembler language with almost half of the source files coded in C. The C-language modules control driver initialization, operating system-dependent functions, and the device-independent setup required by most presentation display driver entry points. Device-dependent and high-performance code are controlled by the assembler-language modules.

The S3 driver was specifically designed for fixed-function video- accelerator chips. It also takes advantage of features such as hardware- assisted bitblt, hardware-line drawing, MMPM/2, fast-monochrome data expansion, bit-map caching and font caching.

The S3 driver offers a number of features not offered by the SVGA driver. It supports multiple resolutions and color depths in a single driver. Further, it supports static-mode change, which makes changing resolution and color depth as easy as changing the desktop color scheme.

Most of the hardware-dependent code is isolated into a handful of assembler -language files. These files have straightforward functions that can be implemented on most accelerator chips. Higher level functions that are also hardware-dependent, such as bit map and font caching, are written in C.

The XGA Driver

The S3 driver was derived from the 32-bit 8514/A presentation display driver for OS/2. This driver, was in turn, derived from the 32-bit XGA presentation display driver. Because the design of the driver was strongly influenced by the features offered by the XGA, and to some extent, the 8514 /A, it is necessary to understand certain aspects of the XGA and 8514/A presentation display drivers.

XGA Pixmaps

The pixmap is a fundamental element of the XGA presentation display driver and the XGA hardware. The pixmap is a description of the height, width, and color depth of a bit map in either system memory or video memory. (The XGA presentation display driver exploits bus-mastering, which allows it to operate on pixmaps in system memory or video memory. Note that in this document, VRAMrefers to the memory on the video card.) The 8514 and S3 source code refer to bit maps as if they were XGA pixmaps, even though neither graphics chip set directly supports pixmaps. The following example of pixmap code appears in the EDDHBBLT.ASM file:

; select the destination map
        memregwrite     pi_map_index_A, SEL_PIX_MAP_A

; write destination bit-map address to hardware mapA base
        mov             eax, [ebx].bit map_address
        IFDEF  _8514
        IFDEF  HARD_DRAW
        and     eax,0fffffffh   ; clear the vram marker
        ENDIF
        ENDIF
        memregwrite     pi_map_base_ptr_A, eax

; write mapA width and height from bit-map header
        mov             eax, dword ptr [ebx].hw_width
        memregwrite     pi_map_size_A, eax

; write mapA format from bit-map header
        mov             al, byte ptr [ebx].hw_format
        memregwrite     pi_map_format_A, al

The memregwrite assembler macros located throughout the source code are used in the XGA display driver to write to XGA-hardware registers. Except for the section in the IFDEF_8514, this code is identical to that found in the XGA display driver. To use this driver source, an understanding of the XGA architecture is essential, even if the graphics chip set is nothing like an XGA chip set.

The following portion of the MMXGAReg structure shows the registers that define a pixmap for the XGA driver:

typedef struct _MMREG {
        .
        .
        .
volatile BYTE    pixmapIndex;
volatile BYTE    bNotUsed5;
volatile ULONG   pixmapBase;
volatile USHORT  pixmapWidth;
volatile USHORT  pixmapHeight;
volatile BYTE    pixmapFormat;
        .
        .
        .
} MMReg;

PixMapIndexselects which of the pixmaps is being defined. The XGA chipset implements four pixmaps: pixmaps A, B, C, and a mask map that must be monochrome. The mask map is primarily used for non-rectangular scissoring, and is not ordinarily used in the XGA presentation display driver. The other maps can be used as either source, destination, or pattern maps.

PixMapBaseis the base address in either system or video memory of the pixmap. The XGA driver refers to objects by their address, rather than by X -Y coordinates of the object in VRAM. The XGA display driver refers to all objects by their address (even cached objects in off-screen VRAM) and is fundamental to the design of the XGA display driver. The XGA chip has a memory management unit that allows it to know if a given pixmap is in VRAM or in system memory. Everything has a virtual address, from the glyph cached in VRAM to the largest system-memory bit map. Objects in VRAM, the character cache, and the Phunk (see The Physical Chunk and Bus-Master Operations, for further information), also have physical addresses associated with them.

PixMapWidthis the actual width of the bit map in pels minus one pel. To simplify the caching of objects in off-screen VRAM, the XGA driver stores bit maps as linear arrays of bytes in off-screen video memory or system memory.

PixMapHeightis the actual height of the bit map in pels minus one pel.

PixMapFormatis the size of the pels in the pixmap, as well as a flag indicating whether the pixmap is stored in Motorola** or Intel** byte-ordering format (the XGA chip set can handle either format). Pel depths can be 1, 4, 8, 16, or 24 bits.

The displayed portion of video memory (display surface) is a pixmap to the XGA driver. Portions of it may be addressed by using the XGA driver's X-Y source or destination registers. The information the XGA driver regards as a pixmap is very similar to that contained in a presentation display bit- map header. (In fact, the previous source code example consisted of copying elements out of the bit-map header.)

Fundamental to the XGA driver's design is that it can perform BitBlts and other accelerator operations on arbitrary bit maps. Because of this design , much of the XGA driver code defines bit maps in system memory as pixmaps. The XGA driver's memory-management scheme is versatile enough to allow the bit-map drawing code in the XGA, 8514/A, and S3 drivers to interpret system -memory images of XGA registers, and determine which drawing operations to perform on bit maps.

XGA Registers

The XGA driver supports both I/O-mapped and memory-mapped registers. The I/ O-mapped XGA registers are used during the initialization of the card and during video-mode setting. The memory-mapped registers control the drawing operations of the XGA driver. Consequently, the XGA presentation display driver rarely uses an assembler outinstruction. The only common driver operation that performs port I/O is the XGA driver's palette RAMDAC in 256- color mode. The XGA presentation display driver takes advantage of this by running at ring 3. Code running at ring 3 is not allowed to perform port I /O. However, applications and the OS/2 graphics engine (GRE) run at ring 3 . Therefore, by running at ring 3, the XGA presentation driver avoids a ring transition on every call into the driver that actually touches the hardware. Using memory-mapped registers is faster than using port I/O, which tends to be slow in protect-mode on Intel 80x86 microprocessors.

The XGA presentation display driver does not use a 32-bit flat pointer to its memory-mapped registers. Instead, it obtains a selector that maps to its memory-mapped registers from its ring 0 driver, XGA.SYS. To find out where this process occurs, look in the EDDEFPDB.C file at the QueryAdapter( ) function. QueryAdapter() makes two IOCtl calls to the XGA.SYS module. The first call obtains the selector to the memory-mapped XGA registers. ( Look in the XGAADAPT.INC file for the details of what is returned by these two IOCtl calls.) For other types of adapters with memory-mapped registers, it is possible to make IOCtl calls to the PMDD.SYS module and obtain a flat pointer to memory-mapped registers. The only place in the presentation driver where this should not occur is in the code that updates the cursor at interrupt level. (This code is located in the EDDCURSR.ASM file.) Having flat pointers in the cursor code does not enable you to determine in which context the cursor code will be called. It is possible that the cursor code will be used in a context in which the flat pointer to memory-mapped registers is invalid (because the cursor code is called at interrupt time). Consequently, it is convenient to use a ring 0 GDT Selector in the cursor- movement code. See Driver Initializationfor more information on flat pointers to video memory.

Shadow XGA Registers

The following piece of code initializes the foreground and background colors for a particular blt. It is a portion of the XGA code from the EDDNBBLT.C file:

       /**************************************************************/
       /* set the foreground and background colors for the blt.      */
       /* These are taken from the destination attribute bundle      */
       /* unless color information was passed in the parameters      */
       /**************************************************************/

if (ArgOptions & BLTMODE_ATTRS_PRES)
{
    ShadowXGARegs.FgCol = (USHORT)LogToPhyIndex(ArgAttrs->lColor);
    ShadowXGARegs.BgCol = (USHORT)LogToPhyIndex(ArgAttrs->lBackColor);
}
else /* use attribute bundle colors */
{
    ShadowXGARegs.FgCol = (USHORT)pdc->DCIImagColatts.ForeColor;
    ShadowXGARegs.BgCol = (USHORT)pdc->DCIImagColatts.BackColor;
}

The ShadowXGARegs structure is declared as type MMREG. The definition for MMREG appears in the XGAADAPT.H file. The definition for MMREG is as follows:

typedef struct _MMReg
    {

       /**************************************************************/
       /* Fields are declared volatile to prevent the compiler that  */
       /* is generating code to write a value to the register, and   */
       /* then read it back expecting it to be the same.             */
       /* However, volatile is not implemented by c5.1.              */
       /**************************************************************/
        volatile ULONG   PageDirBaseAdd;

        volatile ULONG   CurrVirtAddr;

        volatile BYTE    bNotUsed1;
        volatile BYTE    ExtPolling;
        volatile USHORT  bNotUsed2;

        volatile BYTE    StateAlen;
        volatile BYTE    StateBlen;
        volatile USHORT  usNotUsed3;

        volatile BYTE    bNotUsed4;
        volatile BYTE    PIControl;

   /**********************************************************************/
   /* These pixmap registers will not be written to when in software     */
   /* mode                                                               */
   /**********************************************************************/

volatile BYTE pixmapIndex; volatile BYTE bNotUsed5;

        volatile ULONG   pixmapBase;

        volatile USHORT  pixmapWidth;
        volatile USHORT  pixmapHeight;

        volatile BYTE    pixmapFormat;
        volatile BYTE    abNotUsed6[3];

   /**********************************************************************/
   /* End of pixmap registers                                            */
   /**********************************************************************/


        volatile USHORT  BresErrTerm;
        volatile USHORT  usNotUsed7;

        volatile USHORT  BresK1;
        volatile USHORT  usNotUsed8;

        volatile USHORT  BresK2;
        volatile USHORT  usNotUsed9;

        volatile ULONG   DirSteps;

        volatile BYTE    bFifthStep;

/* used by software simulation only */

        volatile BYTE    abNotUsed10[23];

        volatile BYTE    FgMix;
        volatile BYTE    BgMix;
        volatile BYTE    ColCompCond;
        volatile BYTE    bNotUsed11;

        volatile ULONG   ColCompVal;

        volatile ULONG   PlaneMask;

        volatile ULONG   CarryChMask;

        volatile USHORT  FgCol;
        volatile USHORT  FgColHi;

        volatile USHORT  BgCol;
        volatile USHORT  BgColHi;

        volatile USHORT  OpDim1;
        volatile USHORT  OpDim2;

        volatile ULONG   ausNotUsed12[2];

        volatile USHORT  MaskXOffset;
        volatile USHORT  MaskYOffset;

        volatile USHORT  SrcXAddr;
        volatile USHORT  SrcYAddr;

        volatile USHORT  PatXAddr;
        volatile USHORT  PatYAddr;

        volatile SHORT   DstXAddr;
        volatile SHORT   DstYAddr;

        volatile ULONG   PixOp;

    /*********************************************************************/
    /* Here, start extra pixmap definitions, one each for A,B,C and the  */
    /* mask.  The arrangement of these is an exact image of the real     */
    /* registers. (As a result, padding was included).                   */
    /* Note that these 'shadow' registers are always in memory so        */
    /* need not be declared as volatile.                                 */
    /*********************************************************************/

        BYTE    pixmapIndexA;
        BYTE    bPaddingA;
        ULONG   pixmapBaseA;
        USHORT  pixmapWidthA;
        USHORT  pixmapHeightA;
        BYTE    pixmapFormatA;
        BYTE    bPaddingA2;

        BYTE    pixmapIndexB;
        BYTE    bPaddingB;
        ULONG   pixmapBaseB;
        USHORT  pixmapWidthB;
        USHORT  pixmapHeightB;
        BYTE    pixmapFormatB;
        BYTE    bPaddingB2;

        BYTE    pixmapIndexC;
        BYTE    bPaddingC;
        ULONG   pixmapBaseC;
        USHORT  pixmapWidthC;
        USHORT  pixmapHeightC;
        USHORT  pixmapFormatC;
        BYTE    bPaddingC2;

        BYTE    pixmapIndexM;
        BYTE    bPaddingM;
        ULONG   pixmapBaseM;
        USHORT  pixmapWidthM;
        USHORT  pixmapHeightM;
        BYTE    pixmapFormatM;
        BYTE    bPaddingM2;

    } MMReg;

The ShadowXGARegs structure is a system-memory image of values that ultimately will be written to the XGA chip set. After all of the registers needed for an operation are initialized in the structure, the driver calls the TransferShadowRegisters function, which is located in the assembler language file HWACCESS.ASM. TransferShadowRegisters copies the information from the ShadowXGARegs structure to the XGA memory-mapped registers. By polling the Control register, the original XGA graphics chip set was slowed down so that it could wait for the chip to complete a graphics operation. It is necessary to check that the XGA is not busy before writing to its registers, as the XGA has no register FIFO. To some extent, the ShadowXGARegs structure serves as a software FIFO by delaying actual hardware register writes, as long as is possible.

The ShadowXGARegs structure is the portion of the presentation display driver that draws to bit maps and emulates an XGA. Thus, all of the drawing code in the XGA driver for bit maps and the display is identical up to the point at which the actual drawing command is issued to the XGA driver's command register. (The XGA presentation display driver refers to the command register as the Pixel_Op.) The following is an example of the pixel operation from the EDDHGCHS.ASM file, the character drawing code. This example draws a character on either the XGA display surface or to a bit map in system memory.

     ;********************************************************************
     ; Before updating the hardware, determine
     ; its availability and write the destination coordinates.
     ;********************************************************************

        waitshort
        memregwrite        dest_map, eax

     ;********************************************************************
     ; Changes to the processing of bold simulation means that
     ; the foreground mix and color must be written each time.
     ;********************************************************************
ifndef _8514
       mov             al, AIxfer.bfgmix
       memregwrite     fg_mix, al
       mov             ax, AIxfer.usFColor
       memregwrite     fg_colour, ax
endif

     ;********************************************************************
     ; Source is x = left clip adjustment (currently in cx),
     ; y = cell height - 1
     ;********************************************************************

        mov     ax, ptsCharHWsize.y
        shl     eax, 16
        mov     ax, cx
        memregwrite     patt_map, eax

     ;********************************************************************
     ; Write the x dimension to the hardware.
     ;********************************************************************

memregwrite dim1, dx

     ;********************************************************************
     ; Write the character width to the hardware.
     ;********************************************************************

        swap   edx
        memregwrite       pi_map_width_C,dx

     ;********************************************************************
     ; Set up the source address.
     ;********************************************************************

        mov     eax, pGlyphImage
        memregwrite     pi_map_base_ptr_C, eax

     ;********************************************************************
     ; Set the pixel_op and kick off the blt
     ; -  background source: background color
     ; -  foreground source: foreground color
     ; -  step: PxBlt
     ; -  source pixel map:
     ; -  destination pixel map: Map A
     ; -  pattern pixel map: Map C
     ; -  mask pixel map: boundary disabled
     ; -  drawing mode:
     ; -  direction octant: left to right, bottom to top
     ;********************************************************************

         memregwrite        pixel_op,     08013002h

IFDEF HARD_DRAW
ELSE ; SOFT_DRAW
        saveregs
        call    _eddf_MESS
        restoreregs
ENDIF ; SOFT_DRAW

Soft-Draw Mode and Hard-Draw Mode

All presentation display drivers have two major but only marginally related functions: drawing to the display, and drawing to memory bit maps. This dual-mode drawing architecture was resolved by having the bit-map drawing code emulate the XGA hardware. Thus, all of the code needed to set up a drawing operation would be almost identical for the display and for bit maps. Hard-draw mode, therefore, is the mode in which the driver will write data to the XGA adapter, while Soft-draw mode writes only to system-memory bit maps.

Note:The bit map drawing code in the XGA driver emulates a subset of the XGA's hardware drawing capabilities.

In the previous example, Hard-draw mode was used. The following is an example of Soft-draw mode from the EDDNBBLT.C file.

    if (AIxfer.pbmhDest == &DirectListEntry)
    {
        SetDrawModeHard;
    }
    else
    {
        SetDrawModeSoft;
    }

This example is from the eddt_CacheCharacter() function in the EDDNGCHS.C file in the glyph-caching code.

        ShadowXGARegs.FgMix = HWMIX_SOURCE;
        ShadowXGARegs.BgMix = HWMIX_SOURCE;

        ShadowXGARegs.ColCompCond = COLCOMP_ALWAYS;

       /**************************************************************/
       /* Set up destination pixmap details.                         */
       /**************************************************************/

        ShadowXGARegs.pixmapBaseA   = pVRAMCacheStart +
offNextFree11Pos;
        ShadowXGARegs.pixmapWidthA  = xGlyphWidthHW;
        ShadowXGARegs.pixmapHeightA = yGlyphHeight;
        ShadowXGARegs.pixmapFormatA = ONE_BPP;

       /**************************************************************/
       /* Set up source pixmap details.                              */
       /**************************************************************/

        ShadowXGARegs.pixmapBaseB = pSysCacheStartPhy +
offNextFree11Pos;
        ShadowXGARegs.pixmapWidthB  = xGlyphWidthHW;
        ShadowXGARegs.pixmapHeightB = yGlyphHeight;
        ShadowXGARegs.pixmapFormatB = ONE_BPP | MOTOROLA;

       /**************************************************************/
       /* Set up blt details - we want to copy the whole character.  */
       /**************************************************************/

        ShadowXGARegs.SrcXAddr =
         ShadowXGARegs.SrcYAddr =
          ShadowXGARegs.DstXAddr =
           ShadowXGARegs.DstYAddr = 0;

        ShadowXGARegs.OpDim1 = xGlyphWidthHW;
        ShadowXGARegs.OpDim2 = yGlyphHeight;

       /**************************************************************/
       /* Set up the pixel_op to do the blt.                         */
       /**************************************************************/

        ShadowXGARegs.PixOp = BACK_SRC_SRC_PIX_MAP |
                              FORE_SRC_SRC_PIX_MAP |
                              STEP_PXBLT |
                              SRC_PIX_MAP_B |
                              DST_PIX_MAP_A |
                              PAT_PIX_MAP_FORE |
                              MASK_PIX_MAP_OFF |
                              DRAW_MODE_DONTCARE |
                              DIR_OCTANT_LRTB;

       /**************************************************************/
       /* Now do the blt. We have to use the hardware to do this.    */
       /* Set softDrawInUse to false, and then restore it after the  */
       /* blt has been completed.  (Higher level functions may be in */
       /* software-drawing mode, but still keep the VRAM-cache       */
       /* copy up-to-date.)                                          */
       /**************************************************************/

        tempDrawMode = softDrawInUse;
        softDrawInUse = FALSE;
        TransferShadowRegisters( TSR_MAP_A |
                                 TSR_MAP_B |
                                 TSR_COLOUR_MIX |
                                 TSR_COORDINATES |
                                 TSR_PIXELOP );
        softDrawInUse = tempDrawMode;

The preceeding code example copies a character from system memory into the VRAM in cache of the XGA presentation display driver. The TransferShadowRegisters function initiates an XGA bus-mastering BitBlt to copy the character.

The top-level functions in the XGA presentation display driver are written in C language. These functions are set up for a drawing operation by parsing through data structures passed in from GRE and setting up the ShadowXGARegs structure. At a certain point, they look at the address of the bit map that was passed in by GRE. If the address is the display, it uses the SetDrawModeHard macro, otherwise, SetDrawModeSoft is called. In the above example, SetDrawModeHard is executed rather than SetDrawModeSoft. The SetDrawModeHard and SetDrawModeSoft macros, which are located in the EDDMACRO.H. file, are described in the following example :

#define SetDrawModeSoft                                                \
{                                                                      \
    if (!softDrawInUse)                                                \
    {                                                                  \
        pXGARegs          = (pMMReg)&ShadowXGARegs;                    \
        LinePatternCur    = LinePatternSys;                            \
        MarkerCur         = MarkerSys;                                 \
        pDrawFunctions    = (pDrawFunctionsTable)softDrawTable;        \
        softDrawInUse     = TRUE;                                      \
    }                                                                  \
}                                                                      \
                                                                       \
#define SetDrawModeHard                                                \
{                                                                      \
    if (softDrawInUse && foregroundSession)                            \
    {                                                                  \
        pXGARegs          = pRealXGARegs;                              \
        LinePatternCur    = LinePatternPhys;                           \
        MarkerCur         = MarkerPhys;                                \
        pDrawFunctions    = (pDrawFunctionsTable)hardDrawTable;        \
        softDrawInUse     = FALSE;                                     \
    }                                                                  \
}

Initially, SetDrawModeHard determines that it is currently in software- drawing mode by looking at the global flag softDrawInUse and by ensuring the presentation display driver is in the foreground. (A BitBlt operation does not occur in the XGA hardware while the user is running a DOS text- mode application in the foreground.) Next, SetDrawModeHard points pXGARegs to the selector and offset of the XGA driver's memory-mapped registers. ( PXGARegs is a pointer used by various assembler-language modules.) It then sets up pointers to the line patterns and markers in XGA video memory. Finally, it sets up the pDrawFunctions table to point to the set of assembler-language functions that draw to the XGA display, and clears the softDrawInUse flag.

Very few XGA drawing operations are initiated by the C code in the XGA driver. Instead, a group of assembler-language functions (pDrawFunctions) are called and they complete all of the real drawing work. These functions are:

eddh_DestOnlyBlt
eddh_DrawText
eddh_PatDestBlt
eddh_PMIMAGEDATA
eddh_PMLINES
eddh_PMPLOTSTEP
eddh_PMSCANLINE
eddh_SrcDestBlt
eddf_DestOnlyBlt
eddf_DrawText
eddf_PatDestBlt
eddf_PMIMAGEDATA
eddf_PMLINES
eddf_PMPLOTSTEP
eddf_PMSCANLINE
eddf_PMSHORTLINES
eddf_SrcDestBlt

These functions fall into two groups: one for drawing to the display, and one for drawing to memory. Pointers to these functions are stored in two tables in the EDDFDADA.C file. The hardDrawTable contains pointers to the functions that start with "eddh." The softDrawTable contains pointers to the functions that start with "eddf."

These functions are important as they represent the bulk of the hardware- dependent code in the driver. The following is a listing of the source files associated with each function:

EDDHBBLT.ASM:
        eddh_DestOnlyBlt
        eddh_PatDestBlt
        eddh_SrcDestBlt
        eddf_DestOnlyBlt
        eddf_PatDestBlt
        eddf_SrcDestBlt

EDDHGCHS.ASM:
        eddh_DrawText
        eddf_DrawText

EDDHIMAG.ASM:
        eddh_PMIMAGEDATA
        eddf_PMIMAGEDATA

EDDHLINE.ASM:
        eddh_PMLINES
        eddh_PMPLOTSTEP
        eddf_PMLINES
        eddf_PMPLOTSTEP

EDDHSCAN.ASM:
        eddh_PMSCANLINE
        eddf_PMSCANLINE

EDDHSHRT.ASM:
        eddh_PMSHORTLINES
        eddf_PMSHORTLINES

Note that each file lists two versions of each routine: one for hardware drawing, and the other for drawing to bit maps. The code for soft-draw and hard-draw is similar in all of these files. Each of these files is assembled twice, once with HARD_DRAW defined, and once with SOFT_DRAW defined. The conditional assembler in the files renames the major functions, and inserts calls to the bit-map drawing routine, EDDF_MESS. ( EDDF_MESS is located in the DDFFAST.ASM file.) The remainder of the differences are hidden in the memregread and memregwrite assembler macros. In soft-draw mode, memregread and memregwrite write to the ShadowXGARegs structure. The pointer used by memregread and memregwrite is set up in the movxga macro, which gets the pointer to the registers from pMemReg. ( pMemReg is set to point to the ShadowXGARegs structure by the SetDrawModeSoft C macro.) The following is an example from the EDDHBBLT.ASM file, from the start of the function SrcDestBlt (SrcDestBlt is changed by way of conditional assembler to eddh_SrcDestBlt or eddf_SrcDestBlt, depending on whether the module is built for hard-draw mode, or for soft- draw mode.):

        pushxga

; get the base address of the hardware registers
        movxga  pXGARegs

; use ebx as a pointer to the destination bit map header 
         mov       ebx ,   AIxfer . pbmhDest 

;   use   edi   to   count   the   number   of   clip   regions 
         movzx     edi ,   word   ptr   AIxfer . cDestClipRects 

;   select   the   destination   map 
         memregwrite       pi _ map _ index _ A ,   SEL _ PIX _ MAP _ A 

In hard-draw mode, pMemReg points to the XGA registers. Most of the other conditional assembler controls minor differences between hardware and software-drawing modes (for example, not waiting for completion of the previous hardware-drawing operation in software-drawing mode).

None of the assembler-language drawing functions are directly called by the XGA driver's C-code functions; they are always called through the pDrawFunctions table. Again, this usually allows the same code to process the setup for either the display or bit-map drawing operations. In the glyph-caching code example, the state of the softDrawInUse flag is preserved, set to FALSE, and then restored. The call to TransferShadowRegisters initiates a BitBlt to copy the glyph into VRAM. TransferShadowRegisters only touches the hardware if the driver is in hard- draw mode, that is, if softDrawInUse is FALSE. The character-caching code maintains identical caches in system memory and off-screen VRAM. Because the bit-map version of the text-drawing code calls the eddt_CacheCharacter( ) routine (the routine shown in the glyph-caching code example), there will be cases in which the eddt_CacheCharacter routine needs to use the hardware to copy the glyph to VRAM, even though it is in soft-draw mode.

In other words, high-level functions in the driver that are in C language, such as eddb_BitBlt(), set the mode for hard-draw mode or soft-draw mode and then call lower level C functions such as PixBltThroughClips(). These functions are relatively generic. Setup values in the ShadowXGARegs structure can be used to initialize the XGA chip set, or they can be used to interpret a bit-map drawing by the eddf_MESS() file.

PixBltThroughClips() (and other level C functions) conducts slightly more setup, calls the TransferShadowRegisters structure, and then calls one of the assembler-language worker functions by way of the pDrawFunctions table. The assembler-language drawing routines are assembled for either hardware drawing or software drawing. The software drawing versions call eddf_MESS() to draw to bit maps, while the hardware-drawing versions write to the XGA command register, which initiates a drawing operation.

The Physical Chunk and Bus-Master Operations

The XGA driver supports a 64KB, 1MB, or 4MB aperture into VRAM. However, the XGA presentation display driver does not use these apertures. Instead, it transfers bit maps from system memory to VRAM using the XGA driver's bus -master capabilities. The XGA driver has a sophisticated memory-management unit, and is capable of dealing with virtual addresses. In OS/2, there is no guarantee that a given page of memory will be resident in memory at any given time. Therefore, to transfer a bit map to VRAM by way of a bus- master, you must first lock it down. Because this is time-consuming, the XGA driver locks down 64KB of system memory and performs any bus-master operations to or from VRAM using this 64KB buffer. This 64KB of memory is referred to as the Phunk (physical chunk).

The Phunk is created in eddb_CreatePhunk (located in the EDDBPHNK.C file). First, eddb_CreatePhunk allocates 64KB of memory. It then executes the FlatLock macro, from the EDDMACRO.H file. The FlatLock macro is an IOCtl to the XGA ring 0 driver. The IOCtl call takes the virtual address of the 64KB buffer, calls the Dev_Hlp VMLock, which locks the buffer into system memory, and then returns the physical address of the 64KB buffer to the caller. VMLock is limited to locking down 64KB of contiguous memory, which explains the size of the Phunk.

The PixBltThroughClipsViaPhunk() function is the primary user of the Phunk and is located in PIXBLT.C. PixBltThroughClipsViaPhunk is called by eddb_ BitBlt() (in EDDNBBLT.C), which is the driver entry point for BitBlt. The XGA driver uses the Phunk whenever the source bit map is in system memory and the destination is the video memory, or whenever the source bit map is in video memory and the destination is in system memory. In other words, if the Blt involves a transfer to or from the video memory to system memory, it goes through the Phunk. PixBltThroughClipsViaPhunk() reduces the transfer into 64KB-size pieces and performs clipping on the destination by enumerating through the clipping rectangles. It then calls whichever low- level blt function has been set up by eddb_BitBlt(). This process is repeated for each 64KB of the bit map.

Cache Management

The XGA presentation display driver caches bit maps, fonts, line-patterns, markers, and dithered patterns for BitBlt in off-screen VRAM. Off-screen VRAM allocation is divided between two files, namely EDDEVRAM.C and EDDNCACH.C. The EDDEVRAM.C file stores various patterns and markers into off-screen memory. The EDDNCACH.C file contains the code for maintaining the font and bit-map caches.

The XGA presentation driver is able to cache small bit maps in off-screen VRAM. It limits the size of these bit maps to 1600 bytes (refer to EDDNCACH.H), which is large enough for a 40 x 40 pel icon at 8 bits-per-pel , but not large enough for a 32 x 32 pel icon at 16 bits-per-pel. After the XGA presentation display driver reserves off-screen video memory for the software cursor, the font cache, patterns, and so forth, it uses what remains for caching small bit maps. The bit map cache is created by the initialise_bm_cache() function. This cache takes the remaining off-screen VRAM, divides it into 1600-byte chunks, and creates an array of structures of type BMCACHE with that number (the remaining off-screen VRAM divided by 1600) of elements. Bit maps either fit in the cache, or they do not fit in the cache. If they fit in the cache, they take the entire 1600 bytes of cache. For example, a 32 x 32 monochrome bit map, if cached, occupies a 1600 byte slot in the cache even though it is only 128 bytes. The only variable is the number of bit maps that may be cached, and that number is determined at system startup.

The following bit maps are cached in PixBltThroughClipsViaPhunk() (PIXBLT.C ):

if ( !fSeamlessActive &&
     !AIxfer.fStretching &&              /* <DCRTURBO> */
     (AIxfer.pbmhSrc->BMPhys == NULL) &&
     (AIxfer.pbmhDest->bit map == NULL) &&
     (ShadowXGARegs.ColCompCond != COLCOMP_SRC_NOT_EQUAL) &&
     !UsePaletteMapping &&
     AIxfer.pbmhSrc != &DrawBitsBMHeader )
{
  if ( AIxfer.pbmhSrc->BMSize <= VRAM_BM_CACHE_SIZE )
  {
    if ( cache_bit map(AIxfer.pbmhSrc) )
    {
       //Caching the bit map may have corrupted some of our Color and Mix
       //Registers.  Restore them before calling PixBltThroughClips().
       TransferShadowRegisters( TSR_COLOUR_MIX );
       PixBltThroughClips();
       return;
    }
  }
}

If cache_bitmap() is able to cache the bit map, PixBltThroughClipsViaPhunk( ) can call PixBltThroughClips because both the source and destination for the BitBlt are in video memory. PixBltThroughClips enumerates through the clipping rectangles (if any), and performs a screen-to-screen BitBlt.

Cache_bit map() always returns TRUE. Cache_bit map does not check the size of the bit map, which is why the code in the previous figure looks for an empty slot in the cache. If it is unable to find one, it calls evicted_ cache_slot(), which deletes a bit map out of the cache. The following is code for evicted_cache_slot():

ULONG evicted_cache_slot(VOID)


   /**********************************************************************/
   /* Evicts a bit map from the cache and returns its slot number for    */
   /* use by a new bit map.                                              */
   /*                                                                    */
   /**********************************************************************/

{

  evict_cached_bit map(next_eviction);

  if ( next_eviction == 0 )
  {
    next_eviction = max_cached_bit maps - 1;
    return(0);
  }
  else
  {
    return(next_eviction--);
  }

} /* evicted_cache_slot */

The eviction scheme uses round-robin scheduling when evicting bit maps from the cache. It is possible that the bit map evicted will be the one just allocated on the previous call. This could lead to a certain amount of cache thrashing.

The font cache packs glyphs together in the font cache, rather than creating a fixed number of fixed-size slots for glyphs. Instead, there are a maximum of 10 fonts that may be cached. At initialization time, an array of FONTCACHEINFO structures is allocated in CreateFontCache() (in the EDDNCACH.C file). FONTCACHEINFO is defined in EDDTYPET.H, and is as follows:

   /*********************************************************************/
   /* Type definition for FontCacheInfo                                  */
   /**********************************************************************/

#define MAX_NUM_CODEPOINTS 256


typedef struct _FONTCACHEINFO { /* fci */
        FOCAMETRICS     fmFontMetrics;
        USHORT          usHashMetrics;
        USHORT          usUsageCount;
        USHORT          usFontID;
        USHORT          usCodePage;
        ULONG

aulCachedCharOffset[MAX_NUM_CODEPOINTS];
#ifdef FULL_ADDRESS
        PVOID           apCharDef[MAX_NUM_CODEPOINTS];
#else /* ndef FULL_ADDRESS */
        USHORT          apCharDef[MAX_NUM_CODEPOINTS];
#endif /* ndef FULL_ADDRESS */


   /**********************************************************************/
   /* Defect 75206. 800 x 600 x 16bit in 1MB VRAM does not leave enough  */
   /* room to cache large AVio fonts in one plane.  For this resolution, */
   /* reduce the number of cached fonts to 8 and allow them to wrap      */
   /* (once) to plane index + 8.  For each character, ausPlaneOffset is  */
   /* set to:                                                            */
   /* 0 - in plane 0 through 7                                           */
   /* 1 - in plane 8 through 15 */ /* -1 - not in 16-bit color, ignore   */
   /**********************************************************************/


#ifdef  _8514
        USHORT ausPlaneOffset[MAX_NUM_CODEPOINTS];
#endif
    } FONTCACHEINFO;

typedef FONTCACHEINFO * PFONTCACHEINFO;

As the driver draws text strings, it determines if the font is already in the cache. If not, it takes an entry out of the array of FONTCACHEINFO structures. It then checks each character in the string to be drawn, and if they are not cached (the entry in the aulCachedCharOffset array for that codepoint is NULL), it puts each character for the string into the cache. If the 64KB cache overflows, the entire cache is flushed, and all of the characters for the string are cached. The details of this process are in the EDDNGCGS.C, EDDHGCHS.ASM, and EDDNCACH.C files.

The 8514/A Driver

Although the XGA is a functional superset of the 8514/A, the devices have the following differences.

/-------------------------------------------------------------\
|8514/A                        |XGA                           |
|------------------------------+------------------------------|
|Drawing engine registers use  |Registers are memory-mapped.  |
|I/O ports                     |                              |
|------------------------------+------------------------------|
|References objects by         |References objects in VRAM by |
|Cartesian coordinates         |address using drawing commands|
|------------------------------+------------------------------|
|VRAM is arranged into bit     |VRAM is not arranged into bit |
|planes                        |planes                        |
\-------------------------------------------------------------/

Because of the XGA driver's bit-map drawing code design, throughout the code there are references to XGA registers that the 8514/A does not possess .

IFDEF _8514

This section highlights the most significant differences between the XGA and the 8514/A 32-bit presentation drivers, especially those that relate to the S3 driver. (The S3 chip is a streamlined 8514/A design with a VGA chip core.)

The 8514/A driver's register set is different from the XGA driver's register set. In the original XGA driver, it was difficult to determine what to change when adapting the driver to another chip because so much of the code was identical for hard-draw and soft-draw modes. For example, if you went into a file such as EDDHBBLT.ASM, and started replacing memregwrite's macro with a particular video chip that was needed, you had to be careful not to break the bit-map drawing code. The EDDHBBLT.ASM file is assembled twice, once for drawing to the display, and once for drawing to bit maps. The bit map drawing code for the 8514/A driver emulates an XGA, while the display code works with the 8514/A hardware. As a result, files such as EDDHBBLT.ASM tend to have the following structure:

IFDEF HARD_DRAW
DoSomething   equ    _eddh_DoSomething  ;do something to the display

ELSE    ;SOFT_DRAW
DoSomething   equ    _eddf_DoSomething  ;do something to a memory bit map

ENDIF

DoSomething     proc near
;       do some generic setup common to both
        memregwrite
        memregread
        memregwrite
;       etc., etc.

IFDEF HARD_DRAW
IFDEF _8514
;       8514/A specific setup
        .
        .
        .
ENDIF   ;_8514
ENDIF   ;HARD_DRAW

;       more setup common to both
        memregwrite
        memregwrite
        memregwrite
        memregwrite
        .
        .
        .
        memregwrite     pixel_op, ...

IFDEF   HARD_DRAW
IFDEF   _8514
        outwq   X1, ax
        outwq   X2, bx
        .
        .
        .
        outwq   CMD_FLAGS, ...  ;do the 8514/A command
ENDIF   ;_8514
ELSE    ;SOFT_DRAW
        saveregs
        call    _eddf_MESS
        restoreregs
ENDIF   ;SOFT_DRAW

        ret
DoSomething     endp

Shadow8514Regs Structure

The 8514/A driver also uses a data structure to hold register values that will be written to the hardware. In the XGA driver, this structure was called ShadowXGARegs. In the 8514/A driver, it is called the Shadow8514Regs structure. The definition for the Shadow8514Regs is located in the XGAADAPT.H file.

typedef struct _MM8514Reg
    {


   /**********************************************************************/
   /* DRAWING CONTROL REGISTERS                                          */
   /**********************************************************************/


       /**************************************************************/
       /* X0 and Y0 are the current position values used as the      */
       /* starting point for all drawing operations.  Most of the    */
       /* drawing ops update this point during executions.  Any      */
       /* attempt to read these values while drawing could result    */
       /* in meaningless data.                                       */
       /**************************************************************/


      volatile USHORT X0;       /* 86e8 r/w */
      volatile USHORT Y0;       /* 82e8 r/w */

       /**************************************************************/
       /* The following two registers are dual purpose registers     */
       /* that are used for both Line drawing and BitBlt.            */
       /*                                                            */
       /* When used during a Blt, X1 and Y1 specify the target       */
       /* rectangle coordinates.                                     */
       /*                                                            */
       /* When used during a Line drawing op, K1 and K2 specify the  */
       /* axial step constant and the diagonal step constant,        */
       /* respectively. These values can be calculated as follows:   */
       /*                                                            */
       /* K1 = 2 * (minor axis delta)                                */
       /* K2 = [2 * (minor axis delta)]                              */
       /*      [2 * (major axis delta)]                              */
       /**************************************************************/

        volatile USHORT  X1;                /*  8ee8   w */
        volatile USHORT  Y1;                /*  8ae8   w */

        volatile USHORT  K1;                /*  8ae8   w */
        volatile USHORT  K2;                /*  8ee8   w */

    /*********************************************************************/
    /* Error Term is used during line drawing.  The error term           */
    /* is calculated as:                                                 */
    /*                                                                   */            */
    /* Err_Term = [2 * (minor axis delta)]
    /*                (major axis delta) - fixup                         */
    /*********************************************************************/



        volatile USHORT Err_Term; /* 92e8 r/w */

    /*********************************************************************/
    /* Note :  LY, the counter part to LX, is accessed through Index 0   */
    /* of the Multifunction Control Register, BEE8.                      */
    /*********************************************************************/


      volatile USHORT LX;                 /* 96e8    w */

    /*********************************************************************/
    /* These two registers are used to pass commands to the Display      */
    /* Processor and to check the status of the command queue.           */
    /*                                                                   */
    /* Commands that can be initiated are:                               */
    /*                                                                   */
    /* 000 No Operation Performed                                        */
    /* 001 Line Draw                                                     */
    /* 010 Fast-Fill Rectangle                                           */
    /* 011 Fill Rectangle Vertically (#1)                                */
    /* 100 Fill Rectangle Vertically (#2)                                */
    /* 101 Draw Line for Area Fill                                       */
    /* 110 Copy Rectangle                                                */
    /* 111 reserved                                                      */
    /*                                                                   */
    /* Before initiating a command, all of the attributes registers      */
    /* necessary for the primitive should be set up first.               */
    /*                                                                   */
    /* The QStatus register indicates whether or not a command is        */
    /* currently being executed and how many of the eight slots in the   */
    /* queue are currently used.                                         */
    /*                                                                   */

    /* Queue State Value Meaning                                         */
    /* ----------------- -------                                         */
    /* 00000000 Queue Empty                                              */
    /* 00000001 7 Entries available                                      */
    /* 00000011 6 Entries available                                      */
    /* 00000111 5 Entries available                                      */
    /* 00001111 4 Entries available                                      */
    /* 00011111 3 Entries available                                      */
    /* 00111111 2 Entries available                                      */
    /* 01111111 1 Entries available                                      */
    /* 11111111 Queue Full                                               */
    /*********************************************************************/

        volatile CMDFLAG Cmd_Flags;         /*  9ae8   w */
        volatile QSTATUS QStatus;           /*  9ae8   r */

    /*********************************************************************/
    /* Attribute Registers                                               */
    /*********************************************************************/

        volatile SSTROKE ShortStroke;       /*  9ee8   w */

        #ifndef   BPP24
        volatile USHORT  Color_0;           /*  a2e8   w */
        volatile USHORT  Color_1;           /*  a6e8   w */

        volatile USHORT  Write_Enable ;        / *    aae8     w   * / 
         volatile   USHORT    Read _ Enable ;         / *    aee8     w   * / 

         volatile   USHORT    Color _ Comp ;          / *    b2e8     w   * / 
         # else 
         volatile   ULONG     Color _ 0 ;              / *    a2e8     w   * / 
         volatile   ULONG     Color _ 1 ;              / *    a6e8     w   * / 

         volatile   ULONG     Write _ Enable ;        / *    aae8     w   * / 
         volatile   ULONG     Read _ Enable ;         / *    aee8     w   * / 

         volatile   ULONG     Color _ Comp ;          / *    b2e8     w   * / 
         # endif 

         volatile   MIX       Function _ 0 ;          / *    b6e8     w   * / 
         volatile   MIX       Function _ 1 ;          / *    bae8     w   * / 

     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 
     / *   The   register   at   BEE8   is   a   multifunction   control   register   for        * / 
     / *   drawing   operations .    The   different   functions   are   differentiated     * / 
     / *   by   an   index   value   in   the   high   four   bits .                              * / 
     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 

         volatile   USHORT    LY ;                   / *    bee8     w   Index   0    * / 
         volatile   USHORT    YMin ;                 / *    bee8     w   Index   1    * / 
         volatile   USHORT    XMin ;                 / *    bee8     w   Index   2    * / 
         volatile   USHORT    YMax ;                 / *    bee8     w   Index   3    * / 
         volatile   USHORT    XMax ;                 / *    bee8     w   Index   4    * / 
         volatile   USHORT    Config ;               / *    bee8     w   Index   5    * / 
         volatile   USHORT    Pattern _ 0 ;           / *    bee8     w   Index   8    * / 
         volatile   USHORT    Pattern _ 1 ;           / *    bee8     w   Index   9    * / 
         volatile   PIXMODE   Mode ;                 / *    bee8     w   Index   A    * / 

     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 
     / *   Color _ 0 _ Wait   is   the   only   mechanism   for   moving   data   to   and   from      * / 
     / *   the   8514 ' s   VRAM .    The   register   is   capable   of   dealing   with   Pixel     * / 
     / *   mode   and   Planar   mode   color   data .    The   type   used   is   determined   by    * / 
     / *   Config   version   of   the   Multifunction   Control   Register ,   BEE8 .         * / 
     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 

         volatile   USHORT    Color _ 0 _ Wait ;        / *    e2e8    r / w   * / 

     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 
     / *   When   read ,   this   register   is   used   to   query   information   about   the     * / 
     / *   graphics   processor .    Information   available   is   whether   or   not . . .     * / 
     / *                                                                           * / 
     / *   1 . )   The   graphics   processor   is   idle .                                    * / 
     / *   2 . )   A   command   was   written   to   a   full   queue .                            * / 
     / *   3 . )   The   Color _ 0 _ Wait   register   was   read   without   any   data   being       * / 
     / *       available   to   read .                                                  * / 
     / *   4 . )   A   write   to   a   pixel   within   the   clipping   rectangle   is   about       * / 
     / *       to   be   made .                                                          * / 
     / *                                                                           * / 
     / *   When   written   to ,   this   register   is   used   to   enable   and / or   reset       * / 
     / *   any   of   the   above   registers . 
     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 

/ /          volatile   STATCTL   Control ;              / *    42e8     w   * / 
/ /          volatile   STATCTL   Status ;               / *    42e8     r   * / 
         volatile   USHORT    Control ;              / *    42e8     w     * / 
         volatile   USHORT    Status ;               / *    42e8     r     * / 

     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 
     / *   The   register   selects   which   4KB   page   of   the   32KB   ROM                  * / 
     / *   on - board   the   IBM   8514 / A   is   mapped   to   memory .    This   only   applies     * / 
     / *   to   IBM *   Micro   Channel *   computers   that   use   the   power - on   self   test .   * / 
     / *   We   should   be   able   to   ignore   this   register   for   other   computers .      * / 
     / *   However ,   we   must   be   careful   not   to   cause   a   conflict   with   VGA   ROMs . * / 
     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 

         volatile   USHORT    Prom _ Page ;           / *    46e8     w   * / 

     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 
     / *   These   two   main   purposes   of   this   register   are   to   set   the   clock       * / 
     / *   speed ,   25 . 175   MHz   or   44 . 9   MHz ,   and   to   enable   or   disable   the         * / 
     / *   VGA   pass - thru   feature   of   the   8514 / A .                                  * / 
     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 

         volatile   MISCIO    Misc _ IO ;              / *    4ae8     w    * / 

     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 
     / *   Start   extra   pixmap   definitions   here .    One   each   for   A , B , C   and   the    * / 
     / *   mask .   The   arrangement   of   these   is   an   exact   image   of   the   real        * / 
     / *   registers .   ( As   a   result ,   the   padding   was   included ) .                  * / 
     / *   Note   that   these   ' shadow '   registers   are   always   in   memory   so          * / 
     / *   need   not   be   declared   as   volatile .                                      * / 
     / * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 

         USHORT    OpDim1 ; 
         USHORT    OpDim2 ; 

         USHORT    MaskXOffset ; 
         USHORT    MaskYOffset ; 

         USHORT    SrcXAddr ; 
         USHORT    SrcYAddr ; 

         USHORT    PatXAddr ; 
         USHORT    PatYAddr ; 

         SHORT      DstXAddr ; 
         SHORT      DstYAddr ; 

         ULONG         PixOp ; 
         BYTE          bFifthStep ;     / *   used   by   software   simulation   only   * / 

         BYTE      pixmapIndexA ; 
         BYTE      bPaddingA ; 
         ULONG     pixmapBaseA ; 
         USHORT    pixmapWidthA ; 
         USHORT    pixmapHeightA ; 
         BYTE      pixmapFormatA ; 
         BYTE      bPaddingA2 ; 

         BYTE      pixmapIndexB ; 
         BYTE      bPaddingB ; 
         ULONG     pixmapBaseB ; 
         USHORT    pixmapWidthB ; 
         USHORT    pixmapHeightB ; 
         BYTE      pixmapFormatB ; 
         BYTE      bPaddingB2 ; 

         BYTE      pixmapIndexC ; 
         BYTE      bPaddingC ; 
         ULONG     pixmapBaseC ; 
         USHORT    pixmapWidthC ; 
         USHORT    pixmapHeightC ; 
         USHORT    pixmapFormatC ; 
         BYTE      bPaddingC2 ; 

         BYTE      pixmapIndexM ; 
         BYTE      bPaddingM ; 
         ULONG     pixmapBaseM ; 
         USHORT    pixmapWidthM ; 
         USHORT    pixmapHeightM ; 
         BYTE      pixmapFormatM ; 
         BYTE      bPaddingM2 ; 


    }   MM8514Reg ; 

typedef   MM8514Reg   FAR   *   pMM8514Reg ; 

The top 3/4 part of this structure corresponds to 8514/A registers. However, immediately after the volatile MISCIO Misc_IOfield, notice the definitions of several XGA registers. These have to exist because of the bit-map drawing code in the module named eddf_MESS(). The shadow registers are named Shadow8514Regs in the 8514/A driver. The following is an example of conditionally compiled code:

       /**************************************************************/
       /* set the foreground and background colors for the blt.      */
       /* These are taken from the target attribute bundle           */
       /* unless colour information was passed in the parameters     */
       /**************************************************************/

#ifndef   _8514
if (ArgOptions & BLTMODE_ATTRS_PRES)
{
    ShadowXGARegs.FgCol = (USHORT)LogToPhyIndex(ArgAttrs->lColor);
    ShadowXGARegs.BgCol = (USHORT)LogToPhyIndex(ArgAttrs->lBackColor);
}
else /* use attribute bundle colours */
{
    ShadowXGARegs.FgCol = (USHORT)pdc->DCIImagColatts.ForeColor;
    ShadowXGARegs.BgCol = (USHORT)pdc->DCIImagColatts.BackColor;
}
#else

       /**************************************************************/
       /* set the foreground and background colors for the blt.      */
       /* These are taken from the target attribute bundle           */
       /* unless color information was passed in the parameters      */
       /**************************************************************/

if (ArgOptions & BLTMODE_ATTRS_PRES)
{
    Shadow8514Regs.Color_1 = LogToPhyIndex(ArgAttrs->lColor);
    Shadow8514Regs.Color_0 = LogToPhyIndex(ArgAttrs->lBackColor);
}
else /* use attribute bundle colours */
{
    Shadow8514Regs.Color_1 = pdc->DCIImagColatts.ForeColor;
    Shadow8514Regs.Color_0 = pdc->DCIImagColatts.BackColor;
}
#endif

In addition to changing the name of the structure, the fields that corresponded closely between the two devices were renamed to match the 8514 /A structure. The 8514/A and XGA support the same binary raster operations, although they are encoded differently. The MESS code understands 8514/A raster operations, except for the line drawing code, which still uses XGA raster operations. The MESS code does not understand 8514/A commands, however. Thus, the 8514/A driver code must set up XGA pixel operations because the MESS code depends on them. Also, parts of the 8514/A hardware- drawing code reads the XGA pel operation that is set up by the higher-level portions of the driver, and also sets appropriate bits in the 8514/A command register. Blt directions for overlapping Bitblts are handled in this manner.

The result of this process is the bit-map drawing code, which should be relatively device-independent, is dependent on both 8514/A and XGA hardware at the same time. The MESS code is dependent on certain fields in the bit- map header that really should be reserved for the hardware-drawing code. In particular, the MESS code assumes that the hw_widthfield (the width of the bit map in hardware) is one less pel than the width of the bit map. The 8514/A and XGA refer to widths and heights in 0-based units. Therefore, 0 means 1, 1 means 2, and so on. Not all drivers work this way.

TransferShadowRegisters

Although much of the C code in the driver references 8514/A or XGA registers in the Shadow8514Regs structure, only a few pieces of code in the driver actually write to 8514 registers. Of these, the function TransferShadowRegisters(), in the HWACCESS.ASM file is one of the most important. The TransferShadowRegisters function copies values from the shadow registers to the hardware. The TransferShadowRegisters function knows which values in the shadow register structure have been altered by relying on the caller to tell it which registers to update. Bits set in the argument to the TransferShadowRegisters function handle which registers are copied from the shadow registers to the hardware.

Unlike the XGA driver, which occasionally sets the bit TSR_PIXELOP (and initiates an XGA drawing operation) the 8514/A driver never initiates a drawing operation by way of the TransferShadowRegisters function. Indeed, most of the time TransferShadowRegisters is called with an argument of TSR_ COLOUR_MIX. This argument sets the 8514/A foreground and background color, the foreground and background raster operation, color compare, hardware pattern, and bit-map format for the source. It also determines whether the source is VRAM, a color register, or data from the pel port. The 8514/A driver also uses the TSR_COORDINATES argument to the TransferShadowRegisters function. This sets up the starting X-Y coordinate for the drawing operation, as well as the extents of the operation.

Bit-Map Addresses and the VRAM Marker

One fundamental difference between the XGA and 8514/A drivers is that the XGA refers to objects in VRAM by their address as a pixmap and the 8514/A refers to them by an X-Y coordinate. Further, monochrome data on the 8514/ A can be stored not only by an X-Y coordinate but by planes as well. For instance, at 8 bits-per-pel, a 20 x 20 area of the display could hold one 20 x 20 8-bit-per-pel bit map, or eight 20 x 20 1-bit-per-pel bit maps.

Another difference between the XGA and 8514/A drivers is that on the XGA display driver, a pixmap may have any pitch at all, while on the 8514/A, the pitch of a rectangle in VRAM is always the same as the length of a scanline. In effect, the 8514/A has only one pixmap that occupies all of VRAM.

Given that the XGA uses memory addresses to refer to objects in VRAM, the 8514/A refers to them by using an artificial address in VRAM, which is created from the X-Y coordinates. It then is marked so it can be distinguished from a system-memory bit map. The address of a bit map in VRAM for the original 8514/A driver is as follows:

        address = 0f0000000h or (y-coord * 1024 + x-coord)

The 0f0000000h is a special VRAM marker. Any of the lower-level routines that can work with either system or VRAM bit maps, look at the bit-map address, and if the high-order nibble is 0fh, then they know that address refers to VRAM. To convert the address back to X-Y coordinates, the calc8514xymacro is called. This macro logically ANDs the address with 0fffffffh, and divides by 1024, which yields an X-Y coordinate.

The S3 driver creates addresses in VRAM out of X-Y coordinates as follows:

        address = 0f0000000h or (y-coord * 65536 + x-coord)

This is a more efficient computation for the assembler-language portions of the driver to perform.

The Phunk

When the XGA driver has to perform a BitBlt from system memory to VRAM, it copies up to 64KB of the source into the Phunk, and then completes a BitBlt from the Phunk to the screen by way of a bus-master. The 8514/A does not have the ability to process bus-master transfers. The 8514/A driver still uses the Phunk, however. For the 8514/A driver, the Phunk is a 64KB memory buffer that is not locked down. The 8514/A driver copies up to 64KB of source data into the Phunk, by way of eddf_MESS(), and then copies from the Phunk to VRAM by way of software through the 8514/A pel port. For the 8514 /A, the major impact of this process on the low-level routines of the driver is that these routines have to deal with a source or destination that is system memory; whereas the XGA low-level routines do not. (Refer to BitBlt, which describes the uses of the Phunk in more detail.)

The S3 Driver

The S3 driver differs from the 8514/A driver in its support of 16- and 24- bit-per-pel modes, multimedia escapes, and other changes that are required because of the design of S3 chips.

Driver Initialization

The Driver DLL loadproc is located in the DYNA32.ASM file. The loadproc is called once, when the driver module is loaded, and then calls only XGA_ DLLInit. Also located in the DYNA32.ASM file is haltproc(), which is a routine that consists of an INT 3. It can be called from C code and may be useful for debugging (although _asm {INT 3} is capable of performing the same function).

XGA_DLLInit saves the driver module handle, and then creates the driver semaphore. The creation of the semaphore occurs in the SEAMLESS.C file, in the SeamlessInitSem() function. The semaphore is a fast, safe-ram semaphore that is used by the driver to serialize access to the display hardware. This semaphore prevents contention between the seamless windows driver and the presentation display driver and between the various threads of GRE that may attempt to simultaneously enter the driver.

Initialization

The first hardware-dependent task in a PM driver is to initialize the video hardware and set it into a graphics mode. This is slightly more complicated with the S3 driver than with the SVGA driver (as an example) because the S3 driver supports multiple resolutions and color depths. The following is the logical sequence of functions in the driver that perform initialization, followed by commentary about them. There is more to initialization of the driver than what is shown below, but most of what is not covered is not hardware-dependent. (Refer to the OS/2 Presentation Device Driver Referencefor further information.)

OS2_PM_DRV_ENABLE() - eddenabl.c EXPORT @200
FillLdb() - Fill Logical Device Block (eddefldb.c)
        if (first_time) {
        FillPdb() - Fill Physical Device Block (eddefpdb.c)
                QueryAndSelectNativeMode() - (eddesres.c)
                        Determine adapter memory size
                        SetObtainableModes() - (modeinfo.c)
                        Get_User_Mode()
                        DMS32CallBack((PFN) SwitchToChosenMode)
                        KlugeReset() -  (hwaccess.asm)
                        CacheManager() - (cacheman.c)
                SwitchToExtendedGraphicsMode() -  (setmode.c)
                        DMS32CallBack((PFN) SwitchToChosenMode)
                        KlugeReset() -  (hwaccess.asm)
                InitialiseVRAM() - (eddevram.c)
                CreateFontCache() - (eddncach.c)
                InitialiseSeamless() - (seamless.c)
        initialise_bm_cache() - (eddncach.c)
        }
        GetVRAMPointer()
        Pass back pointers to driver functions

OS2_PM_DRV_ENABLE() Exported entry, ordinal 200

This function is the main entry point for the driver. It calls one of several functions based on the subfunction that is passed. Two of the most important are subfunctions 1 (Fill Logical Device Block) and 2 (Fill Physical Device Block).

FillLdb() - Fill Logical Device Block

Fill Logical Device Block is called by every process that attaches to the display driver's .DLL. This subfunction's primary responsibility is to perform any per-process initialization, and pass back a list of hooked functions to the GRE.

The first time FillLdb() is called, it then calls FillPdb(), which selects and sets the video mode, and initializes the bit-map cache. After completion of this process, the FillLdb() subfunction calls GetVRAMPointer( ) to obtain a flat pointer to the aperture. GetVRAMPointer calls PMDD.SYS to obtain the pointer. GetVRAMPointer is only valid in the context of the process that called it. This is a problem. GRE is multithreaded, so multiple processes will attach to the driver's .DLL. If a process other than the one that called GetVRAMPointer() attempts to use the pointer to the aperture, the driver will generate an invalid address exception. To solve this problem, each process that attaches to the driver must have the pointer to the aperture made valid in its context. This is achieved via VMGlobalToProcess. Since FillLdb() is called each time a thread attaches to the driver, FillLdb() is a convenient place to call GetVRAMPointer.

The first time the driver is entered, GetVRAMPointer calls PMDD.SYS to allocate a flat pointer to the aperture. On subsequent calls, GetVRAMPointer attaches to the existing pointer, making it valid in that particular process address space.

Finally, FillLdb() passes back a table of hooked functions to the GRE.

FillPdb() - Fill Physical Device Block

FillPdb can be called in two different ways. Initially, it is called by FillLdb(). It is also a subfunction of OS2_PM_DRV_ENABLE, and as such, it is called at other times by the GRE. The device contexts for the display driver do not require separate physical device blocks. The initial call, however, calls QueryAndSelectNativeMode() to determine which video mode to set, and then switches to that mode by way of SwitchToExtendedGraphicsMode( ). After setting the mode, it calls InitialiseVRAM(), which sets up locations in off-screen VRAM for the hardware and software cursor, dithered patterns, the bit-map cache, and the font cache. Next, it calls CreateFontCache(), which sets up the font cache. Finally, it calls InitialiseSeamless to enable the driver's seamless windows capability.

QueryAndSelectNativeMode() - Find the graphics mode selected by user

This function reads the mode that has been selected from OS2.INI, and determines which modes from the asrarray are valid. It then matches the user-selected mode to the modes available in the asr array. The asr array is used by QueryAndSelectNativeMode, as well as by OS2_PM_DRV_ QUERYSCREENRESOLUTIONS(), which is the driver entry point used by static mode set. (See Multiple Resolution Supportfor more details.) The asr is an array of structures of type:

typedef struct _SCREENRESOLUTION {
   ULONG width;
   ULONG height;
   ULONG colors;
   ULONG planes;
   ULONG floptions;
} SCREENRESOLUTION;

QueryAndSelectNativeMode() initially determines the memory size of the S3 adapter. Having done this, it then calls SetObtainableModes(), which reads the SVGADATA.PMI file for the S3 adapter. Then, it sets the DSP_RESOLUTION_ OBTAINABLE (bit 6) of floptions for each resolution in the SCREENRESOLUTION table that is also found in the .PMI file. Next, QueryAndSelectNativeModes( ) calls Get_User_Mode, which reads OS2.INI and looks for a user-selected resolution. If it is unable to find one, QueryAndSelectNativeModes() searches the asr array for a mode marked as the default. In the case of the S3 driver, the video mode is 640 x 480 x 8 bits-per-pel.

At this point, the S3 driver calls the base video handler to set the mode and then calls KlugeReset(), which sets up the drawing engine and clears the display. (The mode is set again in FillPdb.) Next, QueryAndSelectNativeMode() searches the aResTable for a mode that matches the resolution and color depth requested by the user, and the amount of memory available on the card. When it finds a match, it sets the global variable HWResolution, and then calls CacheManager(), which then sets up pointers to hardware and cache maps. (Further information on CacheManager and the hardware and cache maps can be found in Cache Management.)

Multiple Resolution Support

The S3 driver supports multiple resolutions and color depths that are contained in a single driver. To change resolutions, the user selects the resolution from a page in the Settings notebook for the System setup object . (Making a selection is easier than reinstalling new drivers for each resolution or color depth.) The key to this capability is a documented driver entry point at ordinal 202. At 8514_32.def, the ordinal 202 is used by OS2_PM_DRV_QUERYSCREENRESOLUTIONS. After searching, this function is found in the EDDQSRES.C file.

To obtain the resolutions supported by the video driver, exported entry 202 is called by the system's Settings notebook page. This function copies back to the caller the asr[] array created in the EDDESRES.C file. Those entries that have the asr[]floptions flag DSP_RESOLUTION_OBTAINABLE, will be available for a user to select from the Settings notebook. The asr[] array is initialized in SetObtainableModes(), in the MODEINFO.C file, as part of the driver initialization process. When this array is copied back to the caller, the user chooses one of the resolutions given, and upon restarting OS/2, the driver brings up the new resolution.

The exported entry point at ordinal 202 gives a mechanism for the driver to tell the Settings notebook which resolutions it supports. By way of OS2. INI, the Settings notebook can tell the display driver which resolution was selected. Installing the S3 driver adds and modifies a number of keys in OS2.INI. The following keys are added under PM_DISPLAYDRIVERS:

Key Value

IBMS332 IBMS332

CURRENTDRIVER IBMS332

DEFAULTDRIVER IBMS332

The added keys sets the S3 presentation driver DLL to be the current driver , and is the same procedure used for installing the SVGA driver. However, the system's Settings notebook adds an additional key called DEFAULTSYSTEMRESOLUTION. This key has as its value, a data structure of type SCREENRESOLUTION, which corresponds to an entry in the asr[] array. Based on which resolution is chosen, the value of the key is set. Upon initialization, in QueryAndSelectNativeMode, the display driver calls the function Get_User_Mode() (EDDESRES.C). Get_User_Mode reads the DEFAULTSYSTEMRESOLUTION key from OS2.INI, and returns the structure. The DEFAULTSYSTEMRESOLUTION key value gives the driver the display height, width, and color depth that the user has chosen.

Changing the resolution by way of the Settings notebook (namely, editing SYSTEM.INI) is accomplished by some keys in OS2.INI, so that the correct WINOS/2* drivers are installed. The following is a portion of S3.DSP (the dspinstl installation script for the S3 driver):

OS2.INI
PM_DISPLAYDRIVERS RESOLUTION_CHANGED 1
WIN_RES_640x480x16     WIN_RES_SET    WIN_RES_S3_0
WIN_RES_640x480x256    WIN_RES_SET    WIN_RES_S3_1
WIN_RES_640x480x65536  WIN_RES_SET    WIN_RES_S3_2
WIN_RES_800x600x256    WIN_RES_SET    WIN_RES_S3_3
WIN_RES_800x600x65536  WIN_RES_SET    WIN_RES_S3_4
WIN_RES_1024x768x256   WIN_RES_SET    WIN_RES_S3_5
WIN_RES_1024x768x65536 WIN_RES_SET    WIN_RES_S3_6
WIN_RES_1280x1024x256  WIN_RES_SET    WIN_RES_S3_7
WIN_RES_640x480x16777216  WIN_RES_SET    WIN_RES_S3_8
WIN_RES_S3_0   1  "system.ini boot sdisplay.drv swinvga.drv"
WIN_RES_S3_0   2  "system.ini boot display.drv vga.drv"
WIN_RES_S3_0   3  "system.ini boot fonts.fon vgasys.fon"
WIN_RES_S3_0   4  "system.ini boot fixedfon.fon vgafix.fon"
WIN_RES_S3_0   5  "system.ini boot oemfonts.fon vgaoem.fon"
WIN_RES_S3_0   6  "win.ini fonts \"Symbol %ANYSTRING%\"
WIN_RES_S3_0   7  "win.ini fonts \"Helv %ANYSTRING%\"
WIN_RES_S3_0   8  "win.ini fonts \"Tms Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0     9    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0    10    " win . ini   fonts   \ " MS * *   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0    11    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0    12    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0    13    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ " 
WIN _ RES _ S3 _ 0    14    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( VGA   res ) \ " 
WIN _ RES _ S3 _ 0    15    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ " 
WIN _ RES _ S3 _ 0    16    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ " 
WIN _ RES _ S3 _ 0    17    " win . ini   fonts   \ " Small   Fonts   ( VGA   res ) \ " 

When the resolution is changed, the RESOLUTION_CHANGED key is added by the Settings notebook to OS2.INI. When the presentation display driver is restarted, this flag in OS2.INI is checked. If it is 1, OS/2 examines the WIN_RES_xxx_yyy_bbb key that corresponds to the value of DEFAULTSYSTEMRESOLUTION. Each of these strings in OS2.INI have a single key called WIN_RES_SET, with a value that gives the name of another string in OS2.INI. For example, WIN_RES_S3_0 has 17 keys. Key number 1 installs the line "sdisplay=swinvga.drv" in the "boot" section of SYSTEM.INI. OS/2 iterates through these keys, and edits the appropriate sections of SYSTEM. INI or WIN.INI, based on the value of each key.

Although the S3 driver does not look at the WINOS/2 .INI files, it is possible to use the WIN_RES_XXX values to create the entries for the WIN. INI or SYSTEM.INI that are queried by the WINOS/2 driver during its initialization. For example:

WIN_RES_S3_0   18 "system.ini s3 width 640"
WIN_RES_S3_0   19 "system.ini s3 height 480"
WIN_RES_S3_0   20 "system.ini s3 bpp 16"
WIN_RES_S3_0   20 "system.ini s3 dpi 96"

Adding the above entries to the fragment of S3.DSP (S3.DSP (Sample File for Installation and Configuration)) creates the following entry in SYSTEM.INI when 640 x 480 16-color mode is selected:

[s3]
width=640
height=480
bpp=16
dpi=96

When changing the dspinstl script, refer to S3.DSP (Sample File for Installation and Configuration)for information.

Obtaining Pointers to Video Memory

The PMDD.SYS module provides an IOCtl that takes a physical address and returns a linear address in the address space of the calling process. The presentation display driver calling routine can obtain a linear address from a physical address by calling GetVRAMPointer and is implemented in the S3 driver, which is found in the EDDEFLDB.C file. The following is the source code:

ULONG   flVRAMFirst = 0;
ULONG   pVRAM = 0xffffffff;
HFILE    hSVGA;
ULONG    ulAction;
CHAR     szSQ[32] = "\\DEV\\SINGLEQ$";

/***********************************************************************
*
* FUNCTION NAME = GetVRAMPointer
*
* DESCRIPTION = Uses an IOCtl to get a pointer to VRAM.
*
* INPUT       =
* OUTPUT      =
*
* RETURN-NORMAL =
* RETURN-ERROR  =
*
/***********************************************************************

ULONG GetVRAMPointer ( ULONG ulAddr , ULONG ulSize , PULONG
pulFirst , PULONG  ppVRAM )
{

SCRNTX   scrnTx;
SCRNRX   scrnRx;
BOOL     fAttach;
USHORT   usAction;

   if (DosOpen( szSQ , &hSVGA , &ulAction , 0, 0, 1, 0x00c0, 0))
   {
      goto   getvram_exit;
   }

   scrnTx.stx_Address = ulAddr;
   scrnTx.stx_Size = ulSize;
   scrnTx.stx_flFlag = 0;

   if ( !*pulFirst ) {
      fAttach = 0;
      usAction = 0x007e;
      *pulFirst = 1;
   }
   else
   {
      usAction = 0x007f;
      scrnTx.stx_Address = *ppVRAM;
      fAttach = 1;
   }

   if ( !DosDevIOCtl( hSVGA, 3, usAction, &scrnTx, sizeof(SCRNTX),
                     0, &scrnRx, sizeof(SCRNRX), 0) )
   {
      if ( fAttach == 0)
      {
         *ppVRAM = scrnRx.srx_ScrnPtr;
      }
   }

   DosClose( hSVGA );

getvram_exit:
   return( 1L );

}

The preceding code is designed to be called only once upon initialization of the driver and during the once-per-subsequent process that needs the linear address. The linear address returned on the first invocation of the GetVRAMPointer is valid only in the process that called GetVRAMPointer. GRE is multithreaded, so multiple processes use the S3 driver DLL. Each of these processes must have the linear address added to their page tables.

The PMDD.SYS module uses the DevHlp_VMALLOC to obtain the linear address to the physical memory. The pointer returned by the above code is usable anywhere in the driver except in MoveCursor32. (The pointer is unusable in MoveCursor32 because it is called at interrupt time. The pointer returned by the PMDD.SYS module exists only within the context of any process that has attached to it. The ring 0 code that calls MoveCursor32 does not have the pointer in its address space.)

To get a pointer to the aperture or memory-mapped registers that is usable from MoveCursor32, use DevHlp_PhysToGDTSel. (Refer to the XGA ring 0 driver for an example.) The function GetInstanceGDT in the xgaring0.asm file gives an example of using PhysToGDTSel to get a selector:offset pointer to the XGA driver's memory-mapped registers. If you need a flat pointer that can be used by MoveCursor32, implement your own ring 0 physical device driver that uses VMALLOC to create a linear mapping in the global, system linear space. To use it, you would have to guarantee that MoveCursor32 ran at ring 2, because ring 3 processes cannot access memory in the system space. (OS/2 reserves linear addresses above 512MB for use by operating system.)

It is also possible to get a flat pointer to the video aperture by way of an IOCtl to the SCREEN01.SYS file. The source code to the SCREEN01.SYS file is in the IBM Device Driver Source Kit for OS/2. The code to get the flat pointer is GetLinearAccess, in \ DDK\SCR_S3\DEV\SCREENDD\SVGAROUT.ASM. The device name used to access SCREEN01.SYS is "SCREEN$". The IOCtl number is 0xb. The packet used for this IOCtl is the following:

GetLinear_Packet        STRUC
        PacketLength    DD     0H       ; total size of data packet
        PhysicalAddress DD     0H       ; Physical address of aperture
        ApertureSize    DD     0H       ; Size of aperture
        LinearAddress   DD     0H       ; Linear address of
aperture (
GetLinear_Packet        ENDS

The location of the video aperture is the PhysicalAddress. ApertureSize is the size (in bytes) of the video aperture. The LinearAddressfield returns the linear address of the device. The address returned will be valid only within the context of the process that called the IOCtl. Also, it is not guaranteed that this IOCtl will return the same linear address for each process. Consequently, if you use this IOCtl, you must keep track of which pointer belongs to which process that is using the driver. (MATROX.C in the S3 driver has an example of how to do this).

The XGA ring 0 driver also has an IOCtl for obtaining a flat pointer to video memory. (In this case, the XGA 1MB aperture.) The function flat_ access, can be found in the file \..\..\XGASYS20\XGARING0.ASM. This function calls VMALLOC to obtain a flat pointer to the XGA aperture. The IOCtl function code for flat_access is 0x14. An example of how to call this particular IOCtl can be found in the S3 driver in MATROX.C.

For accessing flat data at ring 3, use selector 53 hex. (Accessing data at ring 3 is always true for code that is not running as part of the system at ring 0.) If a protection fault in the driver appears (Trap d), check the segment register being used to access the data. A segment register other than 0x53 could be part of the cause of the trap.

BitBlt

Unlike the SVGA driver, the S3 driver does not compile BitBlts onto the stack. Instead, eddb_BitBlt analyzes the raster operator and various source and destination options, and breaks the blt down into simpler cases. Each of these cases can take advantage of the graphics accelerator hardware . All BitBlts are broken down into combinations of the following four cases:

�eddh_SrcDestBlt

�eddh_PatDestBlt

�eddh_DestOnlyBlt

�Software BitBlt by way of eddf_MESS

Any BitBlt to the display ultimately ends up in one of the cases, and they are among the first pieces of code that must be modified when this driver is ported to a different chip set. These functions are located in the EDDHBBLT.ASM file. They handle the first three cases that an S3 chip can accelerate in hardware: a source, destination, and a raster operation; a pattern, destination, and a raster operation; or a destination-only raster operation.

eddh_SrcDestBlt (EDDHBBLT.ASM)

The eddh_SrcDestBlt function handles BitBlts involving some source with the display as a destination. It iterates through multiple clip rectangles, copying from the source to the display. The source may be either monochrome or a bit map of the same color depth as the display. The source may be a system-memory bit map, a portion of the visible display (for example, a scroll box), or in VRAM in the bit-map cache. The following is a pseudocode version of eddh_SrcDestBlt:

eddh_SrcDestBlt:
//this first part is mostly for the software drawing version of this
//routine, eddf_SrcDestBlt, although some of the hardware-drawing code
//eventually reads details from the various shadows of the pixmaps.

get the destination address
set pixmapA = destination bit map parameters
if expanding from monochrome source to color
        set pixmapC = source bit map parameters
else
        set pixmapB = source bit map parameters

do
        dec     CountOfClipRects
        if the blt intersects the clipping rectangle
                set pattern map
                set source map
                set destination map
                set pixel op
                if source has VRAM marker
                        //source is in VRAM
                        call SrcSpecialist
                else
                        //source is in system memory
                        call SoftSrcSpecialist
        get next clipping rectangle
while CountOfClipRects > 0

The eddh_SrcDestBlt function rolls through the clipping rectangles passed in from the GRE, and for each rectangle (if the blt intersects it), the eddh_SrcDestBlt function calls either SrcSpecialist, if the source is the display, or SoftSrcSpecialist, if the source is a memory bit map. SrcSpecialist takes the arguments set up by eddh_SrcDestBlt, and performs a VRAM-to-VRAM blt. The arguments it takes are passed in XGA-style in the Shadow8514Regs. The following is an example:

; use ebx as a pointer to the destination bit-map header
        mov     ebx, AIxfer.pbmhDest

; convert destination bit map address to x and y for 8514
hardware
        memregread      eax,dest_map
        mov     x_dst,ax
        ror     eax,16
        mov     y_dst,ax
        calc8514xy  [ebx].bit map_address
        add     x_dst,dx
        add     y_dst,ax

In this case, the X-Y coordinates of the destination are passed in the dest _map. Because the destination is the display, the bit map_addressfield of the AIxfer is set up with a dummy address in VRAM (this is why calc8514xymacro is used). Likewise, the source X-Y coordinates are passed in the source_map and AIxfer.pbmhSrc. AIxfer is a large union used throughout the driver to pass parameters from the high-level portions of the driver down to the various worker routines. For BitBlt, it is defined as type BITBLTPB , which is defined in the EDDHTYPE.H module. AIxfer holds pointers to the source and destination bit-map headers, the area of display affected by the blt (stored as rectangles), and parameters used by stretch blt.

Essentially, everything gets set up just as if the operation were going to occur on an XGA, and then the lowest level routines translate the parameters into a format appropriate to the display hardware.

SrcSpecialist handles operations such as scrolling, copying the contents of a window from one portion of the display to another, and copying bit maps out of the off-screen VRAM cache onto the display. It controls both color and monochrome bit maps, although this is not obvious from reading the code , because of idiosyncrasies of the 8514/A adapter. The 8514/A, and the S3 chip, treat monochrome data in VRAM as a rectangle of pels that occupies only a single plane. Only a few registers distinguish between blting a color or monochrome bit map from VRAM-to-VRAM. Most of these operations are hidden in TransferShadowRegisters. Many graphics accelerator chip sets do not support monochrome expansion from VRAM-to-VRAM at all. One of the most common uses of monochrome data is a mask for icons that are put on the display. When an icon is displayed on the desktop, the first operation that occurs is a monochrome mask that is ANDed onto the display. This operation creates a black hole on the desktop in the shape of the icon. The color portion of the icon bit map is then ORed in over this hole.

In the S3 driver, both the mask and the bit map will be in the cache. If your hardware does not support monochrome expansion from VRAM-to-VRAM, then make the following change to PixBltThroughClipsViaPhunk() in pixblt.c:

original, about line 306:

#ifdef BPP24
if ( !pHWMap->vertical_bmaps ) {
#endif
 if ( AIxfer.pbmhSrc->Info.Width <= VRAM_BM_CACHE_HOR_SIZE &&
      AIxfer.pbmhSrc->Info.Height <= VRAM_BM_CACHE_VERT_SIZE )
 #endif
 {
   if ( cache_bit map(AIxfer.pbmhSrc) )
   {
      // Caching the bit map may have corrupted some of the Color and Mix
      // Registers.  Restore them before calling PixBltThroughClips().
           TransferShadowRegisters( TSR_COLOUR_MIX );
           PixBltThroughClips();
           return;
   }
 }


modified, for no cached monochrome maps:

#ifdef BPP24
if ( !pHWMap->vertical_bmaps ) {
#endif
 if ( AIxfer.pbmhSrc->Info.Width <= VRAM_BM_CACHE_HOR_SIZE &&
      AIxfer.pbmhSrc->Info.Height <= VRAM_BM_CACHE_VERT_SIZE &&
      AIxfer.pbmhSrc->Info.BitCount != 1)
 #endif
 {
   if ( cache_bit map(AIxfer.pbmhSrc) )
   {
      // Caching the bit map may have corrupted some of the Color and Mix
      // Registers.  Restore them before calling PixBltThroughClips().
           TransferShadowRegisters( TSR_COLOUR_MIX );
           PixBltThroughClips();
           return;
   }
 }

Making this change to pixblt.c will prevent caching of monochrome bit maps and will be passed to SoftSrcSpecialist. SoftSrcSpecialist copies bit maps to the display in a variety of formats. When transferring color bit maps to the display, SoftSrcSpecialist uses the S3 pel-transfer register. At 8 bits-per-pel, it uses a memory-mapped version of the register for better performance. At 16 bits-per-pel, it swaps the bytes in each pel prior to writing the pel to the pel-transfer register. This is unnecessary, because the order of bytes written via the pixel transfer register can be swapped in hardware by simply setting a bit in one of the S3 registers. Thus, it is the extra work the driver is doing when it swaps bytes that is unnecessary. For further information, see 16-Bit-Per-Pel Support.) For monochrome data at 8-or 16-bits-per-pel, SoftSrcSpecialist copies the monochrome bit map through the pel transfer register. This is easier on the S3 chip than on the 8514/A as the S3 chip requires no special alignment of monochrome data. The drawing engine of the 86C80X and S3 Vision chips does not directly support packed 24 bit-color. Therefore, when expanding a monochrome bit map at 24-bits-per-pel, it calls Copy24MonoMixToVRAM, in HWACCESS.ASM. This routine processes monochrome expansion to 24-bit-color expansion in software by way of the S3 chip's aperture into video memory.

eddh_PatDestBlt (EDDHBBLT.ASM)

The eddh_PatDestBlt function handles a BitBlt of a pattern onto the display . Structurally, it is very similar to eddh_SrcDestBlt in that it enumerates through the clipping regions passed to it, and for each rectangle that the operation intersects, it calls one of two routines: PatDestBltColor or PatDestBlt1To8. PatDestBltColor performs patblts where the pattern is taken from a color bit map. The most common color pattern blt is the 2x2 dither used to paint the desktop in 8-bit-per-pel modes. Even portions of windows that appear to be white are, in fact, dithered. The pattern bit map may need to be rotated to align with the destination. If this is the case, PatDestBltColor builds a rotated copy of the pattern in the Phunk. When built, the pattern is copied into off-screen VRAM. The pattern is then tiled across the destination with successive hardware blts. In the case of a pattern copy, the first row of the destination is built, and then used as the source for the successive blts. This operation could be performed more efficiently on S3 chips by detecting patterns that are up to 2x2, 4x4, or 8x8, putting them in off-screen VRAM, and performing blts with them with a single S3 pattern-blt command.

PatDestBlt1To8 handles monochrome patterns. It calls either PattBlt24, for the 24 bpp case, PattBlt1x8, or PattBlt8x8. PattBlt1x8 is a special case routine that handles 1 high by 8 wide monochrome patterns. This special case routine is one of the few pattern blts that the original 8514/A could perform in a single operation. The S3 driver performs this operation as a monochrome expansion through the pel port. If your hardware does not handle 1x8 monochrome blts, do not implement this special case routine.

PattBlt8x8 controls the more general case of 8x8 monochrome pattern. The S3 chip can perform this as a single-blt operation. For the S3 driver, the PattBlt8x8 aligns the pattern, copies it into off-screen VRAM, and then issues a command to the S3 chip to do the pattern blt.

Because the various S3 chips do not directly support packed 24-bit-per-pel modes, PattBlt24 processes more than PattBlt8x8. It expands the pattern into off-screen memory and then repeatedly blts this off-screen pattern onto the display using a VRAM-to-VRAM copy blt. After it has filled a single row of the pattern, it then repeatedly blts that entire row, doubling the height of the source each time. For example, if the pattern is 1 pel high by 8 wide, PattBlt24 first builds a row of the pattern 1 pel high. It then copies that row to the second row. Next, it copies both the first and second rows to the third and fourth rows. It then copies the first four rows to the next four. It then continues to double until it has filled the destination rectangle.

eddh_DestOnlyBlt (EDDHBBLT.ASM)

This routine follows the pattern set by eddh_SrcDestBlt and eddh_PatDestBlt . Destination invert raster operations are translated into source invert raster operations in EDDNBBLT.C. This translation might have to be changed on your hardware. Almost all hardware blt engines support inversion of the destination, but many won't invert the source, if the source and destination are identical. The raster operation should be "not destination. " Instead, it is mapped to "not source" and the source and destination are created to be the same.

BitBlt - The Top Level Routines

There is a certain amount of interaction and hardware dependence in the bit -map cache and the three blt routines in EDDHBBLT.ASM. This interaction is controlled by the various routines in BitBlt.

eddb_BitBlt (EDDNBBLT.C)

This is the entry point in the driver for BitBlt. It handles the device- independent portions of BitBlt. It validates parameters, transforms coordinates, and handles error logging. When it has completed some setup, eddb_BitBlt looks at the raster operation and splits into one of several cases, such as a three-way raster operation, a raster operation involving the source and destination, a raster operation involving a pattern and the destination, or a raster operation involving the destination-only. The following is a simplified pseudocode for eddb_BitBlt:

eddb_BitBlt()
// check for stretch blt
if not COM_DEVICE
    if ArgCount == 4 and src_coords != dst_coords
        stretch_return_code = IsValidStretchRequest()

        //can the driver handle the stretch blt?
        if stretch_return_code != OK
            Perform call-back to the engine to do stretchblt

// at this point, eddb_BitBlt checks for a valid rop, and checks to see
// if the request is for correlation or drawing, etc.

if COM_CORRELATE
    if not eddg_ClipPickWindow()        // get correlation rectangles
        goto BITBLT_EXIT                //error!

//if the PM desktop is in the background and the destination is the
//display, disable drawing
if fXGADead and Destination is display
    COMMANDBITS = COMMANDBITS and not(COM_DRAW)

//convert target coordinates to device coordinates
TransformCoordinates()

//Examine the rop and determine which case it falls into

if source_is_required(rop)
    goto SOURCE_3WAY_COMMON
else
    goto PAT_DSTONLY_COMMON

SOURCE_3WAY_COMMON:
//handle all blts with a source, including blts involving source,
//pattern, and destination
if not(Stretching) //no need to setup if this is a stretchblt
    if source is a bit map
        convert handle to pointer and assign to AIxfer.pbmhSrc
    else //source is a device context handle
        convert handle to pointer to DC and assign to pdcSrc
        //get a pointer to the bit map defining the device
        AIxfer.pbmhsrc = pdcSrc->DCISelListEntry

Build rectangles defining the source and destination

//correlation involves determining if a pick is inside the area
//of the drawing operation.
if COM_CORRELATE
        perform correlation

//see if we need to draw
if not(COM_DRAW)
        goto BITBLT_EXIT

Calculate BitBlt dimensions and store in AIxfer.rcsTrg and
AIxfer.rcsSrc

if software_cursor
    calculate exclusion rectangle
    eddm_ExcludeCursor()

if pattern(rop)
    goto THREE_WAY_BLT    //there is a pattern involved
else
    goto SRC_DST_BLT      //no pattern involved

SRC_DST_BLT:
if palette mapping is required
    create palette mapping
    if the source is cached
        evict source bit map from the cache

//is the destination the display?
if AIxfer.pbmhDest == DirectListEntry
    SetDrawModeHard    //drawing to the display
else
    SetDrawModeSoft    //drawing to a bit map

//check for monochrome expansion
if mono(source) and not(mono(destination))
    //source is 1 bpp and destination isn't, so this is a monochrome
    //expansion blt

    setup foreground and background colors in Shadow8514Regs
    if destination is cached
        evict destination from the cache

else
    //both source and destination are in the same format
    //or source is color and destination is monochrome
    if source and destination are the same bit map
        if source and destination overlap
            determine direction in which to blt
            note that clipping rectangles need to be re-ordered
            store blt directions in pixelop
    else if source is color and destination is monochrome
        AIxfer.pbmhSrc = convert_colour_to_mono

Set source and mix in Shadow8514Regs
TransferShadowRegisters
SPad.BltFunction = either eddf_SrcDestBlt or eddh_SrcDestBlt

if src and dest are system memory or src and dest are
display
    PixBltThroughClips
else
    PixBltThroughClipsViaPhunk

if destination is cached
    evict destination from the cache

goto BITBLT_EXIT

THREE_WAY_BLT:
//source, pattern, and destination are involved in this rop

Save a copy of AIxfer.pbmhDest
Save a copy of AIxfer.pbmhSrc
Setup the pattern
Save a copy of the source & target rectangles

if source bit map == destination bit map
    if source and destination overlap
        determine order for clipping regions
        determine blt directions
else if source is monochrome and destination is color
    get foreground and background colors for mono bit map
else if destination is monochrome and source is color
    source = convert_colour_to_mono(source)

if bit 7 of the rop is set
    rop = 0ffh   -   rop 
     calculate   starting   blt   instruction 
     add   trailing   " not "   to   last   blt   instruction 
else 
     get   pointer   to   starting   instruction 

if   Blt3WayBuffer [ rop ] . CreateNew   = =   TRUE 
     allocate   a   temporary   bit   map   to   hold   intermediate   results 

instruction _ count   =   Blt3WayBuffer [ rop ] . Size 

while   ( instruction _ count   >   0 ) 
     if   Instruction - > Destination   = =   BT _ DEST 
         fThreeWayBlt   =   False      / / clip   the   destination 
         set   up   destination   map   in   AIxfer 
     else   if   Instruction - > Destination   = =   BT _ WORK 
         fThreeWayBlt   =   True       / / don ' t   clip   the   destination 
         set   up   work   map   in   AIxfer 

     if   Instruction - > Source   = =   BT _ PAT 
         set   up   the   pattern   in   AIxfer 
         if   destination   is   the   display 
              SetDrawModeHard ( ) 
         else 
              SetDrawModeSoft ( ) 
        else 
         if   Instruction - > Source   = =   BT _ DEST 
              set   AIxfer   source   to   destination   bit   map 
         else   if   Instruction - > Source   = =   BT _ WORK 
              set   AIxfer   source   to   temporary   bit   map 
         else   if   Instruction - > Source   = =   BT _ SRC 
              set   AIxfer   source   to   actual   source   bit   map 
         else 
              no   source ,   so   do   nothing ! 

     if   destination   is   the   display 
         SetDrawModeHard ( ) 
     else 
         SetDrawModeSoft ( ) 

     set   up   palette   mapping   if   needed 

     set   up   foreground   and   background   colors   and   mixes   based   on   if 
     the   blt   is   expanding   from   monochrome   to   color . 

     TransferShadowRegisters ( ) 

     if   src   and   dest   are   system   memory   or   src   and   dest   are   display 
         PixBltThroughClips 
     else 
         PixBltThroughClipsViaPhunk 

     Instruction   =   next ( Instruction ) 
     instruction _ count   =   instruction _ count   -   1 

fThreeWayWorkBlt   =   False 

if   the   original   rop   > =   0x80 
     remove   trailing   " not "   from   last   Instruction 

goto   BITBLT _ EXIT 

PAT _ DSTONLY _ COMMON : 
  / / more   of   the   same . . . . 

PAT _ DST _ BLT : 
/ / not   shown   lest   the   pseudocode   become   as   complicated   as   the 
original 

DST _ ONLY _ BLT : 
/ / ditto 


BITBLT _ EXIT : 
/ / end   of   BitBlt 

Blting from source to destination involves several cases. First, there is the possibility that a palette mapping will be needed. (Palette mapping is necessary when the source and destination use differing palettes. Refer to eddb_CreatePalMapping in the EDDBPHNK.C file for details.) If the source is monochrome and the destination is not, the color_0and Shadow8514Regs.color _1fields must be set up. Finally, if both the source and destination are in system memory, or both are in VRAM, PixBltThroughClips is called to perform the blt. Otherwise, PixBltThroughClipsViaPhunk is called. The Phunk is always used when copying to or from system memory to VRAM. Using bus mastering via the Phunk was an optimization in the XGA driver, because copying to or from the Phunk to VRAM was fast. For the S3 driver, the Phunk is still useful if the source must be changed to a different format or if it must be stretched.

THREE_WAY_BLT involves a raster operation, a pattern, a source, and a destination. The key to understanding three-way blts is that they are interpreted. The blt interpreter breaks the raster operation down into a series of two-way blt operations that can be performed in either hardware or software. The following are examples of data structures:

// eddbtypt.h

typedef struct
{
    BYTE    Source;
    BYTE    Destination;
    BYTE    Mix;
    SHORT   BltFunction ;
} BltInst;
typedef BltInst NEAR * pBltInst;

typedef struct
{
    BYTE       CreateNew;
    BYTE       Size;
    pBltInst   Instruction;
} BltBuffEntry;
typedef BltBuffEntry NEAR * pBltBuffEntry;

In the EDDBDATA.C file, there is a large array called Blt3WayInsts, which is an array of BltInst structures. Each BltInst in the array is one step in the construction of a three-way BitBlt. BltInst.Source lists the source for this stage of the blt. Likewise, BltInst.Destination is the destination. BltInst.Source can have the following values:

/-------------------------------\
|BT_DEST     |0    |Use the     |
|            |     |destination |
|------------+-----+------------|
|BT_WORK     |1    |Use the     |
|            |     |temporary   |
|            |     |work buffer |
|------------+-----+------------|
|BT_SRC      |2    |Use the     |
|            |     |source      |
|------------+-----+------------|
|BT_PAT      |3    |Use the     |
|            |     |pattern     |
|------------+-----+------------|
|BT_NONE     |4    |Use none or |
|            |     |the same as |
|            |     |last time   |
\-------------------------------/

BltInst.Destination can have as a value of either BT_DEST, BT_WORK, or BT_ SRC. (BT_SRC implies no destination or specifies the use of the same destination as last time.)

The Mixfield holds the hardware mix to use (XOR, OR, AND, COPY, and so forth), and the BltFunctionfield holds an index into the pDrawFunctionsTable. BltFunction selects which of three types of blt this instruction is to perform, such as a blt with a source and destination, a pattern blt, or a destination-only blt. For example, the following entry uses the source as the source for this step, uses the destination as the destination, uses a raster operation of (not source) and (not destination), and uses either eddf_SrcDestBlt or eddh_SrcDestBlt to perform this step. In effect, each entry in Blt3WayInsts is an instruction, with BltFunction and Mix forming the operation code.

BT_SRC, BT_DEST, HWMIX_NOTSOURCE_AND_NOTDEST,
index_SrcDestBlt,

Blt3WayBuffer is composed of structures of type BltBuffEntry. The CreateNewfield of this structure is a Boolean value. When it is set to TRUE, a temporary buffer must be created for use during the blt. The Sizefield is the number of instructions it will take to perform this blt, (each instruction is a single entry in Blt3WayInsts), and Instruction field is a pointer to the first entry in Blt3WayInsts used for this blt.

Only raster operations from 0 to 7f hex are encoded this way. If the raster operation for the blt is greater than 80 hex, it is changed to the corresponding raster operation that is less than 80 hex, and a "not" operation is added to the final instruction for the blt. Performing the blt sets up the source and destination bit maps in AIxfer, and then calls either PixBltThroughClipsViaPhunk or PixBltThroughClips. When this has been completed, the next instruction in the blt is taken, and the cycle is repeated until no instructions remain.

The fThreeWayWorkBlt flag is true when the temporary bit map is being used as the destination for the blt. This flag exists so the PixBlt routines will not clip the work bit map against any clipping rectangles. It is necessary to avoid clipping the work bit map because it is an intermediate result, while the clipping rectangles refer to the destination bit map.

The pseudocode for pattern blts and destination-only blts generally follows a similar pattern to blts that involve a source and destination.

PixBltThroughClipsViaPhunk (PIXBLT.C) and PixBltThroughClips (PIXBLT.C)

PixBltThroughClipsViaPhunk and PixBltThroughClips have similar functions. Both enumerate through the clipping rectangles passed in from the graphics engine (GRE), batch up a number of them, and then call the blt function specified in SPad.BltFunction with those rectangles. This process is repeated until all clipping rectangles have been exhausted. The two differ in that PixBltThroughClips is designed to deal with bit maps that are either both in VRAM, or both in system memory. PixBltThroughClipsViaPhunk is used when the source is in system memory and the destination is in video memory. PixBltThroughClipsViaPhunk is also used when the source is in video memory and the destination is system memory. If the source and destination are both in system memory, only PixBltThroughClips is called. Likewise, if the source and destination of the blt are in video memory, only PixBltThroughClips needs to be called. There is one special case. In PixbltThroughClipsViaPhunk, if the source is in system memory and the destination is video memory, it is possible that the source might fit into bit map cache. If the source will fit, PixBltThroughClipsViaPhunk copies the source into the cache. Once the source has been cached, both the source and the destination are in video memory. This means that PixBltThroughClipsViaPhunk can call PixBltThroughClips to perform the blt.

If the source bit map will not fit in the cache, PixBltThroughClipsViaPhunk copies the source bit map into the Phunk in 64KB chunks. It calls CopyChunkToPhunkForPixBltSource to put the source into the Phunk. CopyChunkToPhunkForPixBltSource uses eddf_MESS to copy a portion of the source bit map into the Phunk. For the XGA, this allowed the bit map to be blted to VRAM by way of the bus-master. For the S3 chip, the Phunk is just another 64KB of system memory. PixBltThroughClipsViaPhunk is used when the source is in system memory and the destination is in video memory. PixBltThroughClipsViaPhunk is also used when the source is in video memory and the destination is system memory. If the source and destination are both in system memory, only PixBltThroughClips is called. Likewise, if the source and destination of the blt are in video memory, only PixBltThroughClips needs to be called. There is one special case. In PixbltThroughClipsViaPhunk, if the source is in system memory and the destination is video memory, it is possible that the source might fit into bit map cache. If the source will fit, PixBltThroughClipsViaPhunk copies the source into the cache. Once the source has been cached, both the source and the destination are in video memory. This means that PixBltThroughClipsViaPhunk can call PixBltThroughClips to perform the blt.

eddb_BltThroughClips and eddb_DrawThroughClips (EDDNBBLT.C)

These two routines are in EDDNBBLT.C, but they are not actually a part of BitBlt. Instead, they are called by other parts of the driver that need to enumerate through the clip regions, while performing a drawing operation. Both take as an argument a pointer to a function. This function is one of the worker functions in the pDrawFunctions table. These are simplified, mini-versions of PixBltThroughClips.

Text Output

The S3 presentation driver supports two different types of character output . One type is GRECharStringPos, which is implemented in the S3 driver by eddt_CharStringPos, in the EDDNGCHS.C file. The other type supports AVIO ( Advanced Video Input/Output) text, which is used in OS/2 and DOS window sessions.

The eddt_CharStringPos function uses two strategies for displaying text to the screen. For most strings, it will cache glyphs from the font. While cached, it will draw text by expanding the monochrome bit maps in the font cache to the display. There are, however, some cases where it cannot do this. One case is when the character to be cached is higher than the height of the font cache. Very large fonts will overflow the font cache, as the font cache is typically 127 scan lines tall in the S3 driver. Another reason it may be impossible to cache the glyphs is that the driver may be in 24-bit-per-pel mode, and the requested text is not some shade of gray. A third possibility is that the requested raster operation may be one that has problems on certain S3 chips. A fourth possibility is that only a single character in a font appears, making it undesirable to put it in the font cache. (Doing so might evict a heavily used font so that a single character may be cached.) In any of these cases, eddt_CharStringPos draws characters using BitBlt.

The following is an example of pseudocode for eddt_CharStringPos:

eddt_CharStringPos:
pFocaFont = Current Font
Check that request is valid
if simulation is required
    call back to engine to perform simulation

if display is disabled
    remove COM_DRAW bit from command flags
    if correlation required
        get correlation rectangles

if opaque rectangle is present
    if coordinates must be transformed
        set up opaque rect coordinates for transformation
    else
        get opaque rectangle coordinates

Get starting coordinates for the string

Transform any coordinates that need to be transformed to
device space

if increment vector is present
    convert increment vectors to device space

if current font has only a single character
    BltOneChar = TRUE
    Set up character spacing
    set PerCharDefs to a pointer to the character
    get character width and height
    get character A, B, C space
    if increment vector is present
        add in increment vector
    else
        add in character width
else
    BltOneChar = FALSE
    if character is too tall to fit in the cache
        CharTooBig = TRUE

    if font cache is disabled
        CharTooBig = TRUE

    if requested raster operation is defective on the S3 chip
        CharTooBig = TRUE

    if 24 bits per pixel
        get foreground and background colors
        if NOTGREY(foreground) and NOTGREY(background)
            CharTooBig = TRUE

    Compute starting position for the string

    if cursor is software
        Disable cursor

    if CharTooBig == FALSE
        if font is not in the font cache
            eddt_LocateCachedFont()    //Get a font cache entry

        if eddh_update_cache() == FALSE    //unable to fit font in cache
            eddt_LocateCachedFont()    //Get a font cache entry
            if eddh_update_cache() == FALSE
                bail out of string operation, the font is too big

    reenable cursor
    do one last bit of boundary setup (eddt_GetTextBox)

if there is an increment vector
    add in increment to x position

if BltOneChar == TRUE
    adjust starting position to be compatible with BitBlt
else
    adjust starting position to be compatible with string blt

if opaqueing rectangle required
    build opaque rectangle

if clipping rectangle
    clip bounding   rectangle   against   clip   rectangle 
     if   CharTooBig   = =   FALSE   and   string   completely   clipped 
         goto   UPDATE _ POS 

     clip   opaque   rect   against   clipping   rectangle 

     if   opaque   rect   entirely   clipped 
         disable   COM _ DRAW   bit   in   command   flags 
else 
     handle   multiple   clip   rects   if   necessary 

if   we   need   to   accumulate   bounds 
      accumulate   bounds 

if   we   need   to   perform   correlation 
     perform   correlation 

if   COM _ DRAW   is   not   set   in   command   flags 
     goto   CHARSTRPOS _ OK _ EXIT 

if   destination   is   the   display 
     SetDrawModeHard 
else 
     SetDrawModeSoft 

if   software   cursor 
     exclude   cursor 

setup   foreground   and   background   colors 

if   opaque   rectangle   must   be   drawn 
     set   pixelop 
     set   mix ,   blt   source ,   no   color   compare 
     TransferShadowRegisters ( ) 
     / / draw   the   opaque   rect   via   pattern   blt 
     eddb _ DrawThroughClips ( index _ PatDestBlt ) 

if   number   of   characters   to   draw   is   0 
     goto   CHARSTRPOS _ OK _ EXIT 

/ / special   case   # 1   - -   we   have   a   font   with   a   single   character 
if   BltOneChar   = =   TRUE 
     calculate   size   of   character   in   bytes 
     copy   character   into   the   Phunk ,   putting   it   in   row   major   order 
     Create   a   bit   map   header   for   the   character 
     set   up   pixelop ,   mix ,   source ,   colors   etc . 
     TransferShadowRegisters ( ) 
     Setup   AIxfer   for   a   BitBlt 
     while   count   of   characters   >   0 
         fix   up   the   character   for   BitBlt 
         eddb _ DrawThroughClips ( index _ SrcDestBlt ) 
         update   position   of   next   character 
         decrement   count   of   characters 
     goto   UPDATE _ POS 

/ / special   case   # 2   - -   uncacheable   font 
if   CharTooBig   = =   TRUE 
     set   up   colors ,   mixes ,   source ,   etc . 
     TransferShadowRegisters ( ) 
     while   count   of   characters   >   0 
         get   character   width   and   height 
         set   pCharDefn   to   point   to   the   character   bit   map 
         get   A ,   B ,   and   C   space 
         copy   the   character   into   the   Phunk ,   putting   it   in   row   major   order 
         setup   a   bit   map   header   for   the   character   bit   map 
         setup   AIxfer   for   a   BitBlt 
         fixup   source   and   destination   values   so   they   are   non - negative 
         eddb _ DrawThroughClips ( index _ SrcDestBlt ) 
         advance   to   next   character   position 
         decrement   count   of   characters 
      goto   UPDATE _ POS 

/ / finally   we   get   to   draw   text   through   the   code   in   eddhgchs . asm 
set   up   pointer   to   the   font   in   AIxfer 
store   a   pointer   to   the   code   points   and   position   of   first   char   in   AIxfer 
set   up   mixes ,   source ,   colors 
TransferShadowRegisters ( ) 

if   position   vector   present 
     / / draw   them   one   at   a   time   - -   we   have   a   position   vector 
     set   number   of   characters   in   AIxfer   to   1 
     while   count   of   characters   >   0 
         store   increment   from   vector   in   AIxfer . bCharWidth 
         eddb _ DrawThroughClips ( index _ DrawText ) 
         update   position   of   next   character   from   position   vector 
         point   to   next   character 
         decrement   count   of   characters 
else 
     Set   count   of   character   in   AIxfer   to   number   of   characters   in   string 
     eddb _ DrawThroughClips ( index _ DrawText ) 

UPDATE _ POS : 
update   position   if   required 

if   destination   cached 
     evict   cached   bit   map 

CHARSTRPOS _ OK _ EXIT : 
reenable   cursor 

In eddt_CharStringPos and in the character-caching code, notice the following loop:

for (i = 0; i < CharHeight; i++)
{
    source_index = i;
    for (j = CharBytesPerRow; j--; )
    {
        *pCharBuffer++ = pCharDefn[source_index];
        source_index += CharHeight;
    }
}

This loop is a difficult copy operation because presentation stores the bit maps for glyphs in column major order, rather than in row-major order. That is, all of the bytes that make up the first column of a character are stored one after another, followed by all of the bytes of the second column , and so forth. The bits in each byte of monochrome data are in Motorola** order; that is, bit 7 is the left-most bit, and bit 0 is the right-most bit . Also, after the inner loop rearranges the glyph, the byte ordering is in Motorola order. For other devices, it is possible that either or both the bit and byte ordering may have to be altered.

The eddt_CharStringPos function caches characters in off-screen VRAM. The first portion of this involves determining if the font has already been cached. The eddt_LocateCachedFont( ) data field, in EDDNCACH.C, searches the array of FontCacheInfo structures . If it finds a matching font, it returns. If not, it evicts a font from the cache, and sets the usCachedFontIndexfield in the passed-in parameter in the FONTDETAILS structure. The FONTDETAILS structure is defined in the EDDTYPET.H file, and it stores a pointer to the font and a cache slot, among other things. The S3 driver supports the caching of up to 8 fonts; therefore, the array of pointers to FontCacheInfo structures ( pFontCacheInfo) consists of 8 entries.

When an entry has been found for the font, it is necessary to actually cache the characters in the string. This caching is handled by eddh_update _cache, which is in the EDDHGCHS.ASM file. The eddh_update_cache loops through the string, and for each character that is not already cached, it calls eddt_CacheCharacter (in EDDNCACH.C). The code in eddt_CacheCharacter is similar to the code in eddt_CharStringPos that uses BitBlt to display a single character. First, it attempts to find a position in the cache for the character. The 8514/A and the S3 driver stores a single font in a single plane of VRAM. In 16-bit-per-pel modes, the S3 driver allows a font to wrap to another plane. Because the 8514/A interacts with bit maps as rectangles, eddt_CacheCharacter calculates an X-Y coordinate for the character in the font cache, and calls Cache8514Char (in EDDHGCHS.ASM) to copy the glyph into off-screen memory.

In the cases where it is not using BitBlt, eddt_CharStringPos uses either eddh_DrawText (if the destination is the display), or eddf_DrawText (if the destination is not the display). The eddh_DrawText function loops through an array of clipping rectangles, drawing the string (or portion thereof) into each clipping rectangle. The complexity of eddh_DrawText results from the fact that it does not use the S3 chip hardware-scissoring capabilities to clip the text. Instead, if part of a character is clipped, it calculates offsets into the character, and into the destination so that only the portions of the character that are inside the clipping rectangle are actually drawn. When all of that has been set up, the character is BitBlted by way of a hardware monochrome expansion blt from the character cache to the display.

Advanced Video Input/Output (AVIO) Text

AVIO text is used by GRE to draw characters in DOS or OS/2 window sessions. The S3 driver implements this functionality with eddv_CharStr (in EDDVCSTR. C), eddv_CharRect (in EDDVCREC.C), eddv_ScrollRect (in EDDVSREC.C), and eddv_UpdateCursor (in EDDVUPDC.C). The four basic functions that comprise AVIO text are: drawing a string of characters at a location in the window, drawing a rectangle of characters, scrolling a rectangle, and displaying a text cursor in the window.

In addition to the cursor, the fundamental operation employed in AVIO text is drawing a rectangle of characters. The GRE passes the AVIO functions to a string of characters and attributes, and a rectangle that describes the shape that those characters are to be drawn into. For instance, the string "The Quick Brown Fox" could be rendered as:

The Quick Brown Fox

or:
T
h
e

Q
u
i
c
k

B
r
o
w
n

F
o
x


or even:

The Qui
ck Brow
n Fox

This approach allows portions of the DOS or OS/2 window session to be refreshed efficiently, even if they are partially occluded by other windows . The presentation display driver has to support both horizontal strings of characters and rectangular blocks of characters. The S3 driver calls the same functions to actually render the characters in either case. These functions are CGATextBlock and MFITextBlock. The following is the calling hierarchy for eddv_CharString and eddv_CharRect:

eddv_CharString (eddvcstr.c)
        CheckAVIOFontsCached (eddvsubr.c)
    if cell_size == 2
        CGAText
     else
        MFIText

eddv_CharRect (eddvcrec.c)
        CheckAVIOFontsCached (eddvsubr.c)
    if cell_size == 2
        CGAText
     else
        MFIText

CGAText (eddvsubr.c)
        update_cache_char_rect2 (eddhavio.asm)
        CGATextBlock (eddhavio.asm)

MFIText (eddvsubr.c)
        update_cache_char_rect4 (eddhavio.asm)
        MFITextBlock (eddhavio.asm)

There are similarities in the actual source for eddv_CharRect and eddv_ CharString. The eddv_CharString function is a special case of eddv_CharRect . AVIO fonts are cached in off-screen VRAM in the S3 driver. CheckAVIOFontsCached, update_cache_char_rect2, and update_cache_char_rect4 call the same code in the EDDNCACH.C as does eddt_CharStringPos. When fonts are cached correctly for the presentation desktop text, they will also be cached correctly for AVIO.

CGAText and MFIText ensures the font is cached, and then makes a call to either CGATextBlock or MFITextBlock. These latter two routines perform the work. CGATextBlock handles text that is formatted as two-byte character, attribute pairs, which is exactly how color text is stored on a real CGA. The CGA stored text is one-byte of attribute (foreground and background color) and a one-byte character. (MFI, Main Frame Interactive, is used to support main frame terminal emulation.) MFI Text uses four-byte characters, and includes extended attributes such as underlined characters, and inverse video. Otherwise, MFITextBlock and CGATextBlock are similar to each other.

CGATextBlock takes two arguments, a pointer to a FONTDETAILS structure, and a pointer to an AVIOINFO structure, which is taken from the device context. In addition, CGATextBlock takes parameters from the AIxfer block, and even a few things from the Scatch Pad (Spad). The AVIOINFO structure holds two useful pieces of information: the X and Y starting coordinates of the window and the size of each character cell. Many of the other parameters are given in units of character cells. The AIxfer block holds several useful pieces of information. AIxfer.bRow and AIxfer.bColumn are the starting row and column for this operation. Multiplying them by pAvioInfo.bCellHeight and pAvioInfo.bCellWidth and adding in pAvioInfo.sXoffset and pAvioInfo. sYoffset yields the starting location for the first character on the screen . AIxfer.bDown is the height of the character rectangle, in characters. AIxfer.bAcross is the width of the character rectangle in units of character cells.

Changing CGATextBlock results in the upper and lower 16-bits of various registers that are used to hold different loop counters. The code uses a macro called swapwhen it needs to access something in the high-order 16- bits of a register. As new code is added, a register can easily be locked up if it is set up and used a distance away from the new code. The high 16 -bits of the "ecx" registers hold the count of clipping rectangles that must be iterated through. Register cl holds AIxfer.bDown. Register ch holds AIxfer.bAcross. Later in the code, the "ecx" register is pushed on the stack, and cx holds the current character and attribute pair. The "ebx " register holds a pointer to the string of attributes and characters, and is also pushed onto the stack and then holds the code-point (which is an index into the cache structures so the characters' location in the VRAM cache can be obtained). The "eax" register holds the base address of the glyph definition, and after being pushed, as a repeat count. (CGATextBlock detects multiple copies of the same character, and performs less setup on subsequent renderings of the character. Much of what is drawn into an AVIO window is space characters.) The usage of registers changes depending on where you are located in the code. Locating these changes is probably the single most difficult aspect of changing this code. The actual operation being performed is a monochrome-expansion BitBlt. Often, it is difficult to determine which registers are actually available for use.

CGATextBlock performs clipping a bit differently. Unlike eddh_DrawText, it uses the 8514/A scissoring registers. (In fact, few of the hardware- dependent routines in the S3 driver use the hardware scissoring registers.)

AVIOScroll, also in EDDHAVIO.ASM, is used as part of the process of scrolling an AVIO window. It is a simple screen-to-screen hardware BitBlt. AVIOCursor, in the same file, draws a solid block on the display using whatever colors and raster operations have been set up in the TransferShadowRegisters structure.

Line Drawing

The OS/2 Presentation Device Driver Referencementions three types of line drawings that must be supported by the driver: polylines, poly-short lines, and draw lines in path. Of these, poly-short lines are no longer used by the GRE when rendering curves. Consequently, there is little need to pay attention to short lines.

Draw lines in path is implemented in the EDDLDRAW.C file, in the eddl_ DrawLinesInPath function. Poly lines are implemented in the EDDLPOLY.C file, in the eddl_Polyline function. Neither of these functions has any real dependency on the hardware. In fact, both perform only a certain amount of setup, and then calls to eddl_PolyLineWork (in EDDLPOLY.C), which performs even more setup. The eddl_PolyLineWork function performs coordinate transformations, if they are required. It accumulates bounds and performs correlation, if these are required. It sets the Shadow8514Regs with the colors and mixes required for the polyline operation. It enumerates through the clipping rectangles, if required. It does not draw lines. Instead, it calls (*(*pDrawFunctions)[index_PMLINES]) (), which is really a call to either eddf_PMLINES or eddh_PMLINES.

The eddh_PMLINES function takes an array of lines and an array of clipping rectangles, and renders the lines to the display clipped to the clipping rectangles. The eddh_PMLINES function uses the hardware to render lines. The hardware clips each line against the clipping rectangles in the software. During this clipping, it calculates the octant in which it falls, and the Bresenham error terms for the line. These error-term calculations are geared toward the 8514/A, although with minor modifications they could be adapted to other devices. The octant in which the line falls is calculated as follows:

OCT_DX_BIT Delta x is negative (x is decreasing)

OCT_DY_BIT Delta y is negative (y is decreasing)

OCT_DZ_BIT Line is y major

Aside from the octant and error-term calculations, eddh_PMLINES must also determine whether to draw the first pel of lines. This occurs by checking AIxfer.usCallType after entirely drawing the first line. If this is equal to POLYLINE_CALL, then the first pel of all subsequent lines must be omitted.

The following code example shows how to draw styled lines when using an S3 chip set. This code is located in eddh_PMLINES.

ifdef HARD_DRAW
ifdef _8514
; Is there a pattern which we need to set up?
; If so, the 8514/A can't handle it.  We must use the
Bresenham line
; drawing simulation code.
        cmp     _AIxfer.usPatType, LINETYPE_SOLID
        jnz     softdraw

ifdef   BPP24
        test    [_DDT],USE_24BPP
        jnz     softdraw
endif
endif
endif

.
.
.

softdraw:
; Right, this spells T . r . o . u . b . l . e . 
;   We   are   now   going   to   call   a   ' C '   function   in   the   driver   which   emulates 
;   the   hardware   line   draw .    To   make   things   simple   we   will   save   some 
;   important   registers   here . 
;   These   registers   should   be   saved :   xga ,   edi ,   esi ,   ecx ,   ebx 
;   For   safety   we   save   all   the   necessary   registers 
         pushxga 
         push      edi 
         push      esi 
         push      ebx 
         push      ecx 

         call      _ eddl _ BresenhamOne 

         pop       ecx 
         pop       ebx 
         pop       esi 
         pop       edi 
         popxga 
         jmp       vloopend 

The eddl_BresenhamOne function is located in EDDLPOLY.C. It is a software line-rendering routine that draws to the hardware calling Draw8514_Pel, in EDDHLINE.ASM. Draw8514_Pel plots a single pel at the given X-Y coordinate using the mix, color, and so forth, set up by eddl_BresenhamOne. For chips that support an aperture into the frame buffer, it is almost always more efficient to draw the pel through the frame buffer than to use the drawing engine. Changing one of the conditional jumps in the listing above to a " jmp softdraw," forces all lines to be drawn in software, which is useful for chips that do not support hardware-line drawing.

The PMChart and Pulse programs in the OS/2 Productivity folder provide excellent test cases for the various types of line-drawing that the driver is required to do. In addition, the highlighted icons on the presentation desktop are a very good test for styled lines.

Scanlines

Scanlines are processed by eddh_PMSCANLINE, in EDDHSCAN.ASM, which is the work routine for eddl_PolyScanLine, in EDDSPOLY.C. Scanlines are used internally by the fill code in GRE. They are used any time an area needs to be filled. The eddh_PMSCANLINE function is given an array of scanline endpoints and an array of clipping rectangles. It takes the array of endpoints and draws horizontal lines between them with the given fill pattern.

There are three cases for fills: a monochrome-dithered pattern, a color ( 2x2) dithered pattern, and a user-supplied monochrome bit map that is used as a pattern. The monochrome and color-dithered cases are handled by the main body of eddh_PMSCANLINE. In either case, a monochrome pattern of alternating 1's and 0's is aligned to the destination. In the case of a monochrome pattern, the foreground and background colors are set up in TransferShadowRegisters. In the case of a color-dithered pattern, the colors are pulled from the pattern bit map which is passed in. Note that color-dithered patterns only exist at 8 bits-per-pel and less. There is no reason to dither at 16 bits-per-pel and more. Bit-map patterns are handled by the routine UserBmapScan, which is also in EDDHSCAN.ASM. This takes an arbitrary bit map and uses it as the pattern source for the fill.

Image Data

The image data function is an obscure driver entry point. It takes a single scanline of monochrome data, and expands it to the display using the current color and mix. This is supported by eddb_ImageData, in EDDBIMAG.C, which in turn calls eddh_PMImageData, in EDDHIMAG.ASM. This function takes a supplied monochrome bit map, and blt's a single scanline to the display. This function is rarely used. (The OS/2 Tune Editor makes extensive use of image data.)

Cursor

Presentation display drivers must support both monochrome and color cursors . Support for monochrome and color cursors is handled in three files in the S3 driver: EDDMCURS.C, EDDMCCRS.C, and EDDCURSR.ASM. EDDMCURS.C contains the eddm_DeviceSetCursor function. (The eddm_SetColourCursor routine in the EDDMCCRS.C file is similar to eddm_DeviceSetCursor.) The eddm_ DeviceSetCursor function sets the shape of a monochrome cursor, and then enables the cursor. The bulk of the function is involved in creating the input "AND" and "XOR" masks into a format suitable for an S3 chip. The eddm_DeviceSetCursor function is passed in a bit map. The AND mask is located first in the bit map. The XOR mask immediately follows the AND mask. When the masks are formatted for the hardware, they must be copied to off-screen memory, or in the case of an S3 chip with a Brooktree DAC**, copied to the DAC. When this has been completed, SetSpriteShape in EDDCURSR.ASM is called. This routine will either enable or disable the hardware cursor, depending on the state of cursor_data.cd_draw_sprite_flags .

The data structure for the cursor_data is located in CURSOR.H. It is a large structure, and it holds information such as the color depth the driver is currently running, the dimensions of the display, and so forth. Both of these can be found in the OS/2 Presentation Device Driver Reference . Every presentation display driver is required to export a MoveCursorBlock table of the format:

typedef struct _MCDESCRIPTION {
        PVOID pMoveCursor;      //pointer to the move cursor routine
        ULONG ulCodeLength;     //length of move cursor code
        PVOID pCursorData;      //pointer to data used by move cursor
        ULONG ulDataLength;     //length of move cursor data
} MCDESCRIPTION;

This structure is export ordinal 103. The following exports are located in 8514_32.def:

EXPORTS
        movecursorblock                   @103
        OS2_PM_DRV_ENABLE                 @200
        OS2_PM_DRV_QUERYSCREENRESOLUTIONS @202
        SEAMLESSTERMINATE                 @350
        SEAMLESSINITIALIZE                @351
        OS2_PM_DRV_RING_LEVELS            @999
        OS2_PM_DRV_ENABLE_LEVELS          @998



movecursorblock is located at the beginning of EDDCURSR.ASM:

movecursorblock equ this byte
        dd      OFFSET FLAT:_start_of_cursor_code
        dd      _end_of_cursor_code - _start_of_cursor_code
        dd      OFFSET FLAT:_start_of_cursor_data
        dd      _end_of_cursor_data - _start_of_cursor_data
_DATA           ends


_CURSOR         segment dword use32 public 'CODE'
                assume  cs:FLAT, ds:FLAT, es:FLAT

public  _start_of_cursor_code
_start_of_cursor_code:


;***********************************************************************
; This is the start of the 32-bit move cursor routine
; The interface is:
;       The stack holds 3 dword parameters:
;               The x and y coordinates of the cursor
;               and a pointer to locked global memory containing the
;               cursor data
;
; The internal entry point is used when calling from within the driver.
; The real entry point is the one that will be called at interrupt time.
;***********************************************************************


MoveCursor32:

In this code example, movecursorblock is the MoveCursorBlock structure. MoveCursor32 is exported in this manner because both its code and the data it uses will be called from contexts in which the linear addresses for the rest of the code and data in the driver are not defined. The MoveCursorBlock allows the caller of MoveCursor32 to create a linear address for the cursor code and data. For this reason, MoveCursor32, or any of the routines called by it, cannot access data outside the range of _start_of_cursor_data to _end_of_cursor_data. Between these labels, is the cursor_data structure. To access some data specific to your hardware in MoveCursor32, add it to the cursor_data structure.

MoveCursor32 gets either the new coordinates of the cursor, or if the coordinates are 0x8000, then it is a check cursor call. Check cursor is a way of periodically checking to determine if the cursor needs to be updated . For example, a MoveCursor request might fail because the hardware is currently in use. In that case, CheckCursor allows the driver to update the cursor position as soon as the cursor is not in use. MoveCursor32 also handles movement of the cursor.

There are two possibilities for the S3 driver, either a hardware cursor is in use, or a software cursor is in use. In the case of a hardware cursor, the function DrawSprite is called. DrawSprite calls either OutputSprite or BTOutputSprite depending on whether the S3 driver's internal hardware cursor is used, or the Brooktree DAC's hardware cursor is used.

Software cursors are slightly more complex. First, MoveCursor32 calls CheckXRegion, which checks to see if the cursor falls in the current exclusion region. If it does, then the cursor is not drawn. Otherwise, the routine software_cursor is called. The software_cursor routine calls internal_remove_software_cursor, and then draw_pointer. Moving a software cursor is accomplished as follows:

1.Copy the save area to the position the cursor currently occupies. This erases the cursor. _internal_remove_software_cursor performs this function .

2.Copy the new pointer position to the save area.

3.XOR the XOR mask from off-screen VRAM to the cursor position.

4.AND the AND mask from off-screen VRAM to the cursor position.

5.OR in the color bit map from off-screen VRAM to the cursor position.

If a monochrome cursor must be handled in software for some reason, then the AND mask would be applied first, followed by the XOR mask. (In a monochrome cursor there is no color bit map.) The remainder of the complexity lies in handling cases including:

�Hot spot moves to a negative coordinate.
�Cursor is clipped on top.
�Cursor is clipped on the bottom.
�Cursor is clipped on the left or right side.

Hardware Scissoring

Most of the routines in the driver do not use the S3 driver's scissoring capability. All of the routines assume, however, that initially the scissors are set so all memory is accessible. Therefore, hardware scissoring is implemented and any routines that use it should re-open the scissors after using them.

eddq_Escape - s3qesc.c (EDDQESC.C for XGA)

The eddq_Escape() function processes various escape functions supported by the S3 driver. One of the main uses for these escape functions is the support for full-motion video by OS/2 Multimedia. Full-motion video works by drawing directly into the frame buffer of the video device. In order to do this, MMPM/2 must obtain a pointer to the aperture of the video adapter. It then informs the driver that it is going to draw directly into a rectangular region on the display. If the aperture is smaller than the size of the memory on the video adapter, then MMPM/2 might have to switch banks while it is drawing. Finally, when it is finished, it must inform the presentation display driver that it has finished drawing onto the display. The escape functions that are required to support multimedia are:

DEVESC_GETAPERTURE 33000l

DEVESC_GETAPERTURE is handled by the function GetAperture(PULONG pcOutCount,
PAPERTURE pAperture).

What this function does is return the following structure (located in
eddtypet.h):

typedef struct _APERTURE {  /* aperture */
   ULONG ulPhysAddr;
   ULONG ulApertureSize;
   ULONG ulScanLineSize;
   RECTL rctlScreen;
} APERTURE;

The ulPhysAddr data field must be set to the physical address of the aperture in memory. In the case of the S3 driver, the aperture can be the 64KB aperture at A0000, a 1MB aperture located in the 24-bit AT-bus address space, or a 4MB aperture located in the 32-bit VL-bus address space. GetAperture() calls FindS3Aperture(). FindS3Aperture searches for the aperture in a number of ways.

First, it searches the environment to see if it can find a string matching "VIDEO_APERTURE." If so, it uses the value obtained as the base address of the aperture.

If it does not find an environment variable, it looks at the size of system memory, and several S3 registers in an attempt to find the address of the aperture. It then tests the aperture, and if the test fails, it falls back to the 64KB A0000 aperture.

The ulApertureSizefield must be set, in bytes, to the size of the aperture . The ulScanLineSizefield must be set, in bytes, to the width of a scanline. The rctlScreen function must be set to the minimum and maximum coordinates of the visible display. For example, at 1024 x 768:

        rctlScreen.xLeft = 0;
        rctlScreen.yTop = 0;
        rctlScreen.xRight = 1023;
        rctlScreen.yBottom = 767;

DEVESC_AQUIREFB 33010l

This function is used by MMPM/2 to obtain exclusive access to the frame buffer so that it may draw directly upon its surface. It is handled by the function AquireFB(ULONG cInCount, PAQUIREFB pAquireFB);

The input structure PAQUIREFB is defined as follows:

typedef struct _ACQUIREFB {  /* acquirefb */
   ULONG fAFBFlags;
   ULONG ulBankNumber;
   RECTL rctlXRegion;
} ACQUIREFB;
typedef ACQUIREFB *PACQUIREFB;

The fAFBFlags function is equal to 1 if the driver is to switch banks prior to giving access to the frame buffer. It equals 0 if no bank switch is needed. The ulBankNumberfield is equal to the bank number to switch to, if bit 0 of the fAFBFlags is equal to 1. The rctlXRegion function is the area of the display being touched by MMPM/2, so the cursor might be excluded by the presentation display driver.

First, AquireFB() gets the driver semaphore. Then, it saves the address of the aperture being used by the presentation display driver. Next, it sets the bank, if that is needed. It then performs cursor exclusion if a software cursor is in use. Finally, it sets the location of the aperture, and enables it. (Some S3 chips, notably the older 86C801 and 86C805 chips, allow either the drawing engine or the frame buffer to be active, but not both simultaneously. Therefore, code that uses the frame buffer must first enable it, and then disable it when finished.) The aperture may be moved because the S3 driver attempts to use a 1MB, 2MB, or 4MB aperture for full- motion video to avoid the need for bank selects, thus improving performance .

DEVESC_DEAQUIREFB 33020l

This escape is handled by DequireFB(). DeaquireFB() is a function that disables the frame buffer used by MMPM/2, restores the old frame buffer location, and then de-excludes the software cursor, if needed. Finally, the driver semaphore is freed.

DEVESC_SWITCHBANK 33030l

This escape is handled by SwitchBank(ULONG cInCount, PULONG pInData). The pInData function is a pointer to a bank number. SwitchBank validates that the requested bank number is reasonable, saves it in the cursor_data structure to be restored by the cursor interrupt handler, and then sets the bank.

Death and Resurrection

The EDDMDEAD.C file contains the functions eddm_Death, and eddm_ Resurrection, which are used when switching to and from full-screen Windows **, DOS, or OS/2 sessions. The eddm_Death function handles the switch of the presentation display driver into the background. It switches the display to text mode, sets the drawing mode to software-drawing mode, and disables the bit map cache. The eddm_Resurrection function performs the inverse task. It switches the driver back into graphics mode, reloads the palette if needed, and invalidates the font cache.

Off-Screen VRAM Allocation - CACHEMAN.C

Unlike the XGA driver, which allocated off-screen VRAM in the EDDEVRAM.C file, or the 8514/A driver which used a fixed-allocation strategy, the S3 driver allocates off-screen VRAM in CACHEMAN.C. The CACHEMAN.C function contains two key tables, the HWMAP and the CACHEMAP. The following are the data structures for each:

typedef struct _HWMAP { /* hwm */
        ULONG   vis_width;
        ULONG   vis_height;
        ULONG   phys_width;
        ULONG   phys_height;
        ULONG   phys_memory;
        ULONG   BitCount;
        ULONG   hw_cursor;
        ULONG   hw_cursor_Y1024;
        ULONG   and_mask;
        ULONG   xor_mask;
        ULONG   save_area;
        ULONG   color_cursor;
        ULONG   start_bm_cache;
        ULONG   num_font_planes;
        ULONG   vertical_bmaps;
} HWMAP;

typedef HWMAP  *PHWMAP;


typedef struct _CACHEMAP { /* cm */
        ULONG   max_bit maps;
        ULONG   font_cache_start;
        ULONG   font_cache_left;
        ULONG   font_cache_top;
        ULONG   font_cache_right;
        ULONG   font_cache_bottom;
        ULONG   color_dither;
        ULONG   mono_dither;
} CACHEMAP;

The HWMAP contains information about the resolution, including the width of the display in bytes, locations of the hardware and software cursors, location of the bit-map cache, and the amount of memory required for the video mode. The CACHEMAP table has two entries for every entry in the HWMAP : one for normal driver operation, and one for seamless windows. When seamless windows is active, the size of the font cache is reduced. During initialization of the driver, in the function QueryAndSelectNativeMode, the resolution the user has requested is compared against the entries in the HWMAP. If it is obtainable, then the function CacheManager (in cacheman.c) is called. CacheManager takes the index into the HWMAP, as set up by QueryAndSelectNativeMode, and sets the global pointer pHWMap to point to the corresponding entry in the HWMAP. Likewise, this is done for pCacheMap , taking into account whether seamless windows is currently active. The entries in CACHEMAP and HWMAP that begin with 0xF0 are X-Y coordinates in VRAM concatenated together. (Concatenation is the usual method of addressing VRAM in this driver.)

HWACCESS.ASM

The routines in HWACCESS.ASM are among the most heavily used code in the driver. They are responsible for setting up key hardware values, copying data to or from off-screen VRAM, and resetting the hardware. The purpose of this section is to describe each routine, and where and how it is used. When adapting the S3 driver to another chip set, it is likely that one or more of these routines will have to be modified. Entirely new routines might need to be created to augment or even replace some of the ones mentioned.

TransferShadowRegisters

TransferShadowRegisters takes a single argument (which is a set of flags indicating the registers to copy) and is used throughout the driver to copy various values from the Shadow8514Regs to the graphics hardware. It can initiate drawing commands in the XGA driver; in the S3 driver, it cannot. In the S3 driver, the only function flag used is TSR_COLOUR_MIX, which sets the colors, hardware mix, monochrome expansion, and the color compare.

CopyMemoryToVRAM

CopyMemoryToVRAM takes the following parameters:

pVOID pSystemMemory - Pointer to the system memory bit map to copy
ULONG pVRAMAddress - Pointer to the destination in VRAM
ULONG width - width in pels
ULONG height - height in scanlines
ULONG format - flags indicating the pel depth of pSystemMemory, can be 1, 8,
               16, or 24 bits-per-pel

This function copies a bit map from system memory to VRAM. It is used by EDDMCURS.C and EDDMCCRS.C to copy the cursor image to off-screen VRAM. It is also used by EDDNCACH.C, to copy bit maps into the cache.

CopyVRAMToMemory

This function copies a bit map from VRAM to system memory and performs the exact opposite function of CopyMemoryToVRAM. It is used by PIXBLT.C, as well as CORVBITM.C, EDDSCNLR.C, and EDDBSETP.C, when it is necessary to read memory.

pVOID pSystemMemory - Pointer to the system-memory bit map to copy.

ULONG pVRAMAddress - Pointer to the source in VRAM.

ULONG width - Width in pels.

ULONG height - Height in scanlines.

ULONG format - Flags indicating the pel depth of pSystemMemory, can be 1, 8 , 16, or 24 bits-per-pel.

CopyDestToMemory

Performs exactly the same function as CopyVRAMToMemory, and consists of a jump into CopyVRAMToMemory. CopyDestToMemory is used in PIXBLT.C.

pVOID pSystemMemory - Pointer to the system-memory bit map to copy.

ULONG pVRAMAddress - Pointer to the source in VRAM.

ULONG width - Width in pels.

ULONG height - Height in scanlines.

ULONG format - Flags indicating the pel depth of pSystemMemory, can be 1, 8 , 16, or 24 bits-per-pel.

CopyMaskToVRAM

CopyMaskToVRAM is used by the cursor code to copy a 1-bit-per-pel mask into VRAM and uses the following parameters:

pVOID pSystemMemory - Pointer to the system-memory bit map to copy.

ULONG pVRAMAddress - Pointer to the destination in VRAM.

ULONG width - Width in pels.

ULONG height - Height in scanlines.

ULONG format - Flags indicating the pixel depth of pSystemMemory. The pel depth can be 1 bit-per-pel.

KlugeReset

KlugeReset takes no parameters. It is used to reset the drawing engine and to clear the screen.

eddf_MESS

The following code from EDDHBBLT.ASM is similar to code found throughout the driver.

; ss:esp now points to the destination coordinates:
  pop these straight into
; the hardware
        pop     eax
        memregwrite     dest_map, eax

; write the pixel op to kick off the blt
        memregwrite     pixel_op, edx

IFDEF HARD_DRAW

; see if the source is vram or not by checking vram marker
        IFDEF   _8514
        push    ebx
        mov     ebx, AIxfer.pbmhSrc
        mov     eax, [ebx].bit map_address
        and     eax, 0f0000000h
        cmp     eax, 0f0000000h
        pop     ebx
        jz      short @f
        call    SoftSrcSpecialist
        jmp     short soft_done

@@:     call    SrcSpecialist

soft_done:
        ENDIF   ;_8514

ELSE

        saveregs
        call    _eddf_MESS
        restoreregs

ENDIF

The following code from EDDHLNE.ASM shows the procedure for Soft-Draw mode. In this code, setup is created and calls eddf_MESS.

ELSE ;SOFT_DRAW

IFDEF _8514

        mov             eax,_SPad.ptsNewStart
        memregwrite     dest_map,eax

        mov             ax,_SPad.sK1
        memregwrite     sr_K1,ax

        mov             ax,_SPad.sK2
        memregwrite     sr_K2,ax

        mov             ax,_SPad.usErrorTerm
        memregwrite     Err_Term,ax

        mov             ax,_SPad.usMajorAxis
        memregwrite     dim1,ax

ENDIF ;_8514

        saveregs
        call    _eddf_MESS
        restoreregs
ENDIF

The S3 driver draws to bit maps by having eddf_MESS emulate certain XGA operations in software. The eddf_MESS routine interprets the Shadow8514Regs , based on the parameters therein, and the pel operation, then calls one of a number of routines to perform the requested drawing operation. For the most part, eddf_MESS is a collection of jump tables to routines that do the work. Each case and each pel depth are broken out into special cased routines. To some extent, this explains the size of the code. Individually , the routines themselves are not complex, although many of them are implemented as macros. The following is a list of the files that comprise the MESS, and the functions they perform.

Line Drawing:

The bulk of the code in the following functions is implemented as 
macro calls.

FFLIMES.ASM
        eddf_MESSDoBresenham
        eddf_MESSDoShortLines

Destination-Only BitBlts and Rectangular Fill Operations:

The following routines fill the destination with a solid color:
FFBLTD.ASM
        eddf_MESSBlockFill24
        eddf_MESSBlockFill16
        eddf_MESSBlockFill81
        eddf_MESSBlockFill4111

The following routines fill with a solid color, and also a mix:

        eddf_MESSFixedSrc16
        eddf_MESSFixedSrc81
        eddf_MESSFixedSrc24
        eddf_MESSFixedSrc4111

Pattern Blts:

The following routines copy a general pattern to the destination with a 
mix. This is a pattern with a monochrome bit map.
(This is a different operation from the monochrome expansions used 
for text output.)

FFBLTPD.ASM
        eddf_MESSPatDest16
        eddf_MESSPatDest24
        eddf_MESSPatDest81
        eddf_MESSPatDest41
        eddf_MESSPatDest11
        eddf_MESSPatDestMixes11

The following routines handle pattern copy of general 
patterns:

        eddf_MESSPatCopy16
        eddf_MESSPatCopy24
        eddf_MESSPatCopy81
        eddf_MESSPatCopy41
        eddf_MESSPatCopy11

The following routines handle 8-bit-wide patterns with a mix:

        eddf_MESSPatDestByte24
        eddf_MESSPatDestByte16
        eddf_MESSPatDestByte81
        eddf_MESSPatDestByte41

The following routines handle pattern copy of 8-bit-wide patterns:

        eddf_MESSPatCopyByte16
        eddf_MESSPatCopyByte24
        eddf_MESSPatCopyByte81
        eddf_MESSPatCopyByte41
        eddf_MESSPatCopyByte11

Monochrome Expansion Blts

These BitBlts are used when drawing text in the software-drawing code. The principle difference between software-drawing mode and hardware-drawing mode routines in FFBLTPD.ASM is that text blts are from bottom-left to top- right, while pattern blts are from top-left to bottom-right. These routines are also optimized for text.

The following routines handle monochrome expansion with both a 
foreground and background mix:

FFBLTPX.ASM
        eddf_MESSPatExp16
        eddf_MESSPatExp81
        eddf_MESSPatExp24
        eddf_MESSPatExp41
        eddf_MESSPatExp11

The following routines handle monochrome expansion with a foreground mix 
and transparent background:

        eddf_MESSPatExpFg16
        eddf_MESSPatExpFg81
        eddf_MESSPatExpFg24
        eddf_MESSPatExpFg41
        eddf_MESSPatExpFg11

Setup:

The following routines handle setup for source and destination software 
BitBlt's eddf_MESSSetUpPatDest11.

FFBLTSET.ASM
        eddf_MESSSetUpSrcDest16
        eddf_MESSSetUpSrcDest81
        eddf_MESSSetUpSrcDest41
        eddf_MESSSetUpSrcDest11

The following routine handles setup for non-wrapping pattern setup (such as text):

        eddf_MESSSetUpPatDest11

The following routines handle setup for destination-only blts:

        eddf_MESSSetUpDest16
        eddf_MESSSetUpDest81
        eddf_MESSSetUpDest24
        eddf_MESSSetUpDest41
        eddf_MESSSetUpDest11

The following routine handles common setup for 4-bit-per-pel pattern 
blts:

        eddf_MESSSetUpDestForPat41

Source and Destination Blts:

The following routines makes a copy of the source to the 
destination:

FFBLTSD.ASM

        eddf_MESSBlockCopy4111
        eddf_MESSBlockCopy81
        eddf_MESSBlockCopy24
        eddf_MESSBlockCopy16

The following routines copy the source to the destination while 
applying a mix:

        eddf_MESSSrcDestMix4111
        eddf_MESSSrcDestMix81
        eddf_MESSSrcDestMix24
        eddf_MESSSrcDestMix16

The following routines copy the source to the destination, tiling it to 
fill the destination. eddf_MESSSrcDestWrapMix41:

        eddf_MESSSrcDestWrapCopy41
        eddf_MESSSrcDestWrapCopy81
        eddf_MESSSrcDestWrapCopy24
        eddf_MESSSrcDestWrapCopy16

The following routines copy the source to the destination with a mix,
tiling it to fill the destination:

        eddf_MESSSrcDestWrapMix81
        eddf_MESSSrcDestWrapMix24
        eddf_MESSSrcDestWrapMix16

16-Bit-Per-Pel Support

With the exception of the S3 911 and 924 chips, the S3 chips directly support 16-bit-per-pel drawing operations in hardware. As a result, there is little that needs to be changed in the driver code to support 16-bit-per-pel modes on the various S3 chips. This will most likely be true on most graphics chips. There are, however, two issues that can arise: byte ordering and the location of the red, green, and blue components of the pel . The S3 driver uses a 5,6,5 pel for 16 bits-per-pel. (Green gets the extra bit.) This is exactly the same mode as the XGA. If your adapter uses a different byte ordering or runs 5, 5, 6, or 5, 5, 5, the functions will have to be modified so the bit maps can be converted from one format to another, as well as changing the code to represent 16-bit color in eddf_ MESS. The files that handle bit-map conversions are the following:

CONVBITM.C
CONVFUNS.C
CONVFUNS.H
CONVINT.C
CONVEXT.C
CONVERT.ASM

Of these, the bulk of the changes will be made in CONVFUNS.H, which is a package of macros for setting pels in memory bit maps. To swap the pels in CONVFUNS.H, the following macros need to be altered (the changes are in the ifdef SWAP16BPP sections):

   /**********************************************************************/
   /* Macro to convert to a 16 bit value in Intel format.                */
   /*                                                                    */
   /* Because XGA bit maps in system memory are stored in Motorola       */
   /* format, this requires swapping the low and high bytes.             */
   /**********************************************************************/

#ifdef SWAP16BPP
#define XGA_EnsureIntel16bpp(word)  (word)
#else
#define XGA_EnsureIntel16bpp(word)                                     \
    ((((word) & 0xFF00) >> 8) | (((word) & 0x00FF) << 8))
#endif


   /**********************************************************************/
   /* Macro to write a 16bpp value into the internal bit map, and to     */
   /* increment the internal bit map pointer to the next 16bpp pel.      */
   /* This must be done in Motorola format (high byte, low byte).        */
   /**********************************************************************/

#ifdef SWAP16BPP
#define XGA_SetInternal16BppPel(value)                                 \
    *((PBYTE)SPad.pbTrgPointer)++ = ((value) & 0xff);                  \
    *((PBYTE)SPad.pbTrgPointer)++ = ((value) >> 8);
#else
#define XGA_SetInternal16BppPel(value)                                 \
    *((PRGB16)SPad.pbTrgPointer)++ = value;
#endif

In addition, to change the R, G, and B components of the 16 bit-pel, alter the macro XGA_RGB16FromPRGB2, which is also in CONVFUNS.H. Next, alter the function ConvertExt8ToInt16, which is in CONVERT.ASM. In that function, there are several xchg al, ah instructions. Remove them. Likewise, in ConverExt24toInt16, you will see raster operation ax, 8. Remove it as well .

Finally, make a change to EDDFFAST.ASM, which holds the eddf_MESS function. In it, near the top of the file, you will see code similar to the following :

        mov     ax, word ptr Shadow8514Regs.Color_1
        xchg    ah, al
        mov     word ptr Shadow8514Regs.Color_1, ax
        mov     ax, word ptr Shadow8514Regs.Color_0
        xchg    ah, al
        mov     word ptr Shadow8514Regs.Color_0, ax
        mov     ax, word ptr Shadow8514Regs.Color_Comp
        xchg    ah, al
        mov     word ptr Shadow8514Regs.Color_Comp, ax

Disable this code. It is near the top of eddf_MESS, and immediately after the label exitMESS. It must be disabled in both places.

The modules listed above, along with EDDBCREA.C are useful to study if you are interested in the creation and conversion of bit maps in the driver.

24-Bit-Per-Pel Support

The various S3 chips do not directly support hardware drawing of packed 24- bit-per-pel modes. Some of them include drawing engine support for 32-bit- per-pel modes, which can be found in the IBM Device Driver Source Kit for OS/2, Version 1.2; but the S3 driver does not support this mode. Instead, the S3 driver attempts to use the drawing engine where it can, and falls back to the frame buffer in situations where it is unable to use the drawing engine. All line drawing is done in software at 24-bits-per-pel. Screen-to-screen copy bitblts can be processed, but fills of any sort, including the monochrome expansion operations, can be performed only if the red, green, and blue components of the color are identical. The drawing engine treats 24-bit-per-pel modes as if they are 8-bit-per-pel modes with extremely wide scanlines. Because the drawing engine is addressing bytes rather than 24-bit pels, it is necessary to triple all coordinates before writing them to the hardware. Note that throughout the driver you will find the following construction for tripling coordinates:

fast3x: ;The fast way to triple ax
        mov     bx, ax
        shl     ax, 1
        add     ax, bx

The following is a faster way to triple ax on a 486 microprocessor.

;       Triple eax
fast3x:
        lea     eax, [eax+2*eax]

In terms of changing the byte ordering of 24-bit-per-pel modes, the S3 driver supports two pel orderings, RGB and BGR. To change between the two, set or clear the bit USE_ATTDAC in DDT.fScreenFlags. The bit-map conversion code looks at this flag and performs the correct function, dependent upon its setting.

In terms of changing the byte ordering of 24-bit-per-pel modes, the S3 driver supports two pel orderings, RGB and BGR. The RGB pel ordering is supported by many RAM DACs and is the 'normal' ordering of pixels in 24-bit modes. In RGB pel ordering, the blue pel is first in memory, followed by the green pel, followed by the red pel. The RGB2 structure is defined with the same pel ordering:

 typedef struct _RGB2 {  /* 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;  /* Reserved, must be zero                  */
     } RGB2;
     typedef RGB2 Far *PRGB2;

GB pel ordering is chosen by setting the USE_ATTDAC bit in the DDT. fScreenFlags. (Although the name of this bit implies that an AT&T** DAC is present, this is not so.) Clearing the USE_ATTDAC bit in the DTT. fScreenFlags forces BGR byte ordering which stores the red pel first, followed by the green pel, followed by the blue pel. The USE_ATTDAC bit forces all bit maps to use RGB byte ordering. Following is an example from CONVEXT.C:

/*********************************************************************/
/* ConvertEx24ToInt24                                                */
/*                                                                   */
/* Converts a single scan ine from external   24bpp   to   internal   24bpp .   * / 
/ *   ( No   convert   table   is   used   a   24   bpp .                                    * / 
/ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * / 
VOID   ConvertExt24ToInt24   ( VOID ) 
{ 
     ULONG         j ; 
     rgb           TrgPel ; 

     for   (   j   =   SPad . cx ;   j - - ; ) 
     { 
         TrgPel   =   * ( ( PRGB ) SPad . pbSrcPointer ) ; 
         if   (   ! ( DDT . fScreenFlags   &   USE _ ATTDAC )   )   { 
             * ( ( PBYTE ) SPad . pbTrgPointer ) + +   =   TrgPel . bBlue ; 
             * ( ( PBYTE ) SPad . pbTrgPointer ) + +   =   TrgPel . bGreen ; 
             * ( ( PBYTE ) SPad . pbTrgPointer ) + +   =   TrgPel . bRed ; 
         } 
         else 
         { 
             * ( ( PBYTE ) SPad . pbTrgPointer ) + +   =   TrgPel . bRed ; 
             * ( ( PBYTE ) SPad . pbTrgPointer ) + +   =   TrgPel . bGreen ; 
             * ( ( PBYTE ) SPad . pbTrgPointer ) + +   =   TrgPel . bBlue ; 
         } 
         SPad . pbSrcPointer   + =   sizeof ( RGB ) ; 
      { 
}   / *   ConvertExt24ToInt24   * / 

When the USE_ATTDAC bit is set, the blue pel is first in memory and when USE_ATTDAC bit is not set, the red pel is first in memory. This is the code that translates an external bit map to an internal bit map. However 24-bit color values are not translated in the same way. This is shown in LogToPhyIndex in EDDCSUBR.C:

#ifdef    BPP24
     else if (DDT.BitCount == 24)
     {
     /*************************************************************/
     /* Map the RGB2 value into an RGB24 value. (24bpp pel value) */
     /*************************************************************/
        if ( !(DDT.fScreenFlags & USE_ATTDAC) ) {
          PhyIndex = RGB24FromPRGB2(&RegRGB);
        }
        else
        {
          PhyIndex = RGBRGB24FromPRGB2(&RegRGB);
        }
     }
#endif

The following RGB24From macros are located in CONVFUNS.H:

#define RGB24FromPRGB2(prgb2)         XGA_RGB24FromPRGB2(prgb2)
#define RGB24FromPRGB2ATT(prgb2)      XGA_RGB24FromPRGB2ATT(prgb2)

#define XGA_RGB24FromPRGB2(prgb2)
      *(PULONG)(prgb2)

#define XGA_RGB24FromPRGB2ATT(prgb2)
    ((((ULONG)((prgb2)->bRed))) |                       \
     (((ULONG)((prgb2)->bGreen)) <<8) |                 \
     (((ULONG)((prgb2)->bBlue)) <<16)  )                \

LogToPhyIndex is the routine responsible for translating the logical RGB2 values passed in from PM to colors that are realizable in the driver. It translates almost every color value used in the driver. When the USE_ATTDAC bit is not set, the color passed in is copied over directly, even though PM passes in RGB format colors. When the USE_ATTDAC bit is set, the color value is byte-swapped to BGR order. The following code in Copy24MonoToVRAM (HWACCESS.ASM) explains why this occurs:

;set the colors to expand to and put them in the correct format
;to write dwords

    mov     edx,Shadow8514Regs.Color_1
    mov     ebx,Shadow8514Regs.Color_0
    ror     dx,8
    ror     edx,16
    ror     dx,8
    ror     edx,8
    ror     bx,8
    ror     ebx,8
    ror     dx,8
    ror     ebx,8

Copy24MonoToVRAM performs monochrome to color expansion in 24-bit-per-pel modes in the S3 driver. Notice that it is performing a byte-swap on the colors that were passed into it as arguments in the Shadow8514Regs. The reason the for this reversed color storage has to do with the implementation of eddf_MESS. In eddf_MESS, 24-bit colors are written in reverse order. Consequently, if your device supports 24-bit-per-pel operations in hardware, you must reverse the bytes of Shadow8514Regs.Color_ 0 and Color1 prior to writing them to the color registers of your hardware.

Strategies for Adapting the Driver to Other Chip Sets

To date, the S3-8514-XGA driver has been ported to work on the various Western Digital** accelerators, The Tseng Labs W32 and W32p**, The ATI** Mach 64, and the ATI Mach 32. Of these, only the ATI Mach 32** is similar to an 8514/A**. The amount of code in the driver that is hardware- dependent is relatively small. Still, this is a large set of source modules, and so it is helpful to know where to begin when changing them.

The first part of this section examines the various strategies that can be adopted for porting this driver, and some of the tradeoffs that they entail . The second part of this section consists of an outline for bringing up the driver on a new graphics chip set.

High-Level Design Decisions

There are three basic approaches that can be taken to adapt the S3 driver to another chip set. All of these approaches differ in how they handle the Shadow8514Regs. The Shadow8514Regs are shared by both the hardware- dependent code and the bit-map drawing code. The eddf_MESS() function relies on the fields in Shadow8514Regs, as well as the eddh_SrcDestBlt function.

Strategy 1 - Change the Shadow8514Regs

Retain the pixmaps and other characteristics of the XGA driver and change the 8514 registers to match the new driver. This is the approach that was taken when the 8514/A driver was ported from the original XGA-code base. This is the most efficient solution, because the values from the new renamed driver can be written directly to the hardware. The tradeoff here is that the bit-map drawing code in EDDFFAST.ASM, FFLINES.ASM, FFBLTSET.ASM , and so forth, use the shadow registers extensively; therefore, modifying them will be a significant portion of the work. The other tradeoff is that functions such as eddn_BitBlt and PixBltThroughClipsViaPhunk make extensive use of these registers, and changing them may mean making significant changes to the logic of these complex functions.

Strategy 2 - Add new definitions to the Shadow Registers

Another strategy is to add definitions to the shadow registers and bit-map header definition to support the new chip set, but leave the XGA and 8514 definitions in place. This has the advantage of allowing the values in the shadow registers to be written directly to hardware. The disadvantage is that much of the setup code for BitBlt, line drawing, and so forth, will have to be changed to accommodate these new register definitions. This strategy will be time-consuming and error-prone.

Strategy 3 - Leave the Shadow Registers As Is

In some ways, this strategy is the easiest approach. It is possible to translate the values written into the Shadow8514Regs to ones used by another chip. The bulk of the driver code never accesses the actual graphics-accelerator hardware. In fact, only the routines in HWACCESS.ASM, such as TransferShadowRegisters, and the routines in EDDHBBLT.ASM, EDDHGCHS .ASM, and so forth, actually write to the hardware. In many cases, it is easy to interpret the values written in the Shadow8514Regs structure, and translate them in TransferShadowRegs. TransferShadowRegs sets up colors, hardware-raster operations, monochrome expansion and color compare. It is called by the highest level portions of the driver, and may get called only once for several operations. As a consequence, performing translations on it is efficient.

Typically, the lower-level routines, such as eddh_PatDestBlt, write the origin, direction, height, and width of the desired BitBlt. These are usually very straightforward to translate from 8514/A format. In effect, this approach treats the shadow registers as hardware-independent descriptions of an accelerator operation that needs to be performed. (The fact that this hardware-independent description happens to be very dependent on the designs of the XGA and 8514 is a workable solution.)

Other Considerations

The S3 driver caches fonts and other monochrome data in off-screen VRAM, and uses the hardware BitBlt engine to expand these to the display. Not all devices are capable of doing this. If your chip set does not have this capability, then the text code will need a considerable amount of work. Another consideration is that the S3 driver treats objects in VRAM as rectangles with an X-Y origin. Some devices work this way, others reference portions of VRAM by address. Some can deal only with off-screen bit maps that have the same pitch as the display. Others can work with off -screen bit maps with packed scan lines or with the scan lines padded to some boundary. These considerations will affect the design of the bit map and font-caching code.

Porting the Code

The following is an outline of a scheme to port the S3 driver to another chip set. Many of the actual working details will be dependent upon your device. The goal is to give you a place to start by showing the first modules to interact directly with the hardware. When some of the functions are working, the kind of design that is needed will become apparent, and you may want to design your own plan.

Initializing the Accelerator

The following is a description for how to set a mode and initialize the accelerator.

1.Edit CACHEMAN.C to account for the resolutions supported by your device, and the memory requirements for those resolutions.

2.Edit the asr[] array in EDDESRES.C to match the resolutions your device can support. (See Multiple Resolution Supportfor information on driver initialization for a description of this array.)

3.Edit the QueryAndSelectNativeMode routine in the EDDESRES.C file. Add code to determine the memory size of the adapter and other configuration information.

4.Edit SetObtainableModes routine in the MODEINFO.C file. In the S3 driver, this function reads the SVGADATA.PMI file and marks modes in the asrScreenResolution table as obtainable, based on what it finds there. It is also possible to directly query the hardware. Another possibility is to discard SetObtainableModes altogether, and modify CACHEMAN.C to validate the available modes based on the amount of VRAM and DAC configuration of the board.

5.Edit QueryAndSelectNativeMode and remove the DMS32CallBack((PFN) ( SwitchToChosenMode). This is almost certainly not what you want to do at this time. For some odd reason, the S3 driver sets the mode twice during initialization. There is no real reason to do this, however.

6.Edit SwitchToExtendedGraphicsMode in SETMODE.C so that it will set the appropriate video mode on your device. This may be done by way of the base -video handler or in assembler code that you write as part of your driver. Process the mode set in the presentation display driver if the video handler is not yet working properly. Adding mode set code to the display driver may let you work while the base video handler is being developed. ( Unless one developer is writing both the base video handler and the Presentation Display Driver).

7.If your device's registers are memory-mapped rather than I/O-mapped, additional changes need to be made to FillPdb(). In the S3 driver, a flat pointer to the video aperture is obtained after the mode set and KlugeReset (). This will not work for a memory-mapped device. Move the first call to GetVRAMPointer() so it occurs before the first drawing-engine operation. ( It does not matter the order in which GetVRAMPointer is called.) Also, if your device supports an aperture, this is a good place to test if the aperture-to-video memory has been properly performed. (See Obtaining Pointers to Video Memoryfor details on how to do this.) To test this, create a small routine that copies a fixed bit map to the screen through the aperture. If this routine generates a page fault exception (TRAP 0E), then you do not have a valid pointer to the aperture.

8.Edit KlugeReset (in HWACCESS.ASM) so it can reset the accelerator and clear the screen. Assemble code in an INT 3 immediately after the code that resets the accelerator. For debugging purposes, create some small routines that perform a few basic drawing operations on the display using the accelerator . This is a good test to ensure that everything is set up correctly. (If your drawing engine is not set correctly, nothing in the driver is going to work.) Also, remove any code from the various pieces of initialization code that runs on an S3 chip rather than your chip set.

9.At this point, some code may need to be debugged. Put an _asm {INT 3} in FillPdb() (EDDEFPDB.C), immediately before the call to QueryAndSelectNativeMode(). (The _asm {INT 3} will cause an INT 3 instruction to be inserted in the code, which will cause the kernel debugger to break when it reaches that point.) Build the driver and run it under the debug kernel. If the INT 3 you previously added is reached, the debugging has been successful. If you are unable to reach the INT 3, try adding one to the beginning of FillLdb() in EDDEFLDB.C. This occurs early in the driver. If you are unable get to there, add one in the LOADPROC in DYNA32.ASM. This is the very first entry into the driver. If you are unable to get there, then you are not successfully building the driver. Look at your make file for any inconsistencies.

10.Continue going through routines debugging until you successfully get to KlugeReset. At this point, you will be in a graphics mode. Step through the code that enables the drawing engine of your chip, and test it with the small routines that were written in step 7. Continue until you get a good mode set, have the drawing engine enabled, and are able to do some simple drawing commands inside the KlugeReset routine.

The First BitBlt

The first operations performed by the driver are in BitBlt. Edit EDDHBBLT. ASM, modifying it to work with your hardware. The following are guidelines you can use:

1.The very first BitBlt processed in the driver is a pattern blt performed by eddh_PatDestBlt (in EDDHBBLT.ASM). This paints the gray background screen in 8-bit-per-pel mode. (The seemingly solid gray is a 2x2 dither.) Consequently, eddh_PatDestBlt is the first part of the driver to modify.

2.Modify TransferShadowRegisters in HWACCESS.ASM. This routine sets the color, raster operation, and other operation-specific parameters. If you do not want to perform this operation, you can temporarily get the color, pattern, and other information needed to complete the blt from the Shadow8514Regs, and the AIxfer parameter block, and put code in-line in eddh_PatDestBlt to set these parameters. Eventually, return and make TransferShadowRegisters work correctly.

3.When eddh_PatDestBlt is working, modify eddh_SrcDestBlt and eddh_ DestOnlyBlt, in that order. eddh_SrcDestBlt consists of several cases. The easiest portion to modify is the part that deals with VRAM-to-VRAM blts . Bring up the portion which copies color bit maps in system memory to the display. (This is used early in the construction of the desktop.)

4.Modify CopyMemoryToVRAM in HWACCESS.ASM at this time using the aperture- to-VRAM on your video device. For the most part, the S3 driver uses the drawing engine to copy system-memory bit maps to VRAM. This option may not be available on your device. (Or, it may be more efficient on your device to use the aperture.)

5.Edit EDDHLINE.ASM and EDDHSCAN.ASM, and ifdef out any code that draws anything with the S3 hardware. This will allow these functions to be called without hanging the driver. Likewise, ifdef out the code in EDDHGCHS .ASM. This will temporarily disable text. (If this is performed carefully , mark the places where you need to insert code for your device.)

6.When eddh_PatDestBlt, eddh_SrcDestBlt, and eddh_DestOnlyBlt are working, the presentation desktop (with no text) appears.

7.If caching either monochrome or color bit maps is undesirable during the development of eddh_SrcDestBlt, you can disable one or both of them in PIXBLT.C. (See BitBltfor further information.)

The Cursor

1.Edit CACHEMAN.C so off-screen memory is allocated for the hardware cursor. Remember that cursors can be larger than 32 x 32

2.Edit the eddm_DeviceSetCursor function in the EDDMCURS.C file so it copies the AND and XOR masks into off-screen VRAM. The primary change will be to reformat the incoming AND and XOR masks into a form suitable for use by the hardware cursor.

3.Edit EDDCURSR.ASM, and add code to support the hardware cursor.

Text Output

After BitBlt is functioning, create text output. (If more than one developer is working on the driver, then text and BitBlt can be done simultaneously, when the driver is correctly initialized and some of the rudiments of BitBlt are functional.)

1.The first task is to modify the caching code in EDDNCACH.C so it copies the character bit maps into off-screen VRAM in a format suitable for your hardware. If your hardware is incapable of VRAM-to-VRAM monochrome expansion, set CharTooBig to be TRUE in EDDNGCHS.ASM, and let BitBlt handle text output until a non-cached scheme is created.

2.The routines that handle caching are eddt_CacheCharacter, in EDDNCACH.C, and Cache8514Char, in EDDHGCHS.ASM. Cache8514Char may be unnecessary for your device. A memcpy may work just as well.

3.Modify eddh_DrawText in EDDHGCHS.ASM. Most of the modifications will probably be confined to the sections marked IFDEF HARD_DRAW ... IFDEF _ 8514.

4.Debug the above code. It is difficult to debug the character-caching code without actually drawing any characters. Unless the character-caching code is working, it is impossible to draw any characters correctly.

Miscellaneous

1.Modify EDDHLINE.ASM and bring up line drawing.

2.Modify EDDHSCAN.ASM, and bring up scanlines. At this point, the presentation desktop should appear complete.

3.Modify EDDHAVIO.ASM, and ensure the AVIO text is functioning. (Test with OS/2 window sessions.)

4.Modify EDDMDEAD.C so that death and resurrection are supported. (Test with a full-screen OS/2 session.)

5.Modify EDDHIMAG.ASM, and bring up image data. (Use the tune editor to test this.)

6.Finish any routines in HWACCESS.ASM that have not already been ported.

7.Write code for your device to support the color cursor in EDDCURSR.ASM. (Test with the Solitaire program using auto-play mode.)

Debugging Tips

Debugging the S3 driver is difficult because the kernel debugger does not support source-level debugging of C code. The bulk of the code that must be modified is in assembler, and the kernel debugger handles this adequately. However, there will be occasions when the C portions of the driver must be modified and debugged. Some of the C functions are quite large, and have no internal symbols that are public. Therefore, if you trap in the middle of a large C function, it is often difficult to determine the problem. Also, if you need to set a breakpoint in the middle of a C function, it is often difficult to know precisely where to put it. The way around this particular problem is to put INT 3 instructions near the portion of the code where you suspect the problem to occur. There are two ways to do this . One way is to insert a call to the function haltproc() into the C code. The other is to add the following statement:

_asm {int 3};

Usually it is more convenient to add the _asm {INT 3} statement, as this breaks into the debugger at the point in the code at which you are interested. The haltproc() routine will also break into the kernel debugger , but it is less convenient because you have to trace out of haltproc() to see the real breakpoint location.

Most of the data in this driver is passed around in data structures, such as AIxfer. It is possible to dump these structures easily, even if they are being manipulated by C code. This tends to be easier than dumping stack frames. The ability to recognize which assembler code corresponds to a particular C language statement is necessary when debugging the portions of the driver that are written in C. However, using the C compiler to generate an assembler language version of the module is also helpful. This is accomplished using the /Fa compiler option. Also, when debugging C code , use /Od, which disables optimizations. This makes the code easier to follow.

The first time you build and test your driver, there is a possibility that it might not load, or that it will load, trap, and then immediately unload. The first challenge you face is getting the driver to load, initialize, and set the desired video mode. The first place to set a breakpoint is either loadproc(), which is in DYNA32.ASM, or in XGA_DLLInit, which is in INIT.C. Also, OS2_PM_DRV_ENABLE, in EDDENABL.C, is a good place to break, as it is called very early in the initialization process. FillLdb(), in EDDEFLDB.C, is another place to break. It is the first function in the driver that does any real work. FillPdb()in EDDEFPDB.C, and QueryAndSelectNativeMode(), in EDDESRES.C, are also good candidates for break points. You might want to trace through FillLdb(), FillPdb(), and QueryAndSelectNativeMode() until the driver initialization phase is stable. Any problems thus far are very likely to be in one of these three functions, or in a function that they call.

Some other good breakpoint locations include eddh_SrcDestBlt, eddh_ PatDestBlt, eddh_DestOnlyBlt, eddh_DrawText, eddh_PMLINES, eddh_PMSCANLINE, and eddh_PMIMAGEDATA. Many early problems will be drawing related and will be confined to one of these functions.

If a trap error occurs, such as trap d (General protection error) or trap e , use the "vcf*" debugger command to break on instructions that cause traps . When the debugger breaks on the offending instruction, use "ln" (list near) to give you a nearby label, and also the "ks" to give you a stack trace, which gives a "map" detailing where you have been.

Often graphics chips must be polled to determine if they are ready to accept another command. Consider making the polling loop a macro. In the macro, for debugging mode only, add a drop-dead timer, such as counting down "ecx" from 1,000,000. If the "timer" expires, fall through to an INT 3, so the debugger breaks. This enables you to find situations where the driver will hang while waiting on the video chip. Typically, this is caused by a programming error such as an invalid command to the graphics chip.

Consider using Debug32Output to print a trace of the functions called in the driver when you are unable to determine your present location. The following is an example that traces every major driver entry point.

pmtrace.asm:


.386p

_DATA   segment dword use32 public 'DATA'
_DATA   ends

trace   macro   fn
        _DATA   segment
        s_&fn   db      '&fn, ', 0
        _DATA   ends

        extrn   fn : near
        public  T&fn
        T&fn proc near
                push    offset ds:s_&fn
                call    Debug32Output
                pop     eax
                jmp     fn
        T&fn endp

        endm

_TEXT   segment use32 dword public 'CODE'
        assume  cs:FLAT, ds:FLAT, es:FLAT

extrn   Debug32Output : near

trace eddl_PolyLine
trace eddl_GetCurrentPosition
trace eddl_SetCurrentPosition
trace eddl_DrawLinesInPath
trace eddl_PolyShortLine
trace edds_PolyScanLine
trace DrawBits
trace eddb_DeviceCreatebit map
trace eddb_DeviceDeletebit map
trace eddb_DeviceSelectbit map
trace eddb_BitBlt
trace eddb_GetPel
trace eddb_SetPel
trace eddb_ImageData
trace ScanLR
trace eddm_SaveScreenBits
trace eddb_DrawBorder
trace eddm_DeviceSetCursor
trace Getbit mapBits
trace Setbit mapBits
trace eddm_SetColorCursor
trace eddt_CharString
trace eddt_CharStringPos
trace eddb_PolyMarker
trace eddv_CharRect
trace eddv_CharStr
trace eddv_ScrollRect
trace eddv_UpdateCursor
trace edda_DeviceGetAttribut
trace eddv_DeviceSetAVIOFont2
trace edda_GetPairKerningTable
trace edda_DeviceSetAttributes
trace edda_DeviceSetGlobalAttribute
trace edda_NotifyClipChange
trace eddm_NotifyTransformChange
trace edda_RealizeFont
trace eddm_ErasePS
trace eddl_SetStyleRatio
trace edda_DeviceQueryFontAttributes
trace edda_DeviceQueryFonts
trace edda_DeviceInvalidateVisRegion
trace eddg_GetPickWindow
trace eddg_SetPickWindow
trace eddg_ResetBounds
trace eddg_GetBoundsData
trace eddg_AccumulateBounds
trace edda_GetCodePage
trace edda_SetCodePage
trace eddm_LockDevice
trace eddm_UnlockDevice
trace eddm_Death
trace eddm_Resurrection
trace edda_GetDCOrigin
trace edda_DeviceSetDCOrigin
trace eddl_GetLineOrigin
trace eddl_SetLineOrigin
trace eddl_GetStyleRatio
trace eddc_QueryColorData
trace eddc_QueryLogColorTable
trace eddc_CreateLogColorTable
trace eddc_RealizeColorTable 
trace   eddc _ UnrealizeColorTable 
trace   eddc _ QueryRealColors 
trace   eddc _ QueryNearestColor 
trace   eddc _ QueryColorIndex 
trace   eddc _ QueryRGBColor 
trace   eddq _ QueryDevicebit   maps 
trace   eddq _ QueryDeviceCaps 
trace   eddq _ Escape 
trace   eddq _ QueryHardcopyCaps 
trace   eddm _ QueryDevResource 
trace   DeviceCreatePalette 
trace   DeviceDeletePalette 
trace   DeviceSetPaletteEntries 
trace   DeviceAnimatePalette 
trace   DeviceResizePalette 
trace   RealizePalette 
trace   QueryHWPaletteInfo 
trace   UpdateColors 
trace   QueryPaletteRealization 

_ TEXT     ends 

         end 

This file, along with the following changes to EDDEFLDB.C will cause the name of every driver entry point that is called to be printed on the debug terminal:

//Changes to eddefldb.c - Replace real driver entry points with dummies
//that print a trace, and then call the real entry point.
DSPENTRY Teddl_PolyLine ();
DSPENTRY Teddl_GetCurrentPosition ();
DSPENTRY Teddl_SetCurrentPosition ();
DSPENTRY Teddl_DrawLinesInPath ();
DSPENTRY Teddl_PolyShortLine ();
DSPENTRY Tedds_PolyScanLine ();
DSPENTRY TGetScreenBits ();
DSPENTRY TSetScreenBits ();
DSPENTRY TDrawBits ();
DSPENTRY Teddb_DeviceCreatebit map ();
DSPENTRY Teddb_DeviceDeletebit map ();
DSPENTRY Teddb_DeviceSelectbit map ();
DSPENTRY Teddb_BitBlt ();
DSPENTRY Teddb_GetPel ();
DSPENTRY Teddb_SetPel ();
DSPENTRY Teddb_ImageData ();
DSPENTRY TScanLR ();
DSPENTRY Teddm_SaveScreenBits ();
DSPENTRY Teddb_DrawBorder ();
DSPENTRY Teddm_DeviceSetCursor ();
DSPENTRY TGetbit mapBits ();
DSPENTRY TSetbit mapBits ();
DSPENTRY Teddm_SetColorCursor ();
DSPENTRY Teddt_CharString ();
DSPENTRY Teddt_CharStringPos ();
DSPENTRY Teddb_PolyMarker ();
DSPENTRY Teddv_CharRect ();
DSPENTRY Teddv_CharStr ();
DSPENTRY Teddv_ScrollRect ();
DSPENTRY Teddv_UpdateCursor ();
DSPENTRY Tedda_DeviceGetAttributes ();
DSPENTRY Teddv_DeviceSetAVIOFont2 ();
DSPENTRY Tedda_GetPairKerningTable ();
DSPENTRY Tedda_DeviceSetAttributes ();
DSPENTRY Tedda_DeviceSetGlobalAttribute ();
DSPENTRY Tedda_NotifyClipChange ();
DSPENTRY Teddm_NotifyTransformChange ();
DSPENTRY Tedda_RealizeFont ();
DSPENTRY Teddm_ErasePS ();
DSPENTRY Teddl_SetStyleRatio ();
DSPENTRY Tedda_DeviceQueryFontAttributes ();
DSPENTRY Tedda_DeviceQueryFonts ();
DSPENTRY Tedda_DeviceInvalidateVisRegion ();
DSPENTRY Teddg_GetPickWindow ();
DSPENTRY Teddg_SetPickWindow ();
DSPENTRY Teddg_ResetBounds ();
DSPENTRY Teddg_GetBoundsData ();
DSPENTRY Teddg_AccumulateBounds ();
DSPENTRY Tedda_GetCodePage ();
DSPENTRY Tedda_SetCodePage ();
DSPENTRY Teddm_LockDevice ();
DSPENTRY Teddm_UnlockDevice ();
DSPENTRY Teddm_Death ();
DSPENTRY Teddm_Resurrection ();
DSPENTRY Tedda_GetDCOrigin ();
DSPENTRY Tedda_DeviceSetDCOrigin ();
DSPENTRY Teddl_GetLineOrigin ();
DSPENTRY Teddl_SetLineOrigin ();
DSPENTRY Teddl_GetStyleRatio ();
DSPENTRY Teddc_QueryColorData ();
DSPENTRY Teddc_QueryLogColorTable ();
DSPENTRY Teddc_CreateLogColorTable ();
DSPENTRY Teddc_RealizeColorTable ();
DSPENTRY Teddc_UnrealizeColorTable ();
DSPENTRY Teddc_QueryRealColors ();
DSPENTRY Teddc_QueryNearestColor ();
DSPENTRY Teddc_QueryColorIndex ();
DSPENTRY Teddc_QueryRGBColor ();
DSPENTRY Teddq_QueryDevicebit maps ();
DSPENTRY Teddq_QueryDeviceCaps ();
DSPENTRY Teddq_Escape ();
DSPENTRY Teddq_QueryHardcopyCaps ();
DSPENTRY Teddm_QueryDevResource ();
DSPENTRY TDeviceCreatePalette ();
DSPENTRY TDeviceDeletePalette ();
DSPENTRY TDeviceSetPaletteEntries ();
DSPENTRY TDeviceAnimatePalette ();
DSPENTRY TDeviceResizePalette ();
DSPENTRY TRealizePalette ();
DSPENTRY TQueryHWPaletteInfo ();
DSPENTRY TUpdateColors ();
DSPENTRY TQueryPaletteRealization ();
#define C(F) F                  /* Just call it */
#if 1
#define T(F) T##F               /* Print trace message and call */
#else
#define T(F) F                  /* Print trace message and call */
#endif
PPFNL   EnginesDispatchTable;
PFNL    DriversDispatchTable[] = {
    C(0),                            //GreGetArcParameters
0x4000
    C(0),                            //GreSetArcParameters
0x4001
    C(0),                            //GreArc
0x4002
    C(0),                            //GrePartialArc
0x4003
    C(0),                            //GreFullArcInterior
0x4004
    C(0),                            //GreFullArcBoundary
0x4005
    C(0),                            //GreFullArcBoth
0x4006
    C(0),                            //GreBoxInterior
0x4007
    C(0),                            //GreBoxBoundary
0x4008
    C(0),                            //GreBoxBoth
0x4009
    C(0),                            //GrePolyFillet
0x400A
    C(0),                            //GrePolyFilletSharp
0x400B
    C(0),                            //GrePolySpline
0x400C
    C(0),                            //GreDrawConicsInPath
0x400D
    C(0),                            //GreCookWholePath
0x400E
    C(0),                            //GreCookPathCurves
0x400F
    C(0),                            //
0x4010
    C(0),                            //GreRenderPath
0x4011
#ifdef DCAF
//DCAF
    C(OpenScreenChangeArea),
//GreOpenScreenChangeArea 0x4012//DCAF
    C(GetScreenChangeArea),
//GreGetScreenChangeArea       0x4013//DCAF
    C(CloseScreenChangeArea),
//GreCloseScreenChangeArea     0x4014//DCAF
#else
//DCAF
    C(0),                            //
0x4012
    C(0),                            //
0x4013
    C(0),                            //
0x4014
#endif
//DCAF
    C(0),                            //
0x4015
    T(eddl_PolyLine),                //GreDisjointLines
0x4016
    T(eddl_GetCurrentPosition),      //GreGetCurrentPosition
0x4017
    T(eddl_SetCurrentPosition),      //GreSetCurrentPosition
0x4018
    T(eddl_PolyLine),                //GrePolyLine
0x4019
    T(eddl_DrawLinesInPath),          / / GreDrawLinesInPath 
0x401A 
     T ( eddl _ PolyShortLine ) ,              / / GrePolyShortLine 
0x401B 
     T ( edds _ PolyScanLine ) ,               / / GrePolyScanline 
0x401C 
# ifdef   DCAF 
/ / DCAF 
     T ( GetScreenBits ) ,                   / / GreGetScreenBits 
0x401D / / DCAF 
     T ( SetScreenBits ) ,                   / / GreSetScreenBits 
0x401E / / DCAF 
# else 
/ / DCAF 
     C ( 0 ) ,                                / / 
0x401D 
     C ( 0 ) ,                                / / 
0x401E 
# endif 
/ / DCAF 
     C ( 0 ) ,                                / / 
0x401F 
     C ( 0 ) ,                                / / 
0x4020 
     C ( 0 ) ,                                / / 
0x4021 
     T ( DrawBits ) ,                         / / GreDrawBits 
0x6022 
     T ( eddb _ DeviceCreatebit   map ) ,        / / GreDeviceCreatebit   map 
0x6023 
     T ( eddb _ DeviceDeletebit   map ) ,        / / GreDeviceDeletebit   map 
0x4024 
     C ( eddb _ DeviceSelectbit   map ) ,        / / GreDeviceSelectbit   map 
0x4025 
     T ( eddb _ BitBlt ) ,                     / / GreBitblt 
0x6026 
     T ( eddb _ GetPel ) ,                     / / GreGetPel 
0x6027 
     T ( eddb _ SetPel ) ,                     / / GreSetPel 
0x4028 
     T ( eddb _ ImageData ) ,                  / / GreImageData 
0x4029 
     T ( ScanLR ) ,                           / / GreScanLR 
0x602A 
     C ( 0 ) ,                                / / GreFloodFill 
0x602B 
     T ( eddm _ SaveScreenBits ) ,            / / GreSaveScreenBits 
0x402C 
     C ( 0 ) ,                                / / GreRestoreScreenBits 
0x402D 
     T ( eddb _ DrawBorder ) ,                 / / GreDrawBorder 
0x602E 
     T ( eddm _ DeviceSetCursor ) ,           / / GreDeviceSetCursor 
0x402F 
     T ( Getbit   mapBits ) ,                   / / GreGetbit   mapBits 
0x6030 
     T ( Setbit   mapBits ) ,                   / / GreSetbit   mapBits 
0x6031 
     T ( eddm _ SetColorCursor ) ,            / / GreSetColorCursor 
0x4032 
     C ( 0 ) ,                                / / 
0x4033 
     C ( 0 ) ,                                / / 
0x4034 
     T ( eddt _ CharString ) ,                 / / GreCharString 
0x5035 
     T ( eddt _ CharStringPos ) ,              / / GreCharStringPos 
0x7036 
     C ( 0 ) ,                                / / GreQueryTextBox 
0x5037 
     C ( 0 ) ,                                / / GreQueryCharPositions 
0x5038 
     C ( 0 ) ,                                / / GreQueryWidthTable 
0x5039 
     T ( eddb _ PolyMarker ) ,                 / / GrePolyMarker 
0x403A 
     T ( eddv _ CharRect ) ,                   / / GreCharRect 
0x403B 
     T ( eddv _ CharStr ) ,                    / / GreCharStr 
0x403C 
     T ( eddv _ ScrollRect ) ,                 / / GreScrollRect 
0x403D 
     T ( eddv _ UpdateCursor ) ,               / / GreUpdateCursor 
0x403E 
     C ( 0 ) ,                                / / 
0x403F 
     C ( 0 ) ,                                / / 
0x4040 
     C ( 0 ) ,                                / / 
0x4041 
     C ( 0 ) ,                                / / 
0x4042 
     C ( 0 ) ,                                / / 
0x4043 
     C ( 0 ) ,                                / / 
0x4044 
     C ( 0 ) ,                                / / 
0x4045 
     C ( 0 ) ,                                / / GreBeginArea 
0x4046 
     C ( 0 ) ,                                / / GreEndArea 
0x4047 
     C ( 0 ) ,                                / / GreBeginPath 
0x4048 
     C ( 0 ) ,                                / / GreEndPath 
0x4049 
     C ( 0 ) ,                                / / GreCloseFigure 
0x404A 
     C ( 0 ) ,                                / / GreFillPath 
0x404B 
     C ( 0 ) ,                                / / GreOutlinePath 
0x404C 
     C ( 0 ) ,                                / / GreModifyPath 
0x404D 
     C ( 0 ) ,                                / / GreStrokePath 
0x404E 
     C ( 0 ) ,                                / / GreSelectClipPath 
0x404F 
     C ( 0 ) ,                                / / GreSavePath 
0x4050 
     C ( 0 ) ,                                / / GreRestorePath 
0x4051 
     C ( 0 ) ,                                / / GreClip1DPath 
0x4052 
     C ( 0 ) ,                                / / GreDrawRawPath 
0x4053 
     C ( 0 ) ,                                / / GreDrawCookedPath 
0x4054 
     C ( 0 ) ,                                / / GreAreaSetAttributes 
0x6055 
     C ( 0 ) ,                                / / GrePolygon 
0x4056 
     C ( 0 ) ,                                / / GrePathToRegion 
0x4057 
     C ( 0 ) ,                                / / GreDrawRLE 
0x4058 
     C ( 0 ) ,                                / / 
0x4059 
     C ( 0 ) ,                                / / 
0x405A 
     C ( 0 ) ,                                / / 
0x405B 
     C ( 0 ) ,                                / / 
0x405C 
     C ( 0 ) ,                                / / GreGetRegionBox 
0x405D 
     C ( 0 ) ,                                / / GreGetRegionRects 
0x405E 
     C ( 0 ) ,                                / / GreOffsetRegion 
0x405F 
     C ( 0 ) ,                                / / GrePtInRegion 
0x4060 
     C ( 0 ) ,                                / / GreRectInRegion 
0x4061 
     C ( 0 ) ,                                / / GreCreateRectRegion 
0x4062 
     C ( 0 ) ,                                / / GreDestroyRegion 
0x4063 
     C ( 0 ) ,                                / / GreSetRectRegion 
0x4064 
     C ( 0 ) ,                                / / GreCombineRegion 
0x4065 
     C ( 0 ) ,                                / / GreCombineRectRegion 
0x4066 
     C ( 0 ) ,                                / / GreCombineShortLineRegion 
0x4067 
     C ( 0 ) ,                                / / GreEqualRegion 
0x4068 
     C ( 0 ) ,                                / / GrePaintRegion 
0x4069 
     C ( 0 ) ,                                / / GreSetRegionOwner 
0x406A 
     C ( 0 ) ,                                / / GreFrameRegion 
0x406B 
     C ( 0 ) ,                                / / 
0x406C 
     C ( 0 ) ,                                / / 
0x406D 
     C ( 0 ) ,                                / / GreGetClipBox 
0x406E 
     C ( 0 ) ,                                / / GreGetClipRects 
0x406F 
     C ( 0 ) ,                                / / GreOffsetClipRegion 
0x4070 
     C ( 0 ) ,                                / / GrePtVisible 
0x4071 
     C ( 0 ) ,                                / / GreRectVisible 
0x4072 
     C ( 0 ) ,                                / / GreQueryClipRegion 
0x4073 
     C ( 0 ) ,                                / / GreSelectClipRegion 
0x4074 
     C ( 0 ) ,                                / / GreIntersectClipRectangle 
0x4075 
     C ( 0 ) ,                                / / GreExcludeClipRectangle 
0x4076 
     C ( 0 ) ,                                / / GreSetXformRect 
0x4077 
     C ( 0 ) ,                                / / 
0x4078 
     C ( 0 ) ,                                / / 
0x4079 
     C ( 0 ) ,                                / / 
0x407A 
     C ( 0 ) ,                                / / GreSaveRegion 
0x407B 
     C ( 0 ) ,                                / / GreRestoreRegion 
0x407C 
     C ( 0 ) ,                                / / GreClipPathCurves 
0x407D 
     C ( 0 ) ,                                / / GreSelectPathRegion 
0x407E 
     C ( 0 ) ,                                / / GreRegionSelectbit   map 
0x407F 
     C ( 0 ) ,                                / / GreCopyClipRegion 
0x4080 
     C ( 0 ) ,                                / / GreSetupDC 
0x4081 
     C ( 0 ) ,                                / / 
0x4082 
     C ( 0 ) ,                                / / GreGetPageUnits 
0x4083 
     C ( 0 ) ,                                / / GreSetPageUnits 
0x4084 
     C ( 0 ) ,                                / / GreGetModelXform 
0x4085 
     C ( 0 ) ,                                / / GreSetModelXform 
0x4086 
     C ( 0 ) ,                                / / GreGetWindowViewportXform 
0x4087 
     C ( 0 ) ,                                / / GreSetWindowViewportXform 
0x4088 
     C ( 0 ) ,                                / / GreGetGlobalViewingXform 
0x4089 
     C ( 0 ) ,                                / / GreSetGlobalViewingXform 
0x408A 
     C ( 0 ) ,                                / / GreSaveXformData 
0x408B 
     C ( 0 ) ,                                / / GreRestoreXformData 
0x408C 
     C ( 0 ) ,                                / / GreGetPageViewport 
0x408D 
     C ( 0 ) ,                                / / GreSetPageViewport 
0x408E 
     C ( 0 ) ,                                / / 
0x408F 
     C ( 0 ) ,                                / / 
0x4090 
     C ( 0 ) ,                                / / GreGetGraphicsField 
0x4091 
     C ( 0 ) ,                                / / GreSetGraphicsField 
0x4092 
     C ( 0 ) ,                                / / GreGetViewingLimits 
0x4093 
     C ( 0 ) ,                                / / GreSetViewingLimits 
0x4094 
     C ( 0 ) ,                                / / GreQueryViewportSize 
0x4095 
     C ( 0 ) ,                                / / GreConvert 
0x4096 
     C ( 0 ) ,                                / / GreConvertPath 
0x4097 
     C ( 0 ) ,                                / / GreSaveXform 
0x4098 
     C ( 0 ) ,                                / / GreRestoreXform 
0x4099 
     C ( 0 ) ,                                / / GreMultiplyXforms 
0x409A 
     C ( 0 ) ,                                / / GreConvertWithMatrix 
0x409B 
     C ( 0 ) ,                                / / 
0x409C 
     T ( edda _ DeviceGetAttributes ) ,       / / GreDeviceGetAttributes 
0x609D 
     T ( eddv _ DeviceSetAVIOFont2 ) ,        / / GreDeviceSetAVIOFont2 
0x409E 
     C ( 0 ) ,                                / / 
0x409F 
     T ( edda _ GetPairKerningTable ) ,       / / GreGetPairKerningTable 
0x40A0 
     C ( 0 ) ,                                / / GreDeviceSetAVIOFont 
0x40A1 
     T ( edda _ DeviceSetAttributes ) ,       / / GreDeviceSetAttributes 
0x60A2 
     C ( edda _ DeviceSetGlobalAttribute ) ,      / / GreDeviceSetGlobalAttribut 
0x60A3 
     C ( edda _ NotifyClipChange ) ,          / / GreNotifyClipChange 
0x40A4 
     T ( eddm _ NotifyTransformChange ) ,     / / GreNotifyTransformChange 
0x40A5 
     T ( edda _ RealizeFont ) ,                / / GreRealizeFont 
0x40A6 
     T ( eddm _ ErasePS ) ,                    / / GreErasePS 
0x40A7 
     T ( eddl _ SetStyleRatio ) ,              / / GreSetStyleRatio 
0x40A8 
     T ( edda _ DeviceQueryFontAttributes ) , / / GreDeviceQueryFontAttributes 
0x40A9 
     T ( edda _ DeviceQueryFonts ) ,          / / GreDeviceQueryFonts 
0x40AA 
     C ( edda _ DeviceInvalidateVisRegion ) , / / GreDeviceInvalidateVisRegion 
0x40AB 
     T ( eddg _ GetPickWindow ) ,              / / GreGetPickWindow 
0x40AC 
     T ( eddg _ SetPickWindow ) ,              / / GreSetPickWindow 
0x40AD 
     C ( eddg _ ResetBounds ) ,                / / GreResetBounds 
0x40AE 
     C ( eddg _ GetBoundsData ) ,              / / GreGetBoundsData 
0x40AF 
     C ( eddg _ AccumulateBounds ) ,          / / GreAccumulateBounds 
0x40B0 
     C ( 0 ) ,                                / / GreGetExtraError 
0x40B1 
     C ( 0 ) ,                                / / GreSetExtraError 
0x40B2 
     C ( edda _ GetCodePage ) ,                / / GreGetCodePage 
0x40B3 
     C ( edda _ SetCodePage ) ,                / / GreSetCodePage 
0x40B4 
     C ( eddm _ LockDevice ) ,                 / / GreLockDevice 
0x40B5 
     C ( eddm _ UnlockDevice ) ,               / / GreUnlockDevice 
0x40B6 
     T ( eddm _ Death ) ,                      / / GreDeath 
0x40B7 
     T ( eddm _ Resurrection ) ,               / / GreResurrection 
0x40B8 
     C ( 0 ) ,                                / / 
0x40B9 
     C ( edda _ GetDCOrigin ) ,                / / GreGetDCOrigin 
0x40BA 
     C ( edda _ DeviceSetDCOrigin ) ,         / / GreDeviceSetDCOrigin 
0x40BB 
     T ( eddl _ GetLineOrigin ) ,              / / GreGetLineOrigin 
0x40BC 
     T ( eddl _ SetLineOrigin ) ,              / / GreSetLineOrigin 
0x40BD 
     T ( eddl _ GetStyleRatio ) ,              / / GreGetStyleRatio 
0x40BE 
     C ( 0 ) ,                                / / 
0x40BF 
     C ( 0 ) ,                                / / 
0x40C0 
     C ( 0 ) ,                                / / 
0x40C1 
     C ( 0 ) ,                                / / 
0x40C2 
     T ( eddc _ QueryColorData ) ,            / / GreQueryColorData 
0x60C3 
     T ( eddc _ QueryLogColorTable ) ,        / / GreQueryLogColorTable 
0x60C4 
     C ( eddc _ CreateLogColorTable ) , 
/ / GreCreateLogColorTable       0x60C5 
     T ( eddc _ RealizeColorTable ) ,         / / GreRealizeColorTable 
0x60C6 
     T ( eddc _ UnrealizeColorTable ) , 
/ / GreUnrealizeColorTable       0x60C7 
     T ( eddc _ QueryRealColors ) ,           / / GreQueryRealColors 
0x40C8 
     C ( eddc _ QueryNearestColor ) ,         / / GreQueryNearestColor 
0x40C9 
     C ( eddc _ QueryColorIndex ) ,           / / GreQueryColorIndex 
0x60CA 
     T ( eddc _ QueryRGBColor ) ,              / / GreQueryRGBColor 
0x60CB 
     C ( 0 ) ,                                / / 
0x40CC 
     C ( 0 ) ,                                / / 
0x40CD 
     C ( 0 ) ,                                / / 
0x40CE 
     C ( 0 ) ,                                / / 
0x40CF 
     T ( eddq _ QueryDevicebit   maps ) ,        / / GreQueryDevicebit   maps 
0x40D0 
     C ( eddq _ QueryDeviceCaps ) ,           / / GreQueryDeviceCaps 
0x40D1 
     T ( eddq _ Escape ) ,                     / / GreEscape 
0x40D2 
     T ( eddq _ QueryHardcopyCaps ) ,         / / GreQueryHardcopyCaps 
0x40D3 
     C ( eddm _ QueryDevResource ) ,          / / GreQueryDevResource2 
0x40D4 
     T ( DeviceCreatePalette ) ,            / / GreDeviceCreatePalette 
0x40D5 
     T ( DeviceDeletePalette ) ,            / / GreDeviceDeletePalette 
0x40D6 
     T ( DeviceSetPaletteEntries ) ,        / / GreDeviceSetPaletteEntries 
0x40D7 
     T ( DeviceAnimatePalette ) ,           / / GreDeviceAnimatePalette 
0x40D8 
     T ( DeviceResizePalette ) ,            / / GreDeviceResizePalette 
0x40D9 
     T ( RealizePalette ) ,                  / / GreRealizePalette 
0x40DA 
     T ( QueryHWPaletteInfo ) ,              / / GreQueryHWPaletteInfo 
0x40DB 
     T ( UpdateColors ) ,                    / / GreUpdateColors 
0x40DC 
     T ( QueryPaletteRealization ) ,        / / GreQueryPaletteRealization 
0x40DD 
     C ( 0 ) ,                                / / GreGetVisRects 
0x40DE 
     C ( 0 ) ,                                / / GreDevicePolySet 
0x40DF 
} ; 

The T() macro in EDDEFLDB.C appends a "T" to the beginning of each entry point in the driver. The trace macro in PMTRACE.ASM creates a function with the name "T", in addition to the name of the real entry point. It then prints out the name of the entry point with Debug32Output, and then calls the real driver entry point.

If your driver supports cached-monochrome bit maps, it is often difficult to determine if the code is working correctly while copying monochrome bit maps from system memory to the display in eddh_SrcDestBlt. Almost any monochrome bit map will fit into the bit-map cache, because monochrome bit maps are small. As a result, the code in eddh_SrcDestBlt that handles monochrome data is rarely used. Disabling monochrome bit-map caching in PixBltThroughClipsViaPhunk() enables you to exercise the monochrome code in eddh_SrcDestBlt. (See BitBltfor further details on this.)

If you are familiar with the Microsoft** Windows** debugger, wdeb386, the OS/2 kernel debugger lacks a "z" command to eliminate INT 3 instructions you added to your code but now no longer need. The command e eip 90;gwill perform the same function (by examining the byte at the current instruction pointer, replacing it with a no-op, and restarting execution). Another useful debugger command is the DPcommand, which dumps the page tables. This is useful for getting information about any linear pointer to the video aperture that you obtain.

S3.DSP (Sample File for Installation and Configuration)

The following is an example S3 display (DSP) file containing DSPINSTL installation and configuration commands.

:TITLE

S3 DSP
:KEY
S3
:FILES :MODE=PRIMARY
S3VIDEO %BOOTDRIVE%:
DISPLAY.DL_ %BOOTDRIVE%:
PMVIOP.DL_ %BOOTDRIVE%:

*:FILES :MODE=PRIMARY :MODE=DOS

:FILES :MODE=PRIMARY :MODE=WINDOWS
S3WIN    %WINPATH%\SYSTEM

:CONFIG :MODE=PRIMARY
DEVINFO=SCR,VGA,%BOOTDRIVE%: \OS2\VIOTBL.DCP
SET VIDEO_DEVICES=VIO_SVGA
SET VIO_SVGA=DEVICE(BVHVGA,BVHSVGA)

:CONFIG :MODE=PRIMARY :MODE=BIDI
SET VIO_VGA=DEVICE(BVHVGA,BDBVH)

:CONFIG :MODE=PRIMARY :MODE=DOS
DEVICE=%BOOTDRIVE%: \OS2\MDOS\VSVGA.SYS

:DEL_CONFIG_LINE :MODE=PRIMARY

*:DELETING XGA LINES FOR PROTECT MODE
DEVICE=%BOOTDRIVE%: \OS2\XGARING0.SYS
DEVICE=%BOOTDRIVE%: \OS2\XGA.SYS
BASEDEV=XGA.SYS
SET VIO_XGA=DEVICE(BVHVGA,BVHXGA)

*:DELETING BGA LINES FOR PROTECT MODE
DEVINFO=SCR,BGA,%BOOTDRIVE%: \OS2\VIOTBL.DCP
SET VIO_8514A=DEVICE(BVHVGA,BVH8514A)

*:DELETING CGA LINES FOR PROTECT MODE
DEVINFO=SCR,EGA,%BOOTDRIVE%: \OS2\VIOTBL.DCP
SET VIO_CGA=DEVICE(BVHCGA)

*:DELETING EGA LINES FOR PROTECT MODE
DEVINFO=SCR,EGA,%BOOTDRIVE%: \OS2\VIOTBL.DCP
SET VIO_EGA=DEVICE(BVHEGA)

*:DELETING VGA LINES FOR PROTECT MODE
DEVICE=%BOOTDRIVE%: \OS2\MDOS\VVGA.SYS
SET VIO_VGA=DEVICE(BVHVGA)

:DEL_CONFIG_LINE :MODE=PRIMARY :MODE=DOS

*:DELETING S3 CORPS. DRIVERS STATEMENT FOR REAL MODE
DEVICE=%BOOTDRIVE%: \OS2\MDOS\VENH.SYS

*:DELETING XGA LINES FOR REAL MODE
DEVICE=%BOOTDRIVE%: \OS2\MDOS\VXGA.SYS

*:DELETING BGA LINES FOR REAL MODE
DEVICE=%BOOTDRIVE%: \OS2\MDOS\V8514A.SYS

*:DELETING CGA LINES FOR REAL MODE
DEVICE=%BOOTDRIVE%: \OS2\MDOS\VCGA.SYS

*:DELETING EGA LINES FOR REAL MODE
DEVICE=%BOOTDRIVE%: \OS2\MDOS\VEGA.SYS

*:DELETING VGA LINES FOR REAL MODE
DEVICE=%BOOTDRIVE%: \OS2\MDOS\VVGA.SYS

:OS2INI :MODE=PRIMARY
%BOOTDRIVE%: \OS2\INSTALL\REINSTAL.INI
InstallWindow VIOADAPTERSTR 7

:OS2INI :MODE=SECONDARY
%BOOTDRIVE%: \OS2\INSTALL\REINSTAL.INI
InstallWindow VIOADAPTER2STR 7

:OS2INI :MODE=PRIMARY
OS2.INI
PM_DISPLAYDRIVERS  IBMS332        IBMS332
PM_DISPLAYDRIVERS  CURRENTDRIVER  IBMS332
PM_DISPLAYDRIVERS  DEFAULTDRIVER  IBMS332
PM_Fonts           COURIERI
PM_Fonts           HELVI
PM_Fonts           TIMESI

* 
Note :      win . ini   font   statements   are   missing .   Should   be 
included   if 
*   font   support   for   1024x768   and   1280x768   is   the   same   as 
XGA ' s . 

: OS2INI   : MODE = PRIMARY   : MODE = WINDOWS 
OS2 . INI 
PM _ DISPLAYDRIVERS   RESOLUTION _ CHANGED   1 
WIN _ RES _ 640x480x16       WIN _ RES _ SET      WIN _ RES _ S3 _ 0 
WIN _ RES _ 640x480x256      WIN _ RES _ SET      WIN _ RES _ S3 _ 1 
WIN _ RES _ 640x480x65536    WIN _ RES _ SET      WIN _ RES _ S3 _ 2 
WIN _ RES _ 800x600x256      WIN _ RES _ SET      WIN _ RES _ S3 _ 3 
WIN _ RES _ 800x600x65536    WIN _ RES _ SET      WIN _ RES _ S3 _ 4 
WIN _ RES _ 1024x768x256     WIN _ RES _ SET      WIN _ RES _ S3 _ 5 
WIN _ RES _ 1024x768x65536   WIN _ RES _ SET      WIN _ RES _ S3 _ 6 
WIN _ RES _ 1280x1024x256    WIN _ RES _ SET      WIN _ RES _ S3 _ 7 
WIN _ RES _ 640x480x16777216    WIN _ RES _ SET      WIN _ RES _ S3 _ 8 
WIN _ RES _ S3 _ 0     1    " system . ini   boot   sdisplay . drv   swinvga . drv " 
WIN _ RES _ S3 _ 0     2    " system . ini   boot   display . drv   vga . drv " 
WIN _ RES _ S3 _ 0     3    " system . ini   boot   fonts . fon   vgasys . fon " 
WIN _ RES _ S3 _ 0     4    " system . ini   boot   fixedfon . fon   vgafix . fon " 
WIN _ RES _ S3 _ 0     5    " system . ini   boot   oemfonts . fon   vgaoem . fon " 
WIN _ RES _ S3 _ 0     6    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0     7    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0     8    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0     9    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0    10    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0    11    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0    12    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 0    13    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "    sserife . fon " 
WIN _ RES _ S3 _ 0    14    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( VGA   res ) \ "                   coure . fon " 
WIN _ RES _ S3 _ 0    15    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "         serife . fon " 
WIN _ RES _ S3 _ 0    16    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24 ( VGA   res ) \ "            symbole . fon " 
WIN _ RES _ S3 _ 0    17    " win . ini   fonts   \ " Small   Fonts   ( VGA   res ) \ "                         smalle . fon " 
WIN _ RES _ S3 _ 1     1    " system . ini   boot   sdisplay . drv   swins3 . drv " 
WIN _ RES _ S3 _ 1     2    " system . ini   boot   display . drv   s3 . drv " 
WIN _ RES _ S3 _ 1     3    " system . ini   boot   fonts . fon   vgasys . fon " 
WIN _ RES _ S3 _ 1     4    " system . ini   boot   fixedfon . fon   vgafix . fon " 
WIN _ RES _ S3 _ 1     5    " system . ini   boot   oemfonts . fon   vgaoem . fon " 
WIN _ RES _ S3 _ 1     6    " system . ini   boot . description   display . drv   640x480 " 
WIN _ RES _ S3 _ 1     7    " system . ini   boot . description   sdisplay . drv   640x480 " 
WIN _ RES _ S3 _ 1     8    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 1     9    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 1    10    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 1    11    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 1    12    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 1    13    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 1    14    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 1    15    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "    sserife . fon " 
WIN _ RES _ S3 _ 1    16    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( VGA   res ) \ "                   coure . fon " 
WIN _ RES _ S3 _ 1    17    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "         serife . fon " 
WIN _ RES _ S3 _ 1    18    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "           symbole . fon " 
WIN _ RES _ S3 _ 1    19    " win . ini   fonts   \ " Small   Fonts   ( VGA   res ) \ " smalle . fon " 
WIN _ RES _ S3 _ 2     1    " system . ini   boot   sdisplay . drv   swins316 . drv " 
WIN _ RES _ S3 _ 2     2    " system . ini   boot   display . drv   s316 . drv " 
WIN _ RES _ S3 _ 2     3    " system . ini   boot   fonts . fon   vgasys . fon " 
WIN _ RES _ S3 _ 2     4    " system . ini   boot   fixedfon . fon   vgafix . fon " 
WIN _ RES _ S3 _ 2     5    " system . ini   boot   oemfonts . fon   vgaoem . fon " 
WIN _ RES _ S3 _ 2     6    " system . ini   boot . description   display . drv   640x480x64K " 
WIN _ RES _ S3 _ 2     7    " system . ini   boot . description   sdisplay . drv   640x480x64K " 
WIN _ RES _ S3 _ 2     8    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 2     9    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 2    10    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 2    11    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 2    12    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 2    13    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 2    14    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 2    15    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "    sserife . fon " 
WIN _ RES _ S3 _ 2    16    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( VGA   res ) \ "                   coure . fon " 
WIN _ RES _ S3 _ 2    17    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "         serife . fon " 
WIN _ RES _ S3 _ 2    18    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "           symbole . fon " 
WIN _ RES _ S3 _ 2    19    " win . ini   fonts   \ " Small   Fonts   ( VGA   res ) \ " smalle . fon " 
WIN _ RES _ S3 _ 3     1    " system . ini   boot   sdisplay . drv   swins3 . drv " 
WIN _ RES _ S3 _ 3     2    " system . ini   boot   display . drv   s3 . drv " 
WIN _ RES _ S3 _ 3     3    " system . ini   boot   fonts . fon   vgasys . fon " 
WIN _ RES _ S3 _ 3     4    " system . ini   boot   fixedfon . fon   vgafix . fon " 
WIN _ RES _ S3 _ 3     5    " system . ini   boot   oemfonts . fon   vgaoem . fon " 
WIN _ RES _ S3 _ 3     6    " system . ini   boot . description   display . drv   800x600 " 
WIN _ RES _ S3 _ 3     7    " system . ini   boot . description   sdisplay . drv   800x600 " 
WIN _ RES _ S3 _ 3     8    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 3     9    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 3    10    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 3    11    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 3    12    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 3    13    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 3    14    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 3    15    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "    sserife . fon " 
WIN _ RES _ S3 _ 3    16    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( VGA   res ) \ "                   coure . fon " 
WIN _ RES _ S3 _ 3    17    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "         serife . fon " 
WIN _ RES _ S3 _ 3    18    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "           symbole . fon " 
WIN _ RES _ S3 _ 3    19    " win . ini   fonts   \ " Small   Fonts   ( VGA   res ) \ " smalle . fon " 
WIN _ RES _ S3 _ 4     1    " system . ini   boot   sdisplay . drv   swins316 . drv " 
WIN _ RES _ S3 _ 4     2    " system . ini   boot   display . drv   s316 . drv " 
WIN _ RES _ S3 _ 4     3    " system . ini   boot   fonts . fon   vgasys . fon " 
WIN _ RES _ S3 _ 4     4    " system . ini   boot   fixedfon . fon   vgafix . fon " 
WIN _ RES _ S3 _ 4     5    " system . ini   boot   oemfonts . fon   vgaoem . fon " 
WIN _ RES _ S3 _ 4     6    " system . ini   boot . description   display . drv   800x600x64K " 
WIN _ RES _ S3 _ 4     7    " system . ini   boot . description   sdisplay . drv   800x600x64K " 
WIN _ RES _ S3 _ 4     8    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 4     9    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 4    10    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 4    11    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 4    12    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 4    13    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 4    14    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 4    15    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "    sserife . fon " 
WIN _ RES _ S3 _ 4    16    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( VGA   res ) \ "                   coure . fon " 
WIN _ RES _ S3 _ 4    17    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "         serife . fon " 
WIN _ RES _ S3 _ 4    18    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "           symbole . fon " 
WIN _ RES _ S3 _ 4    19    " win . ini   fonts   \ " Small   Fonts   ( VGA   res ) \ "   smalle . fon " 
WIN _ RES _ S3 _ 5     1    " system . ini   boot   sdisplay . drv   swins3 . drv " 
WIN _ RES _ S3 _ 5     2    " system . ini   boot   display . drv   s3 . drv " 
WIN _ RES _ S3 _ 5     3    " system . ini   boot   fonts . fon   xgasys . fon " 
WIN _ RES _ S3 _ 5     4    " system . ini   boot   fixedfon . fon   xgafix . fon " 
WIN _ RES _ S3 _ 5     5    " system . ini   boot   oemfonts . fon   xgaoem . fon " 
WIN _ RES _ S3 _ 5     6    " system . ini   boot . description   display . drv   1024x768 " 
WIN _ RES _ S3 _ 5     7    " system . ini   boot . description   sdisplay . drv   1024x768 " 
WIN _ RES _ S3 _ 5     8    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 5     9    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 5    10    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 5    11    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 5    12    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 5    13    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 5    14    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 5    15    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "    sserifg . fon " 
WIN _ RES _ S3 _ 5    16    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( XGA   res ) \ "                   courg . fon " 
WIN _ RES _ S3 _ 5    17    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "         serifg . fon " 
WIN _ RES _ S3 _ 5    18    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "           symbolg . fon " 
WIN _ RES _ S3 _ 5    19    " win . ini   fonts   \ " Small   Fonts   ( XGA   res ) \ " smallg . fon " 
WIN _ RES _ S3 _ 6     1    " system . ini   boot   sdisplay . drv   swins316 . drv " 
WIN _ RES _ S3 _ 6     2    " system . ini   boot   display . drv   s316 . drv " 
WIN _ RES _ S3 _ 6     3    " system . ini   boot   fonts . fon   xgasys . fon " 
WIN _ RES _ S3 _ 6     4    " system . ini   boot   fixedfon . fon   xgafix . fon " 
WIN _ RES _ S3 _ 6     5    " system . ini   boot   oemfonts . fon   xgaoem . fon " 
WIN _ RES _ S3 _ 6     6    " system . ini   boot . description   display . drv   1024x768x64K " 
WIN _ RES _ S3 _ 6     7    " system . ini   boot . description   sdisplay . drv   1024x768x64K " 
WIN _ RES _ S3 _ 6     8    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 6     9    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 6    10    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 6    11    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 6    12    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 6    13    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 6    14    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 6    15    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "    sserifg . fon " 
WIN _ RES _ S3 _ 6    16    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( XGA   res ) \ "                   courg . fon " 
WIN _ RES _ S3 _ 6    17    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "         serifg . fon " 
WIN _ RES _ S3 _ 6    18    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "           symbolg . fon " 
WIN _ RES _ S3 _ 6    19    " win . ini   fonts   \ " Small   Fonts   ( XGA   res ) \ "    smallg . fon " 
WIN _ RES _ S3 _ 7     1    " system . ini   boot   sdisplay . drv   ss31280 . drv " 
WIN _ RES _ S3 _ 7     2    " system . ini   boot   display . drv   s31280 . drv " 
WIN _ RES _ S3 _ 7     3    " system . ini   boot   fonts . fon   xgasys . fon " 
WIN _ RES _ S3 _ 7     4    " system . ini   boot   fixedfon . fon   xgafix . fon " 
WIN _ RES _ S3 _ 7     5    " system . ini   boot   oemfonts . fon   xgaoem . fon " 
WIN _ RES _ S3 _ 7     6    " system . ini   boot . description   display . drv   1280x1024 " 
WIN _ RES _ S3 _ 7     7    " system . ini   boot . description   sdisplay . drv   1280x1024 " 
WIN _ RES _ S3 _ 7     8    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 7     9    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 7    10    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 7    11    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 7    12    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 7    13    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 7    14    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 7    15    " win . ini   fonts   \ " MS   Sans   Serif   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "    sserifg . fon " 
WIN _ RES _ S3 _ 7    16    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( XGA   res ) \ "                   courg . fon " 
WIN _ RES _ S3 _ 7    17    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "         serifg . fon " 
WIN _ RES _ S3 _ 7    18    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( XGA   res ) \ "           symbolg . fon " 
WIN _ RES _ S3 _ 7    19    " win . ini   fonts   \ " Small   Fonts   ( XGA   res ) \ " smallg . fon " 
WIN _ RES _ S3 _ 8     1    " system . ini   boot   sdisplay . drv   swins324 . drv " 
WIN _ RES _ S3 _ 8     2    " system . ini   boot   display . drv   s324 . drv " 
WIN _ RES _ S3 _ 8     3    " system . ini   boot   fonts . fon   vgasys . fon " 
WIN _ RES _ S3 _ 8     4    " system . ini   boot   fixedfon . fon   vgafix . fon " 
WIN _ RES _ S3 _ 8     5    " system . ini   boot   oemfonts . fon   vgaoem . fon " 
WIN _ RES _ S3 _ 8     6    " system . ini   boot . description   display . drv   640x480x16M " 
WIN _ RES _ S3 _ 8     7    " system . ini   boot . description   sdisplay . drv   640x480x16M " 
WIN _ RES _ S3 _ 8     8    " win . ini   fonts   \ " Symbol   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 8     9    " win . ini   fonts   \ " Helv   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 8    10    " win . ini   fonts   \ " Tms   Rmn   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 8    11    " win . ini   fonts   \ " Courier   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 8    12    " win . ini   fonts   \ " MS   Sans   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 8    13    " win . ini   fonts   \ " MS   Serif   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 8    14    " win . ini   fonts   \ " Small   Fonts   % ANYSTRING % \ " 
WIN _ RES _ S3 _ 8    15    " win . ini   fonts   \ " MS   Sans   Serif 
8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "    sserife . fon " 
WIN _ RES _ S3 _ 8    16    " win . ini   fonts   \ " Courier   10 , 12 , 15   ( VGA   res ) \ "                   coure . fon " 
WIN _ RES _ S3 _ 8    17    " win . ini   fonts   \ " MS   Serif   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "         serife . fon " 
WIN _ RES _ S3 _ 8    18    " win . ini   fonts   \ " Symbol   8 , 10 , 12 , 14 , 18 , 24   ( VGA   res ) \ "           symbole . fon " 
WIN _ RES _ S3 _ 8    19    " win . ini   fonts   \ " Small   Fonts   ( VGA   res ) \ "    smalle . fon " 

*   customize   icon   spacing   for   s3   below 
: WININI   : MODE = PRIMARY   : MODE = WINDOWS 
WIN . INI 
Desktop   IconSpacing   100 

*   system . ini   entries   below   will   be   overwritten   by   graphics 
engine   after   reboot . 
*   if   graphic   engine   fails   to   update   system . ini   for   some 
reason 
*   the   entries   below   are   the   default . 

: WININI   : MODE = PRIMARY   : MODE = WINDOWS 
SYSTEM . INI 
boot   sdisplay . drv   swins3 . drv 
boot   display . drv   s3 . drv 
boot   fonts . fon   xgasys . fon 
boot   fixedfon . fon   xgafix . fon 
boot   oemfonts . fon   xgaoem . fon 
boot . description   display . drv   1024x768 
boot . description   sdisplay . drv   1024x768 

Deciphering File Names in the S3 Driver

Many of the files in the S3 driver are derived from the original XGA driver for OS/2.

Most of the modules in the XGA driver are named some variant of "edd*.*". The "edd" portion of the file name stands for Expressway Device Driver. This is based on numerous references to the "Expressway hardware" found throughout the driver.

The fourth letter of the filename conveys useful information. In addition, the last four letters in the filename are typically a kind of abbreviation describing what the module actually does. The following is a list of prefixes:

eddb*.* - bitmap creation modules
eddbcrea.c - bitmap creation code
eddbdelt.c - bitmap deletion code
eddbsubrs.c - bitmap creation subroutines
eddbimag.c - image data function (doesn't fit the pattern)

eddc*.* - driver color support functions
eddcdith.c - dithering code
eddcctab.c - color table manipulation functions

edde*.* - initialization code
eddefldb.c - FillLogicalDeviceBlock a primary initialization entry point
eddefpdb.c - FillPhysicalDeviceBlock - another key part of the initialization code
eddesres.c - obtain desired resolution and color depth for the driver

eddf*.*, and ff*.asm - bitmap rendering code, "The MESS."
eddffast.asm - eddf_MESS - the top level of the software drawing code
ffbltsd.asm - MESS support for bitblt's involving source and destination
ffbltpd.asm - MESS support for bitblt's involving pattern and destination
ffbltd.asm - MESS support for bitblt's involving only the destination

eddh*.asm - hardware dependent modules. These are the primary files to be altered.
eddhbblt.asm - driver bitblt support
eddhgchs.asm - driver text output support
eddhline.asm - hardware line drawing support

eddl*.* - polyline and poly shortline code
eddlpoly - eddl_Polyline - entry point for the polyline function

eddm*.* - cursor code, and death and resurrection related code
eddmccrs.c - color cursor setup code
eddmcurs.c - monochrome cursor setup code
eddmdead.c - driver support for death and resurrection

eddn*.* - high-level driver entry points, and caching code
eddnbblt.c - driver entry point for bitblt
eddngchs.c - driver entry point for text output
eddncach.c - font and bitmap caching support code

eddq*.* - query functions
eddqsres.c - query driver for available resolutions
eddqesc.c - multimedia escape functions

eddv*.* - AVIO text functions
eddvsrec.c - eddv_ScrollRect - scroll a rectangle in an AVIO window

Color Palette Default Values

The following tables list the default values in each of the color palettes. This table shows the default values for the VGA (4bpp) palette.

/-------------------------------------------------------------\
|Index               |RRGGBB                                  |
|--------------------+----------------------------------------|
|0                   |000000                                  |
|--------------------+----------------------------------------|
|1                   |000080                                  |
|--------------------+----------------------------------------|
|2                   |008000                                  |
|--------------------+----------------------------------------|
|3                   |008080                                  |
|--------------------+----------------------------------------|
|4                   |800000                                  |
|--------------------+----------------------------------------|
|5                   |800080                                  |
|--------------------+----------------------------------------|
|6                   |808000                                  |
|--------------------+----------------------------------------|
|7                   |808080                                  |
|--------------------+----------------------------------------|
|8                   |CCCCCC                                  |
|--------------------+----------------------------------------|
|9                   |0000FF                                  |
|--------------------+----------------------------------------|
|10                  |00FF00                                  |
|--------------------+----------------------------------------|
|11                  |00FFFF                                  |
|--------------------+----------------------------------------|
|12                  |FF0000                                  |
|--------------------+----------------------------------------|
|13                  |FF00FF                                  |
|--------------------+----------------------------------------|
|14                  |FFFF00                                  |
|--------------------+----------------------------------------|
|15                  |FFFFFF                                  |
\-------------------------------------------------------------/

This table shows the default values for the XGA (8bpp) Palette.

/-------------------------------------------------------------\
|Index               |RRGGBB                                  |
|--------------------+----------------------------------------|
|0                   |000000                                  |
|--------------------+----------------------------------------|
|1                   |800000                                  |
|--------------------+----------------------------------------|
|2                   |009200                                  |
|--------------------+----------------------------------------|
|3                   |808000                                  |
|--------------------+----------------------------------------|
|4                   |0000AA                                  |
|--------------------+----------------------------------------|
|5                   |800080                                  |
|--------------------+----------------------------------------|
|6                   |0092AA                                  |
|--------------------+----------------------------------------|
|7                   |C1C1C1                                  |
|--------------------+----------------------------------------|
|8                   |AAFFAA                                  |
|--------------------+----------------------------------------|
|9                   |AAB6FF                                  |
|--------------------+----------------------------------------|
|10                  |0049AA                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|11                  |0049FF                                  |
|--------------------+----------------------------------------|
|12                  |006D00                                  |
|--------------------+----------------------------------------|
|13                  |006D55                                  |
|--------------------+----------------------------------------|
|14                  |006DAA                                  |
|--------------------+----------------------------------------|
|15                  |006DFF                                  |
|--------------------+----------------------------------------|
|16                  |002400                                  |
|--------------------+----------------------------------------|
|17                  |009255                                  |
|--------------------+----------------------------------------|
|18                  |0024AA                                  |
|--------------------+----------------------------------------|
|19                  |0092FF                                  |
|--------------------+----------------------------------------|
|20                  |00B600                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|21                  |00B655                                  |
|--------------------+----------------------------------------|
|22                  |00B6AA                                  |
|--------------------+----------------------------------------|
|23                  |00B6FF                                  |
|--------------------+----------------------------------------|
|24                  |00DB00                                  |
|--------------------+----------------------------------------|
|25                  |00DB55                                  |
|--------------------+----------------------------------------|
|26                  |00DBAA                                  |
|--------------------+----------------------------------------|
|27                  |00DBFF                                  |
|--------------------+----------------------------------------|
|28                  |FFDBAA                                  |
|--------------------+----------------------------------------|
|29                  |00FF55                                  |
|--------------------+----------------------------------------|
|30                  |00FFAA                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|31                  |FFFFAA                                  |
|--------------------+----------------------------------------|
|32                  |2B0000                                  |
|--------------------+----------------------------------------|
|33                  |2B0055                                  |
|--------------------+----------------------------------------|
|34                  |2B00AA                                  |
|--------------------+----------------------------------------|
|35                  |2B00FF                                  |
|--------------------+----------------------------------------|
|36                  |2B2400                                  |
|--------------------+----------------------------------------|
|37                  |2B2455                                  |
|--------------------+----------------------------------------|
|38                  |2B24AA                                  |
|--------------------+----------------------------------------|
|39                  |2B24FF                                  |
|--------------------+----------------------------------------|
|40                  |2B4900                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|41                  |2B4955                                  |
|--------------------+----------------------------------------|
|42                  |2B49AA                                  |
|--------------------+----------------------------------------|
|43                  |2B49FF                                  |
|--------------------+----------------------------------------|
|44                  |2B6D00                                  |
|--------------------+----------------------------------------|
|45                  |2B6D55                                  |
|--------------------+----------------------------------------|
|46                  |2B6DAA                                  |
|--------------------+----------------------------------------|
|47                  |2B6DFF                                  |
|--------------------+----------------------------------------|
|48                  |2B9200                                  |
|--------------------+----------------------------------------|
|49                  |2B9255                                  |
|--------------------+----------------------------------------|
|50                  |2B92AA                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|51                  |2B92FF                                  |
|--------------------+----------------------------------------|
|52                  |2BB600                                  |
|--------------------+----------------------------------------|
|53                  |2BB655                                  |
|--------------------+----------------------------------------|
|54                  |2BB6AA                                  |
|--------------------+----------------------------------------|
|55                  |2BB6FF                                  |
|--------------------+----------------------------------------|
|56                  |2BDB00                                  |
|--------------------+----------------------------------------|
|57                  |2BDB55                                  |
|--------------------+----------------------------------------|
|58                  |2BDBAA                                  |
|--------------------+----------------------------------------|
|59                  |2BDBFF                                  |
|--------------------+----------------------------------------|
|60                  |2BFF00                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|61                  |2BFF55                                  |
|--------------------+----------------------------------------|
|62                  |2BFFAA                                  |
|--------------------+----------------------------------------|
|63                  |2BFFFF                                  |
|--------------------+----------------------------------------|
|64                  |550000                                  |
|--------------------+----------------------------------------|
|65                  |550055                                  |
|--------------------+----------------------------------------|
|66                  |5500AA                                  |
|--------------------+----------------------------------------|
|67                  |5500FF                                  |
|--------------------+----------------------------------------|
|68                  |552400                                  |
|--------------------+----------------------------------------|
|69                  |552455                                  |
|--------------------+----------------------------------------|
|70                  |5524AA                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|71                  |5524FF                                  |
|--------------------+----------------------------------------|
|72                  |554900                                  |
|--------------------+----------------------------------------|
|73                  |554955                                  |
|--------------------+----------------------------------------|
|74                  |5549AA                                  |
|--------------------+----------------------------------------|
|75                  |5549FF                                  |
|--------------------+----------------------------------------|
|76                  |556D00                                  |
|--------------------+----------------------------------------|
|77                  |556D55                                  |
|--------------------+----------------------------------------|
|78                  |556DAA                                  |
|--------------------+----------------------------------------|
|79                  |556DFF                                  |
|--------------------+----------------------------------------|
|80                  |559200                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|81                  |559255                                  |
|--------------------+----------------------------------------|
|82                  |5592AA                                  |
|--------------------+----------------------------------------|
|83                  |5592FF                                  |
|--------------------+----------------------------------------|
|84                  |55B600                                  |
|--------------------+----------------------------------------|
|85                  |55B655                                  |
|--------------------+----------------------------------------|
|86                  |55B6AA                                  |
|--------------------+----------------------------------------|
|87                  |55B6FF                                  |
|--------------------+----------------------------------------|
|88                  |55DB00                                  |
|--------------------+----------------------------------------|
|89                  |55DB55                                  |
|--------------------+----------------------------------------|
|90                  |55DBAA                                  |
|--------------------+----------------------------------------|
|                    |                                        |
|--------------------+----------------------------------------|
|91                  |55DBFF                                  |
|--------------------+----------------------------------------|
|92                  |55FF00                                  |
|--------------------+----------------------------------------|
|93                  |55FF55                                  |
|--------------------+----------------------------------------|
|94                  |55FFAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 95                     | 55FFFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 96                     | 000055                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 97                     | 800055                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 98                     | 002455                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 99                     | 8000FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 100                    | 802400                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 101                    | 802455                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 102                    | 8024AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 103                    | 8024FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 104                    | 804900                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 105                    | 804955                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 106                    | 8049AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 107                    | 8049FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 108                    | 806D00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 109                    | 806D55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 110                    | 806DAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 111                    | 806DFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 112                    | 080808                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 113                    | 0F0F0F                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 114                    | 171717                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 115                    | 1F1F1F                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 116                    | 272727                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 117                    | 2E2E2E                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 118                    | 363636                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 119                    | 3E3E3E                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 120                    | 464646                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 121                    | 4D4D4D                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 122                    | 555555                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 123                    | 5D5D5D                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 124                    | 646464                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 125                    | 6C6C6C                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 126                    | 747474                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 127                    | 7C7C7C                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 128                    | FFDB00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 129                    | 8B8B8B                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 130                    | 939393                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 131                    | 9B9B9B                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 132                    | FFB6FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 133                    | AAAAAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 134                    | B2B2B2                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 135                    | B9B9B9                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 136                    | 0024FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 137                    | CCCCCC                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 138                    | D1D1D1                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 139                    | D8D8D8                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 140                    | FFB6AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 141                    | E8E8E8                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 142                    | F0F0F0                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 143                    | F7F7F7                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 144                    | FFDBFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 145                    | 809255                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 146                    | 8092AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 147                    | 8092FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 148                    | 80B600                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 149                    | 80B655                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 150                    | 80B6AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 151                    | 80B6FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 152                    | 80DB00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 153                    | 80DB55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 154                    | 80DBAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 155                    | 80DBFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 156                    | 80FF00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 157                    | 80FF55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 158                    | 80FFAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 159                    | 80FFFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 160                    | AA0000                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 161                    | AA0055                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 162                    | AA00AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 163                    | AA00FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 164                    | AA2400                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 165                    | AA2455                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 166                    | AA24AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 167                    | AA24FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 168                    | AA4900                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 169                    | AA4955                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 170                    | AA49AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 171                    | AA49FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 172                    | AA6D00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 173                    | AA6D55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 174                    | AA6DAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 175                    | AA6DFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 176                    | AA9200                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 177                    | AA9255                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 178                    | AA92AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 179                    | AA92FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 180                    | AAB600                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 181                    | AAB655                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 182                    | AAB6AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 183                    | 004955                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 184                    | AADB00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 185                    | AADB55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 186                    | AADBAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 187                    | AADBFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 188                    | AAFF00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 189                    | AAFF55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 190                    | 004900                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 191                    | AAFFFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 192                    | D50000                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 193                    | D50055                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 194                    | D500AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 195                    | D500FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 196                    | D52400                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 197                    | D52455                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 198                    | D524AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 199                    | D524FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 200                    | D54900                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 201                    | D54955                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 202                    | D549AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 203                    | D549FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 204                    | D56D00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 205                    | D56D55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 206                    | D56DAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 207                    | D56DFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 208                    | D59200                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 209                    | D59255                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 210                    | D592AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 211                    | D592FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 212                    | D5B600                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 213                    | D5B655                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 214                    | D5B6AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 215                    | D5B6FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 216                    | D5DB00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 217                    | D5DB55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 218                    | D5DBAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 219                    | D5DBFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 220                    | D5FF00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 221                    | D5FF55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 222                    | D5FFAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 223                    | D5FFFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 224                    | FFDB55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 225                    | FF0055                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 226                    | FF00AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 227                    | FFFF55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 228                    | FF2400                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 229                    | FF2455                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 230                    | FF24AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 231                    | FF24FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 232                    | FF4900                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 233                    | FF4955                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 234                    | FF49AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 235                    | FF49FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 236                    | FF6D00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 237                    | FF6D55                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 238                    | FF6DAA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 239                    | FF6DFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 240                    | FF9200                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 241                    | FF9255                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 242                    | FF92AA                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 243                    | FF92FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 244                    | FFB600                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 245                    | FFB655                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 246                    | E0E0E0                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 247                    | A2A2A2                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 248                    | 838383                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 249                    | FF0000                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 250                    | 00FF00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
|                        |                                              | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 251                    | FFFF00                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 252                    | 0000FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 253                    | FF00FF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 254                    | 00FFFF                                       | 
| ---------- ---------- + ---------- ---------- ---------- ---------- | 
| 255                    | FFFFFF                                       | 
\ ---------- ---------- - ---------- ---------- ---------- ---------- / 

This table shows the default values for the XGA (16bpp) palette.

/-------------------------------------------------------------\
|This is a 5-6-5 format,                 |r    =    red (5    |
|rrrrrggggggbbbbb, where:                |bits)               |
|----------------------------------------+--------------------|
|                                        |g    =    green (6  |
|                                        |bits)               |
|----------------------------------------+--------------------|
|                                        |b    =    blue (5   |
|                                        |bits)               |
\-------------------------------------------------------------/

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.

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
Ultimotion 

The following terms are trademarks of other companies:

Helvetica Linotype Company
MASM Microsoft Corporation
Mitsumi Mitsumi Denki Kabushki Kaisha
Panasonic Matsushita Electric Industrial Co., Ltd.
OPTi OPTi, Inc.
Pioneer Pioneer Electric Corporation
ProAudio Spectrum Media Vision, Inc.
ProAudio Spectrum 16 Media Vision, Inc.
QuickVia Jovian Logic Corp.
ReelMagic Sigma Designs, Inc.
Sound Blaster Creative Technology Ltd.
SuperVia Jovian Logic Corp.
Super VideoWindows New Media Graphics Corporation
Video Blaster Creative Technology, Inc.
Yamaha Yamaha Corporation

Windows is a trademark of Microsoft Corporation.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

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

Glossary

This glossary contains terms and definitions that are, for the most part, used for OS/2 products. This is not a complete dictionary of computer terms .

Introduction

This glossary defines many of the terms used in this book. It includes terms and definitions from the IBM Dictionary of Computing, as well as terms specific to the Presentation Manager, but it is not a complete glossary for OS/2.

Other primary sources for these definitions are:

• The American National Standard Dictionary for Information Systems, ANSI X3 .172-1990, copyrighted 1990 by the American National Standards Institute, 11 West 42nd Street, New York, New York 10036. These definitions are identified by the symbol (A) after the definition.
• The Information Technology Vocabulary, developed by Subcommittee 1, Joint Technical Committee 1, of the International Organization for Standardization and the International Electrotechnical Commission (ISO/IEC JTC1/SC1). Definitions of published parts of this vocabulary are identified by the symbol (I) after the definition; definitions taken from draft international standards, committee drafts, and working papers being developed by ISO/IEC JTC1/SC1 are identified by the symbol (T) after the definition, indicating that final agreement has not yet been reached among the participating National Bodies of SC1.

Glossary Listing

Select a starting letter of glossary terms:

AN
BO
CP
DQ
ER
FS
GT
HU
IV
JW
KX
LY
MZ

Glossary - A

A

ABIOS -Advanced BIOS. See BIOS.

accumulator -(1) A register in which one operand of an operation can be stored and subsequently replaced by the result of that operation. (T) (2) In the IBM 3800 Printing Subsystem Models 3 and 8, a feature that supplies a separate storage that can hold data in raster form. It can be used either for composing a sheet of data that combines a large amount of variable and constant data, or for storing an electronic overlay in raster form that will be merged with variable data as the sheet is printed.

access permission -All access rights a user has regarding an object. (I)

adapter -A piece of hardware that modifies the system unit to allow it to operate in a particular way, often by connecting the system unit to an external device such as a video monitor.

adapter device driver -A device driver that provides hardware-dependent services for an OEMadapter.

address space -(1) The range of addresses available to a program. (A) ( 2) The area of virtual storage available for a particular job.

all points addressable (APA) -In computer graphics, pertaining to the ability to address and display or not display each picture element (pel) on a display surface.

anchor block -An area of the internal resources of OS/2 Presentation Manager which is allocated to a process or thread that calls WinInitialize.

anchor point -The position or choice from which selection or deselection is extended.

APA -All points addressable.

API -Application programming interface.

application programming interface (API) -A functional interface supplied by the operating system, or by a separately-orderable licensed program, that allows an application program written in a high-level language to use specific data or functions of the operating system or the licensed program.

archive flag -In the OS/2 operating system, a flag of files and directories that the operating system uses to determine which files are new or modified. Files with this flag are included when a backup copy is made or when all the files are restored on a hard disk. See flag.

area -In computer graphics, a filled shape such as a solid rectangle.

ASCIIZ -A string of ASCII characters that is terminated with a byte containing the value 0.

aspect ratio -(1) The ratio of the height of a rectangle to its width. A rectangle of width 10 inches and height 5 inches has an aspect ratio of 10/ 5 or 2. (2) On a display screen, the ratio of the maximum length of a display line to the maximum length of a display column.

asynchronous (ASYNC) -(1) Pertaining to two or more processes that do not depend upon the occurrence of specific events such as common timing signals . (T) (2) Without regular time relationship; unexpected or unpredictable with respect to the execution of program instructions.

atom -A constant that represents a string. Once a string has been defined as an atom, the atom can be used in place of the string to save space. Strings are associated with their respective atoms in an atom table. See integer atom.

atom table -A table used to associate atoms with the strings that they represent. This table contains the mechanism by which the presence of a string can be verified.

AVIO -Advanced Video Input/Output

Glossary - B

B

background color -The color assigned to a background image.

background mix -An attribute that determines how the background of a graphic primitive is combined with the existing color of the graphics presentation space.

base device driver -An OS/2 device driver that performs I/O during the OS/ 2 kernel boot sequence to provide IPL support. Base device drivers are loaded by way of the CONFIG.SYS BASEDEV keyword, rather than the DEVICE keyword. See BASEDEV keyword, adapter device driver, and device manager.

BASEDEV keyword -New CONFIG.SYS keyword; loads a base device driver into the operating system.

Basic Input/Output System (BIOS) -Code that controls basic hardware operations, such as interactions with diskette drives, hard disk drives, and the keyboard.

Bezier curve -A mathematical technique of specifying a smooth, continuous line or surface, requiring a starting point and an ending point, with several intermediate points that influence or control the path of the linking curve.

BIOS -Basic Input/Output System.

bit-block transfer (bitblt) -Transfer of a rectangular array of bit-map data.

bitblt -Bit-block transfer.

bit map -A representation of an image by an array of bits.

block -(1) In programming languages, a compound statement that coincides with the scope of at least one of the declarations contained within it. A block may also specify storage allocation or segment programs for other purposes. (I) (2) A string of data elements recorded or transmitted as a unit. The elements may be characters, words or physical records. (T) (3) A collection of contiguous records recorded as a unit. Blocks are separated by interblock gaps and each block may contain one or more records. (A)

Bit block transfer (bitblt) -The process of transferring one or more blocks of data.

border -A visual indicator of a window's boundaries.

BPB -BIOS Parameter Block.

breakpoint -(1) A point in a computer program where execution may be halted. A breakpoint is usually at the beginning of an instruction where halts, caused by external intervention, are convenient for resuming execution. (T) (2) An instruction in a program for halting execution. Breakpoints are usually established at positions in a program where halts, caused by external intervention, are convenient for restarting. (T) (3) A place in a program, specified by a command or a condition, where the system halts execution and gives control to the workstation user or to a specified program.

Bus Master adapter -An adapter capable of performing Reads and Writes to physical storage by communicating directly with the storage subsystem ( memory) rather than depending on a host DMA channel or host CPU. Synonymous with first-party DMA adapter.

Glossary - C

C

cached micro presentation space -A presentation space from a Presentation Manager owned store of micro presentation spaces. It can be used for drawing to a window only, and must be returned to the store when the task is complete.

CDB -Command Descriptor Block.

cell -See character cell.

character box -(1) An imaginary parallelogram on a display surface that contains all parts of one graphic character. Synonymous with bounding box. (T) (2) The maximum area in which a symbol and all associated elements, such as a cursor, an underline, or space surrounding the symbol to separate it from other symbols, can be printed or displayed. Synonymous with character cell. (3) The imaginary parallelogram whose boundaries govern the size, orientation, and spacing of individual characters to be displayed on a graphics display device.

character cell -(1) An addressable location on a display surface or printing medium. (2) The physical width and height in pels of a font. See also bounding box. (3) The imaginary box whose boundaries govern the size , orientation, and spacing of individual characters to be displayed on a workstation.

character mode -A mode that, in conjunction with the font type, determines the extent to which graphics characters are affected by the character box, shear, and angle attributes.

clipping -In computer graphics, removing those parts of display elements that lie outside of given boundary.

clip limits -The area of the paper that can be reached by a printer or plotter.

clipping path -A clipping boundary in world-coordinate space.

code page -An assignment of graphic characters and control function meanings to all code points; for example, assignment of characters and meanings to 256 code points for an 8-bit code, assignment of characters and meanings to 128 code points for a 7-bit code.

code point -A 1-byte code representing one of 256 potential characters.

code segment -An executable section of programming code within a load module.

color conversion -Changing one color format to another. Required, for example, when the source color format is different from the destination color format. When going from the monochrome color format to the color format, 1 (one) bits are converted to the image foreground color, and 0 ( zero) bits are converted to the image background color.

When going from color to monochrome, all pels that match the passed background color are converted to the image background color of the destination.

All other pels are converted to the image foreground color of the destination. The color conversion takes place prior to any mix mode.

color dithering -See dithering.

command code -In this specification, refers to a group of related commands that an adapter device driver can receive.

All command codes have a prefix of "IOCC_". For example, common I/O requests (such as Read, Write, etc.) are grouped under the command code IOCC_EXECUTE_IO.

command data block -A data structure defined by the Small Computer System Interface standard to send commands to devices that conform to SCSI standards.

command descriptor block (CDB) -The structure used to communicate commands from a source to a destination.

command modifier -In this specification, a specific operation that an adapter device driver is to perform.

All command modifiers have a prefix of "IOCM_". For example, an adapter device driver might receive an IOCC_EXECUTE_IO command with a command modifier of IOCM_READ.

compatibility kernel -The portion of the OS/2 kernel that exists to support DOS INT 20, 21, 25, 26, and 27 functions. It acts as an interface to common kernel functionality such as the file system.

CON -Character-device name reserved for the console keyboard and screen.

conditional compilation -Processing by the preprocessor of certain specified code in the file, depending on the evaluation of a specified condition.

context hook -Similar to a "force flag" in earlier versions of OS/2. These are events, signaled by a virtual device driver, that are processed at task time. Forcing an IRET, and simulating an NMI, can fall into this category.

control program -A computer program designed to schedule and to supervise the execution of programs of a computer system.

controller sector buffer -One or more buffers, managed by a hardware adapter, to improve I/O transfer rates by helping to match a device and software timing requirements.

Glossary - D

D

DASD -Direct-access storage device.

data bus -A bus used to communicate data internally and externally to and from a processing unit, storage, and peripheral devices. (A) See bus.

data structure -The syntactic structure of symbolic expressions and their storage allocation characteristics. (T)

DBCS -Double-byte character set.

DC -Device context.

DDB -Device-dependent bit map.

deinstantiation -See instantiation.

DevHlp -Device helper.

device context (DC) -A logical description of a data destination such as memory, metafile, display, printer, or plotter. See also direct device context, information device context, memory device context, metafile device context, and screen device context.

device driver -A file that contains the code needed to attach and use a device such as a display, printer, or plotter.

device driver initialization (init) time -See initialization (init) time, device driver.

device driver profile -A file with a "DDP" extension, containing a script that is interpreted by the OS/2 DDINSTAL utility. Among other things, it defines which files to copy from installation diskettes to target directories and specifies how the CONFIG.SYS file will be updated.

device helper (DevHlp) -(1) A kernel service (memory, hardware interrupt, software interrupt, queuing, semaphore, and so forth) provided to physical device drivers. (2) A callable C-language or assembler-language routine that provides an operating system service for an OS/2 device driver.

device object -A device that provides a means of communication between a computer and the outside world. A printer is an example of a device object.

device table -A data structure containing a summary of the adapters an adapter device driver supports and a list of the I/O devices attached to each adapter. This data structure is built by the adapter device driver in response to an IOCC_CONFIGURATION IOCM_GET_DEVICE_TABLE request.

direct access storage device (DASD) -A device in which access time is effectively independent of the location of the data.

direct memory access (DMA) -(1) A technique for moving data directly between main storage and peripheral equipment without requiring processing of the data by the processing unit. (2) The transfer of data between memory and input/output units without processor intervention.

display frame -(1) In computer graphics, an area in storage in which a display image can be recorded. (2) In computer micrographics, an area on a microform in which a display image can be recorded.

dispatch table -(1) A block of memory, allocated by the graphics engine, for the containment of entry points for use by a display driver. (2) An array of pointers to function-handling routines.

dithering -A technique for interleaving dark and light pels so that the resulting image looks smoothly shaded from a distance.

DLL -Dynamic link library.

DMA -Direct memory access.

double-byte character set (DBCS) -A set of characters in which each character is represented by two bytes. Languages such as Japanese, Chinese, and Korean, which contain more characters than can be represented by 256 code points, require double-byte character sets. Because each character requires 2 bytes, the typing, display, and printing of DBCS characters requires hardware and programs that support DBCS. Contrast with single-byte character set.

driver -(1) A program (and possibly data files) that contain information needed to run a particular unit, such as a plotter, printer, port, or mouse. See also device driver and printer driver. (2) A system or device that enables a functional unit to operate.

dynamic link library (DLL) -A file containing executable code and data bound to a program at load time or run time, rather than during linking. The code and data in a dynamic link library can be shared by several applications simultaneously.

Glossary - E

E

entry point -(1) In a database, the record that is first accessed upon entry into a database, caused by a user's command. (T) (2) The address or label of the first instruction executed on entering a computer program, routine, or subroutine. A computer program, routine, or subroutine may have a number of different entry points, each perhaps corresponding to a different function or purpose. (I) (A) Synonymous with entrance, entry. (3) In a routine, any place to which control can be passed. (A) (4) In the C, FORTRAN, and Pascal languages, the address or label of the first instruction processed or entered in a program, routine, or subroutine. A program, routine, or subroutine can have a number of different entry points , each corresponding to a different function or purpose.

EOI -End Of Interrupt

Glossary - F

F

Far call -Code that calls from one segment into another segment.

fillet -An arc that is tangential to the end points of two adjacent lines. See also polyfillet.

filter adapter device driver -A special class of adapter device drivers that do not manage the hardware directly, but monitor the stream of commands between a device manager and an adapter device driver. See Device Managerand adapter device driver.

first-party DMA adapter -See bus master adapter.

flag -A characteristic of a file or directory that enables it to be used in certain ways. See also archive flag, hidden flag, and read-only flag.

flat address -See linear address.

frame styles -Standard window layouts provided by the Presentation Manager .

freeze and thaw services -Functions that prevent a DOS session from executing (VDHFreezeVDM) until the matching thaw function (VDHThawVDM) is called. The freeze occurs when the specified DOS session leaves kernel mode .

Glossary - G

G

GDT -Global descriptor table.

Global Descriptor Table (GDT) -A table that defines code and data segments available to all tasks in an application.

glyph -A graphic symbol whose appearance conveys information; for example, the vertical and horizontal arrows on cursor keys that indicate the directions in which they control cursor movement, the sunburst symbol on the screen illumination control of a display device.

GPI -Graphics programming interface

graphic primitive -In computer graphics, a basic element, such as an arc or a line, that is not made up of smaller parts and that is used to create diagrams and pictures.

graphics attributes -The attributes that apply to graphics primitives. Examples are color selection, line type, and shading pattern definition. Contrast with segment attributes.

Graphics programming interface (GPI) -The formally-defined programming language that lies between an IBM graphics program and the user of the program.

graphics segment -A sequence of related graphic primitives and graphics attributes. See also graphic primitive.

GRE -Graphics engine.

Glossary - H

H

handle -(1) An identifier that represents an object, such as a device or a window, to the Presentation Interface. (2) In the Advanced DOS and OS/2 operating systems, a binary value created by the system that identifies a drive, directory, and file so that the file can be found and opened.

handshaking -A method by which two pieces of hardware, such as a personal computer and a plotter, can communicate. Depending upon the devices communicating, handshaking occurs either as a hardware function or through software, such as a device driver.

hard error -An error condition on a network that requires that the network be reconfigured or that the source of the error be removed before the network can resume reliable operation.

hardware palette -The array of RGBs that the physical device is displaying .

heap -An area of free storage available for dynamic allocation by an application. Its size varies depending on the storage requirements of the application.

hex -See hexadecimal

hexadecimal -Pertaining to a system of numbers to the base 16; hexadecimal digits range from 0 through 9 and A through F, where A represents 10 and F represents 15.

hook -A point in a system-defined function where an application can supply additional code that the system processes as though it were part of the function.

hook chain -A sequence of hook procedures that are "chained" together so that each event is passed in turn to each procedure in the chain.

Glossary - I

I

IDC -Inter-device-driver communication.

in-memory buffer -A block of memory in the address space of the host machine, used for data transfer.

init time -See initialization time, device driver.

initialization time, device driver -After the OS/2 loads a device driver, it sends it an OS/2 request packet to initialize. During this initialization, certain DevHlp functions are not permitted. Also called init time.

Input/Output Control (IOCtl) -A system service that provides a way for an application to send device-specific control commands to a device driver.

Input/Output Privilege Level (IOPL) -Allows part of a Ring 3 application or device driver to execute at Ring 0.

input router -OS/2 internal process that removes messages from the system queue.

inter-device-driver communication (IDC) -A mechanism that enables a physical device driver to communicate with another physical device driver.

interprocess communication -In the OS/2 operating system, the exchange of information between processes or threads through semaphores, queues, and shared memory.

interrupt -An instruction that directs the microprocessor to suspend what it is doing and run a specified routine. When the routine is complete, the microprocessor resumes its original work. See also routine.

interrupt request (IR) -Broadly, an "interrupt request level", referring to pending or in-service interrupt requests, or to a specific level (for example, IR 4).

interrupt request flag -A bit in the 8259 PIC controller that indicates an interrupt is pending on particular level. The VPIC also maintains a virtual interrupt request flag for each interrupt level for each DOS session.

interrupt service flag -A bit in the 8259 PIC controller that indicates an interrupt request is being serviced. It is cleared when the PIC is sent EOI . The VPIC maintains a virtual interrupt service flag indicating that a simulated interrupt is in-progress in a DOS session.

interrupt time -When a device driver is run because of an interrupt rather than because of an application request. OS/2 device drivers receive interrupts either from the hardware they manage or from the system real- time clock.

During interrupt time, certain DevHlp functions are not permitted. Also, addresses received directly from OS/2 applications might not be valid unless they are converted system addresses.

IOCtl -Input/Output Control.

IOPL -Input/Output Privilege Level.

IORB -Input/Output Request Block.

Input/Output Request Block (IORB) -A data structure defined by this specification that is passed as a parameter on all calls to an adapter device driver. It contains a fixed section, followed by a command-dependent section.

IORBH -Input/Output Request Block Header

IRET -Interrupt return.

IRQ -Interrupt Request.

Glossary - J

J

journal -A special-purpose file or data set that can be used to provide an audit trail of operator and system actions, or as a means of recovering superseded data.

Glossary - K

K

kanji -A graphic character set consisting of symbols used in Japanese ideographic alphabets. Each character is represented by 2 bytes.

kernel -(1) The part of an operating system that performs basic functions such as allocating hardware resources. (2) A program that can run under different operating system environments.

kerning -The design of graphic characters so that their character boxes overlap. The toned picture elements (pels) of the character appear outside the character cell.

Note:Kerning allows character boxes to overlap and characters to run together, so that characters can be designed for cursive languages, ligatures, or any other kind of character that requires more than one character box. It also allows for design of proportional-spaced fonts. By overlapping character boxes, characters can be placed closer together, or they can be placed farther apart by using overlapped blank character boxes.

Glossary - L

L

LCT -logical color table.

LDT -Local descriptor table.

LIFO stack -A data structure from which data is retrieved in "Last-In, First-Out" order.

linked list -A list in which the data elements may be dispersed, but in which each data element contains information for locating the next. Synonym for chained list.

linear address -A unique value that identifies the memory object.

Local Descriptor Table (LDT) -A table that defines code and data segments specific to a single task.

logical palette -An array of RGB and mapping index pairs, created by the device driver when defining a palette (as a result of a GpqCreatePalette call).

LVB -Logical Video Buffer.

Glossary - M

M

memory device context -A logical description of a data destination that is a memory bit map. See also device context.

metafile -A file containing a series of attributes that set color, shape, and size, usually of a picture or a drawing. Using a program that can interpret these attributes, a user can view the assembled image.

metafile device context -A logical description of a data destination that is a metafile which is used for graphics interchange. See also device context.

mickey -A unit of measurement for physical mouse motion whose value depends on the mouse device driver that is currently loaded.

mixed character string -A string containing a mixture of one-byte and kanji or Hangeul (two-byte) characters.

mutex semaphore -(Mutual exclusion semaphore). A semaphore that enables threads to serialize their access to resources. Only the thread that currently owns the mutex semaphore can gain access to the resource, thus preventing one thread from interrupting operations being performed by another.

Glossary - N

N

named pipe -A named buffer that provides client-to-server, server-to- client or duplex communication between unrelated processes. Contrast with unnamed pipe.

notification callout -The feature that provides for a routine to be called on completion of an input/output request. See also notification routine.

notification routine -The routine indicated in an input/output request block to be called on completion of that request. See also notification callout.

null-terminated string -A string of (n+1) characters where the (n+1)th character is the "null" character (X'00') and is used to represent an n- character string with implicit length. Also called a "zero-terminated" string or an "ASCIIZ". string.

Glossary - O

O

Glossary - P

P

palette -A list of colors assigned to various areas on a panel. A user can change the color of these areas.

PDD -Physical Device Driver.

PDE -PageDirectoryEntry.

pel -Picture element.

permissible action -In a conceptual schema language, an action conforming to specified rules or constraints that changes a presumably consistent collection of sentences into a consistent one or makes known a consistent one present in the information base or conceptual schema.

phase alignment -Aligning source bits with destination bits. Often required in a Bitblt function move operation where byte blocks are moved on bit boundaries.

physical address -A 32-bit byte address giving the actual address in physical storage for a data item.

physical device driver (PDD) -A system interface that handles hardware interrupts and supports a set of input and output functions.

pipe -See named pipe, unnamed pipe.

picture element (pel, pixel) -(1) In computer graphics, the smallest element of a display surface that can be independently assigned color and intensity. (T) . (2) The area of the finest detail that can be reproduced effectively on the recording medium. (3) An element of a raster pattern about which a toned area on a photoconductor can appear.

PIO -Programmed I/O.

pixel -Picture element.

polyfillet -A curve based on a sequence of lines. The curve is tangential to the end points of the first and last lines, and tangential also to the midpoints of all other lines.

polyline -In computer graphics, a sequence of adjoining lines.

pop -To remove an item from the top of a pushdown list. Contrast with push .

prefetch -To locate and load a quantity of data in anticipation of a request.

presence-check function -A Ring 3 (non-privileged) .EXE program that determines whether a given hardware interface is present on a workstation.

PRESENCECHECK -A keyword, interpreted by the DDINSTAL utility, to determine whether to process the device driver profile file, based on the return code from PRESENCECHECK.

printer driver -A file that describes the physical characteristics of a printer, plotter, or other peripheral device, and is used to convert graphics and text into device-specific data at the time of printing or plotting.

Print Manager -In the Presentation Manager, the part of the spooler that manages the spooling process. It also allows the user to view print queues and to manipulate print jobs.

privilege level -A method of protection that allows only certain program instructions to be used by certain programs.

program group -Several programs that can be acted upon as a single entity.

protect mode -A method of program operation that limits or prevents access to certain instructions or areas of storage. Contrast with real mode.

push -To add an item to the top of a pushdown list. Contrast with pop.

Glossary - Q

Q

queued device context -A logical description of a data destination (for example, a printer or plotter) where the output is to go through the spooler. See also device context.

Glossary - R

R

read-only memory basic input/output system (ROM-BIOS) -Microcode in read- only memory that controls basic input/output operations such as interactions with cassettes, diskette drives, hard disk drives, and the keyboard. See also BIOS, NetBIOS.

Note:ROM BIOS allows the user to write programs and add or remove devices without concern for characteristics such as device addresses.

real mode -In the OS/2 operating system, a method of program operation that does not limit or prevent access to any instructions or areas of storage. The operating system loads the entire program into storage and gives the program access to all system resources.

reentrant -The attribute of a program or routine that allows the same copy of the program or routine to be used concurrently by two or more tasks.

removable-media indicator -A flag (bit) indicating that a device permits media removal.

resource -The means of providing extra information used in the definition of a window. A resource can contain definitions of fonts, templates, accelerators and mnemonics; the definitions are held in a resource file.

resurrection -The Presentation Manager event that occurs when switched back from a full-screen DOS or WIN-OS/2 session.

RETF -Return far.

reverse video -A form of highlighting a character, field, or cursor by reversing the color of the character, field, or cursor with its background; for example, changing a red character on a black background to a black character on a red background.

ROM BIOS -Read-Only Memory Basic Input/Output System.

ROP -Raster operation.

RTC -Real-Time Clock.

Glossary - S

S

SBCS -Single-byte character set

SCB -See subsystem control block architecture.

screen device context -A logical description of a data destination that is a particular window on the screen. See also device context.

SCSI -Small Computer System Interface.

seamless windows -An architecture contained within OS/2 which permits one or more applications to share windowed desktop graphical space and other resources, while executing concurrently. Application session windows managed by seamless windows can share border information, and pointing device transitions from session to session are handled smoothly and transparently.

second-party DMA adapter -See DMA slave.

semaphore -(1) A variable that is used to enforce mutual exclusion. (T) (2) An indicator used to control access to a file; for example, in a multiuser application, a flag that prevents simultaneous access to a file. (3) An entity used to control access to system resources. Processes can be locked to a resource with semaphores if the processes follow certain programming conventions.

sense data -Data which describes an I/O error as defined by the ANSI SCSI specifications.

single-byte character set (SBCS) -A character set in which each character is represented by a one-byte code. Contrast with double-byte character set.

Small Computer System Interface (SCSI) -An input and output bus that provides a standard interface between the OS/2 multimedia system and peripheral devices.

spline curve -In computer graphics, a shape created when a user specifies a series of points and the computer software draws a curve that smoothly approaches those points.

spooler -A program that intercepts data going to a device driver and writes it to a disk. The data is later printed or plotted when the required device is available. A spooler prevents output from different sources from being intermixed.

synchronous -Pertaining to two or more processes that depend upon the occurrence of specific events such as common timing signals.

Glossary - T

T

text window -See VIO window.

thread -The smallest unit of operation to be performed within a process.

thunk -term used to describe the process of address conversion, stack, and structure realignment that is necessary when passing control between 16-bit and 32-bit modules.

thunk layer -An interface that converts 32-bit parameters to 16-bit parameters, and maps linear addresses to segmented addresses.

time slice -(1) The period of processing time allocated for running a program. (2) An interval of time on the processing unit allocated for use in performing a task. After the interval has expired, processing unit time is allocated to another task, so a task cannot monopolize processing unit time beyond a fixed limit.

tuple -In a relational database, a part of a relation that uniquely describes an entity and its attribute.

Glossary - U

U

unnamed pipe -A circular buffer created in memory; used by related processes to communicate with one another. Contrast with named pipe.

Glossary - V

V

VBIOS -Virtual BIOS device driver

VCMOS -Virtual CMOS device driver

VDD -Virtual device driver

VDH -Virtual video Device Handler

VDM -Virtual DOS Machine; use DOS session.

VDMA -Virtual Direct Memory Access device driver

VDSK -Virtual hard DiSK device driver

video graphics adapter (VGA) -A computer adapter that provides high- resolution graphics and a total of 256 colors.

VIO -Virtual Input/Output

VIRR -Virtual Interrupt Request Register

Virtual Device Driver (VDD) -In the OS/2 operating system, a type of device driver used by DOS programs running in a DOS session to access devices, such as the screen or mouse, which must be shared with other processes in the system. The virtual device driver maps DOS device commands to the normal (physical) device driver under OS/2 2.0 and later versions of the operating system.

virtual DevHlp (VDH) -Kernel (linear memory, paging, hardware interrupt, event control, port control) services provided to virtual device drivers.

virtual I/O (VIO) -A facility that pages data into and out of external page storage.

virtual memory -Synonym for virtual storage.

Virtual Programmable Interrupt Controller -Virtualizes the 8259 Programmable Interrupt Controller (PIC). A special virtual device driver, in that it provides services to other virtual device drivers.

virtual storage -Addressable space that is apparent to the user as the processor storage space, from which the instructions and the data are mapped into the processor storage locations. Synonymous with virtual memory .

visible region -A window's presentation space clipped to the boundary of the window and the boundaries of any overlying window.

VPIC -Virtual Programmable Interrupt Controller device driver.

VRAM -Video Random-Access Memory.

VTIMER -Virtual TIMER device driver.

V86 mode -Virtual 8086 mode of the 80386 CPU.

Glossary - W

W

window coordinates -A set of coordinates by which a window position or size is defined; measured in device units, or pels.

Glossary - X

X

Glossary - Y

Y

There are no glossary terms for this initial letter.

Glossary - Z

Z

This chapter is based in part on the VESA SVPMI (Video Electronics Standards Association Super VGA Protect Mode Interface) proposal.