[PATCH] Add section describing the filtergraph.

[Stefano Sabatini]

---
 doc/filters.texi |   88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 88 insertions(+), 0 deletions(-)

diff --git a/doc/filters.texi b/doc/filters.texi
index 9583e4e..d26a02e 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -1,3 +1,91 @@
+ at chapter Filtergraph description
+ at c man begin FILTERGRAPH DESCRIPTION
+
+A filtergraph is a directed graph of filters. It can contain cycles,
+and there can be multiple links between a pair of filters. Each link
+has one input pad on one side connecting it to one filter from which
+it takes its input and one output pad on the other side connecting it
+to the one filter accepting its output.
+
+A filter with no input pads is called a "source", a filter with no
+output pads is called a "sink".
+
+ at section Filtergraph syntax
+
+A filtergraph can be represented using a textual representation, which
+is recognized by the @code{-vf} and @code{-af} options of the ff*
+tools, and by the @code{av_parse_graph()} function defined in
+ at file{libavfilter/avfiltergraph}.
+
+A filter in the graph is called filternode.
+
+A sequence of connected filternodes, each one connected to the
+previous one in the sequence, is called a filterchain. A filterchain
+is represented by a list of ","-separated filternode descriptions.
+
+A sequence of filterchains completely describe a filtergraph. A
+filtergraph is represented by a list of ";"-separated filterchain
+descriptions.
+
+A filternode is represented by a string of the form:
+ at example
+[@var{in_link_1}]...[@var{in_link_N}]@var{filter_name}=@var{arguments}[@var{out_link_1}]...[@var{out_link_M}]
+ at end example
+
+ at var{filter_name} is the name of a filter, optionally
+followed by a string "=@var{arguments}", and eventually preceded and
+followed by a list of link labels.
+
+ at var{arguments} is a string representing the parameters used to
+initialize the corresponding filter instance, and are described in the
+filter descriptions below.
+
+The list of arguments can be quoted using the character "'" as initial
+and ending mark, and the character '\' for escaping the characters
+within the quoted text; otherwise the argument string is considered
+terminated when the next special character (belonging to the set
+"[]=;,") is encountered.
+
+A link label allows to name a link and associate it to an output or
+input pad of a filternode. @var{in_link_1}, ..., @var{in_link_N} are
+associated to the input pads of the filternode, and @var{out_link_1},
+..., at var{out_link_M} to the output pads.
+
+If an output pad is not labelled, it is linked by default to the first
+non-labelled input pad of the next filter in the filterchain.
+
+For example in the filterchain:
+ at example
+nullsrc, split[L1], [L2]overlay, nullsink
+ at end example
+
+split has two output pads, and overlay two input pads. The first
+output pad of split is labelled "L1", the first input pad of
+overlay is labelled "L2", and the second output pad of split is linked
+to the second input pad of overlay, which are both unlabelled.
+
+In a complete filterchain all the unlabeled input and output pads must
+be connected. A filtergraph is considered valid if all the input and
+output filternode pads are connected.
+
+Follows the BNF description of the filtergraph syntax:
+ at example
+ at var{NAME}             ::= sequence of alphanumeric characters and '_'
+ at var{LINKLABEL}        ::= "[" @var{NAME} "]"
+ at var{LINKLABELS}       ::= @var{LINKLABEL} [@var{LINKLABELS}]
+ at var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)
+ at var{FILTERNODE}       ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}]
+ at var{FILTERCHAIN}      ::= @var{FILTERNODE} [, at var{FILTERCHAIN}]
+ at var{FILTERGRAPH}      ::= @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
+ at end example
+
+The tool program @file{tools/graph2dot} can be used for converting a
+textual representation of a filtergraph to a representation in the dot
+language, which can be converted to a visual representation using the
+graphviz utilities, e.g. with @file{dot}.
+
+ at c man end FILTERGRAPH DESCRIPTION
+
 @chapter Audio Filters
 @c man begin AUDIO FILTERS
 
-- 
1.7.1


--k1lZvvs/B4yU6o8G--