ImageGear provides several functions that let you get and set the values of individual pixels, rows or columns of pixels, and rectangular groups of pixels. This family of functions is referred to as the "pixel access" functions.

All functions include the acronym "DIB" in their names. Every pixel access function is part of a "_get()/_set()" pair of functions. In other words, for each pixel access type, you can obtain the value(s) of a pixel or group of pixels, and set the value(s) of a pixel or group of pixels.

To obtain descriptions of each pixel access function and view additional sample code, refer to the Core Component API Function Reference.

This topic provides information about the following:

Setting Pixel Access Mode
Allocating Space for ImageGear Pixel Access
Getting and Setting Individual Pixels
Getting and Setting Linear Groups of Pixels
Getting and Setting a Rectangular Area of Pixels
Filling DIB Area

Setting Pixel Access Mode

Pixel access functions have two modes of operation:

Legacy (prior to ImageGear v14.5). The default mode is legacy, in which these functions behave the same way they did before v14.5. So if you have existing code written for ImageGear v14.4 or earlier that uses pixel access functions, you shouldn't need to update it.
New (ImageGear v14.5 and newer). New pixel access mode provides more access to the new storage system. It lets you work directly with higher bit depths, advanced color spaces, and alpha/extra channel data included with the main channel data.

If you are migrating from legacy mode to new mode, you must be aware of the following differences between these modes:

For RGB images, color channel order is RGB (in legacy mode, it is BGR)
DIBs may use bit depths that were not supported by the Legacy mode (i.e., 36-bit, 48-bit RGB)
Additional color spaces are supported (i.e., LAB, YUV)
Alpha and extra channel data is included on a per-pixel basis. For example, if you have a 24-bit RGB image with an 8-bit alpha channel, the pixel data will look like RGBA, RGBA, RGBA and so on, where R, G, B, and A are each one byte.

Pixel packing and raster padding are as follows:

Packing Mode	Legacy	New
IG_PIXEL_PACKED	1 bit pixels are packed 8 into a byte; 4 bit pixels are packed 2 into a byte; other pixels are not packed. Rasters are padded to DWORD boundary.	1 bit pixels are packed 8 into a byte; other pixels are not packed. In 32-bit edition of ImageGear, rasters are padded to DWORD boundary. In 64-bit edition of ImageGear, rasters are padded to QWORD boundary.
IG_PIXEL_UNPACKED	Pixels are not packed; each 1-bit pixel occupies a byte. Rasters are padded to BYTE boundary.	Pixels are not packed; each 1-bit pixel occupies a byte. In 32-bit edition of ImageGear, rasters are padded to DWORD boundary; In 64-bit edition of ImageGear, rasters are padded to QWORD boundary.

Packing Mode

Legacy

New

IG_PIXEL_PACKED

1 bit pixels are packed 8 into a byte; 4 bit pixels are packed 2 into a byte; other pixels are not packed. Rasters are padded to DWORD boundary.

1 bit pixels are packed 8 into a byte; other pixels are not packed.

In 32-bit edition of ImageGear, rasters are padded to DWORD boundary.
In 64-bit edition of ImageGear, rasters are padded to QWORD boundary.

IG_PIXEL_UNPACKED

Pixels are not packed; each 1-bit pixel occupies a byte. Rasters are padded to BYTE boundary.

Pixels are not packed; each 1-bit pixel occupies a byte.

In 32-bit edition of ImageGear, rasters are padded to DWORD boundary;
In 64-bit edition of ImageGear, rasters are padded to QWORD boundary.

Note that 1-bit pixels are the only pixels that are packed in the new mode - 8 pixels are stored in each byte. Pixels of any other channel depths are stored using 1, 2, or 4 bytes per channel. If a pixel has more than one channel and use 1 bit per channel, each of its channels will be stored in a separate byte. A channel value with depth of 2-8 bits will be stored in one byte, 9-16 bits in two bytes, and 17-32 bits in four bytes.

To use the new mode, set the DIB.PIX_ACCESS_USE_LEGACY_MODE global control parameter to IG_PIX_ACCESS_MODE_NEW, as shown in the example below.

	Copy Code
AT_MODE pixAccessMode = IG_PIX_ACCESS_MODE_NEW; IG_gctrl_item_set("DIB.PIX_ACCESS_USE_LEGACY_MODE", AM_TID_AT_MODE, &pixAccessMode, sizeof(pixAccessMode), NULL);

If pixel access mode is IG_PIX_ACCESS_MODE_LEGACY, and the image uses a pixel format not supported by the legacy mode, pixel access “…_get” functions convert image pixels into the closest available legacy supported format.

Allocating Space for ImageGear Pixel Access

A common thread for all pixel access _get() functions is that you must provide an array with enough space to accommodate the data that you will receive.

Use IG_DIB_raster_size_get() to get the size of the array for storing a complete raster of an image.
Use IG_DIB_pixel_array_size_get to get the size of the array for storing a specified number of pixels.
Use IG_DIB_pixel_array_size_get to get the size of the array for storing a specified number of pixels from a single row, column, or line.
Use IG_DIB_area_size_get to get the size of the array for storing a rectangular area of pixels.

