OS2 PM DRV ENABLE

The enable entry point is exported as OS2_PM_DRV_ENABLE by the presentation driver. The Enable routine in the driver supports a set of subfunctions that enable or disable the environment for a device context owned by a specific application or process. When a device context is opened or closed, the Presentation Manager interface issues a series of calls to subfunctions at the enable entry point. These calls initialize the presentation driver, the physical device, and the device context.

Syntax

OS2_PM_DRV_ENABLE (Subfunc, Param1, Param2)

Example Code

LONG APIENTRY OS2_PM_DRV_ENABLE (Subfunc, Param1, Param2)

ULONG   Subfunc;
ULONG   Param1;
ULONG   Param2;

Note

LONG, ULONG (unsigned LONG), and APIENTRY are defined in OS2DEF.H, which is included through the header file OS2.H.

Stack Frame

At entry to the OS2_PM_DRV_ENABLE routine, the stack frame contains:

Parameter	Description
Subfunction	32-bit value identifying the subfunction
Param1	First parameter
Param2	Second parameter

Subfunctions

Presentation drivers must support the following OS2_PM_DRV_ENABLE subfunctions:

• 01h FillLogicalDeviceBlock
• 02h FillPhysicalDeviceBlock
• 04h DisablePhysicalDeviceBlock
• 05h EnableDeviceContext
• 06h DisableDeviceContext
• 07h SaveDCState
• 08h RestoreDCState
• 09h ResetDCState
• 0Ah CompleteOpenDC
• 0Bh BeginCloseDC
• 0Ch InstallPMEngineDisplayHooks

Note

The OS2_PM_DRV_ENABLE function should return -1 (ERROR_MINUS) for Subfunction 03h, and numbers greater than 0Ch.

Device Context Manager

Device contexts are opened in response to an application or process calling the DevOpenDC API function. On receiving this call, Presentation Manager loads the presentation driver (if it is not already present and able to support the device context) and issues a series of calls to the enable entry point.

Initially, when the presentation driver has not been enabled for use by the calling application or process, the driver receives the series of calls shown in the following figure. When the driver has been enabled for an application or process, the sequence of calls to enable additional device contexts does not include subfunction FillLogicalDeviceBlock and, depending upon a requirement that the driver posts in the initial enable sequence, includes or excludes FillPhysicalDeviceBlock.

The OS2_PM_DRV_ENABLE entry point handles the DC management functions. Those functions can be placed in three categories:

• Transactions involved in opening a DC
• Transactions involved in closing a DC
• Other DC functions including SaveDC, RestoreDC and ResetDC

Opening and Closing DCs

The open and close transaction sequences are symmetrical.

Device contexts are opened in response to an application or process calling the DevOpenDC API function. On receiving this call, the graphics engine (PMGRE.DLL) loads the presentation driver, if it is not already present and able to support the device context, and issues a series of calls to the OS2_PM_DRV_ENABLE entry point.

Initially, when the presentation driver has not been enabled for use by the calling application or process, the driver receives the Open Transaction series of calls. When the driver has been enabled for an application or process, the sequence of calls to enable additional device contexts can include FillLogicalDeviceBlock and, depending upon a requirement that the driver posts in the initial enable sequence, includes or excludes FillPhysicalDeviceBlock.

Each of the Close Transaction functions undoes actions taken by a corresponding Open Transaction function. For example, theEnableDeviceContext subfunction allocates the DDC data area within the presentation driver and returns the hDDC handle. The DisableDeviceContext subfunction deallocates the DDC data area.

The FillLogicalDeviceBlock transaction occurs when a thread of a process opens the first instance of a DC for this presentation driver. During this transaction, a dispatch table will be created for later use by the graphics engine.

The FillPhysicalDeviceBlock transaction will occur only if the result flags from the FillLogicalDeviceBlock transaction indicate that it is necessary. See the description of Bit 2 under FillPhysicalDeviceBlock.

This subfunction is used by presentation drivers that support multiple types of physical devices. It will occur during the DevOpenDC call for every DC associated with a particular type of physical device. (This is where any memory allocation and initializations relating to a physical device should be done.) During the EnableDeviceContext transaction, the presentation driver will allocate and format the driver-specific data (DDC) associated with the DC being constructed. At CompleteOpenDC time, the DC is completely constructed and initialized. This transaction gives the presentation driver anopportunity to make final adjustments to the DC before the application gets access to it.

If either the FillLogicalDeviceBlock or FillPhysicalDeviceBlock transaction returns a failure return code, no other transactions are requested by the graphics engine.

If the EnableDeviceContext fails, the DisablePhysicalDeviceBlock transaction is sent to the presentation driver. If the CompleteOpenDC transaction fails, the BeginCloseDC, DisableDeviceContext, and DisablePhysicalDeviceBlock transactions are sent to the presentation driver.

If an application has opened a device context, but the application terminates before it closes the device context, the graphics engine still calls the disable routines BeginCloseDC, DisableDeviceContext, and DisablePhysicalDeviceBlock, as expected by the presentation driver when a device context is closed explicitly by an application.

Saving and Restoring Device Contexts

The SaveDCState and RestoreDCState subfunctions manage a stack of entries that correspond to most of the state of a DC. SaveDCState pushes an entry on the stack. RestoreDCState retrieves one of the pushed entries and uses it to revert the DC back to its earlier saved state. Note that a particular RestoreDCState call can pop more than one entry from the stack of SaveDC entries.

Resetting an Device Context

This call resets a DC to its original initialized state, as it was just after the CompleteOpenDC transaction.