Add gtk-doc blurbs to pango elements.

Original commit message from CVS:
* docs/plugins/Makefile.am:
* docs/plugins/gst-plugins-base-plugins-docs.sgml:
* docs/plugins/gst-plugins-base-plugins-sections.txt:
* docs/plugins/gst-plugins-base-plugins.hierarchy:
* ext/pango/gstclockoverlay.c:
* ext/pango/gsttextoverlay.c:
* ext/pango/gsttextrender.c:
* ext/pango/gsttimeoverlay.c:
Add gtk-doc blurbs to pango elements.

ChangeLog

@@ -1,3 +1,15 @@
+2005-12-02  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/plugins/Makefile.am:
+	* docs/plugins/gst-plugins-base-plugins-docs.sgml:
+	* docs/plugins/gst-plugins-base-plugins-sections.txt:
+	* docs/plugins/gst-plugins-base-plugins.hierarchy:
+	* ext/pango/gstclockoverlay.c:
+	* ext/pango/gsttextoverlay.c: 
+	* ext/pango/gsttextrender.c:
+	* ext/pango/gsttimeoverlay.c:
+	  Add gtk-doc blurbs to pango elements.
+
 2005-12-02  Wim Taymans  <wim@fluendo.com>
 
 	* gst/audioresample/buffer.c: (audioresample_buffer_queue_flush):

docs/plugins/Makefile.am

@@ -77,6 +77,10 @@ IGNORE_CFILES = utils.c mem.c imgconvert.c
 #	$(top_srcdir)/ext/gnomevfs/gstgnomevfssink.c 
 
 EXTRA_HFILES = \
+	$(top_srcdir)/ext/pango/gstclockoverlay.h \
+	$(top_srcdir)/ext/pango/gsttextoverlay.h \
+	$(top_srcdir)/ext/pango/gsttextrender.h \
+	$(top_srcdir)/ext/pango/gsttimeoverlay.h \
 	$(top_srcdir)/ext/theora/gsttheoraenc.h \
 	$(top_srcdir)/ext/vorbis/vorbisenc.h \
 	$(top_srcdir)/gst/audioconvert/gstaudioconvert.h \

docs/plugins/gst-plugins-base-plugins-docs.sgml

@@ -14,6 +14,7 @@
     <title>gst-plugins-base Elements</title>
     <xi:include href="xml/element-audioconvert.xml" />
     <xi:include href="xml/element-audiotestsrc.xml" />
+    <xi:include href="xml/element-clockoverlay.xml" />
     <xi:include href="xml/element-ffmpegcolorspace.xml" />
 <!--
     <xi:include href="xml/element-gnomevfssink.xml" />
@@ -21,6 +22,9 @@
     <xi:include href="xml/element-multifdsink.xml" />
     <xi:include href="xml/element-tcpserversink.xml" />
     <xi:include href="xml/element-theoraenc.xml" />
+    <xi:include href="xml/element-textoverlay.xml" />
+    <xi:include href="xml/element-textrender.xml" />
+    <xi:include href="xml/element-timeoverlay.xml" />
     <xi:include href="xml/element-videotestsrc.xml" />
     <xi:include href="xml/element-volume.xml" />
     <xi:include href="xml/element-vorbisenc.xml" />

docs/plugins/gst-plugins-base-plugins-sections.txt

@@ -15,6 +15,14 @@ GstAudioTestSrc
 GstAudioTestSrcClass
 </SECTION>
 
+<SECTION>
+<FILE>element-clockoverlay</FILE>
+<TITLE>clockoverlay</TITLE>
+GstClockOverlay
+<SUBSECTION Standard>
+GstClockOverlayClass
+</SECTION>
+
 <SECTION>
 <FILE>element-ffmpegcolorspace</FILE>
 <TITLE>ffmpegcolorspace</TITLE>
@@ -53,6 +61,22 @@ GstTCPServerSink
 GstTCPServerSinkClass
 </SECTION>
 
+<SECTION>
+<FILE>element-textoverlay</FILE>
+<TITLE>textoverlay</TITLE>
+GstTextOverlay
+<SUBSECTION Standard>
+GstTextOverlayClass
+</SECTION>
+
+<SECTION>
+<FILE>element-textrender</FILE>
+<TITLE>textrender</TITLE>
+GstTextRender
+<SUBSECTION Standard>
+GstTextRenderClass
+</SECTION>
+
 <SECTION>
 <FILE>element-theoraenc</FILE>
 <TITLE>theoraenc</TITLE>
