ImageGear for C and C++ on Linux - Updated
IG_IP_merge
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Image Processing Functions > IG_IP_merge

This function is used to "place" or merge one image into another.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_merge (
        HIGEAR hImage1, 
        HIGEAR hImage2, 
        LPAT_RECT lpImageRect2, 
        AT_PIXPOS nDstX, 
        AT_PIXPOS nDstY, 
        AT_MODE nPix_op 
);

Arguments:

Name Type Description
hImage1 HIGEAR HIGEAR handle of image.
hImage2 HIGEAR HIGEAR image to be merged into hImage1; must have same bit depth as hImage1.
lpImageRect2 LPAT_RECT Far pointer to an AT_RECT structure specifying the rectangular portion of hImage2 to merge into hImage1. upon. Set to NULL if you want to merge the entire image of hImage2. Before ImageGear performs this operation, it will check to see if an internal flag has been set to TRUE to make a mask active for this HIGEAR image. If a mask is active, and a valid pointer to a mask can be found, ImageGear will override the settings passed to this structure in favor of the non - rectangular ROI defined by the mask.
nDstX AT_PIXPOS The x coordinate within hImage1 at which to place the upper - left corner of hImage2.
nDstY AT_PIXPOS The y coordinate within hImage1 at which to place the upper-left corner of hImage2.
nPix_op AT_MODE A variable of constant type AT_MODE that specifies what type of arithmetic operation (merge method) to perform on all pixels of hImage1 that have been intersected with pixels from hImage2. Examples are IG_ARITH_ADD, which adds the pixel values of both images, and IG_ARITH_SUB, which subtracts the pixel values of hImage2 from the corresponding pixel values of hImage1. For the full list of available constants, see accucnst.h or see the description for IG_clipboard_paste_op_set() which also uses these constants for full list.

Return Value:

Returns the number of ImageGear errors that occurred during this function call.

Supported Raster Image Formats:

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

Example:

 
Copy Code
HIGEAR hIGear1,  /* HIGEAR handle of destination image   */
                hIGear2;  /* HIGEAR handle of image to be merged in */
AT_ERRCOUNT nErrcount; /* # of ImageGear errors on stack */
nErrcount = IG_IP_merge ( hIGear1, hIGear2, NULL, 0, 0, IG_ARITH_OVER );

Remarks:

The images do not have to be the same size but do have to be the same bit depth. hImage2 is drawn into hImage1. The top left corner of hImage2 will be placed at nDstX, nDstY of hImage1. Any over-hanging pixels of hImage2 will be clipped automatically. The nPix_op, which is defined in accucnst.h, determines how the pixels are combined.

This function, like other ImageGear Image Processing and Clipboard API calls, takes an AT_RECT structure as an argument, so that you can merge a rectangular sub-region of HIGEAR2 into HIGEAR1. 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, 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 ROI defined by the mask HIGEAR. To create a non-rectangular region of interest, call IG_IP_NR_ROI_to_HIGEAR_mask().

if lpImageRect2 is not NULL, or hIGear2 has a mask attached to it, and you want to place the top left corner of lpImageRect2 or the mask at nDstX, nDstY of hImage1, subtract the coordinates of the left top corner of lpImageRect2 or mask from the destination coordinates.
Please see the descriptions of IG_IP_NR_ROI_mask_associate() and IG_IP_NR_ROI_to_HIGEAR_mask() functions for more details.