L_StartCompressBuffer

#include "l_bitmap.h"

L_LTFIL_API L_INT L_StartCompressBuffer(pBitmap, pfnCallback, uInputBytes, uOutputBytes, pOutputBuffer, nOutputType, nQFactor, pUserData, pSaveOptions)

pBITMAPHANDLE pBitmap;	pointer to the bitmap handle
COMPBUFFCALLBACK pfnCallback;	pointer to the callback function
L_SIZE_T uInputBytes;	size of user allocated input buffer
L_SIZE_T uOutputBytes;	size of user allocated output buffer
L_UCHAR *pOutputBuffer;	pointer to the output buffer
L_INT nOutputType;	type of compression to use
L_INT nQFactor;	compression quality factor
L_VOID *pUserData;	pointer to more parameters for the callback
pSAVEFILEOPTION pSaveOptions;	pointer to optional extended save options

Initializes the buffered compression engine. The compression is then carried out using the L_CompressBuffer function. It is ended by the L_EndCompressBuffer function.

Parameter	Description
pBitmap	Pointer to the bitmap handle that describes the image to compress. The following fields must be set correctly in the bitmap handle: Width, Height, and BitsPerPixel. This allows the compression process to know what type of image it is trying to compress.
pfnCallback	Pointer to the callback function. This function is responsible for writing or handling the compressed data. The callback function must adhere to the function prototype described in COMPBUFFCALLBACK.
	This callback function must return SUCCESS or an error code (negative number). If it returns an error code, the compression process will stop, and the code will be passed back as the return code for L_CompressBuffer.
uInputBytes	The size of user allocated buffer that will hold the raw data. This has to be a multiple of 8 lines or 16 lines depending on the output compression method specified. For LEAD1JTIF, LEAD1JFIF, or any LEAD Qfactor that is greater than 100, or a predefined setting of MC, SQT, or MCQ, you must allocate 16-line multiples. For LEADJ2K and LEADJP2, this value should represent one line of image data only (pBitmap>BytesPerLine). For all other compression factors and methods, manually set or predefined, 8-line multiples are required.
	To simplify your coding, you can always allocate 16-line multiples.
uOutputBytes	The size of user allocated compressed buffer.For LEADJ2K and LEADJP2, use 0.
pOutputBuffer	Pointer to user output buffer that will hold the compressed data. For LEADJ2K and LEADJP2, use NULL (the buffer will be allocated internally).
nOutputType	Type of compression to use. Valid values are:
	Value	Meaning
	LEAD	[0] LEAD CMP compression format.
	JFIF	[1] JPEG File Interchange Format using YUV 4:4:4 color spacing.
	LEAD2JFIF	[5] JPEG File Interchange Format using YUV 4:2:2 color spacing.
	LEAD1JFIF	[3] JPEG File Interchange Format using YUV 4:1:1 color spacing.
	JTIF	[2] JPEG JTIF using YUV 4:4:4 color spacing.
	LEAD2JTIF	[6] JPEG JTIF using YUV 4:2:2 color spacing.
	LEAD1JTIF	[4] JPEG JTIF using YUV 4:1:1 color spacing.
	LEADJ2K	[7] JPEG 2000 Stream.
	LEADJP2	[8] JPEG 2000 File.
nQFactor	Compression quality factor to use for the specified compression format. This value can be any integer ranging from 2 to 255 for all the supported compression methods.
	Alternatively, for LEAD CMP compression only, LEADTOOLS provides enhanced Q factors which are defined as follows:
	Value	Meaning
	PQ1	[-1] Perfect Quality compression Option 1.
	PQ2	[-2] Perfect Quality compression Option 2.
	QFS	[-3] Quality Far more important than Size.
	QMS	[-4] Quality More important than Size.
	QS	[-5] Quality and Size are equally important.
	SQS	[-6] Size more important than Quality - Sharp.
	SQT	[-7] Size more important than Quality - less Tilling.
	MCQ	[-8] Maximum Compression, keeping quality as good as possible.
	MC	[-9] Maximum Compression.
pUserData	Void pointer that you can use to pass one or more additional parameters that the callback function needs.
	To use this feature, assign a value to a variable or create a structure that contains as many fields as you need. Then, in this parameter, pass the address of the variable or structure, casting it to L_VOID *. The callback function, which receives the address in its own pUserData parameter, can cast it to a pointer of the appropriate data type to access your variable or structure.
	If the additional parameters are not needed, you can pass NULL in this parameter.
pSaveOptions	Pointer to optional extended save options. Pass NULL to use the default save options.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

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.

You must declare and initialize a bitmap handle before calling this function, but you do not have to allocate the bitmap. In the bitmap handle, the Order field must be ORDER_BGR, and the ViewPerspective field must be TOP_LEFT. Then, the data that you put into the input buffer must be BGR and loaded from top left.

The compression process starts after the first call to L_CompressBuffer. Your callback function is called when the output buffer is filled with compressed data or after completing the compression process. The callback function is responsible for emptying the output buffer storing it, sending it, or doing other processing.

Your program must allocate the output buffer. The following is a flow chart that shows the relationship of these functions:

$image\compbuf.gif$

Do not free any buffers that the compression engine uses until after you call the L_EndCompressBuffer function.

Before calling this function to compress LEADJ2K or LEADJP2, you can call L_SetJ2KOptions to specify the file save options if you wish to use somthing other than the default.

Required DLLs and Libraries

