Management of buffers for image acquisition

It can be difficult to capture images close to the maximum possible frame rate without dropping frames. To avoid this situation, the user can prepare multiple buffers and give them for image aquisition to the library. The buffers are automatically used after each other sequentially and given back to the user when completed.

From the user's perspective there are two internal queues, both with FIFO characteristic. One queue holds the empty buffers ready for aquisition and another queue contains the completed images.

Simple use case

The following example describes a simple flow, using only a single buffer:

The user allocates a buffer by calling FG_alloc_image().
The buffer is added to the acquisition queue by calling FG_append_image(), the library controls the buffer now.
The buffer gets filled with the next sensor frame.
After the image is completely captured, the buffer is moved to the done queue. The library will continue using buffers in the empty queue for new sensor frames.
FG_get_image() will return with the buffer and the user can access the image data.
After the user finished working with the buffer, the buffer can again be added to the acquisition queue.

Simplified buffer flow

The example can easily be modified to use multiple buffers by calling FG_alloc_image() and FG_append_image() multiple times during startup.
For more details, also take a look at the Frist Steps Example.

Note: The sensor interface on the VisionSensor PV3 requires at least two queued buffers before aquisition is started, see e2v EV2S02M / EV2S05M for details.

Additional buffers handling rules

Abort acquisition: Calling FG_stop_image() forces the library to stop using any buffer immediately regardless of the current buffer state. After return of this function, all buffers are under the control of the user. The function will also wake up other threads waiting in FG_get_image().

Acquisition timeouts and errors

The function call FG_get_image() can return two dedicated error codes:

FG_ERROR_CODE_GrabTimeOut: Timeout occured, no buffer is passed on to the user. Previously added buffers stay under the control of the library. The user can call FG_get_image() again.
FG_ERROR_CODE_BrokenImage: A buffer is passed on to the user but the content is undefined, because something went wrong during acquisition of a frame.

Additional buffer restrictions

There are some restrictions when working with image buffers:

Buffers can only be allocated with FG_alloc_image() and released with FG_free_image().
After the first buffer is allocated with FG_alloc_image(), it is not possible to change the AOI size. Some sensors allow moving the AOI position wihtout changing the size. Uninstall the camera or use FG_stop_image() and release all buffers before changing the size.
It is not allowed to access the buffer contents while the buffer is owned by the library.