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

Declaration:

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

Arguments:

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:

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.

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.