[gst-cvs] gstreamer: plugins: add example launch lines and more explanation to the docs.

[Stefan Kost]

Module: gstreamer
Branch: master
Commit: 6ee61e4cb3d2c38665e051a52c833f1a8a766948
URL:    http://cgit.freedesktop.org/gstreamer/gstreamer/commit/?id=6ee61e4cb3d2c38665e051a52c833f1a8a766948

Author: Stefan Kost <ensonic at users.sf.net>
Date:   Mon Aug 16 18:01:27 2010 +0300

plugins: add example launch lines and more explanation to the docs.

The plugins where almost undocumented :/ ...

---

 plugins/elements/gstcapsfilter.c |    7 +++++++
 plugins/elements/gstfakesink.c   |    7 +++++++
 plugins/elements/gstfilesink.c   |    7 +++++++
 plugins/elements/gstfilesrc.c    |    7 +++++++
 plugins/elements/gsttee.c        |   17 ++++++++++++++++-
 5 files changed, 44 insertions(+), 1 deletions(-)

diff --git a/plugins/elements/gstcapsfilter.c b/plugins/elements/gstcapsfilter.c
index 792337d..a144611 100644
--- a/plugins/elements/gstcapsfilter.c
+++ b/plugins/elements/gstcapsfilter.c
@@ -24,6 +24,13 @@
  *
  * The element does not modify data as such, but can enforce limitations on the
  * data format.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch videotestsrc ! video/x-raw-gray ! ffmpegcolorspace ! autovideosink
+ * ]| Limits acceptable video from videotestsrc to be grayscale.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/plugins/elements/gstfakesink.c b/plugins/elements/gstfakesink.c
index 1691908..ebae1f8 100644
--- a/plugins/elements/gstfakesink.c
+++ b/plugins/elements/gstfakesink.c
@@ -24,6 +24,13 @@
  * @see_also: #GstFakeSrc
  *
  * Dummy sink that swallows everything.
+ * 
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch audiotestsrc num-buffers=1000 ! fakesink sync=false
+ * ]| Render 1000 audio buffers (of default size) as fast as possible.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/plugins/elements/gstfilesink.c b/plugins/elements/gstfilesink.c
index 1c69f57..bcd514f 100644
--- a/plugins/elements/gstfilesink.c
+++ b/plugins/elements/gstfilesink.c
@@ -25,6 +25,13 @@
  * @see_also: #GstFileSrc
  *
  * Write incoming data to a file in the local file system.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch v4l2src num-buffers=1 ! jpegenc ! filesink location=capture1.jpeg
+ * ]| Capture one frame from a v4l2 camera and save as jpeg image.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/plugins/elements/gstfilesrc.c b/plugins/elements/gstfilesrc.c
index 81c2df8..0894de6 100644
--- a/plugins/elements/gstfilesrc.c
+++ b/plugins/elements/gstfilesrc.c
@@ -24,6 +24,13 @@
  * @see_also: #GstFileSrc
  *
  * Read data from a file in the local file system.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch filesrc location=song.ogg ! decodebin2 ! autoaudiosink
+ * ]| Play a song.ogg from local dir.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H
diff --git a/plugins/elements/gsttee.c b/plugins/elements/gsttee.c
index a639b04..4f3cc07 100644
--- a/plugins/elements/gsttee.c
+++ b/plugins/elements/gsttee.c
@@ -25,7 +25,22 @@
  * SECTION:element-tee
  * @see_also: #GstIdentity
  *
- * Split data to multiple pads.
+ * Split data to multiple pads. Branching the data flow is useful when e.g.
+ * capturing a video where the video is shown on the screen and also encoded and
+ * written to a file. Another example is playing music and hooking up a
+ * visualisation module.
+ *
+ * One needs to use separate queue elements (or a multiqueue) in each branch to
+ * provide separate threads for each branch. Otherwise a blocked dataflow in one
+ * branch would stall the other branches.
+ *
+ * <refsect2>
+ * <title>Example launch line</title>
+ * |[
+ * gst-launch filesrc location=song.ogg ! decodebin2 ! tee name=t ! queue ! autoaudiosink t. ! queue ! audioconvert ! goom ! ffmpegcolorspace ! autovideosink
+ * ]| Play a song.ogg from local dir and render visualisations using the goom
+ * element.
+ * </refsect2>
  */
 
 #ifdef HAVE_CONFIG_H