Microsoft DirectX 8.0 |
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 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 a DVD-Video volume.
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.
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();
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 decoderhardware 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_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 workthe application didn't use the AM_DVD_NOVPE flag and the video stream couldn't be put through the Overlay Mixer. In this case, if the video is decoded in software the application will have enough information to inform the user that the video won't be visible. Hardware-decoded video will be visible 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 display a warning or informative message that closed captioning is not available because of the decoder.
- No volume path is specified and DVD Navigator didn't locate any DVD-Video volume to be played. The application can ask the user to insert a DVD-Video disc if none is available in the drive when playback starts.
- 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 streams can't be played.
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.