This function converts a frame (stored in a buffer) into another format and stores it in a buffer.  Is is useful for preparing image data to save to file or for converting a raw data buffer to another format.



..................................................................................................................................................................................................................................................................................


Controls and Indicators



         uOutputFormat IN is an enumerated list of output format types. The list currently contains the following values:


  • IMAGE_FORMAT_TIFF - Convert to TIFF (.tif)

  • IMAGE_FORMAT_BMP - Convert to bitmap (.bmp) format.

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

  • IMAGE_FORMAT_JPG - Convert to JPEG (.jpg) fotmat (high quality; 5% compression)

  • IMAGE_FORMAT_RGB24 - Converts to RGB with 24 bits per pixel (Windows Device Independent Bitmap Format).



          pDest IN is a pointer (array) to the output buffer. If the array has zero elements, then DestBufferSize OUT will contain the size of the required output buffer based on the information in pFrameDesc IN.


         DestBufferSize IN is the size of the pDest IN buffer in bytes. If pDest IN is set to an empty array, it is ignored.


         pSrc IN is the pointer (array) to the buffer containing the image data to be converted.



         pFrameDesc IN is a structure containing descriptive information about the frame returned from the camera by GetNextFrame.vi or the Callback threads. It contains the values of all camera settings used to capture the image. See the API reference manual for more information.Only the following four features in the structure are used:


        ROI - the cluster specifying the ROI size and position on the sensor.



       fWidth - the width of the ROI in pixels


       fHeight - the height of the ROI in pixels


        PixelAddressingValue

      fValue - the factor by which the ROI.fWidth and ROI.fHeight need to be reduced. Each dimension can be pided by PixelAddressingValue to determine the pixel size of the output image.

         Pixel Format

      fValue - the value of the PixelFormat enumerated control. It determines the number of bytes per pixel in pDest IN.

       uOutputFormat OUT is a pass through of the uOutputFormat IN.


       pDest OUT is the formatted output buffer.


       DestBufferSize OUT is the size of the pDest IN buffer in bytes.


       pSrc OUT is a pass-through of pSrc IN. 


      pFrameDesc OUT is a pass-through of pFrameDesc IN. 



Equivalent API Function: PxLFormatImage


Details


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, FormatImageArray will return the size of the output frame in pDestBufferSize OUT.  To determine the appropriate amount of the memory to be allocated to the destination buffer without generating an error message, call FormatImageArray with pDest IN set to an empty array and a valid pFrameDesc IN. The required number of bytes will be returned in pDestBufferSize OUT, and the destination buffer can be sized accordingly.


An overlay callback can be used to modify the output image.  Before calling FormatImageArray, call SetCallback with CallbackInfo IN.uOverlayUse set to OVERLAY_FORMAT_IMAGE.



Note: See Error Handling for error input and output information and error codes.