EngAssociateSurface

The EngAssociateSurface function marks a given surface as belonging to a specified device.

BOOL
  EngAssociateSurface(
    IN HSURF  hsurf,
    IN HDEV  hdev,
    IN 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 bit-wise OR of any of the following values:

Flag	Function to be hooked
HOOK_ALPHABLEND	DrvAlphaBlend
HOOK_BITBLT	DrvBitBlt
HOOK_COPYBITS	DrvCopyBits
HOOK_FILLPATH	DrvFillPath
HOOK_GRADIENTFILL	DrvGradientFill
HOOK_LINETO	DrvLineTo
HOOK_MOVEPANNING	Obsolete
HOOK_PAINT	Obsolete
HOOK_PLGBLT	DrvPlgBlt
HOOK_STRETCHBLT	DrvStretchBlt
HOOK_STRETCHBLTROP	DrvStretchBltROP
HOOK_STROKEANDFILLPATH	DrvStrokeAndFillPath
HOOK_STROKEPATH	DrvStrokePath
HOOK_SYNCHRONIZE	DrvSynchronize or DrvSynchronizeSurface (either or both)
HOOK_SYNCHRONIZEACCESS	Obsolete
HOOK_TEXTOUT	DrvTextOut
HOOK_TRANSPARENTBLT	DrvTransparentBlt

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.

Headers

Declared in winddi.h. Include winddi.h.

Comments

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.

See Also

DrvBitBlt, DrvCompletePDEV, DrvCopyBits, DrvCreateDeviceBitmap, DrvDeleteDeviceBitmap, DrvEnableSurface, DrvFillPath, DrvLineTo, DrvStretchBlt, DrvStrokeAndFillPath, DrvStrokePath, DrvSynchronize, DrvSynchronizeSurface, DrvTextOut, EngModifySurface