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:

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< ImageBuffer >	snapSingle (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< ImageBuffer >	snapSingle (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< SnapSink >	create (Error &err=Error::Default()) Creates a SnapSink using the default configuration.
static std::shared_ptr< SnapSink >	create (const CustomAllocationStrategy &strategy, Error &err=Error::Default()) Creates a SnapSink using a customized buffer allocation strategy.
static std::shared_ptr< SnapSink >	create (const std::shared_ptr< BufferAllocator > &allocator, Error &err=Error::Default()) Creates a SnapSink using a custom buffer allocator.
static std::shared_ptr< SnapSink >	create (const std::vector< PixelFormat > &acceptedPixelFormats, Error &err=Error::Default()) Creates a SnapSink specifying a list of accepted image types.
static std::shared_ptr< SnapSink >	create (PixelFormat acceptedPixelFormat, Error &err=Error::Default()) Creates a SnapSink specifying an accepted image type.
static std::shared_ptr< SnapSink >	create (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

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.

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]	config	A configuration structure specifying sink behavior
[out]	err	Reference 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]	strategy	A custom buffer allocation strategy
[out]	err	Reference 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]	allocator	A custom buffer allocator
[out]	err	Reference 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]	acceptedPixelFormats	A `std::vector` containing the accepted pixel formats.
[out]	err	Reference 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] err Reference 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]	acceptedPixelFormat	The pixel format accepted by the sink.
[out]	err	Reference 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] err Reference 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

	count	Number of images to grab
	timeout_ms	Time to wait for all images to arrive
[out]	err	Reference 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.

Parameters

	count	Number of images to grab
	timeout	Time to wait for all images to arrive
[out]	err	Reference 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_ms	Time to wait for a new image to arrive
[out]	err	Reference 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

	timeout	Time to wait for a new image to arrive
[out]	err	Reference 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.