L_StartCompressBuffer

Summary

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

Syntax

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

Parameters

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

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

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

L_SIZE_T uOutputBytes

The size of user allocated compressed buffer.For LEADJ2K and LEADJP2, use 0.

L_UCHAR *pOutputBuffer

Pointer to user output buffer that will hold the compressed data. For LEADJ2K and LEADJP2, use NULL (the buffer will be allocated internally).

L_INT nOutputType

Type of compression to use. Valid values are:

L_INT 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:

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

pSAVEFILEOPTION pSaveOptions

Pointer to optional extended save options. Pass NULL to use the default save options.

Returns

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:

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.

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,
and L_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)[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; 
}