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

pOutputBuffer

Pointer to user output buffer that will hold the compressed data.

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.

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.

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

Windows 2000 / XP/Vista, Windows CE.

See Also

Functions:

L_CompressBuffer, L_EndCompressBuffer

Topics:

Raster Image Functions: Saving Files

Example

This example demonstrates low-level image compression using L_StartCompressBuffer,L_CompressBuffer, L_CompressBuffer, and L_EndCompressBufferL_EndCompressBuffer. The callback function for writing the output is included at the end of the example.

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, 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 (TEXT("C:\\Program Files\\LEAD Technologies\\LEADTOOLS 15\\Images\\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(TEXT("C:\\Program Files\\LEAD Technologies\\LEADTOOLS 15\\Images\\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;
}