Documentation updates. Make BaseSink and BaseSrc docs contain the class structure so that people can actually see the...

Original commit message from CVS:
* docs/libs/gstreamer-libs-sections.txt:
* gst/gsttaglist.c:
* libs/gst/base/gstbasesink.c:
* libs/gst/base/gstbasesink.h:
* libs/gst/base/gstbasesrc.c:
* libs/gst/base/gstbasesrc.h:
Documentation updates. Make BaseSink and BaseSrc docs contain the
class structure so that people can actually see the prototypes for
virtual functions they're supposed to be overriding.

ChangeLog

@@ -1,3 +1,15 @@
+2006-04-04  Jan Schmidt  <thaytan@mad.scientist.com>
+
+	* docs/libs/gstreamer-libs-sections.txt:
+	* gst/gsttaglist.c:
+	* libs/gst/base/gstbasesink.c:
+	* libs/gst/base/gstbasesink.h:
+	* libs/gst/base/gstbasesrc.c:
+	* libs/gst/base/gstbasesrc.h:
+	  Documentation updates. Make BaseSink and BaseSrc docs contain the
+	  class structure so that people can actually see the prototypes for
+	  virtual functions they're supposed to be overriding.
+
 2006-04-04  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* plugins/elements/gsttypefindelement.c:

docs/libs/gstreamer-libs-sections.txt

@@ -129,6 +129,7 @@ gst_adapter_get_type
 <TITLE>GstBaseSrc</TITLE>
 <INCLUDE>gst/base/gstbasesrc.h</INCLUDE>
 GstBaseSrc
+GstBaseSrcClass
 GstBaseSrcFlags
 
 gst_base_src_is_live
@@ -137,7 +138,6 @@ gst_base_src_set_format
 
 GST_BASE_SRC_PAD
 <SUBSECTION Standard>
-GstBaseSrcClass
 GstBaseSrcPrivate
 GST_BASE_SRC
 GST_BASE_SRC_CAST
@@ -156,6 +156,7 @@ gst_base_src_get_type
 <TITLE>GstBaseSink</TITLE>
 <INCLUDE>gst/base/gstbasesink.h</INCLUDE>
 GstBaseSink
+GstBaseSinkClass
 
 GST_BASE_SINK_PAD
 
@@ -165,7 +166,6 @@ gst_base_sink_set_max_lateness
 gst_base_sink_get_max_lateness
 
 <SUBSECTION Standard>
-GstBaseSinkClass
 GST_BASE_SINK
 GST_BASE_SINK_CAST
 GST_IS_BASE_SINK

gst/gsttaglist.c

@@ -1257,6 +1257,9 @@ TAG_MERGE_FUNCS (pointer, gpointer)
  * Copies the contents for the given tag into the value, merging multiple values
  * into one if multiple values are associated with the tag.
  * 
+ * The resulting string in @value should be freed by the caller using g_free 
+ * when no longer needed
+ *
  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
  *              given list.
  */
@@ -1270,6 +1273,9 @@ TAG_MERGE_FUNCS (pointer, gpointer)
  * Gets the value that is at the given index for the given tag in the given
  * list.
  *
+ * The resulting string in @value should be freed by the caller using g_free 
+ * when no longer needed
+ *
  * Returns: TRUE, if a value was copied, FALSE if the tag didn't exist in the
  *              given list.
  */

libs/gst/base/gstbasesink.c

@@ -26,15 +26,17 @@
  *
  * #GstBaseSink is the base class for sink elements in GStreamer, such as
  * xvimagesink or filesink. It is a layer on top of #GstElement that provides a
- * simplified interface to plugin writers. #GstBaseSink handles many details for
+ * simplified interface to plugin writers. #GstBaseSink handles many details 
- * you, for example preroll, clock synchronization, state changes, activation in
+ * for you, for example: preroll, clock synchronization, state changes, 
- * push or pull mode, and queries. In most cases, when writing sink elements,
+ * activation in push or pull mode, and queries. 
- * there is no need to implement class methods from #GstElement or to set
- * functions on pads, because the #GstBaseSink infrastructure should be sufficient.
  * 
