Microsoft DirectX 9.0

Setting Properties on Effects and Transitions

Many effects and transitions support properties that control their behavior. An application can set the value of a property using the IPropertySetter interface. The underlying effect or transition object must support IDispatch for setting the properties. With video effects and transitions, the application can set a range of values that change over time. (For example, you can set a wipe transition to move back and forth across the frame.) With audio effects, the value of the property is static and cannot change over time. The only exception is the Volume Envelope effect, which supports a dynamic property for the volume level.

To set a property, perform the following steps.

  1. Create an instance of the property setter (CLSID_PropertySetter).
  2. Fill DEXTER_PARAM and DEXTER_VALUE structures with the property data. These structures are discussed below.
  3. Pass the DEXTER_PARAM and DEXTER_VALUE structures to the IPropertySetter::AddProp method.
  4. Repeat steps 2 and 3 for each property you want to set.
  5. Pass the IPropertySetter interface pointer to the IAMTimelineObj::SetPropertySetter method.

The DEXTER_PARAM structure specifies which property is being set. It contains the following members.

The DEXTER_VALUE structure specifies the value of a property at a given time. It contains the following members.

If you set the vt member to VT_BSTR, the property setter makes any necessary conversions. For floating-point values, include the leading zero before the decimal place. For example, 0.3, not .3.

The value of a property can change over time, so the IPropertySetter::AddProp method takes a single DEXTER_PARAM structure and a pointer to an array of DEXTER_VALUE structures. The array defines a set of time-based values for the property. The members of the array must be in ascending time order, and the nValues member of the DEXTER_PARAM structure must equal the length of the array.

The following code example creates property data for the SMPTE Wipe transition. It sets the wipe code to 120, which creates an oval wipe. It sets the reference time to zero, indicating the start of the transition.

IPropertySetter     *pProp;   // Property setter
IAMTimelineObj      *pTransObj;  // Transition object
// Create an SMPTE Wipe transition object. (Not shown)

hr = CoCreateInstance(CLSID_PropertySetter, NULL, CLSCTX_INPROC_SERVER,
    IID_IPropertySetter, (void**) &pProp);

// Error checking is omitted for clarity...


// Initialize the parameter. 
param.Name = SysAllocString(L"MaskNum");
param.dispID = 0;
param.nValues = 1;

// Initialize the value.
pValue->v.vt = VT_BSTR;
pValue->v.bstrVal = SysAllocString(L"120"); // Oval
pValue->rt = 0;
pValue->dwInterp = DEXTERF_JUMP;

pProp->AddProp(param, pValue);

// Free allocated resources.

// Set the property on the transition.

Dynamically Changing Properties

After you render a video editing project, it is possible to modify an effect or transition object's properties while the graph is running. However, this is possible only if you set properties on that object before the application called IRenderEngine::ConnectFrontEnd. If so, you can call IAMTimelineObj::GetPropertySetter on the effect or transition, clear or modify the properties, and the changes will happen dynamically as the graph is running. There may be visual anomalies while the change occurs, so this is recommended only for preview. Do not change the properties while you are writing the project to a file.

If you did not set any properties on the effect or transition object before you called ConnectFrontEnd, you cannot add properties to it while the graph is running.