Queue Sink

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

Data Structures

struct	IC4_QUEUESINK_CALLBACKS Contains function pointers used to specify the behavior of a queue sink. More...
struct	IC4_QUEUESINK_CONFIG Configures the behavior of a queue sink. More...
struct	IC4_QUEUESINK_QUEUE_SIZES Contains information about the current queue lengths inside the queue sink. More...

Functions

bool	ic4_queuesink_create (struct IC4_SINK *ppSink, const struct IC4_QUEUESINK_CONFIG config) Creates a new Queue Sink.
bool	ic4_queuesink_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_queuesink_alloc_and_queue_buffers (struct IC4_SINK *pSink, size_t num_buffers) Allocates a number of buffers matching the sink's image type and puts them into the free queue.
bool	ic4_queuesink_pop_output_buffer (struct IC4_SINK pSink, struct IC4_IMAGE_BUFFER *ppImageBuffer) Retrieves a buffer that was filled with image data from the sink's output queue.
bool	ic4_queuesink_is_cancel_requested (const struct IC4_SINK pSink, bool cancel_requested) Checks whether the data stream this sink is connected to is in the process of being stopped.
bool	ic4_queuesink_get_queue_sizes (const struct IC4_SINK pSink, struct IC4_QUEUESINK_QUEUE_SIZES sizes) Query information about the number of image buffers in the queue sink's queues.

Detailed Description

The queue sink is 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 ic4_queuesink_create().

Usually, the queue sink is interacted with by registering a set of callback functions in IC4_QUEUESINK_CALLBACKS. The callback functions are called at different significant points in the lifetime of a queue sink:

IC4_QUEUESINK_CALLBACKS::sink_connected 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.
IC4_QUEUESINK_CALLBACKS::frames_queued is called whenever there are images available in the output queue.
IC4_QUEUESINK_CALLBACKS::sink_disconnected is called when a previously-created data stream is stopped.
IC4_QUEUESINK_CALLBACKS::release is called when the sink object is being destroyed. Resources that the sink or other callback functions depends on can be released.

To retrieve the oldest available image from the output queue, call ic4_queuesink_pop_output_buffer(). The caller owns the IC4_IMAGE_BUFFER that is returned. It is responsible to call ic4_imagebuffer_unref() at a later time to return the buffer to the sink's free queue.

A program does not necessarily have to requeue all image buffers immediately; it can choose to store references 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 ic4_grabber_get_stream_stats() to find out whether a buffer underrun occurred.

Function Documentation

◆ ic4_queuesink_alloc_and_queue_buffers()

bool ic4_queuesink_alloc_and_queue_buffers	(	struct IC4_SINK *	pSink,
		size_t	num_buffers
	)

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

Parameters

[in]	pSink	A queue sink
[in]	num_buffers	Number of buffers to allocate

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

Precondition

This operation is only valid while the sink's image type is known. This is the case

inside the IC4_QUEUESINK_CALLBACKS::sink_connected callback function
when the sink was successfully connected to a data stream

◆ ic4_queuesink_create()

bool ic4_queuesink_create	(	struct IC4_SINK **	ppSink,
		const struct IC4_QUEUESINK_CONFIG *	config
	)

Creates a new Queue Sink.

Parameters

[in]	ppSink	Pointer to a sink handle to receive the new queue sink.
[in]	config	Pointer to a structure containing the sink 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_QUEUESINK_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_QUEUESINK_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_QUEUESINK_CONFIG::pixel_formats exists, the stream setup fails.

◆ ic4_queuesink_get_output_image_type()

bool ic4_queuesink_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]	pSink	A queue sink
[out]	image_type	A 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_queuesink_get_queue_sizes()

bool ic4_queuesink_get_queue_sizes	(	const struct IC4_SINK *	pSink,
		struct IC4_QUEUESINK_QUEUE_SIZES *	sizes
	)

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

Parameters

[in]	pSink	A queue sink
[out]	sizes	A pointer to a structure to receive the queue lengths

Precondition: This operation is only valid while there is a data stream from a device to the sink.

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_queuesink_is_cancel_requested()

bool ic4_queuesink_is_cancel_requested	(	const struct IC4_SINK *	pSink,
		bool *	cancel_requested
	)

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 IC4_QUEUESINK_CALLBACKS::frames_queued callback.

Parameters

[in]	pSink	A queue sink
[out]	cancel_requested	Pointer to a flag that receives the cancel request

Returns: true on success, otherwise false.
Use ic4_get_last_error() to query error information.

◆ ic4_queuesink_pop_output_buffer()

bool ic4_queuesink_pop_output_buffer	(	struct IC4_SINK *	pSink,
		struct IC4_IMAGE_BUFFER **	ppImageBuffer
	)

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

Parameters

[in]	pSink	A queue sink
[out]	ppImageBuffer	A pointer to a frame handle to receive the newly-filled image

Returns: true if a buffer was successfully dequeued, 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: The buffers are retrieved in order they were received from the video capture device; the oldest image is returned first.; After a successfull call, the handle pointed to by ppImageBuffer owns the frame object.
A call to ic4_imagebuffer_unref() is required to put the image buffer into the sink's free queue for later reuse.