- * There is only support in GstBaseSink for one sink pad, which should be named
+ * In most cases, when writing sink elements, there is no need to implement 
- * "sink". A sink implementation (subclass of GstBaseSink) should install a pad
+ * class methods from #GstElement or to set functions on pads, because the 
- * template in its base_init function, like so:
+ * #GstBaseSink infrastructure should be sufficient.
+ *
+ * #GstBaseSink provides support for exactly one sink pad, which should be 
+ * named "sink". A sink implementation (subclass of GstBaseSink) should 
+ * install a pad template in its base_init function, like so:
  * <programlisting>
  * static void
  * my_element_base_init (gpointer g_class)
@@ -51,75 +53,81 @@
  * </programlisting>
  *
  * #GstBaseSink will handle the prerolling correctly. This means that it will
- * return GST_STATE_CHANGE_ASYNC from a state change to PAUSED until the first buffer
+ * return GST_STATE_CHANGE_ASYNC from a state change to PAUSED until the first 
- * arrives in this element. The base class will call the GstBaseSink::preroll
+ * buffer arrives in this element. The base class will call the 
- * vmethod with this preroll buffer and will then commit the state change to the
+ * GstBaseSink::preroll vmethod with this preroll buffer and will then commit 
- * next asynchronously pending state.
+ * the state change to the next asynchronously pending state.
  *
- * When the element is set to PLAYING, #GstBaseSink will synchronize on the clock
+ * When the element is set to PLAYING, #GstBaseSink will synchronise on the 
- * using the times returned from ::get_times. If this function returns
+ * clock using the times returned from ::get_times. If this function returns
  * #GST_CLOCK_TIME_NONE for the start time, no synchronisation will be done.
- * Synchronisation can be disabled entirely by setting the object "sync" property 
+ * Synchronisation can be disabled entirely by setting the object "sync" 
- * to FALSE.
+ * property to FALSE.
  *
  * After synchronisation the virtual method #GstBaseSink::render will be called.
  * Subclasses should minimally implement this method.
  *
- * Since 0.10.3 subclasses that synchronize on the clock in the ::render method
+ * Since 0.10.3 subclasses that synchronise on the clock in the ::render method
  * are supported as well. These classes typically receive a buffer in the render
  * method and can then potentially block on the clock while rendering. A typical
- * example would be an audiosink. 
+ * example is an audiosink. 
  *
- * Upon receiving the EOS event in the PLAYING state, #GstBaseSink will wait for 
+ * Upon receiving the EOS event in the PLAYING state, #GstBaseSink will wait 
- * the clock to reach the time indicated by the stop time of the last ::get_times 
+ * for the clock to reach the time indicated by the stop time of the last 
- * call before posting an EOS message. When the element receives EOS in PAUSED,
+ * ::get_times call before posting an EOS message. When the element receives 
- * preroll completes, the event is queued and an EOS message is posted when going 
+ * EOS in PAUSED, preroll completes, the event is queued and an EOS message is 
- * to PLAYING.
+ * posted when going to PLAYING.
  * 
  * #GstBaseSink will internally use the GST_EVENT_NEW_SEGMENT events to schedule
  * synchronisation and clipping of buffers. Buffers that fall completely outside
- * of the segment are dropped. Buffers that fall partially in the segment are 
+ * of the current segment are dropped. Buffers that fall partially in the 
- * rendered (and prerolled), subclasses should do any subbuffer clipping themselves
+ * segment are rendered (and prerolled). Subclasses should do any subbuffer 
- * when needed.
+ * clipping themselves when needed.
  * 
  * #GstBaseSink will by default report the current playback position in 
  * GST_FORMAT_TIME based on the current clock time and segment information. 
- * If no clock has been set on the element, the query will be forwarded upstream.
+ * If no clock has been set on the element, the query will be forwarded 
+ * upstream.
  *
