- Documentation updates, renamed some _ methods because gtkdoc didn't want to generate docs for them.

Original commit message from CVS:
- Documentation updates, renamed some _ methods because gtkdoc didn't
want to generate docs for them.
- Add some more events for future use.

gst/elements/gstfilesrc.c

@@ -340,7 +340,7 @@ gst_filesrc_free_parent_mmap (GstBuffer *buf)
 
   GST_BUFFER_DATA (buf) = NULL;
 
-  _gst_buffer_free (buf);
+  gst_buffer_default_free (buf);
 }
 
 static GstBuffer *

gst/gstbuffer.c

@@ -94,17 +94,15 @@ _gst_buffer_sub_free (GstBuffer *buffer)
 }
 
 /**
- * _gst_buffer_free:
+ * gst_buffer_default_free:
  * @buffer: a #GstBuffer to free
  *
  * Free the momory associated with the buffer including the buffer data,
  * unless the GST_BUFFER_DONTFREE flags was set or the buffer data is NULL.
  * This function is used by bufferpools.
- *
- * Returns: new #GstBuffer
  */
 void
-_gst_buffer_free (GstBuffer *buffer)
+gst_buffer_default_free (GstBuffer *buffer)
 {
   /* free our data */
   if (!GST_BUFFER_FLAG_IS_SET (buffer, GST_BUFFER_DONTFREE) && GST_BUFFER_DATA (buffer)) 
@@ -121,7 +119,7 @@ _gst_buffer_free (GstBuffer *buffer)
 }
 
 /**
- * _gst_buffer_copy:
+ * gst_buffer_default_copy:
  * @buffer: a #GstBuffer to make a copy of
  *
  * Make a full newly allocated copy of the given buffer, data and all.
@@ -130,7 +128,7 @@ _gst_buffer_free (GstBuffer *buffer)
  * Returns: new #GstBuffer
  */
 GstBuffer*
-_gst_buffer_copy (GstBuffer *buffer)
+gst_buffer_default_copy (GstBuffer *buffer)
 {
   GstBuffer *copy;
 
@@ -172,8 +170,8 @@ gst_buffer_new (void)
   _GST_DATA_INIT (GST_DATA (new), 
 		  _gst_buffer_type,
 		  0,
-		  (GstDataFreeFunction) _gst_buffer_free,
+		  (GstDataFreeFunction) gst_buffer_default_free,
-		  (GstDataCopyFunction) _gst_buffer_copy);
+		  (GstDataCopyFunction) gst_buffer_default_copy);
 
   GST_BUFFER_BUFFERPOOL (new) = NULL;
   GST_BUFFER_POOL_PRIVATE (new) = NULL;
@@ -183,6 +181,7 @@ gst_buffer_new (void)
 
 /**
  * gst_buffer_new_and_alloc:
+ * @size: the size of the buffer and the memory to allocate
  *
  * Creates a newly allocated buffer with data of the given size.
  *
@@ -278,7 +277,7 @@ gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size)
 		  GST_DATA_FLAG_SHIFT (GST_BUFFER_SUBBUFFER) |
 		  GST_DATA_FLAG_SHIFT (GST_DATA_READONLY),
 		  (GstDataFreeFunction) _gst_buffer_sub_free,
-		  (GstDataCopyFunction) _gst_buffer_copy);
+		  (GstDataCopyFunction) gst_buffer_default_copy);
 
   GST_BUFFER_OFFSET (buffer) = parent_offset + offset;
   GST_BUFFER_TIMESTAMP (buffer) = -1;
@@ -302,7 +301,7 @@ gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size)
  * buffers.  The original source buffers will not be modified or
  * unref'd.
  *
- * Internally is nothing more than a specialized gst_buffer_span,
+ * Internally is nothing more than a specialized gst_buffer_span(),
  * so the same optimizations can occur.
  *
  * Returns: a new #GstBuffer that's the concatenation of the source buffers
@@ -322,7 +321,7 @@ gst_buffer_merge (GstBuffer *buf1, GstBuffer *buf2)
  * @buf1: first source buffer
  * @buf2: second source buffer
  *
- * Determines whether a gst_buffer_span is free (as in free beer), 
+ * Determines whether a gst_buffer_span() is free (as in free beer), 
  * or requires a memcpy. 
  *
  * Returns: TRUE if the buffers are contiguous, FALSE if a copy would be required.
@@ -354,7 +353,8 @@ gst_buffer_is_span_fast (GstBuffer *buf1, GstBuffer *buf2)
  *
  * If the two source buffers are children of the same larger buffer,
  * and are contiguous, the new buffer will be a child of the shared
- * parent, and thus no copying is necessary.
+ * parent, and thus no copying is necessary. you can use 
+ * gst_buffer_is_span_fast() to determine if a memcpy will be needed.
  *
  * Returns: a new #GstBuffer that spans the two source buffers
  */
