SMART Streaming

SMART Streaming allows the user to assign individual exposure settings to each frame of a continuous sequence; the camera will apply the settings just before the frame is captured. This feature is camera-dependent, please check PARAM_SMART_STREAM_MODE_ENABLED parameter and ATTR_AVAIL to discover the availability.

The maximum number of SMART Streaming entries varies from camera to camera. This parameter can be requested via the ATTR_MAX attribute of particular SMART Streaming parameter (PARAM_SMART_STREAM_EXP_PARAMS or PARAM_SMART_STREAM_DLY_PARAMS).

The diagram below illustrates SMART Streaming for a sequence of 3 frames with exposures of 10ms, 20ms, 30ms, and no delay between frames.

An example of SMART Streaming acquisition setup:

• pl_set_param with PARAM_SMART_STREAM_MODE_ENABLED - SMART stream mode is enabled.
• pl_set_param with PARAM_SMART_STREAM_EXP_PARAMS - the exposure parameters are passed in to the camera
• pl_exp_setup_seq or pl_exp_setup_cont - either single sequence or circular buffer mode is selected. The exposure time in this call needs to be non-zero and it will be overwritten by the exposure times passed by pl_set_param with PARAM_SMART_STREAM_EXP_PARAMS.
• pl_exp_start_seq or pl_exp_start_cont - data acquisition is started
• the loop is repeated until the buffer fills up or until continuous data acquisition is stopped with pl_exp_abort

Data Types

A SMART Streaming acquisition is programmed by sending the camera a list of the individual exposures or delays along with the frame count. To facilitate this process, the smart_stream_type structure encapsulates the required parameters. This data type consists of an uns16 variable called entries and an array of uns32 values called params. The params variable points to a list of exposures or delays. The entries variable contains the number of entries in the list.

A variable of type smart_stream_type can be filled in two ways:

1. On stack, for example:

   smart_stream_type exposureArray;
   uns32 exposureValues[] = {10, 20 ,30, 40};
   exposureArray.entries = sizeof(exposureValues) / sizeof(uns32);
   exposureArray.params = exposureValues;
   /* Send to PVCAM via #pl_set_param and acquire the data here */

2. On heap, with the aid of the pl_create_smart_stream_struct function. To avoid memory leaks, don't forget in this case to release allocated memory via pl_release_smart_stream_struct function. For example:

   smart_stream_type* pExposureArray;
   pl_create_smart_stream_struct(&pExposureArray, 4);
   for (uns16 i = 0; i < pExposureArray->entries; i++)
       pExposureArray->params[i] = 10 + i * 10;
   /* Send to PVCAM via #pl_set_param */
   pl_release_smart_stream_struct(&pExposureArray);
   /* Acquire the data here, pExposureArray is not needed anymore */

The parameters PARAM_SMART_STREAM_EXP_PARAMS and PARAM_SMART_STREAM_DLY_PARAMS work with values of smart_stream_type structure. The same type is returned also for other attributes. For backward compatibility with inconsistent historical implementation, all other attributes except for ATTR_CURRENT return only the first two bytes of smart_stream_type structure, i.e. the number of entries, which in case of ATTR_MAX represents the maximum number of entries the camera accepts. This size can be used to pre-allocate the structure dynamically for its maximum possible size. The value of ATTR_COUNT reports the current number of valid exposure entries returned by ATTR_CURRENT.

Note

Please, refer to the Live Image SMART Streaming code example to obtain more information on how to use SMART Streaming.

Possible Scenarios

• SMART Streaming enabled but no arrays passed in
  In this case, only the exposure as defined in the pl_exp_setup_seq will be used.
• Exposure Count (N) > Sequence Size (M)
  For a finite sequence, the first N entries will be used and the rest will be ignored. For a circular buffer sequence, all of the defined entries will be used in a round-robin fashion (i.e. after a frame has been captured with the last entry defined in the SMART stream parameter, the cycle will be repeated with the first defined entry, then the second, etc.)
• Exposure Count (N) < Sequence Size (M)
  For a finite sequence, the defined entries will be used in a round-robin fashion and repeated until all frames are consumed. For a circular buffer sequence, all of the defined entries will be used in a round-robin fashion (i.e. after a frame has been captured with the last entry defined in the SMART streaming parameter, the cycle will be repeated with the first defined entry, then the second one, etc.)