GraphEdit Help

GraphEdit Help

  • Introduction to GraphEdit
  • Building Filter Graphs
  • Saving and Loading Filter Graphs
  • Filter Graph Operations
  • Viewing Filter Graph Information
© 2000-2002 Microsoft Corporation. All rights reserved.


Introduction to GraphEdit

GraphEdit is a visual tool for building and testing filter graphs. It is provided as an executable with the DirectX SDK. With GraphEdit, you can quickly build and test filter graphs to see if they function as you expect. You can even view a filter graph created by an application running in another process.

The following illustration shows a simple filter graph as it appears in GraphEdit.

Filter Graph in GraphEdit

Filters are displayed as boxes, with a text caption showing the name of the filter. Pins appear as small squares along the edge of the filter. Input pins are shown on the left side of the filter, and output pins are on the right side of the filter. A pin connection appears as an arrow connecting the output pin to the input pin.

GraphEdit uses a custom persistence format. This format is not supported for application use, but it is helpful for testing and debugging your application.

Note The GraphEdit source code is not provided, and you may not redistribute the executable.


Building Filter Graphs

  • Build a File Playback Graph
  • Build a Graph Manually
  • Intelligent Connect
  • Favorite Filters
  • Filter Cache


Build a File Playback Graph

GraphEdit can automatically build a filter graph that plays a file. The file can be a local file, or a file located at a URL.

To build a graph that plays a local file:

  1. On the File menu, click Render Media File....
  2. Select the file.
  3. Click Open.

Note You can also drag a file icon to the GraphEdit application window, or to the GraphEdit program icon.

To build a graph that plays a file located at a URL:

  1. On the File menu, click Render URL....
  2. In the dialog box that appears, type the URL or select a URL from the drop-down list.
  3. Click Open.

These two commands are equivalent to calling the IGraphBuilder::RenderFile method.


Build a Graph Manually

To build a filter graph manually, you must add one or more filters to the graph, and then either connect them or render their output pins.

  • Add Filters to the Graph
  • Connect Filters
  • Render an Output Pin
  • Disconnect Pins


Add Filters to the Graph

To add filters to the graph, do the following:

  1. On the Graph menu, click Insert Filters....

    GraphEdit displays a dialog box with a tree view. The tree view contains entries for all the filters registered on your system, enumerated by filter category. (Refer to the following diagram.)

  2. In the tree view, click the plus (+) symbol to expand a category.
  3. Select a filter name and click Insert Filter, or double-click a filter name.
  4. Click Close.

You can also add a filter to the graph through the Favorites menu. See Favorite Filters.

Add Filters Dialog Box


Connect Filters

To connect two filters, drag the mouse from the output pin of one filter to the input pin of the other filter. If the pins connect, GraphEdit displays the connection as an arrow connecting the pins. If the pins reject the connection, GraphEdit displays a dialog box with an error message.

If the Intelligent Connect option is turned on, GraphEdit automatically adds any intermediate filters needed to complete the connection. This is equivalent to calling the IGraphBuilder::Connect method. If Intelligent Connect is turned off, GraphEdit attempts to connect the pins directly. This is equivalent to calling the IFilterGraph::ConnectDirect method.


Render an Output Pin

Instead of connecting two pins, you can render an output pin. When you render a pin, GraphEdit adds the necessary downstream filters and connects them. This is equivalent to calling the IGraphBuilder::Render method.

To render an output pin, perform the following steps:

  1. Right-click an output pin.
  2. On the pop-up menu, click Render Pin.


Disconnect Pins

To disconnect two pins, do the following:

  1. Select the arrow that connects the pins.
  2. Type the Delete key.

To disconnect every pin in the graph, click the Remove all connections between filters button on the toolbar.


Intelligent Connect

In Microsoft DirectShow, Intelligent Connect is the mechanism by which the filter graph manager adds intermediate filters when it connects two pins.

For a detailed description of Intelligent Connect, see the DirectShow documentation. Briefly, the filter graph manager searches for filters with matching media types. If more than one filter matches, the filter graph manager tries them in the following order:

  • Filters in the filter cache. (See Filter Cache.)
  • Unconnected filters in the graph.
  • Registered filters, in order of merit.

In GraphEdit, you can turn Intelligent Connect on or off by clicking Connect Intelligent in the Graph menu. This option determines how GraphEdit connects two pins when you manually build a graph. For more information, see Connect Filters.


Favorite Filters

The Favorites menu contains a list of bookmarked filters. This list is useful if you are testing a filter and frequently want to add it to the graph.

