ImageGear for C and C++ on Linux v18.8 - Updated
IG_IP_NR_ROI_mask_associate
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Image Processing Functions > IG_IP_NR_ROI_mask_associate

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.

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