[PATCH] Add section describing the filtergraph.

Stefano Sabatini stefano.sabatini-lala
Sat Nov 6 03:04:43 CET 2010

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

diff --git a/doc/filters.texi b/doc/filters.texi
index 9583e4e..3fc5c60 100644
--- a/doc/filters.texi
+++ b/doc/filters.texi
@@ -1,3 +1,91 @@
+ at chapter 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 filternode is a filter instance which is a node of a filtergraph.
+A filterchain consists of a sequence of connected filternodes, each
+one connected to the previous one in the sequence. A filterchain is
+represented by a list of ","-separated filternode descriptions.
+A filtergraph is completely defined by a sequence of filterchains. A
+sequence of filterchains is represented by a list of ";"-separated
+filterchain descriptions.
+A filternode is represented by a string of the form:
+ at example
+ 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 which contains 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}.
 @chapter Audio Filters
 @c man begin AUDIO FILTERS


More information about the ffmpeg-devel mailing list