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:

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.

Protected Member Variables Description
m_BlockStateLock Critical section that protects the blocking state.
m_hUnblockOutputPinEvent Event that is signaled when the pin is not blocked.
m_hNotifyCallerPinBlockedEvent Event that is signaled when the pin successfully blocks, or the user cancels a pending block.
m_BlockState Blocking state.
m_dwBlockCallerThreadID The identifier of the thread that last called the IPinFlowControl::Block method on this pin.
m_dwNumOutstandingOutputPinUsers Number of streaming threads using this pin.
m_hStopEvent Event that is signaled when the filter stops or the pin flushes data.
m_pGraphConfig Pointer to the IGraphConfig interface for performing dynamic reconnections.
m_bPinUsesReadOnlyAllocator Flag that specifies whether samples from the pin's allocator are read-only.
Protected Methods Description
SynchronousBlockOutputPin Blocks the pin; does not return until the pin is blocked.
AsynchronousBlockOutputPin Blocks the pin; might return before the pin is blocked.
UnblockOutputPin Unblocks the pin.
BlockOutputPin Blocks the pin.
WaitEvent Waits until the specified event is signaled.
Public Methods Description
CDynamicOutputPin Constructor method.
~CDynamicOutputPin Destructor method.
SetConfigInfo Specifies the IGraphConfig pointer and the stop event.
DeliverBeginFlush Requests the connected input pin to begin a flush operation.
DeliverEndFlush Requests the connected input pin to end a flush operation.
Inactive Notifies the pin that the filter has stopped.
Active Notifies the pin that the filter is now active.
CompleteConnect Completes a connection to an input pin. Virtual.
StartUsingOutputPin Obtains access to the pin for a streaming operation. Virtual.
StopUsingOutputPin Releases access to the pin after a streaming operation. Virtual.
StreamingThreadUsingOutputPin Determines whether any thread is performing a streaming operation on the pin. Virtual.
ChangeOutputFormat Dynamically changes the media type for the connection, and delivers new segment information.
ChangeMediaType Dynamically changes the media type for the connection.
DynamicReconnect Performs a dynamic reconnection with a new media type.
IPin Methods Description
Disconnect Breaks the current pin connection.
IPinFlowControl Methods Description
Block Blocks or unblocks the flow of data from the pin.

Requirements

Requirement Value
Header
Amfilter.h (include Streams.h)
Library
Strmbase.lib (retail builds);
Strmbasd.lib (debug builds)