IDirectDrawSurface7::SetClipper

The IDirectDrawSurface7::SetClipper method attaches a clipper object to, or deletes one from, a surface.

HRESULT SetClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper  
);

Parameters

lpDDClipper

Address of the IDirectDrawClipper interface for the DirectDrawClipper object to be attached to the DirectDrawSurface object. If NULL, the current DirectDrawClipper object is detached.

Return Values

If the method succeeds, the return value is DD_OK.

If it fails, the method can return one of the following error values:

Remarks

When setting a clipper to a surface for the first time, this method increments the clipper's reference count; subsequent calls do not affect the clipper's reference count. If you pass NULL as the lpDDClipper parameter, the clipper is removed from the surface, and the clipper's reference count is decremented. If you do not delete the clipper, the surface automatically releases its reference to the clipper when the surface itself is released. According to COM rules, your application is responsible for releasing any references that it holds to the clipper when the object is no longer needed.

This method is primarily used by surfaces that are being overlaid on, or blitted to, the primary surface. However, it can be used on any surface. After a DirectDrawClipper object has been attached and a clip list is associated with it, the DirectDrawClipper object is used for the IDirectDrawSurface7::Blt, IDirectDrawSurface7::BltBatch, and IDirectDrawSurface7::UpdateOverlay operations involving the parent DirectDrawSurface object. This method can also detach the current DirectDrawClipper object of a DirectDrawSurface object.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 98.
  Header: Declared in ddraw.h.

See Also

IDirectDrawSurface7::GetClipper