Getting and Setting Individual Pixels

There are two pairs of ImageGear functions for getting and setting the value of an individual pixel.

IG_DIB_pix_get() and IG_DIB_pix_set() get and set a pixel value as a HIGPIXEL object handle.
IG_DIB_pixel_get() and IG_DIB_pixel_set() get and set a pixel value into / from a byte array. These two functions take into account the current Pixel Access Mode. If pixel access mode is IG_PIX_ACCESS_MODE_LEGACY, and the image uses a pixel format not supported by the legacy mode, the pixel is converted into the closest available legacy supported format. See "Setting Pixel Access Mode" above for more information.

All pixel access functions consider the coordinates 0,0 as the upper left-hand corner of the bitmap data.

Getting and Setting Linear Groups of Pixels

ImageGear lets you get and set the values of linear groups of pixels that run in a horizontal, vertical, or diagonal direction.

Name	Description
IG_DIB_column_get()	Gets the values of a variable-length (vertical) column of pixels. The IG_DIB_column_get() function requires that you set the nX parameter to the horizontal position of the column that you would like to get, and also the first and last row from which you would like to get the pixel values. For this, you set the values of nY1 and nY2. You also give it a pointer to and nLenBytes (size in bytes) of the buffer to which you will store the pixel values. This function will return the actual number of pixel values acquired: lpNumPixels. If the buffer size of nLenBytes is not large enough to accommodate the number of pixels specified by nY1 and nY2, the line of pixels will be truncated, and you will not receive all of the pixels that you specified.
IG_DIB_column_set()	Sets the values of a column of pixels. IG_DIB_column_set() does just the opposite as its _get() counterpart. It takes the pixel values in the buffer and transfers a specified number of them to a HIGEAR image at row nX, and columns nY1 through nY2. You also supply this function with the number of pixel values that you will be setting, where: max # of pixels to set = (nY2 - nY1) + 1
IG_DIB_line_get()	Gets the values of a variable-length line of pixels. Gives you access to the line of pixel values between any two sets of points in the image (i.e., a diagonal line, a horizontal line, or a vertical line). For this reason, it requires that you have set two x coordinates and two y coordinates. If you were to give equal values to either the x pair of coordinates or the y pair of coordinates, you would specify a line that was strictly horizontal or vertical, respectively. These get/set functions require that you give the size in bytes of the buffer and its address.
IG_DIB_line_set()	Sets the values of a line of pixels. Gives you access to the line of pixel values between any two sets of points in the image (i.e., a diagonal line, a horizontal line, or a vertical line). For this reason, it requires that you set two x coordinates and two y coordinates. If you were to give equal values to either the x pair of coordinates or the y pair of coordinates, you would specify a line that was strictly horizontal or vertical, respectively. These get/set functions require that you give the size in bytes of the buffer and its address.
IG_DIB_raster_get()	Gets the values of a full raster line of pixels. Works similarly to the IG_DIB_column_get() and IG_DIB_row_get() functions, except that it will get the values of a full (horizontal) raster line of pixels. This function is quite a bit easier to use than the above functions, however, because you do not need to supply the beginning and ending position of the line. Also, while you must allocate sufficient memory for the data, you do not need to tell ImageGear what number of bytes your buffer contains.
IG_DIB_raster_set()	Sets the values of a full raster line of pixels. Works similarly to the IG_DIB_column_set() and IG_DIB_row_set() functions, except that it will set the values of a full (horizontal) raster line of pixels. This function is quite a bit easier to use than the above functions, however, because you do not need to supply the beginning and ending position of the line. Also, while you must allocate sufficient memory for the data, you do not need to tell ImageGear what number of bytes your buffer contains.
IG_DIB_row_get()	Gets the values of a variable-length (horizontal) row of pixels. This function works exactly like IG_DIB_column_get(), except that it gets the values of a horizontal row of pixels.
IG_DIB_row_set()	Sets the values of a row of pixels. This function works exactly like IG_DIB_column_set(), except that it sets the values of a horizontal row of pixels.

All pixel access functions consider the coordinates 0,0 as the upper left-hand corner of the bitmap data.

Raster and row access API allow packing more than one pixel per byte; to pack more than one pixel per byte, set the nFormat argument to IG_PIXEL_PACKED. For more details, see "Setting Pixel Access Modes" and "Allocating Space for ImageGear Pixel Access Functions" above.

Getting and Setting a Rectangular Area of Pixels

Use IG_DIB_area_get() and IG_DIB_area_set() functions for getting and setting the values of a rectangular area of an image.

Use IG_DIB_area_size_get to get the size of the array for storing a rectangular area of pixels.

All pixel access functions consider the coordinates 0,0 as the upper left-hand corner of the bitmap data.

These functions take into account the current pixel access mode (new or legacy). See "Setting Pixel Access Modes" above for more details.

Filling DIB Area

The IG_DIB_flood_fill() function fills an area in the DIB that is surrounded by a border of the specified color.