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 "Brightness" property to demonstrate how the properties are organized and how they are accessed. First, the IVCDPropertyItem for "Brightness" is retrieved from the IVCDPropertyItems collection (for details refer to Grabber::getAvailableVCDProperties ). Then a switch and a range interface are retrieved from the respective elements of this IVCDPropertyItem. The switch interface is used to toggle 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 this sample program can be found in the %TOPLEVEL%\samples\VC71\VCD Simple sample source directory. A VC6 version can be found in the directory %TOPLEVEL%\Samples\VC6.

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_BRIGHTNESS_CHECK and the slider IDC_BRIGHTNESS_SLIDER. To display the live video add a static text control to the dialog and give it the ID IDC_DISPLAY.

Retrieving a VCDPropertyItem

After a valid video capture device has been selected, the IVCDPropertyItem for "Brightness" is retrieved. This is done in the InitPropertyControls method, which is called by the OnInitDialog method:

tIVCDPropertyItemsPtr pItems = m_Grabber.getAvailableVCDProperties();
if( pItems != 0 )
{
    // Try to find the brightness item
    tIVCDPropertyItemPtr pBrightnessItem = pItems->findItem( VCDID_Brightness );

Just declare a variable pItems of type tIVCDPropertyItemsPtr which will hold the available VCD Properties. Then declare a variable pBrightnessItem of type tIVCDPropertyItemPtr and use the findItem method to assign the appropriate property. The property item that should be retrieved must be specified by its item ID (or GUID). 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 such as 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. Add 2 member variables to the CVCDSimpleDlg class that will hold the interfaces to the value and the automation state:

DShowLib::tIVCDRangePropertyPtr        m_pBrightnessRange;
DShowLib::tIVCDSwitchPropertyPtr    m_pBrightnessAuto;

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.

tIVCDPropertyElementPtr pBrightnessValueElement = pBrightnessItem->findElement( VCDElement_Value );
tIVCDPropertyElementPtr pBrightnessAutoElement =  pBrightnessItem->findElement( VCDElement_Auto );
 
// If a value element exists, try to acquire a range interface
if( pBrightnessValueElement != 0 )
{
    pBrightnessValueElement->getInterfacePtr( m_pBrightnessRange );
}
 
// If an auto element exists, try to acquire a switch interface
if( pBrightnessAutoElement != 0 )
{
    pBrightnessAutoElement->getInterfacePtr( m_pBrightnessAuto );
 
    // If successful, disable automation
    if( m_pBrightnessAuto != 0 )
        m_pBrightnessAuto->setSwitch( false );
}

The interface is retrieved in 2 steps. In the first step, the appropriate element that should be manipulated is retrieved. This is done using the IVCDPropertyItem::findElement method. In the second step, the desired interfaces are retrieved from the respective elements. This is done using the IVCDPropertyElement::getInterfacePtr method, which returns a reference to the specified interface.

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 brightness value
if( m_pBrightnessRange != 0 )
{
    m_BrightnessSlider.EnableWindow();
 
    // Set the slider range
    int delta = m_pBrightnessRange->getDelta();
    m_BrightnessSlider.SetRangeMin( m_pBrightnessRange->getRangeMin() / delta );
    m_BrightnessSlider.SetRangeMax( m_pBrightnessRange->getRangeMax() / delta );
 
    // Set the slider position
    m_BrightnessSlider.SetPos( m_pBrightnessRange->getValue() / delta );
}
else
{
    m_BrightnessSlider.EnableWindow( FALSE );
}
 
// Check whether we were able to acquire a switch interface to brightness auto
if( m_pBrightnessAuto != 0 )
{
    m_BrightnessAutoCheck.EnableWindow();
 
    m_BrightnessAutoCheck.SetCheck( m_pBrightnessAuto->getSwitch() );
}
else
{
    m_BrightnessAutoCheck.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 "Brightness" property. The code looks as follows:

if( m_BrightnessAutoCheck.GetCheck() )
{
    m_BrightnessSlider.EnableWindow( FALSE );
    m_pBrightnessAuto->setSwitch( true );
}
else
{
    m_BrightnessSlider.EnableWindow();
    m_pBrightnessAuto->setSwitch( false );
}

The code above just assigns the current state of the check box to the automation element of the "Brightness" 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_pBrightnessRange->getDelta();
m_pBrightnessRange->setValue( m_BrightnessSlider.GetPos() * delta );

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

<< Programmer's Guide