ImageGear for C and C++ on Linux v19.10 - Updated
Access Image Pixels
User Guide > How to Work with... > Common Operations > Manipulating Image Data > Access Image Pixels

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

Pixel access functions have two modes of operation:

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

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. 

Getting and Setting Individual Pixels

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

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.