IOverlay Interface

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 interface 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 interface 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.

Methods in Vtable Order

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

IOverlay methods Description
GetPalette Retrieves the current palette.
SetPalette Sets the palette.
GetDefaultColorKey Retrieves the default color key.
GetColorKey Returns the identifier of the currently active color key.
SetColorKey Changes the color key.
GetWindowHandle Returns the window handle.
GetClipList Retrieves the clipping list.
GetVideoPosition Retrieves the current video source and destination rectangles.
Advise Sets up an advise link for the overlay events.
Unadvise Terminates the advise link.

IUnknown methods	Description
QueryInterface	Returns pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IOverlay methods	Description
GetPalette	Retrieves the current palette.
SetPalette	Sets the palette.
GetDefaultColorKey	Retrieves the default color key.
GetColorKey	Returns the identifier of the currently active color key.
SetColorKey	Changes the color key.
GetWindowHandle	Returns the window handle.
GetClipList	Retrieves the clipping list.
GetVideoPosition	Retrieves the current video source and destination rectangles.
Advise	Sets up an advise link for the overlay events.
Unadvise	Terminates the advise link.

IOverlay::Advise

IOverlay Interface

Sets up an advise link for the overlay events specified by the dwInterests parameter.

Syntax

HRESULT Advise(

  IOverlayNotify *pOverlayNotify,

  DWORD dwInterests

  );

Parameters

pOverlayNotify
[in] Pointer to the notification interface.
dwInterests
[in] Callbacks of interest, which can be any subset of the following events.

ADVISE_NONE No changes.
ADVISE_CLIPPING Change in clipping region (synchronized with the window).
ADVISE_PALETTE Change in palette.
ADVISE_COLORKEY Change of chroma key value.
ADVISE_POSITION Change in position of video window (not synchronized with the window).
ADVISE_DISPLAY_CHANGE Called on WM_DISPLAYCHANGE. The WM_DISPLAYCHANGE message is sent to all windows when the display resolution has changed.
ADVISE_ALL2 All of the above.

Return Value

No return value.

Remarks

This method sets up an advise link for the IOverlayNotify interface to receive notifications. If one of these events occurs, the appropriate entry point in the pOverlayNotify parameter passed in is called (IOverlayNotify::OnClipChange, IOverlayNotify::OnColorKeyChange, IOverlayNotify::OnPaletteChange, or IOverlayNotify::OnPositionChange).
Only one advise link can be set on any given IOverlay interface. Trying to set another notification interface on second and subsequent calls returns VFW_E_ADVISE_ALREADY_SET. You can cancel an advise link by using IOverlay::Unadvise.

IOverlay::GetClipList

IOverlay Interface

Retrieves the clipping list.

Syntax

HRESULT GetClipList(

  RECT *pSourceRect,

  RECT *pDestinationRect,

  RGNDATA **ppRgnData

  );

Parameters

pSourceRect
[out] Pointer to the bounding client rectangle.
pDestinationRect
[in] Pointer to the destination rectangle.
ppRgnData
[out] Address of a pointer to the header and data describing clipping. If successful, the Microsoft® Win32® CoTaskMemFree function should free memory.

Return Value

No return value.

Remarks

The IOverlay implementation allocates the memory for the clipping rectangles, because it can vary in length. The filter calling this method should free the memory (using CoTaskMemFree) when it is finished with it.

IOverlay::GetColorKey

IOverlay Interface

Retrieves the current color key used for chroma keying.

Syntax

HRESULT GetColorKey(

  COLORKEY *pColorKey

  );

Parameters

pColorKey
[out] Pointer to where the current color key for chroma keying is copied.

Return Value

No return value.

Remarks

If you change the color key by using the IOverlay::SetColorKey method, all the advise links receive an IOverlayNotify::OnColorKeyChange callback method with the new color.
If no color key is currently being used, this method returns VFW_E_NO_COLOR_KEY_SET.

IOverlay::GetDefaultColorKey

IOverlay Interface

Retrieves the default color key used for a chroma key overlay.

