Enabling and Disabling the Surface

  • Article

As the final initialization stage, GDI calls DrvEnableSurface to have the driver enable a surface for an existing PDEV. DrvEnableSurface must specify the type of surface by calling the appropriate GDI service to create it. As described in GDI Support for Surfaces, and depending on the device and circumstances, the driver can call the appropriate GDI services from within DrvEnableSurface to create the surfaces:

  • For a device-managed surface, the driver should call the EngCreateDeviceSurface function to get a handle for the surface.

  • To create a standard-format (DIB) bitmap that GDI can manage completely, including the performance of all drawing operations, the driver should call the EngCreateBitmap function. The driver can hook out any drawing operations it can optimize. The driver can either have GDI allocate the space for the pixels or can provide the space itself, although the latter option is usually used only by printer and frame buffer drivers.

DrvEnableSurface returns a valid surface handle as a return value.

Following the creation of the surface, the driver must associate that surface with a PDEV by calling the GDI service EngAssociateSurface. This call also tells GDI which drawing functions a driver has hooked for that surface.

GDI calls the DrvDisableSurface function to inform the driver that the current surface created for the PDEV by DrvEnableSurface is no longer required. The driver must deallocate any memory and resources allocated during the execution of DrvEnableSurface. DrvDisableSurface is always called before DrvDisablePDEV, if the PDEV has an enabled surface.

Once created, a surface must be deleted when it is no longer in use. Failure to properly match surface creation with deletion can cause stray objects to accumulate and degrade system performance.