VCDProperties

VCD Properties provide a generic, hardware independent and extendable way to control the settings of a video capture device.

Introduction

DirectShow defines two sub sets of properties for video capture devices: VideoProcAmp and CameraControl. There is only one scalar data type ( long ) defined to represent a property value. Although this concept is an abstraction that allows you to write device independent code, there are two problems:

Some video capture devices provide more properties than the ones defined by DirectShow.
If the values of some properties such as "exposure" are mapped to a "long", the meaning of the value gets lost. With regard to "exposure" the question is for example: which value corresponds to 1/20.000 sec? There is an approach in DirectShow to overcome this problem with negative values. The value -2, for example, means 2 to the power of -2, which is 1/4 seconds. These negative values are called "physical values" because they have a physical meaning (in this case in terms of seconds). There is one problem with this approach, it suffers from inaccuracy. There is no way to specify 1/3 second as an exposure time in "physical values". There is the same problem with the properties "iris" and "zoom".

On one hand, the new VCD properties provide interfaces that allow property values to manipulated in terms of physical dimensions, such as seconds. On the other hand, these interfaces provide high precision. For all who are happy with the simple and somehow restricted way of accessing properties provided by earlier versions of IC Imaging Control, there is a helper class called VCDSimpleProperty. This class allow old code to be ported with minimum effort. If this class is used, the benefits of the new VCD properties are not available.

Basic concepts

VCD properties are organized in a tree structure. In order to understand this, we have to consider the elements of which a property consists. First of all, a property has a name, such as "exposure". In addition, it contains elements, such as the value and an automation state. Therefore, we may say that a property is an object that contains a name and a set of elements. This object is called VCDPropertyItem. The elements are called VCDPropertyElement and contain a set of interfaces that allow to manipulate the element. The interfaces provide different access methods to the property. The interface VCDRangeProperty, for example, provides access to the property that is equivalent to the property access of DirectShow. The VCDAbsoluteValueProperty allows the property to be accessed in terms of a physical dimension with high accuracy. After this consideration, the structure of VCD property is clear: The property item contains property elements, which contain one or more interfaces. In order to be able to manipulate a property, you have to retrieve the appropriate item, element and interface. Please open the application "VCD Property Inspector" from the IC Imaging Control start menu entry, in order to get an idea on how the VCD properties are organized for your device.

Finding Property objects

First of all, we need a way to specify a property item, element or interface in order to be able to find it. There are GUIDs (Global Unique IDentifiers) for every property item, element and interface defined in the module VCDPropertyIDs. These GUIDs should be used in the VCD property's find methods. All property items that are supported by the currently active video capture device are contained in the VCDPropertyItems collection. This collection provides methods for retrieving a property item, element or interface. They are called VCDPropertyItems.FindItem, VCDPropertyItems.FindElement and VCDPropertyItems.FindInterface. The object to be retrieved has to specified by a single GUID for FindItem and a combination of GUIDs for the other two. In the following, we will call the GUID or combination of GUIDs that specifiy a property object, a GUID path.

Finding Interfaces

As described earlier, an interface is the object that actually allows data to be read from and written to a property. As described in the previous section, we use the GUID path for the desired interface as a parameter to VCDPropertyItems.FindInterface in order to retrieve the interface. Before we do this, we will have to decide which interface we want to use. In case of an auto item ( VCDPropertyElement, GUID: VCDElement_Auto) we will try to retrieve a switch interface ( VCDSwitchProperty, GUID: VCDInterface_Switch) because a switch is the expected functionality of the auto item. In case of the value item - the actual value of the property - we have to search for the best interface. The best or most advanced interface is the absolute value interface ( refer to VCDAbsoluteValueProperty for details).

As described at the beginning, the absolute values interface provide high accuracy and a meaning of the value it represents. The following code retrieves the absolute value interface for the value element of the exposure property item:

' Declare an absolute value interface
Dim AbsValItf As VCDAbsoluteValueProperty

' Retrieve an absolute value interface for exposure
Set AbsValItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDID_Exposure + ":" +_
	   														     VCDElement_Value + ":" + _
															     VCDInterface_AbsoluteValue )

If Not AbsValItf Is Nothing Then
    ' Interface successfully retrieved ...
Else
    ' There is no absolute value interface for the value element
    ' of the exposure property item.
End If

If the absolute values interface does not exist for this property, we try to retrieve the map strings interface ( VCDMapStringsProperty, GUID: VCDInterface_MapStrings). It is not as accurate as the absolute values interface, but it provides a meaning for the value. The following code retrieves the map strings interface for the value element of the exposure property item:

' Declare a map strings interface
Dim MapStringsItf As VCDMapStringsProperty

' Retrieve a map strings interface for exposure
Set MapStringsItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDID_Exposure + ":" + _
	   														     VCDElement_Value + ":" + _
															     VCDInterface_MapStrings )

If Not MapStringsItf Is Nothing Then
    ' Interface successfully retrieved ...
Else
    ' There is no map strings interface for the value element
    ' of the exposure property item.
End If

If the map strings interface does not exist for this property, we try to retrieve the range interface ( VCDRangeProperty, GUID: VCDInterface_Range). This interface does not provide a meaning for the value, but it may provide more values than the map strings interface. The following code retrieves the range interface for the value element of the exposure property item:

' Declare a range interface
Dim RangeItf As VCDRangeProperty

' Retrieve a range interface for exposure
Set RangeItf = ICImagingControl1.VCDPropertyItems.FindInterface( VCDID_Exposure + ":" + _
	   														     VCDElement_Value + ":" + _
															     VCDInterface_Range )

If Not RangeItf Is Nothing Then
    ' Interface successfully retrieved ...
Else
    ' There is no range interface for the value element
    ' of the exposure property item.
End If

Using Interfaces

In the previous section we learned how to get an interface. Now we will discuss how use them in order to get information about the property and manipulate the value. All interfaces provide the following properties:

Available: Indicates whether this interface is currently available. For example, interfaces for the trigger property item may not be available while the image stream is running.
ReadOnly: Indicates whether a value may be assigned to the Value of the interface.
Default: Is the default value.
Value: The Value of the interface.

The absolute values and the range interface provide properties to get information about the minimum, maximum value that can be assigned to the actual value. The absolute values interface provides additional information about the physical dimension of the value. The map strings interface provides a collection of strings, which build the set of possible values that may be assigned to the actual value.

If the absolute values interface could be retrieved, the code for accessing the interface looks as follows:

' AbsValItf is a valid absolute value interface for exposure
If AbsValItf.Available Then
    ' Set the current value to the average
    AbsValItf.Value = ( AbsValItf.RangeMin + AbsValItf.RangeMax ) / 2
End If

If the map strings interface could be retrieved, the code for accessing the interface looks as follows:

' MapStringsItf is a valid map string interface for exposure
If MapStringsItf.Available Then
    ' Set the current value to the average
    MapStringsItf.Value = ( MapStringsItf.RangeMin + MapStringsItf.RangeMax ) / 2
End If

If only the range interface could be retrieved, the code for accessing the interface looks as follows:

' RangeItf is a valid range interface for exposure
If RangeItf.Available Then
    ' Set the current value to the average
    RangeItf.Value = ( RangeItf.RangeMin + RangeItf.RangeMax ) / 2
End If

Serialization of property values

The VCDPropertyItems collection provides a method called VCDPropertyItems.Save that serializes the current state of all VCD properties of the currently selected device into a string. The property values are stored in XML format. Therefore, it is easy to store the string in the registry or a file for later restore operations. Please note that the XML representation is not documented and may change without notice. The method for restoring all property values is called VCDPropertyItems.Load.

<< Technical Articles