Microsoft DirectX 8.0

Filter Graph Markup Language (XGR)

DirectShow グラフ ビルダの XML インターフェイスは、DirectShow グラフの新しい永続性フォーマットを提供する。このフォーマットは、グラフの永続性を読み取り可能な形にしてデバッグを行うことだけを目的としていて、アプリケーションで使用することは目的としていない。

GraphEdit でグラフを XGR フォーマットで保存するには、[File] メニューの [Save As XML] を選択する。

目次

FGML の規則と規約

FGML ファイルのデフォルトのファイル拡張子は .XGR である。このドキュメントでは、XGR と FGML が同義語として使われている。

FGML のファイル フォーマット、トークン化、および解析は XML 1.0 規格に準拠している。

さらに、DirectShow フィルタ グラフに固有の問題に対処するため、以下の規則が追加されている。

名前付けの競合

XGR ファイルのそれぞれのフィルタ定義およびピン定義では、一意な識別子を定義する必要がある。一意な識別子が定義されていない場合は、XGR リーダーが自動的に競合を解決する。XGR ファイルが読み込まれると、フィルタのインスタンスが生成され、ドキュメントの指定に従ってピンが命名される。競合が発生した場合は、同じ名前を使おうとした 2 番目のフィルタまたはピンに別の名前が付けられる。この名前は、要求された名前を基にして、一意性を持たせるためにサフィックスを追加した名前になる。XGR リーダーはこのような名前の変更が発生したことをクライアント コードに通知しないため、クライアントは、XGR ファイルがロードされた後、それらの名前が正しい名前を使ってオブジェクトを参照するように取り計らう必要がある。

名前付けの競合を回避するため、XGR 仕様にはスコープ演算子が追加されている。スコープ演算子は、<SUBGRAPH> タグを使って定義される。サブグラフ内で定義されたすべてのフィルタは、複合名 "subgraph_name.child_filter_name" を使って参照できる。DirectShow の現在のリリースは、ネイティブではサブグラフをサポートしていないが、将来のリリースではこれが変わる可能性がある。その場合は、ネイティブの DirectShow サブグラフに対しても同じ名前付け規約が適用され、'.’ 演算子が、子フィルタを包含するサブグラフ フィルタと子フィルタの名前を区切る手段になる。

XGR 用の XML タグ

GRAPH 要素

GRAPH 要素は、グラフ ビルダ ドキュメントのルート要素である。この要素のパラメータは定義されていない。XGR ファイル内では GRAPH タグをネストできない。

構文:

<GRAPH version=”{number} >
...
</GRAPH>
属性 必須かどうか

説明

version

必須ではない

このファイルが従う XGR ファイル仕様のバージョンを指定する。特に指定がない場合、この値は、現在唯一の有効なバージョンである "1" になる。

関連するタグ

親要素 子要素

なし

FILTER

CONNECT

SUBGRAPH

<GRAPH>

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

</GRAPH>

FILTER 要素

説明

FILTER 要素は、グラフ内のフィルタを定義するために使用する。グラフ ビルダは、この要素で定義されている情報を利用して、適切なフィルタを選択し、作成する。この要素は、フィルタに対して設定されるプロパティも定義する。FILTER 要素を有効にするには、'category' 属性または 'clsid' 属性のいずれかを指定する必要があるが、両方を指定することはできない。両方の属性が指定された場合は、'clsid' が使用され、'category' 属性および 'instance' 属性は無視される。

構文:

<FILTER
id=”filter_name”
clsid=”{GUID}”
category=”category_name”
instance=”instance name”
/>
属性 必須かどうか

説明

id

必須

グラフ内のフィルタのインスタンスの名前を指定する。

clsid

必須ではない

フィルタのクラス ID を指定する。グラフ ビルダは、これを利用してフィルタのインスタンスを作成する。clsid が指定されている場合、category 属性と instance 属性は使用できない。

category

必須ではない

グラフ ビルダが使用するフィルタのカテゴリを指定する。グラフ ビルダはこれを使用して、フィルタを検索する。'instance' が指定されていない場合は、このカテゴリのデフォルトのフィルタのインスタンスが生成される。clsid が指定されていると、この属性は無視される。

instance

必須ではない

カテゴリが指定されている場合は、'Instance' 属性を使って、そのカテゴリのどのフィルタのインスタンスを生成するかを指定する。clsid が指定されていると、この属性は無視される。

注意

親要素 子要素

GRAPH

PARAM

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

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

<FILTER id=”videocompress” clsid=”{?c}”>

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

</FILTER>

