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 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.