CDynamicOutputPin Class
| Microsoft DirectShow 9.0 |
CDynamicOutputPin Class
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
** Header:** Declared in Amfilter.h; include Streams.h.
** Library:** Use Strmbase.lib (retail builds) or Strmbasd.lib (debug builds).
| 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 | |
| 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 | |
| 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 | |
| Disconnect | Breaks the current pin connection. |
| IPinFlowControl Methods | |
| Block | Blocks or unblocks the flow of data from the pin. |