Microsoft DirectX 8.0 |
Microsoft® DirectShow® supports system-defined events. Filters pass events to the filter graph manager using the IMediaEventSink::Notify method. The filter graph manager handles some events, and passes others to the application. The application can retrieve events by calling the IMediaEvent::GetEvent method. For more information, see Event Notification in DirectShow.
This article describes the DirectShow events that are not specific to DVD. For events that are specific to DVD, see DVD Event Notification Codes.
For each event, this article lists the event code and the meaning of the two event parameters. It also describes the filter graph manager's default handling for the event, if any. To override the default handling, call IMediaEvent::CancelDefaultHandling in your application.
The event notification codes are defined in the header files Evcode.h and Audevcod.h.
Event notification code | Description |
---|---|
EC_ACTIVATE | A video window is being activated or deactivated. |
EC_BUFFERING_DATA | The graph is buffering data, or has stopped buffering data. |
EC_CLOCK_CHANGED | The reference clock has changed. |
EC_COMPLETE | All data from a particular stream has been rendered. |
EC_DEVICE_LOST | A Plug and Play device was removed or has become available again. |
EC_DISPLAY_CHANGED | The display mode has changed. |
EC_END_OF_SEGMENT | The end of a segment has been reached. |
EC_ERROR_STILLPLAYING | An asynchronous command to run the graph has failed. |
EC_ERRORABORT | An operation was aborted because of an error. |
EC_FULLSCREEN_LOST | The video renderer is switching out of full-screen mode. |
EC_GRAPH_CHANGED | The filter graph has changed. |
EC_NEED_RESTART | A filter is requesting that the graph be restarted. |
EC_NOTIFY_WINDOW | Notifies a filter of the video renderer's window. |
EC_OLE_EVENT | A filter is passing a text string to the application. |
EC_OPENING_FILE | The graph is opening a file, or has finished opening a file. |
EC_PALETTE_CHANGED | The video palette has changed. |
EC_PAUSED | A pause request has completed. |
EC_QUALITY_CHANGE | The graph is dropping samples, for quality control. |
EC_REPAINT | A video renderer requires a repaint. |
EC_SEGMENT_STARTED | A new segment has started. |
EC_SHUTTING_DOWN | The filter graph is shutting down, prior to being destroyed. |
EC_SNDDEV_IN_ERROR | An audio device error has occurred on an input pin. |
EC_SNDDEV_OUT_ERROR | An audio device error has occurred on an output pin. |
EC_STARVATION | A filter is not receiving enough data. |
EC_STEP_COMPLETE | A filter performing frame stepping has stepped the specified number of frames. |
EC_STREAM_CONTROL_STARTED | A stream-control start command has taken effect. |
EC_STREAM_CONTROL_STOPPED | A stream-control start command has taken effect. |
EC_STREAM_ERROR_STILLPLAYING | An error has occurred in a stream. The stream is still playing. |
EC_STREAM_ERROR_STOPPED | A stream has stopped because of an error. |
EC_USERABORT | The user has terminated playback. |
EC_VIDEO_SIZE_CHANGED | The native video size has changed. |
EC_WINDOW_DESTROYED | The video renderer was destroyed or removed from the graph. |
A video window is being activated or deactivated.
Parameters
- lParam1
- TRUE if the window is activated, or FALSE if the window is deactivated.
- lParam2
- Pointer to the renderer's IBaseFilter interface.
Default Handling
The filter graph manager sets the focus, through the IResourceManager interface. It does not send the event notification to the application.
Remarks
A video renderer sends this event whenever its window is activated or deactivated (that is, when it receives a WM_ACTIVATEAPP message). Window activation or deactivation can occur because the window has gained or lost focus, or because the renderer has switched between full-screen mode and windowed mode.
This event enables the filter graph manager to allocate resources that depend on window focus, such as audio devices.
The graph is buffering data, or has stopped buffering data.
Parameters
- lParam1
- TRUE if the graph is starting to buffer, or FALSE if the graph has stopped buffering.
- lParam2
- Zero.
Default Handling
None.
Remarks
A filter can send this event if it needs to buffer data from an external source. (For example, it might be loading data from a network.) The application can use this event to adjust its user interface.
The reference clock has changed.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
None.
Remarks
The filter graph manager sends this event when its IMediaFilter::SetSyncSource method is called.
All data from a particular stream has been rendered.
Parameters
- lParam1
- HRESULT value; can be S_OK.
- lParam2
- Zero, or a pointer to the renderer's IBaseFilter interface.
Default Handling
By default, the filter graph manager does not forward this event to the application. However, after all the streams in the graph report EC_COMPLETE, the filter graph manager posts a separate EC_COMPLETE event to the application.
If default handling is disabled for this event, the application receives all of the EC_COMPLETE events from the renderers.
Remarks
A renderer filter sends this event when it receives an end-of-stream notice. (End-of-stream is signaled through the IPin::EndOfStream method.) The filter sends exactly one EC_COMPLETE event for each stream. The filter must process any pending samples before it sends the event. Stopping a renderer resets any end-of-stream state that was cached.
Filters set the lParam2 parameter to an IBaseFilter pointer. If default handling is enabled, the filter graph manager sets this parameter to zero.
A Plug and Play device was removed or has become available again.
Parameters
- lParam1
- Pointer to the IUnknown interface of the filter that represents the device.
- lParam2
- Zero if the device was removed, or 1 if the device is available again.
Default Handling
None.
Remarks
When the device becomes available again, the previous state of the device filter is no longer valid. The application must rebuild the graph in order to use the device.
The display mode has changed.
Parameters
- lParam1
- Pointer to the IPin interface of the video renderer's input pin, or zero.
- lParam2
- Zero.
Default Handling
The filter graph manager temporarily stops the graph, and then disconnects and reconnects the video renderer. It does not pass the event to the application.
Remarks
Video renderers can send this event in response to a WM_DISPLAYCHANGE message. The WM_DISPLAYCHANGE message indicates that the user has changed the display resolution.
During pin connection, most video renderers pick a format based on the current display mode. If the display mode changes, the video renderer might need to choose another format. By sending this message, the renderer signals to the filter graph manager that it needs to be reconnected. During the reconnection, the renderer can select a new format. If the reconnection fails, the filter graph manager sends an EC_ERRORABORT event to the application.
The end of a segment has been reached.
Parameters
- lParam1
- Pointer to a REFERENCE_TIME value that specifies the accumulated stream time since the start of the segment.
- lParam2
- DWORD value indicating the segment number (zero-based).
Default Handling
The filter graph manager checks the number of EC_END_OF_SEGMENT events against the number of EC_SEGMENT_STARTED events. If they match, it forwards the EC_END_OF_SEGMENT event to the application.
Remarks
This event code supports seamless looping. When a call to the IMediaSeeking::SetPositions method includes the AM_SEEKING_Segment flag, the source filter sends this event code instead of calling IPin::EndOfStream.
An asynchronous command to run the graph has failed.
Parameters
- lParam1
- HRESULT value of the operation that failed.
- lParam2
- Zero.
Default Handling
None.
Remarks
If the filter graph manager issues an asynchronous run command that fails, it sends this event to the application. The graph remains in a running state. The state of the underlying filters is indeterminate. Some filters might be running, others might not.
An operation was aborted because of an error.
Parameters
- lParam1
- HRESULT value of the operation that failed.
- lParam2
- Zero.
Default Handling
None.
The video renderer is switching out of full-screen mode.
Parameters
- lParam1
- Zero.
- lParam2
- Pointer to the video renderer's IBaseFilter interface, or NULL.
Default Handling
None.
Remarks
When the Full Screen Renderer loses activation, it sends this event. When another video renderer switches out of full-screen mode, the filter graph manager sends this event, in response to an EC_ACTIVATE event from the renderer.
The filter graph has changed.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
None.
Remarks
This event code is intended for debugging. It is not sent for all graph changes.
A filter is requesting that the graph be restarted.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
The filter graph manager pauses and restarts the graph. It does not pass the event to the application.
Remarks
If a filter rejects a sample in the middle of a stream, the upstream pin will stop delivering samples. The filter can restart the stream by sending this event. For example, the audio renderer might lose access to the sound device, because a video window has lost focus. At that point, the audio renderer starts rejecting samples. When it regains access to the sound device, it sends this event to restart the audio stream.
Notifies a filter of the video renderer's window.
Parameters
- lParam1
- Handle to the window.
- lParam2
- Zero.
Default Handling
This event is used internally by DirectShow. The filter graph manager does not pass this event to the application. Applications cannot override the default handling for this event.
Remarks
When a video renderer is connected, it checks whether the upstream output pin supports the IMediaEventSink interface. If so, the renderer sends this event to the upstream filter.
A filter is passing a text string to the application.
Parameters
- lParam1
- String of type BSTR.
- lParam2
- String of type BSTR.
Default Handling
None.
Remarks
By convention, the first parameter contains type information (for example, Text) and the second parameter contains the text string.
The graph is opening a file, or has finished opening a file.
Parameters
- lParam1
- TRUE if the graph is starting to open a file, or FALSE if the graph is no longer opening the file.
- lParam2
- Zero.
Default Handling
None.
Remarks
A filter can send this event if it spends significant time opening a file. (For example, the file might be located on a network.) The application can use this event to adjust its user interface.
Currently, none of the filters included with DirectShow send this event.
The video palette has changed.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
None.
Remarks
Video renderers send this event if they detect a palette change in the stream.
A pause request has completed.
Parameters
- lParam1
- HRESULT value that indicates the result of the transition. If the value is S_OK, the filter graph is now in a paused state.
- lParam2
- Zero.
Default Handling
None.
Remarks
The filter graph manager sends this event when it completes an asynchronous pause command.
The graph is dropping samples, for quality control.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
None.
Remarks
A filter sends this event if it drops samples in response to a quality control message. It sends the event only when it adjusts the quality level, not for each sample that it drops. For more information, see Quality Control Management.
A video renderer requires a repaint.
Parameters
- lParam1
- Pointer to the IPin interface of the video renderer's input pin, or NULL.
- lParam2
- Zero.
Default Handling
The lParam1 parameter might specify the video renderer's input pin. If so, the filter graph manager finds the output pin connected to that pin and queries it for the IMediaEventSink interface. If the output pin supports IMediaEventSink, the filter graph manager calls IMediaEventSink::Notify with the EC_REPAINT event code. This gives the upstream filter the opportunity to re-send the last sample.
If lParam1 is NULL, or if the pin does not support IMediaEventSink, or if the Notify method fails, the filter graph manager handles the EC_REPAINT event by itself. Its behavior depends on the state of the graph:
- Running: Ignores the event. (The renderer will receive the next sample in the stream.)
- Paused: Seeks the graph to its current location, thereby flushing the filter and re-queueing the data.
- Stopped: Pauses and stops the graph, thereby re-queueing the data.
By default, the filter graph manager does not pass this event to the application.
Remarks
Video renderers send this message when they receive a WM_PAINT message and have no data to display.
A new segment has started.
Parameters
- lParam1
- Pointer to a REFERENCE_TIME value that specifies the accumulated stream time since the start of the segment.
- lParam2
- DWORD value indicating the segment number (zero-based).
Default Handling
This event is not sent to the application.
Remarks
If a filter will send an EC_END_OF_SEGMENT at the end of a segment, it sends this event at the start of the segment. The filter graph manager uses this event notification to compute how many EC_END_OF_SEGMENT notifications it should expect at the end of the segment.
By default, filters do not send EC_END_OF_SEGMENT events at the end of segments, and therefore should not send this event. For more information, see AM_SEEKING_Segment and IMediaSeeking::SetPositions.
The filter graph is shutting down, prior to being destroyed.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
This event is not sent to the application. The filter graph manager sends it to plug-in distributors, to notify them that the graph is shutting down. Applications cannot override the default handling of this event.
An audio device error has occurred on an input pin.
Parameters
- lParam1
- DWORD value from the SNDDEV_ERR enumerated type, indicating how the device was being accessed when the failure occurred.
- lParam2
- DWORD value indicating the error returned from the sound device call.
Default Handling
None.
An audio device error has occurred on an output pin.
Parameters
- lParam1
- DWORD value from the SNDDEV_ERR enumerated type, indicating how the device was being accessed when the failure occurred.
- lParam2
- DWORD value indicating the error returned from the sound device call.
Default Handling
None.
A filter is not receiving enough data.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
The event is not sent to the application. If the filter graph is running, the filter graph manager pauses the graph and waits for the pause to complete. Then it runs the graph again. The filter sending the event should not complete its transition to paused until it has enough data to resume. If the filter graph is not running, the filter graph manager ignores this event.
Remarks
A parser or source filter can send this event if too little data is arriving.
A filter performing frame stepping has stepped the specified number of frames.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
The filter graph manager pauses the graph and passes the event to the application.
See Also
IVideoFrameStep::Step
A stream-control start command has taken effect.
Parameters
- pSender
- Pointer to the IPin interface of the pin that started the stream.
- dwCookie
- User-defined DWORD value.
Default Handling
None.
Remarks
Filters send this event in response to the IAMStreamControl::StartAt method. This method specifies a reference time for a pin to begin streaming. When streaming does begin, the filter sends this event.
The pSender parameter specifies the pin that executes the start command. Depending on the implementation, it might not be the pin that received the StartAt call.
The dwCookie parameter is specified by the application in the StartAt method. This parameter enables the application to track multiple calls to the method.
A stream-control start command has taken effect.
Parameters
- pSender
- Pointer to the IPin interface of the pin that stopped the stream.
- dwCookie
- User-defined DWORD value.
Default Handling
None.
Remarks
Filters send this event in response to the IAMStreamControl::StopAt method. This method specifies a reference time for a pin to stop streaming. When streaming does halt, the filter sends this event.
The pSender parameter specifies the pin that executes the stop command. Depending on the implementation, it might not be the pin that received the StopAt call.
The dwCookie parameter is specified by the application in the StopAt method. This parameter enables the application to track multiple calls to the method.
An error has occurred in a stream. The stream is still playing.
Parameters
- lParam1
- HRESULT of the operation that failed.
- lParam2
- DWORD value, generally zero.
Default Handling
None. The application must decide whether to stop the graph.
A stream has stopped because of an error.
Parameters
- lParam1
- HRESULT of the operation that failed.
- lParam2
- DWORD value, generally zero.
Default Handling
None.
The user has terminated playback.
Parameters
- lParam1
- Zero.
- lParam2
- Zero.
Default Handling
None. The application must decide whether to stop the graph.
Remarks
This event code signals that the user has terminated normal graph playback. For example, video renderers send this event if the user closes the video window.
After sending this event, the filter should reject all samples and not send any EC_REPAINT events, until the filter stops and is reset.
The native video size has changed.
Parameters
- lParam1
- Low-order WORD specifies the new width, in pixels; high-order WORD specifies the new height, in pixels.
- lParam2
- Zero.
Default Handling
None.
Remarks
Video renderers send this event if they detect a change in the native video size.
The video renderer was destroyed or removed from the graph.
Parameters
- lParam1
- Pointer to the video renderer's IBaseFilter interface.
- lParam2
- Zero.
Default Handling
The filter graph manager releases this window as the focus, through the IResourceManager interface. It does not send the event notification to the application.
Remarks
The video renderer sends this event when it leaves the filter graph, in its IBaseFilter::JoinFilterGraph method. (Sending the event when the filter is destroyed might be too late, because at that point the filter graph manager might also be destroyed.)
This event enables other filters to acquire resources that depend on window focus, such as audio devices.