L_GetBitmapYUVData

#include "l_bitmap.h"

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

pBITMAPHANDLE pBitmap;	pointer to the bitmap handle
L_VOID *pYuvData;	data pointer
L_SIZE_T *pnYuvDataSize;	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.
pnYuvDataSize	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.

Example

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

#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName 
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 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_SetBitmapYUVData, L_GetBitmapRow, L_PutBitmapRow, L_AllocateBitmap, L_CreateBitmap, L_ChangeBitmapViewPerspective
Topics:	Raster Image Functions: Creating and Deleting Images