DirectShow Animated Header -- IDvdGraphBuilder Interface DirectShow Animated Header -- IDvdGraphBuilder Interface* Microsoft DirectShow SDK
*Index  *Topic Contents
*Previous Topic: IDvdControl Interface
*Next Topic: IDvdInfo Interface

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:

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