@@ -62,6 +86,14 @@ GstTheoraEncBorderMode
 GstTheoraEncClass
 </SECTION>
 
+<SECTION>
+<FILE>element-timeoverlay</FILE>
+<TITLE>timeoverlay</TITLE>
+GstTimeOverlay
+<SUBSECTION Standard>
+GstTimeOverlayClass
+</SECTION>
+
 <SECTION>
 <FILE>element-videotestsrc</FILE>
 <TITLE>videotestsrc</TITLE>
@@ -108,27 +140,27 @@ GstXvImagesSinkClass
 
 CLIENTS_UNLOCK
 CLIENTS_LOCK_INIT
-GST_MULTIFDSINK_GET_CLASS
+GST_MULTI_FD_SINK_GET_CLASS
 CLIENTS_LOCK_FREE
-GST_IS_MULTIFDSINK_CLASS
+GST_IS_MULTI_FD_SINK_CLASS
-gst_multifdsink_get_type
+gst_multi_fd_sinkget_type
-gst_multifdsink_remove
+gst_multi_fd_sinkremove
-GST_IS_MULTIFDSINK
+GST_IS_MULTI_FD_SINK
 CLIENTS_LOCK
-GST_TYPE_MULTIFDSINK
+GST_TYPE_MULTI_FD_SINK
-gst_multifdsink_clear
+gst_multi_fd_sinkclear
 GstTCPClient
-GST_MULTIFDSINK_CLASS
+GST_MULTI_FD_SINK_CLASS
-gst_multifdsink_get_stats
+gst_multi_fd_sinkget_stats
-GST_MULTIFDSINK
+GST_MULTI_FD_SINK
-gst_multifdsink_add
+gst_multi_fd_sinkadd
 
-GST_TCPSERVERSINK
+GST_TCP_SERVER_SINK
 GstTCPServerSinkFlags
-GST_TYPE_TCPSERVERSINK
+GST_TYPE_TCP_SERVER_SINK
-gst_tcpserversink_get_type
+gst_tcp_server_sink_get_type
-GST_IS_TCPSERVERSINK_CLASS
+GST_IS_TCP_SERVER_SINK_CLASS
-GST_IS_TCPSERVERSINK
+GST_IS_TCP_SERVER_SINK
 
 GST_GNOMEVFSSINK_CLASS
 GST_TYPE_GNOMEVFSSINK
@@ -142,7 +174,7 @@ GST_GNOMEVFSSINK
 GST_IS_VORBISENC
 GST_VORBISENC_CLASS
 GST_VORBISENC
-GST_TCPSERVERSINK_CLASS
+GST_TCP_SERVER_SINK_CLASS
 GST_TYPE_VORBISENC
 GST_IS_VORBISENC_CLASS
 vorbisenc_get_type

docs/plugins/gst-plugins-base-plugins.hierarchy

@@ -47,6 +47,10 @@ GObject
       GstVorbisEnc
       GstVorbisDec
       GstVorbisParse
+      GstTextOverlay
+        GstTimeOverlay
+        GstClockOverlay
+      GstTextRender
       GstTheoraDec
       GstTheoraEnc
       GstVisual

ext/pango/gstclockoverlay.c

@@ -18,6 +18,37 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-clockoverlay
+ * @see_also: #GstTextOverlay, #GstTimeOverlay
+ *
+ * <refsect2>
+ * <para>
+ * This element overlays the current clock time on top of a video
+ * stream. You can position the text and configure the font details
+ * using the properties of the #GstTextOverlay class. By default, the
+ * time is displayed in the top left corner of the picture, with some
+ * padding to the left and to the top.
+ * </para>
+ * <para>
+ * Here is a simple pipeline that displays the current time in the top left
+ * corner of the video picture:
+ * <programlisting>
+ * gst-launch -v videotestsrc ! clockoverlay ! xvimagesink
+ * </programlisting>
+ * </para>
+ * <para>
+ * Here is another pipeline that displays the current time with some leading
+ * text in the bottom right corner of the video picture, with the background
+ * of the text being shaded in order to make it more legible on top of a
+ * bright video background:
+ * <programlisting>
+ * gst-launch -v videotestsrc ! clockoverlay halign=right valign=bottom text="Edge City" shaded-background=true ! ffmpegcolorspace ! ximagesink
+ * </programlisting>
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif

