Filter Graph Markup Language (XGR)

The XML interface for the DirectShow Graph Builder provides a new persistence format for DirectShow graphs. This format is intended for debugging purposes only to allow a human-readable form of graph persistence; it is not intended for use in applications.

To save a graph in XGR format from GraphEdit, choose Save As XML from the File menu.

Contents:

• FGML Rules and Conventions
• Naming Conflicts
• XML Tags for XGR
  • GRAPH
  • FILTER
  • PARAM
  • CONNECT
  • RENDER
  • FILESOURCE
  • INCLUDE
  • VIDEOCOMPRESS
  • AUDIOCOMPRESS
  • SUBGRAPH
  • FRAGMENT
• FGML Schema

FGML Rules and Conventions

The default file extension of an FGML file is .XGR. In this document, XGR and FGML are using as synonyms.

FGML follows the XML 1.0 standard for file formatting, tokenization and parsing.

In addition, the following rules are added to deal with issues specific to DirectShow filter graphs:

Naming Conflicts

Each filter and pin definition in the XGR file should define a unique identifier. If this is not the case, then the XGR reader resolves conflicts automatically. As the XGR file is read, filters are instantiated and pins are named as specified in the document. If the case of a conflict, the second filter or pin attempting to use that name will be given a different name. This name will be based on the requested name with a suffix added for uniqueness. Note that the XGR reader will not inform the client code of any such renames which occur, so it will be the responsibility of the client to ensure that they refer to the objects using the correct name after the XGR file is loaded.

In order to avoid naming conflicts, scoping operators have been added to the XGR specifications. These are defined using the <SUBGRAPH> tag. All filters defined within the subgraph can be referred to using the compound name of "subgraph_name.child_filter_name". While the current release of DirectShow does not support subgraphs natively, this may change in future releases. The same naming conventions will apply with native DirectShow subgraphs, with the '.' operator becoming a means of separating the containing subgraph filter from the child filter names.

XML Tags for XGR

GRAPH Element

The GRAPH element is a root element of the graph builder document. It has no defined parameters. GRAPH tags cannot be nested in an XGR file.

Syntax:

<GRAPH version="{number} >
...
</GRAPH>

Related tags

Example

<GRAPH>

<FILTER id="videocompress" clsid="{…}" />

</GRAPH>

FILTER Element

Description

The FILTER element is used to define a filter in the graph. The graph builder will use the information defined in this element to select the appropriate filter and creates it. The element also defines the properties that are set on the filter. You must specify one of the 'category' or 'clsid' attributes, but not both of them, in order for the FILTER element to be valid. If both are specified, the 'clsid' will be used and the 'category' and 'instance' attributes will be ignored.

Syntax:

<FILTER
id="filter_name"
clsid="{GUID}"
category="category_name"
instance="instance name"
/>

Remarks

Example

<FILTER id="asfmux" clsid="{….}  />

<FILTER id="capture" category="{Video Capture Sources}" instance="winnov" />

<FILTER id="videocompress" clsid="{…}">

<PARAM name="bitrate" value="24000" />

</FILTER>

PARAM Element

Description

The PARAM element defines a generic way of setting the properties on the filter. It defines a name/value pair that is passed to the filter. The name/value pairs are defined as attributes to PARAM element.

Syntax:

<PARAM name="fps" value="15" />

Remarks

Example

<FILTER id="videocompress" clsid="{…}">

<PARAM name="bitrate" value="24000" />

<PARAM name="fps" value="15" />

</FILTER>

CONNECT Element

Description

The CONNECT Element is used to define a connection between two filters. If the pin to be used is not specified, CONNECT will look for unconnected pins in the correct direction on the filter and choose one of them. The pin chosen in this case is not guaranteed to be the same on subsequent instantiations of the graph from XGR, so if you require a certain pin it must be fully specified.

Syntax:

<CONNECT 
src="src_filter_name"
srcpin="src_pin_name"
dest="dest_filter_name"
destpin="dest_pin_name"
CONNECT/>

Remarks

Example

<CONNECT src="vidcap.video" srcpin='pin1' dest='renderer' destpin='pin3' />

RENDER Element

Description

The RENDER element informs the graph builder that the specified filter and pin should be rendered.

Syntax:

<RENDER id="filter_name" pin="pin_name />

Remarks

Example

<FILTER id="waveout" clsid="{….}  />

<RENDER id="waveout">

FILESOURCE Element

Description

The FILESOURCE element specifies a URL from which a file is to be played. Based on the media type of this URL a source filter with the given id will be instantiated.

ISSUE – Does this create a single filter or an input subgraph.

Syntax:

<FILESOURCE id="source_filter_name" url="file url" />

Remarks

Example

<FILESOURCE id="ASF1" url="http://example.microsoft.com/" />

INCLUDE Element

Description

The INCLUDE element is used to include another XGR file or a FRAGMENT into the current XGR stream. This allows you to use code snippets from a common source to build a complicated graph from smaller pieces. Any file INCLUDED may not contain the GRAPH element since this breaks the rule against nesting GRAPH elements. If the "url" attribute is set than any "fragment" attributes are ignored, these attributes are mutually exclusive. If the specified url or fragment does not exist then the INCLUDE element is ignored.

Syntax:

< INCLUDE
url="url_for_file"
fragment="fragment_name"
subgraph="subgraph_name"
/>

Remarks

