IDDrawExclModeVideoCallback Interface

The IDDrawExclModeVideoCallback interface enables applications to get synchronous notification about changes to the overlay position, size, visibility, and so on, so that the application can adjust its video visibility, size, and position. This avoids any color key flash at the beginning, end, or during playback. The application must implement a COM object supporting this interface. For an example application, see the DDrawXcl sample application in Samples\Multimedia\DShow\Src\DDrawXcl subdirectory. For more information, see the description of the example in DDrawXcl Sample (DirectDraw Exclusive Mode Video Playback Application).

Implement this interface if you are using an IDDrawExclModeVideo interface and want the callback information (presumably always).

Use this interface if you're using the Microsoft® DirectShow® Overlay Mixer filter, and more generally if you are writing a filter that supports IDDrawExclModeVideo or needs to generate callbacks to enable an application to draw color keys at the right time.

Methods in Vtable Order

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

IDDrawExclModeVideoCallback methods Description

OnUpdateOverlay Informs the application when the overlay surface for the video is about to change.

OnColorKeyChange Informs the application that the color key has changed so that the application can use the new color key to overlay graphics on the video.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDDrawExclModeVideoCallback methods	Description
OnUpdateOverlay	Informs the application when the overlay surface for the video is about to change.
OnColorKeyChange	Informs the application that the color key has changed so that the application can use the new color key to overlay graphics on the video.

IDDrawExclModeVideoCallback::OnColorKeyChange

IDDrawExclModeVideoCallback Interface

Informs the application that the color key has changed so that the application can use the new color key to overlay graphics on the video.

Syntax

HRESULT OnColorKeyChange (
    COLORKEY const *pKey,
    DWORD dwColor
);

Parameters

pKey
[out] Pointer to a COLORKEY structure that contains the key type and a palette index.
dwColor
[out] Value indicating the 8-bit palette index of the COLORKEY returned in pKey, if the current display mode is 8-bit palettized. Otherwise, it is a value representing the color key in the pixel format of the current display mode.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.
The current DirectShow implementation return values include the following:

S_OK Success.

E_INVALIDARG One of the parameters is invalid.

IDDrawExclModeVideoCallback::OnUpdateOverlay

IDDrawExclModeVideoCallback Interface

Informs the application when the overlay surface for the video is about to become visible, invisible, change size, or change position, so that the application can repaint its window appropriately.

Syntax

HRESULT OnUpdateOverlay(
    BOOL bBeforeChange,
    DWORD dwFlags,
    BOOL bOldVisible,
    LPRECT *prcSrcOld,
    LPRECT *prcDestOld,
    BOOL bNewVisible,
    LPRECT *prcSrcNew,
    LPRECT *prcDestNew,
);

Parameters

bBeforeChange
[in] Boolean value specifying whether the call is being made before or after the overlay-related change. TRUE specifies before, FALSE specifies after.
dwFlags
[in] Value from the AM_OVERLAY_NOTIFY_FLAGS data type that specifies what is about to change or what changed.
bOldVisible
[in] Boolean value specifying whether the old window is visible. TRUE means the old window is visible.
prcSrcOld
[in] Pointer to the rectangle representing the old source position of the DirectDraw surface.
prcDestOld
[in] Pointer to the rectangle representing the old destination position of the rectangle in the overlay surface.
bNewVisible
[in] Boolean specifying whether the new window is visible. TRUE means the new window is visible.
prcSrcNew
[in] Pointer to the rectangle representing the new source position of the DirectDraw surface.
prcDestNew
[in] Pointer to the rectangle representing the new destination position of the rectangle in the overlay surface.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.
The current DirectShow implementation return values include the following:

S_OK Success.

E_INVALIDARG Invalid parameter.

Remarks

The application should call this method once before the overlay-related change occurs and once after the changes are done. In the call before the change, the overlay change doesn't happen until the application completes executing this method.