ImageGear for C and C++ on Windows v19.4 - Updated
IG_IP_contrast_invert
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Image Processing Functions > IG_IP_contrast_invert

This function inverts every color to its complement within the rectangular portion of the image selected by lpRect.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_contrast_invert(
   HIGEAR hIGear,
   LPAT_RECT lpRect,
   AT_MODE nMethodMode
);

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of image of which to invert contrast.
lpRect LPAT_RECT Specifies a rectangle within the image on which to operate. NULL means the entire image. See remarks below.
nMethodMode AT_MODE Specifies whether to alter the pixels or the palette. See enumIGContrastModes.

Return Value:

Returns 0 if successful. Otherwise, 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++.

Sample:

Image Processing, Medical, Timing

Example:

 
Copy Code
HIGEAR hIGear;            // HIGEAR handle of the image
AT_ERRCOUNT nErrcount;    // Count of errs on stack upon ret from func

// Load image file "picture.bmp" from working directory
nErrcount = IG_load_file("picture.bmp", &hIGear);
if(nErrcount == 0)
{
    // Invert the image
    nErrcount = IG_IP_contrast_invert(hIGear, NULL, IG_CONTRAST_PIXEL);
    // ...
    // Destroy the image
    IG_image_delete(hIGear);
}

Remarks:

For black-and-white images, black will become white, and white will become black. For grayscale and color images, every red, green, and blue color intensity value will be complemented: 0 will become 255 (and vice versa), 1 will become 254, and so on. Therefore, in a grayscale image, the darkest grays will become the lightest grays, and vice versa; and in a color image, colors near green will complement to colors near magenta (the complement of green), and so on.

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 NRA 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 nMethodMode = IG_CONTRAST_PIXEL, the inversion is accomplished by inverting all bits of all pixels within lpRect: bits that are 1 become 0, and bits that are 0 become 1. If nMethodMode = IG_CONTRAST_PALETTE, the inversion is accomplished by inverting the bits in the image's palette (the pixels are left unchanged).

Specifying IG_CONTRAST_PALETTE inverts the entire image, ignoring any rectangle specified.

Although the function allows using IG_CONTRAST_PIXEL for indexed images, in most cases such operation will not invert the image, but rather will change image colors in a random looking way, depending on image palette. Only if the palette is symmetric (R[i] = ^R[^i], G[i] = ^G[^i], G[i] = ^G[^i]) will inverting the pixels actually result in an inverted display. An example of a symmetric palette is the grayscale palette: R[i] = G[i] = B[i] = i.

If the image is not paletted, nMethodMode is ignored.