Using Direct Draw Clippers

Overview

Clippers allow you to restrict which portions of a surface can be blitted to at a particular point of program execution. This is accomplished by specifying one or more rectangles in which blitting can occur, known as a clip list.

Direct Draw Clippers should definitely be used in place of software algorithms that perform clipping, because Direct Draw Clippers will take advantage of video hardware acceleration if available. Note that you must use the IDirectDrawSurface4::Blt() function to perform blit operations, because IDirectDrawSurface4::BltFast() does not support clipping.

Creating a Clipper

First, declare an object of type LPDIRECTDRAWCLIPPER. This object is effectively a pointer to a clipper object. Next, create a clipper by calling IDirectDraw4::CreateClipper(), passing the address of the clipper object pointer that you declared earlier. For example:

LPDIRECTDRAWCLIPPER clipper;
displayDevice->CreateClipper((DWORD)0,&clipper,NULL);

Establishing the Clip List

Next, you need to define the clipped region of the surface by calling the IDirectDrawClipper::SetClipList() function. The following example code demonstrates how to establish a clip list.

RECT clipRect;

SetRect( &clipRect, left, top, right, bottom ); // left, top, right, and bottom are integers defining the clipper rectangle

struct __clipList
{
RGNDATAHEADER hdr;
RGNDATA rgndata;
} clipList;

clipList.hdr.dwSize = sizeof(RGNDATAHEADER);
clipList.hdr.iType = RDH_RECTANGLES;
clipList.hdr.nCount = 1;
clipList.hdr.nRgnSize = 0;
memcpy(&clipList.hdr.rcBound, &clipRect, sizeof(RECT));
memcpy(&clipList.rgndata, &clipRect, sizeof(RECT));

clipper->SetClipList((LPRGNDATA)&clipList,0);

Attaching/Detaching a Clipper to a Surface

To activate a clipper, you must attach it to a surface with the IDirectDrawSurface4::SetClipper() function as shown in the following example:

backSurface->SetClipper(clipper);

Likewise, you must detach a clipper in order to regain the ability to blit to the entire surface as shown below:

backSurface->SetClipper(NULL);

Setting the clipper to NULL effectively disables clipping.

Definitions

blit - A short, pronounceable term that stands for block transfer. A block transfer is simply copying one logical block of memory to another, and is often performed asynchronously by video hardware.

surface - A linear area of display memory that exists either in video memory or system memory.

Author: Rodney Myers -- 5/18/99

http://www.mtsu.edu/~csjudy/directX/DirectDraw/clippers.html