Port gtk-doc comments to their equivalent markdown syntax

[platform/upstream/gstreamer.git] / gst / gstbufferlist.c

diff --git a/gst/gstbufferlist.c b/gst/gstbufferlist.c
index 5319f70..ec92645 100644 (file)
--- a/gst/gstbufferlist.c
+++ b/gst/gstbufferlist.c
@@ -23,6 +23,7 @@
 
 /**
  * SECTION:gstbufferlist
+ * @title: GstBufferList
  * @short_description: Lists of buffers for data-passing
  * @see_also: #GstPad, #GstMiniObject
  *
@@ -274,7 +275,7 @@ gst_buffer_list_foreach (GstBufferList * list, GstBufferListFunc func,
  *
  * Returns: (transfer none) (nullable): the buffer at @idx in @group
  *     or %NULL when there is no buffer. The buffer remains valid as
- *     long as @list is valid.
+ *     long as @list is valid and buffer is not removed from the list.
  */
 GstBuffer *
 gst_buffer_list_get (GstBufferList * list, guint idx)
@@ -310,6 +311,7 @@ gst_buffer_list_insert (GstBufferList * list, gint idx, GstBuffer * buffer)
 
   g_return_if_fail (GST_IS_BUFFER_LIST (list));
   g_return_if_fail (buffer != NULL);
+  g_return_if_fail (gst_buffer_list_is_writable (list));
 
   if (idx == -1 && list->n_buffers < list->n_allocated) {
     list->buffers[list->n_buffers++] = buffer;
@@ -359,6 +361,46 @@ gst_buffer_list_remove (GstBufferList * list, guint idx, guint length)
   g_return_if_fail (GST_IS_BUFFER_LIST (list));
   g_return_if_fail (idx < list->n_buffers);
   g_return_if_fail (idx + length <= list->n_buffers);
+  g_return_if_fail (gst_buffer_list_is_writable (list));
 
   gst_buffer_list_remove_range_internal (list, idx, length, TRUE);
 }
+
+/**
+ * gst_buffer_list_copy_deep:
+ * @list: a #GstBufferList
+ *
+ * Create a copy of the given buffer list. This will make a newly allocated
+ * copy of the buffer that the source buffer list contains.
+ *
+ * Returns: (transfer full): a new copy of @list.
+ *
+ * Since: 1.6
+ */
+GstBufferList *
+gst_buffer_list_copy_deep (const GstBufferList * list)
+{
+  guint i, len;
+  GstBufferList *result = NULL;
+
+  g_return_val_if_fail (GST_IS_BUFFER_LIST (list), NULL);
+
+  result = gst_buffer_list_new ();
+
+  len = list->n_buffers;
+  for (i = 0; i < len; i++) {
+    GstBuffer *old = list->buffers[i];
+    GstBuffer *new = gst_buffer_copy_deep (old);
+
+    if (G_LIKELY (new)) {
+      gst_buffer_list_insert (result, i, new);
+    } else {
+      g_warning
+          ("Failed to deep copy buffer %p while deep "
+          "copying buffer list %p. Buffer list copy "
+          "will be incomplete", old, list);
+    }
+  }
+
+  return result;
+}