Snap Sink

The snap sink is a sink implementation that allows a program to capture single images or sequences of images on demand, while still having a display showing all images. More...

Data Structures

struct  IC4_SNAPSINK_CONFIG

Configures the behavior of a snap sink. More...

Enumerations

enum  IC4_SNAPSINK_ALLOCATION_STRATEGY { IC4_SNAPSINK_ALLOCATION_STRATEGY_DEFAULT = 0 , IC4_SNAPSINK_ALLOCATION_STRATEGY_CUSTOM }

The buffer allocation strategy defines how many buffers are pre-allocated, when additional buffers are created, and when excess buffers are reclaimed. More...

Functions

bool ic4_snapsink_create (struct IC4_SINK **ppSink, const struct IC4_SNAPSINK_CONFIG *config)

Creates a new Snap Sink.

bool ic4_snapsink_get_output_image_type (const struct IC4_SINK *pSink, struct IC4_IMAGE_TYPE *image_type)

Queries the image type of the images the sink is configured to receive.
bool ic4_snapsink_snap_single (const struct IC4_SINK *pSink, struct IC4_IMAGE_BUFFER **ppImageBuffer, int64_t timeout_ms)

Grabs a single image out of the video stream received from the video capture device.
size_t ic4_snapsink_snap_sequence (const struct IC4_SINK *pSink, struct IC4_IMAGE_BUFFER **pImageBufferList, size_t count, int64_t timeout_ms)

Grabs a sequence of images out of the video stream received from the video capture device.

Detailed Description

The snap sink is a sink implementation that allows a program to capture single images or sequences of images on demand, while still having a display showing all images.

To create a snap sink, call ic4_snapsink_create().

To grab a single image out of the stream, call ic4_snapsink_snap_single(). To grab a sequence of images, call ic4_snapsink_snap_sequence().

The snap sink manages the buffers used for background image aquisition as well as for the grabbed images. During stream setup, a number of buffers is allocated depending on the configured allocation strategy. Additional buffers can be automatically created on demand, if the allocation strategy allows. Likewise, if there is a surplus of unused image buffers, unused buffers are reclaimed and released automatically.

Image buffers that were returned by one of the snap functions are owned by their respective caller until ic4_imagebuffer_unref() is called on them. Once the image buffer objects are released, they are automatically returned to the snap sink for reuse.

Please note that if there are no buffers available in the sink when the device tries to deliver a frame, the frame will be dropped. Use ic4_grabber_get_stream_stats() to find out whether a buffer underrun occurred.

By default, the sink uses buffers provided by the device driver or the implicitly created transformation filter. It is possible to use program-defined buffers be used by setting allocator callback functions in IC4_SNAPSINK_CONFIG::allocator.

Enumeration Type Documentation

◆ IC4_SNAPSINK_ALLOCATION_STRATEGY

enum IC4_SNAPSINK_ALLOCATION_STRATEGY

The buffer allocation strategy defines how many buffers are pre-allocated, when additional buffers are created, and when excess buffers are reclaimed.

Enumerator
IC4_SNAPSINK_ALLOCATION_STRATEGY_DEFAULT 

Use the default strategy.

This strategy pre-allocates an automatically selected number of buffers depending on the requirements of the data stream and the image size.

The custom strategy parameters in IC4_SNAPSINK_CONFIG setting are ignored.

IC4_SNAPSINK_ALLOCATION_STRATEGY_CUSTOM 

Custom allocation strategy.

The IC4_SNAPSINK_CONFIG::num_buffers_alloc_on_connect, IC4_SNAPSINK_CONFIG::num_buffers_allocation_threshold IC4_SNAPSINK_CONFIG::num_buffers_free_threshold and IC4_SNAPSINK_CONFIG::num_buffers_max parameters determine the sink's allocation behavior.

Function Documentation

◆ ic4_snapsink_create()

bool ic4_snapsink_create ( struct IC4_SINK **  ppSink,
const struct IC4_SNAPSINK_CONFIG *  config 
)

Creates a new Snap Sink.

Parameters
[in]ppSinkPointer to a sink handle to receive the new snap sink.
[in]configPointer to a structure containing the sink configuration.
This parameter is optional; passing NULL will use the default configuration.
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.

The image type of the images the sink receives is determined when the data stream to the sink is created in a call to ic4_grabber_stream_setup() using the following steps:

  • If IC4_SNAPSINK_CONFIG::num_pixel_formats is 0, the device format is selected.
  • If the device's output format matches one of the pixel formats passed in IC4_SNAPSINK_CONFIG::pixel_formats, the first match is selected.
  • If there is no direct match, but a conversion between the device's output format format and one of the passed pixel formats exists, the first format with a conversion is selected.
  • If no conversion between the device's output format and any of the values in IC4_SNAPSINK_CONFIG::pixel_formats exists, the stream setup fails.

◆ ic4_snapsink_get_output_image_type()

bool ic4_snapsink_get_output_image_type ( const struct IC4_SINK *  pSink,
struct IC4_IMAGE_TYPE *  image_type 
)

Queries the image type of the images the sink is configured to receive.

Parameters
[in]pSinkA queue sink
[out]image_typeA structure receiving the image type information
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Precondition
This operation is only valid while there is a data stream from a device to the sink.

◆ ic4_snapsink_snap_sequence()

size_t ic4_snapsink_snap_sequence ( const struct IC4_SINK *  pSink,
struct IC4_IMAGE_BUFFER **  pImageBufferList,
size_t  count,
int64_t  timeout_ms 
)

Grabs a sequence of images out of the video stream received from the video capture device.

This function waits until count images have been grabbed, or timeout_ms milliseconds have passed. If the timeout expires, the function returns the number of images grabber and the error value is set to IC4_ERROR_TIMEOUT.

Parameters
[in]pSinkA snap sink
[out]pImageBufferListA pointer to an array of frame handles to receive the newly-filled images
[in]countNumber of images to grab
[in]timeout_msTime to wait for all images to arrive
Returns
The number of images grabbed successfully.
If an error occurred, the function returns 0. Use ic4_get_last_error() to query error information.
Precondition
This operation is only valid while the sink is connected to a device in a data stream.
Note
After a successfull call, the handles pointed to by pImageBufferList own the frame objects.
A call to ic4_imagebuffer_unref() is required to return each image buffer to the sink for reuse.

◆ ic4_snapsink_snap_single()

bool ic4_snapsink_snap_single ( const struct IC4_SINK *  pSink,
struct IC4_IMAGE_BUFFER **  ppImageBuffer,
int64_t  timeout_ms 
)

Grabs a single image out of the video stream received from the video capture device.

This function waits until either the next buffer from the video capture device is received, or timeout_ms milliseconds have passed. If the timeout expires, the function fails and the error value is set to IC4_ERROR_TIMEOUT.

Parameters
[in]pSinkA snap sink
[out]ppImageBufferA pointer to a frame handle to receive the newly-filled image
[in]timeout_msTime to wait for a new image to arrive
Returns
true on success, otherwise false.
Use ic4_get_last_error() to query error information.
Precondition
This operation is only valid while the sink is connected to a device in a data stream.
Note
After a successfull call, the handle pointed to by ppImageBuffer owns the frame object.
A call to ic4_imagebuffer_unref() is required to return the image buffer to the sink for reuse.