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

This function provides information about a rectangular area of the image.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_area_info_get(
   HIGEAR hIGear,
   const LPAT_RECT lpRect,
   HIGPIXEL lpPixel,
   AT_MODE nChannel,
   AT_MODE nInfo
);

Arguments:

Name Type Description
hIGear HIGEAR Handle of the image for which to obtain the information.
lpRect const LPAT_RECT Rectangle to get the information from (pass NULL for getting information on the whole image).
lpPixel HIGPIXEL Receives the calculated value. Depending on the "DIB.PIX_ACCESS_USE_LEGACY_MODE" global control parameter - either a HIGPIXEL object handle, or a pointer to an array of AT_PIXEL. See Remarks.
nChannel AT_MODE Specifies a channel or a channel range to get the info about. See enumIGColorChannels for possible values.
nInfo AT_MODE Specifies the kind of information to be obtained. See enumDIBAreaInfo for possible values.

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:

Pixel Access, Legacy Pixel Access

Example:

 
Copy Code
HIGEAR hIGear;            // HIGEAR handle of image
AT_ERRCOUNT nErrcount;    // Count of errs on stack upon ret from func
AT_INT channelCount;    // Count of channels in the image
AT_INT bitsPerChannel;    // Channel depth
HIGPIXEL hPixel;

// Load image file "picture.bmp" from working directory
nErrcount = IG_load_file("picture.bmp", &hIGear);
if(nErrcount == 0)
{
    // Set IG_PIX_ACCESS_MODE_NEW access mode
    AT_LMODE AccessMode = IG_PIX_ACCESS_MODE_NEW;
    IG_gctrl_item_set("DIB.PIX_ACCESS_USE_LEGACY_MODE", AM_TID_AT_LMODE, &AccessMode, sizeof(AT_LMODE), NULL);

    IG_image_channel_count_get(hIGear, &channelCount);
    IG_image_channel_depth_get(hIGear, 0, &bitsPerChannel);

    hPixel = IG_pixel_create(channelCount, bitsPerChannel);
    if(hPixel != NULL)
    {
        // Get average pixel value
        nErrcount = IG_IP_area_info_get(hIGear, NULL, hPixel, IG_COLOR_COMP_ALL, IG_DIB_AREA_INFO_AVE);
        // ...
        // Delete pixel
        IG_pixel_delete(hPixel);
    }
    // Destroy the image
    IG_image_delete(hIGear);
}

Remarks:

Behavior of this function depends on the "DIB.PIX_ACCESS_USE_LEGACY_MODE" global control parameter.

If "DIB.PIX_ACCESS_USE_LEGACY_MODE" is set to IG_PIX_ACCESS_MODE_NEW, the function expects that lpPixel is set to an HIGPIXEL object handle. The calculated value will be returned in this object. Use IG_pixel_create to create an HIGPIXEL object, specifying the correct number of channels and number of bits per channel. Use IG_pixel_delete to delete it when it is no longer in use.

If the global parameter is set to IG_PIX_ACCESS_MODE_LEGACY, the function expects that lpPixel is a pointer to an array of AT_PIXEL. Length of the array must correspond to the number of image channels. The area info will be scaled to the AT_PIXEL range (BYTE). For example, if the image has 16 bits per channel, and the area info corresponds to 32767, the return value will be (32767 / 256) = 128.

See Accessing Image Pixels section for more information on pixel access modes.

Default value of "DIB.PIX_ACCESS_USE_LEGACY_MODE" global control parameter is IG_PIX_ACCESS_MODE_LEGACY.