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.

When to Implement

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

When to Use

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.

---

IOverlay::Advise

IOverlay Interface

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

HRESULT Advise(
  IOverlayNotify * pOverlayNotify,
  DWORD dwInterests
  );

Parameters

pOverlayNotify

[in] Notification interface.

dwInterests

[in] Callbacks of interest, which can be any subset of the following events.

Event	Meaning
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_ALL	All of the above.

Return Values

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.

HRESULT GetClipList(
  RECT * pSourceRect,
  RECT * pDestinationRect,
  RGNDATA ** ppRgnData
  );

Parameters

pSourceRect

[out] Bounding client rectangle.

pDestinationRect

[in] Destination rectangle.

ppRgnData

[out] Header and data describing clipping. If successful, the Microsoft® Win32® CoTaskMemFree function should free memory.

Return Values

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.

HRESULT GetColorKey(
  COLORKEY * pColorKey
  );

Parameters

pColorKey

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

Return Values

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.

HRESULT GetDefaultColorKey(
  COLORKEY * pColorKey
  );

Parameters

pColorKey

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

Return Values

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

Value	Meaning
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.

HRESULT GetPalette(
  DWORD * pdwColors,
  PALETTEENTRY ** ppPalette
  );

Parameters

pdwColors

[out] Number of colors present.

ppPalette

[out] Retrieved palette structure.

Return Values

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

Value	Meaning
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.

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

Parameters

pSourceRect

[out] Bounding video client rectangle.

pDestinationRect

[in] Destination video rectangle.

Return Values

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

Value	Meaning
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.

HRESULT GetWindowHandle(
  HWND *pHwnd
  );

Parameters

pHwnd

[out] Window handle.

Return Values

Returns a pointer to the window handle.

---

IOverlay::SetColorKey

IOverlay Interface

Changes the color key.

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 Values

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

Value	Meaning
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.

HRESULT SetPalette(
  DWORD dwColors,
  PALETTEENTRY * pPalette
  );

Parameters

dwColors

[in] Number of colors present.

pPalette

[in] Colors to use for the palette.

Return Values

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

Value	Meaning
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.

HRESULT Unadvise( );

Return Values

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

Value	Meaning
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.

© 1998 Microsoft Corporation. All rights reserved. Terms of Use.

Top of Page