L_GetPixelColor

#include "l_bitmap.h"

L_LTKRN_API L_COLORREF L_GetPixelColor(pBitmap, nRow, nCol)

Returns the color of the specified pixel.

Returns

This function returns a COLORREF value which may represent an index into a bitmap's palette, a grayscale value (Document and Medical Imaging toolkits), or red, green, and blue color values.

If an error occurs, this function returns 0x80000000.

Comments

This function does not support signed data images. It returns the error code ERROR_SIGNED_DATA_NOT_SUPPORTED if a signed data image is passed to this function.

The standard Windows values for COLORREF represent either red, green, and blue color values, or an index into the bitmap's palette. A COLORREF value with the format 0x00BBGGRR represents the blue, green, and red color values for the specified pixel, where 0xBB is the blue value, 0xGG is the green value and 0xRR is the red value. If 0x01000000 is set in the COLORREF value (0x010000ZZ), the lower 8 bits (0xZZ) represent an index into the bitmap's palette which holds the color value. These COLORREF values can be used with any Windows function and macro that takes a COLORREF parameter. please note that just because a bitmap has a palette, that does not mean the returned COLORREF value is automatically an index.

In the Document and Medical Imaging toolkits, the COLORREF value may represent a 16 bit grayscale value if pBitmap is a 12 or 16-bit grayscale bitmap. So that the value is not confused with an RGB value, the COLORREF_GRAY16 mask (0x04000000) is set. In this case (0x0400YYYY), the lower 16 bits (0xYYYY) of the COLORREF value represent the 16-bit grayscale value. This is not a standard Windows value. Therefore, LEADTOOLS functions will recognize a COLORREF having this format, but Windows functions will not. To use a COLORREF value of this type in a non-LEADTOOLS function, you must do the following:

COLORREF color;

color = L_GetPixelColor(pBitmap, x, y);
if(color & COLORREF_GRAY16)
{  // nonstandard colorref value, convert it to a windows COLORREF
   // get an 8 bit gray value corresponding to the 16 bit gray value
   L_UCHAR gray = (color & 0xFFFF) >> 8;
   // use the standard windows RGB macro to get a windows COLORREF
   color = RGB(gray, gray, gray);
}

If the pBitmap is a 32-bit grayscale bitmap, this function returns 0x80000000.

To get pixel data for a 32-bit grayscale bitmap, you can call L_GetPixelData, L_GetBitmapRow, or L_GetBitmapRowCol functions.

You can use the L_PutPixelColor function to assign the returned value to another pixel.

This function uses bitmap coordinates to specify the pixel. Therefore, you must account for the view perspective of the bitmap. For more information, refer to Accounting for View Perspective.

If you specify a pixel that is outside the bitmap or outside the region (if the bitmap has one), this function returns an error.

Required DLLs and Libraries

Platforms

Windows 2000 / XP/Vista, Windows CE.

See Also

Example

/* This example uses L_GetPixelColor and L_PutPixelColor to invert 
the colors of the pixels in a line in the upper left part of the displayed image. */
 L_INT GetPixelColorExample(L_TCHAR*       szFilename,
                                          pBITMAPHANDLE  pBitmap)
{
   L_INT    XOffset;    /* Column offset of the line to process */
   L_INT    XSize;      /* Pixel width of the line to process */
   L_INT    YOffset;    /* Row offset of the line to process */
   L_INT    oldXOffset; /* Column offset of the line to process */
   L_INT    oldYOffset; /* Column offset of the line to process */
   COLORREF PixelColor; /* Current pixel color */
   L_INT    i;          /* Counter */
   L_INT    nRet;

   /* Load the bitmap, at its own bits per pixel */
   if(pBitmap->Flags.Allocated)
      L_FreeBitmap(pBitmap);
   nRet = L_LoadBitmap (szFilename, pBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL);
   if(nRet != SUCCESS)
      return nRet;

   /* Specify a line of pixels */
   XOffset  = BITMAPWIDTH(pBitmap) / 8;
   XSize    = BITMAPWIDTH(pBitmap) / 3;
   YOffset  = BITMAPHEIGHT(pBitmap) / 8;
   /* Invert the colors of pixels in the line */
   for(i=0; i < XSize; i++)
   {
      oldXOffset = XOffset;
      oldYOffset = YOffset;
      /* Adjust the XOffset and YOffset  in case the view perspective is not TOP_LEFT */
      nRet = L_PointToBitmap ( pBitmap, TOP_LEFT, &XOffset, &YOffset );
      if(nRet != SUCCESS)
         return nRet;
      PixelColor = L_GetPixelColor(pBitmap, YOffset, XOffset);
      PixelColor = PixelColor ^ 0x00FFFFFF;
      nRet = L_PutPixelColor(pBitmap, YOffset, XOffset, PixelColor);
      if(nRet != SUCCESS)
         return nRet;
      XOffset = oldXOffset; /* Restore XOffset */
      YOffset = oldYOffset; /* Restore YOffset */
      XOffset++;
   }
   return SUCCESS;
}