bufferpool: add reset_buffer vmethod

Add a vmethod to reset a buffer to its original state. Add a default
implementation that resets the flags, timestamps and offsets.
Add some more docs.

gst/gstbufferpool.c

@@ -76,6 +76,8 @@ static GstFlowReturn default_alloc_buffer (GstBufferPool * pool,
     GstBuffer ** buffer, GstBufferPoolParams * params);
 static GstFlowReturn default_acquire_buffer (GstBufferPool * pool,
     GstBuffer ** buffer, GstBufferPoolParams * params);
+static void default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer,
+    GstBufferPoolParams * params);
 static void default_free_buffer (GstBufferPool * pool, GstBuffer * buffer);
 static void default_release_buffer (GstBufferPool * pool, GstBuffer * buffer);
 
@@ -92,6 +94,7 @@ gst_buffer_pool_class_init (GstBufferPoolClass * klass)
   klass->stop = default_stop;
   klass->set_config = default_set_config;
   klass->acquire_buffer = default_acquire_buffer;
+  klass->reset_buffer = default_reset_buffer;
   klass->alloc_buffer = default_alloc_buffer;
   klass->release_buffer = default_release_buffer;
   klass->free_buffer = default_free_buffer;
@@ -775,6 +778,18 @@ dec_outstanding (GstBufferPool * pool)
   }
 }
 
+static void
+default_reset_buffer (GstBufferPool * pool, GstBuffer * buffer,
+    GstBufferPoolParams * params)
+{
+  GST_BUFFER_FLAGS (buffer) = 0;
+
+  GST_BUFFER_TIMESTAMP (buffer) = GST_CLOCK_TIME_NONE;
+  GST_BUFFER_DURATION (buffer) = GST_CLOCK_TIME_NONE;
+  GST_BUFFER_OFFSET (buffer) = GST_BUFFER_OFFSET_NONE;
+  GST_BUFFER_OFFSET_END (buffer) = GST_BUFFER_OFFSET_NONE;
+}
+
 /**
  * gst_buffer_pool_acquire_buffer:
  * @pool: a #GstBufferPool
@@ -814,6 +829,9 @@ gst_buffer_pool_acquire_buffer (GstBufferPool * pool, GstBuffer ** buffer,
     /* all buffers from the pool point to the pool and have the refcount of the
      * pool incremented */
     (*buffer)->pool = gst_object_ref (pool);
+    /* now reset the buffer when needed */
+    if (G_LIKELY (pclass->reset_buffer))
+      pclass->reset_buffer (pool, *buffer, params);
   } else {
     dec_outstanding (pool);
   }

gst/gstbufferpool.h

@@ -54,7 +54,8 @@ typedef struct _GstBufferPoolClass GstBufferPoolClass;
  * GstBufferPoolFlags:
  * @GST_BUFFER_POOL_FLAG_NONE: no flags
  * @GST_BUFFER_POOL_FLAG_KEY_UNIT: buffer is keyframe
- * @GST_BUFFER_POOL_FLAG_DONTWAIT: don't wait for buffer
+ * @GST_BUFFER_POOL_FLAG_DONTWAIT: don't wait for buffer. This makes the
+ * acquire_buffer method return GST_FLOW_UNEXPECTED.
  * @GST_BUFFER_POOL_FLAG_DISCONT: buffer is discont
  *
  * Additional flags to control the allocation of a buffer
@@ -76,6 +77,10 @@ typedef enum {
  *
  * Parameters passed to the gst_buffer_pool_acquire_buffer() function to control the
  * allocation of the buffer.
+ *
+ * The default implementation ignores the @start and @stop members but other
+ * implementations can use this extra information to decide what buffer to
+ * return.
  */
 typedef struct _GstBufferPoolParams {
   GstFormat          format;
@@ -119,6 +124,32 @@ struct _GstBufferPool {
   gpointer _gst_reserved[GST_PADDING];
 };
 
+/**
+ * GstBufferPoolClass:
+ * @object_class:  Object parent class
+ * @get_metas: get a list of metadata supported by this pool
+ * @set_config: apply the bufferpool configuration. The default configuration
+ *              will parse the default config parameters
+ * @start: start the bufferpool. The default implementation will preallocate
+ *         min-buffers buffers and put them in the queue
+ * @stop: stop the bufferpool. the default implementation will free the
+ *        preallocated buffers. This function is called when all the buffers are
+ *        returned to the pool.
+ * @acquire_buffer: get a new buffer from the pool. The default implementation
+ *        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
+ *        size, prefix and alignment.
+ * @reset_buffer: reset the buffer to its state when it was freshly allocated.
+ *        The default implementation will clear the flags and timestamps.
+ * @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.
+ * @free_buffer: free a buffer. The default implementation unrefs the buffer.
+ *
+ * The GstBufferPool class.
+ */
 struct _GstBufferPoolClass {
   GstObjectClass    object_class;
 
@@ -133,6 +164,8 @@ struct _GstBufferPoolClass {
                                     GstBufferPoolParams *params);
   GstFlowReturn  (*alloc_buffer)   (GstBufferPool *pool, GstBuffer **buffer,
                                     GstBufferPoolParams *params);
+  void           (*reset_buffer)   (GstBufferPool *pool, GstBuffer *buffer,
+                                    GstBufferPoolParams *params);
   void           (*release_buffer) (GstBufferPool *pool, GstBuffer *buffer);
   void           (*free_buffer)    (GstBufferPool *pool, GstBuffer *buffer);