From 5af73b30eda046f9b0b3bcbd2b485297165cb918 Mon Sep 17 00:00:00 2001 From: Nirbheek Chauhan Date: Mon, 26 Oct 2015 18:07:11 +0530 Subject: [PATCH] buffer: flesh out docs for gst_buffer_make_writable() a little There is a similar explanation in gst_caps_make_writable, but the existing documentation can be misleading since it does not define what 'is already writable' means. Also note when this function is meant to be used. --- gst/gstbuffer.h | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h index 4343b6ad1a..59a1f3964b 100644 --- a/gst/gstbuffer.h +++ b/gst/gstbuffer.h @@ -462,9 +462,24 @@ gboolean gst_buffer_copy_into (GstBuffer *dest, GstBuffer *src * gst_buffer_make_writable: * @buf: (transfer full): a #GstBuffer * - * Makes a writable buffer from the given buffer. If the source buffer is - * already writable, this will simply return the same buffer. A copy will - * otherwise be made using gst_buffer_copy(). + * Returns a writable copy of @buf. If the source buffer is + * already writable, this will simply return the same buffer. + * + * Use this function to ensure that a buffer can be safely modified before + * making changes to it, including changing the metadata such as PTS/DTS. + * + * If the reference count of the source buffer @buf is exactly one, the caller + * is the sole owner and this function will return the buffer object unchanged. + * + * If there is more than one reference on the object, a copy will be made using + * gst_buffer_copy(). The passed-in @buf will be unreffed in that case, and the + * caller will now own a reference to the new returned buffer object. Note + * that this just copies the buffer structure itself, the underlying memory is + * not copied if it can be shared amongst multiple buffers. + * + * In short, this function unrefs the buf in the argument and refs the buffer + * that it returns. Don't access the argument after calling this function unless + * you have an additional reference to it. * * Returns: (transfer full): a writable buffer which may or may not be the * same as @buf