In This Topic ▼

L_GetBitmapYUVData

Summary

Converts the bitmap's grayscale or BGR data to YUV and stores it in an output buffer.

Syntax

#include "l_bitmap.h"

L_LTKRN_API L_INT L_GetBitmapYUVData(pBitmap, pYuvData, puYuvDataSize, yuvFormat, uFlags)

Parameters

pBITMAPHANDLE pBitmap

Pointer to the bitmap handle that references the bitmap whose data will be converted. The bitmap must be allocated. The bitmap must be either 8-bit grayscale or 24- or 32-bit color (BGR).

L_VOID *pYuvData

Pointer to a buffer to receive the YUV data. If NULL, pnYuvDataSize will be updated with the expected size of the YUV data buffer. If not NULL, the YUV data will be extracted and stored in pYuvData if the buffer is large enough to contain the YUV data.

L_SIZE_T *puYuvDataSize

Required size of the YUV data buffer pointed to by pYuvData. Cannot be NULL. If pYuvData is non-NULL, nYuvDataSize indicates the size of pYuvData. If this value is too small, the function will fail (and display the ERROR_BUFFER_TOO_SMALL error), and pnYuvDataSize will be updated with the required buffer size.

L_YUV yuvFormat

Specifies the YUV data format. See L_YUV.

L_UINT uFlags

Unused, reserved for future use. Pass 0.

Returns

Value	Meaning
SUCCESS	The function was successful.
ERROR_NULL_PTR	`pBitmap` or `pYuvData` is NULL.
ERROR_BITPERPIXEL	pBitmap is not 8-, 24- or 32-bits per pixel.
ERROR_NO_MEMORY	Not enough memory.
ERROR_INV_RANGE	Invalid bitmap width or height (usually because they are not multiple of 2).
ERROR_INVALID_YUV_SIZE	The size of the YUV data (nYuvDataSize) does not match the width and height values from pBitmap.
ERROR_INVALID_YUV_FORMAT	The color space in `yuvFormat` does not match one of the supported values.
< 1	An error occurred. Refer to Return Codes.

Comments

The user is responsible for allocating the YUV buffer, and freeing it when it is no longer needed.

The buffer should be large enough to store the data for the whole image. If the buffer is not large enough to store all the requested data, the function will fail (and display the ERROR_BUFFER_TOO_SMALL error).

Note that in each case, the function ignores the ViewPerspective. So the YUV data will match the view perspective in the bitmap. In other words, if the bitmap's view perspective is BOTTOM_LEFT, the YUV data you retrieve in the YUV buffer will be flipped. In most cases, you will want the YUV buffer to be correct side up, so make the ViewPerspective to be TOP_LEFT. You can use the L_ChangeBitmapViewPerspective function to make the bitmap have the correct ViewPerspective.

The YUV data will be in studio YUV format, which means the Y values will range from 16 to 235 and the U, V values will range from 16 to 240. The Y values are unsigned, while U, V values are offset by 0x80. In other words, a value of 0x80 for U corresponds to a U value of 0 and a value of 0x7F corresponds to a U value of -1.

If you do not know the expected size of the YUV buffer, you can call the function twice, as follows:

L_SIZE_T yuvSize; 
/* Call L_GetBitmapYUVData with pYuvBuffer=NULL to get the size */ 
if(L_GetBitmapYUVData(pBitmap, NULL, &yuvSize, L_YUV_NV21, 0) == SUCCESS) 
{ 
   L_VOID *pYuvBuffer = malloc(yuvSize); 
   L_GetBitmapYUVData(pBitmap, pYuvBuffer, &yuvSize, L_YUV_NV21, 0); 
   /* use pYuvBuffer */ 
   free(pYuvBuffer); /* free it when it is not necessary anymore */ 
}

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

This function loads a YUV data from a file in nv21 format. The bitmap was saved using an Android device's camera.

L_INT GetBitmapYUVDataExample(BITMAPHANDLE *pBitmap) 
{ 
   L_INT nRet; 
   HANDLE hFile = CreateFile(MAKE_IMAGE_PATH(TEXT("nv21.bin")), GENERIC_READ, FILE_SHARE_READ, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL); 
 
   if(hFile == INVALID_HANDLE_VALUE) 
      return ERROR_FILE_OPEN; 
 
   LARGE_INTEGER fileSize; 
 
   if(!GetFileSizeEx(hFile, &fileSize)) 
   { 
      CloseHandle(hFile); 
      return ERROR_FILE_READ; 
   } 
 
   L_UCHAR *pYuvData = (L_UCHAR*)malloc((size_t)fileSize.QuadPart * 2); 
   if(!pYuvData) 
   { 
      CloseHandle(hFile); 
      return ERROR_NO_MEMORY; 
   } 
 
   DWORD dwRead; 
   if(!ReadFile(hFile, pYuvData, (DWORD)fileSize.QuadPart, &dwRead, NULL)) 
   { 
      CloseHandle(hFile); 
      free(pYuvData); 
      return ERROR_FILE_READ; 
   } 
   CloseHandle(hFile); 
 
   L_FreeBitmap(pBitmap); 
 
   L_InitBitmap(pBitmap, sizeof(BITMAPHANDLE), 1920, 1080, 24); 
   pBitmap->ViewPerspective = TOP_LEFT; 
 
   L_SIZE_T yuvDataSize = (L_SIZE_T)fileSize.QuadPart; 
 
   nRet = L_SetBitmapYUVData(pBitmap, pYuvData, yuvDataSize, L_YUV_NV21, 0); 
 
   if(nRet == SUCCESS) 
      nRet = L_SaveFile(MAKE_IMAGE_PATH(TEXT("nv21-0.jpg")), pBitmap, FILE_JPEG, 0, 2, 0, NULL, NULL, NULL); 
 
   if(nRet == SUCCESS) 
   { 
      yuvDataSize += yuvDataSize; 
      nRet = L_GetBitmapYUVData(pBitmap, pYuvData, &yuvDataSize, L_YUV_YUY2, 0); 
   } 
 
   if(nRet == SUCCESS) 
      nRet = L_SetBitmapYUVData(pBitmap, pYuvData, yuvDataSize, L_YUV_YUY2, 0); 
 
   if(nRet == SUCCESS) 
      nRet = L_SaveFile(MAKE_IMAGE_PATH(TEXT("nv21-1.jpg")), pBitmap, FILE_JPEG, 0, 2, 0, NULL, NULL, NULL); 
 
   free(pYuvData); 
 
   return nRet; 
}