[PATCH 3/3] Add section describing the filtergraph.

[Stefano Sabatini]

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

diff --git a/doc/filters.texi b/doc/filters.texi
index 4750d32..39a474e 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -1,3 +1,85 @@
+ at chapter Filtergraph description
+ at c man begin FILTERGRAPH DESCRIPTION
+
+A filtergraph is a graph of connected filters.
+
+The node of a filtergraph is a single filter instance, which has a
+variable number of inputs and output pads, which are used to connect
+it with other filter nodes. A filter with no input pads is called
+a "source", a filter with no output pads is called a "sink". A
+connection between an output pad and an input pad of a filter is
+called a "link".
+
+ 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 filtergraph is represented by a list of ";"-separated filterchain
+descriptions. Each filterchain represents a sequence of connected
+filter instances, each one called filternode.
+
+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 filter instance, and
+ at 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


--IJpNTDwzlM2Ie8A6--