Microsoft DirectX 8.0

IMediaParams Interface

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.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
IMediaParams methodsDescription
GetParamRetrieves the most recent value of the specified parameter.
SetParamSets the value of a parameter.
AddEnvelopeAdds an envelope to a parameter.
FlushEnvelopeFlushes envelope data for a specified parameter over the specified time range.
SetTimeFormatSpecifies the time format for the object.

IMediaParams::GetParam

IMediaParams Interface

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_OKSuccess.
E_INVALIDARGIndex out of range.
E_POINTERNULL pointer argument.

Remarks

To enumerate the parameters supported by this object, along with their index values, use the IMediaParamInfo interface.

IMediaParams::SetParam

IMediaParams 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_OKSuccess.
E_INVALIDARGIndex 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.

IMediaParams::AddEnvelope

IMediaParams 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_OKSuccess.
E_INVALIDARGIndex out of range.
E_OUTOFMEMEORYInsufficient memory.
E_POINTERNULL 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.

IMediaParams::FlushEnvelope

IMediaParams 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_OKSuccess.
E_INVALIDARGIndex 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:

To enumerate the parameters supported by this object, along with their index values, use the IMediaParamInfo interface.

IMediaParams::SetTimeFormat

IMediaParams 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_OKSuccess.
E_DMOTIMESTAMPFORMATObject 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 FormatMeaning of Time Data
GUID_TIME_REFERENCEIgnored.
GUID_TIME_MUSICParts per quarter note.
GUID_TIME_SAMPLESSamples 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.