Random doc of the day: the deinterlace element.

Original commit message from CVS:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-bad-plugins-docs.sgml:
* docs/plugins/gst-plugins-bad-plugins-sections.txt:
* docs/plugins/inspect/plugin-gstinterlace.xml:
* gst/deinterlace/gstdeinterlace.c:
* gst/deinterlace/gstdeinterlace.h:
Random doc of the day: the deinterlace element.

7 files changed, 102 insertions, 11 deletions

diff --git a/ChangeLog b/ChangeLog
index 18d7acfb..4b56bc30 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2008-05-11  Jan Schmidt  <jan.schmidt@sun.com>
+
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-bad-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-bad-plugins-sections.txt:
+	* docs/plugins/inspect/plugin-gstinterlace.xml:
+	* gst/deinterlace/gstdeinterlace.c:
+	* gst/deinterlace/gstdeinterlace.h:
+	Random doc of the day: the deinterlace element.
+
 2008-05-09  Zaheer Abbas Merali  <zaheerabbas at merali dot org>
 
 	* gst/mpegtsparse/mpegtspacketizer.c:
diff --git a/docs/plugins/Makefile.am b/docs/plugins/Makefile.am
index 9e4a7cde..a96d2029 100644
--- a/docs/plugins/Makefile.am
+++ b/docs/plugins/Makefile.am
@@ -111,6 +111,7 @@ EXTRA_HFILES = \
 	$(top_srcdir)/ext/theora/theoradec.h \
 	$(top_srcdir)/ext/timidity/gsttimidity.h \
 	$(top_srcdir)/ext/timidity/gstwildmidi.h \
+	$(top_srcdir)/gst/deinterlace/gstdeinterlace.h \
 	$(top_srcdir)/gst/dvdspu/gstdvdspu.h \
 	$(top_srcdir)/gst/festival/gstfestival.h \
 	$(top_srcdir)/gst/modplug/gstmodplug.h \
diff --git a/docs/plugins/gst-plugins-bad-plugins-docs.sgml b/docs/plugins/gst-plugins-bad-plugins-docs.sgml
index 38d7d07f..0b062e59 100644
--- a/docs/plugins/gst-plugins-bad-plugins-docs.sgml
+++ b/docs/plugins/gst-plugins-bad-plugins-docs.sgml
@@ -16,7 +16,7 @@
     <xi:include href="xml/element-amrwbenc.xml" />
     <xi:include href="xml/element-amrwbparse.xml" />
     <xi:include href="xml/element-audioparse.xml" />
-    <xi:include href="xml/element-dfb-example.xml" />
+    <xi:include href="xml/element-deinterlace.xml" />
     <xi:include href="xml/element-dfbvideosink.xml" />
     <xi:include href="xml/element-dvbsrc.xml" />
     <xi:include href="xml/element-dvdspu.xml" />
diff --git a/docs/plugins/gst-plugins-bad-plugins-sections.txt b/docs/plugins/gst-plugins-bad-plugins-sections.txt
index 90ff6da5..039772f4 100644
--- a/docs/plugins/gst-plugins-bad-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-bad-plugins-sections.txt
@@ -69,6 +69,20 @@ gst_dc1394_get_type
 </SECTION>
 
 <SECTION>
+<FILE>element-deinterlace</FILE>
+<TITLE>deinterlace</TITLE>
+GstDeinterlace
+<SUBSECTION Standard>
+GstDeinterlaceClass
+GST_DEINTERLACE
+GST_DEINTERLACE_CLASS
+GST_IS_DEINTERLACE
+GST_IS_DEINTERLACE_CLASS
+GST_TYPE_DEINTERLACE
+gst_deinterlace_get_type
+</SECTION>
+
+<SECTION>
 <FILE>element-dfbvideosink</FILE>
 <TITLE>dfbvideosink</TITLE>
 GstDfbVideoSink
diff --git a/docs/plugins/inspect/plugin-gstinterlace.xml b/docs/plugins/inspect/plugin-gstinterlace.xml
index 4a639b2b..a006595e 100644
--- a/docs/plugins/inspect/plugin-gstinterlace.xml
+++ b/docs/plugins/inspect/plugin-gstinterlace.xml
@@ -3,10 +3,10 @@
   <description>Deinterlace video</description>
   <filename>../../gst/deinterlace/.libs/libgstdeinterlace.so</filename>
   <basename>libgstdeinterlace.so</basename>
-  <version>0.10.7</version>
+  <version>0.10.7.1</version>
   <license>LGPL</license>
   <source>gst-plugins-bad</source>
-  <package>GStreamer Bad Plug-ins source release</package>
+  <package>GStreamer Bad Plug-ins CVS/prerelease</package>
   <origin>Unknown package origin</origin>
   <elements>
     <element>
@@ -17,14 +17,14 @@
       <author>Wim Taymans &lt;wim.taymans@gmail.com&gt;</author>
       <pads>
         <caps>
-          <name>src</name>
-          <direction>source</direction>
+          <name>sink</name>
+          <direction>sink</direction>
           <presence>always</presence>
           <details>video/x-raw-yuv, format=(fourcc){ I420, Y42B }, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]</details>
         </caps>
         <caps>
-          <name>sink</name>
-          <direction>sink</direction>
+          <name>src</name>
+          <direction>source</direction>
           <presence>always</presence>
           <details>video/x-raw-yuv, format=(fourcc){ I420, Y42B }, width=(int)[ 1, 2147483647 ], height=(int)[ 1, 2147483647 ], framerate=(fraction)[ 0/1, 2147483647/1 ]</details>
         </caps>
