Edit

Optional Streams

  • Article

[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.]

A DMO can designate some of its output streams as optional. An optional stream produces data that the application can discard, either completely or on occasional samples. For example, an optional stream might contain additional information about a primary stream.

To query whether a stream is optional, call the IMediaObject::GetOutputStreamInfo method and check the pdwFlags parameter. Optional streams return either the DMO_OUTPUT_STREAMF_DISCARDABLE flag or the DMO_OUTPUT_STREAMF_OPTIONAL flag. These flags mean almost the same thing; one minor difference between them will be explained shortly.

If a stream is optional, the client can instruct the DMO to discard data from that stream when it processes the output. To do so, call the IMediaObject::ProcessOutput method and set the output buffer to NULL for each stream that you wish to discard. (The output buffer is specified in the pBuffer member of the DMO_OUTPUT_DATA_BUFFER.) Also set the DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER flag in the dwFlags parameter.

For each stream where the pBuffer pointer is NULL, the DMO will attempt to discard the data. If the stream is optional, the DMO is guaranteed to discard the data. If the stream is not optional, the DMO discards the data when possible, but is not guaranteed to do so. If it cannot discard the data, it sets the DMO_OUTPUT_DATA_BUFFERF_INCOMPLETE flag. If you set a pBuffer pointer to NULL but do not set the DMO_PROCESS_OUTPUT_DISCARD_WHEN_NO_BUFFER flag, the DMO does not discard the data. In that case, the DMO either buffers the output internally, or simply fails the ProcessOutput call.

The only functional difference between the DMO_OUTPUT_STREAMF_OPTIONAL flag and the DMO_OUTPUT_STREAMF_DISCARDABLE flag is the following:

  • The DMO_OUTPUT_STREAMF_OPTIONAL flag indicates that the client does not have to set a media type on that stream. However, if the client begins processing data without setting the media type for that stream, then it must discard the data from that stream for the entire duration of streaming. If you want to discard samples selectively, then you must set the media type.
  • The DMO_OUTPUT_STREAMF_DISCARDABLE flag indicates that, although the stream is optional, it always requires a media type.

Directly Hosting a DMO