L_GetBitmapRowCol

#include "l_bitmap.h"

L_LTKRN_API L_SSIZE_T L_GetBitmapRowCol(pBitmap, pBuffer, nRow, nCol, 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_INT nCol;	column offset within the row to retrieve
L_SIZE_T uBytes;	number of bytes to retrieve

Accepts a column offset to retrieve data from a bitmap and place it in a buffer. The buffer to which pBuffer points will be filled with uncompressed data.

Parameter	Description
pBitmap	Pointer to the bitmap handle referencing the bitmap to get the image data 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.
nRow	The number of the row to retrieve. The first row is 0, and the last row is 1 less than the bitmap height.
nCol	The column offset within the row to retrieve. The first column offset is 0, and the last column offset is 1 less than the bitmap width.
uBytes	The number of bytes to retrieve. Consider the bits per pixel, and avoid specifying a number that goes past the end of the row.
	Value	Meaning
	1-bit bitmap	Each byte represents 8 pixels.
	4-bit bitmap	Each byte represents 2 pixels.
	8-bit bitmap	Each byte represents 1 pixel.
	16-bit bitmap	Every 2 bytes represents one pixel.
	24-bit bitmap	Every three bytes represents one pixel.
	32-bit bitmap	Every four bytes represents one pixel.
	48-bit bitmap	Every six bytes represents one pixel.
	64-bit bitmap	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 copied.
< 1	An error occurred. Refer to Return Codes.

Comments

By using this low-level function to get any part of a row, you can write a procedure that accesses a single pixel or a rectangular area within the bitmap.

This function accepts an offset parameter (nCol) in pixels and a length (uBytes) in bytes. Therefore, you must consider the bits per pixel of the bitmap when specifying these parameters. The following table describes the rules:

Bits Per Pixel	Column Offset (in Pixels)	Bytes to Get
1	Must be a multiple of 8 (such as 0, 8, or 16).	Can be any number up to the end of the row. Consider that there are 8 pixels per byte.
4	Must be an even number (such as 0, 2, or 4).	Can be any number up to the end of the row. Consider that there are 2 pixels per byte.
8	Can be any column within the bitmap.	Can be any number up to the end of the row. Consider that there is 1 pixel per byte.
16	Can be any column within the bitmap.	Must be a multiple of 2 (such as 2, 4, or 6), because there are 2 bytes per pixel.
24	Can be any column within the bitmap.	Must be a multiple of 3 (such as 3, 6, or 9), because there are 3 bytes per pixel.
32	Can be any column within the bitmap.	Must be a multiple of 4 (such as 4, 8, or 12), because there are 4 bytes per pixel.

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.

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, Linux.

Example

The following example is designed to work with bitmaps that have a bottom-left or top-left view perspective: This example uses L_GetBitmapRowCol and L_PutBitmapRowCol to invert the colors of a rectangle in the upper left part of the displayed image.

#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName 
L_INT GetBitmapRowColExample(L_VOID) 
{ 
   L_INT nRet; 
   BITMAPHANDLE   LeadBitmap; /* Bitmap handle to hold the loaded image */ 
   L_INT          XOffset;    /* Column offset of the rectangle to process */ 
   L_INT          XSize;      /* Pixel width of the rectangle to process */ 
   L_INT          YOffset;    /* Row offset of the rectangle to process */ 
   L_INT          YSize;      /* Pixel height of the rectangle to process */ 
   L_UCHAR*       pBuf;       /* Buffer to hold the row */ 
   HGLOBAL        hBuf;       /* Handle to the buffer */ 
   L_INT          i, n;       /* Counters */ 
   /* 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; 
   /* This example does not work with rotated view perspectives */ 
   if ( (LeadBitmap.ViewPerspective != TOP_LEFT) || (LeadBitmap.ViewPerspective != BOTTOM_LEFT) ) 
   { 
      nRet = L_ChangeBitmapViewPerspective ( NULL, &LeadBitmap, sizeof(BITMAPHANDLE), TOP_LEFT ); 
      if(nRet != SUCCESS) 
         return nRet; 
   } 
   /* Specify a rectangle in the top left part of the displayed image */ 
   XOffset = BITMAPWIDTH(&LeadBitmap) / 8; 
   XSize = BITMAPWIDTH(&LeadBitmap) / 3; 
   YOffset = BITMAPHEIGHT(&LeadBitmap) / 8; 
   YSize = BITMAPHEIGHT(&LeadBitmap) / 3; 
   /* Adjust the YOffset if the view perspective is bottom left */ 
   if (LeadBitmap.ViewPerspective == BOTTOM_LEFT) 
   { 
      YOffset = LeadBitmap.Height - YOffset - YSize; 
   } 
   /* Allocate the buffer */ 
   hBuf = GlobalAlloc(GMEM_MOVEABLE, XSize * 3); 
   pBuf = (L_UCHAR*)GlobalLock( hBuf ); 
   /* Invert the colors of pixels in the rectangle */ 
   L_AccessBitmap(&LeadBitmap); 
   for(i=YOffset; i < (YOffset + YSize); i++) 
   { 
      nRet = (L_INT)L_GetBitmapRowCol(&LeadBitmap, pBuf, i, XOffset, XSize * 3); 
      if(nRet < 1) 
         return nRet; 
      for(n=0; n < (XSize * 3); n++) 
      pBuf[n] = pBuf[n] ^ 0xFF; 
      nRet =(L_INT) L_PutBitmapRowCol(&LeadBitmap, pBuf, i,  XOffset, XSize * 3); 
      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 */ 
   GlobalFree(hBuf); 
   return SUCCESS; 
}

Help Version 19.0.2017.10.27

Products | Support | Contact Us | Copyright Notices
© 1991-2017 LEAD Technologies, Inc. All Rights Reserved.

LEADTOOLS Raster Imaging C API Help

Introduction

Version History

Getting Started

LEADTOOLS Raster Imaging Features

Redistributables/Files To Be Included With Your Application

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