IOverlay interface (strmif.h)
[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 IOverlay interface provides information so that a filter can write directly to video memory while placing the video in the correct window position. It is implemented on the input pin of the video renderer and communicates with an upstream filter (typically a video decompressor) by calling that filter's IOverlayNotify methods to notify it of changes to the video window.
This interface has no relationship to the DirectDraw® overlay capability. The Microsoft video renderer draws data it receives through the IMemInputPin interface, using DirectDraw overlays when available. This interface, used in place of IMemInputPin, is intended to provide notification support for any upstream filter that bypasses the renderer's drawing capabilities, but needs notifications of other display properties.
See the IOverlayNotify reference page for more information on how the IOverlay and IOverlayNotify interfaces work together.
See the IOverlayNotify2 interface for more information on asynchronous notifications of changes to the rendering window.
This interface is implemented on the Microsoft® DirectShow® video renderer filter. It can also be implemented on replacement video renderer filters if desired. If doing so, implement this interface so that filters writing directly to the frame buffer or trying to position an overlay know where to display their video. To implement this interface, the renderer must be prepared to use methods on the IOverlayNotify interface or the IOverlayNotify2 interface of the filter doing the drawing, with notifications of video property changes.
The window-based renderer in DirectShow supports both IMemInputPin and IOverlay interfaces. These two interfaces are mutually exclusive. A filter chooses to use the IOverlay transport by providing a media type during connection that has a subtype of MEDIASUBTYPE_Overlay. After connection, it will be able to get and use successfully the IOverlay interface. If it connects with any other video formats (such as MEDIASUBTYPE_RGB8), trying to call through IOverlay returns VFW_E_NOT_OVERLAY_CONNECTION.
Use the methods on this function from an upstream filter that must control video overlay properties and intends to handle the displaying of the video data itself. This typically is used by hardware video decoders that have an alternate connection to the video hardware.
Inheritance
The IOverlay interface inherits from the IUnknown interface. IOverlay also has these types of members:
Methods
The IOverlay interface has these methods.
| IOverlay::Advise The Advise method sets up an advise link for the overlay events specified by the dwInterests parameter. |
| IOverlay::GetClipList The GetClipList method retrieves the clipping list. |
| IOverlay::GetColorKey The GetColorKey method retrieves the current color key used for chroma keying. |
| IOverlay::GetDefaultColorKey The GetDefaultColorKey method retrieves the default color key used for a chroma key overlay. |
| IOverlay::GetPalette The GetPalette method retrieves the current system palette. |
| IOverlay::GetVideoPosition The GetVideoPosition method retrieves the current video source and destination rectangles. |
| IOverlay::GetWindowHandle The GetWindowHandle method retrieves the current window handle. |
| IOverlay::SetColorKey The SetColorKey method changes the color key. |
| IOverlay::SetPalette The SetPalette method sets the palette. |
| IOverlay::Unadvise The Unadvise method terminates the advise link established with the IOverlayNotify interface. |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | strmif.h (include Dshow.h) |