EngAssociateSurface

BOOL EngAssociateSurface(

IN HSURF hsurf,

IN HDEV hdev,

IN FLONG flHooks

);

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

Parameters

hsurf

Identifies the surface or bitmap to be associated with hdev.

hdev

Identifies the device with which the surface is to be associated. This is the handle that was passed to DrvCompletePDEV.

flHooks

Specifies a set of flags that control the functions the driver can hook. The flags that can be set are as follows:

Flag	Function to be hooked
HOOK_BITBLT	DrvBitBlt
HOOK_STRETCHBLT	DrvStretchBlt
HOOK_TEXTOUT	DrvTextOut
HOOK_PAINT	DrvPaint
HOOK_STROKEPATH	DrvStrokePath
HOOK_FILLPATH	DrvFillPath
HOOK_STROKEANDFILLPATH	DrvStrokeAndFillPath
HOOK_LINETO	DrvLineTo
HOOK_COPYBITS	DrvCopyBits
HOOK_SYNCHRONIZE	DrvSynchronize
HOOK_SYNCHRONIZEACCESS	See Comments below.

When a standard format bitmap is being drawn on, GDI automatically manages the operation. Setting bits in this parameter, except for HOOK_SYNCHRONIZEACCESS, causes particular output functions to be sent to the driver instead. This is referred to as hooking.

EngAssociateSurface can be used by printer drivers to implement “rules” or device fonts, or by frame buffer display drivers to make use of special blt hardware.

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.

Comments

If the specified surface is a standard format bitmap, the driver can specify which output functions to the surface it will handle.

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.

The HOOK_SYNCHRONIZEACCESS flag can be set by the driver to ensure that all drawing calls to the surface are synchronized, or single-threaded.

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.

A display driver can use the HOOK_SYNCHRONIZEACCESS value to have GDI synchronize access for drawing on this surface while drawing occurs on the main surface; or on any other surface that the driver supports. Such single-threading can be necessary if:

The driver creates device-managed bitmaps in the same memory block that the primary display surface is in, and;
The driver can’t have two calls accessing the memory block, or its hardware drawing accelerators, at the same time.

Most hardware must be used synchronously and such synchronization is managed by GDI when the driver sets the HOOK_SYNCHRONIZEACCESS flag. This flag causes GDI to synchronize all accesses to that device bitmap with all accesses to the primary surface, or to any other synchronized device bitmap. That is, if the driver sets this flag for all device bitmaps, it will be guaranteed to be single-threaded for any drawing operation.

Note GDI only allows one drawing thread to access a surface at a time. If a device driver supports device format bitmaps, then many threads might be in the driver at the same time drawing on different surfaces. The driver does not, by default, single-thread access all device surfaces, but if the HOOK_SYNCHRONIZEACCESS bit is specified in EngAssociateSurface for all a driver's device bitmaps, then GDI will single-thread all drawing calls to the driver.

IN HSURF hsurf,
IN HDEV hdev,
IN FLONG flHooks
);