diff --git a/gst/deinterlace/gstdeinterlace.c b/gst/deinterlace/gstdeinterlace.c
index 39105b57..cd0b8533 100644
--- a/gst/deinterlace/gstdeinterlace.c
+++ b/gst/deinterlace/gstdeinterlace.c
@@ -28,6 +28,26 @@
 #include "gstdeinterlace.h"
 #include <gst/video/video.h>
 
+/**
+ * SECTION:element-deinterlace
+ * @short_description: Adaptively deinterlace video
+ *
+ * <refsect2>
+ * <para>
+ * Adaptively deinterlaces video frames by detecting interlacing artifacts.
+ * An edge detection matrix is used, with a threshold value. Pixels detected
+ * as 'interlaced' are replaced with pixels blended from the pixels above and
+ * below.
+ * </para>
+ * <title>Example launch line</title>
+ * <para>
+ * <programlisting>
+ * gst-launch -v videotestsrc ! deinterlace ! ffmpegcolorspace ! xvimagesink
+ * </programlisting>
+ * </para>
+ * </refsect2>
+ */
+
 GST_DEBUG_CATEGORY_STATIC (deinterlace_debug);
 #define GST_CAT_DEFAULT deinterlace_debug
 
@@ -103,26 +123,71 @@ gst_deinterlace_class_init (GstDeinterlaceClass * klass)
   gobject_class->set_property = gst_deinterlace_set_property;
   gobject_class->get_property = gst_deinterlace_get_property;
 
+  /**
+   * GstDeinterlace:deinterlace:
+   *
+   * Turn processing on/off. When false, no modification of the 
+   * video frames occurs and they pass through intact.
+   */
   g_object_class_install_property (gobject_class, ARG_DEINTERLACE,
       g_param_spec_boolean ("deinterlace", "deinterlace",
           "turn deinterlacing on/off", DEFAULT_DEINTERLACE, G_PARAM_READWRITE));
+  /**
+   * GstDeinterlace:di-area-only:
+   *
+   * When set to true, only areas affected by the deinterlacing are output,
+   * making it easy to see which regions are being modified.
+   *
+   * See Also: #GstDeinterlace::ni-area-only
+   */
   g_object_class_install_property (gobject_class, ARG_DI_ONLY,
       g_param_spec_boolean ("di-area-only", "di-area-only",
           "displays deinterlaced areas only", DEFAULT_DI_AREA_ONLY,
           G_PARAM_READWRITE));
+  /**
+   * GstDeinterlace:ni-area-only:
+   *
+   * When set to true, only areas unaffected by the deinterlacing are output,
+   * making it easy to see which regions are being preserved intact.
+   *
+   * See Also: #GstDeinterlace::di-area-only
+   */
   g_object_class_install_property (gobject_class, ARG_NI_ONLY,
       g_param_spec_boolean ("ni-area-only", "ni-area-only",
           "displays non-interlaced areas only", DEFAULT_DI_AREA_ONLY,
           G_PARAM_READWRITE));
+  /**
+   * GstDeinterlace:blend:
+   *
+   * Change the blending for pixels which are detected as
+   * 'interlacing artifacts'. When true, the output pixel is a weighted
+   * average (1,2,1) of the pixel and the pixels above and below it.
+   * When false, the odd field lines are preserved, and the even field lines
+   * are averaged from the surrounding pixels above and below (the odd field).
+   */
   g_object_class_install_property (gobject_class, ARG_BLEND,
       g_param_spec_boolean ("blend", "blend", "blend", DEFAULT_BLEND,
           G_PARAM_READWRITE));
+  /**
+   * GstDeinterlace:threshold:
+   *
+   * Affects the threshold of the edge-detection function used for detecting
+   * interlacing artifacts.
+   */
   g_object_class_install_property (gobject_class, ARG_THRESHOLD,
-      g_param_spec_int ("threshold", "threshold", "threshold", G_MININT,
-          G_MAXINT, 0, G_PARAM_READWRITE));
+      g_param_spec_int ("threshold", "Edge-detection threshold",
+          "Threshold value for the interlacing artifacts in the output "
+          "of the edge detection", G_MININT, G_MAXINT, 0, G_PARAM_READWRITE));
+  /**
+   * GstDeinterlace:edge-detect:
+   *
+   * Affects the weighting of the edge-detection function used for detecting
+   * interlacing artifacts.
+   */
   g_object_class_install_property (gobject_class, ARG_EDGE_DETECT,
-      g_param_spec_int ("edge-detect", "edge-detect", "edge-detect", G_MININT,
-          G_MAXINT, 0, G_PARAM_READWRITE));
+      g_param_spec_int ("edge-detect", "edge detection weighting",
+          "Weighting value used for calculating the edge detection matrix",
+          G_MININT, G_MAXINT, 0, G_PARAM_READWRITE));
 
   basetransform_class->transform_ip =
       GST_DEBUG_FUNCPTR (gst_deinterlace_transform_ip);
diff --git a/gst/deinterlace/gstdeinterlace.h b/gst/deinterlace/gstdeinterlace.h
index 3e7c834e..faa8e811 100644
--- a/gst/deinterlace/gstdeinterlace.h
+++ b/gst/deinterlace/gstdeinterlace.h
@@ -38,6 +38,7 @@ typedef struct _GstDeinterlaceClass GstDeinterlaceClass;
 struct _GstDeinterlace {
   GstBaseTransform basetransform;
 
+  /*< private >*/
   gint         width;
   gint         height;
   gint         uv_height;