Microsoft DirectX 8.0

IPropertySetter Interface

Sets properties on an effect or transition in Microsoft® DirectShow® Editing Services (DES).

To use this interface, create an instance of a property setter object (CLSID_PropertySetter), and associate it with an effect or transition by calling the IAMTimelineObj::SetPropertySetter method. For more information, see Working with Effects and Transitions.

Usually an application needs to call only the ClearProps method to clear existing properties, and the AddProp method to add new properties. The other methods on this interface are called by other DES components.

Requirements

Requires Qedit.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IPropertySetter MethodsDescription
LoadXMLLoads property data expressed in Extensible Markup Language (XML).
PrintXMLConverts property data into an XML string.
ClonePropsClones a set of properties from this property setter and adds them to a new property setter.
AddPropAdds a property to the property setter, with an array of time-value pairs defining the value of the property over a range of time.
GetPropsRetrieves the properties set on this object, with their corresponding values.
FreePropsFrees resources allocated by the GetProps method.
ClearPropsClears all property data from the property setter.
SaveToBlobSaves the property data to a persistence format.
LoadFromBlobLoads property data from a persistence format.
SetPropsSets the properties of the target object to the appropriate state for the specified time.

IPropertySetter::AddProp

IPropertySetter Interface

Adds a property to the property setter, with an array of time-value pairs defining the value of the property over a range of time.

Syntax

HRESULT AddProp(
    DEXTER_PARAM Param,
    DEXTER_VALUE *paValue
);

Parameters

Param
[in] DEXTER_PARAM structure that specifies the property. The nValues member of the structure must equal the size of the array given in the paValue parameter.
paValue
[in] Pointer to an array of DEXTER_VALUE structures that contain time-value pairs. The array must be in ascending time order. The times are relative to the starting time of the effect or transition.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_INVALIDARGInvalid argument.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.

Remarks

The first DEXTER_VALUE structure must specify a reference time of zero and an interpolation flag (dwInterp) of DEXTERF_JUMP, or the method returns an error.

IPropertySetter::ClearProps

IPropertySetter Interface

Clears all property data from the property setter. The application can set new property data after calling this function.

Syntax

HRESULT ClearProps( void );

Return Value

Returns S_OK.

IPropertySetter::CloneProps

IPropertySetter Interface

Clones a set of properties from this property setter and adds them to a new property setter.

Syntax

HRESULT CloneProps(
    IPropertySetter **ppSetter,
    REFERENCE_TIME rtStart,
    REFERENCE_TIME rtStop
);

Parameters

ppSetter
[out] Address of a pointer to receive the IPropertySetter interface of the new property setter.
rtStart
[in] Start time of the range of values to clone, in 100-nanosecond units.
rtStop
[in] Reserved.

Return Value

Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error. Possible error codes include the following:

E_INVALIDARGInvalid argument.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.

Remarks

Only values that fall after the specified start time are cloned. The times on the cloned values are then adjusted relative to the start time. For example, if rtStart is 20000000 (2 seconds), then a value at time 30000000 (3 seconds) is cloned with time 10000000 (1 second). Finally, each cloned property is given an initial value equal to the value of the original property at the start time (correctly interpolated if necessary). In effect, the property data is split at the specified start time.

If the method succeeds, the IPropertySetter interface that it returns has an outstanding reference count. Be sure to release the interface when you are finished using it.

IPropertySetter::FreeProps

IPropertySetter Interface

Frees resources allocated by the GetProps method. Call this method after calling GetProps, passing it the structures returned by GetProps.

Syntax

HRESULT FreeProps(
    LONG cParams,
    DEXTER_PARAM *paParam,
    DEXTER_VALUE *paValue
);

Parameters

cParams
[in] Value that specifies the size of the array given in the paParam parameter.
paParam
[in] Pointer to an array of DEXTER_PARAM structures.
paValue
[in] Pointer to an array of DEXTER_VALUE structures.

Return Value

Returns S_OK.

IPropertySetter::GetProps

IPropertySetter Interface

Retrieves the properties set on this object, with their corresponding values.

Syntax

HRESULT GetProps(
    LONG *pcParams,
    DEXTER_PARAM **paParam,
    DEXTER_VALUE **paValue
);

