Class QueueSink

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

Inheritance

object

HandleObject

Sink

QueueSink

Implements

IDisposable

Inherited Members

Sink.IsAttached

Sink.Mode

HandleObject.Dispose(bool)

HandleObject.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

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.

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 than`0`
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.

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 than`0`
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

Sink.Type

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.

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

IDisposable