Basic Use of VCD Properties

This chapter illustrates the basic functionality of the VCDProperties. It shows you how to retrieve interfaces which allow you to manipulate elements, such as the value or the automation state of a property.

Introduction

This sample uses the "Brightness" property to demonstrate how the properties are organized and how they are accessed. First, the VCDPropertyItem for "Brightness" is retrieved from the VCDPropertyItems collection. Then a switch and a range interface is retrieved from the respective elements of this VCDPropertyItem. The switch interface is used to turn the automation state of this property on and off. The range interface is used to manipulate the value of this property.

The source code for C# version of this sample program can be found in samples\C# *\BrightnessProperty in your My Documents/IC Imaging Control 3.5 directory.

Creating the Project

Create a new project and add IC Imaging Control to the form. Before you run the program, select the video device, input and video format as shown in the First Steps Visual Studio .NET 2010 chapter. Alternatively, run the program without selecting a device. In this case, the program shows the device selection dialog that ships with IC Imaging Control. If you close this dialog without selecting a device, the program displays an error message and terminates.

Now add a check box and a slider (or 'trackbar') to the form. Name the check box chkBrightnessAuto and the slider sldBrightness.

Retrieving a VCDPropertyItem

After a valid video capture device has been selected, the VCDPropertyItem for "Brightness" is retrieved:

[C#]
TIS.Imaging.VCDPropertyItem brightness = icImagingControl1.VCDPropertyItems.FindItem( TIS.Imaging.VCDGUIDs.VCDID_Brightness );

Just declare a variable of type VCDPropertyItem and use the VCDPropertyItems.FindItem method to assign the appropriate property. The property item that should be retrieved must be specified by its ID as mentioned above. In this case, it is VCDID_Brightness for the "Brightness" property item.

Retrieving Interfaces and Initialize the Controls

Properties consist of one or more elements like the value, automation state, one push operation and further parameters, if supported. To manipulate a property, interfaces are used. They can be retrieved from the elements of a property item. Declare 2 global variables that will hold the interfaces to the value and the automation state:

[C#]
private TIS.Imaging.VCDRangeProperty _brightnessRange;
private TIS.Imaging.VCDSwitchProperty _brightnessSwitch;

The following code shows you how to actually retrieve a switch and a range interface and how to get their current states in order to initialize the associated user controls.

[C#]
// Acquire interfaces to the range and switch interface for value and auto
_brightnessRange = brightness.Find<TIS.Imaging.VCDRangeProperty>( TIS.Imaging.VCDGUIDs.VCDElement_Value );
_brightnessSwitch = brightness.Find<TIS.Imaging.VCDSwitchProperty>( TIS.Imaging.VCDGUIDs.VCDElement_Auto );
if( _brightnessSwitch == null )
{
    MessageBox.Show( "Automation of brightness is not supported by the current device!" );
}

The VCDPropertyItem.Find generic parameter is used to retrieve a specific interface type.

Now that the we have the interfaces, the user controls can be initialized. The following code shows you how this is done:

[C#]
// Initialize the slider with the current range and value of the
// BrightnessRange object.
sldBrightness.Enabled = true;
sldBrightness.Minimum = _brightnessRange.RangeMin;
sldBrightness.Maximum = _brightnessRange.RangeMax;
sldBrightness.Value = _brightnessRange.Value;
// Initialize the checkbox with the BrightnessSwitch object
if( _brightnessSwitch != null )
{
    chkBrightnessAuto.Enabled = true;
    sldBrightness.Enabled = !_brightnessSwitch.Switch;
    chkBrightnessAuto.Checked = _brightnessSwitch.Switch;
}
icImagingControl1.LiveStart();

As the code above shows, the interfaces let you easily access the range and values of a property element.

Manipulating the elements of a Property

In this final step, we want to show you how to use the interfaces to manipulate a property. Add a Click event for the check box and a Scroll event for the slider. The check box toggles the automation state of the "Brightness" property. The code looks as follows:

[C#]
private void chkBrightnessAuto_CheckedChanged( object sender, EventArgs e )
{
    _brightnessSwitch.Switch = chkBrightnessAuto.Checked;
    sldBrightness.Enabled = !chkBrightnessAuto.Checked;
}

The code above just assigns the current state of the check box to the automation element of the "Brightness" property. Additionally, the slider will be disabled, if the automation state is on.

The code for the Scroll event of the slider is even simpler:

[C#]
private void sldBrightness_Scroll( object sender, EventArgs e )
{
    _brightnessRange.Value = sldBrightness.Value;
}

Now you can run the program and manipulate the "Brightness" property, using the slider and the check box.

<< Programmer's Guide