IDDrawExclModeVideo Interface

The IDDrawExclModeVideo interface enables video playback while in Microsoft® DirectDraw® exclusive full-screen mode. Game applications can use DirectDraw in exclusive full-screen mode and continue playing video. For example, the video can be in the background and graphics can be used on top of it. The application passes in a DirectDraw object and primary surface, and these are passed to the Overlay Mixer filter in the filter graph.

The DVD graph builder object uses IDDrawExclModeVideo to play DVD content while in DirectDraw exclusive full-screen mode. This interface can also be used alone to play MPEG-1 or AVI videos in games.

For an example application, see the DDrawXcl sample application in Samples\Multimedia\DShow\Src\DDrawXcl subdirectory. For more information, see the description of the sample in DDrawXcl Sample (DirectDraw Exclusive Mode Video Playback Application).

You do not need to implement this interface. It is implemented in the Overlay Mixer filter.

Use this interface in your DirectDraw exclusive-mode games that play video.

Methods in Vtable Order

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

IDDrawExclModeVideo methods Description

SetDDrawObject Sets the DirectDraw object to be used in subsequent drawing.

GetDDrawObject Retrieves the DirectDraw object being used by the Overlay Mixer.

SetDrawParameters Specifies which part of the original video will appear at which position of the screen.

SetDDrawSurface Sets the DirectDraw surface to be used in subsequent drawing.

GetDDrawSurface Retrieves the DirectDraw surface being used by the Overlay Mixer.

GetNativeVideoProps Retrieves the width, height, and aspect ratio of the Overlay Mixer's primary stream.

SetCallbackInterface Specifies the callback interface to the Overlay Mixer so that the calling application can be notified about adjustments to the display during video playback.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDDrawExclModeVideo methods	Description
SetDDrawObject	Sets the DirectDraw object to be used in subsequent drawing.
GetDDrawObject	Retrieves the DirectDraw object being used by the Overlay Mixer.
SetDrawParameters	Specifies which part of the original video will appear at which position of the screen.
SetDDrawSurface	Sets the DirectDraw surface to be used in subsequent drawing.
GetDDrawSurface	Retrieves the DirectDraw surface being used by the Overlay Mixer.
GetNativeVideoProps	Retrieves the width, height, and aspect ratio of the Overlay Mixer's primary stream.
SetCallbackInterface	Specifies the callback interface to the Overlay Mixer so that the calling application can be notified about adjustments to the display during video playback.

IDDrawExclModeVideo::GetDDrawObject

IDDrawExclModeVideo Interface

Retrieves the DirectDraw object being used by the Overlay Mixer filter.

Syntax

HRESULT GetDDrawObject(
    LPDIRECTDRAW *pDDrawObject,
    LPBOOL *pbUsingExternal
);

Parameters

pDDrawObject
[out] Address of a pointer to the IDirectDraw interface that the Overlay Mixer is using.
pbUsingExternal
[out] Address of a pointer to a value indicating whether the Overlay Mixer is using a DirectDraw object specified by SetDDrawObject; TRUE if the Overlay Mixer is using a DirectDraw object specified SetDDrawObject or FALSE otherwise.

Return Value

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

S_OK Success.

E_INVALIDARG Argument is invalid.

A DirectDraw error code A DirectDraw error is encountered when trying to set the specified surface on the Overlay Mixer.

Remarks

If the filter graph has not set a DirectDraw object and the Overlay Mixer has not yet allocated one, then pDDrawObject will be set to NULL and pbUsingExternal will be set to FALSE.

IDDrawExclModeVideo::GetDDrawSurface

IDDrawExclModeVideo Interface

Retrieves the DirectDraw surface being used by the Overlay Mixer.

Syntax

HRESULT GetDDrawSurface(
    LPDIRECTDRAWSURFACE *pDDrawSurface,
    LPBOOL *pdUsingExternal
);

Parameters

pDDrawSurface
[out] Address of a pointer to the IDirectDrawSurface interface that is being used by the Overlay Mixer.
pdUsingExternal
[out] Address of a pointer to a Boolean value indicating whether the Overlay Mixer is using a DirectDraw surface specified by SetDDrawSurface; TRUE if the Overlay Mixer is using a DirectDraw surface specified by SetDDrawSurface or FALSE otherwise.

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 Argument is invalid.

