DrvEnableSurface

HSURF DrvEnableSurface(

IN DHPDEV dhpdev

);

DrvEnableSurface sets up a surface to be drawn on and associates it with a given PDEV.

Parameters

dhpdev: Identifies a handle to a PDEV. This value is the return value of DrvEnablePDEV. The PDEV describes the physical device for which a surface is to be created.

Return Value

The return value is a handle that identifies the newly created surface. Otherwise, it is zero, and an error code is logged.

Comments

Depending on the device and circumstances, the driver can do any of the following to enable the surface:

If the driver manages its own surface, the driver can call EngCreateDeviceSurface to get a handle for the surface.
GDI can manage the surface completely if the device has a surface that resembles a standard-format bitmap. The driver can obtain a bitmap handle for the surface by calling EngCreateBitmap with a pointer to the buffer for the bitmap.
GDI can collect the graphics directly onto a GDI bitmap. The driver should call EngCreateBitmap, allowing GDI to allocate memory for the bitmap. This function is generally used only by printer devices.

Any existing GDI bitmap handle is a valid surface handle.

Before defining and returning a surface, a graphics driver must associate the surface with the physical device using EngAssociateSurface. This GDI function allows the driver to specify which graphics output routines are supported for standard-format bitmaps. A call to this function can only be made when no surface exists for the given physical device.

DrvEnableSurface is required for graphics drivers.