## IDvdGraphBuilder Interface

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

When to Implement

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

When to Use

Use this interface in your application to build a filter graph for DVD-Video playback.

Methods in Vtable Order

IUnknown methods | Description
QueryInterface | Returns 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.

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 Values

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

The current DirectShow implementation return values include the following:

Value | Meaning
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.

##### Remarks

You'll 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.

Remember to release the interface by using the following code when you're done with it:

    *ppvIF->Release();

###

IDvdGraphBuilder::GetFiltergraph

IDvdGraphBuilder Interface

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

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 Values

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.

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

##### Parameters

lpcwszPathName
  [in] Path name 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 Values

Returns an HRESULT value that depends on the implementation of the interface. The current DirectShow implementation return values include the following:

Value | Meaning
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_DVDDEC_NOTENOUGH | 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_DVDGRAPH_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.
  - VPE mixing doesn't work (application didn't use the AM_DVD_NOVPE flag). In this case, the application will have enough information to tell the user that the video won't be visible unless a TV is connected to the NTSC out port of the DVD-Video decoder (presumably hardware decoder in this case).
  - Video decoder doesn't produce Line21 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 lpwszPathName 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.

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