review some docs

docs/pwg/advanced-events.xml

@@ -210,13 +210,13 @@ gst_my_filter_sink_event (GstPad  *pad, GstEvent * event)
         It is important to note that <emphasis>only elements driving the
         pipeline should ever send an EOS event</emphasis>. If your element
         is chain-based, it is not driving the pipeline. Chain-based elements
-        should just return GST_FLOW_UNEXPECTED from their chain function at
+        should just return GST_FLOW_EOS from their chain function at
         the end of the stream (or the configured segment), the upstream
         element that is driving the pipeline will then take care of
         sending the EOS event (or alternatively post a SEGMENT_DONE message
         on the bus depending on the mode of operation). If you are implementing
         your own source element, you also do not need to ever manually send
-        an EOS event, you should also just return GST_FLOW_UNEXPECTED in
+        an EOS event, you should also just return GST_FLOW_EOS in
         your create function (assuming your element derives from GstBaseSrc
         or GstPushSrc).
       </para>

gst/gstbin.c

@@ -154,7 +154,7 @@
  * </para>
  * </refsect2>
  *
- * Last reviewed on 2006-04-28 (0.10.6)
+ * Last reviewed on 2012-03-28 (0.11.3)
  */
 
 #include "gst_private.h"

gst/gstbuffer.c

@@ -22,14 +22,12 @@
 
 /**
  * SECTION:gstbuffer
- * @short_description: Data-passing buffer type, supporting sub-buffers.
+ * @short_description: Data-passing buffer type
- * @see_also: #GstPad, #GstMiniObject, #GstBufferPool
+ * @see_also: #GstPad, #GstMiniObject, #GstMemory, #GstMeta, #GstBufferPool
  *
- * Buffers are the basic unit of data transfer in GStreamer.  The #GstBuffer
+ * Buffers are the basic unit of data transfer in GStreamer. They contain the
- * type provides all the state necessary to define the regions of memory as
+ * timing and offset along with other arbitrary metadata that is associated
- * part of a stream. Region copies are also supported, allowing a smaller
+ * with the #GstMemory blocks that the buffer contains.
- * region of a buffer to become its own buffer, with mechanisms in place to
- * ensure that neither memory space goes away prematurely.
  *
  * Buffers are usually created with gst_buffer_new(). After a buffer has been
  * created one will typically allocate memory for it and add it to the buffer.
@@ -62,21 +60,29 @@
  * meaningful value can be given for these, they should be set. The timestamps
  * and duration are measured in nanoseconds (they are #GstClockTime values).
  *
+ * The buffer DTS refers to the timestamp when the buffer should be decoded and
+ * is usually monotonically increasing. The buffer PTS refers to the timestamp when
+ * the buffer content should be presented to the user and is not always
+ * monotonically increasing.
+ *
  * A buffer can also have one or both of a start and an end offset. These are
  * media-type specific. For video buffers, the start offset will generally be
  * the frame number. For audio buffers, it will be the number of samples
  * produced so far. For compressed data, it could be the byte offset in a
  * source or destination file. Likewise, the end offset will be the offset of
  * the end of the buffer. These can only be meaningfully interpreted if you
- * know the media type of the buffer (the #GstCaps set on it). Either or both
+ * know the media type of the buffer (the preceeding CAPS event). Either or both
  * can be set to #GST_BUFFER_OFFSET_NONE.
  *
  * gst_buffer_ref() is used to increase the refcount of a buffer. This must be
  * done when you want to keep a handle to the buffer after pushing it to the
- * next element.
+ * next element. The buffer refcount determines the writability of the buffer, a
+ * buffer is only writable when the refcount is exactly 1, i.e. when the caller
+ * has the only reference to the buffer.
  *
  * To efficiently create a smaller buffer out of an existing one, you can
- * use gst_buffer_copy_region().
+ * use gst_buffer_copy_region(). This method tries to share the memory objects
+ * between the two buffers.
  *
  * If a plug-in wants to modify the buffer data or metadata in-place, it should
  * first obtain a buffer that is safe to modify by using
@@ -91,14 +97,18 @@
  * gst_buffer_append(). Copying of memory will only be done when absolutely
  * needed.
  *
+ * Arbitrary extra metadata can be set on a buffer with gst_buffer_add_meta().
+ * Metadata can be retrieved with gst_buffer_get_meta(). See also #GstMeta
+ *
  * An element should either unref the buffer or push it out on a src pad
  * using gst_pad_push() (see #GstPad).
  *
  * Buffers are usually freed by unreffing them with gst_buffer_unref(). When
- * the refcount drops to 0, any data pointed to by the buffer is unreffed as
+ * the refcount drops to 0, any memory and metadata pointed to by the buffer is
- * well.
+ * unreffed as well. Buffers allocated from a #GstBufferPool will be returned to
+ * the pool when the refcount drops to 0.
  *
- * Last reviewed on November 8, 2011 (0.11.2)
+ * Last reviewed on 2012-03-28 (0.11.3)
  */
 #include "gst_private.h"
 

