IDirectDrawVideo Interface

This interface is on the video renderer and provides information about Microsoft® DirectDraw® with respect to its use by the renderer. For example, the interface allows an application to get details of the surface and any available hardware capabilities. It also allows 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 allows simple access to that information without calling the DirectDraw provider directly.

DirectDraw is not loaded by the renderer 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.

When to Implement

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

When to Use

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 are allowed to 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	Returns 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 might 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.

HRESULT CanUseOverlayStretch(
  long * UseOverlayStretch
  );

Parameters

UseOverlayStretch

Set to OATRUE if the renderer can use overlay stretching; otherwise, set to OAFALSE.

Return Values

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.

HRESULT CanUseScanLine(
  long * UseScanLine
  );

Parameters

UseScanLine

Set to OATRUE if the renderer can use scan line information; otherwise, set to OAFALSE.

Return Values

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.

HRESULT GetCaps(
  DDCAPS *pCaps
  );

Parameters

pCaps

DDCAPS structure containing the hardware capabilities.

Return Values

Returns an HRESULT value.

Remarks

If the renderer has not loaded DirectDraw, this method returns E_FAIL. DirectDraw is not loaded by the renderer until it is connected, and likewise is unloaded only when the renderer is disconnected.

---

IDirectDrawVideo::GetDirectDraw

IDirectDrawVideo Interface

Retrieves the IDirectDraw interface.

HRESULT GetDirectDraw(
  LPDIRECTDRAW *ppDirectDraw
  );

Parameters

ppDirectDraw

IDirectDraw interface.

Return Values

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.

HRESULT GetEmulatedCaps(
  DDCAPS *pCaps
  );

Parameters

pCaps

DDCAPS structure containing the emulated capabilities.

Return Values

Returns an HRESULT value.

Remarks

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

---

IDirectDrawVideo::GetFourCCCodes

IDirectDrawVideo Interface

Retrieves the multimedia format type.

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

Parameters

pCount

Number of FOURCC codes in the pCodes array.

pCodes

Array of DWORD media tags formerly used for Microsoft multimedia types.

Return Values

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.

HRESULT GetSurfaceDesc(
  DDSURFACEDESC *pSurfaceDesc
  );

Parameters

pSurfaceDesc

DDSURFACEDESC structure describing the current DirectDraw surface.

Return Values

Returns an HRESULT value.

Remarks

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. Surfaces are allocated only when the renderer is paused. Once 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.

HRESULT GetSurfaceType(
  DWORD *pSurfaceType
  );

Parameters

pSurfaceType

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 AMDDS_ALL	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 Values

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.

HRESULT GetSwitches(
  DWORD *pSwitches
  );

Parameters

pSwitches

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 AMDDS_ALL	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 Values

Returns an HRESULT value.

---

IDirectDrawVideo::SetDefault

IDirectDrawVideo Interface

Makes the current property settings the global default.

HRESULT SetDefault( );

Return Values

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

HRESULT SetDirectDraw(
  LPDIRECTDRAW pDirectDraw
  );

Parameters

pDirectDraw

IDirectDraw interface to be passed.

Return Values

Returns an HRESULT value.

Remarks

To have the renderer release a DirectDraw interface previously passed in through SetDirectDraw, an application can call SetDirectDraw, passing 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.

HRESULT SetSwitches(
  DWORD pSwitches
  );

Parameters

pSwitches

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 AMDDS_ALL	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 Values

Returns an HRESULT value.

---

IDirectDrawVideo::UseOverlayStretch

IDirectDrawVideo Interface

Determines whether the renderer should check overlay stretch limitations.

HRESULT UseOverlayStretch(
  long UseOverlayStretch
  );

Parameters

UseOverlayStretch

Set to OATRUE for the renderer to use overlay stretching; otherwise, set to OAFALSE.

Return Values

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 On (the default), DirectShow will ensure the overlay is adequately stretched before displaying it. If it is set to 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.

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 Values

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 offscreen 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 might change display mode when going to full-screen mode.

HRESULT UseWhenFullScreen(
  long UseWhenFullScreen
  );

Parameters

UseWhenFullScreen

Set to OATRUE to cause the renderer to use DirectX in full-screen mode; otherwise, set to OAFALSE.

Return Values

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 x 768 pixels, a video might look relatively small, but when displayed in a 320 x 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.

HRESULT WillUseFullScreen(
  long * UseWhenFullScreen
  );

Parameters

UseWhenFullScreen

Set to OATRUE if DirectShow is set to use DirectX in full-screen mode; otherwise, set to OAFALSE.

Return Values

Returns an HRESULT value.

Remarks

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

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

Top of Page