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:
![](common/img/classic4_queue_sink.png)
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. |
![]() |
|
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
![]() | |
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()
|
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, otherwisefalse
.
Check the err output parameter for error code and error message.
◆ create() [1/9]
|
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, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
◆ create() [2/9]
|
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, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
◆ create() [3/9]
|
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, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
◆ create() [4/9]
|
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, ornullptr
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]
|
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, ornullptr
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() [6/9]
|
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, ornullptr
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() [7/9]
|
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, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
◆ create() [8/9]
|
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, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
◆ create() [9/9]
|
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, ornullptr
if an error occurred.
Check the err output parameter for error code and error message.
◆ isCancelRequested()
|
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, otherwisefalse
.
In case of an error, the function returnsfalse
.
Check the err output parameter for error code and error message.
◆ outputImageType()
|
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()
|
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, otherwisenullptr
.
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()
|
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.