Overview - the grand picture:

Devices, Properties, Video Formats and Data Buffers

To work with unicap you first need to find a suitable video capture device and acquire a handle to it. This handle is used by all functions of unicap to communicate with the device.

A device usually provides several properties. A property represents a certain functionality of the device like a brightness setting or a frame rate setting.

Also each device needs to provide at least one _Video Format_. The video format describes how the video stream data will look like. It contains the image dimensions of the video stream and the color format used. Most devices will provide different dimensions and/or color formats to choose from.

The image data coming from the device will be presented to the calling applications in _Data Buffers_. A data buffer contains the image data for one frame, a time stamp determing the time the image was taken and the video format of the image.

There are two kinds of data buffers:
system buffers and user buffers.

System buffers are allocated by the device driver and can only be accessed in callback functions called from the unicap capture thread.

User buffers are provided by the application and are put into an input queue by the application. unicap takes each buffer from this queue, fills it with image data and places it into an output queue when ready. The application reads the data buffers from this output queue and places them in the input queue again after processing.

GUI Applikations with UnicapGTK

A GUI application is generally expected to present the user a live display of the video image, controls to set the video device to use and its video format and special controls to configure device settings like brightness, contrast or exposure time.

UnicapGTK provides easy to use widgets for the GTK toolkit which handle all these tasks.

The video display widget used to display the video stream can be used in two different ways:

It can handle the whole capture process by starting and stopping the video device at appropriate times, also taking care of the data buffer handling to acquire the image data. When using the video display this way, all the user needs to do is to add the widget to the application GUI and tell the display when to start the video stream.

If the application needs more flexibility, the video display widget can also be used passively. This way, the application handles the capture process and passes only individual video frames to the video display.

Together with UCIL, an application can draw overlay images onto the video stream by connecting to the signals provided by the video display widgets.

To give the user access to the device settings, the application can either use the standard property dialog or it can easily create its own user interface by using device property widgets.