IDvdGraphBuilder Interface

The IDvdGraphBuilder interface enables you to easily build a filter graph for DVD-Video playback. This interface is implemented by the CDvdGraphBuilder COM object, which is part of qdvd.dll. An application can instantiate this COM object by calling CoCreateInstance on CLSID_DvdGraphBuilder to get back a pointer to the IDvdGraphBuilder interface. The application can then build a DVD-Video playback graph by calling the RenderDvdVideoVolume method, and thus get access to DVD-specific DirectShow interfaces such as IDvdInfo and IDvdControl as well generic DirectShow interfaces such as IAMLine21Decoder, IBasicVideo, IVideoWindow, and IBasicAudio (you only need this interface if an audio renderer is used to render audio, which is not the case with most decoders). The application can also get a pointer to the filter graph created by calling the RenderDvdVideoVolume method and then calling play, stop, or pause on the title. At the end, the application should release all the interfaces acquired through IDvdGraphBuilder methods as well as the IDvdGraphBuilder interface pointer.

Generally, you should not add, remove, connect, disconnect or access individual filters in the graph created by IDvdGraphBuilder::RenderDvdVideoVolume, since doing so may 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.

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. 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, which is not the case with most decoders.

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.

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

Top of Page