QueueSink Class Referencefinal

A sink implementation that allows a program to process all images received from a video capture device. More...

Inheritance diagram for QueueSink:

Classes

struct	Config The QueueSink configuration structure. More...
struct	QueueSizes Contains information about the current queue lengths inside the queue sink. More...

Public Member Functions

ImageType	outputImageType (Error &err=Error::Default()) const Queries the image type of the images the sink is configured to receive.
SinkType	sinkType () const noexcept final Returns the type of this sink.
bool	allocAndQueueBuffers (size_t num_buffers, Error &err=Error::Default()) Allocates a number of buffers matching the sink's image type and puts them into the free queue.
std::shared_ptr< ImageBuffer >	popOutputBuffer (Error &err=Error::Default()) Retrieves a buffer that was filled with image data from the sink's output queue.
bool	isCancelRequested (Error &err=Error::Default()) Checks whether the data stream this sink is connected to is in the process of being stopped.
QueueSizes	queueSizes (Error &err=Error::Default()) Query information about the number of image buffers in the queue sink's queues.
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< QueueSink >	create (QueueSinkListener &cb, Error &err=Error::Default()) Creates a new queue sink using the default configuration.
static std::shared_ptr< QueueSink >	create (const std::shared_ptr< QueueSinkListener > &cb, Error &err=Error::Default()) Creates a new queue sink using the default configuration.
static std::shared_ptr< QueueSink >	create (std::function< void(ic4::QueueSink &)> frames_queued, Error &err=Error::Default()) Creates a new queue sink using the default configuration.
static std::shared_ptr< QueueSink >	create (QueueSinkListener &cb, PixelFormat sink_format, Error &err=Error::Default()) Creates a new queue sink specifying a pixel format for the sink.
static std::shared_ptr< QueueSink >	create (const std::shared_ptr< QueueSinkListener > &cb, PixelFormat sink_format, Error &err=Error::Default()) Creates a new queue sink specifying a pixel format for the sink.
static std::shared_ptr< QueueSink >	create (std::function< void(ic4::QueueSink &)> frames_queued, PixelFormat sink_format, Error &err=Error::Default()) Creates a new queue sink specifying a pixel format for the sink.
static std::shared_ptr< QueueSink >	create (QueueSinkListener &cb, const Config &config, Error &err=Error::Default()) Creates a new queue sink using a configuration structure.
static std::shared_ptr< QueueSink >	create (const std::shared_ptr< QueueSinkListener > &cb, const Config &config, Error &err=Error::Default()) Creates a new queue sink using a configuration structure.
static std::shared_ptr< QueueSink >	create (std::function< void(ic4::QueueSink &)> frames_queued, const Config &config, Error &err=Error::Default()) Creates a new queue sink using a configuration structure.

Additional Inherited Members

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

Detailed Description

A sink implementation that allows a program to process all images received from a video capture device.

A queue sink manages a number of buffers that are organized in two queues:

A free queue that buffers are pulled from to fill with data from the device
An output queue that contains the filled buffers ready to be picked up by the program

To create a queue sink, call QueueSink::create().

Pass the sink to Grabber::streamSetup() to feed images into the sink.

Usually, the queue sink is interacted with by deriving a class from QueueSinkListener and implementing its member functions. The functions are called at different significant points in the lifetime of a queue sink:

QueueSinkListener::sinkConnected() is called when a data stream is being set up from the device to the sink. The callback is responsible for making sure there are enough buffers queued for streaming to begin.
QueueSinkListener::framesQueued() is called whenever there are images available in the output queue.
QueueSinkListener::sinkDisconnected() is called when a previously-created data stream is stopped.

To retrieve the oldest available image from the output queue, call QueueSink::popOutputBuffer(). The image buffer is owned by the returned shared_ptr. The caller is responsible to reset the shared_ptr at a later time to return the image buffer to the sink's free queue.

A program does not necessarily have to requeue all image buffers immediately; it can choose to store pointers to a number of them in its own data structures. However, please note that if there are no buffers in the free queue when the device tries to deliver a frame, the frame will be dropped. Use Grabber::streamStatistics() to find out whether a buffer underrun occurred.

Member Function Documentation

◆ allocAndQueueBuffers()

bool allocAndQueueBuffers	(	size_t	num_buffers,
		Error &	err = `Error::Default()`
	)

inline

Allocates a number of buffers matching the sink's image type and puts them into the free queue.

Parameters

[in]	num_buffers	Number of buffers to allocate
[out]	err	Reference to an error handler. See Error Handling for details.

Returns: true on success, otherwise false.
Check the err output parameter for error code and error message.

◆ create() [1/9]