LTFIL
File format DLLs

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 example demonstrates low-level image compression using L_StartCompressBuffer, L_CompressBuffer, and L_EndCompressBuffer. The callback function for writing the output is included at the end of the example.

#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName 
L_INT EXT_CALLBACK FileWrite (pBITMAPHANDLE pBitmap, 
L_UCHAR     * pBuffer, 
L_SIZE_T      uBytes, 
L_VOID      * pParams) 
{ 
   UNREFERENCED_PARAMETER (pBitmap); 
   DWORD dwBytesWritten; 
   /* Write data to the file.  Note that the file handle is passed in as an L_VOID 
   pointer as per the LEAD definition and must be cast appropriately to use it as a file handle. */ 
   WriteFile( ((HANDLE*)pParams)[0], pBuffer, (DWORD)uBytes, &dwBytesWritten, NULL); 
   return (SUCCESS); 
} 
L_INT StartCompressBufferExample(pBITMAPHANDLE LeadBitmap) 
{ 
   L_INT nRet; 
   L_INT i, j;            /* Loop counters                           */ 
   HANDLE hFD;             /* File handle                             */ 
   L_UINT32 uLineBytes;   /* Bytes per line in the input buffer      */ 
   HGLOBAL hInBuffer;     /* Input buffer handle                     */ 
   HGLOBAL hOutBuffer;    /* Output buffer handle                    */ 
   L_UCHAR *lpInBuffer;   /* Pointer to the input buffer             */ 
   L_UCHAR *lpOutBuffer;  /* Pointer to the output buffer            */ 
   L_UCHAR *lpDataBuffer; /* Copy of the pointer to the input buffer */ 
   /* Load the image to the bitmap at 24-bits per pixel */ 
   if(LeadBitmap->Flags.Allocated) 
      L_FreeBitmap(LeadBitmap); 
   nRet = L_LoadBitmap (MAKE_IMAGE_PATH(TEXT("ImageProcessingDemo\\Image3.cmp")), LeadBitmap, sizeof(BITMAPHANDLE), 24, ORDER_BGR, NULL, NULL); 
   if(nRet != SUCCESS) 
      return nRet; 
   if(LeadBitmap->ViewPerspective != TOP_LEFT) 
   { 
      nRet = L_ChangeBitmapViewPerspective ( NULL, LeadBitmap, sizeof(BITMAPHANDLE), TOP_LEFT ); 
      if(nRet != SUCCESS) 
         return nRet; 
   } 
   /* Create the output file */ 
   hFD = CreateFile(MAKE_IMAGE_PATH(TEXT("COMPCB.CMP")), GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, 0); 
   /* Calculate the bytes per line in the input buffer, without padding */ 
   uLineBytes = LeadBitmap->Width * 3; 
   /* Allocate memory for the incoming uncompressed data. Note that we 
   are compressing 16 lines at a time. You should always use multiples of 16 */ 
   hInBuffer = GlobalAlloc( GMEM_MOVEABLE, 16 * uLineBytes); 
   lpInBuffer = (L_UCHAR *)GlobalLock( hInBuffer ); 
   /* Allocate an output buffer. This is where the compressed data will 
   go. Note that this allocates 1024-byte packets. */ 
   hOutBuffer = GlobalAlloc( GMEM_MOVEABLE, 1024 ); 
   lpOutBuffer = (L_UCHAR *)GlobalLock( hOutBuffer ); 
   /* Lock down the bitmap */ 
   L_AccessBitmap( LeadBitmap ); 
   /* Initialize the compression engine  */ 
   nRet = L_StartCompressBuffer(LeadBitmap, 
   FileWrite, 
   16 * uLineBytes, 
   1024, 
   (L_UCHAR *)lpOutBuffer, 
   LEAD, 
   QFS, 
   (L_VOID *) &hFD, NULL ); 
   if(nRet != SUCCESS) 
      return nRet; 
   /* Compress the data */ 
   for( i = 0; i < LeadBitmap->Height; ) /* i is incremented at the end */ 
   { 
      lpDataBuffer = lpInBuffer; 
      /* Compression of the 16-line chunk starts here */ 
      for( j = 0; (i+j) < LeadBitmap->Height && j < 16; j++ ) 
      { 
         /* Get one line at time */ 
         nRet = (L_INT)  L_GetBitmapRow(LeadBitmap, lpDataBuffer, i+j, uLineBytes); 
         if(nRet < 1) 
            return nRet; 
         /* Move the pointer to next line */ 
         lpDataBuffer = lpDataBuffer + uLineBytes; 
      } 
      /* This is the main function that will do the actual Compression. */ 
      nRet = L_CompressBuffer(lpInBuffer); 
      if(nRet != SUCCESS) 
         return nRet; 
      i += 16; 
   } 
   /* Reset the compression engine */ 
   nRet = L_EndCompressBuffer(); 
   if(nRet != SUCCESS) 
      return nRet; 
   /* Free all allocated memory.  Release the bitmap.  Close the file. */ 
   GlobalUnlock( hInBuffer ); 
   GlobalFree( hInBuffer ); 
   GlobalUnlock( hOutBuffer ); 
   GlobalFree( hOutBuffer ); 
   L_ReleaseBitmap(LeadBitmap ); 
   CloseHandle( hFD ); 
   MessageBox (NULL, TEXT("Function complete"), TEXT("Notice"), MB_OK); 
   return SUCCESS; 
}

Help Version 19.0.2017.10.27

Functions:	L_CompressBuffer, L_EndCompressBuffer
Topics:	Raster Image Functions: Saving Files