The EngAssociateSurface function marks a given surface as belonging to a specified device.
Handle to the device with which the surface is to be associated. This is the GDI-created handle that was passed to the driver's DrvCompletePDEV function.
Specifies the functions that the driver can hook from GDI. The driver must implement the corresponding function for every bit that it sets in flHooks. This member is a bitwise OR of any of the following values:
Flag Function to be hooked
The return value is TRUE if the function is successful. Otherwise, the driver should send the information to the GDI function it is implementing, and return GDI's return value.
EngAssociateSurface can be used by printer drivers to implement "rules" or device fonts, or by display drivers to make use of special blt hardware.
If the surface identified by hsurf is a standard format bitmap, the driver can specify which output functions to the surface it will handle by setting bits in flHooks. Setting bits in flHooks causes particular output functions to be sent to the driver instead. This is referred to as hooking. If the driver does not hook a call, GDI will automatically manage the operation when a standard format bitmap is being drawn on.
By default, when a driver supports device bitmaps by implementing DrvCreateDeviceBitmap/DrvDeleteDeviceBitmap, GDI does not automatically synchronize drawing calls to the device bitmap and to the primary surface. For example, GDI can call the driver's DrvBitBlt function to draw to a device bitmap, while another thread is drawing to the primary surface by executing the driver's implementation of DrvTextOut. The driver can even be called to draw to multiple device bitmaps at the same time.
After DrvEnableSurface returns a handle to a primary surface, do not call EngAssociateSurface on that handle. Doing so can cause a bug check in certain circumstances. For more information, see Microsoft Knowledge Base article 330248.
Available in Windows 2000 and later versions of the Windows operating systems.