Syntax

HRESULT GetDefaultColorKey(

  COLORKEY *pColorKey

  );

Parameters

pColorKey
[out] Pointer to where the default color key is copied.

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

A filter using color keys can get a default color from the video renderer. The default color key can then be installed into the window using IOverlay::SetColorKey. The colors returned through this method vary depending on the current display mode. If the colors are 8-bit palettized, they will be bright system colors (such as magenta). If the display is in a true-color mode, they will be shades of black.
The IOverlay interface ensures that separate instances of the renderer on the same computer get different color keys so that overlays do not conflict.

IOverlay::GetPalette

IOverlay Interface

Retrieves the current system palette.

Syntax

HRESULT GetPalette(

  DWORD *pdwColors,

  PALETTEENTRY **ppPalette

  );

Parameters

pdwColors
[out] Pointer to the number of colors present.
ppPalette
[out] Address of a pointer to the retrieved palette structure.

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.

IOverlay::GetVideoPosition

IOverlay Interface

Retrieves the current video source and destination rectangles.

Syntax

HRESULT GetVideoPosition(
  [out] RECT *pSourceRect,
  [out] RECT *pDestinationRect
  );

Parameters

pSourceRect
[out] Pointer to the bounding video client rectangle.
pDestinationRect
[in] Pointer to the destination video rectangle.

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.

IOverlay::GetWindowHandle

IOverlay Interface

Retrieves the current window handle.

Syntax

HRESULT GetWindowHandle(
  HWND *pHwnd
  );

Parameters

pHwnd
[out] Pointer to the window handle.

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.

IOverlay::SetColorKey

IOverlay Interface

Changes the color key.

Syntax

HRESULT SetColorKey(

  COLORKEY *pColorKey

  );

Parameters

pColorKey
[out] Pointer to the color key value to be set. If successful, the actual color key value selected is copied to this parameter.

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

If you change the color key by using the IOverlay::SetColorKey method, all the advise links will receive an IOverlayNotify::OnColorKeyChange callback method with the new color.
When using IOverlay on a palettized display, a filter can either install a color key (using IOverlay::SetColorKey) or install a palette (using IOverlay::SetPalette), but not both. This is because color keys in this mode require a palette to be realized that would conflict with SetPalette. Color keys can be uninstalled by requesting a color key with the CK_NOCOLORKEY flag. Likewise, any palette installed through SetPalette can be uninstalled by calling SetPalette and passing in null parameters (that is, SetPalette(0,NULL)).
Trying to set a palette when a color key is installed returns a VFW_E_PALETTE_SET error. Trying to set a color key when a palette is installed returns VFW_E_COLOR_KEY_SET.

IOverlay::SetPalette

IOverlay Interface

Sets the palette.

Syntax

HRESULT SetPalette(

  DWORD dwColors,

  PALETTEENTRY *pPalette

  );

Parameters

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

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 sets a logical palette for the window. The window is not guaranteed to always have the colors requested in the actual system device palette. The Microsoft® Windows® operating system only guarantees those colors when the window is the foreground active window. The current device palette can be obtained by calling IOverlay::GetPalette.
If the device does not have a palette, it returns VFW_E_NO_DISPLAY_PALETTE.

IOverlay::Unadvise

IOverlay Interface

Terminates the advise link established with the IOverlayNotify interface.

Syntax

HRESULT Unadvise(void);

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 terminates the advise link established by using the IOverlay::Advise method. Only one advise link can be maintained at any one time.

ADVISE_NONE	No changes.
ADVISE_CLIPPING	Change in clipping region (synchronized with the window).
ADVISE_PALETTE	Change in palette.
ADVISE_COLORKEY	Change of chroma key value.
ADVISE_POSITION	Change in position of video window (not synchronized with the window).
ADVISE_DISPLAY_CHANGE	Called on WM_DISPLAYCHANGE. The WM_DISPLAYCHANGE message is sent to all windows when the display resolution has changed.
ADVISE_ALL2	All of the above.

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