DrvEnableSurface

This function sets up a surface to be drawn on and associates it with a specified PDEV.

Syntax

HSURF DrvEnableSurface( IN DHPDEV dhpdev );

Parameters

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

Return Values

A handle that identifies the newly created surface indicates success. Zero indicates failure.

Remarks

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 the EngCreateDeviceSurface function to get a handle to the surface.
The 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 the EngCreateBitmap function with a pointer to the buffer for the bitmap.
The GDI can collect the graphics directly onto a GDI bitmap. The driver should call EngCreateBitmap, allowing the 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 the EngAssociateSurface function. 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.

This function is required for graphics drivers.