SnapSink Class Referencefinal

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

Inheritance diagram for SnapSink:

Sink

Classes

struct  Config

The SnapSink configuration structure. More...

struct  CustomAllocationStrategy

Specifies a custom allocation strategy. More...

Public Types

enum class  AllocationStrategy { Default = ic4::c_interface::IC4_SNAPSINK_ALLOCATION_STRATEGY_DEFAULT , Custom = ic4::c_interface::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...

- Public Types inherited from Sink
enum class  SinkMode { Run = c_interface::IC4_SINK_MODE_RUN , Pause = c_interface::IC4_SINK_MODE_PAUSE }

Defines the possible sink modes. More...

Public Member Functions

ImageType outputImageType (Error &err=Error::Default()) const

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

std::shared_ptr< ImageBuffersnapSingle (std::chrono::milliseconds timeout, Error &err=Error::Default())

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

std::shared_ptr< ImageBuffersnapSingle (int64_t timeout_ms, Error &err=Error::Default())

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

std::vector< std::shared_ptr< ImageBuffer > > snapSequence (size_t count, std::chrono::milliseconds timeout, Error &err=Error::Default())

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

std::vector< std::shared_ptr< ImageBuffer > > snapSequence (size_t count, int64_t timeout_ms, Error &err=Error::Default())

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

SinkType sinkType () const noexcept final

Returns the type of this sink.

- Public Member Functions inherited from Sink
bool setSinkMode (SinkMode mode, Error &err=Error::Default()) noexcept

Sets the sink mode for a sink.

SinkMode sinkMode () const noexcept

Gets the current sink mode of a sink.

bool isAttached () const noexcept

Checks whether a sink is currently attached to a Grabber as part of a data stream.

Static Public Member Functions

static std::shared_ptr< SnapSinkcreate (Error &err=Error::Default())

Creates a SnapSink using the default configuration.

static std::shared_ptr< SnapSinkcreate (const CustomAllocationStrategy &strategy, Error &err=Error::Default())

Creates a SnapSink using a customized buffer allocation strategy.

static std::shared_ptr< SnapSinkcreate (const std::shared_ptr< BufferAllocator > &allocator, Error &err=Error::Default())

Creates a SnapSink using a custom buffer allocator.

static std::shared_ptr< SnapSinkcreate (const std::vector< PixelFormat > &acceptedPixelFormats, Error &err=Error::Default())

Creates a SnapSink specifying a list of accepted image types.

static std::shared_ptr< SnapSinkcreate (PixelFormat acceptedPixelFormat, Error &err=Error::Default())

Creates a SnapSink specifying an accepted image type.

static std::shared_ptr< SnapSinkcreate (const Config &config, Error &err=Error::Default())

Creates a SnapSink using a configuration structure.

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 SnapSink::create().

To grab a single image out of the stream, call SnapSink::snapSingle(). To grab a sequence of images, call SnapSink::snapSequence().

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 through a std::shared_ptr. Once all std::shared_ptr pointers are reset, 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 Grabber::streamStatistics() 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 providing a BufferAllocator to the sink creation function.

Member Enumeration Documentation

◆ AllocationStrategy

enum class AllocationStrategy
strong

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

Enumerator
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 Config::customAllocationStrategy setting is ignored.

Custom 

Custom allocation strategy.

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

Member Function Documentation

◆ create() [1/6]

static std::shared_ptr< SnapSink > create ( const Config config,
Error err = Error::Default() 
)
inlinestatic

Creates a SnapSink using a configuration structure.

This generic overload allows specifying a combination of configuration options like allocation strategy, buffer allocator and accepted frame types.

Parameters
[in]configA configuration structure specifying sink behavior
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::shared_ptr to the new sink, or nullptr if an error occurred.
Check the err output parameter for error code and error message.

◆ create() [2/6]

static std::shared_ptr< SnapSink > create ( const CustomAllocationStrategy strategy,
Error err = Error::Default() 
)
inlinestatic

Creates a SnapSink using a customized buffer allocation strategy.

Parameters
[in]strategyA custom buffer allocation strategy
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::shared_ptr to the new sink, or nullptr if an error occurred.
Check the err output parameter for error code and error message.
See also
create(const Config&, Error&)

◆ create() [3/6]

static std::shared_ptr< SnapSink > create ( const std::shared_ptr< BufferAllocator > &  allocator,
Error err = Error::Default() 
)
inlinestatic

Creates a SnapSink using a custom buffer allocator.

Parameters
[in]allocatorA custom buffer allocator
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::shared_ptr to the new sink, or nullptr if an error occurred.
Check the err output parameter for error code and error message.
See also
create(const Config&, Error&)

◆ create() [4/6]

static std::shared_ptr< SnapSink > create ( const std::vector< PixelFormat > &  acceptedPixelFormats,
Error err = Error::Default() 
)
inlinestatic

Creates a SnapSink specifying a list of accepted image types.

Parameters
[in]acceptedPixelFormatsA std::vector containing the accepted pixel formats.
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::shared_ptr to the new sink, or nullptr if an error occurred.
Check the err output parameter for error code and error message.
See also
create(const Config&, Error&)

◆ create() [5/6]

static std::shared_ptr< SnapSink > create ( Error err = Error::Default())
inlinestatic

Creates a SnapSink using the default configuration.

Parameters
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::shared_ptr to the new sink, or nullptr if an error occurred.
Check the err output parameter for error code and error message.
See also
create(const Config&, Error&)

◆ create() [6/6]

static std::shared_ptr< SnapSink > create ( PixelFormat  acceptedPixelFormat,
Error err = Error::Default() 
)
inlinestatic

Creates a SnapSink specifying an accepted image type.

Parameters
[in]acceptedPixelFormatThe pixel format accepted by the sink.
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::shared_ptr to the new sink, or nullptr if an error occurred.
Check the err output parameter for error code and error message.
See also
create(const Config&, Error&)

◆ outputImageType()

ImageType outputImageType ( Error err = Error::Default()) const
inline

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

Parameters
[out]errReference to an error handler. See Error Handling for details.
Returns
The image type the sink is configured for. If the function fails, the image type's pixel format is PixelFormat::Invalid. Check the err output parameter for error code and error message.

◆ sinkType()

SinkType sinkType ( ) const
inlinefinalvirtualnoexcept

Returns the type of this sink.

Returns
The type of this sink

Implements Sink.

◆ snapSequence() [1/2]

std::vector< std::shared_ptr< ImageBuffer > > snapSequence ( size_t  count,
int64_t  timeout_ms,
Error err = Error::Default() 
)
inline

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 the timeout has expired. If the timeout expires, the function returns the number of images grabber and the error value is set to ErrorCode::Timeout.

Parameters
countNumber of images to grab
timeout_msTime to wait for all images to arrive
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::vector of std::shared_ptr to image buffers.
If an error occurred, the vector's size is smaller than count.
Check the err output parameter for error code and error message.
Precondition
This operation is only valid while the sink is connected to a device in a data stream.
Note
After a successfull call, the returned std::shared_ptrs own the image buffers.
All pointers have to be reset to return the image buffers to the sink for reuse.

◆ snapSequence() [2/2]

std::vector< std::shared_ptr< ImageBuffer > > snapSequence ( size_t  count,
std::chrono::milliseconds  timeout,
Error err = Error::Default() 
)
inline

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 the timeout has expired. If the timeout expires, the function returns the number of images grabber and the error value is set to ErrorCode::Timeout.

Parameters
countNumber of images to grab
timeoutTime to wait for all images to arrive
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::vector of std::shared_ptr to image buffers.
If an error occurred, the vector's size is smaller than count.
Check the err output parameter for error code and error message.
Precondition
This operation is only valid while the sink is connected to a device in a data stream.
Note
After a successfull call, the returned std::shared_ptrs own the image buffers.
All pointers have to be reset to return the image buffers to the sink for reuse.

◆ snapSingle() [1/2]

std::shared_ptr< ImageBuffer > snapSingle ( int64_t  timeout_ms,
Error err = Error::Default() 
)
inline

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

Parameters
timeout_msTime to wait for a new image to arrive
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::shared_ptr to the filled image buffer, or nullptr in case of an error.
Check the err output parameter for error code and error message.
Precondition
This operation is only valid while the sink is connected to a device in a data stream.
Note
After a successfull call, the returned std::shared_ptr owns the image buffer.
The pointer has to be reset to return the image buffer to the sink for reuse.

◆ snapSingle() [2/2]

std::shared_ptr< ImageBuffer > snapSingle ( std::chrono::milliseconds  timeout,
Error err = Error::Default() 
)
inline

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

Parameters
timeoutTime to wait for a new image to arrive
[out]errReference to an error handler. See Error Handling for details.
Returns
A std::shared_ptr to the filled image buffer, or nullptr in case of an error.
Check the err output parameter for error code and error message.
Precondition
This operation is only valid while the sink is connected to a device in a data stream.
Note
After a successfull call, the returned std::shared_ptr owns the image buffer.
The pointer has to be reset to return the image buffer to the sink for reuse.