Expand Minimize

EngAssociateSurface function

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

Syntax


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:

FlagFunction 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

Version

Available in Windows 2000 and later versions of the Windows operating systems.

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

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft