FrameQueueSink

The FrameQueueSink is the preferred sink if the application's task requires processing all frames in a video stream.

The sink is created by calling its constructor, and requires a reference to a class implementing IFrameQueueSinkListener, or a function object that gets called for every received frame. The listener's methods are called when an image becomes available for processing, or when the sink's state changes.

Buffer Handling

The sink internally manages two queues of IFrameQueueBuffers:

An input queue of free buffers
An output queue of filled buffers

Buffers are put into the input queue by calls to AllocAndQueueBuffers or QueueBuffer. The current length of the input queue can be queried through InputQueueSize.

When the FrameQueueSink receives an image from the device, it takes a buffer from the input queue, copies the image data into it, and places it at the end of the output queue. If the input queue is empty at the time when the sink receives an image, the image will be dropped. Information about the number of frames copied or dropped by the sink can be queried through CountOfFramesCopied and CountOfFramesDropped.

Buffers can be extracted from the output queue by calling PopOutputQueueBuffer or PopAllOutputQueueBuffers. The current length of the output queue can be queried through OutputQueueSize.

To avoid frames being dropped by the sink, the application has to ensure that there are buffers available in the input queue at any time. It is therefore imperative to re-queue buffers that have been extracted from the output queue after they have been processed.

Sink Events

The IFrameQueueSinkListener.SinkConnected method is called when the sink image format has been decided during the call to ICImagingControl.LiveStart or ICImagingControl.LivePrepare. It can be used to allocate buffers in the correct format and enqueue them before the first images are received from the video capture device.

The IFrameQueueSinkListener.FramesQueued method is called each time after a frame has been filled with image data and copied to the output queue. If one more frame is added to the output queue during the execution of the callback, the callback is called again immediately after it returns.

The IFrameQueueSinkListener.SinkDisconnected method is called when the device is stopped during a call to ICImagingControl.LiveStop.

Note: All sink events get called in arbitrary thread contexts.

Sink state changes

When ICImagingControl.LiveStart or ICImagingControl.LivePrepare is called:

The sink clears its output buffer queue and its input buffer queue so that sink.InputQueueSize == 0 and sink.OutputQueueSize == 0.
The sink negotiates the sink's output frame type and then connects inside the Graph.
The sink calls the user-supplied IFrameQueueSinkListener.SinkConnected.

When the actual streaming begins:

When the sink receives a new image and InputQueueSize > 0, a buffer is dequeued and the image is copied into the IFrameQueueBuffer. The internal copied counter is incremented.
After copying the frame, a thread is woken up and it then calls the user-supplied IFrameQueueSinkListener.FramesQueued.
When the sink receives a new image and InputQueueSize == 0 the internal drop counter is incremented.

When ICImagingControl.LiveStop is called

The sink stops accepting images from the camera.
When called, sink.IsCancelRequested() from returns true.
The sink waits until a possible currently executing call to IFrameQueueSinkListener.FramesQueued returns.
The sink calls IFrameQueueSinkListener.SinkDisconnected.
When this returns, the sink clears its input buffer queue so that sink.InputQueueSize == 0.
Filled buffers will remain in the output queue; this queue is not cleared until LiveStart or LivePrepare is called again.

Using a function object instead of a listener

When the sink is created with a function object of type FrameQueuedResult FuncName( IFrameQueueBuffer img ), the passed in function object gets called for every frame copied and receives a IFrameQueueBuffer object.

The callee then can either do its work on the buffer itself, and return FrameQueuedResult.ReQueue or queue the buffer into something and return FrameQueuedResult.SkipReQueue to indicate that the buffer should not be queued back into the input queue of the sink.

Note: The output queue is popped by the thread calling the function object. (So it will not contain any buffers which were passed to the function object).
Note: The function object gets called in an arbitrary thread context.

Information

Namespace: TIS.Imaging
Introduced in version 3.5

Inheritance

BaseSink
FrameQueueSink

Properties

	Property		Description


	CountOfFramesCopied		Returns the number of frames that were copied into this sink's output queue.

	CountOfFramesDropped		Returns the number of frames that were dropped by the sink due to a lack of buffers in the input queue.

	InputQueueSize		Returns the current count of IFrameQueueBuffer instances held in the queued (or free) list.

	IsCancelRequested		Returns true if the Sink is currently transitioning into stopped state.

	OutputFrameType		Returns the FrameType of the IFrames used by this sink.

	OutputQueueSize		Returns the current count of IFrameQueueBuffer instances held in the output (or filled) list.

Methods

	Method		Description


	AllocAndQueueBuffers		Allocates and queues one or more IFrameQueueBuffers into the queued buffer list.

	FrameQueueSink		Creates a new FrameQueueSink.

	PopAllInputQueueBuffers		Returns all buffers in the input queue and sets the internal list to empty.

	PopAllOutputQueueBuffers		Returns all buffers in the output queue and sets the internal list to empty.

	PopOutputQueueBuffer		Returns one IFrameQueueBuffer from the copied buffer list.

	QueueBuffer		Queues one or more IFrameQueueBuffers into the queued buffer list.

<< Classes