gst/gstbufferlist.c

@@ -30,6 +30,11 @@
  * Buffer lists are created with gst_buffer_list_new() and filled with data
  * using a gst_buffer_list_insert().
  *
+ * Buffer lists can be pushed on a srcpad with gst_pad_push_list(). This is
+ * interesting when multiple buffers need to be pushed in one go because it
+ * can reduce the amount of overhead for pushing each buffer individually.
+ *
+ * Last reviewed on 2012-03-28 (0.11.3)
  */
 #include "gst_private.h"
 

gst/gstbufferpool.c

@@ -24,6 +24,45 @@
  * @short_description: Pool for buffers
  * @see_also: #GstBuffer
  *
+ * a #GstBufferPool is an object that can be used to pre-allocate and recycle
+ * buffers of the same size and with the same properties.
+ *
+ * A #GstBufferPool is created with gst_buffer_pool_new().
+ *
+ * After the buffer is created, it needs to be configured.
+ * gst_buffer_pool_get_config() get the current configuration structure from the
+ * pool. With gst_buffer_pool_config_set_params() and
+ * gst_buffer_pool_config_set_allocator() the bufferpool parameters and allocator
+ * can be configured. Other properties can be configured in the pool depending
+ * on the pool implementation.
+ *
+ * A bufferpool can have extra options that can be enabled with
+ * gst_buffer_pool_config_add_option(). The available options can be retrieved
+ * with gst_buffer_pool_get_options(). Some options allow for additional
+ * configuration properties to be set.
+ *
+ * After the configuration structure has been configured,
+ * gst_buffer_pool_set_config() updates the configuration in the pool. This can
+ * fail when the configuration structure is not accepted.
+ *
+ * After the a pool has been configured, it can be activated with
+ * gst_buffer_pool_set_active(). This will preallocate the configured resources
+ * in the pool.
+ *
+ * When the pool is active, gst_buffer_pool_acquire_buffer() can be used to
+ * retrieve a buffer from the pool.
+ *
+ * Buffer allocated from a bufferpool will automatically be returned to the pool
+ * with gst_buffer_pool_release_buffer() when their refcount drops to 0.
+ *
+ * The bufferpool can be deactivated again with gst_buffer_pool_set_active().
+ * All further gst_buffer_pool_acquire_buffer() calls will return an error. When
+ * all buffers are returned to the pool they will be freed.
+ *
+ * Use gst_object_unref() to release the reference to a bufferpool. If the
+ * refcount of the pool reaches 0, the pool will be freed.
+ *
+ * Last reviewed on 2012-03-28 (0.11.3)
  */
 
 #include "gst_private.h"

gst/gstbufferpool.h

@@ -45,7 +45,7 @@ typedef struct _GstBufferPoolClass GstBufferPoolClass;
  * @GST_BUFFER_POOL_ACQUIRE_FLAG_NONE: no flags
  * @GST_BUFFER_POOL_ACQUIRE_FLAG_KEY_UNIT: buffer is keyframe
  * @GST_BUFFER_POOL_ACQUIRE_FLAG_DONTWAIT: don't wait for buffer. This makes the
- * acquire_buffer method return GST_FLOW_UNEXPECTED.
+ * acquire_buffer method return GST_FLOW_EOS.
  * @GST_BUFFER_POOL_ACQUIRE_FLAG_DISCONT: buffer is discont
  * @GST_BUFFER_POOL_ACQUIRE_FLAG_LAST: last flag, subclasses can use private flags
  *    starting from this value.