Parameters

pcParams
[out] Pointer to a variable that receives the number of structures returned in paParam.
paParam
[out] Address of a pointer to an array of DEXTER_PARAM structures.
paValue
[out] Address of a pointer to an array of DEXTER_VALUE structures.

Return Value

Returns one of the following HRESULT values:

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.

Remarks

For each property returned in paParam, the nValues member indicates the number of DEXTER_VALUE structures associated with the property. The pairs are returned in ascending time order for each property.

For example, the following code fragment shows how to iterate through all the values:

DEXTER_PARAM *pParam;
DEXTER_VALUE *pValue;
LONG count;

hr = pSetter->GetProps(&count, &pParam, &pValue);

LONG num = 0;
for (LONG i = 0; i < count; i++)
{
    for (LONG j = 0; j < pParam[i].nValues; j++)
    {
        // pValue[num] is the next value in the sequence for pParam[i]
    }
    num += pParam[i].nValues;
}

When you are finished using the returned structures, call FreeProps to free the resources allocated by this method.

IPropertySetter::LoadFromBlob

IPropertySetter Interface

Loads property data from a persistence format.

Syntax

HRESULT LoadFromBlob(
    LONG cSize,
    BYTE *pb
);

Parameters

cSize
[in] Size of the data, in bytes.
pb
[in] Pointer to an array of bytes that contains the data.

Return Value

Returns S_OK if successful. Otherwise, returns E_OUTOFMEMORY or another error code.

IPropertySetter::LoadXML

IPropertySetter Interface

Loads property data expressed in Extensible Markup Language (XML).

Syntax

HRESULT LoadXML(
    IUnknown *pxml
);

Parameters

pxml
[in] Pointer to the IUnknown interface of an XML element created by the Microsoft XML parser.

Return Value

Returns an HRESULT value. Possible values include the following.

S_FALSENo property data.
S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
VFW_E_INVALID_FILE_FORMATInvalid format.

Remarks

Typically, applications will not need to use this method. DES uses it internally to load properties from XTL files.

To use this method, create an IXMLDocument object and use it to parse an XML file. Then use the IXMLDocument object to retrieve IXMLElement objects. If the object has properties, you can pass the IXMLElement pointer to the LoadXML method. The method loads the properties into the property setter.

IPropertySetter::PrintXML

IPropertySetter Interface

Converts property data into an Extensible Markup Language (XML) string.

Syntax

HRESULT PrintXML(
    char *pszXML,
    int cbXML,
    int *pcbPrinted,
    int indent
);

Parameters

pszXML
[out] Pointer to a buffer that receives the XML string.
cbXML
[in] Size of the buffer pointed to by pszXML, in bytes.
pcbPrinted
[out] Pointer to a variable that receives the length of the XML string. Can be NULL.
indent
[in] Number of indent levels for the outermost tag.

Return Value

Returns S_OK if successful. Otherwise, returns an HRESULT value indicating the cause of the error. If the XML string is longer than the buffer, the method returns E_OUTOFMEMORY.

IPropertySetter::SaveToBlob

IPropertySetter Interface

Saves the property data to a persistence format.

Syntax

HRESULT SaveToBlob(
    LONG *pcSize,
    BYTE **ppb
);

Parameters

pcSize
[out] Pointer to a variable that receives the size of the data, in bytes.
ppb
[out] Address of a pointer to an array of bytes that receives the data.

Return Value

Returns an HRESULT value. Possible values include the following:

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.

Remarks

The method allocates memory for the byte array. The caller must free it, using the CoTaskMemFree function.

IPropertySetter::SetProps

IPropertySetter Interface

Sets the properties of the target object to the appropriate state for the specified time.

Syntax

HRESULT SetProps(
    IUnknown *pTarget,
    REFERENCE_TIME rtNow
);

Parameters

pTarget
[in] Pointer to the target object for which to set the properties.
rtNow
[in] Time at which to set the properties, in 100-nanosecond units, or –1 to set static properties (those that do not vary over time).

Return Value

Returns an HRESULT value.

Remarks

This method is called by DES to set the properties on a transition or effect. An application will not normally call this method.

The object specified by pTarget must implement the IDispatch interface.