Example

<INCLUDE url="http://example.microsoft.com/" subgraph="capture"/>

VIDEOCOMPRESS Element

Description

The VIDEOCOMPRESS element is used to instantiate a standard set of filters which take an input video stream in one format and convert it to the required output format. This is a shortcut method of instantiating the complete set of filters necessary to complete this task. If the pin to be used is not specified, the first available pin on the filter is used. The choice of which pin is used by default is not guaranteed to be the same on subsequent instantiations of the graph from XGR, so if you require a certain pin it must be fully specified.

Syntax:

< VIDEOCOMPRESS
src="src_filter_name" 
srcpin="src_filter_pin_name"
dest="dest_filter"
destpin="dest_filter_pin_name"
width="{number}"
size="{number}"
codec="codec_name"
datarate="{number}"
keyframespacing="{number}"
frametime="{number}"
subgraph="subgraph_name"
/>

Remarks

Example

AUDIOCOMPRESS Element

Description

The AUDIOCOMPRESS element is used to instantiate a standard set of filters which take an input audio stream in one format and convert it to the required output format. This is a shortcut method of instantiating the complete set of filters necessary to complete this task. If the pins to be used are not specified, the first available pin on the filter is used. The choice of which pin is used by default is not guaranteed to be the same on subsequent instantiations of the graph from XGR, so if you require a certain pin it must be fully specified.

Syntax:

< AUDIOCOMPRESS
src="src_filter_name"
srcpin="src_filter_pin_name"
dest="dest_filter"
destpin="dest_filter_pin_name"
samplerate="{number}"
sampledepth="{number}"
channels="{number}"
subgraph="subgraph_name"
/>

Remarks

Example

SUBGRAPH Element

Description

The SUBGRAPH element is used create namespace and sectioning behaviors in the filter graph. All Filters defined within the SUBGRAPH element are now referred to with the subgraph name prefixed on to the name in the filter tag. For example, a filter named "Filter" in subgraph "SG1" is referred to by the name "SG1.Filter".

Syntax:

< SUBGRAPH name="subgraph_name"> ... </SUBGRAPH>

Remarks

FRAGMENT Element

Description

The FRAGMENT element creates a reusable section of XGR code that can be included in numerous places in the graph. When the FRAGMENT element is encountered, all subsequent elements inside the tag are not added to the filter graph. When an INCLUDE tag that references this FRAGMENT is seen, the elements from the fragment are now inserted into the XGR stream as though they were located in the XGR file at the location of the INCLUDE element. You can INCLUDE a FRAGMENT any number of times in the XGR file. A FRAGMENT may contain any other element except GRAPH.

Syntax:

< FRAGMENT name="fragment_name">
...
</FRAGMENT>

Remarks

Example

FGML Schema

<?xml version="1.0"?>

<Schema xmlns="urn:schemas-microsoft-com:xml-data"

     xmlns:dt="urn:schemas-microsoft-com:datatypes">

<!-- Define standard attribute types -->

<AttributeType name="category" dt:type="string" />

<AttributeType name="clsid" dt:type="string" />

<AttributeType name="dest" dt:type="string" />

<AttributeType name="destpin" dt:type="string" />

<AttributeType name="id" dt:type="string" />

<AttributeType name="instance" dt:type="string" />

<AttributeType name="name" dt:type="string" />

<AttributeType name="pin" dt:type="string" />

<AttributeType name="src" dt:type="string" />

<AttributeType name="srcpin" dt:type="string" />

<AttributeType name="url" dt:type="string" />

<AttributeType name="value" dt:type="string" />

<!-- GRAPH element definition -->

<ElementType name="GRAPH" content="eltOnly" model="closed" order="many">

     <!-- decide if a version attribute is required -->

     <element type="FILTER" />

     <element type="CONNECT" />

     <element type="SUBGRAPH" />

     <element type="PARAM" />

     <element type="FILESOURCE" />

</ElementType>

<!-- FILTER element definition -->

<ElementType name="FILTER" content="eltOnly" model="closed" order="many">

     <attribute type="id" required="yes" />

     <attribute type="clsid" required="no" />

     <attribute type="category" required="no" />

     <attribute type="instance" required="no" />

     <element type="PARAM" />

</ElementType>

<!-- PARAM element definition -->

<ElementType name="PARAM" content="empty" model="closed" order="many">

     <attribute type="name" required="yes" />

     <attribute type="value" required="yes" />

</ElementType>

<!-- CONNECT element definition -->

<ElementType name="CONNECT" content="empty" model="closed">

     <attribute type="src" required="yes" />

     <attribute type="srcpin" required="no" />

     <attribute type="dest" required="yes" />

     <attribute type="destpin" required="no" />

</ElementType>

<!-- RENDER element definition -->

<ElementType name="RENDER" content="empty" model="closed">

     <attribute type="id" required="yes" />

     <attribute type="pin" required="yes" />

</ElementType>

<!-- FILESOURCE element definition -->

<ElementType name="FILESOURCE" content="empty" model="closed">

     <attribute type="id" required="yes" />

     <attribute type="url" required="yes" />

</ElementType>

<!-- VIDEOCOMPRESS element definition -->

<!-- AUDIOCOMPRESS element definition -->

<!-- INCLUDE element definition -->

<!-- FRAGMENT element definition -->

<!-- SUBGRAPH element definition -->

</Schema>