IOverlayNotify 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 IOverlayNotify interface provides an upstream filter, such as a decoder, with notifications of changes to the rendering window. This includes notifications of changes to the palette, color key, and window position, and visible region (clipping) changes.

Most software video decoders let the video renderer draw the decompressed images they produce by passing the media samples to the IMemInputPin interface on the renderer's input pin.

However, some video decoding filters (typically hardware decompression boards) handle the drawing of the images themselves, perhaps by using a VGA connector. These filters do not need to use IMemInputPin, but can instead use the IOverlay interface provided by the renderer input pin. Through this interface, the decoder can be notified when the window position or size changes, or when the current system palette changes in order to install and change color keys and palettes.

Decoders that do their own drawing should implement the IOverlayNotify and IOverlayNotify2 interfaces. The renderer uses this interface to notify the decoder whenever the window size or position changes, the system palette changes, or a different color key is used. The decoder should call the IOverlay::Advise method on the renderer's input pin, to set up the callback. Once the callback is established, the renderer calls the decoder's IOverlayNotify methods when the appropriate events occur. To cancel the callback, use the IOverlay::Unadvise method.

The video renderer is the only filter that calls the methods on this interface. This is done automatically by the default video renderer. If you are writing a replacement video renderer, you will need to use the methods on this interface if your filter supports IOverlay and this interface is passed to your filter in an IOverlay::Advise call.

Inheritance

The IOverlayNotify interface inherits from the IUnknown interface. IOverlayNotify also has these types of members:

Methods

The IOverlayNotify interface has these methods.

IOverlayNotify::OnClipChange The OnClipChange method provides notification that the window's visible region has changed. It is essential that any overlay hardware be updated to reflect the change to the visible region before returning from this method.
IOverlayNotify::OnColorKeyChange The OnColorKeyChange method provides notification that the window's color key has changed.
IOverlayNotify::OnPaletteChange The OnPaletteChange method provides notification that the palette of the window has changed.
IOverlayNotify::OnPositionChange The OnPositionChange method provides notification that the position has changed.

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)