Microsoft DirectX 8.0

IDvdGraphBuilder Interface

The IDvdGraphBuilder interface is implemented on the DVD Graph Builder object. The RenderDvdVideoVolume method automatically builds a filter graph for DVD-Video playback from the available software and hardware on the system. For information on how to build the DVD filter graph and obtain the pointers to all the necessary interfaces, see Building The DVD Filter Graph. The DVDSample application also demonstrates this process in DvdCore.cpp.

Note  A DVD filter graph requires either a hardware or software MPEG-2 decoder, which DirectShow does not provide. You must install a DirectShow-compatible third-party decoder on your computer before attempting to build the DVD filter graph.

Generally, you should not add, remove, connect, disconnect, or access individual filters in the graph created by RenderDvdVideoVolume, because doing so might confuse the cleanup code. The purpose of the DvdGraphBuilder object is to simplify the developement of DVD-Video applications. If you need a specific type of graph for a particular solution, you should manually create the entire filter graph.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IDvdGraphBuilder methodsDescription
GetFiltergraph Retrieves the IGraphBuilder interface for the filter graph used by the DVD-Video graph builder object.
GetDvdInterface Retrieves specific interface pointers in the DVD-Video playback graph to make DVD-Video playback development easier.
RenderDvdVideoVolume Completes building a filter graph according to user specifications for playing a DVD-Video volume.

IDvdGraphBuilder::GetDvdInterface

IDvdGraphBuilder Interface

Retrieves specific interface pointers in the DVD-Video playback graph to make DVD-Video playback development easier.

Syntax

HRESULT GetDvdInterface(
    REFIID riid,
    void **ppvIF
    );

Parameters

riid
[in] IID of the required interface.
ppvIF
[out] Address of a pointer to the retrieved interface.

Return Value

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

The DirectShow implementation return values include the following:
E_INVALIDARG The ppvIF parameter is invalid.
E_NOINTERFACE The riid parameter value is not supported.
VFW_E_DVD_GRAPHNOTREADY The graph has not been built through the IDvdGraphBuilder::RenderDvdVideoVolume method before retrieving this interface.

Remarks

Use this method to get the IDvdControl2 and IDvdInfo2 interfaces to control playback of a DVD-Video volume, and to get the IAMLine21Decoder interface to turn closed captioning on and off. You also use this method to get the IBasicVideo, IVideoWindow, and IBasicAudio interfaces. You only need a pointer to IBasicAudio if an audio renderer is used to render audio.

Remember to release the interface when you're done by using the following code.

*ppvIF->Release();

The IMixerPinConfig2 interface can be retrieved from the first input pin (primary video stream) of the Overlay Mixer in the DVD-Video playback graph using this interface. The IDDrawExclModeVideo interface can also be retrieved from the Overlay Mixer in the DVD-Video playback graph. This interface is required to playback video in DirectDraw exclusive mode, as some games require. Unlike other interfaces, it is not necessary to build the graph using the RenderDvdVideoVolume method before calling GetDvdInterface. This interface should be retrieved before using the RenderDvdVideoVolume method to build the graph.

IDvdGraphBuilder::GetFiltergraph

IDvdGraphBuilder Interface

Retrieves the IGraphBuilder interface for the filter graph used by the DVD-Video graph builder object.

Syntax

HRESULT GetFiltergraph(
    IGraphBuilder **ppGB
    );

Parameters

ppGB
[out] Address of a pointer to the IGraphBuilder interface that the DVD-Video graph builder object is using.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation returns E_INVALIDARG if ppGB is invalid.

Remarks

Remember to release the IGraphBuilder interface when you're done by using the following code.

*ppGB->Release();

IDvdGraphBuilder::RenderDvdVideoVolume

IDvdGraphBuilder Interface

Completes building a filter graph according to user specifications for playing a DVD-Video volume.

Syntax

HRESULT RenderDvdVideoVolume(
    LPCWSTR lpcwszPathName,
    DWORD dwFlags,
    AM_DVD_RENDERSTATUS *pStatus
    );

Parameters

lpcwszPathName
[in] Pointer to the path for the DVD-Video volume to play. Can be NULL.
dwFlags
[in] Member of the AM_DVD_GRAPH_FLAGS enumerated data type indicating the type of decoder—hardware or software or a mix of hardware and software) to include in the filter graph. Maximum hardware decoding (AM_DVD_HWDEC_PREFER) is the default.
pStatus
[out] Pointer to the retrieved AM_DVD_RENDERSTATUS structure, which returns indication of any failure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface. The DirectShow implementation return values include the following:
E_INVALIDARG The dwFlags parameter specifies conflicting options, or pStatus is a bad pointer.
S_FALSE Graph has been built, but not perfectly. The pStatus parameter provides details of the problems.
S_OK Success. Playback graph built successfully, all streams rendered, and the DVD-Video volume was specified or found.
VFW_E_DVD_DECNOTENOUGH AM_DVD_HWDEC_ONLY or AM_DVD_SWDEC_ONLY was specified and there weren't enough hardware or software decoders to decode all streams.
VFW_E_DVD_RENDERFAILSome basic error occurred in building the graph. Possibilities include the DVD Navigator filter or the video or audio renderer not instantiating, a trivial connection or pin enumeration failing, or none of the streams rendering.

Remarks

The AM_DVD_RENDERSTATUS structure reflects failure codes for this method. Reasons for this method returning S_FALSE include the following:

This method builds the graph without any knowledge of the DVD-Video file or volume to play. The DVD-Video graph builder builds the graph even if lpcwszPathName is NULL or if the DVD Navigator filter does not find a default DVD-Video volume to play. An application can later specify the volume by using the IDvdControl::SetRoot method.