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 Functions This 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:
- Disjointed (not special cased)
- Identical (not special cased)
- 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.
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
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:
- 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.
- At the Procomm Plus screen, press [Enter] to go to terminal mode.
- Press [Alt+D] for dial mode.
- Type the number and start the call.
- When the connection has been established perform login.
- Type a "U" to upload a file or a "D" to download a file.
- Type the modem protocol type. The most common protocols are Kermit, Xmodem and Ymodem. Use these protocols along with a mixture of the others.
- Type the file name.
- To begin the file transfer, press Page Down to download files or Page Up to upload files.
- Verify that the file transfer has completed.
- 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:
- 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
- Select File | Exit to exit CorelDRAW.
- Select NO to save changes in MINE.CDR.
- Make the MOSAIC window active.
- Select File | Exit to exit MOSAIC.
- Open a OS/2 Full Screen or OS/2 Window.
- Change to the \COREL32 directory.
- 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
- Open CorelTRACE** in a seamless mode.
- Select Help | Contents.
- Select File | Exit to close the help window.
- Select File | Exit to close CorelTRACE.
- Open CorelTRACE in a full screen mode.
- Close CorelTRACE.
Testing CorelCHART
- Open CorelCHART** in a seamless mode.
- Select File | Open and double-click on the Chart subdirectory.
- Select 3DRISER and click on 3D0005.CCH. It appears in the preview window .
- Press OK.
- Select Help | Content.
- Select File | Exit to close the help window.
- Select File | Exit to close CorelCHART.
- Open CorelCHART in a full screen mode.
- 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.
This chapter is based in part on the VESA SVPMI (Video Electronics Standards Association Super VGA Protect Mode Interface) proposal.
Display Device Driver Reference for OS/2:OS/2 Version Compatibility Considerations