PARAM 要素

説明

PARAM 要素は、フィルタのプロパティを設定する一般的な方法を定義する。この要素は、フィルタに渡される名前と値の組み合わせを定義する。名前と値の組み合わせは、PARAM 要素の属性として定義される。

構文:

<PARAM name=”fps” value=”15” />
属性 必須かどうか

説明

name

必須

name プロパティを指定する。

Value

必須

プロパティの値を指定する。

注意

親要素 子要素

FILTER

なし

<FILTER id=”videocompress” clsid=”{?c}”>

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

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

</FILTER>

CONNECT 要素

説明

CONNECT 要素は、2 つのフィルタ間の接続を定義するために使用する。使用するピンが指定されていない場合、CONNECT は、方向が正しく、接続されていないフィルタ上のピンを検索し、その中の 1 つを選択する。その場合、それ以降に XGR から生成されるグラフのインスタンスでも同じピンが選択される保証はないため、特定のピンが必要なときは、絶対パス名で指定する必要がある。

構文:

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

属性 必須かどうか

説明

src

必須

接続のデータ ソースとして使用するフィルタの絶対パス名。

srcpin

必須ではない

データ ソースの接続相手となる特定のピンの名前。

dest

必須

接続のデータ シンクとして使用するフィルタの絶対パス名。

destpin

必須ではない

データ シンクの接続相手となる特定のピンの名前。

注意

親要素 子要素

GRAPH

なし

<CONNECT src=”vidcap.video” srcpin=’pin1’ dest=’renderer’ destpin=’pin3’ />

RENDER 要素

説明

RENDER 要素は、グラフ ビルダに対して、指定されたフィルタとピンをレンダリングする必要があることを通知する。

構文:

<RENDER id=”filter_name” pin=”pin_name />
属性 必須かどうか

説明

Id

必須

レンダリングに使用するフィルタの名前。

pin

必須

使用するピンの名前。

注意

親要素 子要素

GRAPH

なし

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

<RENDER id=”waveout”>

FILESOURCE 要素

説明

FILESOURCE 要素は、再生するファイルの URL を指定する。この URL のメディア タイプに基づいて、指定された id のソース フィルタのインスタンスが生成される。

問題 – これは 1 つのフィルタを作成するのか、入力サブグラフを作成するのか。

構文:

<FILESOURCE id=”source_filter_name” url=”file url” />
属性 必須かどうか

説明

id

必須

インスタンスが生成されたソース フィルタで使用される名前。

url

必須

ソース フィルタが開くメディア ファイルを識別する URL。

注意

親要素 子要素

GRAPH

なし

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

INCLUDE 要素

説明

INCLUDE 要素は、別の XGR ファイルまたは FRAGMENT を現在の XGR ストリームに含めるために使用する。これにより、共通のソースのコードを使って、小さいコードから複雑なグラフを作成できる。GRAPH 要素のネストを禁じている規則に違反するため、INCLUDE されたファイルに GRAPH 要素を含めることはできない。"url" 属性が設定されている場合、"fragment" 属性はすべて無視される。これらの属性は両立しない。指定された url または fragment が存在しない場合、INCLUDE 要素は無視される。

構文:

< INCLUDE
url=”url_for_file”
fragment=”fragment_name”
subgraph=”subgraph_name”
/>
属性 必須かどうか

説明

url

必須ではない

グラフに含める XGR ファイルを指す URL。fragment 属性が設定されていない場合は、これを指定する必要がある。

fragment

必須ではない

含める XGR FRAGMENT 要素の名前。url 属性が設定されていない場合は、これを指定する必要がある。url が設定されている場合、これは無視される。

subgraph

必須ではない

サブグラフが指定されている場合は、ファイル フラグメントがグラフ内に別のサブグラフを作成するものと見なされる。これは、SUBGRAPH 要素の中に INCLUDE 要素をラップすることに等しい。subgraph 属性が使用されていない場合、ファイルはデフォルトの名前空間にロードされる。

注意

親要素 子要素

GRAPH

なし

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

VIDEOCOMPRESS 要素

説明

VIDEOCOMPRESS 要素は、あるフォーマットの入力ビデオ ストリームを受け取り、それを、必要とされる出力フォーマットに変換するフィルタの標準的なセットのインスタンスを生成するために使用する。これは、このタスクを実行するために必要なフィルタの完全なセットのインスタンスを生成するのに代わる方法である。使用するピンが指定されていない場合は、フィルタ上の利用可能な最初のピンが使用される。それ以降に、XGR から生成されるグラフのインスタンスでも同じピンがデフォルトで使用される保証はないため、特定のピンが必要な場合は、絶対パス名で指定する必要がある。

