EngCreateWnd

WNDOBJ *EngCreateWnd(

SURFOBJ *pso,
HWND hwnd,
WNDOBJCHANGEPROC pfn,
FLONG fl,
int iPixelFormat
);

EngCreateWnd creates a WNDOBJ for the window referenced by hwnd.

Parameters

pso

Identifies the device surface.

hwnd

Handle that identifies a window created by an application’s call to CreateWindow or an equivalent function.

pfn

Points to a driver-defined callback function that GDI calls for changes to the window identified by hwnd. In the context of this function, the WNDOBJ values will be unchanged. The prototype for this callback function is defined in the header file as follows:

VOID (CALLBACK * WNDOBJCHANGEPROC)(WNDOBJ *pwo, FLONG fl);
 

The callback’s pwo parameter points to the window object that is currently changing and that contains the new size and position of the window. This parameter is null if fl is WOC_CHANGED.

The callback’s fl parameter can be one of the values listed in the following table:

Flag	Meaning
WOC_RGN_CLIENT_DELTA	The window object contains a delta client region. The delta region is valid for this call only.
WOC_RGN_CLIENT	The window object contains a new visible client region.
WOC_RGN_SURFACE_DELTA	The window object contains a delta surface region. The pvConsumer field of the WINOBJ contains 0. The delta region is valid for this call only.
WOC_RGN_SURFACE	The window object refers to a surface region created by GDI. The pvConsumer field of the WINOBJ contains 0.
WOC_CHANGED	Indicates that all WNDOBJ callbacks have been made for the current desktop update. GDI always notifies the driver at the end of a desktop update. Note that pwo is null here.
WOC_DELETE	The window object is deleted as a result of the deletion of the window.

fl

Bitmask that specifies the type of changes to track. This value must be consistent through all WNDOBJ requests made by the driver. This parameter can be one or more of the following bit field values:

Bit field	Meaning
WO_RGN_CLIENT_DELTA	GDI should track changes in the delta client region of the window object, and notify the driver when the window’s visible region changes. The region enumerated in the callback function is a non-empty delta area that is in the new region but not in the old region. The delta region is valid during the callback only.
WO_RGN_CLIENT	GDI should track changes in the client region of the window object, and notify the driver when the window’s visible client region changes. The region enumerated in the callback function is the new visible client area of the window.
WO_RGN_SURFACE_DELTA	GDI should track changes in the delta surface region of the window object, and notify the driver when the surface region changes. The region enumerated in the callback function is a non-empty delta area that is in the new surface region but not in the old surface region. The delta surface region is valid during the callback only.
WO_RGN_SURFACE	GDI should track changes in the surface region of the window object, and notify the driver when the surface region changes. The surface region is the display surface area excluding all visible client regions of the windows being tracked by the driver.
WO_RGN_UPDATE_ALL	GDI should notify the driver for all windows it tracks when any of its windows’ visible regions change. This flag must be used in conjunction with the WO_RGN_CLIENT flag.

iPixelFormat

Specifies the pixel format associated with the window object. The pixel format of a window object is fixed. This parameter can be zero if there is no associated pixel format.

Return Value

The return value is a pointer to a WNDOBJ if the function is successful. Otherwise, the return value is -1 if the same window is being tracked by the driver, or zero if the driver is not tracking the same window.

Comments

Because creating a window object involves locking window resources, EngCreateWnd should be called only in the context of the WNDOBJ_SETUP escape in DrvEscape.

EngCreateWnd supports window tracking by multiple drivers. Each driver is identified by a unique pfn function pointer. For example, a live video driver can track changes to live video windows while an OpenGL driver is tracking changes to OpenGL windows.

GDI will call the function pointed to by pfn with the most recent window state if a new WNDOBJ is created by DrvEscape. GDI will also notify the pfn function when a window described by a WNDOBJ is destroyed.

See Also

DrvEscape, WNDOBJ