L_GetBitmapRow

#include "l_bitmap.h"

L_LTKRN_API L_SSIZE_T L_GetBitmapRow(pBitmap, pBuffer, nRow, uBytes)

pBITMAPHANDLE pBitmap;	/* pointer to the bitmap handle */
L_UCHAR* pBuffer;	/* pointer to the target buffer */
L_INT nRow;	/* number of the row to retrieve */
L_SIZE_T uBytes;	/* number of bytes in the row to retrieve */

Retrieves a row from a specified bitmap.The buffer to which pBuffer points should contain uncompressed data whether pBitmap is compressed or not.

Parameter	Description
pBitmap	Pointer to the bitmap handle referencing the bitmap to get the row from.
pBuffer	Pointer to the buffer to hold the image data that this function gets. You must allocate the buffer before calling this function, and the buffer must be large enough to hold the image data. NOTE: The data in the buffer will be padded to pBitmap->BytesPerLine.
nRow	The number of the row to retrieve. The first row is 0, and the last row is 1 less than the bitmap height.
uBytes	The number of bytes in the row to retrieve. To get a full row, use the value in the BytesPerLine field in the bitmap handle.
	When getting less than full row, you must consider the bits per pixel. For a 1-bit bitmap, each byte represents 8 pixels. For a 4-bit bitmap, each byte represents 2 pixels. For an 8-bit bitmap, each byte represents 1 pixel. For a 16-bit bitmap, every 2 bytes represents one pixel. For 24-bit images, every three bytes represents one pixel. For a 32-bit bitmap, every four bytes represents one pixel. For 48-bit images, every six bytes represents one pixel. For 64-bit images, every eight bytes represents one pixel.
	You can use the bitmap handle's BitsPerPixel field with integer math to calculate the number of bytes needed for a particular number of pixels. For example:
	NumberOfBytes = (Bitmap.BitsPerPixel * NumberOfPixels) / 8;
	if ((Bitmap.BitsPerPixel * NumberOfPixels) % 8)
	++NumberOfBytes; /* Round up if necessary for a 1- or 4-bit image */

Returns

>=1	The number of bytes gotten.
< 1	An error occurred. Refer to Return Codes.

Comments

This function copies image data from the bitmap to a buffer that you specify. The data is copied exactly as it is stored in the image. The bitmap memory must be locked when you use this function. Normally, you can call L_AccessBitmap to lock the memory before starting an operation that uses this function, then call L_ReleaseBitmap when the operation is finished.

Use the BytesPerLine field in the bitmap handle to determine the byte count of each line. Color order is determined by the Order field in the bitmap handle. This value can be ORDER_RGB, ORDER_BGR, ORDER_GRAY or ORDER_ROMM. ORDER_GRAY is only valid for 12, 16 and 32-bit grayscale images. Support for 12, 16 and 32-bit grayscale images is only available in the Document and Medical Imaging toolkits.

Required DLLs and Libraries

LTKRN

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64, Mobile.

See Also

Functions:	L_AccessBitmap, L_ReleaseBitmap, L_ClearBitmap, L_PutBitmapRow, L_GetBitmapRowCol, L_PutBitmapRowCol, L_GetPixelColor, L_PutPixelColor
Topics:	Raster Image Functions: Getting and Setting Pixel Values

Example

For complete sample code, refer to the GETROW example. This example gets each row from a bitmap, inverts the color values, and puts the row back into the bitmap.

 L_INT GetBitmapRowExample(L_VOID)
{
   L_INT nRet;
   BITMAPHANDLE   LeadBitmap;   /* Bitmap handle to hold the loaded image */
   L_UCHAR*       pBuf;         /* Buffer to hold the row */
   HGLOBAL        hBuf;         /* Handle to the buffer */
   L_INT          nRow;         /* Row counter */
   L_UINT         uByte;        /* Byte counter */

   /* Load the bitmap, at 24 bits per pixel */
   nRet = L_LoadBitmap (MAKE_IMAGE_PATH(TEXT("ImageProcessingDemo\\Image3.cmp")), &LeadBitmap, sizeof(BITMAPHANDLE), 24, ORDER_BGR, NULL, NULL);
   if(nRet != SUCCESS)
      return nRet;
   /* Allocate and lock the buffer */
   hBuf = GlobalAlloc(GMEM_MOVEABLE,LeadBitmap.BytesPerLine);
   pBuf = (L_UCHAR *)GlobalLock( hBuf );
   /* Process each row in the bitmap */
   L_AccessBitmap(&LeadBitmap);
   for(nRow = 0; nRow < LeadBitmap.Height; nRow++)
   {
      nRet =(L_INT) L_GetBitmapRow(&LeadBitmap, pBuf, nRow, LeadBitmap.BytesPerLine);
      if(nRet < 1)
         return nRet;
      for(uByte = 0; uByte < LeadBitmap.BytesPerLine; uByte++)
         pBuf[uByte] ^= 0xFF;
      nRet = (L_INT )L_PutBitmapRow(&LeadBitmap, pBuf, nRow, LeadBitmap.BytesPerLine);
      if(nRet <1)
         return nRet;
   }
   L_ReleaseBitmap(&LeadBitmap);

   nRet = L_SaveBitmap(MAKE_IMAGE_PATH(TEXT("Result.BMP")), &LeadBitmap, FILE_BMP, 24, 0, NULL);
   if(nRet != SUCCESS)
      return nRet;
   L_FreeBitmap(&LeadBitmap);

   /* Free memory that we no longer need */
   GlobalUnlock(hBuf);
   GlobalFree(hBuf);
   return SUCCESS;
}