View source for GpiCombineRegion

This function combines two regions.

==Syntax==
 GpiCombineRegion(hps, hrgnDest, hrgnSrc1, hrgnSrc2, lMode)

==Parameters==
; hps ([[HPS]]) - input
: Presentation-space handle.
: The regions must be owned by the device identified by the currently associated device context.

; hrgnDest ([[HRGN]]) - input
: Handle of destination.

; hrgnSrc1 ([[HRGN]]) - input
: Handle of first source region.

; hrgnSrc2 ([[HRGN]]) - input
: Handle of second source region.

; lMode ([[LONG]]) - input
: Method of combination.
:; CRGN_OR
:: Union of hrgnSrc1 and hrgnSrc2
:; CRGN_COPY
:: hrgnSrc1 only (hrgnSrc2 ignored)
:; CRGN_XOR
:: Symmetric difference of hrgnSrc1 and hrgnSrc2
:; CRGN_AND
:: Intersection of hrgnSrc1 and hrgnSrc2
:; CRGN_DIFF
:: hrgnSrc1 and not (hrgnSrc2).

==Return Value==
; lComplexity ([[LONG]]) - returns
: Complexity of resulting region and error indicators.
:; RGN_NULL
:: Null region
:; RGN_RECT
:: Rectangular region
:; RGN_COMPLEX
:: Complex region
:; RGN_ERROR
:: Error.

==Remarks==
Source and destination regions must all be of the same device class. The destination region can be one of the source regions.
An error is raised if any of the specified regions are currently selected as the clip region (by [[GpiSetClipRegion]]).

==Errors==
Possible returns from WinGetLastError:
; PMERR_INV_HPS (0x207F)
: An invalid presentation-space handle was specified.
; PMERR_PS_BUSY (0x20F4)
: An attempt was made to access the presentation space from more than one thread simultaneously.
; PMERR_INV_HRGN (0x2080)
: An invalid region handle was specified.
; PMERR_REGION_IS_CLIP_REGION (0x20F8)
: An attempt was made to perform a region operation on a region that is selected as a clip region.
; PMERR_INV_REGION_MIX_MODE (0x20BF)
: An invalid mode parameter was specified with GpiCombineRegion.
; PMERR_HRGN_BUSY (0x2034)
: An internal region busy error was detected. The region was locked by one thread during an attempt to access it from another thread.

==Example Code==
<PRE>
#define INCL_GPIREGIONS /* Or use INCL_GPI, INCL_PM, */
#include &lt;os2.h&gt;

HPS     hps;       /* Presentation-space handle. */
HRGN    hrgnDest;  /* Handle of destination. */
HRGN    hrgnSrc1;  /* Handle of first source region. */
HRGN    hrgnSrc2;  /* Handle of second source region. */
LONG    lMode;     /* Method of combination. */
LONG    lComplexity; /* Complexity of resulting region and error indicators. */

lComplexity = GpiCombineRegion(hps, hrgnDest, hrgnSrc1, hrgnSrc2, lMode);
</PRE>

This example uses the GpiCombineRegion function to create a complex region consisting of everything in two rectangles except where they overlap.

<pre>
#define INCL_GPIREGIONS /* Region functions */
#include &lt;os2.h&gt;

HPS hps; /* presentation space handle */
HRGN hrgn1, hrgn2, hrgn3;
RECTL rclRect1 = { 0, 0, 100, 100 };
RECTL rclRect2 = { 50, 50, 200, 200 };

/* create first region */
hrgn1 = GpiCreateRegion(hps, 1L, &rclRect1);
/* create second region */
hrgn2 = GpiCreateRegion(hps, 1L, &rclRect2);
/* create empty region */
hrgn3 = GpiCreateRegion(hps, 0L, NULL);

/* Combine first and second regions, replacing the empty region. */
GpiCombineRegion(hps, hrgn3, hrgn1, hrgn2, CRGN_XOR);
</pre>

==Related Functions==
* [[GpiCreateRegion]]
* [[GpiDestroyRegion]]
* [[GpiEqualRegion]]
* [[GpiOffsetRegion]]
* [[GpiPaintRegion]]
* [[GpiPtInRegion]]
* [[GpiQueryRegionBox]]
* [[GpiQueryRegionRects]]
* [[GpiRectInRegion]]
* [[GpiSetRegion]]

[[Category:Gpi]]