EngModifySurface function (winddi.h)
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 |