Microsoft DirectX 8.0 |
Controls individual streams on a filter. Pins on some filters expose this interface. For example, the AVI Mux filter supports this interface on its input pins, and the Audio Capture and WDM Video Capture filters support it on their output pins.
This interface enables an application to turn streams on and off at specified times. For example, an application might turn off an audio stream, to mute the audio, while video playback continued. Capture applications can use this interface to specify exact start and stop times for capture, and to control capture and preview streams independently of each other.
Call the StartAt method to specify the reference time when the pin will start streaming. Call the StopAt method to specify when the pin will stop streaming. Then call IMediaControl::Run on the filter graph manager.
When using this interface, you should be aware of the following limitations:
Depending on the application, you might find the ICaptureGraphBuilder2::ControlStream method more convenient, because it supports stream control at the graph level, without the application having to enumerate individual filters and pins.
Filter developers: The CBaseStreamControl base class implements this interface.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IAMStreamControl methods Description StartAt Informs the pin when to start sending streaming data. StopAt Informs the pin when to suspend processing and supplying data. GetInfo Retrieves information about the current streaming settings.
Retrieves information about the current streaming settings, including start and stop times.
Syntax
HRESULT GetInfo( AM_STREAM_INFO *pInfo );
Parameters
- pInfo
- [out] Pointer to an AM_STREAM_INFO structure that contains current stream settings.
Return Value
If the method succeeds, the return value is S_OK. Otherwise, returns an HRESULT value indicating the cause of the failure.
Remarks
The dwFlags member of the AM_STREAM_INFO structure contains flags that indicate whether valid start and stop times have been set, and whether the filter is currently discarding data.
Informs the pin when to start sending streaming data. When streaming actually starts, the filter sends an EC_STREAM_CONTROL_STARTED notification code.
Syntax
HRESULT StartAt( const REFERENCE_TIME *ptStart, DWORD dwCookie );
Parameters
- ptStart
- [in] Pointer to the time at which to start streaming. If NULL, start immediately (without sending an event notification); if MAX_TIME, cancel the existing start request.
- dwCookie
- [in] Value to send with the event notification once the start occurs. (Ignored if ptStart is MAX_TIME or NULL.)
Return Value
If the method succeeds, the return value is S_OK. Otherwise, returns an HRESULT value indicating the cause of the failure.
Remarks
Streams are enabled by default, so it is only necessary to call this method if you have previously called the StopAt method.
When the pin actually begins streaming, it signals the EC_STREAM_CONTROL_STARTED event. The first event parameter is a pointer to the pin's IPin interface, and the second is the value given in the dwCookie parameter. This enables applications to tie the events back to their requests.
If start and stop are scheduled for a single point in time, the effect is as if the start occurred an infinitesimal time before the stop. You can use this to capture a single frame.
Informs the pin when to suspend processing and supplying data.
Syntax
HRESULT StopAt( const REFERENCE_TIME *ptStop, BOOL bSendExtra, DWORD dwCookie );
Parameters
- ptStop
- [in] Pointer to the time at which to stop streaming. If NULL, stop immediately (without sending an event notification); if MAX_TIME, cancel the existing stop request.
- bSendExtra
- [in] Boolean value indicating whether to send an extra sample after the scheduled stop time. If TRUE, send an extra sample.
- dwCookie
- [in] Value to send with the event notification once the stop occurs. (Ignored if ptStart is MAX_TIME or NULL).
Return Value
If the method succeeds, the return value is S_OK. Otherwise, returns an HRESULT value indicating the cause of the failure.
Remarks
When the pin actually stops streaming, it signals the EC_STREAM_CONTROL_STOPPED event. The first event parameter is a pointer to the pin's IPin interface, and the second is the value given in the dwCookie parameter. This enables applications to tie the events back to their requests.
In video capture, you would typically call this method on both the output pin of a capture filter and the input pin of a multiplexer, and pay attention only to the notification from the multiplexer. This ensures that the capture filter doesn't needlessly capture extra frames, while guaranteeing that the multiplexer has, in fact, saved the last frame to a file.
In addition, you should specify TRUE for the bSendExtra parameter on the capture pin, and specify FALSE to the multiplexer pin. If an extra frame is not sent, the multiplexer will wait for the stop time indefinitely and not realize it already has received all the capture information. The multiplexer will discard the extra sample sent by the capture pin, so it will not get written to the file. Do not set bSendExtra to TRUE unless you also use IAMStreamControl on another downstream pin too, as in the preceding case.
If you call StopAt with a time that is in the middle of a packet, the filter will deliver the whole packet before going into a discarding state. Also, if start and stop are scheduled for a single point in time, the effect is as if the start occurred an infinitesimal time before the stop. You can use this to capture a single frame.