IG_IP_contrast

This function adjusts the brightness and contrast of the image.

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_contrast_adjust( HIGEAR hIGear, LPAT_RECT lpRect, AT_MODE nMethodMode, DOUBLE dblContrast, DOUBLE dblBrightness );

Arguments:

Name	Type	Description
hIGear	HIGEAR	HIGEAR handle of image.
lpRect	LPAT_RECT	Specifies a rectangle within the image to operate on. NULL means the entire image. See Remarks below.
nMethodMode	AT_MODE	Specifies whether to alter the pixels or the palette. See enumIGContrastModes.
dblContrast	DOUBLE	Specifies the contrast value. The useful range is from -(2^bpc) to (2^bpc), where bpc is the image bits per channel.
dblBrightness	DOUBLE	Specifies the brightness value. The useful range is from -(2^bpc)+1 to (2^bpc)-1, where bpc is the image bits per channel.

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++.

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) { nErrcount = IG_IP_contrast_adjust(hIGear, NULL, IG_CONTRAST_PIXEL, 2.0, -10.0); // ... // Destroy the image IG_image_delete(hIGear); }

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)
{
    nErrcount = IG_IP_contrast_adjust(hIGear, NULL, IG_CONTRAST_PIXEL, 2.0, -10.0);
    // ...
    // Destroy the image
    IG_image_delete(hIGear);
}

Remarks:

Brightness and contrast are linear controls that affect the intensity of the image pixels. These controls are similar to the Brightness and Contrast controls on a typical television set.

Contrast is a multiplier, and Brightness is an additive value. The contrast is applied about the middle value of the pixel intensity range. A Contrast of 2.0 will cause each pixel to become twice farther from the middle intensity value, while 0.5 makes each twice closer to it. A Brightness value of 20.0 will cause each pixel's intensity to be increased by 20, and a -20 will decrease or darken each by 20. Pixel values are clipped to the pixel intensity range supported by the image channel depths. Once clipped, the data is lost and cannot be regenerated. A Brightness of 0.0 and a Contrast of 1.0 will cause no change to the image. A -1.0 Contrast with a Brightness of 0.0 can be used to invert the intensity range.

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.

When IG_CONTRAST_PALETTE is used, the lpRect rectangle is ignored, since the whole image is affected when the palette is changed.

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 linear will adjusting the pixels adjust the display in the desired way. An example of a linear palette is the grayscale palette: R[i] = G[i] = B[i] = i.

IG_IP_contrast_adjust_ex is an extended version of this function that allows adjusting contrast on specific image channels.