NtGdiDdResetVisrgn function

Articolo
01/06/2021

[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	Ntgdi.h