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:

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]pSinkA queue sink
[in]num_buffersNumber 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

◆ ic4_queuesink_create()

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

Creates a new Queue Sink.

Parameters
[in]ppSinkPointer to a sink handle to receive the new queue sink.
[in]configPointer 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]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_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]pSinkA queue sink
[out]sizesA 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]pSinkA queue sink
[out]cancel_requestedPointer 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]pSinkA queue sink
[out]ppImageBufferA 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.