Get Ready to Unleash the Power of UCanCode .NET

ExtSelectClipRgn

The ExtSelectClipRgn function combines the specified region with the current Clip Region using the specified mode. If you would like more details on how the different modes will affect the current Clip Region, refer to this guide: Guide to WIN32 Regions.

int ExtSelectClipRgn(
  HDC hdc,          // handle to DC
  HRGN hrgn,        // handle to region
  int fnMode        // region-selection mode
);

The dimensions that this function return are in device coordinates for the current DC. The return value will indicate the current region type that is stored in the Clip Region.

IntersectClipRect

The IntersectClipRect function creates a new Clip Region from the intersection of the current Clip Region and the specified rectangle. Unless one of the other clipping functions has been called to modify the initial Clip Region, this function will have not effect as the default Clip Region includes the entire DC.

int IntersectClipRect(
  HDC hdc,         // handle to DC
  int nLeftRect,   // x-coord of upper-left corner
  int nTopRect,    // y-coord of upper-left corner
  int nRightRect,  // x-coord of lower-right corner
  int nBottomRect  // y-coord of lower-right corner
);

ExcludeClipRect

The ExcludeClipRect function creates a new Clip Region that consists of the existing Clip Region minus the specified rectangle.

int ExcludeClipRect(
  HDC hdc,         // handle to DC
  int nLeftRect,   // x-coord of upper-left corner
  int nTopRect,    // y-coord of upper-left corner
  int nRightRect,  // x-coord of lower-right corner
  int nBottomRect  // y-coord of lower-right corner
);

OffsetClipRgn

The OffsetClipRgn function moves the Clip Region of a device context by the specified offsets.

int OffsetClipRgn(
  HDC hdc,       // handle to DC
  int nXOffset,  // offset along x-axis
  int nYOffset   // offset along y-axis
);

SelectClipPath

The SelectClipPath function selects the current path as a Clip Region for a device context, combining the new region with any existing Clip Region using the specified mode.

BOOL SelectClipPath(
  HDC hdc,    // handle to DC
  int iMode   // clipping mode
);

Meta Region Functions

At first glance the set of Meta Region functions may seem a little meager with only two. However, when a Meta Region is set, it will combine the intersection of the current Meta Region, with the current clip region. The Clip Region will then be reset to the entire DC. This in effect allows the Meta Region to use all of the Clip region functions in order to create itself. It is highly likely that this function could be implemented in terms of GetRandomRgn by simply passing in a 2 to the iNum parameter.

It is however, very important that SaveDC is used to save the state of the DC before a meta region is set into the DC. Because when a Meta Region is created, it is intersected with the current Meta Region. Once a Meta Region region is reduced from the default client rectangle, then the region cannot be returned back to its original state except by restoring a previously saved DC context.

GetMetaRgn

The GetMetaRgn function retrieves the current meta region for the specified device context.

int GetMetaRgn(
  HDC hdc,    // handle to DC
  HRGN hrgn   // handle to region
);

SetMetaRgn

The SetMetaRgn function intersects the current Clip Region for the specified device context with the current meta region and saves the combined region as the new meta region for the specified device context. The Clip Region is reset to a null region. The only way to reset the Meta Region to its original state is to return to a previously saved version of the DC with SaveDC.

int SetMetaRgn(
  HDC hdc   // handle to DC
);

Application of the DC Regions

The regions that are a part of the DC are used extensively. Quite often an application will use these regions and not be unaware of this fact. By understanding the regions that are used, and what these regions accomplish, a developer can possibly design their system around these features in order to create a more efficient program. This fact is especially true when an application or control is implemented that does not follow the normal design for WIN32 development.

BeginPaint

This is probably the most common use of the regions that are involved the DC. Internally BeginPaint makes a call to GetDCEx in order to create the DC that finally gets used. The current update region for the target window is used as the clipping region in GetDCEx. This final result is the System Region is equivalent to the Update Region of the window for the paint DC. When the application attempts to paint on the paint DC, only the regions that have been invalidated will be repainted.

At this point the application could call GetRandomRgn in order to get the region that needs to be repainted, and factor out all of the unnecessary painting increasing the efficiency of the paint routine. Even if the application sends the entire window to be repainted upon each paint message, the display ultimately experiences less flicker because of the automatic clipping that is experienced by the System Region. In order to see a demonstration of the flicker that would occur with out this feature, make a call to InvalidateRect before BeginPaint in your paint handler.

InvalidateRect(hWnd, NULL, TRUE);

This will have the effect of invalidating the entire target window, and eliminating any benefit that System Region provides.