ImageGear for C and C++ on Windows v19.1 - Updated
IG_clipboard_cut
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Clipboard Functions > IG_clipboard_cut

This function "cuts away" a portion of an image.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_clipboard_cut (
        HIGEAR hIGear, 
        const LPAT_RECT lprcRegion, 
        const LPAT_PIXEL lpPixel
);

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of current image.
lprcRegion const LPAT_RECT A long pointer to a rectangular region of the image, which should be copied to the clipboard and removed from the image.
lpPixel const LPAT_PIXEL A long pointer to a pixel value you would like to be used to fill in the area out of which the region has been cut.

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:

All pixel formats supported by ImageGear for C and C++.

The copied pixels will be converted to 1-, 4-, 8-bit indexed or 24-bit RGB format for copying to the clipboard.

Sample:

Clipboard, Image Processing

Example:

 
Copy Code
HIGEAR        hIGear;     /* HIGEAR handle of image  */
AT_ERRCOUNT   nErrcount;  /* # of IG errors on the stack  */
AT_RECT       rcRegion;   /* Rectangular region to cut from image */
AT_PIXEL      pixel       /* Pixel value used when filling cut regions */
pixel = 0;
/* For a currently loaded 1-bit image where black = 0, set the cut area to black*/
nErrcount = IG_clipboard_cut ( hIGear, &rcRegion, &pixel );

Remarks:

The cut portion is copied to the clipboard with its original pixel values, while in the displayed image, that rectangle is replaced by a pixel value as specified by lpPixel. The color used is usually black or white. You can restore the image to its original composition by calling IG_clipboard_paste_merge_ex(). You then set the x and y positions of the upper left-hand corner arguments to PIXPOS left and PIXPOS right of the image rectangle defined by lprcRegion. If you save the image after a call to this function, it will be saved with the cut.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can process a rectangular sub-region of an image. However, before ImageGear performs the operation specified by this function, it will check to see if an internal flag has been set to TRUE, indicating that a mask HIGEAR should be used with the image. If the flag is set to TRUE (i.e. an NRA mask is active), and a valid pointer to a mask image has been assigned, ImageGear will override the settings passed to the AT_RECT structure and use the non-rectangular ROIdefined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.

For 24-bit images, lpPixel must point to 3 bytes where the first byte is red, the second - green and the third - blue. For all other bit depths, lpPixel must point to a single byte.