IDirectDrawVideo Interface

The IDirectDrawVideo interface is on the video renderer and provides information about Microsoft® DirectDraw® with respect to its use by the renderer. For example, the interface enables an application to get details of the surface and any available hardware capabilities. It also enables the application to adjust the surfaces that the renderer should use, and even to set the DirectDraw instance. There is some duplication in this interface with the IDirectDraw interface; however, this interface enables simple access to that information without calling the DirectDraw provider directly.

The renderer doesn't load DirectDraw until it is connected, and likewise DirectDraw is unloaded only when the renderer is disconnected. When the renderer has allocated the DirectDraw surfaces it will use for video playback, an application can obtain a DDSURFACEDESC structure describing it. By passing in a pointer to a DDSURFACEDESC structure, the renderer will fill in the structure with the details of the current surface. If DirectDraw has not been loaded, the renderer will return E_FAIL. If the renderer is using DCI (the predecessor to DirectDraw), the DDSURFACEDESC structure is not filled in but the call will return S_FALSE. The only type of DCI surfaces the renderer uses are primary surfaces.

This interface is implemented by the Microsoft® DirectShow® video renderer to provide information about DirectDraw surfaces and hardware capabilities.

Applications can use this interface to get details of the surface and any available hardware capabilities, adjust the surfaces that the renderer should use, and set the IDirectDraw instance. Applications can set the IDirectDraw instance because DirectDraw can be opened only once per process; this helps resolve conflicts.

Methods in Vtable Order

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

IDirectDrawVideo methods Description

GetCaps Retrieves a DirectDraw-defined DDCAPS structure containing the hardware capabilities.
GetEmulatedCaps Retrieves a DirectDraw-defined DDCAPS structure containing the emulated capabilities.
CanUseOverlayStretch Determines whether the renderer will check overlay restrictions.
CanUseScanLine Determines whether the renderer will check the current scan line when drawing.
GetDirectDraw Retrieves the IDirectDraw interface.
GetFourCCCodes Retrieves the multimedia format type FOURCC DWORD.
GetSurfaceDesc Retrieves a description of the DirectDraw surface in use.
GetSurfaceType Retrieves the actual surface type.
GetSwitches Retrieves the surface types that the renderer is allowed to use.
SetDefault Makes the current property settings the global default.
SetDirectDraw Passes the IDirectDraw interface to a loaded driver.
SetSwitches Sets the surface types that the renderer is allowed to use.
UseOverlayStretch Determines whether the renderer should check overlay stretch limitations.
UseScanLine Determines whether the renderer should check the current scan line when drawing a video.
UseWhenFullScreen Determines whether DirectShow should change display mode when going to full-screen mode.
WillUseFullScreen Determines whether DirectShow will change display mode when going to full-screen mode.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDirectDrawVideo methods	Description
GetCaps	Retrieves a DirectDraw-defined DDCAPS structure containing the hardware capabilities.
GetEmulatedCaps	Retrieves a DirectDraw-defined DDCAPS structure containing the emulated capabilities.
CanUseOverlayStretch	Determines whether the renderer will check overlay restrictions.
CanUseScanLine	Determines whether the renderer will check the current scan line when drawing.
GetDirectDraw	Retrieves the IDirectDraw interface.
GetFourCCCodes	Retrieves the multimedia format type FOURCC DWORD.
GetSurfaceDesc	Retrieves a description of the DirectDraw surface in use.
GetSurfaceType	Retrieves the actual surface type.
GetSwitches	Retrieves the surface types that the renderer is allowed to use.
SetDefault	Makes the current property settings the global default.
SetDirectDraw	Passes the IDirectDraw interface to a loaded driver.
SetSwitches	Sets the surface types that the renderer is allowed to use.
UseOverlayStretch	Determines whether the renderer should check overlay stretch limitations.
UseScanLine	Determines whether the renderer should check the current scan line when drawing a video.
UseWhenFullScreen	Determines whether DirectShow should change display mode when going to full-screen mode.
WillUseFullScreen	Determines whether DirectShow will change display mode when going to full-screen mode.