A DirectDraw error code A DirectDraw error is encountered when trying to set the specified surface on the Overlay Mixer.

Remarks

If the filter graph has not set a DirectDraw surface and the Overlay Mixer has not yet allocated one, then pDDrawSurface will be set to NULL and pdUsingExternal will be set to FALSE.

IDDrawExclModeVideo::GetNativeVideoProps

IDDrawExclModeVideo Interface

Retrieves the current video size and picture aspect ratio of the Overlay Mixer's primary stream.

Syntax

HRESULT GetNativeVideoProps(
    LPDWORD *pdwVideoWidth,
    LPDWORD *pdwVideoHeight,
    LPDWORD *pdwPictAspectRatioX,
    LPDWORD *pdwPictAspectRatioY
);

Parameters

pdwVideoWidth
[out] Address of a pointer to the width of the video.
pdwVideoHeight
[out] Address of a pointer to the height of the video.
pdwPictAspectRatioX
[out] Address of a pointer to the x-axis aspect ratio.
pdwPictAspectRatioY
[out] Address of a pointer to the y-axis aspect ratio.

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 Argument is invalid.

Remarks

The filter graph should look for the EC_VIDEO_SIZE_CHANGED event, and on its receipt call this method to adjust the aspect ratio and position.

IDDrawExclModeVideo::SetCallbackInterface

IDDrawExclModeVideo Interface

Retrieves a pointer to the callback interface of the Overlay Mixer so that the calling application can be notified about adjustments to the display during video playback.

Syntax

HRESULT SetCallbackInterface(
    IDDrawExclModeVideoCallback *pCallback
    DWORD dwFlag
);

Parameters

pCallback
[out] Pointer to the object that implements the IDDrawExclModeVideoCallback interface. If pCallback is NULL, the callback interface is set to NULL and no more callbacks are made. If there was a previous callback interface, it is released and no more callbacks are made to it. If pCallback is not NULL and this method returns S_OK, then the reference count of the object pCallback points to is incremented.
dwFlag
[in] Must be zero.

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 Argument is invalid.

Remarks

An application should use this method to get notification about the overlay size, position, or color key change happening, so that it can hide or show the video, or adjust the video at the start, end, or during playback. By calling this method, an application can access the IDDrawExclModeVideoCallback interface and pass the pointer to that interface to the Overlay Mixer.

IDDrawExclModeVideo::SetDDrawObject

IDDrawExclModeVideo Interface

Sets the DirectDraw object to be used in subsequent drawing.

Syntax

HRESULT SetDDrawObject(
    LPDIRECTDRAW *pDDrawObject
);

Parameters

pDDrawObject
[in] Address of a pointer to the IDirectDraw interface on the object to use.

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 Argument is invalid.

A DirectDraw error code A DirectDraw error is encountered when trying to set the specified surface on the Overlay Mixer.

Remarks

A game application can use this method to share the DirectDraw object it has created for itself to the Overlay Mixer filter, so that the video can be drawn in a specified surface, as set in SetDDrawSurface.

IDDrawExclModeVideo::SetDrawParameters

IDDrawExclModeVideo Interface

Specifies which part of the original video will appear at which position of the screen.

Syntax

HRESULT SetDrawParameters(
    RECT *pSrcRect,
    RECT *pDestRect
);

Parameters

pSrcRect
[in] Pointer to the RECT structure of the original video.
pDestRect
[in] Pointer to the RECT that indicates where the video will appear on the screen.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IDDrawExclModeVideo::SetDDrawSurface

IDDrawExclModeVideo Interface

Specifies the DirectDraw surface to be used in subsequent drawing.

Syntax

HRESULT SetDDrawSurface(
    LPDIRECTDRAWSURFACE *pDDrawSurface
);

Parameters

pDDrawSurface
[in] Address of a pointer to the IDirectDrawSurface interface on the surface to use.

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 Argument is invalid.

A DirectDraw error code A DirectDraw error is encountered when trying to set the specified surface on the Overlay Mixer.

Remarks

A game application can use this to share the DirectDraw surface it has created for itself to the Overlay Mixer filter so that the video can be drawn in a specified surface. This surface must be associated with the object specified in SetDDrawObject.

S_OK	Success.
E_INVALIDARG	Argument is invalid.
A DirectDraw error code	A DirectDraw error is encountered when trying to set the specified surface on the Overlay Mixer.