docs/plugins/: Add cdparanoiasrc to docs.

Original commit message from CVS:
* docs/plugins/gst-plugins-base-plugins-docs.sgml:
* docs/plugins/gst-plugins-base-plugins-sections.txt:
* docs/plugins/gst-plugins-base-plugins.hierarchy:
Add cdparanoiasrc to docs.
* gst-libs/gst/cdda/gstcddabasesrc.c:
More GstCddaBaseSrc docs.

diff --git a/ChangeLog b/ChangeLog
index 2a42cc3..9c05a77 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 2006-03-12  Tim-Philipp Müller  <tim at centricular dot net>
 
+       * docs/plugins/gst-plugins-base-plugins-docs.sgml:
+       * docs/plugins/gst-plugins-base-plugins-sections.txt:
+       * docs/plugins/gst-plugins-base-plugins.hierarchy:
+         Add cdparanoiasrc to docs.
+
+       * gst-libs/gst/cdda/gstcddabasesrc.c:
+         More GstCddaBaseSrc docs.
+
+2006-03-12  Tim-Philipp Müller  <tim at centricular dot net>
+
        * docs/libs/gst-plugins-base-libs-sections.txt:
        * gst-libs/gst/tag/gstid3tag.c: (gst_tag_from_id3_user_tag):
        * gst-libs/gst/tag/tag.h:

diff --git a/docs/plugins/gst-plugins-base-plugins-docs.sgml b/docs/plugins/gst-plugins-base-plugins-docs.sgml
index 8b3773a..5b4a520 100644 (file)
--- a/docs/plugins/gst-plugins-base-plugins-docs.sgml
+++ b/docs/plugins/gst-plugins-base-plugins-docs.sgml
@@ -18,6 +18,7 @@
     <xi:include href="xml/element-audioconvert.xml" />
     <xi:include href="xml/element-audioresample.xml" />
     <xi:include href="xml/element-audiotestsrc.xml" />
+    <xi:include href="xml/element-cdparanoiasrc.xml" />
     <xi:include href="xml/element-clockoverlay.xml" />
     <xi:include href="xml/element-ffmpegcolorspace.xml" />
     <xi:include href="xml/element-gnomevfssink.xml" />

diff --git a/docs/plugins/gst-plugins-base-plugins-sections.txt b/docs/plugins/gst-plugins-base-plugins-sections.txt
index 1e855df..55cb9ea 100644 (file)
--- a/docs/plugins/gst-plugins-base-plugins-sections.txt
+++ b/docs/plugins/gst-plugins-base-plugins-sections.txt
@@ -92,6 +92,14 @@ PINK_RANDOM_SHIFT
 </SECTION>
 
 <SECTION>
+<FILE>element-cdparanoiasrc</FILE>
+<TITLE>cdparanoiasrc</TITLE>
+GstCdParanoiaSrc
+<SUBSECTION Standard>
+GstCdParanoiaSrcClass
+</SECTION>
+
+<SECTION>
 <FILE>element-clockoverlay</FILE>
 <TITLE>clockoverlay</TITLE>
 GstClockOverlay

diff --git a/docs/plugins/gst-plugins-base-plugins.hierarchy b/docs/plugins/gst-plugins-base-plugins.hierarchy
index b831a75..1fcdad0 100644 (file)
--- a/docs/plugins/gst-plugins-base-plugins.hierarchy
+++ b/docs/plugins/gst-plugins-base-plugins.hierarchy
@@ -22,6 +22,8 @@ GObject
       GstBaseSrc
         GstAudioTestSrc
         GstPushSrc
+          GstCddaBaseSrc
+            GstCdParanoiaSrc
           GstTCPClientSrc
           GstTCPServerSrc
           GstVideoTestSrc

diff --git a/gst-libs/gst/cdda/gstcddabasesrc.c b/gst-libs/gst/cdda/gstcddabasesrc.c
index 192fe32..1f02539 100644 (file)
--- a/gst-libs/gst/cdda/gstcddabasesrc.c
+++ b/gst-libs/gst/cdda/gstcddabasesrc.c
@@ -44,6 +44,32 @@
  * Provides a base class for CDDA sources, which handles things like seeking,
  * querying, discid calculation, tags, and buffer timestamping.
  * </para>
+ * <title>Using GstCddaBaseSrc-based elements in applications</title>
+ * <para>
+ * GstCddaBaseSrc registers two #GstFormat<!-- -->s of its own, namely
+ * the "track" format and the "sector" format. Applications will usually
+ * only find the "track" format interesting. You can retrieve that #GstFormat
+ * for use in seek events or queries with gst_format_get_by_nick("track").
+ * </para>
+ * <para>
+ * In order to query the number of tracks, for example, an application would
+ * set the CDDA source element to READY or PAUSED state and then query the
+ * the number of tracks via gst_element_query_duration() using the track
+ * format acquired above. Applications can query the currently playing track
+ * in the same way.
+ * </para>
+ * <para>
+ * Alternatively, applications may retrieve the currently playing track and
+ * the total number of tracks from the taglist that will posted on the bus
+ * whenever the CD is opened or the currently playing track changes. The
+ * taglist will contain GST_TAG_TRACK_NUMBER and GST_TAG_TRACK_COUNT tags.
+ * </para>
+ * <para>
+ * Applications playing back CD audio using playbin and cdda://n URIs should
+ * issue a seek command in track format to change between tracks, rather than
+ * setting a new cdda://n+1 URI on playbin (as setting a new URI on playbin
+ * involves closing and re-opening the CD device, which is much much slower).
+ * </para>
  * </refsect2>
  */