IMediaParams::AddEnvelope method (medparam.h)

Article
4/26/2023

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The AddEnvelope method adds an envelope to a parameter.

Syntax

HRESULT AddEnvelope(
  [in] DWORD               dwParamIndex,
  [in] DWORD               cSegments,
  [in] MP_ENVELOPE_SEGMENT *pEnvelopeSegments
);

Parameters

[in] dwParamIndex

Zero-based index of the parameter, or DWORD_ALLPARAMS to add the envelope to every parameter.

[in] cSegments

Number of segments in the envelope.

[in] pEnvelopeSegments

Pointer to an array of MP_ENVELOPE_SEGMENT 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.

Return code	Description
E_INVALIDARG	Index out of range.
E_OUTOFMEMEORY	Insufficient memory.
E_POINTER	NULL pointer argument.
S_OK	Success.

Remarks

The caller should add envelopes in time-ascending order. Otherwise, the results on playback are indeterminate. If one envelope overlaps another, the later envelope takes precedence.

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

Examples

The following code sets two envelope segments, both using a linear function.


#define MSEC 10000  // One millisecond

// Define an array with two segments. Note the segments appear in 
// time-ascending order.
MP_ENVELOPE_SEGMENT Segments[] =
{
    {  
        0,                  // rtStart
        3 * MSEC,           // rtStop
        0,                  // valStart
        12,                 // valStop
        MP_CURVE_LINEAR,    // iCurve
        MPF_ENVLP_STANDARD  // flags
    },
    {  
        6 * MSEC,
        9 * MSEC,
        12,
        0,
        MP_CURVE_LINEAR,
        MPF_ENVLP_STANDARD
    }
};
// Define the number of segments in the array.
DWORD cSegments = sizeof(Segments) / sizeof(Segments[0]);
DWORD dwParam = 0;  // Which parameter to set.

hr = pMediaParams->AddEnvelope(dwParam, cSegments, Segments);

This example assumes that the caller has previous used the IMediaParamInfo interface to query whether the DMO supports the MP_CURVE_LINEAR curve for that parameter.

Requirements

Requirement	Value
Target Platform	Windows
Header	medparam.h
Library	Dmoguids.lib

Share via