IDvdGraphBuilder Interface

The IDvdGraphBuilder interface enables you to easily build a filter graph for DVD-Video playback.

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.

An application creates an instance of the DvdGraphBuilder object by calling CoCreateInstance using CLSID_DvdGraphBuilder, which returns a pointer to the IDvdGraphBuilder interface. The application can then build a DVD-Video playback graph by calling the RenderDvdVideoVolume method. Then, by calling GetFiltergraph through the IDvdGraphBuilder interface pointer, the application gets a pointer to the filter graph itself, with which you obtain the various interfaces your application will use to control DVD navigation, playback and display options. These interfaces include IDvdInfo and IDvdControl, as well as interfaces such as IAMLine21Decoder, IBasicVideo, IVideoWindow, and IBasicAudio (you only need this interface if an audio renderer is used). At the end, the application should release all the interfaces acquired through IDvdGraphBuilder methods as well as the IDvdGraphBuilder interface pointer. The basic steps in the DVD graph building process are illustrated in the following code snippets taken from the DirectShow sample application, Dvdsampl.

     // Instantiate the DVD Graph Builder object.
     HRESULT hr = CoCreateInstance(CLSID_DvdGraphBuilder, NULL, CLSCTX_INPROC, 
                    IID_IDvdGraphBuilder, (LPVOID *)&m_pDvdGB) ;
                    
     // Build the DVD filter graph.
     HRESULT hr = m_pDvdGB->RenderDvdVideoVolume(lpszwFileName,
				    m_dwRenderFlag, &Status) ;

     // Get a pointer to it.
     hr = m_pDvdGB->GetFiltergraph(&m_pGraph) ;
     
     // Use the graph pointer to get a pointer to IMediaControl.
     // (used for controlling the filter graph as a whole)
     hr = m_pGraph->QueryInterface(IID_IMediaControl, (LPVOID *)&m_pMC) ;
      
     // Get a pointer to IMediaEventEx.
     hr = m_pGraph->QueryInterface(IID_IMediaEventEx, (LPVOID *)&m_pME) ;
     
     // Use the IMediaEventEx pointer to set up event notifications
     // (i.e. EC_DVD_DOMAIN_CHANGE) to be sent to the main window.
     hr = m_pME->SetNotifyWindow((OAHWND) m_hWnd, WM_DVDPLAY_EVENT, 
                     (ULONG)(LPVOID)m_pME) ;
                     
     // Now use the graph builder pointer again to get the 
     // DVD-specific interfaces for navigation and playback.
     hr = m_pDvdGB->GetDvdInterface(IID_IDvdControl, (LPVOID *)&m_pDvdC) ;
     hr = m_pDvdGB->GetDvdInterface(IID_IDvdInfo, (LPVOID *)&m_pDvdI) ;  
     hr = m_pDvdGB->GetDvdInterface(IID_IAMLine21Decoder, (LPVOID *)&pL21Dec) ;

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. This interface is intended to help develop DVD-Video playback applications easily. If you need a very specific type of graph built for a particular solution, you should build a custom graph rather than use this interface and then change the resulting filter graph.

Do not implement this interface. The DirectShow DVD-Video graph builder object implements it for you.

Methods in Vtable Order

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

IDvdGraphBuilder methods Description
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 back a DVD-Video volume.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IDvdGraphBuilder methods	Description
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 back 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 current 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 Graph has not been built through the IDvdGraphBuilder::RenderDvdVideoVolume method before retrieving this interface.

Remarks

You typically use this method to get the IDvdControl interface to control playback of a DVD-Video volume, or to get the IAMLine21Decoder interface to turn closed captioning on and off. You also use this method to get the IDvdInfo, 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 by using the following code when you're done with it.
*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 by using the following code when you're done with it.
*ppGB->Release();

IDvdGraphBuilder::RenderDvdVideoVolume

IDvdGraphBuilder Interface

Completes building a filter graph according to user specifications for playing back 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 current 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 problem(s).
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_RENDERFAIL Some 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:

The graph has been completely built, but one of the following is true.

Overlay mixing doesn't work (application didn't use the AM_DVD_NOVPE flag and somehow the video stream couldn't be put through the Overlay Mixer). In this case, the application will have enough information to tell the user that the video won't be visible at all if the video is decoded in software while hardware decoded video could be seen only on a TV connected to the NTSC out port of the hardware video decoder.
Video decoder doesn't produce line 21 data. The application can put up a warning or informative message that closed captioning is not available because of the decoder.
No volume path specified and DVD Navigator didn't locate any DVD-Video volume to be played. Application can ask the user to insert a DVD-Video disc, if none is available in the drive when playback is started.

Some streams didn't render or didn't render completely. Volume can be partially played back. The application can indicate to the user that some of the streams can't be played.

This method builds the graph without any knowledge of the DVD-Video file or volume to play back. 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 back. An application can later specify the volume by using the IDvdControl::SetRoot method.

E_INVALIDARG	The ppvIF parameter is invalid.
E_NOINTERFACE	The riid parameter value is not supported.
VFW_E_DVD_GRAPHNOTREADY	Graph has not been built through the IDvdGraphBuilder::RenderDvdVideoVolume method before retrieving this interface.

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 problem(s).
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_RENDERFAIL	Some 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.