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. |
Determines whether the renderer will check overlay restrictions.
HRESULT CanUseOverlayStretch(
long * UseOverlayStretch
);
Returns an HRESULT value.
For a description of overlay stretching, see IDirectDrawVideo::UseOverlayStretch.
Determines whether the renderer will check the current scan line when drawing.
HRESULT CanUseScanLine(
long * UseScanLine
);
Returns an HRESULT value.
For a description of the use of scan line detection in the DirectShow video renderer, see IDirectDrawVideo::UseScanLine.
Retrieves a DirectDraw-defined DDCAPS structure containing the hardware capabilities.
HRESULT GetCaps(
DDCAPS *pCaps
);
Returns an HRESULT value.
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.
Retrieves the IDirectDraw interface.
HRESULT GetDirectDraw(
LPDIRECTDRAW *ppDirectDraw
);
Returns an HRESULT value.
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.
Retrieves a DirectDraw-defined DDCAPS structure containing the emulated capabilities.
HRESULT GetEmulatedCaps(
DDCAPS *pCaps
);
Returns an HRESULT value.
If the renderer has not loaded DirectDraw, this method returns E_FAIL.
Retrieves the multimedia format type.
HRESULT GetFourCCCodes(
DWORD *pCount,
DWORD *pCodes
);
Returns an HRESULT value.
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.
Retrieves a DDSURFACEDESC structure describing the current DirectDraw surface.
HRESULT GetSurfaceDesc(
DDSURFACEDESC *pSurfaceDesc
);
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. Surfaces are allocated only when the renderer is paused. Once the renderer has been paused, it cannot release the surfaces when stopped.
Retrieves the actual surface type as a DirectShow DirectDraw Surface (AMDDS) definition.
HRESULT GetSurfaceType(
DWORD *pSurfaceType
);
| 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). |
Returns an HRESULT value.
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.
Retrieves the surface types that the renderer is allowed to use.
HRESULT GetSwitches(
DWORD *pSwitches
);
| 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). |
Returns an HRESULT value.
Makes the current property settings the global default.
HRESULT SetDefault( );
Returns an HRESULT value.
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.
Passes the IDirectDraw interface to a loaded driver.
HRESULT SetDirectDraw(
LPDIRECTDRAW pDirectDraw
);
Returns an HRESULT value.
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.
Sets the surface types that the renderer is allowed to use.
HRESULT SetSwitches(
DWORD pSwitches
);
| 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). |
Returns an HRESULT value.
Determines whether the renderer should check overlay stretch limitations.
HRESULT UseOverlayStretch(
long UseOverlayStretch
);
Returns an HRESULT value.
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).
Determines whether the renderer should check the current scan line when drawing a video.
HRESULT UseScanLine(
long UseScanLine
);
Returns E_INVALIDARG if the argument is invalid or NOERROR otherwise.
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.
Determines whether DirectShow might change display mode when going to full-screen mode.
HRESULT UseWhenFullScreen(
long UseWhenFullScreen
);
Returns an HRESULT value.
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.
Determines whether DirectShow will change display mode when going to full-screen mode.
HRESULT WillUseFullScreen(
long * UseWhenFullScreen
);
Returns an HRESULT value.
For a description of this feature, see IDirectDrawVideo::UseWhenFullScreen.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.