IG_IP_NR_ROI_mask

This function will associate a mask HIGEAR, as specified by the AT_NR_ROI_MASK structure, with the image referenced by hIGear.

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_NR_ROI_mask_associate( HIGEAR hIGear, LPAT_NR_ROI_MASK lpMask, BOOL bState );

Arguments:

Name	Type	Description
hIGear	HIGEAR	HIGEAR handle of the image to associate with a non-rectangular ROI mask.
lpMask	LPAT_NR_ROI_MASK	Pass ImageGear a long pointer to a structure of type AT_NR_ROI_MASK that gives the HIGEAR handle of the mask HIGEAR.
bState	BOOL	Set to TRUE if you want to make the mask "active", meaning that affected IP or clipboard operations will operate on the non-rectangular region only; set to FALSE if you want affected IP or clipboard operations to apply the image rectangle specified by the AT_RECT argument.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Supported Raster Image Formats:

This function does not process image pixels.

Example:

	Copy Code
AT_ERRCOUNT nErrcount; HIGEAR hIGear; AT_NR_ROI_MASK lpMask; BOOL bState; nErrcount = IG_IP_NR_ROI_mask_associate(hIGear, &lpMask, TRUE);

Remarks:

The bState argument determines whether or not the ROI defined by AT_NR_ROI_MASK should be made active. If you set bState to TRUE, ImageGear will override the AT_RECT argument passed to certain Image Processing and Clipboard API functions in favor of using the non-rectangular ROI. For example, the function IG_IP_contrast_adjust() takes an AT_RECT as an argument, so that you can adjust the contrast in a rectangular sub-region of an image, or adjust the contrast of the whole image (if you set the AT_RECT parameter to NULL). If you set bState to TRUE, when you next call IG_IP_contrast_adjust(), its AT_RECT argument will be ignored, or "overridden", and ImageGear will instead use the ROI described by the mask HIGEAR.

If you provide an invalid mask HIGEAR, you will receive the error IGE_INVALID_MASK_ASSOCIATED.

No change will take place in the image until you perform an Image Processing or Clipboard operation. When using image processing functions the changes made are permanent if you save the image. For this reason, you may want to keep a copy of the original image so that the user can "undo" an operation.

The setting for bState, which ImageGear stores with the image can also be set using IG_IP_NR_ROI_control_set() with the constant IG_CONTROL_NR_ROI_CONDITION.
To reset the reference point in HIGEAR, call IG_IP_NR_ROI_control_set() with the constant IG_CONTROL_NR_ROI_REFERENCE_POINT.
Call IG_IP_NR_ROI_mask_unassociate() to clear the mask HIGEAR from its association with HIGEAR.

To create a non-rectangular region of interest call IG_IP_NR_ROI_to_HIGEAR_mask() function.