IDirectDrawVideo::CanUseOverlayStretch

IDirectDrawVideo Interface

Determines whether the renderer will check overlay restrictions.

Syntax

HRESULT CanUseOverlayStretch(
    long *UseOverlayStretch
);

Parameters

UseOverlayStretch
Pointer to a value indicating whether the renderer can use overlay restrictions. OATRUE indicates the renderer will check overlay restrictions; OAFALSE indicates it will not.

Return Value

Returns an HRESULT value.

Remarks

For a description of overlay stretching, see IDirectDrawVideo::UseOverlayStretch.

IDirectDrawVideo::CanUseScanLine

IDirectDrawVideo Interface

Determines whether the renderer will check the current scan line when drawing.

Syntax

HRESULT CanUseScanLine(
    long *UseScanLine
);

Parameters

UseScanLine
Pointer to a value indicating whether the renderer will use scan line information. OATRUE indicates the renderer will check the current scan line when drawing; OAFALSE indicates it will not.

Return Value

Returns an HRESULT value.

Remarks

For a description of the use of scan line detection in the DirectShow video renderer, see IDirectDrawVideo::UseScanLine.

IDirectDrawVideo::GetCaps

IDirectDrawVideo Interface

Retrieves a DirectDraw-defined DDCAPS structure containing the hardware capabilities.

Syntax

HRESULT GetCaps(
    DDCAPS *pCaps
);

Parameters

pCaps
Pointer to a DDCAPS structure containing the hardware capabilities.

Return Value

Returns an HRESULT value.

Remarks

If the renderer has not loaded DirectDraw, this method returns E_FAIL.

IDirectDrawVideo::GetDirectDraw

IDirectDrawVideo Interface

Retrieves the IDirectDraw interface.

Syntax

HRESULT GetDirectDraw(
    LPDIRECTDRAW *ppDirectDraw
);

Parameters

ppDirectDraw
Address of a pointer to the IDirectDraw interface.

Return Value

Returns an HRESULT value.

Remarks

If an application wants to load DirectDraw but allow the renderer to also allocate surfaces, it can let the renderer load DirectDraw and then obtain a reference-incremented interface to it through this method. The interface returned should be released by the application when it is finished with it.

IDirectDrawVideo::GetEmulatedCaps

IDirectDrawVideo Interface

Retrieves a DirectDraw-defined DDCAPS structure containing the emulated capabilities.

Syntax

HRESULT GetEmulatedCaps(
    DDCAPS *pCaps
);

Parameters

pCaps
Pointer to a DDCAPS structure containing the emulated capabilities.

Return Value

Returns an HRESULT value. If the renderer has not loaded DirectDraw, this method returns E_FAIL.

IDirectDrawVideo::GetFourCCCodes

IDirectDrawVideo Interface

Retrieves the multimedia format type.

Syntax

HRESULT GetFourCCCodes(
    DWORD *pCount,
    DWORD *pCodes
);

Parameters

pCount
Pointer to the number of FOURCC codes in the pCodes array.
pCodes
Pointer to an array of DWORD media tags formerly used for Microsoft multimedia types.

Return Value

Returns an HRESULT value.

Remarks

In the original Microsoft® Windows® multimedia APIs, media types were tagged with 32-bit values created from four 8-bit characters and were known as FOURCC codes. Because FOURCC codes are unique, a one-to-one mapping has been made possible by allocating a range of 4 billion GUIDs representing FOURCCs.
This method retrieves the FOURCC codes that the current display driver can support. The number available is obtained by calling the method with a valid pCount pointer, but with pCodes set to NULL. In this case, the pCount variable will be filled in with the number of FOURCC codes available. An application can then allocate enough DWORD values for this many FOURCC codes and call the method again with the array pointer in pCodes.

IDirectDrawVideo::GetSurfaceDesc

