ImageGear for C and C++ on Windows v19.1 - Updated
IG_DIB_raster_get
API Reference Guide > Core Component API Reference > Core Component Functions Reference > DIB Functions > IG_DIB_raster_get

This function obtains an entire horizontal raster line of pixels from the DIB image bitmap.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_DIB_raster_get (
        HIGEAR hIGear, 
        AT_PIXPOS nYpos, 
        LPAT_PIXEL lpPixel, 
        AT_MODE nFormat 
); 

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of image.
nYpos AT_PIXPOS Raster line number (0 is top line).
lpPixel LPAT_PIXEL Far pointer to first byte of area to receive the raster row of pixel values.
nFormat AT_MODE A variable of type AT_MODE (see accucnst.h) that tells whether the data being read in packed, unpacked, or RLE-compressed.

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

Sample:

Pixel Access

Example:

 
Copy Code
HIGEAR            hIGear;                        /* HIGEAR handle of image                                       */
AT_PIXEL                 cPixelValue[64];                       /* Needed to hold 500 1-bit pixels                                      */
AT_PIXPOS                nRaster;                       /* Index for the loop below                                     */
AT_ERRCOUNT              nErrcount;                     /* Hold the returned error count                                        */
AT_MODE         nFormat;
/* Obtain the top raster of a 1-bit image that's 500 pixels wide:               */
/* The pixels occupy 500/8 = 62.5 bytes.                                                */
nErrcount = IG_DIB_raster_get ( hIGear, 0, &cPixelValue[0], IG_PIXEL_PACKED);
/* Make the next 9 rows identical to the top row: */
for ( nRaster = 1; nRaster < 10; nRaster++ )
        nErrcount = IG_DIB_raster_set ( hIGear, nRaster, &cPixelValue[0], IG_PIXEL_PACKED );

Remarks:

This function does not pad the IpPixel array of bytes with zeros. To prevent unintended artifacts and unexpected results, it is highly recommended that the IpPixel array be initialized with zeros before calling this function.

You may first make a call to IG_DIB_raster_size_get() in order to determine the size of buffer that you will need to hold the raster data. The format in which the data is returned, nFormat, tells ImageGear whether the data is packed, unpacked, or RLE-compressed. The values that nFormat may be set to are: IG_PIXEL_PACKED, IG_PIXEL_UNPACKED, and IG_PIXEL_RLE. IG_PIXEL_PACKED gives the storage format of a standard uncompressed DIB, which includes padding to a multiple of 4 bytes length. (If 1-bit or 4-bit, the pixels are packed 8 or 2 to a byte respectively, stored most-significant-bit-first.) 24-bit pixels are returned 3 bytes each, ordered Blue-Green-Red, with the row padded to a multiple of 4 bytes length.

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.