Frequently Asked Questions

For an overview of these Microsoft technologies as well as many others, see http://www.microsoft.com/directx/.

DirectShow supports Microsoft® Windows® 9x, Microsoft® Windows NT® version 4.x, and Windows® 2000.

No. DirectShow uses all DirectDraw and DirectSound hardware capabilities where they are available. Where no special hardware is available, DirectShow uses GDI to draw video and the waveOut* multimedia APIs to play back audio.

DirectShow supports the following formats.

• MIDI (.mid)
• MPEG-1 (.mpg, .mpeg, .mpv, .mp2, .mpa, .mpe)
• Audio-Video Interleaved (.avi)
• Apple® QuickTime® files (.qt, .mov), version 2 and earlier
• WAV (.wav)
• AU (.au, .snd)
• AIFF (.aif, .aifc, .aiff)
• MPEG Audio Layer-3 (.mp3)
• Advanced Streaming Format (.asf)
• Windows Media Audio (.wma)

One source is Encyclopedia of Graphics File Formats, second edition, by James D. Murray and William vanRyper, published by O'Reilly & Associates, Inc. That book describes MPEG-1, AVI, and some QuickTime file formats. See AVI 2.0 File Format Extensions for more information about DirectShow support of this format.

Yes, DirectShow provides video capture.

DirectShow is designed for Internet Explorer 3.x and later.

For information on the HTML tags to use to play movies using DirectShow, see the Microsoft® Windows Media™ Player control documentation.

The DirectX Media SDK includes sample source code in C, C++, and Microsoft® Visual Basic®. For more information, see DirectShow Samples.

DirectShow was designed with Microsoft® Visual C++® 5.x in mind, but any compiler capable of generating Component Object Model (COM) objects should work once the compiler's environment has been configured correctly. The base class libraries might need to be rebuilt to work completely since compilers can vary between versions.

No. After DirectShow is installed, double-click any media file to view it. If you want more specialized applications, you can program DirectShow by using either C/C++ (in which case a compiler is required) or any Automation-compatible language (such as Visual Basic).

DirectShow will be included in the next and future versions of Windows.

No, the source is not available.

Windows 2000 built on NT technology supports DirectX Foundation 5.x, including DirectDraw, Microsoft® DirectPlay®, DirectSound, Microsoft® Direct3D®, and Microsoft® DirectInput®. Windows NT 4.x supports DirectDraw, DirectPlay, and DirectSound.

Several books from Microsoft Press, including Advanced Windows by Jeffrey Richter and Understanding ActiveX and OLE by David Chappell, make great references for DirectShow developers.

A globally unique identifier (GUID) is a 128-bit (16-byte) integer that an algorithm creates. The algorithm uses several criteria, including the current date, time, and a machine identifier, to ensure that it will be unique. GUIDs are used extensively in the Component Object Model (COM) and have an important role in DirectShow.

GUIDs can be generated using Guidgen.exe. Guidgen, a Windows-native program, is included with Microsoft's Visual C++® products. Developers can also use Uuidgen.exe, a console application, in the Platform SDK.

Whenever you need to obtain an interface for an object.

Some typical problems involving COM are:

• Forgetting to create a new GUID is a very common problem in filter development. For example, if you create a new filter based on one of the sample filters, you must create a new GUID for your filter. Otherwise, when you install your filter, it will overwrite the information that was already registered for the sample filter. Create a new GUID by using the Guidgen.exe tool.
• Omitting the address of (&) operator in the last parameter of a call to QueryInterface or CoCreateInstance causes an exception when trying to use the object specified in that last parameter. The problem can be difficult to debug, because the void cast required prevents a compiler warning. The following example shows both the bad and the good syntax in a call to QueryInterface.

  IUnknown *pUnk;
  
  // Bad -- you will hit an exception when you try to use pUnk
  // HRESULT hr = pObject->QueryInterface(IID_IPersist, 
  //                                     (void **)pUnk); // <-- bad
  
  // Good -- note the '&' is required for the last parameter
  HRESULT hr = pObject->QueryInterface(IID_IPersist, 
                                       (void **)&pUnk); // <-- good
  
  

No. It's safe to install the DirectX Media 6 run time, then the DirectX Foundation 6.x run time, and then reboot once at the end if either run-time install indicated that a reboot was required.

The SDK includes a redistributable package under the Redist directory.

No, the source is not available, and Graphedt.exe is not redistributable.