static std::shared_ptr< QueueSink > create	(	const std::shared_ptr< QueueSinkListener > &	cb,
		const Config &	config,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink using a configuration structure.

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

Parameters

[in]	cb	A `std::shared_ptr` to a QueueSinkListener-derived listener receiving the sink callbacks.
[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/9]

static std::shared_ptr< QueueSink > create	(	const std::shared_ptr< QueueSinkListener > &	cb,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink using the default configuration.

Parameters

[in]	cb	A `std::shared_ptr` to a QueueSinkListener-derived listener receiving the sink callbacks.
[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 std::shared_ptr<QueueSinkListener>&, const Config&, Error&)

◆ create() [3/9]

static std::shared_ptr< QueueSink > create	(	const std::shared_ptr< QueueSinkListener > &	cb,
		PixelFormat	sink_format,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink specifying a pixel format for the sink.

Parameters

[in]	cb	A `std::shared_ptr` to a QueueSinkListener-derived listener receiving the sink callbacks.
[in]	sink_format	The pixel format of the buffers received by the sink. If this differs from the device's pixel format, the image data is transformed automatically.
[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 std::shared_ptr<QueueSinkListener>&, const Config&, Error&)

◆ create() [4/9]

static std::shared_ptr< QueueSink > create	(	QueueSinkListener &	cb,
		const Config &	config,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink using a configuration structure.

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

Parameters

[in]	cb	A reference to a QueueSinkListener-derived listener receiving the sink callbacks.
[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.

Remarks: The program has to make sure that the passed listener exists as long as the sink does.

◆ create() [5/9]

static std::shared_ptr< QueueSink > create	(	QueueSinkListener &	cb,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink using the default configuration.

Parameters

[in]	cb	A reference to a QueueSinkListener-derived listener receiving the sink callbacks.
[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.

Remarks: The program has to make sure that the passed listener exists as long as the sink does.

See also: create(QueueSinkListener&, const Config&, Error&)

◆ create() [6/9]

static std::shared_ptr< QueueSink > create	(	QueueSinkListener &	cb,
		PixelFormat	sink_format,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink specifying a pixel format for the sink.

Parameters

[in]	cb	A reference to a QueueSinkListener-derived listener receiving the sink callbacks.
[in]	sink_format	The pixel format of the buffers received by the sink. If this differs from the device's pixel format, the image data is transformed automatically.
[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.

Remarks: The program has to make sure that the passed listener exists as long as the sink does.

See also: create(QueueSinkListener&, const Config&, Error&)

◆ create() [7/9]

static std::shared_ptr< QueueSink > create	(	std::function< void(ic4::QueueSink &)>	frames_queued,
		const Config &	config,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink using a configuration structure.

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

Parameters

[in]	frames_queued	A function to be called when new frames have been queued in the sink.
[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() [8/9]

static std::shared_ptr< QueueSink > create	(	std::function< void(ic4::QueueSink &)>	frames_queued,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink using the default configuration.

Parameters

[in]	frames_queued	A function to be called when new frames have been queued in 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(std::function<void(ic4::QueueSink&)>, const Config&, Error&)

◆ create() [9/9]

static std::shared_ptr< QueueSink > create	(	std::function< void(ic4::QueueSink &)>	frames_queued,
		PixelFormat	sink_format,
		Error &	err = `Error::Default()`
	)

inlinestatic

Creates a new queue sink specifying a pixel format for the sink.

Parameters

[in]	frames_queued	A function to be called when new frames have been queued in the sink.
[in]	sink_format	The pixel format of the buffers received by the sink. If this differs from the device's pixel format, the image data is transformed automatically.
[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(std::function<void(ic4::QueueSink&)>, const Config&, Error&)

◆ isCancelRequested()

bool isCancelRequested ( Error & err = Error::Default() )

inline

Checks whether the data stream this sink is connected to is in the process of being stopped.

This function can be used to cancel a long-running operation in the QueueSinkListener::framesQueued() callback.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: true if cancel is requested, otherwise false.
In case of an error, the function returns false.
Check the err output parameter for error code and error message.

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

◆ popOutputBuffer()

std::shared_ptr< ImageBuffer > popOutputBuffer ( Error & err = Error::Default() )

inline

Retrieves a buffer that was filled with image data from the sink's output queue.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A std::shared_ptr to the buffer that was successfully dequeued, otherwise nullptr.
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: The buffers are retrieved in order they were received from the video capture device; the oldest image is returned first.; After a successful call, the caller owns the image buffer via the std::shared_ptr. The pointer must be reset to put the image buffer into the sink's free queue for later reuse.

◆ queueSizes()

QueueSizes queueSizes ( Error & err = Error::Default() )

inline

Query information about the number of image buffers in the queue sink's queues.

Parameters

[out] err Reference to an error handler. See Error Handling for details.

Returns: A structure containing queue size information. If the function fails, both queues are reported to have size 0. 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.