EngAssociateSurface function (winddi.h)
The EngAssociateSurface function marks a given surface as belonging to a specified device.
Syntax
ENGAPI BOOL EngAssociateSurface(
HSURF hsurf,
HDEV hdev,
FLONG flHooks
);
Parameters
hsurf
Handle to the surface or bitmap to be associated with hdev. This handle was returned by EngCreateBitmap or EngCreateDeviceBitmap.
hdev
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.
flHooks
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 |
|---|---|
| HOOK_ALPHABLEND | |
| HOOK_BITBLT | |
| HOOK_COPYBITS | |
| HOOK_FILLPATH | |
| HOOK_GRADIENTFILL | |
| HOOK_LINETO | |
| HOOK_MOVEPANNING | Obsolete |
| HOOK_PAINT | Obsolete |
| HOOK_PLGBLT | |
| HOOK_STRETCHBLT | |
| HOOK_STRETCHBLTROP | |
| HOOK_STROKEANDFILLPATH | |
| HOOK_STROKEPATH | |
| HOOK_SYNCHRONIZE |
DrvSynchronize or DrvSynchronizeSurface (either or both) |
| HOOK_SYNCHRONIZEACCESS | Obsolete |
| HOOK_TEXTOUT | |
| HOOK_TRANSPARENTBLT |
Return value
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.
Remarks
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.
When the surface is associated, it assumes the default palette and style steps of the PDEV. A surface must be associated before it is returned by DrvEnableSurface.
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Available in Windows 2000 and later versions of the Windows operating systems. |
| Target Platform | Universal |
| Header | winddi.h (include Winddi.h) |
| Library | Win32k.lib |
| DLL | Win32k.sys |