The Microsoft® DirectX® Media Software Development Kit (SDK) includes a redistributable package under the Redist directory. The Microsoft DirectX® Media redistributable package is Dxmedia.exe. Dxmedia.exe supports two command-line switches, which are: -NQ and -id:. The required -id: switch must be followed by a unique identifier for the application. The optional -NQ switch enables the user interface. If used, the -NQ switch must come before the -id switch on the command line, and the letters "N" and "Q" must be capitalized. If the -NQ switch is not used, the installation is totally quiet, and no dialog boxes appear.

An example is shown in the following command line.

dxmedia.exe -NQ -id:identifier

The identifier should uniquely identify your application. The identifier can be the GUIDs of your registered application or a unique string. You should not use a string such as "game", but instead use a more distinctive string. For example:

dxmedia.exe -NQ -id:myrocketgame

- or -

dxmedia.exe -NQ -id:my_GUID

- or -

dxmedia.exe -id:my_GUID

The identifier is required. If you run Dxmedia.exe without using any switches, or double-click on the Dxmedia.exe icon, nothing will be installed.

The same syntax is used for all platforms: Microsoft Windows® 9x, Windows 2000, and Windows® NT® x86.

If successful, the installation returns one of the following success codes.

• ERROR_SUCCESS—installation was successful.
• ERROR_SUCCESS_REBOOT_REQUIRED—installation was successful, but changes will not be effective until the system is rebooted.

Note: If you are installing both DirectX Media 6 and DirectX Foundation 6.x, you do not have to reboot between installs. It's safe to install the DirectX Media 6 run time, then the DirectX Foundation 6.x run time, and then reboot once at the end if either run-time install indicated that a reboot was required.

If unsuccessful, the installation returns an HRESULT describing the error. Possible common errors include E_FAIL, which might be caused by a corrupt file.

The install package automatically handles different versions during installation. Files are only overwritten if they are older than the files about to be installed.

In addition to installing the core DirectX media run time, the DirectX media redistributable package installs a minimal version of DirectX foundation version 3.0 on systems that do not meet the minimum DirectX media requirements. The application can install DirectX foundation separately if the full installation is needed after the redistributable package has been installed.

No, but it must be unique. GUIDs are essentially guaranteed to be unique.

Yes, automatically. Files are only overwritten (after backup) if they use the same platform and are older than the files about to be installed.

It installs the DirectX media run-time components. It also installs a minimum version of DirectX foundation on Windows 9x x86, as appropriate. The application can install DirectX foundation separately if the full installation is needed, after the redistributable package has been installed.

Use the following code fragment to detect whether DirectShow is installed. It assumes that you have already included the Streams.h header file and initialized the COM subsystem by using the CoInitialize function with a null parameter. It also assumes that you will uninitialize COM by using the CoUninitialize function before closing your application.

IGraphBuilder * lpAMovie;

HRESULT hr = CoCreateInstance(
	CLSID_FilterGraph,
	0,
	CLSCTX_INPROC_SERVER,
	IID_IGraphBuilder,
	(void **) &lpAMovie );


if (SUCCEEDED(hr)) {
    lpAMovie->Release();
    // DirectShow is installed
} else {
    // DirectShow is not installed
}

IGraphBuilder, IMediaEvent, IMediaControl, and IVideoWindow.

Use the IVideoWindow::put_Owner method.

Use IVideoWindow::put_Owner to specify the window you want. Set the style of the video window to include WS_CHILD using the IVideoWindow::put_WindowStyle method, and then position the video window inside your window using the IVideoWindow::SetWindowPosition method. The following sample code demonstrates this process.

#include <windows.h>
#include <streams.h>

#define FILENAME L"C:\\WIN95.AVI"

void PlayVideoInWindow(HWND hTargetWindow)

{   // PlayVideoInWindow //

    CoInitialize(NULL);

    HRESULT hr;
    IGraphBuilder *pigb;

    // Create an empty filter graph object
    hr = CoCreateInstance(CLSID_FilterGraph,
        NULL,
        CLSCTX_INPROC_SERVER,
        IID_IGraphBuilder,
        (void **)&pigb);

    if (FAILED(hr))
        return;

    hr = pigb->RenderFile(FILENAME, NULL);

    if (FAILED(hr)) {
        pigb->Release();
        return;
        }   // Bail out, file probably wasn't found! //

    RECT rc;
    IVideoWindow *pivw;

    hr = pigb->QueryInterface(IID_IVideoWindow, (void **)&pivw);
    pivw->put_Owner((OAHWND)hTargetWindow);

    // Here's the key: we must set the required flags, 
    //   AND set the position
    pivw->put_WindowStyle(WS_CHILD | WS_CLIPCHILDREN | WS_CLIPSIBLINGS);
    GetClientRect(hTargetWindow, &rc);
    pivw->SetWindowPosition(rc.left, rc.top, rc.right rc.bottom);

    IMediaControl *pimc;

    hr = pigb->QueryInterface(IID_IMediaControl, (void **)&pimc);

    long l;
    IMediaEvent *pime;

    hr = pigb->QueryInterface(IID_IMediaEvent, (void **)&pime);
    pimc->Run();

    pime->WaitForCompletion(INFINITE, &l);

    // The following MUST be called otherwise nasty things can happen!
    pivw->put_Owner(NULL);

    pime->Release();
    pimc->Release();
    pivw->Release();
    pigb->Release();

    CoUninitialize();

}   // PlayVideoInWindow 

