| Microsoft DirectX 8.0 |
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.
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:
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.
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>
| Attribute | Required | Description |
|
version |
N |
Specifies the version of the XGR file specification to which this file conforms. This defaults to a value of "1", which is currently the only valid version. |
Related tags
| Parent Elements | Child Elements |
|
None |
FILTER |
| CONNECT | |
| SUBGRAPH |
Example
<GRAPH>
<FILTER id="videocompress" clsid="{…}" />
</GRAPH>
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"
/>
| Attribute | Required | Description |
|
id |
Y |
Specifies the name of the filter instance in the graph |
|
clsid |
N |
Specifies the class id for the filter. Graph builder uses this to create an instance of the filter. If clsid is specified then the category and instance attributes cannot be used. |
|
category |
N |
Specifies the category of the filter for the graph builder. The graph builder uses this to find the filter. If no 'instance' is specified then the default filter from this category is instantiated. If clsid is specified this attribute is ignored. |
|
instance |
N |
When a category is specified, the 'Instance' attribute is used to specify which filter in that category is to be instantiated. If clsid is specified this attribute is ignored. |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
PARAM |
Example
<FILTER id="asfmux" clsid="{….} />
<FILTER id="capture" category="{Video Capture Sources}" instance="winnov" />
<FILTER id="videocompress" clsid="{…}">
<PARAM name="bitrate" value="24000" />
</FILTER>
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" />
| Attribute | Required | Description |
|
name |
Y |
Specifies the name property |
|
Value |
Y |
Specifies the value of the property |
Remarks
| Parent Elements | Child Elements |
|
FILTER |
None |
Example
<FILTER id="videocompress" clsid="{…}">
<PARAM name="bitrate" value="24000" />
<PARAM name="fps" value="15" />
</FILTER>
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/>
| Attribute | Required | Description |
|
src |
Y |
Fully qualified name of the filter to be used as the data source for the connection. |
|
srcpin |
N |
Name of the specific pin from the data source to connect to. |
|
dest |
Y |
Fully qualified name of the filter to be used as the data sink for the connection. |
|
destpin |
N |
Name of the specific pin from the data sink to connect to. |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
None |
Example
<CONNECT src="vidcap.video" srcpin='pin1' dest='renderer' destpin='pin3' />
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 />
| Attribute | Required | Description |
|
Id |
Y |
Name of the filter to use for rendering |
|
pin |
Y |
Name of the pin to use. |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
None |
Example
<FILTER id="waveout" clsid="{….} />
<RENDER id="waveout">
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" />
| Attribute | Required | Description |
|
id |
Y |
Name to be used for the instantiated source filter. |
|
url |
Y |
URL which identifies the media file to be opened by the source filter. |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
None |
Example
<FILESOURCE id="ASF1" url="http://example.microsoft.com/" />
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" />
| Attribute | Required | Description |
|
url |
N |
URL which points to the XGR file to be included into the graph. Must be specified if the fragment attribute is not set. |
|
fragment |
N |
Name of the XGR FRAGMENT element which is to be included. Must be specified if the url attribute is not set, ignored if url is set. |
|
subgraph |
N |
If a subgraph is specified, the file fragment is assumed to create a distinct subgraph in the graph. This is equivalent to wrapping the INCLUDE element in a SUBGRAPH element. If no subgraph attribute is used then the file is loaded into the default namespace. |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
None |
Example
<INCLUDE url="http://example.microsoft.com/" subgraph="capture"/>
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"
/>
| Attribute | Required | Description |
|
src |
Y |
Fully qualified name of the filter to be used as the data source for the connection. |
|
srcpin |
N |
Name of the specific pin from the data source to connect to. |
|
dest |
Y |
Fully qualified name of the filter to be used as the data sink for the connection. |
|
destpin |
N |
Name of the specific pin from the data sink to connect to. |
|
width |
Y |
Width, in pixels, of the output stream |
|
height |
Y |
Height, in pixels, of the output stream |
|
codec |
Y |
Codec to be used to do the video conversion |
|
datarate |
Y |
This is the datarate, in kb/sec, of the output stream |
|
keyframespacing |
Y |
This defines the keyframespacing |
|
frametime |
Y |
This defines the frametime |
|
subgraph |
N |
If a subgraph is specified, the video compression filters are assumed to be in a distinct subgraph in the graph. This is equivalent to wrapping the VIDEOCOMPRESS element in a SUBGRAPH element. If no subgraph attribute is used then the file is loaded into the default namespace. |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
None |
Example
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"
/>
| Attribute | Required | Description |
|
src |
Y |
Fully qualified name of the filter to be used as the data source for the connection. |
|
srcpin |
N |
Name of the specific pin from the data source to connect to. |
|
dest |
Y |
Fully qualified name of the filter to be used as the data sink for the connection. |
|
destpin |
N |
Name of the specific pin from the data sink to connect to. |
|
samplerate |
Y |
Sample rate, in k/s, of the output stream |
|
sampledepth |
Y |
Sample size, in bits, of each audio sample |
|
channels |
N |
Number of distinct audio channels in the output stream. If not specified, the default is "1". |
|
subgraph |
N |
If a subgraph is specified, the video compression filters are assumed to be in a distinct subgraph in the graph. This is equivalent to wrapping the VIDEOCOMPRESS element in a SUBGRAPH element. If no subgraph attribute is used then the file is loaded into the default namespace. |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
None |
Example
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>
| Attribute | Required | Description |
|
subgraph_name |
Y |
Name to be used for this subgraph. |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
None |
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>
| Attribute | Required | Description |
|
fragment _name |
Y |
Name to be used for this fragment |
Remarks
| Parent Elements | Child Elements |
|
GRAPH |
None |
Example
<?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>