Edit

EngModifySurface function (winddi.h)

  • Article

The EngModifySurface function notifies GDI about the attributes of a surface that was created by the driver.

Syntax

ENGAPI BOOL EngModifySurface(
  HSURF  hsurf,
  HDEV   hdev,
  FLONG  flHooks,
  FLONG  flSurface,
  DHSURF dhsurf,
  VOID   *pvScan0,
  LONG   lDelta,
  VOID   *pvReserved
);

Parameters

hsurf

Handle to the surface to be modified. This parameter is the surface handle returned by EngCreateDeviceBitmap or EngCreateDeviceSurface, or from the hsurf member of the SURFOBJ structure.

hdev

Handle to the device with which the surface is to be associated. This is the handle that GDI passed to DrvCompletePDEV.

flHooks

Is a set of flags that control the functions the driver can hook whenever GDI drawing occurs on the specified surface. This can be a bitwise OR of any of the HOOK_Xxx values listed on the EngAssociateSurface reference page.

flSurface

Is a set of flags that describe the surface's attributes. Currently, the driver should set this to MS_NOTSYSTEMMEMORY when the surface is located in video memory.

dhsurf

Identifies the surface to the driver. The driver can set this to anything; GDI sets the dhsurf member of the resulting surface's SURFOBJ structure to this value if the function is successful.

pvScan0

Pointer to the virtual address of the start of the bitmap.

lDelta

Is the virtual address stride of the bitmap; that is, the number of bytes between the beginning of one bitmap row and the next.

pvReserved

Is reserved and must always be set to NULL.

Return value

EngModifySurface returns TRUE upon success; otherwise it returns FALSE.

Remarks

EngModifySurface allows the driver to modify a device-managed surface and inform GDI of this surface's attributes. This allows drivers to convert the destination surface from being opaque to nonopaque, thus allowing GDI to draw on the surface.

The DIB engine uses pvScan0 and lDelta to draw directly to the surface. When these parameters are NULL, the surface is opaque to GDI, and GDI will revert to calling DrvCopyBits for drawing operations not hooked by the driver.

After DrvEnableSurface returns a handle to a primary surface, do not call EngModifySurface 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

DrvCopyBits

EngAssociateSurface