IG_DIB_area

This function obtains all the pixels contained within the rectangular portion of image hIGear specified by lpRect.

Declaration:

	Copy Code
AT_ERRCOUNT ACCUAPI IG_DIB_area_get ( HIGEAR hIGear, const LPAT_RECT lpRect, LPAT_PIXEL lpPixel, AT_MODE nPixelFormat );

Arguments:

Name	Type	Description
hIGear	HIGEAR	The hIGear handle of an image.
lpRect	const LPAT_RECT	Far pointer to an AT_RECT struct specifying the rectangular portion of the image bitmap to get.
lpPixel	LPAT_PIXEL	Far pointer to first in an array of bytes large enough to receive all pixels in the area.
nPixelFormat	AT_MODE	A constant such as IG_DIB_AREA_UNPACKED, specifying in what form you want the pixels stored in your array. The list of IG_DIB_AREA_ constants available is in file accucnst.h.

Return Value:

Returns the number of ImageGear errors that occurred during this function call. If there are no errors, the return value is IGE_SUCCESS.

Supported Raster Image Formats:

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

Example:

	Copy Code
HIGEAR hIGear; /* HIGEAR handle of image / AT_RECT rcBlock; / The rectangular block to get / AT_PIXEL cPixArray[400];/ Will receive returned pixels / AT_DIMENSION nWid, nHi; / Will receive width, height of image / UINT nBpp; / Bits per pixel / AT_ERRCOUNT nErrcount; / Will receive returned error counts / / Will fetch upper left 20 x 20 pixels, to cPixArray[]: / rcBlock.top = rcBlock.left = 0; rcBlock.bottom = rcBlock.right = 20; / 20x20 area, 400 pixels / nErrcount = IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp ); / if ( nErrcount == 0 ) /* If valid image, dimensions obtained' / { if ( (nBpp <= 8) && (nWid >= 20) && (nHi >= 20) ) {/ (Array is too small for 24-bit) */ nErrcount = IG_DIB_area_get ( hIGear, &rcBlock, &cPixelArray[0], IG_DIB_AREA_UNPACKED ); } }

Copy Code

HIGEAR         hIGear;       /* HIGEAR handle of image  */
AT_RECT        rcBlock;      /* The rectangular block to get  */
AT_PIXEL       cPixArray[400];/* Will receive returned pixels  */
AT_DIMENSION   nWid, nHi;     /* Will receive width, height of image     */
UINT           nBpp;          /* Bits per pixel  */
AT_ERRCOUNT   nErrcount;   /* Will receive returned error counts      */
/* Will fetch upper left 20 x 20 pixels, to cPixArray[]:   */
rcBlock.top = rcBlock.left = 0;
rcBlock.bottom = rcBlock.right = 20;  /* 20x20 area, 400 pixels  */
nErrcount = IG_image_dimensions_get ( hIGear, &nWid, &nHi, &nBpp );  */
if ( nErrcount == 0 )      /* If valid image, dimensions obtained'    */
        {
        if ( (nBpp <= 8) && (nWid >= 20) && (nHi >= 20) )
                {/* (Array is too small for 24-bit)                                     */
                nErrcount = IG_DIB_area_get ( hIGear, &rcBlock, 
                        &cPixelArray[0], IG_DIB_AREA_UNPACKED );
                }
        }

Remarks:

Use the lpPixel argument to tell ImageGear where to store the pixels.

ImageGear's pixel access functions consider the coordinates (0,0) to refer to the upper left-hand corner of the bitmap data. They do not follow the DIB's orientation, which considers (0,0) to refer to the lower left-hand corner of the bitmap.

Use nPixelFormat = IG_DIB_AREA_DIB if you want the data in standard uncompressed DIB format, and with each row returned to you padded to a multiple of 4 bytes length. 1-bit pixels are returned 8 to the byte, most significant bit first. 4-bit pixels are returned 2 to the byte, similarly left justified. 24-bit pixels are returned 3 bytes per pixel, ordered Blue-Green-Red.

Use nPixelFormat = IG_DIB_AREA_UNPACKED if you want the pixels returned 1 per byte (but still 3 bytes for a 24-bit pixel, ordered Blue-Green-Red). Each 1-bit or 4-bit pixel will be returned right justified in a single byte, padded with zeroes in the most significant bits of the byte.

In either case, be sure your area pointed to by lpPixel is large enough to receive all the pixel data including padding.