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 — 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.
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 sizeThe size of the input buffer is assumed to be width X height X number of bytes per pixel
- Pixel format
For more information, go to FRAME_DESC structure (defined in the file PixeLINKTypes.h).