To add a filter to the Favorites list, do the following:

  1. On the Graph menu, click Insert Filters....

    GraphEdit displays a dialog box with a tree view. The tree view contains entries for all the filters registered on your system, enumerated by filter category.

  2. In the tree view, click the plus (+) symbol to expand a category.
  3. Select a filter name.
  4. Select the Favorite Filter? check box.
  5. Click Cancel or Close.

To add a filter from the Favorites list to the graph:

  • On the Favorites menu, click the name of the filter.

To remove all of the filters from the Favorites list:

  1. On the Favorites menu, click Clear Favorites.
  2. In the Clear Favorites dialog box, click Yes.


Filter Cache

For dynamic graph building, the filter graph manager maintains a cache of filters. If an application performs a dynamic reconnection, the filter graph manager can cache filters that it removes from the graph. During Intelligent Connect, the filter graph manager tries cached filters first.

In GraphEdit, you can manually add a filter to the cache, as follows:

  1. Add a filter to the graph. (See Add Filters to the Graph.)
  2. Select the filter.
  3. In the Graph menu, click Add Filter To Cache.
  4. GraphEdit removes the filter from the graph and caches it.

To see which filters are in the cache:

  • In the Graph menu, click Enumerate Cached Filters....
  • To remove a filter from the cache:
  1. In the Graph menu, click Enumerate Cached Filters....
  2. Select the name of the filter.
  3. Click Remove Filter.

For more information about dynamic graph building in Microsoft DirectShow, see Dynamic Graph Building in the DirectShow documentation.


Saving and Loading Filter Graphs

  • Save a GraphEdit File
  • Save a Filter Graph as XML
  • Load a GraphEdit File
  • Load a Graph From an External Process


Save a GraphEdit File

To save a GraphEdit file, perform the following steps.

  1. On the File menu, click Save Graph.
  2. In the Save As dialog box, enter the name of the file.
  3. Click Save.

GraphEdit files use the extension .grf.

Applications should not use GraphEdit files as a persistence format. The format is designed for testing and debugging purposes only.


Save a Filter Graph as XML

Note GraphEdit implements a preliminary version of this feature. This feature may change. Future releases are not guaranteed to support it.

To save a filter graph as an XML file, perform the following steps:

  1. On the File menu, click Save As XML (.XGR)....
  2. In the Save As dialog box, enter the name of the file.
  3. Click Save.

XML graph files use the extension .xgr.

Applications should not use this format as a persistence format. It is designed for testing and debugging purposes only.


Load a GraphEdit File

To load a GraphEdit file, perform the following steps:

  1. On the File menu, click Open Graph (.GRF)....
  2. Select the .grf file you want to open.
  3. Click Open.


Load a Graph From an External Process

GraphEdit can load a filter graph created by an external process. With this feature, you can see exactly what filter graph your application builds, with only a minimal amount of additional code in your application.

The application must register the filter graph instance in the Running Object Table (ROT). The ROT is a globally accessible look-up table that keeps track of running objects. For information about how your application can add its filter graph to the ROT, see the topic Loading a Graph From an External Process in the Microsoft DirectShow documentation.

To use this feature, perform the following steps:

  1. Compile your application with code that adds a ROT entry for the filter graph.
  2. Run GraphEdit.
  3. Run your application.
  4. In the File menu, click Connect to Remote Graph....
  5. In the Select a remote filter graph to view... dialog box, select the process identifier (pid) of the second application.
  6. Click OK.

To refresh the list of process identifiers, click Refresh in the dialog box.


Filter Graph Operations

  • Control a Filter Graph
  • Set the Reference Clock


Control a Filter Graph

After you build or load a filter graph in GraphEdit, you can perform operations such as running, pausing, or stopping the graph. You can do this through the menu or the toolbar.

The following table lists the menu command, and equivalent Microsoft DirectShow method for each operation.

Command | Menu | DirectShow Method
Run | On the Graph menu, click Play. | IMediaControl::Run
Pause | On the Graph menu, click Pause. | IMediaControl::Pause
Stop | On the Graph menu, click Stop. | IMediaControl::Stop
Frame Step | On the Graph menu, click Step. | IVideoFrameStep::Step

If the graph is seekable, you can seek using the slider bar that appears below the toolbar.

Note If the graph is seekable, the Stop command also seeks the graph back to the start of the stream.


Set the Reference Clock

If a filter can provide a reference clock, a clock icon appears inside the filter.

Filter with a Reference Clock

If the filter graph manager is using this clock as the filter graph's reference clock, the clock icon is yellow. Otherwise, the icon is gray.

