Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This method attaches a Clipperobject to or deletes one from a surface.

Syntax 

HRESULT SetClipper(
  LPDIRECTDRAWCLIPPER
 lpDDClipper
);

Parameters

lpDDClipper

Address of the IDirectDrawClipperinterface for the DirectDrawClipperobject that will be attached to the DirectDrawSurfaceobject. If this parameter is NULL, the current DirectDrawClipperobject will be detached.

Return Value

If the method succeeds, the return value is DD_OK.

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOCLIPPERATTACHED

For more information on these error codes see DirectDraw Return 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 lpDDClipperparameter, the clipper is removed from the surface, and the clipper's reference count is decremented.

If you do not delete the clipper, the surface releases its reference to the clipper when the surface itself is released.

According to COM rules, your application is responsible for releasing references it holds to the clipper when the object is no longer needed.

This method is mainly used by surfaces that are being overlaid on or blitted to the primary surface. However, it can be used on any surface.

After a DirectDrawClipperobject has been attached and a clip list is associated with it, the DirectDrawClipperobject will be used for the IDirectDrawSurface::Bltand IDirectDrawSurface::UpdateOverlayoperations involving the parent DirectDrawSurfaceobject.

This method can also detach a DirectDrawSurfaceobject's current DirectDrawClipperobject.

Requirements

Header ddraw.h
Library ddraw.lib
Windows Embedded CE Windows Embedded CE 6.0 and later
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

See Also