Class QueueSink

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

Inheritance

QueueSink

Implements

Namespace: ic4
Assembly: ic4dotnet.dll
Syntax
public class QueueSink : Sink, IDisposable
Remarks

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, use one of its constructors (QueueSink(PixelFormat, IBufferAllocator, int) or QueueSink(IEnumerable<PixelFormat>, IBufferAllocator, int)).

Pass the sink to StreamSetup(Sink, IDisplay, StreamSetupOption) or StreamSetup(Sink, StreamSetupOption) to feed images into the sink.

Usually, the sink is interacted with by registering handlers for the sink's events. The Events are raised at different significant points in the lifetime of a queue sink:

  • SinkConnected occurs when a data stream is being set up from the device to the sink. The event handler is responsible for making sure there are enough buffers queued for streaming to begin.
  • FramesQueued occurs whenever there are images available in the output queue.
  • SinkDisconnected occurs when a previously-created data stream is stopped.

To retrieve the oldest available image from the output queue, call PopOutputBuffer() or TryPopOutputBuffer(out ImageBuffer). The returned image buffer is owned by the program. If the program no longer needs the image buffer, Dispose() must be called it 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 keep references to the 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 StreamStatistics to find out whether a buffer underrun occurred.

Constructors

QueueSink(IEnumerable<PixelFormat>, IBufferAllocator, int)

Creates a new queue sink.

Declaration

public QueueSink(IEnumerable<PixelFormat> acceptedPixelFormats = null, IBufferAllocator customAllocator = null, int maxOutputBuffers = 0)

Parameters

Type Name Description
IEnumerable<PixelFormat> acceptedPixelFormats

An optional list of pixel formats that restrict the input to this sink.

This can be used to force an automatic conversion from the device's pixel format to a pixel format usable by the sink.

IBufferAllocator customAllocator

An optional custom buffer allocator

int maxOutputBuffers

Defines the maximum number of buffers that are stored in the sink's output queue.

If set to 0, the number of buffers is unlimited.

If a new frame arrives at the sink, and the output queue size would exceed this number, the oldest image is discarded and its buffer is added to the free queue.

Exceptions

Type Condition
ArgumentException

maxOutputBuffers is less than0

IC4Exception

Check ErrorCode and ToString() for details.

QueueSink(PixelFormat, IBufferAllocator, int)

Creates a new queue sink.

Declaration

public QueueSink(PixelFormat acceptedPixelFormat, IBufferAllocator customAllocator = null, int maxOutputBuffers = 0)

Parameters

Type Name Description
PixelFormat acceptedPixelFormat

A pixel format that restricts the input to this sink.

This can be used to force an automatic conversion from the device's pixel format to a pixel format usable by the sink.

IBufferAllocator customAllocator

An optional custom buffer allocator

int maxOutputBuffers

Defines the maximum number of buffers that are stored in the sink's output queue.

If set to 0, the number of buffers is unlimited.

If a new frame arrives at the sink, and the output queue size would exceed this number, the oldest image is discarded and its buffer is added to the free queue.

Exceptions

Type Condition
ArgumentException

maxOutputBuffers is less than0

IC4Exception

Check ErrorCode and ToString() for details.

Properties

IsCancelRequested

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

Declaration

public bool IsCancelRequested { get; }
Property Value
Type Description
bool

true, if the data stream to this sink is in the process of being stopped, otherwise false.

Exceptions

Type Condition
IC4Exception

Check ErrorCode and ToString() for details.

OutputImageType

The image type of the images the sink is configured to receive

Declaration

public ImageType OutputImageType { get; }
Property Value
Type Description
ImageType

The image type of the images the sink is configured to receive

Exceptions

Type Condition
IC4Exception

Check ErrorCode and ToString() for details.

QueueSizes

The lengths of the queues in the sink

Declaration

public QueueSinkQueueSizes QueueSizes { get; }
Property Value
Type Description
QueueSinkQueueSizes

A structure containing information about the sink's current queue sizes.

Exceptions

Type Condition
IC4Exception

Check ErrorCode and ToString() for details.

Type

The type of the sink.

For queue sinks, this always is QueueSink.

Declaration

public override SinkType Type { get; }
Property Value
Type Description
SinkType

The type of the sink.

Overrides

Methods

AllocAndQueueBuffers(int)

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

Declaration

public void AllocAndQueueBuffers(int count)

Parameters

Type Name Description
int count

Number of buffers to allocate

Exceptions

Type Condition
IC4Exception

Check ErrorCode and ToString() for details.

PopOutputBuffer()

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

Declaration

public ImageBuffer PopOutputBuffer()

Returns

Type Description
ImageBuffer

A filled image buffer

Remarks

This operation is only valid while the sink is connected to a device in a data stream.

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 program owns the image buffer through the ImageBuffer reference. The image buffer object must be disposed to put the image buffer into the sink's free queue for later reuse.

Exceptions

Type Condition
IC4Exception

Check ErrorCode and ToString() for details.

TryPopOutputBuffer(out ImageBuffer)

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

In contrast to PopOutputBuffer(), this function does not throw an exception in case of an error.

Declaration

public bool TryPopOutputBuffer(out ImageBuffer buffer)

Parameters

Type Name Description
ImageBuffer buffer

Output parameter receiving the image buffer reference on success

Returns

Type Description
bool

true, if a filled image buffer was retrieved, otherwise false.

Remarks

This operation is only valid while the sink is connected to a device in a data stream.

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 program owns the image buffer through the ImageBuffer reference. The image buffer object must be disposed to put the image buffer into the sink's free queue for later reuse.

Events

FramesQueued

Occurs when new images were added to the sink's queue of filled buffers.

Declaration

public event EventHandler<QueueSinkEventArgs> FramesQueued
Event Type
Type Description
EventHandler<QueueSinkEventArgs>
Remarks

The event handler usually calls PopOutputBuffer() to get access to the filled image buffers.

If this callback function performs a lengthy operation, it is recommended to regularly check IsCancelRequested to determine whether the data stream is being stopped.

The function is executed on dedicated thread managed by the sink.

When the data stream to the sink is stopped, the StreamStop() call will wait until this event handler returns. This can quickly lead to a deadlock, if code in the event handler performs an operation that unconditionally requires activity on the thread that called StreamStop().

SinkConnected

Occurs when the data stream to the sink is created

Declaration

public event EventHandler<QueueSinkConnectedEventArgs> SinkConnected
Event Type
Type Description
EventHandler<QueueSinkConnectedEventArgs>
Remarks

The event handler can abort the creation of the data stream by setting AbortConnect to true.

MinBuffersRequired indicates the minimum number of buffers required for the data stream to operate. If the event handler does not allocate any buffers, the sink will automatically allocate the minimum number of buffers required.

The function is executed on the thread that calls StreamSetup(Sink, StreamSetupOption).

SinkDisconnected

Occurs when the data stream to the sink is stopped.

Declaration

public event EventHandler<QueueSinkEventArgs> SinkDisconnected
Event Type
Type Description
EventHandler<QueueSinkEventArgs>
Remarks

The function is executed on the thread that calls StreamStop().

Implements