@@ -127,13 +127,13 @@ struct _GstBufferPool {
  *        will take a buffer from the queue and optionally wait for a buffer to
  *        be released when there are no buffers available.
  * @alloc_buffer: allocate a buffer. the default implementation allocates
- *        buffers from the default memory allocator and with the configured
+ *        buffers from the configured memory allocator and with the configured
- *        size, prefix, padding and alignment. All metadata that is present on the
+ *        parameters. All metadata that is present on the allocated buffer will
- *        allocated buffer will be marked as #GST_META_FLAG_POOLED and will not
+ *        be marked as #GST_META_FLAG_POOLED and will not be removed from the
- *        be removed from the buffer in @reset_buffer.
+ *        buffer in @reset_buffer.
  * @reset_buffer: reset the buffer to its state when it was freshly allocated.
  *        The default implementation will clear the flags, timestamps and
- *        will remove the metadata added after alloc_buffer.
+ *        will remove the metadata without the #GST_META_FLAG_POOLED flag.
  * @release_buffer: release a buffer back in the pool. The default
  *        implementation will put the buffer back in the queue and notify any
  *        blocking acquire_buffer calls.

gst/gstbus.c

@@ -64,7 +64,7 @@
  * Note that a #GstPipeline will set its bus into flushing state when changing
  * from READY to NULL state.
  *
- * Last reviewed on 2006-03-12 (0.10.5)
+ * Last reviewed on 2012-03-28 (0.11.3)
  */
 
 #include "gst_private.h"

gst/gstcaps.c

@@ -20,9 +20,9 @@
 /**
  * SECTION:gstcaps
  * @short_description: Structure describing sets of media formats
- * @see_also: #GstStructure
+ * @see_also: #GstStructure, #GstMiniObject
  *
- * Caps (capabilities) are lighweight refcounted objects describing media types.
+ * Caps (capabilities) are lightweight refcounted objects describing media types.
  * They are composed of an array of #GstStructure.
  *
  * Caps are exposed on #GstPadTemplate to describe all possible types a
@@ -33,10 +33,6 @@
  * function. This function describes the possible types that the pad can
  * handle or produce at runtime.
  *
- * Caps are also attached to buffers to describe to content of the data
- * pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
- * a #GstBuffer allow for format negotiation upstream and downstream.
- *
  * A #GstCaps can be constructed with the following code fragment:
  *
  * <example>
@@ -54,13 +50,13 @@
  * </example>
  *
  * A #GstCaps is fixed when it has no properties with ranges or lists. Use
- * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
+ * gst_caps_is_fixed() to test for fixed caps. Fixed caps can be used in a
- * set on a #GstPad or #GstBuffer.
+ * caps event to notify downstream elements of the current media type.
  *
  * Various methods exist to work with the media types such as subtracting
  * or intersecting.
  *
- * Last reviewed on 2007-02-13 (0.10.10)
+ * Last reviewed on 2011-03-28 (0.11.3)
  */
 
 #ifdef HAVE_CONFIG_H

gst/gstclock.c

@@ -99,7 +99,7 @@
  * number of samples to use when calibrating and #GstClock:window-threshold
  * defines the minimum number of samples before the calibration is performed.
  *
- * Last reviewed on 2009-05-21 (0.10.24)
+ * Last reviewed on 2012-03-28 (0.11.3)
  */
 
 

gst/gstelement.c

@@ -34,7 +34,7 @@
  * core when using the appropriate locking. Do not use this in plug-ins or
  * applications in order to retain ABI compatibility.
  *
- * All elements have pads (of the type #GstPad).  These pads link to pads on
+ * Elements can have pads (of the type #GstPad).  These pads link to pads on
  * other elements.  #GstBuffer flow between these linked pads.
  * A #GstElement has a #GList of #GstPad structures for all their input (or sink)
  * and output (or source) pads.
@@ -44,7 +44,7 @@
  * An existing pad of an element can be retrieved by name with
  * gst_element_get_static_pad(). A new dynamic pad can be created using
  * gst_element_request_pad() with a #GstPadTemplate or 
- * gst_element_get_request_pad() with the template name such as "src_\%d".
+ * gst_element_get_request_pad() with the template name such as "src_\%u".
  * An iterator of all pads can be retrieved with gst_element_iterate_pads().
  *
  * Elements can be linked through their pads.
@@ -65,18 +65,18 @@
  * You can get and set a #GstClock on an element using gst_element_get_clock()
  * and gst_element_set_clock().
  * Some elements can provide a clock for the pipeline if
- * gst_element_provides_clock() returns %TRUE. With the
+ * the #GST_ELEMENT_FLAG_PROVIDE_CLOCK flag is set. With the
  * gst_element_provide_clock() method one can retrieve the clock provided by
  * such an element.
- * Not all elements require a clock to operate correctly. If
+ * Not all elements require a clock to operate correctly. If the
- * gst_element_requires_clock() returns %TRUE, a clock should be set on the
+ * #GST_ELEMENT_FLAG_REQUIRE_CLOCK() flag is set, a clock should be set on the
  * element with gst_element_set_clock().
  *
  * Note that clock slection and distribution is normally handled by the
  * toplevel #GstPipeline so the clock functions are only to be used in very
  * specific situations.
  *
- * Last reviewed on 2009-05-29 (0.10.24)
+ * Last reviewed on 2012-03-28 (0.11.3)
  */
 
 #include "gst_private.h"

gst/gstevent.c

@@ -72,7 +72,7 @@
  *   </programlisting>
  * </example>
  *
- * Last reviewed on 2006-09-6 (0.10.10)
+ * Last reviewed on 2012-03-28 (0.11.3)
  */
 
 
@@ -452,10 +452,6 @@ gst_event_set_seqnum (GstEvent * event, guint32 seqnum)
   GST_EVENT_SEQNUM (event) = seqnum;
 }
 
-/* FIXME 0.11: It would be nice to have flush events
- * that don't reset the running time in the sinks
- */
-
 /**
  * gst_event_new_flush_start:
  *
@@ -540,7 +536,7 @@ gst_event_parse_flush_stop (GstEvent * event, gboolean * reset_time)
  *
  * Create a new EOS event. The eos event can only travel downstream
  * synchronized with the buffer flow. Elements that receive the EOS
- * event on a pad can return #GST_FLOW_UNEXPECTED as a #GstFlowReturn
+ * event on a pad can return #GST_FLOW_EOS as a #GstFlowReturn
  * when data after the EOS event arrives.
  *
  * The EOS event will travel down to the sink elements in the pipeline

gst/gstminiobject.c

@@ -111,9 +111,8 @@ gst_mini_object_copy (const GstMiniObject * mini_object)
  * @mini_object: the mini-object to check
  *
  * Checks if a mini-object is writable.  A mini-object is writable
- * if the reference count is one and the #GST_MINI_OBJECT_FLAG_READONLY
+ * if the reference count is one. Modification of a mini-object should
- * flag is not set.  Modification of a mini-object should only be
+ * only be done after verifying that it is writable.
- * done after verifying that it is writable.
  *
  * MT safe
  *

gst/gstpad.h

@@ -325,7 +325,7 @@ typedef GstFlowReturn		(*GstPadChainListFunction)	(GstPad *pad, GstObject *paren
  * #GST_QUERY_SEEKING.
  *
  * Any @offset larger or equal than the length will make the function return
- * #GST_FLOW_UNEXPECTED, which corresponds to EOS. In this case @buffer does not
+ * #GST_FLOW_EOS, which corresponds to EOS. In this case @buffer does not
  * contain a valid buffer.
  *
  * The buffer size of @buffer will only be smaller than @length when @offset is

libs/gst/base/gstbasesrc.h

@@ -149,7 +149,7 @@ struct _GstBaseSrc {
  *   When the subclass returns GST_FLOW_OK, it MUST return a buffer of the
  *   requested size unless fewer bytes are available because an EOS condition
  *   is near. No buffer should be returned when the return value is different
- *   from GST_FLOW_OK. A return value of GST_FLOW_UNEXPECTED signifies that the
+ *   from GST_FLOW_OK. A return value of GST_FLOW_EOS signifies that the
  *   end of stream is reached. The default implementation will call @alloc and
  *   then call @fill.
  * @alloc: Ask the subclass to allocate a buffer with for offset and size. The