構文:

< 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”
/>
属性 必須かどうか

説明

src

必須

接続のデータ ソースとして使用するフィルタの絶対パス名。

srcpin

必須ではない

データ ソースの接続相手となる特定のピンの名前。

dest

必須

接続のデータ シンクとして使用するフィルタの絶対パス名。

destpin

必須ではない

データ シンクの接続相手となる特定のピンの名前。

width

必須

ピクセル単位で表す出力ストリームの幅。

height

必須

ピクセル単位で表す出力ストリームの高さ。

CODEC

必須

ビデオ変換を行うときに使用する CODEC。

datarate

必須

kb/秒単位で表す出力ストリームのデータ速度。

keyframespacing

必須

keyframespacing を定義する。

frametime

必須

frametime を定義する。

subgraph

必須ではない

subgraph が指定されている場合、ビデオ圧縮フィルタは、グラフ内の別のサブグラフ内にあるものと見なされる。これは、VIDEOCOMPRESS 要素を SUBGRAPH 要素の中にラップすることに等しい。subgraph 属性が使用されていない場合、ファイルはデフォルトの名前空間にロードされる。

注意

親要素 子要素

GRAPH

なし

AUDIOCOMPRESS 要素

説明

AUDIOCOMPRESS 要素は、あるフォーマットの入力オーディオ ストリームを受け取り、それを、必要とされる出力フォーマットに変換するフィルタの標準的なセットのインスタンスを生成するために使用する。これは、このタスクを実行するために必要なフィルタの完全なセットのインスタンスを生成するのに代わる方法である。使用するピンが指定されていない場合は、フィルタ上の利用可能な最初のピンが使用される。それ以降に XGR から生成されるグラフのインスタンスでも同じピンがデフォルトで使用される保証はないため、特定のピンが必要な場合は、絶対パス名で指定する必要がある。

構文:

< 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”
/>
属性 必須かどうか

説明

src

必須

接続のデータ ソースとして使用するフィルタの絶対パス名。

srcpin

必須ではない

データ ソースの接続相手となる特定のピンの名前。

dest

必須

接続のデータ シンクとして使用するフィルタの絶対パス名。

destpin

必須ではない

データ シンクの接続相手となる特定のピンの名前。

samplerate

必須

k/秒で表す出力ストリームのサンプル速度。

sampledepth

必須

ビット単位で表す各オーディオ サンプルのサンプル サイズ。

channels

必須ではない

出力ストリーム内の別のオーディオ チャンネルの数。指定されていない場合のデフォルトは、"1" になる。

subgraph

必須ではない

subgraph が指定されている場合、ビデオ圧縮フィルタは、グラフ内の別のサブグラフ内にあるものと見なされる。これは、VIDEOCOMPRESS 要素を SUBGRAPH 要素の中にラップすることに等しい。subgraph 属性が使用されていない場合、ファイルはデフォルトの名前空間にロードされる。

注意

親要素 子要素

GRAPH

なし

SUBGRAPH 要素

説明

SUBGRAPH 要素は、フィルタ グラフ内で名前空間と分割動作を作成するために使用する。SUBGRAPH 要素内で定義されたすべてのフィルタは、フィルタ タグ内でサブグラフ名をプリフィックスとして追加した名前を使って参照できる。たとえば、サブグラフ "SG1" 内の "Filter" という名前のフィルタは、"SG1.Filter" という名前によって参照される。

構文:

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

属性 必須かどうか

説明

subgraph_name

必須

このサブグラフで使用される名前。

注意

親要素 子要素

GRAPH

なし

FRAGMENT 要素

説明

FRAGMENT 要素は、グラフ内のさまざまな場所に含めることができる XGR コードの再利用可能なセクションを作成する。FRAGMENT 要素があると、タグ内のそれ以降のすべての要素はフィルタ グラフに追加されない。この FRAGMENT を参照する INCLUDE タグがあると、フラグメントの要素は、INCLUDE 要素の位置にある XGR ファイル内にあるかのように、XGR ストリームに挿入される。XGR ファイル内には何回でも FRAGMENT を INCLUDE することができる。FRAGMENT には、GRAPH 以外であれば、どのような要素でも含めることができる。

構文:

< FRAGMENT name=”fragment_name”>
...
</FRAGMENT>
属性 必須かどうか

説明

fragment _name

必須

このフラグメントで使用される名前

注意

親要素 子要素

GRAPH

なし

FGML スキーマ

<?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>