Microsoft DirectX 8.0 |
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IPropertySetter Methods Description LoadXML Loads property data expressed in Extensible Markup Language (XML). PrintXML Converts property data into an XML string. CloneProps Clones a set of properties from this property setter and adds them to a new property setter. AddProp 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. GetProps Retrieves the properties set on this object, with their corresponding values. FreeProps Frees resources allocated by the GetProps method. ClearProps Clears all property data from the property setter. SaveToBlob Saves the property data to a persistence format. LoadFromBlob Loads property data from a persistence format. SetProps Sets the properties of the target object to the appropriate state for the specified time.
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_OK Success. E_INVALIDARG Invalid argument. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL 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.
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.
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_INVALIDARG Invalid argument. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL 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.
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.
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_OK Success. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL 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.
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.
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_FALSE No property data. S_OK Success. E_OUTOFMEMORY Insufficient memory. VFW_E_INVALID_FILE_FORMAT Invalid 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.
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.
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_OK Success. E_OUTOFMEMORY Insufficient memory. E_POINTER NULL pointer argument.
Remarks
The method allocates memory for the byte array. The caller must free it, using the CoTaskMemFree function.
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.