Microsoft DirectX 8.0 |
Sets and retrieves envelope-following parameters on an object.
To reduce overhead, parameters are referenced by index value, and all parameter values are 32 bits, defined as type MP_DATA. Use the IMediaParamInfo interface to determine whether a given parameter is an integer, floating-point value, Boolean value, or member of an enumerated type.
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMediaParams methods Description GetParam Retrieves the most recent value of the specified parameter. SetParam Sets the value of a parameter. AddEnvelope Adds an envelope to a parameter. FlushEnvelope Flushes envelope data for a specified parameter over the specified time range. SetTimeFormat Specifies the time format for the object.
Retrieves the current value of the specified parameter. If the parameter is currently within an envelope segment, the returned value is the value on the most recently processed sample.
Syntax
HRESULT GetParam( DWORD dwParamIndex, MP_DATA *pValue );
Parameters
- dwParamIndex
- [in] Zero-based index of the parameter.
- pValue
- [out] Pointer to a variable of type MP_DATA that receives the parameter value.
Return Value
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_INVALIDARG Index out of range. E_POINTER NULL pointer argument.
Remarks
To enumerate the parameters supported by this object, along with their index values, use the IMediaParamInfo interface.
Sets the value of a parameter.
Syntax
HRESULT SetParam( DWORD dwParamIndex, MP_DATA value );
Parameters
- dwParamIndex
- [in] Zero-based index of the parameter, or DWORD_ALLPARAMS to apply the value to every parameter.
- value
- [in] New value of the parameter.
Return Value
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_INVALIDARG Index out of range, or illegal parameter value.
Remarks
If the parameter is currently within an envelope segment, the envelope segment will overwrite the new value. To remove an envelope segment, call the FlushEnvelope method.
To enumerate the parameters supported by this object, along with their index values, use the IMediaParamInfo interface.
Adds an envelope to a parameter.
Syntax
HRESULT AddEnvelope( DWORD dwParamIndex, DWORD cPoints, MP_ENVELOPE *pEnvelope, );
Parameters
- dwParamIndex
- [in] Zero-based index of the parameter, or DWORD_ALLPARAMS to add the envelope to every parameter.
- cPoints
- [in] Number of segments in the envelope.
- pEnvelope
- [in] Pointer to an array of MP_ENVELOPE structures that define the envelope segments. The size of the array is given in the cPoints parameter.
Return Value
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_INVALIDARG Index out of range. E_OUTOFMEMEORY Insufficient memory. E_POINTER NULL pointer argument.
Remarks
If the envelope overlaps an existing envelope, the new envelope takes precedence.
To enumerate the parameters supported by this object, along with their index values, use the IMediaParamInfo interface.
Flushes envelope data for a specified parameter over the specified time range.
Syntax
HRESULT FlushEnvelope( DWORD dwParamIndex, REFERENCE_TIME refTimeStart, REFERENCE_TIME refTimeEnd );
Parameters
- dwParamIndex
- [in] Zero-based index of the parameter, or DWORD_ALLPARAMS to flush envelope data from every parameter.
- refTimeStart
- [in] Start time of the envelope data to flush.
- refTimeEnd
- [in] Stop time of the envelope data to flush.
Return Value
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_INVALIDARG Index out of range.
Remarks
If the time span specified by refTimeStart and refTimeEnd overlaps an envelope segment, the entire segment is flushed. On the other hand, if it falls on the boundary of an envelope segment, the entire segment is retained. Thus:
- If the start time falls inside an envelope segment, the segment is flushed.
- If the end time falls inside an envelope segment, the segment is flushed.
- If the start time equals the end time of an envelope segment, the segment is retained.
- If the end time equals the start time of an envelope segment, the segment is retained.
To enumerate the parameters supported by this object, along with their index values, use the IMediaParamInfo interface.
Specifies the time format for the object.
Syntax
HRESULT SetTimeFormat( GUID guidTimeFormat, MP_TIMEDATA mpTimeData );
Parameters
- guidTimeFormat
- [in] Time format GUID that specifies the time format.
- mpTimeData
- [in] Value of type MP_TIMEDATA that specifies the unit of measure for the new format.
Return Value
Returns an HRESULT value. Possible values include the following.
S_OK Success. E_DMOTIMESTAMPFORMAT Object does not support this time format.
Remarks
Objects can support more than one time format. Every object must support reference time, in which each unit of time is 100 nanoseconds (ns). Other formats are optional. The application must ensure that time stamps on the input buffers match whatever time format was set using this method.
The meaning of the mpTimeData parameter depends on the value of the guidTimeFormat parameter:
Time Format Meaning of Time Data GUID_TIME_REFERENCE Ignored. GUID_TIME_MUSIC Parts per quarter note. GUID_TIME_SAMPLES Samples per second. When you call this method, you should also call the FlushEnvelope method, to flush any envelopes that were set using the previous time format.
To determine what time formats an object supports, call the IMediaParamInfo::GetSupportedTimeFormat method. To retrieve the current format, call the IMediaParamInfo::GetCurrentTimeFormat method.