[PATCH] Add section describing the filtergraph.

[Stefano Sabatini]

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

diff --git a/doc/filters.texi b/doc/filters.texi
index 7e48b83..aab910a 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -1,3 +1,95 @@
+ at chapter Filtergraph description
+ at c man begin FILTERGRAPH DESCRIPTION
+
+A filtergraph is a directed graph of connected 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.
+
+Each filter in a filtergraph is an instance of a filter class
+registered in the application, which defines the features and the
+number of input and output pads of the filter.
+
+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 filterchain consists of a sequence of connected filters, each one
+connected to the previous one in the sequence. A filterchain is
+represented by a list of ","-separated filter descriptions.
+
+A filtergraph consists of a sequence of filterchains. A sequence of
+filterchains is represented by a list of ";"-separated filterchain
+descriptions.
+
+A filter 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 the filter class of which the
+described filter is an instance of, and has to be the name of one of
+the filter classes registered in the program.
+The name of the filter class is optionally followed by a string
+"=@var{arguments}".
+
+ at var{arguments} is a string which contains the parameters used to
+initialize the 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.
+
+The name and arguments of the filter are eventually preceded and
+followed by a list of link labels.
+A link label allows to name a link and associate it to an output or
+input pad of the filter. @var{in_link_1}, ..., @var{in_link_N} are
+associated to the input pads of the filter, and @var{out_link_1},
+..., at var{out_link_M} to the output pads.
+When another link label with the same name is detected in the
+filtergraph, a link between the corresponding input and output pad is
+created.
+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
+
+the split filter instance has two output pads, and the overlay filter
+instance 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 filter
+pads must be connected. A filtergraph is considered valid if all the
+input and output filter pads of all the filterchains 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{FILTER}           ::= [@var{LINKNAMES}] @var{NAME} ["=" @var{ARGUMENTS}] [@var{LINKNAMES}]
+ at var{FILTERCHAIN}      ::= @var{FILTER} [, at var{FILTERCHAIN}]
+ at var{FILTERGRAPH}      ::= @var{FILTERCHAIN} [;@var{FILTERGRAPH}]
+ at end example
+
+ at c man end FILTERGRAPH DESCRIPTION
+
 @chapter Audio Filters
 @c man begin AUDIO FILTERS
 
-- 
1.7.2.3


--VbJkn9YxBvnuCH5J
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="0003-Move-graph2dot-description-from-libavfilter.texi-to-.patch"