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

This function stores an arbitrary line of pixels in the DIB image bitmap of the image referenced by HIGEAR.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_DIB_line_set ( 
        HIGEAR hIGear, 
        AT_PIXPOS nX1, 
        AT_PIXPOS nY1, 
        AT_PIXPOS nX2, 
        AT_PIXPOS nY2, 
        const LPAT_PIXEL lpPixel, 
        AT_DIMENSION nNumPixels 
);

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of image to which to transfer pixels.
nX1 AT_PIXPOS X coordinate of the first endpoint of line to store.
nY1 AT_PIXPOS Y coordinate of the first endpoint.
nX2 AT_PIXPOS X coordinate of the second endpoint of line to store.
nY2 AT_PIXPOS Y coordinate of the second endpoint.
lpPixel const LPAT_PIXEL Far pointer to your data area containing the pixels to be stored.
nNumPixels AT_DIMENSION Number of pixels (not bytes) to be transferred.

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 cPixArray[400]; /* Receives the returned pixels         */
AT_PIXPOS nXleft, nYtop,  /* Coordinates of upper-left end of line*/
  nXright, nYbot; /* Coordinates of the lower-right end   */
AT_DIMENSION nFetched;     /* Holds the count of pixels retrieved  */
AT_ERRCOUNT  nErrcount;            /* Receives the returned error counts   */
/* Fetch a diagonal line, from Coordinates (0,0) to (100,100):                                                            */
nXleft  = 0;    nYtop = 0;                                      /* Diagonal line from upper left corner      */
nXright = 100;  nYbot = 100;
nErrcount = IG_DIB_line_get ( hIGear, nXleft, nYtop, nXright, nYbot, &cPixArray[0], 400,
&nFetched );
 ...
/* Now restore the line: */
nErrcount = IG_DIB_line_set ( hIGear, nXleft, nYtop, nXright, nYbot, &cPixArray[0],
nFetched );

Remarks:

The line does not have to be horizontal or vertical. (nX1,nY1) are the coordinates of one endpoint of the line and (nX2,nY2) are of the other.

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.

If the image you are modifying is 1-bit, you must convert the image from run-end encoded to a standard DIB before you can set pixel values. Please see the section Accessing Image Pixels for details.

1-bit and 4-bit pixels should be provided one to a byte, right justified (that is, in the least significant bits of the byte). 24 bit pixels should be 3 bytes per pixel, in Blue-Green-Red order.

To calculate the number of pixels that your line will consist of, use the following formula:
max((1+abs(x2-x1)), (1+abs(y2-y1)))