CDynamicOutputPin class

[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 CDynamicOutputPin class implements an output pin that supports dynamic reconnections and format changes.

This class derives from the CBaseOutputPin class and implements the IPinFlowControl interface. It supports several operations that are important for dynamic graph building:

• Dynamic reconnection: The pin can disconnect and reconnect while the filter is still active (paused or running).
• Dynamic format change: The pin can negotiate a new media type while the filter is still active, without reconnecting.
• Flow control: The owning filter (or an application) can block data flow from the pin without stopping the filter.

For more information, see Dynamic Graph Building.

The pin has three possible states: blocked, unblocked, and pending. In the pending state, the pin is waiting for some operation to complete on another thread, before the pin switches to the blocked state. While the pin is blocked, the filter cannot deliver data through the pin, or change the pin's connection.

To coordinate among multiple threads, the owning filter must follow certain rules. (For more information about threads in the filter graph, see Threads and Critical Sections.) First, the streaming thread must always call the CDynamicOutputPin::StartUsingOutputPin method before it calls any of the following methods:

• CDynamicOutputPin::ChangeOutputFormat
• CDynamicOutputPin::ChangeMediaType
• CDynamicOutputPin::DynamicReconnect
• CBaseOutputPin::Deliver
• CBaseOutputPin::DeliverEndOfStream
• CBaseOutputPin::DeliverNewSegment
• IMemInputPin::Receive
• IMemInputPin::ReceiveMultiple
• IPin::EndOfStream
• IPin::NewSegment

Afterward, it must call the CDynamicOutputPin::StopUsingOutputPin method.

Second, the application thread must not call any of the methods in the previous list. Third, the streaming thread must not call the class methods that block or unblock the pin. These methods are: CDynamicOutputPin::Block, CDynamicOutputPin::SynchronousBlockOutputPin, CDynamicOutputPin::AsynchronousBlockOutputPin, and CDynamicOutputPin::UnblockOutputPin.

These rules ensure that the application thread cannot block the pin while the streaming thread is using it, and vice versa. After the streaming thread has called StartUsingOutputPin, the pin will not block until the streaming thread calls StopUsingOutputPin. Conversely, if the pin is blocked, StartUsingOutputPin waits until the pin is unblocked.

To avoid forgetting to call StopUsingOutputPin, you can use the CAutoUsingOutputPin class. It calls StopUsingOutputPin automatically when it goes out of scope.

When the owning filter joins or leaveds the filter graph (in its IBaseFilter::JoinFilterGraph method), it must call the pin's CDynamicOutputPin::SetConfigInfo method.

Requirements