PDRREF:Display Drivers

Presentation Device Driver Reference for OS/2

Introduction to OS/2 Presentation Drivers Design Considerations for All Drivers Graphics Engine/Presentation Driver Design Changes Design Considerations for Display Drivers Design Considerations for Hardcopy Drivers Display Drivers Distributed Console Access Facility (DCAF) Architecture Graphics Engine Hardcopy Drivers Queue Drivers Port Drivers Presentation Manager Function Categories Exported Driver Function Reference Mandatory and Simulated Graphics Engine Function Reference Device Support Function Reference DBIDI Command Structures and Command Flow Appendixes A - OS/2 Version Compatibility Considerations B - Syntax Conventions C - Format of the Journal File D - Bit-Map Simulation for 16-Bit Hardcopy Drivers E - Data Types F - Notices Miscellaneous G - Glossary

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

This chapter describes video cursor support and the installation utility program used by OS/2 display drivers.

Exported Entry Points (Cursor)

The following entry point is exported by the dynamic link library of a display driver:

EXPORTS
   MoveCursorBlock     @103

MoveCursorBlock

Display drivers must export an entry point for the MoveCursorBlock table. This table contains information about the display driver's MoveCursor routine (code) and data areas. The table values are checked after the display driver is initialized. This allows the driver to determine the correct values.

 typedef struct _MCDESCRIPTION {
     PVOID    pMoveCursor;
     ULONG    ulCodeLength;
     PVOID    pCursorData;
     ULONG    ulDataLength;
 } MCDESCRIPTION;
 typedef MCDESCRIPTION * PMCDESCRIPTION;

The fields in the MCDESCRIPTION data structure are described below:

pMoveCursor

Flat address of the MoveCursor routine in the display driver.

ulCodeLength

Length in bytes of the MoveCursor routine

pCursorData

Flat address of the data area used by the MoveCursor routine

ulDataLength

Length in bytes of the data area used by the MoveCursor routine

This routine supports calls from the system timer (at interrupt time). The strategy for the MoveCursor routine is that the pointer is checked and, if necessary, redrawn or excluded at timed intervals.

The PMDD.SYS physical device driver creates a privilege level 0 alias for the data address and passes the alias to the routine in the EAX register when MoveCursor is called at interrupt time. Therefore, all data addressing within the routine must be performed relative to this address.

At entry to the MoveCursor routine, the stack contains the following:

VOID MoveCursor(LONG abs_x, LONG abs_y, PVOID pCursorData)

Using the C calling convention, the stack contains two LONGs, which hold the X- and Y-coordinates of the cursor hot spot, and a PVOID that is a pointer to the cursor data area that is valid in the current context. All references to this data area must be done relative to the address passed in. If the X- and Y-coordinates are set to 0x80000000, this signifies a CheckCursor call.

Regular timer interrupts give the presentation driver an opportunity to check whether the pointer is valid. For example, the driver can check the following:

• Have new X- and Y- coordinates been set?
• Is the pointer excluded because of a drawing operation? If so, has that operation been completed?
• Is the pointer currently visible (although it should be excluded) because it is in an area that is being redrawn?

At the end of the MoveCursor routine, a check is performed to see if a new location was given for the pointer while it was being drawn. If the pointer has moved again, it must be drawn at the new location or be excluded because it has moved into the protection rectangle. This implies that the routine needs to track both real (X,Y) and pointer (X,Y) coordinates.

Programming Considerations

Typical cursors are an arrow or a cross with an action point called the hot spot at the point of the arrow or the center of the cross. When the presentation driver draws a cursor, the origin of the image must be offset to place the action point at the required (X,Y) position. The required offset is specified in the call to GreSetCursor. Because the cursor entry point can be called at various times from many different places, the cursor routine uses semaphores to protect itself (protection is the responsibility of the presentation driver). Similarly, because cursor drawing can be a time-consuming operation, the display driver must also protect itself against re-entrance.

The display driver must resolve all interactions between cursor drawing at interrupt time and access to video hardware. While in the background, the display driver does not draw any cursor image.

Caution should be used when the display is a buffered device and the cursor is drawn into a bit map in the buffer. In this case, the display driver deletes the cursor and excludes it when a draw operation occurs at the cursor location. To do this, the driver does a "hit test" for each output operation to see if the cursor location is in the drawing area and to set a protection rectangle that is used to exclude the cursor.

Introduction to Display Driver Installation