You need to specify the WS_CLIPCHILDREN style for the video window's owner.

    Error LNK2001: unresolved external symbol IID_IGraphBuilder

The symbols are defined in Strmiids.lib, which is one of the libraries located in the Lib directory. You need to link this library into your project. For information on how to do this in Microsoft Developer Studio, see Build a Filter or Application with Visual C++ 5.x. The VC5KIT kit in the Tools directory also describes how to configure Developer Studio to build DirectShow-based applications.

The error return codes specific to DirectShow are found in Vfwmsgs.h, located in the DirectX Media SDK Include directory. More general errors, such as error codes returned by CoCreateInstance, can be found in \Msdev\Include\Winerror.h if you have Microsoft Developer Studio. Vfwmsgs.h and Winerror.h also provide information about the layout of HRESULT values. Before you search for a particular error in Winerror.h, you might need to convert the low portion to decimal, depending on the error.

Calls to DirectShow object methods and properties can return error codes; these codes are stored in (and can be retrieved from) the Number property of the Err object. Error numbers can be returned in one of two forms: an DirectShow error or a Visual Basic run-time error code. DirectShow errors are referred to by number, starting at 0x80040200 (2147746304 in decimal). You can look up the error number by its hexadecimal value in the Include\Vfwmsgs.h header file. When Visual Basic can interpret the external object error, it generates a Visual Basic run-time error. For example, the E_INVALIDARG return code from an interface generates Visual Basic run-time error 5, "remote procedure call failed". In cases when Visual Basic cannot interpret a system error (such as E_ABORT), error 287 is returned in the Err object.

The E_NOTIMPL return value indicates that no filter is in the graph that supports IVideoWindow. In other words, your graph does not contain a video renderer. One solution is to call the IGraphBuilder::Render method and allow the filter graph manager to automatically insert any necessary filters and complete the filter graph.

The VFW_E_NOT_CONNECTED return value indicates that the video renderer's input pin is not connected.

You can turn off the controls and display programmatically by setting the ShowControls and ShowDisplay properties to FALSE (0). For example, to do this using <PARAM> tags:

<PARAM NAME="ShowControls" Value="False">
<PARAM NAME="ShowDisplay" Value="False">

Enumerators are COM objects created to traverse an ordered set. The application or filter can call a method such as IEnumPins::Next to obtain an item from the set. Enumerators are usually matched to the data type they retrieve. In DirectShow, there are different enumerators to retrieve items such as filters, pins, and media types.

If the filter exposes a custom interface for this purpose, you can access the filter properties. The DirectX Media SDK includes a sample called Contrast, which exposes methods such as get_ContrastLevel and put_ContrastLevel to enable you to change its properties programmatically. For more details, see the implementation of Contrast's property page. You can find a description of the Contrast filter in About Effect Filters and Contrast Sample (Video Contrast Filter).

Currently, the MPEG audio codec does not enable you to set its properties programmatically.

There is no callback notification of position. Use a timer and poll for the current position by using the IMediaSeeking::GetCurrentPosition method.

Alter the time stamps instead of changing the frame rate.

You can write DirectShow filters in any language that can generate objects adhering to the Microsoft Component Object Model (COM). The base classes for DirectShow are written in C++.

The DirectShow class library is totally independent of MFC and contains most of the base classes you might need for filter development. For information on how to build DirectShow applications with Visual C++, see Build a Filter or Application with Visual C++ 5.x. You can use the VC5Kit located in the Tools directory for assistance in building these applications.

Source filters form the point of origin for data, while rendering filters present the data in a final format on various devices such as a video card, audio card, disk file, and so on. Transform filters manipulate, modify, or alter the data in some way.

For information about how to install (self-register) a filter, see Register DirectShow Objects and the IAMovieSetup interface.