ext/pango/gsttextoverlay.c

@@ -18,6 +18,59 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-textoverlay
+ * @see_also: #GstTextRender, #GstClockOverlay, #GstTimeOverlay, #GstSubParse
+ *
+ * <refsect2>
+ * <para>
+ * This plugin renders text on top of a video stream. This can be either
+ * static text or text from buffers received on the text sink pad, e.g.
+ * as produced by the subparse element. If the text sink pad is not linked,
+ * the text set via the "text" property will be rendered. If the text sink
+ * pad is linked, text will be rendered as it is received on that pad,
+ * honouring and matching the buffer timestamps of both input streams.
+ * </para>
+ * <para>
+ * The text can contain newline characters and text wrapping is enabled by
+ * default.
+ * </para>
+ * <para>
+ * Here is a simple pipeline that displays a static text in the top left
+ * corner of the video picture:
+ * <programlisting>
+ * gst-launch -v videotestsrc ! textoverlay text="Room A" valign=top halign=left ! xvimagesink
+ * </programlisting>
+ * </para>
+ * <para>
+ * Here is another pipeline that displays subtitles from an .srt subtitle 
+ * file, centered at the bottom of the picture and with a rectangular shading
+ * around the text in the background:
+ * <programlisting>
+ * gst-launch -v filesrc location=subtitles.srt ! subparse ! txt.   videotestsrc ! timeoverlay ! textoverlay name=txt shaded-background=yes ! xvimagesink
+ * </programlisting>
+ * If you do not have such a subtitle file, create on looking like this
+ * in a text editor:
+ * <programlisting>
+ * 1
+ * 00:00:03,000 --> 00:00:05,000
+ * Hello? (3-5s)
+ * 
+ * 2
+ * 00:00:08,000 --> 00:00:13,000
+ * Yes, this is a subtitle. Don&apos;t
+ * you like it? (8-13s)
+ * 
+ * 3
+ * 00:00:18,826 --> 00:01:02,886
+ * Uh? What are you talking about?
+ * I don&apos;t understand  (18-62s)
+ * </programlisting>
+ * </para>
+ * </refsect2>
+ */
+
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif

ext/pango/gsttextrender.c

@@ -18,6 +18,30 @@
  * Boston, MA 02111-1307, USA.
  */
 
+
+/**
+ * SECTION:element-textrender
+ * @see_also: #GstTextOverlay
+ *
+ * <refsect2>
+ * <para>
+ * This plugin renders text received on the text sink pad to a video
+ * buffer (retaining the alpha channel), so it can later be overlayed
+ * on top of video streams using other elements.
+ * </para>
+ * <para>
+ * The text can contain newline characters. (FIXME: What about text 
+ * wrapping? It does not make sense in this context)
+ * </para>
+ * <para>
+ * Example pipeline:
+ * <programlisting>
+ * gst-launch -v filesrc location=subtitles.srt ! subparse ! textrender ! xvimagesink
+ * </programlisting>
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include <config.h>
 #endif

ext/pango/gsttimeoverlay.c

@@ -18,6 +18,37 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:element-timeoverlay
+ * @see_also: #GstTextOverlay, #GstClockOverlay
+ *
+ * <refsect2>
+ * <para>
+ * This element overlays the buffer time stamps of a video stream on
+ * top of itself. You can position the text and configure the font details
+ * using the properties of the #GstTextOverlay class. By default, the
+ * time stamp is displayed in the top left corner of the picture, with some
+ * padding to the left and to the top.
+ * </para>
+ * <para>
+ * Here is a simple pipeline that displays the time stamps in the top left
+ * corner of the video picture:
+ * <programlisting>
+ * gst-launch -v videotestsrc ! timeoverlay ! xvimagesink
+ * </programlisting>
+ * </para>
+ * <para>
+ * Here is another pipeline that displays the time stamps with some leading
+ * text in the bottom right corner of the video picture, with the background
+ * of the text being shaded in order to make it more legible on top of a
+ * bright video background:
+ * <programlisting>
+ * gst-launch -v videotestsrc ! timeoverlay halign=right valign=bottom text="Stream time:" shaded-background=true ! xvimagesink
+ * </programlisting>
+ * </para>
+ * </refsect2>
+ */
+
 #ifdef HAVE_CONFIG_H
 #include "config.h"
 #endif