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:

Sink

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< ImageBufferpopOutputBuffer (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< QueueSinkcreate (QueueSinkListener &cb, Error &err=Error::Default())

Creates a new queue sink using the default configuration.

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

Creates a new queue sink using the default configuration.

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

Creates a new queue sink using the default configuration.

static std::shared_ptr< QueueSinkcreate (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< QueueSinkcreate (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< QueueSinkcreate (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< QueueSinkcreate (QueueSinkListener &cb, const Config &config, Error &err=Error::Default())

Creates a new queue sink using a configuration structure.

static std::shared_ptr< QueueSinkcreate (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< QueueSinkcreate (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:

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_buffersNumber of buffers to allocate
[out]errReference 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]cbA std::shared_ptr to a QueueSinkListener-derived listener receiving the sink callbacks.
[in]configA configuration structure specifying sink behavior
[out]errReference 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]cbA std::shared_ptr to a QueueSinkListener-derived listener receiving the sink callbacks.
[out]errReference 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]cbA std::shared_ptr to a QueueSinkListener-derived listener receiving the sink callbacks.
[in]sink_formatThe 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]errReference 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]cbA reference to a QueueSinkListener-derived listener receiving the sink callbacks.
[in]configA configuration structure specifying sink behavior
[out]errReference 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]cbA reference to a QueueSinkListener-derived listener receiving the sink callbacks.
[out]errReference 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]cbA reference to a QueueSinkListener-derived listener receiving the sink callbacks.
[in]sink_formatThe 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]errReference 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_queuedA function to be called when new frames have been queued in the sink.
[in]configA configuration structure specifying sink behavior
[out]errReference 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_queuedA function to be called when new frames have been queued in the sink.
[out]errReference 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_queuedA function to be called when new frames have been queued in the sink.
[in]sink_formatThe 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]errReference 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]errReference 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]errReference 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]errReference 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]errReference 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.