L_GetBitmapYUVData

#include "l_bitmap.h"

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

pBITMAPHANDLE pBitmap;

pointer to the bitmap handle

L_VOID *pYuvData;

data pointer

L_SIZE_T *puYuvDataSize;

pointer to a variable to be updated with the size of the data buffer pointed to by pYuvData

L_YUV yuvFormat;

data format

L_UINT uFlags;

flags

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

Parameter

Description

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).

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.

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.

yuvFormat Specifies the YUV data format.  See L_YUV.
uFlags Unused, reserved for future use.  Pass 0.

Returns

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.

See Also

Functions:

L_SetBitmapYUVData, L_GetBitmapRow, L_PutBitmapRow, L_AllocateBitmap, L_CreateBitmapL_ChangeBitmapViewPerspective

Topics:

Raster Image Functions: Creating and Deleting Images

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 L_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; 
} 

Help Version 20.0.2018.2.25
Products | Support | Contact Us | Copyright Notices
© 1991-2018 LEAD Technologies, Inc. All Rights Reserved.
LEADTOOLS Raster Imaging C API Help