IDirectDrawVideo Interface

Retrieves a DDSURFACEDESC structure describing the current DirectDraw surface.

Syntax

HRESULT GetSurfaceDesc(
    DDSURFACEDESC *pSurfaceDesc
);

Parameters

pSurfaceDesc
Pointer to a DDSURFACEDESC structure describing the current DirectDraw surface.

Return Value

Returns an HRESULT value. If no surface has been allocated, this method will return E_FAIL. If a DCI primary surface is in use, the DDSURFACEDESC structure will not be filled in and the call will return S_FALSE.

Remarks

Surfaces are allocated only when the renderer is paused. After the renderer has been paused, it cannot release the surfaces when stopped.

IDirectDrawVideo::GetSurfaceType

IDirectDrawVideo Interface

Retrieves the actual surface type as a DirectShow DirectDraw Surface (AMDDS) definition.

Syntax

HRESULT GetSurfaceType(
    DWORD *pSurfaceType
);

Parameters

pSurfaceType
Pointer to a field filled in with one bit setting selected from the following list of AMDDS definitions.

AMDDS_NONE No use for DCI/DirectDraw.
AMDDS_DCIPS Use DCI primary surface.
AMDDS_PS Use DirectDraw primary surface.
AMDDS_RGBOVR RGB overlay surfaces.
AMDDS_YUVOVR YUV overlay surfaces.
AMDDS_RGBOFF RGB off-screen surfaces.
AMDDS_YUVOFF YUV off-screen surfaces.
AMDDS_RGBFLP RGB flipping surfaces.
AMDDS_YUVFLP YUV flipping surfaces.
AMDDS_ALL All the previous flags.
AMDDS_DEFAULT Use all available surfaces.
AMDDS_YUV (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY (AMDDS_DCIPS | AMDDS_PS).

Return Value

Returns an HRESULT value.

Remarks

It is not always easy to discover which kind of surface is being used by looking at a DDSURFACEDESC structure. Therefore, an application can call GetSurfaceType to retrieve the surface type. The field will be filled in with one bit setting selected from the preceding list of AMDDS definitions.

IDirectDrawVideo::GetSwitches

IDirectDrawVideo Interface

Retrieves the surface types that the renderer is allowed to use.

Syntax

HRESULT GetSwitches(
    DWORD *pSwitches
);

Parameters

pSwitches
Pointer to a bit mask containing one or more of the following DirectShow DirectDraw Surface (AMDDS) surface types.

AMDDS_NONE No use for DCI/DirectDraw.
AMDDS_DCIPS Use DCI primary surface.
AMDDS_PS Use DirectDraw primary surface.
AMDDS_RGBOVR RGB overlay surfaces.
AMDDS_YUVOVR YUV overlay surfaces.
AMDDS_RGBOFF RGB off-screen surfaces.
AMDDS_YUVOFF YUV off-screen surfaces.
AMDDS_RGBFLP RGB flipping surfaces.
AMDDS_YUVFLP YUV flipping surfaces.
AMDDS_ALL All the previous flags.
AMDDS_DEFAULT Use all available surfaces.
AMDDS_YUV (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY (AMDDS_DCIPS | AMDDS_PS).

Return Value

Returns an HRESULT value.

IDirectDrawVideo::SetDefault

IDirectDrawVideo Interface

Makes the current property settings the global default.

Syntax

HRESULT SetDefault(void);

Return Value

Returns an HRESULT value.

Remarks

All properties set through IDirectDrawVideo are specific to that particular instance. Call this method to make properties set on this instance of IDirectDrawVideo the global default of all DirectShow instances of this interface. After it is called, the current property settings will persist between the subsequent starting of other DirectShow filter graphs and between any computer restarts.

IDirectDrawVideo::SetDirectDraw

IDirectDrawVideo Interface

Passes the IDirectDraw interface to a loaded driver.

Syntax

HRESULT SetDirectDraw(
    LPDIRECTDRAW pDirectDraw
);

Parameters

pDirectDraw
Pointer to the IDirectDraw interface to be passed.

Return Value

Returns an HRESULT value.

Remarks

To have the renderer release a DirectDraw interface previously passed in through SetDirectDraw, an application can call SetDirectDraw and pass in NULL. However, the renderer will continue using that DirectDraw interface until it is disconnected. Therefore, calling SetDirectDraw with a null parameter does not make the renderer stop using it immediately.
This method was created because only one instance of IDirectDraw could be loaded per process in DirectDraw 1.0. If an application wanted to load IDirectDraw but allow the renderer to also allocate surfaces, the application could open IDirectDraw itself and then pass the interface to the loaded driver through IDirectDrawVideo::SetDirectDraw. Alternatively, the application could let the renderer load DirectDraw and then obtain a reference-incremented interface to it through IDirectDrawVideo::GetDirectDraw. Because DirectShow ships with the most recently shipped version of DirectDraw, however, this method is not required unless the application wants to change display modes itself and pass in a DirectDraw object, which the renderer can then use to allocate surfaces.

IDirectDrawVideo::SetSwitches

IDirectDrawVideo Interface

Sets the surface types that the renderer is allowed to use.

Syntax

HRESULT SetSwitches(
    DWORD Switches
);

Parameters

Switches
Bit mask containing one or more of the following DirectShow DirectDraw Surface (AMDDS) surface types.

AMDDS_NONE No use for DCI/DirectDraw.
AMDDS_DCIPS Use DCI primary surface.
AMDDS_PS Use DirectDraw primary surface.
AMDDS_RGBOVR RGB overlay surfaces.
AMDDS_YUVOVR YUV overlay surfaces.
AMDDS_RGBOFF RGB off-screen surfaces.
AMDDS_YUVOFF YUV off-screen surfaces.
AMDDS_RGBFLP RGB flipping surfaces.
AMDDS_YUVFLP YUV flipping surfaces.
AMDDS_ALL All the previous flags.
AMDDS_DEFAULT Use all available surfaces.
AMDDS_YUV (AMDDS_YUVOFF | AMDDS_YUVOVR | AMDDS_YUVFLP).
AMDDS_RGB (AMDDS_RGBOFF | AMDDS_RGBOVR | AMDDS_RGBFLP).
AMDDS_PRIMARY (AMDDS_DCIPS | AMDDS_PS).

Return Value

Returns an HRESULT value.

IDirectDrawVideo::UseOverlayStretch

IDirectDrawVideo Interface

Determines whether the renderer should check overlay stretch limitations.

Syntax

HRESULT UseOverlayStretch(
    long UseOverlayStretch
);

Parameters

UseOverlayStretch
Value specifying whether the renderer checks overlay stretching. Set to OATRUE for the renderer to check overlay stretching; otherwise, set to OAFALSE.

Return Value

Returns an HRESULT value.

Remarks

Some display cards provide the use of overlay surfaces through DirectDraw. An overlay surface is a block of video memory whose contents are overlaid onto the display during the monitor's vertical refresh. DirectShow uses all available overlay surfaces where possible because they typically offer higher-quality video and very fast performance. On some display cards set to relatively high bit depths, the overlay must be displayed on the screen larger than its real size (to accommodate certain display hardware bandwidth limitations). If the overlay is not displayed large enough, certain undesirable effects can be seen on the display (sometimes described as a "fleeting shimmering" effect).
If UseOverlayStretch is set to OATRUE (on, the default), DirectShow will ensure the overlay is adequately stretched before displaying it. If it is set to OAFALSE (off), DirectShow will not check that the overlay is adequately stretched, and the user is likely to experience artifacts on the screen (although it will also guarantee that the overlay will be used if possible).

IDirectDrawVideo::UseScanLine

IDirectDrawVideo Interface

Determines whether the renderer should check the current scan line when drawing a video.

Syntax

HRESULT UseScanLine(
    long UseScanLine
);

Parameters

UseScanLine
Long integer value that specifies whether or not to use the scan line information. Set to OATRUE to use scan line information or OAFALSE to ignore it.

Return Value

Returns E_INVALIDARG if the argument is invalid or NOERROR otherwise.

Remarks

If you blit a video image to the screen while the monitor's scan line is scanning over a visible portion of the screen, the complete image will be a composite of the old and new images. This composite is known as a torn video image. You can avoid torn images by waiting until the previous image is complete before blitting the new image. Some video cards can retrieve the scan line's current position; if this information is available, you can have DirectShow try to reduce tearing by waiting until the scan line is off-screen before blitting the new image. Note that checking the scan line location increases load on the processor and can reduce the amount of video frames delivered to the screen. If scan line information is available, DirectShow uses it by default. Set UseScanLine to OAFALSE if you want to save processing time at the expense of minor image degradation.

IDirectDrawVideo::UseWhenFullScreen

IDirectDrawVideo Interface

Determines whether DirectShow should change display mode when going to full-screen mode.

Syntax

HRESULT UseWhenFullScreen(
    long UseWhenFullScreen
);

Parameters

UseWhenFullScreen
Value specifying whether to change the display mode. Set to OATRUE to cause the renderer to use DirectShow in full-screen mode; otherwise, set to OAFALSE.

Return Value

Returns an HRESULT value.

Remarks

When asked to go to full-screen mode, DirectShow has a number of choices. The first choice is to determine if any filters in the graph can support full-screen playback directly; if one can, it will be asked to do so.
The second choice is to automatically add a special full-screen renderer to the filter graph that uses DirectDraw mode-changing services to play back the video. By changing display modes, the video effectively fills more (but not necessarily all) of the display. So, for example, if the current mode is 1024 × 768 pixels, a video might look relatively small, but when displayed in a 320 × 240 display mode it might look very presentable.
The third and final choice is to simply take any renderer supporting the IVideoWindow interface and have its window stretched full-screen. This will typically offer lower performance than the second option (swapping in a full-screen DirectDraw-enabled renderer). If the UseWhenFullScreen parameter is set to On (OATRUE), the window will always be stretched full-screen for full-screen playback; if set to Off (the default), the filter graph manager is free to swap in the DirectDraw-enabled full-screen renderer.

IDirectDrawVideo::WillUseFullScreen

IDirectDrawVideo Interface

Determines whether DirectShow will change display mode when going to full-screen mode.

Syntax

HRESULT WillUseFullScreen(
    long *UseWhenFullScreen
);

Parameters

UseWhenFullScreen
Pointer to a value indicating whether DirectShow will use DirectX in full-screen mode. OATRUE indicates it will use full-screen mode; OAFALSE indicates it will not.

Return Value

Returns an HRESULT value.

Remarks

For a description of this feature, see IDirectDrawVideo::UseWhenFullScreen.

AMDDS_NONE	No use for DCI/DirectDraw.
AMDDS_DCIPS	Use DCI primary surface.
AMDDS_PS	Use DirectDraw primary surface.
AMDDS_RGBOVR	RGB overlay surfaces.
AMDDS_YUVOVR	YUV overlay surfaces.
AMDDS_RGBOFF	RGB off-screen surfaces.
AMDDS_YUVOFF	YUV off-screen surfaces.
AMDDS_RGBFLP	RGB flipping surfaces.
AMDDS_YUVFLP	YUV flipping surfaces.
AMDDS_ALL	All the previous flags.
AMDDS_DEFAULT	Use all available surfaces.
AMDDS_YUV	(AMDDS_YUVOFF \| AMDDS_YUVOVR \| AMDDS_YUVFLP).
AMDDS_RGB	(AMDDS_RGBOFF \| AMDDS_RGBOVR \| AMDDS_RGBFLP).
AMDDS_PRIMARY	(AMDDS_DCIPS \| AMDDS_PS).