FrameQueueSink

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

The sink is created by calling FrameQueueSink::create, and requires a reference to an instance of a class derived from FrameQueueSinkListener. 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 FrameQueueBuffers:

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 by calling getInputQueueSize.

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 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 by calling getFrameCountInfo.

Buffers can be extracted from the output queue by calling popOutputQueueBuffer or popAllOutputQueueBuffers. The current length of the output queue can be queried by calling getOutputQueueSize.

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 FrameQueueSinkListener::sinkConnected method is called when the sink image format has been decided during the call to Grabber::startLive or Grabber::prepareLive. 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 FrameQueueSinkListener::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.

The FrameQueueSinkListener::sinkDisconnected method is called when the device is stopped during a call to Grabber::stopLive.

Sink state changes

When Grabber::prepareLive or Grabber::startLive is called:

The sink clears its output queue and its input buffer queue so that this sink.getInputQueueSize() == 0 and sink.getOutputQueueSize() == 0.
The sink negotiates its output frame type and then connects inside the Graph.
The sink calls the user-supplied FrameQueueSinkListener::sinkConnected.

When the actual streaming begins:

When the sink receives a new image and getInputQueueSize() > 0, a buffer is dequeued and the image is copied into the FrameQueueBuffer. The internal copied counter is incremented.
After copying the frame, a thread is woken up and it then calls the user-supplied FrameQueueSinkListener::framesQueued.
When the sink receives a new image and getInputQueueSize() == 0 the internal drop counter is incremented.

When Grabber::stopLive 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 FrameQueueSinkListener::framesQueued returns.
The sink calls FrameQueueSinkListener::sinkDisconnected.
When this returns, the sink clears its input buffer queue so that sink.getInputQueueSize() == 0.
Filled buffers will remain in the output queue; this queue is not cleared until grabber.startLive is called again.

Information

    Header File: tisudshl.h
    Namespace: DShowLib
    Introduced in version 3.5

Inheritance

GrabberSinkType
FrameQueueSink

Methods

	Method		Description


	allocAndQueueBuffers		This function creates a number of buffers and puts them into the input queue.

	create		Creates a new FrameQueueSink.

	getFrameCountInfo		Fetches the FrameCountInfo from the sink.

	getInputQueueSize		Returns the current count of FrameQueueBuffer objects in the input queue.

	getOutputFrameType		Retrieves the FrameTypeInfo of the current connection.

	getOutputQueueSize		Returns the current count of FrameQueueBuffer objects in the output queue.

	isCancelRequested		Returns true when Grabber::stopLive was called. The sink is required to halt operation and return from any callbacks as soon as possible.

	isConnected		Returns if the sink is currently connected.

	popAllInputQueueBuffers		Fetches all FrameQueueBuffer instances from the input queue and returns them.

	popAllOutputQueueBuffers		Fetches all currently available FrameQueueBuffer instances from the output queue and returns them.

	popOutputQueueBuffer		Fetches a single FrameQueueBuffer from the output queue and returns it.

	queueBuffer		Queues one or more FrameQueueBuffer objects into the input queue of the FrameQueueSink .

Structs

	Struct		Description


	FrameCountInformation		Frame count information from the sink.

<< Classes