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

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.

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

See also

DrvBitBlt

DrvCompletePDEV

DrvCopyBits

DrvCreateDeviceBitmap

DrvDeleteDeviceBitmap

DrvEnableSurface

DrvFillPath

DrvLineTo

DrvStretchBlt

DrvStrokeAndFillPath

DrvStrokePath

DrvSynchronize

DrvSynchronizeSurface

DrvTextOut

EngModifySurface