PxLGetNextCompressedFrame : Pixelink Support

Syntax

PXL_RETURN_CODE PxLGetNextFrame (
  HANDLE      hCamera,
  U32         bufferSize,
  void*       pFrame,
  FRAME_DESC* pFrameDesc,
  COMPRESSION_DESC*	pCompressionDesc,
  U32*		compressionDescSize);

Description

This function returns a compressed frame of image data, the feature descriptor, and the compression descriptor for that frame from the video stream of the pixel format the camera is using. The image data in the frame is compressed using the specified compression scheme by the feature compression. The pixel format and compression information can be found by querying the PixelFormat and CompressionInfo elements of the frame descriptor structure that is returned by PxLGetNextCompressedFrame. If the camera has a trigger feature (see PxLGetCameraFeatures) and the trigger mode is set to TRIGGER_TYPE_SOFTWARE, then this function also causes a software trigger. Trigger types are defined in the file PixelinkTypes.h.

hCamera is the camera handle. This value is returned by PxLInitializeEx.
bufferSize is the number of bytes of memory allocated for the frame as uncompressed. This value is used as a check to prevent memory overflow.
pFrame is the pointer to the array receiving the frame of image data.
pFrameDesc is the pointer to a frame descriptor (see FRAME_DESC structure). The structure is also defined in the file PixeLINKTypes.h.
- N.B. The uSize member of the FRAME_DESC structure MUST be filled in before each and every call to PxLGetNextFrame. Otherwise the API will assume that an older version (smaller size) of the structure is being used, and consequently some members of the structure will not be populated with data.

Comments, Restrictions and Limitations

Before this function is called, memory space should be allocated for the image data pFrame (width × height × number of bytes per pixel, where width and height take the pixel addressing value into account), and the FRAME_DESC structure for pFrameDesc. The C/C++ demo application 'getsnapshot' demonstrates one technique to determine the image size.

Before this function is called, the camera defined by the handle hCamera must be streaming. Use PxLSetStreamState START_STREAM to start streaming.

Get Next Compressed Frame

The same as PxLGetNextFrame, PxLGetNextCompressedFrame gets the next compressed frame available after the function is called; it will block until the next compressed frame becomes available. If your application must not miss a compressed frame, PxLGetNextCompressedFrame must be called at a rate greater than the frame rate.

Timeouts

Note that it is possible for PxLGetNextCompressedFrame to return an error code because of a temporary timeout condition during times of high CPU usage or high bus utilization. To account for this, it is suggested that calls to PxLGetNextCompressedFrame for non-triggered cameras be wrapped by a retry loop which detects this temporary timeout condition.

The demonstration application 'getnextframe' demonstrates a suggested approach, but for PxLGetNextFrame.

Dropping a Frame

As of PixeLINK Release 7.0, it is possible to drop a frame, or retrieve information about a frame without requiring that the frame data be copied. This is done by passing in a frame buffer size of -1.

Example 1

// Drop a frame. i.e. Throw away the next frame 

PXL_RETURN_CODE rc = PxLGetNextFrame(hCamera, (U32)-1, NULL, NULL, &compressionDesc, &compressionDescSize);

Example 2

// Throw away the next frame, but return the information for that frame.

FRAME_DESC frameDesc
frameDesc.uSize = sizeof(frameDesc);
PXL_RETURN_CODE rc = PxLGetNextCompressedFrame(hCamera, (U32)-1, NULL, &frameDesc, &compressionDesc, &compressionDescSize);

The latter call is useful if you want to ensure that you're receiving images that have recent feature changes applied. For example, after changing the exposure from X to Y, you may want to ensure that all the images with exposure X have been received by the host, and that images with exposure Y are now being received.

Trigger Modes

When the camera is configured for free-running triggering (that is, frames are output continuously, driven by an internal trigger that occurs as frequently as possible), this function returns the next available frame from the camera.

When in software trigger mode, PxLGetNextCompressedFrame:

generates the trigger
blocks until the frame is received from the camera.

When in hardware trigger mode, PxLGetNextCompressedFrame blocks until the next triggered frame is received from the camera. Triggered frames delivered to the host while a thread is not blocked in PxLGetNextCompressedFrame will be missed.

PxLGetNextCompressedFrame

Related Articles