- * The ::set_caps function will be called when the subclass should configure itself
+ * The ::set_caps function will be called when the subclass should configure 
- * to process a specific media type.
+ * itself to process a specific media type.
  * 
- * The ::start and ::stop virtual methods will be called when resources should be
+ * The ::start and ::stop virtual methods will be called when resources should 
- * allocated. Any ::preroll, ::render  and ::set_caps function will be called
+ * be allocated. Any ::preroll, ::render  and ::set_caps function will be 
- * between the ::start and ::stop calls. 
+ * called between the ::start and ::stop calls. 
  *
  * The ::event virtual method will be called when an event is received by 
  * #GstBaseSink. Normally this method should only be overriden by very specific
- * elements such as file sinks that need to handle the newsegment event specially.
+ * elements (such as file sinks) which need to handle the newsegment event 
+ * specially.
  * 
- * #GstBaseSink provides an overridable ::buffer_alloc function that can be used
+ * #GstBaseSink provides an overridable ::buffer_alloc function that can be 
- * by specific sinks that want to do reverse negotiation or want to provided 
+ * used by sinks that want to do reverse negotiation or to provide
- * hardware accelerated buffers for downstream elements.
+ * custom buffers (hardware buffers for example) to upstream elements.
  *
  * The ::unlock method is called when the elements should unblock any blocking
- * operations they perform in the ::render method. This is mostly usefull when
+ * operations they perform in the ::render method. This is mostly useful when
- * the ::render method performs a blocking write on a file descripter.
+ * the ::render method performs a blocking write on a file descriptor, for 
+ * example.
  *
- * The max-lateness property defines how the sink deals with buffers that arrive 
+ * The max-lateness property affects how the sink deals with buffers that 
- * too late in the sink. A buffer arrives too late in the sink when the presentation
+ * arrive too late in the sink. A buffer arrives too late in the sink when 
- * time (as a combination of the last segment, buffer timestamp and element
+ * the presentation time (as a combination of the last segment, buffer 
- * base_time) plus the duration is before the current time of the clock. 
+ * timestamp and element base_time) plus the duration is before the current 
- * If the frame is later than max-lateness, the sink will drop the buffer. 
+ * time of the clock. 
- * This feature is disabled if sync is disabled, the ::get-times method does not
+ * If the frame is later than max-lateness, the sink will drop the buffer
- * return a valid start time or max-lateness is set to -1 (the default). 
+ * without calling the render method. 
- * Subclasses can use gst_base_sink_set_max_lateness() to configure the max-lateness.
+ * This feature is disabled if sync is disabled, the ::get-times method does 
+ * not return a valid start time or max-lateness is set to -1 (the default). 
+ * Subclasses can use gst_base_sink_set_max_lateness() to configure the 
+ * max-lateness value.
  *
  * The qos property will enable the quality-of-service features of the basesink 
  * which gather statistics about the real-time performance of the clock 
  * synchronisation. For each dropped buffer it will also send a QoS message 
  * upstream.
  *
- * Last reviewed on 2006-03-21 (0.10.5)
+ * Last reviewed on 2006-03-31 (0.10.5)
  */
 
 #ifdef HAVE_CONFIG_H

libs/gst/base/gstbasesink.h

@@ -102,6 +102,31 @@ struct _GstBaseSink {
   GstBaseSinkPrivate *priv;
 };
 
