IOverlayNotify Interface

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.

To get notifications of when the window size or position changes, when the current system palette changes, or when a different color key is used, decoders that do their own drawing should implement an IOverlayNotify interface. A pointer to this interface can then be passed to the IOverlay interface on the renderer's input pin, through the method, to set up an advise link (essentially a callback mechanism). After the advise link is established, the renderer calls the decoder's IOverlayNotify methods when the appropriate events occur. An advise link can be canceled by calling IOverlay::Unadvise.

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.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Returns pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IOverlayNotify methods Description
OnPaletteChange Provides notification that the palette of the window has changed.
OnClipChange Provides notification that the window's visible region has changed.
OnColorKeyChange Provides notification that the chroma key has changed.
OnPositionChange Provides notification that the position has changed.

IUnknown methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOverlayNotify methods	Description
OnPaletteChange	Provides notification that the palette of the window has changed.
OnClipChange	Provides notification that the window's visible region has changed.
OnColorKeyChange	Provides notification that the chroma key has changed.
OnPositionChange	Provides notification that the position has changed.

IOverlayNotify::OnClipChange

IOverlayNotify Interface

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.

Syntax

HRESULT OnClipChange(
  RECT *pSourceRect,
  RECT *pDestinationRect,
  RGNDATA *pRgnData
  );

Parameters

pSourceRect
[in] Pointer to the region of the video to use.
pDestinationRect
[in] Pointer to the video destination.
pRgnData
[in] Pointer to the clipping information.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

The calls to OnClipChange happen in synchronization with the window. It is called with an empty clip list to freeze the video before the window moves, and then called again when the window has stabilized with the new clip list.
If the window rectangle is all zeros, the window is invisible. As is the case for AVI decoders, the decoder should save the image if it relies on the current image to decode the next one.

IOverlayNotify::OnColorKeyChange

IOverlayNotify Interface

Provides notification that the window's color key has changed.

Syntax

HRESULT OnColorKeyChange(

  COLORKEY *pColorKey

  );

Parameters

pColorKey
[in] Pointer to the new chroma key.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

IOverlayNotify::OnPaletteChange

IOverlayNotify Interface

Provides notification that the palette of the window has changed.

Syntax

HRESULT OnPaletteChange(

  DWORD dwColors,

  const PALETTEENTRY *pPalette

  );

Parameters

dwColors
[in] Number of colors present.
pPalette
[in] Pointer to the array of palette colors.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

Before returning, the filter should copy the array of RGBQUAD values, if necessary.

IOverlayNotify::OnPositionChange

IOverlayNotify Interface

Provides notification that the position has changed.

Syntax

HRESULT OnPositionChange(
  const RECT *pSourceRect,
  const RECT *pDestinationRect
  );

Parameters

pSourceRect
[in] Pointer to the source video rectangle.
pDestinationRect
[in] Pointer to the destination video rectangle. Note that this is not clipped to the visible display area.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This method is a callback intended for use by hardware overlay cards that do not want the expense of synchronous clipping updates, and just want to know when the source or destination video positions change.
Unlike the IOverlayNotify::OnClipChange method, this method is not called in synchronization with the window changing but, rather, at some point after the window has changed (basically in time with WM_SIZE messages received). This is therefore suitable for overlay cards that do not inlay their data to the frame buffer.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.