Syntax
 

 PXL_RETURN_CODE PxLFormatImage (

 void const *       pSrcImage,

 FRAME_DESC const * pSrcFrameDesc,

 U32                outputFormat,

 void*              pDstImage,

 U32*               pDstBufferSize );

 

Description


This function converts a frame (stored in a buffer) into an end-user format and stores it in a buffer. 

  • pSrcImage is the pointer to the buffer containing the image data to be converted.  
  • pSrcFrameDesc is the pointer to the frame descriptor.  This is normally provided by PxLGetNextFrame, but the application may also apply a custom descriptor to the output frame.  See below for more information.
  • outputFormat is the output format desired.  Valid format flags are:
    • IMAGE_FORMAT_BMP — Convert to bitmap (.bmp) format
    • IMAGE_FORMAT_TIFF — Convert to TIFF (.tif)
    • IMAGE_FORMAT_PSD — Convert to Adobe Photoshop (.psd) format
    • IMAGE_FORMAT_JPEG — Convert to JPEG (.jpg) format (high quality; 5% compression).
    • IMAGE_FORMAT_RAW_RGB24 — Converts to RGB with 24 bits per pixel. Similar to the data found in a Windows Device Independent Bitmap format, with an array of data with 8bits per color channel or 24bits per pixel in the order of blue, green, red, left to right, bottom to top (last row first).  
    • IMAGE_FORMAT_RAW_RGB24_NON_DIB —Converts to RGB with 24 bits per pixel.  With this format, the first line of the image is also the first line of the buffer (first row first), with the 8bit color channels sequenced red, green, then blue. 
    • IMAGE_FORMAT_RAW_RGB48 — Converts to RGB with 48 bits per pixel. Each pixel is a triplet of little-endian 16-bit values, starting at the top left pixel.
     

These values are defined in the file PixeLINKTypes.h. 

  • pDst is a pointer to the destination buffer.  Set to NULL to return the required output buffer size in pDstBufferSize 
  • pDstBufferSize points to the size of the pDst buffer (in bytes).  On output, the function returns the actual buffer size in this parameter.

Usage

Recommended method of using PxLFormatImage: 

  • Call the function with pDst set to NULL.  The required size of the destination buffer is returned in pDstBufferSize
  • Allocate the required number of bytes of memory to the destination buffer.
  • Call the function with pDst set to point to the allocated destination buffer
   

Comments, Restrictions and Limitations


 Output Buffer size               

Prior to calling this function, sufficient memory space should be allocated to the destination buffer.  If the destination buffer is too small, the application will return an ApiBufferTooSmall message.  

           

Regardless of the return code generated, PxLFormatImage will return the size of the output frame in pDstBufferSize, so to determine the appropriate amount of the memory to be allocated to the destination buffer without running the risk of generating an error message, call PxLFormatImage with pDst set to NULL.  The required number of bytes will be returned in pDstBufferSize, and the destination buffer can be allocated prior to calling the function with pDst pointing at the buffer location.      

         

Input Buffer size

   The size of the input buffer is assumed to be width X height X number of bytes per pixel 

Custom frame descriptor
Use of a custom descriptor requires the use of advanced functions.
Note that pFrameDesc applies only the following four features from a descriptor:
  • Width
  • Height
  • Decimation
  • Pixel format


For more information, go to FRAME_DESC structure (defined in the file PixeLINKTypes.h).


 Callback  

If you want a chance to modify the image, specify the  callback function with PxLSetCallback using the  callback type CALLBACK_FORMAT_IMAGE.