Welcome

Grapher Help


Grapher Overview

Grapher is a DDK utility which can be used to build, examine and test WDM-CSA filter graphs on the Windows and Windows NT Operating Systems*. Although it is directed primarilly toward audio filter graphs, it can be used to build and explore graphs using any WDM-CSA-compliant filters.

* Windows 98 and Windows NT ver. 5.0 or later


Grapher Crash Course

Grapher Quick Start Guide

Since this is a DDK tool, it is assumed that you are writing a WDM driver, so that you already know what filters, pins and nodes are. This is a one-page gross overview of what you will typically do in grapher.

When you launch Grapher, it does the following:

  • enumerates the filters that are installed on your system

  • creates a profile of each filters properties

  • creates a tree structure that graphically represents the available filters

Once this is done you can do the following:

  • Examine properties of a each filter

  • Examine Pins and Nodes on each filter

  • Examine a filters topology map

  • Instantiate filters

Once a filter is instantiated, you can

  • Instantiate pins on the filter

Once a pin is instantiated, you can

  • Instantiate Grapher Test Filters which can be used to stream data to the KS filters that were enumerated

** Tips

  • If an object in the filter tree has an icon, then it has a context-sensitive menu as well, which you can get to by right-clicking on the object.

  • Test Filter actions are controlled from the filters menu, not from its pins (e.g. to play a Test Filter, right click the Test Filter, not its pin).

  • You don't need to instantiate a filter to view its topology map.


Grapher Objects Overview

Grapher displays graphic representations, via a standard Windows tree control (the graph tree), the following WDM-CSA objects:

Filter

Filter Instance

Pin

Pin Instance

Nodes


Object Instantiation

In order to use a KS Filter or Pin, you must first instantiate it. To instantiate an object, right-click on it, and choose Instantiate. If, for some reason, the instantiation fails, the object will get a [image] over the top of it.

Filter Instantiation

When you instantiate a filter, Grapher calls CreateFile, passing in the filter's device name. If filter instantiation succeeds, Grapher then builds a more in depth profile of the filter and updates the filter tree accordingly.

Pin Instantiation

Instantiating a pin is much more complicated. When you instantiate a pin, you are prompted with a Pin Creation dialog. This dialog allows you to tailor a KSPIN_CREATE structure which is passed to KsCreatePin.

Test Filter Instantiation

Instantiating a Test Filter creates a user-mode object internal to the Grapher application which can be used to stream data to or from an actual KS Filter. The nature of Test Filter instantiation varies depending on the filter type. For example, instantiating a wave file source filter involves choosing an audio WAV file that will be used as the data source for streaming to an audio wave data pin.


Test Filters vs KS Filters

Grapher displays in the Filter Graph Tree two different families of filters -- KS Filters, and Grapher Test Filters. It is important to understand the difference between the two.

KS Filters

KS Filters are bona-fide Kernel Mode Filters that are exposed to the Windows Operating System. Grapher enumerates these filters in any of a number of ways as outlined in the topic FEnum.htm.

Grapher Test Filters

Grapher Test Filters are modeled after real KS Filters or DirectShow (ActiveMovie) filters, but exist only within the Grapher Application, i.e. these filters do not export the COM interfaces that would expose their functionality to the rest of the system. They are provided as a means to test KS Filters that are under development.


Filter Enumeration

At startup time, you are presented (by default) with the following dialog. You can choose to enumerate filters by any of the three means:

  • Setup APIs -- This option should almost always be checked. It uses the same methods to discover your device that the operating system uses. To choose which device classes are enumerated, click the Classes button, which gives you the dialog shown on the right, below. All device categories listed in KS.H as of the release date of the DDK are provided.

  • Grapher Test Filters -- Filters internal to Grapher which can be used to stream data to/from real KS Filters. All but one of these filters are Audio-specific.

  • Defaults System Filters -- Again, these are audio-centric. This option is of little value to most developers.

  • Registry Groveling -- Grapher roots around in the registry for what it thinks are valid filters. This option is generally not useful, but could be used, for instance, to debug problems with SetupAPI enumeration.

  • Additional Filters -- This option can be used to load a device by DOS Device name, e.g. \\.\Portclass0\Wave.


Filter Topology Diagrams

To see a map of the topology as reported by a given filter, right-click on the filter (does not have to be instantiated) and choose View Topology Map. Nodes and pins are identified by their respective id numbers. Furthermore, you can get the named GUID of a node type by hovering the mouse pointer over it.

If the connections are cluttered it may be usedful to toggle between bezier or straight lines, or to drag some Nodes from their default location. For a description of the items in the topology map, click the Key button in the upper left corner of the dialog.


Faux Filters

Grapher Test Filters

Test Filters have functional characteristics of normal WDM-CSA filters, but exist only within the context of grapher and are not exported. They are presented like other KS filters for visual consistancy.

Wavefile source -- uses a wave (.wav) file as a source of data which it packages appropriately and streams to a sink pin.

