ImageGear for C and C++ on Linux v18.10 - Updated
IG_runs_row_get
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Run-End Functions > IG_runs_row_get

This function returns a pointer to the run-end line specified by the yPos parameter.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_runs_row_get(
        HIGEAR hIGear, 
        AT_PIXPOS yPos,
        AT_RUN* wRunCount, 
        LPAT_RUN* lpRunEnd
); 

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of the image from which to get the run ends information.
yPos AT_PIXPOS Y-Offset into the image.
wRunCount AT_RUN* The number of runs in the lpRunEnd buffer.
lpRunEnd LPAT_RUN* Returns a pointer to the run-end line specified by yPos.

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:

Indexed RGB - 1 bpp;
Grayscale – 1bpp.

Example:

 
Copy Code
AT_ERRCOUNT      nErrcount;
HIGEAR  hIGear;
AT_PIXPOS       y;
WORD    wRunCount;
LPWORD  lpRunEnd, lpRunBuffer;
AT_DIMENSION    nWidth, nHeight;
IG_image_dimensions_get(hIGear, &nWidth, &nHeight, NULL);
/* calculate the maximum size of a raster line */
lpRunBuffer = (LPWORD)malloc((nWidth + 3) * sizeof(WORD));
/* invert the image */
for (y = 0; y < nHeight; y++)
{
        IG_runs_row_get(hIGear, y, &wRunCount, &lpRunEnd);
        if (lpRunEnd[0] != 0)
        {
                lpRunBuffer[0] = 0;
                for (wRunCount = 0; lpRunEnd[wRunCount] != 
                        nWidth; wRunCount++)
                        lpRunBuffer[wRunCount + 1] = lpRunEnd[wRunCount];
                wRunCount++;
                lpRunBuffer[wRunCount++] = (WORD)nWidth;
                lpRunBuffer[wRunCount++] = (WORD)nWidth;
                lpRunBuffer[wRunCount++] = (WORD)nWidth;
        }
        else
        {
                memcpy(lpRunBuffer, lpRunEnd + 1, (wRunCount - 1) * sizeof(WORD));
                lpRunBuffer[wRunCount - 1] = nWidth;
        }
        IG_runs_row_set(hIGear, y, wRunCount, lpRunBuffer);
}
InvalidateRect(hWnd, NULL, FALSE);
free(lpRunBuffer);

Remarks:

Run-end encoding is used on 1-bit images only. The wRunCount argument returns the number of runs to which lpRunEnd points. The read-only data in the pointer returned should not be changed because it may corrupt the image.

To safely change the data, use IG_runs_row_set(). Developers should be cautious when using the IG_runs_row_set() function because it is possible to corrupt the image by supplying invalid run-end data.

This function will set an error, if the image specified by hIGear is not in run-ends format or if the yPos parameter is greater than the height of the image.

The format of the run-end encoded data is as follows: Each line in the image starts with a value of type AT_RUN which stores the number of AT_RUN values used to hold the line. This value is equal to the number of runs in the line plus one (for the size value). The rest of the line consists of run ends of type AT_RUN. A run end specifies the first pixel position beyond the run of color. The run ends alternate between white and black, and start with white. The line ends with at least three run ends containing a value equal to the image's width. A 2500 pixel source line with black pixels in positions 0, 7, 23, and 30, would be encoded as runs: 10, 0, 1, 7, 8, 23, 31, 2500, 2500, 2500 (with 10 being the number of AT_RUN values used to store the encoded line.)

This function returns a pointer to the second AT_RUN value of the line in the lpRunEnd parameter, and returns the number of runs in wRunCount. The IG_runs_row_set() function copies the data in the lpRunEnd parameter to the second AT_RUN value of the line. The first AT_RUN value is set to the wRunCount parameter.