By default, the filter graph manager selects the reference clock. You can select another reference clock, as follows:

  1. Right-click the filter.
  2. On the pop-up menu that appears, click Select Clock.

You can enable or disable the reference clock. On the Graph menu, click Use Clock. A check mark next to this menu item means that the reference clock is enabled. Otherwise, the reference clock is disabled. With no reference clock, samples are rendered as soon as they arrive at the renderer filter.

Note You cannot set the reference clock unless the graph is stopped. For more information, see Control a Filter Graph.


Viewing Filter Graph Information

  • View Filter Registry Data
  • View Filter Property Pages
  • View Filter Graph Statistics
  • Log Graph-Building Operations


View Filter Registry Data

When you add filters, GraphEdit uses the system device enumerator to enumerate all of the filters registered on your system. They appear in a tree view, listed by category (see Add Filters to the Graph).

To view the registry data for a particular filter, click the plus (+) symbol next to the name of the filter. The following information is displayed.

Filter Information

Item | Description
DisplayName | The display name provided by the filter moniker, as returned by the IMoniker::GetDisplayName method.
Merit | The filter's merit value.
Version | The version of the registration format used to register this filter.

For more information, see REGFILTER2 in the Microsoft DirectShow documentation.

Pin Information

Item | Description
bMany | If 1, the filter might have multiple instances of this pin.
bOutput | If 1, this pin is an output pin.
bRendered | If 1, the filter renders the data from this pin. (Applies only to input pins.)
bZero | If 1, the filter might have zero instances of this pin.
ClsPinCategory | The pin category, taken from the pin property set.

For more information, see REGFILTERPINS and REGFILTERPINS2 in the DirectShow documentation.

Media Type Information

Item | Description
major type | The major type GUID
subtype | The subtype GUID

For more information, see AM_MEDIA_TYPE in the DirectShow documentation.

Medium Information

Item | Description
medium clsid | The GUID that specifies the medium set
Data 1 | The ID number of the medium
Data 2 | Not used

For more information, see REGPINMEDIUM in the DirectShow documentation.


View Filter Property Pages

To view a filter's property page, perform the following steps.

  1. Add the filter to the graph. (See Add Filters to the Graph.)
  2. Right-click the filter.
  3. On the pop-up menu, click Properties.

The property page contains any property sheets defined by the filter. In addition, it contains a property sheet for each pin on the filter. (These are defined by GraphEdit, not by the filter.)

If the pin is connected, the pin property sheet lists the media type for the connection. Otherwise, it lists the pin's preferred media types.


View Filter Graph Statistics

GraphEdit measures statistical information about the filter graph manager's performance.

To view the statistics:

  1. On the View menu, click Graph Statistics....
  2. GraphEdit displays a dialog box titled Graph Statistics.

To refresh the statistics after a graph operation:

  • In the Graph Statistics dialog box, click Refresh.

To reset the statistics to zero:

  • In the Graph Statistics dialog box, click Zero.

For more information, see IAMStats in the Microsoft DirectShow documentation.


Log Graph-Building Operations

GraphEdit can log the steps it takes when building a graph. To set up graph logging, do the following:

  1. On the File menu, click Set Log File....
  2. In the Save As dialog box, enter the name of the log file.

When you are done using GraphEdit, you can view the file with a text editor.

The following is an excerpt from a typical log file:

Render file C:\Example.avi
File has media type 0xe436eb83... Subtype 0xe436eb88...
Source filter clsid is 0xe436ebb5...
Source filter has loaded the source file
RenderFile: Source filter added: Address=87bb4
RenderFile: Render source filter pin 87cc4
Render: Pin 87cc4 has major type 0xe436eb83...
Render: Trying filter at address 87bb4
Render: Examining filter at address 87bb4 for input pin to connect output pin 87cc4 to
Render: No more pins - FAILED to find a pin to use on filter 87bb4
[...]


GraphEdit Help

Legal Notice

Information in this document, including URL and other Internet Web site references, is subject to change without notice. Unless otherwise noted, the example companies, organizations, products, people and events depicted herein are fictitious and no association with any real company, organization, product, person or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

© 2000-2002 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, Windows, Windows Media, Windows NT, ActiveSync, ActiveX, Direct3D, DirectDraw, DirectInput, DirectMusic, DirectPlay, DirectShow, DirectSound, DirectX, FrontPage, JScript, Microsoft Press, MSN, NetShow, Outlook, PowerPoint, Visual Basic, Visual C++, Visual InterDev, Visual J++, Visual Studio, WebTV, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.