You can install the filter anywhere you want, because the filter registration process records the filter's full path and file name at the time of registration. There is no need to put your filter in the Windows System or System32 directory.

The Filter Graph Editor (Graphedt.exe) displays this message when it can't find the filter's .ax file. The filter has probably been moved, renamed, deleted, or was not properly set up. It needs to be properly registered. For information about how to self-register a filter, see Register DirectShow Objects and the IAMovieSetup interface.

The minimum resolution is 100 nanoseconds.

Yes, but to take advantage of the "plug-in" nature of DirectShow, it is best to use different combinations of filters chained together. This also provides easier code reuse and flexibility in design, and is strongly recommended.

Yes. Ensure that you implement the IPin::QueryInternalConnections method on every pin. Without this, the graph builder will assume that each input pin streams through to every output pin. While you can have a filter with many input and output pins, it's often more desirable to have several filters. Otherwise, you might find yourself writing more code (overriding more and more functions from the base classes) than if you just use an individual filter for each stream.

This is the default behavior. Implement the IPin::QueryInternalConnections method on every pin to avoid this.

No, filters are integrated with the DirectShow architecture and require a filter graph.

Call the IBaseFilter::EnumPins method, and then keep calling the IEnumPins::Next method until you don't get any more pins.

Filters in DirectShow run at user-privilege level three (ring three on x86 processors).

Filters typically communicate with one another through their pins. Pins negotiate a common format and transport for exchanging data.

GraphEdit was designed to help filter developers visualize the connections and interaction between filters during filter development. It is not meant as a robust test platform.

DirectShow pins are not designed to have their direction changed. You could create two pins, one for each direction, and use a single piece of code to drive both pins.

Codec filters are only required by the renderer if the audio driver does not support a given audio format. Renderers often query the audio driver inside CheckMediaType to determine if the proposed format is supported, and if supported, pass the media samples directly to the audio subsystem when the graph is run. If the driver incorrectly indicates a format is supported, the most obvious symptom is garbled audio. You then need to get corrected drivers from your audio board manufacturer.

If you want your source filter to be recognized like the DirectShow file and URL source filters, then use the following method.

Refer to your object using some protocol name you make up (for example, ABC). Add an entry in the registry under HKEY_CLASSES_ROOT\ABC, specifying the CLSID of your source filter. Your source filter will be used for your fictional ABC protocol, much like HTTP is used for Internet addresses.

If you want your capture filter to show up in the list of devices in a video capture application, see Write a Video Capture Filter.

Use a special file to start up your filter with a known set of bytes (for example, a UUID you define yourself). Add the necessary check bytes to the registry under HKEY_CLASSES_ROOT\Media Type, making up your own major type, or stick with MEDIATYPE_Stream as other filters do and specify the proper subtype. Put your filter's CLSID in the Source Filter value. Check bytes are (decimal start, decimal length, mask (default all FF), hex value) so for a CLSID at the start you want (0, 36, , your CLSID). For more information, see Registering a Custom File Type.

The DDrawXcl sample (DirectDraw exclusive mode video playback application) uses the Overlay Mixer filter to overlay graphics on video. For this to happen successfully, overlay surfaces need to be created and the video frames and fields need to be handled directly by the application. The Overlay Mixer does this through the IDDrawExclModeVideo interface.

The most probable reasons for the DDrawXcl sample failing to play back a media file are the following.

• The file does not render properly, even in the Filter Graph Editor (Graphedt.exe).
• The display card cannot create an overlay surface (Overlay Mixer creation in Graphedt.exe fails).
• The video decoder is not connected to the Overlay Mixer filter. Possible causes include a bug in the decoder filter, an unacceptable output format offered by the decoder to the display driver (for example, CRAM codec gives only RGB8 format, for which many display cards cannot create overlay surfaces), or a lack of video memory.

Use the following tests to target the problem.

• Drag the media file into Graphedt.exe. If all streams do not render correctly, your system cannot play the file, DDrawXcl or otherwise.
• Instantiate the Overlay Mixer in the graph. If this fails, the display hardware or driver does not support overlay surfaces.
• Disconnect the video renderer filter's connection to the upstream video decoder filter. Try to connect the video decoder filter's output pin to the Overlay Mixer's first input pin. If this fails, note the error message shown by Graphedt.exe.
• Connect the output pin of the Overlay Mixer to the input pin of the video renderer. If this works, your problem should be solved.

Note The chance of successful rendering is always greater with an MPEG-1 file using the DDrawXcl sample, because all Pentium systems with DirectShow can render MPEG-1 with a decoder that works well with the Overlay Mixer filter.