+/**
+ * GstBaseSinkClass:
+ * @parent_class: Element parent class
+ * @get_caps: Called to get sink pad caps from the subclass 
+ * @set_caps: Notify subclass of changed caps
+ * @buffer_alloc: Subclasses can override to perform custom buffer allocations
+ * @get_times: Called to get the start and end times for synchronising 
+ *             the passed buffer to the clock
+ * @start: Start processing. Ideal for opening resources in the subclass
+ * @stop: Stop processing. Subclasses should use this to close resources.
+ * @unlock: Unlock any pending access to the resource. Subclasses should 
+ *          unblock any blocked function ASAP
+ * @event: Override this to handle events arriving on the sink pad
+ * @preroll: Called to present the preroll buffer if desired
+ * @render: Called when a buffer should be presented or output, at the
+ *          correct moment if the #GstBaseSink has been set to sync to 
+ *          the clock.
+ * @async_play: Subclasses should override this when they need to perform
+ *          special processing when changing to the PLAYING state asynchronously.
+ *          Called with the OBJECT_LOCK held. 
+ *
+ * Subclasses can override any of the available virtual methods or not, as 
+ * needed. At the minimum, the render method should be overridden to 
+ * output/present buffers
+ */
 struct _GstBaseSinkClass {
   GstElementClass parent_class;
 

libs/gst/base/gstbasesrc.c

@@ -35,23 +35,25 @@
  *
  * <refsect2>
  * <para>
- * The source can be configured to operate in a any #GstFormat with the
+ * The source can be configured to operate in any #GstFormat with the
- * gst_base_src_set_format(). This format determines the format of the
+ * gst_base_src_set_format() method. The currently set format determines 
- * internal #GstSegment and the #GST_EVENT_NEW_SEGMENT. The default format for
+ * the format of the internal #GstSegment and any #GST_EVENT_NEW_SEGMENT 
- * #GstBaseSrc is GST_FORMAT_BYTES.
+ * events. The default format for #GstBaseSrc is #GST_FORMAT_BYTES.
  * </para>
  * <para>
- * #GstBaseSrc always supports the push mode scheduling. If the following
+ * #GstBaseSrc always supports push mode scheduling. If the following
  * conditions are met, it also supports pull mode scheduling:
  * <itemizedlist>
- *   <listitem><para>the format is set to GST_FORMAT_BYTES (default).</para></listitem>
+ *   <listitem><para>The format is set to GST_FORMAT_BYTES (default).</para>
- *   <listitem><para>#GstBaseSrc::is_seekable returns TRUE.</para></listitem>
+ *   </listitem>
+ *   <listitem><para>#GstBaseSrc::is_seekable returns TRUE.</para>
+ *   </listitem>
  * </itemizedlist>
  * </para>
  * <para>
  * If all the conditions are met for operating in pull mode, #GstBaseSrc is
- * automatically seekable in push mode as well. The following conditions must be
+ * automatically seekable in push mode as well. The following conditions must 
- * met to make the element seekable in push mode when the format is not
+ * be met to make the element seekable in push mode when the format is not
  * GST_FORMAT_BYTES:
  * <itemizedlist>
  *   <listitem><para>
@@ -67,37 +69,39 @@
  * </itemizedlist>
  * </para>
  * <para>
- * When the default format is not GST_FORMAT_BYTES, the element should ignore the
+ * When the default format is not GST_FORMAT_BYTES, the subclass should ignore 
- * offset and length in the #GstBaseSrc::create method. It is recommended to subclass
+ * the offset and length in the #GstBaseSrc::create method. It is recommended 
- * #GstPushSrc instead in this situation.
+ * to subclass #GstPushSrc instead in this situation.
  * </para>
  * <para>
- * #GstBaseSrc has support for live sources. Live sources are sources that produce
+ * #GstBaseSrc has support for live sources. Live sources are sources that 
- * data at a fixed rate, such as audio or video capture. A typical live source also
+ * produce data at a fixed rate, such as audio or video capture devices. A 
- * provides a clock to export the rate at which they produce data.
+ * typical live source also provides a clock to publish the rate at which 
+ * they produce data.
  * Use gst_base_src_set_live() to activate the live source mode.
  * </para>
  * <para>
- * A live source does not produce data in the PAUSED state, this means that the 
+ * A live source does not produce data in the PAUSED state. This means that the 
  * #GstBaseSrc::create method will not be called in PAUSED but only in PLAYING.
- * To signal the pipeline that the element will not produce data, its return
+ * To signal the pipeline that the element will not produce data, the return
  * value from the READY to PAUSED state will be GST_STATE_CHANGE_NO_PREROLL.
  * </para>
  * <para>
- * A typical live source will timestamp the buffers they create with the current
+ * A typical live source will timestamp the buffers they create with the 
- * stream time of the pipeline. This is why they can only produce data in PLAYING,
+ * current stream time of the pipeline. This is one reason that they can only 
- * when the clock is actually distributed and running.
+ * produce data in PLAYING, when the clock is actually distributed and running.
  * </para>
  * <para>
- * The #GstBaseSrc::get_times method can be used to implement pseudo-live sources.
+ * The #GstBaseSrc::get_times method can be used to implement pseudo-live 
- * The base source will wait for the specified stream time returned in 
+ * sources. The base source will wait for the specified stream time returned in 
- * #GstBaseSrc::get_times before pushing out the buffer. It only makes sense to implement
+ * #GstBaseSrc::get_times before pushing out the buffer. 
- * the ::get_times function if the source is a live source.
+ * It only makes sense to implement the ::get_times function if the source is 
+ * a live source.
  * </para>
  * <para>
- * There is only support in GstBaseSrc for one source pad, which should be named
+ * There is only support in GstBaseSrc for exactly one source pad, which 
- * "src". A source implementation (subclass of GstBaseSrc) should install a pad
+ * should be named "src". A source implementation (subclass of GstBaseSrc) 
- * template in its base_init function, like so:
+ * should install a pad template in its base_init function, like so:
  * </para>
  * <para>
  * <programlisting>
@@ -118,7 +122,7 @@
  * <para>
  * Applications that record from a live source may want to stop recording
  * in a controlled way, so that the recording is stopped, but the data
- * already in the pipeline processed to the end (remember that many live
+ * already in the pipeline is processed to the end (remember that many live
  * sources would go on recording forever otherwise). For that to happen the
  * application needs to make the source stop recording and send an EOS
  * event down the pipeline. The application would then wait for an
@@ -150,7 +154,7 @@
  * </programlisting>
  * </para>
  * <para>
- * Last reviewed on 2006-03-07 (0.10.4)
+ * Last reviewed on 2006-03-31 (0.10.5)
  * </para>
  * </refsect2>
  */

libs/gst/base/gstbasesrc.h

@@ -117,8 +117,31 @@ struct _GstBaseSrc {
 
 /**
  * GstBaseSrcClass:
- * @create: ask the subclass to create a buffer with offset and size
+ * @parent_class: Element parent class
- * @start: start processing
+ * @get_caps: Called to get the caps to report
+ * @set_caps: Notify subclass of changed output caps
+ * @negotiate: Negotiated the caps with the peer.
+ * @newsegment: Generate and send a new_segment event.
+ * @start: Start processing. Subclasses should open resources and prepare
+ *    to produce data.
+ * @stop: Stop processing. Subclasses should use this to close resources.
+ * @get_times: Given a buffer, return the start and stop time when it 
+ *    should be pushed out. The base class will sync on the clock using 
+ *    these times. 
+ * @get_size: Return the total size of the resource, in the configured format.
+ * @is_seekable: Check if the source can seek
+ * @unlock: Unlock any pending access to the resource. Subclasses should
+ *    unblock any blocked function ASAP
+ * @event: Override this to implement custom event handling.
+ * @create: Ask the subclass to create a buffer with offset and size.
+ * @do_seek: Perform seeking on the resource to the indicated segment.
+ * @query: Handle a requested query. 
+ * @check_get_range: Check whether the source would support pull-based 
+ *   operation if it were to be opened now. This vfunc is optional, but 
+ *   should be implemented if possible to avoid unnecessary start/stop 
+ *   cycles. The default implementation will open and close the resource 
+ *   to find out whether get_range is supported, and that is usually 
+ *   undesirable. 
  */
 struct _GstBaseSrcClass {
   GstElementClass parent_class;