ImageGear for C and C++ on Windows v21.0 - Updated
API Reference Guide / Core Component API Reference / Core Component Functions Reference / Image Processing Functions / IG_IP_area_info_get
In This Topic
    IG_IP_area_info_get
    In This Topic

    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.