Basic Use of VCD Properties

This chapter describes 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 gain property to demonstrate how the properties are organized and how they are accessed. The example uses the range interface to access the value of gain, and the switch interface to control auto gain.

The source code for this sample program can be found in the %TOPLEVEL%\samples\VC10\VCD Simple sample source directory.

Creating the Project

The sample program of this chapter is a dialog based application. To set up such a project, follow the steps as described in the FirstSteps chapter. This sample is very similar, however it is a "Dialog based" type of application instead of a "Single Document" type as described in the FirstSteps.

Now, add a check box and a slider to the form. Give the check box the ID IDC_GAIN_CHECK and the slider IDC_GAIN_SLIDER. To display the live video add a static text control to the dialog and give it the ID IDC_DISPLAY.

Querying VCD Property Interfaces

Properties consist of one or more elements such as the value, automation state, one push operation and further parameters, if supported. To manipulate a property element, interfaces are used.

Add 2 member variables to the CVCDSimpleDlg class that will hold the interfaces to the gain value and the gain automation state:

DShowLib::tIVCDRangePropertyPtr        m_pGainRange;
DShowLib::tIVCDSwitchPropertyPtr    m_pGainAuto;

After a valid video capture device has been selected, the property interfaces for the gain value and automation are retrieved. This is done in the InitPropertyControls method, which is called by the OnInitDialog method:

m_pGainRange = m_Grabber.getVCDPropertyInterface<IVCDRangeProperty>( VCDID_Gain, VCDElement_Value );
m_pGainAuto = m_Grabber.getVCDPropertyInterface<IVCDSwitchProperty>( VCDID_Gain, VCDElement_Auto );
if( m_pGainAuto != NULL )
{
    m_pGainAuto->setSwitch( false );
}

Interfaces are queried using the Grabber::getVCDPropertyInterface method. The template argument specifies the type of interface to query, while the parameters specify for which property the interface should be returned.

In this example, we first query the IVCDRangeProperty interface to the gain value by passing VCDID_Gain and VCDElement_Value. Then, we query the IVCDSwitchProperty interface to the gain auto function by passing VCDID_Gain and VCDElement_Auto.

A list of possibly available features can be found in the sections Standard Property Item GUIDs and Standard Element GUIDs.

Retrieving Interfaces and Initialize the Controls

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

// Check whether we were able to acquire a range interface to gain value
if( m_pGainRange != NULL )
{
    m_GainSlider.EnableWindow();
    // Set the slider range
    int delta = m_pGainRange->getDelta();
    m_GainSlider.SetRangeMin( m_pGainRange->getRangeMin() / delta );
    m_GainSlider.SetRangeMax( m_pGainRange->getRangeMax() / delta );
    // Set the slider position
    m_GainSlider.SetPos( m_pGainRange->getValue() / delta );
}
else
{
    m_GainSlider.EnableWindow( FALSE );
}
// Check whether we were able to acquire a switch interface to gain auto
if( m_pGainAuto != NULL )
{
    m_GainAutoCheck.EnableWindow();
    m_GainAutoCheck.SetCheck( m_pGainAuto->getSwitch() );
}
else
{
    m_GainAutoCheck.EnableWindow( FALSE );
}

As the code above illustrates, the interface classes let you easily access the elements of a property item.

Manipulating the Elements of a Property

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

if( m_GainAutoCheck.GetCheck() )
{
    m_GainSlider.EnableWindow( FALSE );
    m_pGainAuto->setSwitch( true );
}
else
{
    m_GainSlider.EnableWindow();
    m_pGainAuto->setSwitch( false );
}

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

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

int delta = m_pGainRange->getDelta();
m_pGainRange->setValue( m_GainSlider.GetPos() * delta );

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

<< Programmer's Guide