Syntax


 PXL_RETURN_CODE PxLFormatImage (

   void const *       pSrcImage,

   FRAME_DESC const * pSrcFrameDesc,

   U32                outputFormat,

   void*              pDstImage,

   U32*               pDstBufferSize );


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 - Converts to bitmap (.bmp) format

    • IMAGE_FORMAT_TIFF - Converts to TIFF (.tif)

    • IMAGE_FORMAT_PSD - Converts to Adobe Photoshop (.psd) format

    • IMAGE_FORMAT_JPEG - Converts to JPEG (.jpg) format (high quality; 5% compression).

    • IMAGE_FORMAT_PNG - Converts to PNG (.png) format.

    • IMAGE_FORMAT_RAW_MONO8 - Converts to the monochrome equivalent of IMAGE_FORMAT_RAW_BGR24, with data presented left to right, top to bottom (last row last).

    • IMAGE_FORMAT_RAW_RGB24 - Converts to RGB with 24 bits per pixel. The output is an array of data similar to the BMP format but without the header. The data is in a Windows Device Independent Bitmap format. Windows DIB format is an array of data with 8 bits per color channel or 24 bits 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. Similar to IMAGE_FORMAT_RAW_RGB24, but the data is presented in a non-DIB format. More explicitly, the colors are in a red, green, blue order (left to right), top to bottom (last row last). 

    • IMAGE_FORMAT_RAW_BGR24 - Converts to BGR with 24 bits per pixel. Similar to IMAGE_FORMAT_RAW_RGB24_NON_DIB, but the colors are sequenced blue, green, then red (left to right).

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