@@ -368,7 +368,7 @@ gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len)
   g_return_val_if_fail (len > 0, NULL);
 
   /* if the two buffers have the same parent and are adjacent */
-  if (gst_buffer_is_span_fast(buf1,buf2)) {
+  if (gst_buffer_is_span_fast (buf1, buf2)) {
     GstBuffer *parent = GST_BUFFER (buf1->pool_private);
     /* we simply create a subbuffer of the common parent */
     newbuf = gst_buffer_create_sub (parent, buf1->data - parent->data + offset, len);
@@ -386,6 +386,9 @@ gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len)
     /* copy the second buffer's data across */
     memcpy (newbuf->data + (buf1->size - offset), buf2->data, len - (buf1->size - offset));
   }
+  /* if the offset is 0, the new buffer has the same timestamp as buf1 */
+  if (offset == 0)
+    GST_BUFFER_TIMESTAMP (newbuf) = GST_BUFFER_TIMESTAMP (buf1);
 
   return newbuf;
 }
@@ -393,7 +396,8 @@ gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len)
 static void
 _gst_buffer_pool_free (GstBufferPool *pool)
 {
-  _gst_data_free (GST_DATA (pool));
+  _GST_DATA_DISPOSE (GST_DATA (pool));
+  g_free (pool);
   _gst_buffer_pool_live--;
 }
 
@@ -498,6 +502,15 @@ gst_buffer_pool_get_user_data (GstBufferPool *pool)
   return pool->user_data;
 }
 
+/**
+ * gst_buffer_pool_get_default:
+ * @size: The size of the buffers to allocate from this pool
+ * @numbuffers: The number of buffer to preallocate in the pool
+ *
+ * Create a pool with buffers of the given size.
+ * 
+ * Returns: A new bufferpool to create buffers of the given size.
+ */
 /* FIXME */
 GstBufferPool*	
 gst_buffer_pool_get_default (guint size, guint numbuffers)

gst/gstbuffer.h