The OS/2 2.0 Display Driver Installation utility program (DSPINSTL.EXE) provides all the facilities necessary to install and configure OS/2 display drivers. The OS/2 display driver installation installs and configures PM display drivers. It might also include the installation and configuration of WIN-OS/2 display drivers, and the installation of base video service (VIO) drivers and DOS virtual device drivers (VDDs).

Display driver installation and configuration is more complex than standard device driver installation. It typically includes the following activities:

• Allowing the user to select OS/2 display characteristics - Specification of the type and resolution of the display driver to be installed. (See Allowing the User to Select OS/2 Display Driver Characteristics)
• Copying display driver-related files - Copying 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 system configuration files - Appropriately updating various OS/2 and WIN-OS/2 configuration files to ready the new display driver for subsequent execution when the user's system is restarted (see Updating System Configuration Files).

Allowing the User to Select OS/2 Display Driver Characteristics

The user needs to specify whether the display driver to be installed will be used as the primary display adapter or as the secondary display adapter.

The user must then specify the type of display driver to install. This is important 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 the high-resolution XGA display driver or other lower resolution standard display drivers such as video graphics array (VGA) or enhanced graphics adapter (EGA) display drivers.

Finally, because some display drivers can support operation at more than one graphics resolution, the user might have to specify the display resolution at which the driver is to be operated. Display resolutions are typically specified by supplying the width and height of the display (in pels) and the maximum number of colors that can be simultaneously displayed. The user's choices for display resolution are often affected 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 can affect which display resolutions can be run.

Copying Display Driver-Related Files

There are several factors that can complicate the copying of display driver-related files from source directories to target directories. First, display driver files might be sufficiently large and numerous to span more than one source diskette. This can easily occur when several display drivers that support different display resolutions are bundled together on the same diskettes (along with their associated font and resource files). Second, to save space within the source directory, it might be desirable to place packed files within the source directory. If so, the packed files should be unpacked when they are copied to the target directory. Third, the display driver packager might wish to specify file version checks that are to take place before file copying is performed. Such checks are valuable because they can prevent the inadvertent replacement of updated display driver files by older versions of the files.

Updating System Configuration Files

After display driver-related files have been copied to the user's system it is necessary to update different system configuration files to complete the installation process. Frequently, the CONFIG.SYS and OS2.INI files need to be updated to complete PM display driver installation and the SYSTEM.INI and WIN.INI files need to be updated to complete the WIN-OS/2 display driver installation. Depending on the display driver to be installed, other configuration files might also have to be updated.

Display Driver Installation Utility Program

DSPINSTL, the display driver installation utility program, is similar in some ways to the OS/2 Device Driver Installation utility program, DDINSTAL.EXE. DSPINSTL contains extensions that are specifically geared to simplify the steps that the user must perform to install and configure OS/2 display drivers. Because different types of OS/2 display drivers can have radically different installation and configuration requirements, DSPINSTL contains a set of features that allows a display driver developer to customize the installation process to meet the developer's special needs.

DSPINSTL consists of the following six major components:

• DSPINSTL Configuration File (DSC file) Interpreter
• Initial User Interface PM Panels - A standard set of PM panels that serve as a basic front-end user interface (see User Interface PM Panels).
• Action Routine Interface - An interface that allows the display driver developer to (optionally) add custom control logic (see Action Routine Interface).
• Service Functions - A set of standard service functions that can be called from within an action routine (see reference to service functions under Action Routine Interface and DSPINSTL Service Functions).
• Command Language PM Panels - A standard set of PM panels that act as the front end to the DSPINSTL Command Language Interpreter (see Command Language Presentation Manager Panels).
• Command Language Interpreter - The final stage of DSPINSTL that executes the installation and configuration commands that are packed in Display Driver Profile files (DSP files) (see DSPINSTL Command Language Interpreter).

DSPINSTL Configuration File Interpreter

The DSPINSTL Configuration file (DSC file) interpreter allows the display driver developer to specify, within the DSC files, the high level knowledge that characterizes one or more display driver packages. The information contained in the DSC files determines the contents of some of the fields in the standard set of PM panels. It also initializes a chain of data elements that will subsequently be passed to the DSPINSTL Command Language Interpreter that executes as the final stage of DSPINSTL operation.

Command Language Presentation Manager Panels

       ===DSPINSTL Command Language Interpreter===
           ====DSPINSTL Command Language====
           ====DSPINSTL Commands====
           ====KEY====
           ====FILES====
               =====File Version Field Checking=====
               =====Date/Time Checking =====
           ====CONFIG====
           ====OS2INI====
           ====WININI====
           ====RUN====
           ====SET_DRIVER====
           ====SET_RESOLUTION ====