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. |
Sets up an advise link for the overlay events specified by the dwInterests parameter.
HRESULT Advise(
IOverlayNotify * pOverlayNotify,
DWORD dwInterests
);
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. |
No return value.
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.
Retrieves the clipping list.
HRESULT GetClipList(
RECT * pSourceRect,
RECT * pDestinationRect,
RGNDATA ** ppRgnData
);
No return value.
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.
Retrieves the current color key used for chroma keying.
HRESULT GetColorKey(
COLORKEY * pColorKey
);
No return value.
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.
Retrieves the default color key used for a chroma key overlay.
HRESULT GetDefaultColorKey(
COLORKEY * pColorKey
);
Returns an HRESULT value.
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.
Retrieves the current system palette.
HRESULT GetPalette(
DWORD * pdwColors,
PALETTEENTRY ** ppPalette
);
Returns an HRESULT value.
Retrieves the current video source and destination rectangles.
HRESULT GetVideoPosition(
[out] RECT *pSourceRect,
[out] RECT *pDestinationRect
);
Returns an HRESULT value.
Retrieves the current window handle.
HRESULT GetWindowHandle(
HWND *pHwnd
);
Returns a pointer to the window handle.
Changes the color key.
HRESULT SetColorKey(
COLORKEY * pColorKey
);
Returns an HRESULT value.
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.
Sets the palette.
HRESULT SetPalette(
DWORD dwColors,
PALETTEENTRY * pPalette
);
Returns an HRESULT value.
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.
Terminates the advise link established with the IOverlayNotify interface.
HRESULT Unadvise( );
Returns an HRESULT value.
This method terminates the advise link established by using the IOverlay::Advise method. Only one advise link can be maintained at any one time.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.