NtGdiDdResetVisrgn function
[This function is subject to change with each operating system revision. Instead, use the Microsoft DirectDraw and Microsoft Direct3DAPIs; these APIs insulate applications from such operating system changes, and hide many other difficulties involved in interacting directly with display drivers.]
Used to enable the user mode to gain a valid understanding of the clipping region for windows on the desktop. This clipping can change asynchronously from the point of view of user-mode threads.
Syntax
BOOL APIENTRY NtGdiDdResetVisrgn(
_In_ HANDLE hSurface,
_In_ HWND hwnd
);
Parameters
-
hSurface [in]
-
Pointer to the user-mode object of any surface belonging to the DirectDraw device for which clipping is to be reset. For details, see the DDK documentation.
-
hwnd [in]
-
Reserved.
Return value
If successful, this function returns TRUE; otherwise it returns FALSE.
Remarks
Clipping can change asynchronously from the point of view of user-mode threads. The kernel-mode parts of DirectDraw and Windows Graphics Device Interface (GDI) maintain a counter that is incremented whenever the clipping list for the entire desktop changes. A call to this function records this counter with every existing DirectDraw primary surface on the system.
At any later time when one of these primary surfaces is modified by a IDirectDrawSurface7::Blt or IDirectDrawSurface7::Lock operation (see DDK documentation), then the counter recorded with the surface is compared with the global counter. If these values are different, an error code DDERR_VISRGNCHANGED is returned to the user-mode code. The user-mode code will then re-query the current clipping for the desktop, call NtGdiDdResetVisrgn, and re-try the IDirectDrawSurface7::Blt applied to the primary surface, respecting the new clipping. Eventually, the clipping that was sampled by the user-mode code will be the same as the current clipping owned by kernel mode, and the IDirectDrawSurface7::Blt will be allowed to continue.
Applications are advised to use the IDirectDrawClipper interface or IDirect3DDevice8::Present method to handle asynchronous clipping changes. These constructs implement asynchronous clipping in an automated and operating-system-independent way.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows 2000 Professional [desktop apps only] |
| Minimum supported server |
Windows 2000 Server [desktop apps only] |
| Header |
|
See also