Wavemeter sink -- connects to a source pin and displays a rough numerical average of data values steraming from the source.

Midifile source -- uses a simple midi (.mid) file as a source of data which it packages appropriately and streams to a sink pin.

Midimic sink -- connects to a source pin and displays in the logging window data streaming from the source as translated midi messages.

Video Capture sink -- connects to a video capture source pin and displays video data in a window.

Full Duplex Router (sink and source) -- couples to sink pins together.


Using Faux Filters To Submit Irps

Using Test Filters To Submit IRPs

To use a Test Filter as a data sink or source

  • Instantiate it. In the case of source filters, you will be prompted for a data source file.

  • Instantiate it's pin. You will be prompted for a sink or source pin to connect to.

  • Set the various properties of the sink or source to tailor the IRP format. By default, these are set to values which are reasonable in a very general sense for the particular filter type.

  • Once connected to a KS Filter pin, you can submit IRPs to that pin. You do this at the Test Filter level. e.g. to submit wave data IRPs to the KS Pin, right-click on the wavefile filter (not on the pin) and choose play from the context menu.

For an example of a Test Filter in action see Filter Graphs .


Faux Filter Properties

Test Filter Properties

Under each Test Filter is a properties branch. Each of the properties listed therein controls some aspect of the IRP structure that the Test Filter sends. To change the value of a property, right-click on the property and choose Modify. You will be presented with an editing control appropriate for the data type.


Pins

A pin is a data entry point on a filter. To get data into a filter, you stream data to an input pin on the filter. To get data from a filter, you stream data from an output pin on the filter.


Instantiating a Pin

To instantiate a pin, right-click on the pin and choose Instantiate from the context menu.

At this point, you are presented with a magnificent dialog which allows you to control pin creation parameters -- essentially, the values for the KSPIN_CREATE structure that is passed to KsCreatePin in order to instantiate the pin. Notice that there are three presets for commonly used audio formats, namely those used for streaming PCM audio, MIDI, and DirectSound PCM audio.


Nodes

A Node is a logical functional unit within a KS Filter that the filter provides for property handling and topology description purposes. For example, a KSNODETYPE_VOLUME Node is a functional unit which corresponds to audio volume control in the data flow of the filter which contains the Node. A Node is analogous to a control block in an electronic circuit diagram.

A Node may support one or more Properties. Continuing with our example, a KSNODETYPE_VOLUME Node generally supports the KSPROPERTY_AUDIO_VOLUMELEVEL property. Grapher queries each Node for support of each Property of each PropertySet that the filter claims to support. The supported properties and their current values are displayed as leafs in the Grapher filter tree view and are designated by the icon [image].


Node Properties

To change the values of a property, right-click on the property tree control item and choose Modify. You will be presented with a dialog box appropriate for the data type of the property. For example, if the property value is of type BOOL, you will be prompted with a list control that only allows the values TRUE and FALSE.


Connections

A Connection simply denotes a link between two Pins, two Nodes, or a Pin and a Node. A connection implies data flow from one Node or Pin to a second Node or Pin.

Each connection has a From Node/Pin pair and a To Node/Pin pair. Each Node/Pin pair is designated by ordered pairs like (-1, 1). The nomenclature is somewhat confusing, however, in that the term Node here refers to both Nodes within a filter, as well as the filter itself. It follows that the term Pin in the context of connections refers to both Pins on a Filter as well as logical pins on a Node.

The best way to visual Connections is to have Grapher do it for you using the Topology Diagram feature.


Filter Graphs

A Filter Graph is a collection of connected Filters. Grapher is an example of a Graph Builder. Other Graph Builders include the System Audio Device (SysAudio.sys), and the DirectShow (ActiveMovie) media player. Grapher and SysAudio deal exclusively with Kernel Streaming (KS) Filters.

A simple Graph is built when you connect Pins from two different Filters. This is done implicitly when you instantiate a Pin and specify a valid Pin Handle for KSPIN_CONNECT.ConnectTo. A typical graph built by an Operating System component such as SysAudio may include several filters chained together. For example, in the Audio case, there may be a mixer filter, an acoustic echo cancellation (AEC) filter, and and several device driver filters in the graph.

In Grapher, a connection between Pins is represented by a bezier curve as in the following diagram. In this example, the Wave File Source Test Filter was instantiated with a monophonic wave file. Its pin was instantiated and connected to the input sink pin on an Audio wave port filter (which is exposed by the sound card Adapter Driver). This constitutes a simple, but functional graph. To prove that the graph is functional, one could hit the Play button on the toolbar at this point -- audio should be heard out of the speakers on the sound card.


Filter View and Logging View

The Filter View and The Logging View

The grapher UI is separated into two Windows:

  • The Filter Graph Window displays the Filters that have been enumerated or specified in the filter options.

  • The Logging Window


Controlling the Logging View

You can control the level of information logged in the Logging view by right clicking on in the logging view and chosing Properties...


Index

Contents Index


Content

Contents Index