PDRREF:Graphics Engine/Presentation Driver Design Changes

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

In the graphics engine for OS/2 Warp, Version 3, the presentation driver has to support only the current OS2_PM_DRV_ENABLE and DEVESC_ functions. A new enable subfunction call, OS2_PM_DRV_ENABLE: Subfunction 0Eh - QueryDeviceSurface, has been added so that the graphics engine can manage the formerly mandatory functions for presentation drivers.

This graphics engine is designed so that a developer can create a presentation driver with minimal effort, and then incrementally add function that supports specific hardware. In order to achieve this, the new graphics engine does the following:

• Manages Presentation Manager contextual and state information
• Performs rasterization into a linear address specified by the presentation driver
• Provides a set of device support routines

Mandatory Functions now handled by the OS/2 Graphics Engine

The following existing functions will be simulated by the graphics engine:

PolyScanLine

If the current presentation driver's dispatch table has not hooked out this function, the graphics engine will handle the PolyScanLine call. The graphics engine will convert the shortline structure to a set of rectangles and pass them as ROP_PATCOPY BITBLTS to the presentation driver.

DrawLinesInPath

The graphics engine will convert the PLINE structure (which is passed into the DrawLinesInPath function) into the LINEINFO structure required by the SDLine function.

QueryDeviceCaps

The device will now give the capabilities to the graphics engine during the OS2_PM_DRV_ENABLE: QueryDeviceSurface call. The graphics engine will then do the default handling on the information provided earlier. The presentation driver can dynamically change its device capabilities through the GreSetDeviceSurface call.

Bit maps

The graphics engine will create and manage bit maps if the presentation driver has not hooked the following bit map functions:

• DeviceCreateBitmap
• DeviceDeleteBitmap
• DeviceSelectBitmap
• GetBitmapBits
• SetBitmapBits

The engine will support all standard bitcounts (1, 4, 8, 16 and 24) in packed pixel format. All the bit maps are converted to the device's bitcount except monochrome bit maps. Features supported include the following:

• All standard bitcount support
• Only ONE plane (that is, packed pixel)
• Bits are either BOTTOM to TOP or TOP to BOTTOM
• BYTE, 2 BYTE or 4 BYTE alignment
• RLE compression, can add other compression algorithms

BitBlt

Bitblt is fully supported. Presentation drivers need not hook this function or call back for simulation. Bit maps could be stretched, flipped, rotated and sheared. The engine will do the simulation and call Bitblt with COM_DEVICE set (if the Bitblt is hooked) or call SDBitBlt. If SDBitBlt is called, the bits are preclipped. Stretching (not rotation or shear) will be done in batches.

SetPel

The graphics engine converts this call to a BitBlt call with a 1x1x[dst bpp] source bit map. It will behave as described in the OS/2 Presentation Device Driver Reference, Fourth Edition.

GetPel

The graphics engine converts this call to a BitBlt call with a 1x1x[dst bpp] destination bit map. It will behave as described in the OS/2 Presentation Device Driver Reference, Fourth Edition.

CharString

CharString will be handled by retrieving the current position and calling the Device Driver Interface (DDI) CharStringPos.

CharStringPos

CharStringPos simulation will start by handling the current default requirements of the Device Driver Interface. That is, the string is being output in the left/right direction and supports a raster image of the current font. All simulation currently being handled by the engine will still take place; then on the CharStringPos call with the COM_DEVICE flag set, the default handling will take place.

PolyMarker

PolyMarker simulation will be handled by using the default ATM scalable marker that is currently provided for hardcopy drivers. This simulation will give the display marker the ability to support attributes and different sizes with the default marker.

GetCodePage/SetCodePage

The engine now stores the code page in the engine's device context. The code page will be provided by the engine if requested by the driver.

GetDCOrigin

The engine currently stores the device origin in device coordinates on a device context basis. For simulation, the engine will return these values.

DevEscape

This is still a mandatory function. The driver is now required to pass through the DevEscape function to the graphic engine's DevEscape entry point for certain DevEscape simulation (QueryVIOCellSizes).

Attributes

Attributes are already stored by the engine. Now the engine will return only the correct values in the case of DeviceGetAttributes, and set either the appropriate dirty flags or physical attributes in the case of DeviceSetAttributes and DeviceSetGlobalAttribute.

NOP Simulations

The following functions do not require graphics engine simulation, and will simply provide the appropriate return code:

• RealizeFont
• DeviceQueryFontAttributes
• DeviceQueryFonts
• SaveScreenBits
• DeviceSetDCOrigin

OpenDC Modifications

Because of the added driver support, presentation drivers have a smaller subset of mandatory functions. These mandatory functions differ between display and printer drivers. All drivers are still required to handle the Enable subfunctions and a subset of the DEVESC_functions. One new mandatory function is required - OS2_PM_DRV_ENABLE: Subfunction 0Eh - QueryDeviceSurface. This function provides to the graphics engine the information needed for handling the new Device Driver Interface architecture. This call is made from the graphics engine during an OpenDC call.