VCD Properties provide a generic, hardware independent and extendable way to control the settings of a video capture device.
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. 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.
TO just access one specific property you can use the generic function VCDPropertyItems.Find. Just specifying the individual components and the interface type you want either gives you the according interface or null to indicate this object could not be found.
This sample code shows how to disable Auto-Exposure:
[C#]
VCDSwitchProperty exposureAuto = ICImagingControl1.VCDPropertyItems.Find<VCDSwitchProperty>(VCDGUIDs.VCDID_Exposure, VCDGUIDs.VCDElement_Auto); if( exposureAuto != null ) { exposureAuto.Switch = false; }
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 static class VCDGUIDs. 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 specify a property object, a GUID path.
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:
[C#]
// Declare an absolute value interface VCDAbsoluteValueProperty absValItf; // Retrieve the interface for exposure absValItf = ICImagingControl1.VCDPropertyItems.Find<VCDAbsoluteValueProperty>(VCDGUIDs.VCDID_Exposure, VCDGUIDs.VCDElement_Value); if( absValItf != null ) { // Interface successfully retrieved ... } else { // There is no according interface for the this element of this property item. }
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:
[C#]
// Declare this interface VCDMapStringsProperty mapStringsItf; // Retrieve the interface for exposure mapStringsItf = ICImagingControl1.VCDPropertyItems.Find<VCDMapStringsProperty>(VCDGUIDs.VCDID_Exposure, VCDGUIDs.VCDElement_Value); if( mapStringsItf != null ) { // Interface successfully retrieved ... } else { // There is no according interface for the this element of this property item. }
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:
[C#]
// Declare this interface VCDRangeProperty rangeItf; // Retrieve the interface for exposure rangeItf = ICImagingControl1.VCDPropertyItems.Find<VCDRangeProperty>(VCDGUIDs.VCDID_Exposure, VCDGUIDs.VCDElement_Value); if( rangeItf != null ) { // Interface successfully retrieved ... } else { // There is no according interface for the this element of this property item. }
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:
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:
[C#]
if( absValItf != null && absValItf.Available ) { absValItf.Value = (absValItf.RangeMin + absValItf.RangeMax) / 2; }
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 in a future version. The method for restoring all property values is called VCDPropertyItems.Load.