@@ -110,11 +110,19 @@ struct _GstBufferPool {
 /*< private >*/
 void		_gst_buffer_initialize		(void);
 
-void		_gst_buffer_free 		(GstBuffer *buf);
+/* function used by subclasses and bufferpools */
-GstBuffer*	_gst_buffer_copy 		(GstBuffer *buf);
+void		gst_buffer_default_free 	(GstBuffer *buffer);
+GstBuffer*	gst_buffer_default_copy 	(GstBuffer *buffer);
 
 void		gst_buffer_print_stats		(void);
 
+/* allocation */
+GstBuffer*	gst_buffer_new	 		(void);
+GstBuffer*	gst_buffer_new_and_alloc	(guint size);
+
+/* creating a new buffer from a pool */
+GstBuffer*	gst_buffer_new_from_pool 	(GstBufferPool *pool, guint64 offset, guint size);
+
 /* refcounting */
 #define		gst_buffer_ref(buf)		GST_BUFFER (gst_data_ref (GST_DATA (buf)))
 #define		gst_buffer_ref_by_count(buf,c)	GST_BUFFER (gst_data_ref_by_count (GST_DATA (buf), c))
@@ -124,13 +132,6 @@ void		gst_buffer_print_stats		(void);
 #define		gst_buffer_copy_on_write(buffer) GST_BUFFER (gst_data_copy_on_write (GST_DATA (buffer)))
 #define		gst_buffer_free(buffer)		gst_data_free (GST_DATA (buffer))
 
-/* allocation */
-GstBuffer*	gst_buffer_new	 		(void);
-GstBuffer*	gst_buffer_new_and_alloc	(guint size);
-
-/* creating a new buffer from a pool */
-GstBuffer*	gst_buffer_new_from_pool 	(GstBufferPool *pool, guint64 offset, guint size);
-
 /* creating a subbuffer */
 GstBuffer*	gst_buffer_create_sub		(GstBuffer *parent, guint offset, guint size);
 
@@ -143,7 +144,7 @@ GstBuffer*	gst_buffer_span			(GstBuffer *buf1, guint32 offset, GstBuffer *buf2,
 /* creating a new buffer pools */
 GstBufferPool*	gst_buffer_pool_new			(GstDataFreeFunction free,
 							 GstDataCopyFunction copy,
-							 GstBufferPoolBufferNewFunction buffer_create,
+							 GstBufferPoolBufferNewFunction buffer_new,
                                                 	 GstBufferPoolBufferCopyFunction buffer_copy,
                                                 	 GstBufferPoolBufferFreeFunction buffer_free,
 							 gpointer user_data);
@@ -151,11 +152,9 @@ GstBufferPool*	gst_buffer_pool_new			(GstDataFreeFunction free,
 gboolean	gst_buffer_pool_is_active		(GstBufferPool *pool);
 void		gst_buffer_pool_set_active		(GstBufferPool *pool, gboolean active);
 
-GstBufferPool*	gst_buffer_pool_get_default		(guint size, guint numbuffers);
+#define		gst_buffer_pool_ref(pool)		GST_BUFFER_POOL (gst_data_ref (GST_DATA (pool)))
-
+#define		gst_buffer_pool_ref_by_count(pool,c)	GST_BUFFER_POOL (gst_data_ref_by_count (GST_DATA (pool), c))
-#define		gst_buffer_pool_ref(buf)		GST_BUFFER_POOL (gst_data_ref (GST_DATA (buf)))
+#define		gst_buffer_pool_unref(pool)		gst_data_unref (GST_DATA (pool))
-#define		gst_buffer_pool_ref_by_count(buf,c)	GST_BUFFER_POOL (gst_data_ref_by_count (GST_DATA (buf), c))
-#define		gst_buffer_pool_unref(buf)		gst_data_unref (GST_DATA (buf))
 
 /* bufferpool operations */
 #define		gst_buffer_pool_copy(pool)		GST_BUFFER_POOL (gst_data_copy (GST_DATA (pool)))
@@ -165,6 +164,8 @@ GstBufferPool*	gst_buffer_pool_get_default		(guint size, guint numbuffers);
 void 		gst_buffer_pool_set_user_data		(GstBufferPool *pool, gpointer user_data);
 gpointer	gst_buffer_pool_get_user_data		(GstBufferPool *pool);
 
+/* implement me */
+GstBufferPool*	gst_buffer_pool_get_default		(guint size, guint numbuffers);
 
 G_END_DECLS
 

gst/gstdata.c

@@ -28,24 +28,56 @@
 #include "gstdata_private.h"
 #include "gstlog.h"
 
+/**
+ * gst_data_init:
+ * @data: a #GstData to initialize
+ * @type: the type of this data
+ * @flags: flags for this data
+ * @free: a free function 
+ * @copy: a copy function 
+ *
+ * Initialize the given data structure with the given parameters. The free and copy 
+ * function will be called when this data is freed or copied respectively.
+ */
 void
-_gst_data_init (GstData *data, GType type, guint16 flags, GstDataFreeFunction free, GstDataCopyFunction copy)
+gst_data_init (GstData *data, GType type, guint16 flags, GstDataFreeFunction free, GstDataCopyFunction copy)
 {
   _GST_DATA_INIT (data, type, flags, free, copy);
 }
 
+/**
+ * gst_data_copy_into:
+ * @data: a #GstData to copy
+ * @target: the target #GstData to copy into
+ *
+ * Copy the GstData into the specified target GstData structure.
+ * Thos method is mainly used by subclasses when they want to copy
+ * the relevant GstData info.
+ */
 void
-_gst_data_free (GstData *data)
+gst_data_copy_into (const GstData *data, GstData *target)
+{
+}
+
+/**
+ * gst_data_dispose:
+ * @data: a #GstData to dispose
+ *
+ * Free all the resources allocated in the gst_data_init() function, 
+ * mainly used by subclass implementors.
+ */
+void
+gst_data_dispose (GstData *data)
 {
   _GST_DATA_DISPOSE (data);
-  g_free (data);
 }
 
 /**
  * gst_data_copy:
  * @data: a #GstData to copy
  *
- * Copies the given #GstData
+ * Copies the given #GstData. This function will call the custom subclass
+ * copy function or return NULL if no function was provided by the subclass.
  *
  * Returns: a copy of the data or NULL if the data cannot be copied.
  */
@@ -88,7 +120,8 @@ gst_data_copy_on_write (const GstData *data)
  * gst_data_free:
  * @data: a #GstData to free
  *
- * Frees the given #GstData 
+ * Frees the given #GstData. This function will call the custom free function
+ * provided by the subclass. 
  */
 void
 gst_data_free (GstData *data) 

gst/gstdata.h

@@ -75,15 +75,15 @@ struct _GstData {
  
   /* utility function pointers, can override default */
   GstDataFreeFunction 	 free;		/* free the data */
-  GstDataCopyFunction 	 copy;		/* free the data */
+  GstDataCopyFunction 	 copy;		/* copy the data */
 };
 
 /* function used by subclasses only */
-void			_gst_data_init			(GstData *data, GType type, guint16 flags,
+void			gst_data_init			(GstData *data, GType type, guint16 flags,
 							 GstDataFreeFunction free,
 							 GstDataCopyFunction copy);
-void			_gst_data_free			(GstData *data);
+void			gst_data_dispose		(GstData *data);
-GstData*		_gst_data_copy			(const GstData *data);
+void			gst_data_copy_into		(const GstData *data, GstData *target);
 
 /* basic operations on data */
 GstData*		gst_data_copy	 		(const GstData *data);

gst/gstevent.c

@@ -44,9 +44,9 @@ _gst_event_initialize (void)
 }
 
 /**
- * gst_buffer_print_stats:
+ * gst_event_print_stats:
  *
- * Logs statistics about live buffers (using g_log).
+ * Logs statistics about live events (using g_log).
  */
 void
 gst_event_print_stats (void)
@@ -232,4 +232,27 @@ gst_event_new_size (GstFormat format, gint64 value)
 }
 
 
+/**
+ * gst_event_new_segment_seek:
+ * @type: The type of the seek event
+ * @start: The start offset of the seek
+ * @stop: The stop offset of the seek
+ *
+ * Allocate a new segment seek event with the given parameters. 
+ *
+ * Returns: A new segment seek event.
+ */
+GstEvent*       
+gst_event_new_segment_seek (GstSeekType type, gint64 start, gint64 stop)
+{
+  GstEvent *event;
+
+  event = gst_event_new (GST_EVENT_SEEK_SEGMENT);
+
+  GST_EVENT_SEEK_TYPE (event) = type;
+  GST_EVENT_SEEK_OFFSET (event) = start;
+  GST_EVENT_SEEK_ENDOFFSET (event) = stop;
+
+  return event;
+}
 

gst/gstevent.h

@@ -40,8 +40,11 @@ typedef enum {
   GST_EVENT_NEW_MEDIA,
   GST_EVENT_QOS,
   GST_EVENT_SEEK,
-  GST_EVENT_FILLER,
+  GST_EVENT_SEEK_SEGMENT,
-  GST_EVENT_SIZE
+  GST_EVENT_SEGMENT_DONE,
+  GST_EVENT_SIZE,
+  GST_EVENT_RATE,
+  GST_EVENT_FILLER
 } GstEventType;
 
 extern GType _gst_event_type;
@@ -69,7 +72,8 @@ typedef enum {
 
   GST_SEEK_FLAG_FLUSH		= (1 << (GST_SEEK_FLAGS_SHIFT + 0)),
   GST_SEEK_FLAG_ACCURATE	= (1 << (GST_SEEK_FLAGS_SHIFT + 1)),
-  GST_SEEK_FLAG_KEY_UNIT	= (1 << (GST_SEEK_FLAGS_SHIFT + 2))
+  GST_SEEK_FLAG_KEY_UNIT	= (1 << (GST_SEEK_FLAGS_SHIFT + 2)),
+  GST_SEEK_FLAG_SEGMENT_LOOP	= (1 << (GST_SEEK_FLAGS_SHIFT + 3))
 } GstSeekType;
 
 typedef enum {
@@ -88,6 +92,7 @@ typedef struct
 #define GST_EVENT_SEEK_METHOD(event)		(GST_EVENT_SEEK_TYPE(event) & GST_SEEK_METHOD_MASK)
 #define GST_EVENT_SEEK_FLAGS(event)		(GST_EVENT_SEEK_TYPE(event) & GST_SEEK_FLAGS_MASK)
 #define GST_EVENT_SEEK_OFFSET(event)		(GST_EVENT(event)->event_data.seek.offset)
+#define GST_EVENT_SEEK_ENDOFFSET(event)		(GST_EVENT(event)->event_data.seek.endoffset)
 #define GST_EVENT_SEEK_ACCURACY(event)		(GST_EVENT(event)->event_data.seek.accuracy)
 
 #define GST_EVENT_DISCONT_NEW_MEDIA(event)	(GST_EVENT(event)->event_data.discont.new_media)
@@ -97,6 +102,8 @@ typedef struct
 #define GST_EVENT_SIZE_FORMAT(event)		(GST_EVENT(event)->event_data.size.format)
 #define GST_EVENT_SIZE_VALUE(event)		(GST_EVENT(event)->event_data.size.value)
 
+#define GST_EVENT_RATE_VALUE(event)		(GST_EVENT(event)->event_data.rate.value)
+
 struct _GstEvent {
   GstData data;
 
@@ -108,6 +115,7 @@ struct _GstEvent {
     struct {
       GstSeekType 	type;
       gint64      	offset;
+      gint64      	endoffset;
       GstSeekAccuracy 	accuracy;
     } seek;
     struct {
@@ -119,6 +127,9 @@ struct _GstEvent {
       GstFormat 	format;
       gint64      	value;
     } size;
+    struct {
+      gdouble      	value;
+    } rate;
   } event_data;
 };
 
@@ -137,6 +148,7 @@ GstEvent*	gst_event_new	        	(GstEventType type);
 
 /* seek event */
 GstEvent*	gst_event_new_seek		(GstSeekType type, gint64 offset);
+GstEvent*	gst_event_new_segment_seek	(GstSeekType type, gint64 start, gint64 stop);
 
 /* size events */
 GstEvent*	gst_event_new_size		(GstFormat format, gint64 value);

plugins/elements/gstfilesrc.c

@@ -340,7 +340,7 @@ gst_filesrc_free_parent_mmap (GstBuffer *buf)
 
   GST_BUFFER_DATA (buf) = NULL;
 
-  _gst_buffer_free (buf);
+  gst_buffer_default_free (buf);
 }
 
 static GstBuffer *