gst/gstbuffer.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstbuffer.c: Buffer operations
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 #include "gst_private.h"
  24
  25 #include "gstatomic_impl.h"
  26 #include "gstdata_private.h"
  27 #include "gstbuffer.h"
  28 #include "gstmemchunk.h"
  29 #include "gstinfo.h"
  30
  31 GType _gst_buffer_type;
  32
  33 #ifndef GST_DISABLE_TRACE
  34 /* #define GST_WITH_ALLOC_TRACE  */
  35 #include "gsttrace.h"
  36
  37 static GstAllocTrace *_gst_buffer_trace;
  38 #endif
  39
  40 static GstMemChunk *chunk;
  41
  42 static GstBuffer *gst_buffer_alloc_chunk (void);
  43 static void gst_buffer_free_chunk (GstBuffer * buffer);
  44
  45 void
  46 _gst_buffer_initialize (void)
  47 {
  48   _gst_buffer_type = g_boxed_type_register_static ("GstBuffer",
  49       (GBoxedCopyFunc) gst_data_copy, (GBoxedFreeFunc) gst_data_unref);
  50
  51 #ifndef GST_DISABLE_TRACE
  52   _gst_buffer_trace = gst_alloc_trace_register (GST_BUFFER_TRACE_NAME);
  53 #endif
  54
  55   chunk = gst_mem_chunk_new ("GstBufferChunk", sizeof (GstBuffer),
  56       sizeof (GstBuffer) * 200, 0);
  57
  58   GST_CAT_LOG (GST_CAT_BUFFER, "Buffers are initialized now");
  59 }
  60
  61 GType
  62 gst_buffer_get_type (void)
  63 {
  64   return _gst_buffer_type;
  65 }
  66
  67 static void
  68 _gst_buffer_sub_free (GstBuffer * buffer)
  69 {
  70   gst_data_unref (GST_DATA (buffer->buffer_private));
  71
  72   GST_BUFFER_DATA (buffer) = NULL;
  73   GST_BUFFER_SIZE (buffer) = 0;
  74
  75   _GST_DATA_DISPOSE (GST_DATA (buffer));
  76
  77   gst_buffer_free_chunk (buffer);
  78 }
  79
  80 /**
  81  * gst_buffer_default_free:
  82  * @buffer: a #GstBuffer to free.
  83  *
  84  * Frees the memory associated with the buffer including the buffer data,
  85  * unless the GST_BUFFER_DONTFREE flags was set or the buffer data is NULL.
  86  */
  87 void
  88 gst_buffer_default_free (GstBuffer * buffer)
  89 {
  90   g_return_if_fail (buffer != NULL);
  91
  92   /* free our data */
  93   if (GST_BUFFER_FREE_DATA_FUNC (buffer)) {
  94     GST_BUFFER_FREE_DATA_FUNC (buffer) (buffer);
  95   } else if (!GST_BUFFER_FLAG_IS_SET (buffer, GST_BUFFER_DONTFREE)) {
  96     g_free (GST_BUFFER_DATA (buffer));
  97   }
  98
  99   /* set to safe values */
 100   GST_BUFFER_DATA (buffer) = NULL;
 101   GST_BUFFER_SIZE (buffer) = 0;
 102
 103   _GST_DATA_DISPOSE (GST_DATA (buffer));
 104
 105   gst_buffer_free_chunk (buffer);
 106 }
 107
 108 /**
 109  * gst_buffer_stamp:
 110  * @dest: buffer to stamp
 111  * @src: buffer to stamp from
 112  *
 113  * Copies additional information (timestamps and offsets) from one buffer to
 114  * the other.
 115  */
 116 void
 117 gst_buffer_stamp (GstBuffer * dest, const GstBuffer * src)
 118 {
 119   g_return_if_fail (dest != NULL);
 120   g_return_if_fail (src != NULL);
 121
 122   GST_BUFFER_TIMESTAMP (dest) = GST_BUFFER_TIMESTAMP (src);
 123   GST_BUFFER_DURATION (dest) = GST_BUFFER_DURATION (src);
 124   GST_BUFFER_OFFSET (dest) = GST_BUFFER_OFFSET (src);
 125   GST_BUFFER_OFFSET_END (dest) = GST_BUFFER_OFFSET_END (src);
 126 }
 127
 128 /**
 129  * gst_buffer_default_copy:
 130  * @buffer: a #GstBuffer to make a copy of.
 131  *
 132  * Make a full newly allocated copy of the given buffer, data and all.
 133  *
 134  * Returns: the new #GstBuffer.
 135  */
 136 GstBuffer *
 137 gst_buffer_default_copy (GstBuffer * buffer)
 138 {
 139   GstBuffer *copy;
 140
 141   g_return_val_if_fail (buffer != NULL, NULL);
 142
 143   /* create a fresh new buffer */
 144   copy = gst_buffer_alloc_chunk ();
 145
 146   _GST_DATA_INIT (GST_DATA (copy),
 147       _gst_buffer_type,
 148       0,
 149       (GstDataFreeFunction) gst_buffer_default_free,
 150       (GstDataCopyFunction) gst_buffer_default_copy);
 151
 152   /* we simply copy everything from our parent */
 153   GST_BUFFER_DATA (copy) = g_memdup (GST_BUFFER_DATA (buffer),
 154       GST_BUFFER_SIZE (buffer));
 155   GST_BUFFER_SIZE (copy) = GST_BUFFER_SIZE (buffer);
 156   GST_BUFFER_MAXSIZE (copy) = GST_BUFFER_SIZE (buffer);
 157
 158   gst_buffer_stamp (copy, buffer);
 159   GST_BUFFER_FREE_DATA_FUNC (copy) = NULL;
 160   GST_BUFFER_PRIVATE (copy) = NULL;
 161
 162   return copy;
 163 }
 164
 165 static GstBuffer *
 166 gst_buffer_alloc_chunk (void)
 167 {
 168   GstBuffer *newbuf;
 169
 170   newbuf = gst_mem_chunk_alloc (chunk);
 171 #ifndef GST_DISABLE_TRACE
 172   gst_alloc_trace_new (_gst_buffer_trace, newbuf);
 173 #endif
 174
 175   return newbuf;
 176 }
 177
 178 static void
 179 gst_buffer_free_chunk (GstBuffer * buffer)
 180 {
 181   gst_mem_chunk_free (chunk, GST_DATA (buffer));
 182 #ifndef GST_DISABLE_TRACE
 183   gst_alloc_trace_free (_gst_buffer_trace, buffer);
 184 #endif
 185 }
 186
 187 /**
 188  * gst_buffer_new:
 189  *
 190  * Creates a newly allocated buffer without any data.
 191  *
 192  * Returns: the new #GstBuffer.
 193  */
 194 GstBuffer *
 195 gst_buffer_new (void)
 196 {
 197   GstBuffer *newbuf;
 198
 199   newbuf = gst_buffer_alloc_chunk ();
 200
 201   GST_CAT_LOG (GST_CAT_BUFFER, "new %p", newbuf);
 202
 203   _GST_DATA_INIT (GST_DATA (newbuf),
 204       _gst_buffer_type,
 205       0,
 206       (GstDataFreeFunction) gst_buffer_default_free,
 207       (GstDataCopyFunction) gst_buffer_default_copy);
 208
 209   GST_BUFFER_DATA (newbuf) = NULL;
 210   GST_BUFFER_SIZE (newbuf) = 0;
 211   GST_BUFFER_MAXSIZE (newbuf) = GST_BUFFER_MAXSIZE_NONE;
 212   GST_BUFFER_TIMESTAMP (newbuf) = GST_CLOCK_TIME_NONE;
 213   GST_BUFFER_DURATION (newbuf) = GST_CLOCK_TIME_NONE;
 214   GST_BUFFER_OFFSET (newbuf) = GST_BUFFER_OFFSET_NONE;
 215   GST_BUFFER_OFFSET_END (newbuf) = GST_BUFFER_OFFSET_NONE;
 216   GST_BUFFER_FREE_DATA_FUNC (newbuf) = NULL;
 217   GST_BUFFER_PRIVATE (newbuf) = NULL;
 218
 219   return newbuf;
 220 }
 221
 222 /**
 223  * gst_buffer_new_and_alloc:
 224  * @size: the size of the new buffer's data.
 225  *
 226  * Creates a newly allocated buffer with data of the given size.
 227  *
 228  * Returns: the new #GstBuffer.
 229  */
 230 GstBuffer *
 231 gst_buffer_new_and_alloc (guint size)
 232 {
 233   GstBuffer *newbuf;
 234
 235   newbuf = gst_buffer_new ();
 236
 237   GST_BUFFER_DATA (newbuf) = g_malloc (size);
 238   GST_BUFFER_SIZE (newbuf) = size;
 239   GST_BUFFER_MAXSIZE (newbuf) = size;
 240
 241   return newbuf;
 242 }
 243
 244 /**
 245  * gst_buffer_create_sub:
 246  * @parent: a parent #GstBuffer to create a subbuffer from.
 247  * @offset: the offset into parent #GstBuffer.
 248  * @size: the size of the new #GstBuffer sub-buffer (with size > 0).
 249  *
 250  * Creates a sub-buffer from the parent at a given offset.
 251  * This sub-buffer uses the actual memory space of the parent buffer.
 252  * This function will copy the offset and timestamp field when the
 253  * offset is 0, else they are set to _NONE.
 254  * The duration field of the new buffer are set to GST_CLOCK_TIME_NONE.
 255  *
 256  * Returns: the new #GstBuffer, or NULL if there was an error.
 257  */
 258 GstBuffer *
 259 gst_buffer_create_sub (GstBuffer * parent, guint offset, guint size)
 260 {
 261   GstBuffer *buffer;
 262   gpointer buffer_data;
 263
 264   g_return_val_if_fail (parent != NULL, NULL);
 265   g_return_val_if_fail (GST_BUFFER_REFCOUNT_VALUE (parent) > 0, NULL);
 266   g_return_val_if_fail (size > 0, NULL);
 267   g_return_val_if_fail (parent->size >= offset + size, NULL);
 268
 269   /* remember the data for the new buffer */
 270   buffer_data = parent->data + offset;
 271   /* make sure we're child not child from a child buffer */
 272   while (GST_BUFFER_FLAG_IS_SET (parent, GST_BUFFER_SUBBUFFER)) {
 273     parent = GST_BUFFER (parent->buffer_private);
 274   }
 275   /* ref the real parent */
 276   gst_data_ref (GST_DATA (parent));
 277
 278   /* create the new buffer */
 279   buffer = gst_buffer_alloc_chunk ();
 280
 281   GST_CAT_LOG (GST_CAT_BUFFER, "new subbuffer %p (parent %p)", buffer, parent);
 282
 283   /* make sure nobody overwrites data in the new buffer
 284    * by setting the READONLY flag */
 285   _GST_DATA_INIT (GST_DATA (buffer),
 286       _gst_buffer_type,
 287       GST_DATA_FLAG_SHIFT (GST_BUFFER_SUBBUFFER) |
 288       GST_DATA_FLAG_SHIFT (GST_DATA_READONLY),
 289       (GstDataFreeFunction) _gst_buffer_sub_free,
 290       (GstDataCopyFunction) gst_buffer_default_copy);
 291
 292   /* set the right values in the child */
 293   GST_BUFFER_DATA (buffer) = buffer_data;
 294   GST_BUFFER_SIZE (buffer) = size;
 295   GST_BUFFER_MAXSIZE (buffer) = size;
 296   GST_BUFFER_FREE_DATA_FUNC (buffer) = NULL;
 297   GST_BUFFER_PRIVATE (buffer) = parent;
 298   /* we can copy the timestamp and offset if the new buffer starts at
 299    * offset 0 */
 300   if (offset == 0) {
 301     GST_BUFFER_TIMESTAMP (buffer) = GST_BUFFER_TIMESTAMP (parent);
 302     GST_BUFFER_OFFSET (buffer) = GST_BUFFER_OFFSET (parent);
 303   } else {
 304     GST_BUFFER_TIMESTAMP (buffer) = GST_CLOCK_TIME_NONE;
 305     GST_BUFFER_OFFSET (buffer) = GST_BUFFER_OFFSET_NONE;
 306   }
 307
 308   GST_BUFFER_DURATION (buffer) = GST_CLOCK_TIME_NONE;
 309   GST_BUFFER_OFFSET_END (buffer) = GST_BUFFER_OFFSET_NONE;
 310
 311   if (GST_BUFFER_FLAG_IS_SET (parent, GST_BUFFER_DONTKEEP)) {
 312     GST_BUFFER_FLAG_SET (buffer, GST_BUFFER_DONTKEEP);
 313   }
 314   if (GST_BUFFER_FLAG_IS_SET (parent, GST_BUFFER_READONLY)) {
 315     GST_BUFFER_FLAG_SET (buffer, GST_BUFFER_READONLY);
 316   }
 317
 318   return buffer;
 319 }
 320
 321
 322 /**
 323  * gst_buffer_merge:
 324  * @buf1: a first source #GstBuffer to merge.
 325  * @buf2: the second source #GstBuffer to merge.
 326  *
 327  * Create a new buffer that is the concatenation of the two source
 328  * buffers.  The original source buffers will not be modified or
 329  * unref'd.
 330  *
 331  * WARNING: Incorrect use of this function can lead to memory leaks.
 332  * It is recommended to use gst_buffer_join() instead of this function.
 333  *
 334  * If the buffers point to contiguous areas of memory, the buffer
 335  * is created without copying the data.
 336  *
 337  * Returns: the new #GstBuffer that's the concatenation of the source buffers.
 338  */
 339 GstBuffer *
 340 gst_buffer_merge (GstBuffer * buf1, GstBuffer * buf2)
 341 {
 342   GstBuffer *result;
 343
 344   /* we're just a specific case of the more general gst_buffer_span() */
 345   result = gst_buffer_span (buf1, 0, buf2, buf1->size + buf2->size);
 346
 347   return result;
 348 }
 349
 350 /**
 351  * gst_buffer_join:
 352  * @buf1: a first source #GstBuffer to merge.
 353  * @buf2: the second source #GstBuffer to merge.
 354  *
 355  * Create a new buffer that is the concatenation of the two source
 356  * buffers.  The original buffers are unreferenced.
 357  *
 358  * If the buffers point to contiguous areas of memory, the buffer
 359  * is created without copying the data.
 360  *
 361  * Returns: the new #GstBuffer that's the concatenation of the source buffers.
 362  */
 363 GstBuffer *
 364 gst_buffer_join (GstBuffer * buf1, GstBuffer * buf2)
 365 {
 366   GstBuffer *result;
 367
 368   /* we're just a specific case of the more general gst_buffer_span() */
 369   result = gst_buffer_span (buf1, 0, buf2, buf1->size + buf2->size);
 370
 371   gst_buffer_unref (buf1);
 372   gst_buffer_unref (buf2);
 373
 374   return result;
 375 }
 376
 377 /**
 378  * gst_buffer_is_span_fast:
 379  * @buf1: a first source #GstBuffer.
 380  * @buf2: the second source #GstBuffer.
 381  *
 382  * Determines whether a gst_buffer_span() can be done without copying
 383  * the contents, that is, whether the data areas are contiguous.
 384  *
 385  * Returns: TRUE if the buffers are contiguous,
 386  * FALSE if a copy would be required.
 387  */
 388 gboolean
 389 gst_buffer_is_span_fast (GstBuffer * buf1, GstBuffer * buf2)
 390 {
 391   g_return_val_if_fail (buf1 != NULL && buf2 != NULL, FALSE);
 392   g_return_val_if_fail (GST_BUFFER_REFCOUNT_VALUE (buf1) > 0, FALSE);
 393   g_return_val_if_fail (GST_BUFFER_REFCOUNT_VALUE (buf2) > 0, FALSE);
 394
 395   /* it's only fast if we have subbuffers of the same parent */
 396   return ((GST_BUFFER_FLAG_IS_SET (buf1, GST_BUFFER_SUBBUFFER)) &&
 397       (GST_BUFFER_FLAG_IS_SET (buf2, GST_BUFFER_SUBBUFFER)) &&
 398       (buf1->buffer_private == buf2->buffer_private) &&
 399       ((buf1->data + buf1->size) == buf2->data));
 400 }
 401
 402 /**
 403  * gst_buffer_span:
 404  * @buf1: a first source #GstBuffer to merge.
 405  * @offset: the offset in the first buffer from where the new
 406  * buffer should start.
 407  * @buf2: the second source #GstBuffer to merge.
 408  * @len: the total length of the new buffer.
 409  *
 410  * Creates a new buffer that consists of part of buf1 and buf2.
 411  * Logically, buf1 and buf2 are concatenated into a single larger
 412  * buffer, and a new buffer is created at the given offset inside
 413  * this space, with a given length.
 414  *
 415  * If the two source buffers are children of the same larger buffer,
 416  * and are contiguous, the new buffer will be a child of the shared
 417  * parent, and thus no copying is necessary. you can use
 418  * gst_buffer_is_span_fast() to determine if a memcpy will be needed.
 419  *
 420  * Returns: the new #GstBuffer that spans the two source buffers.
 421  */
 422 GstBuffer *
 423 gst_buffer_span (GstBuffer * buf1, guint32 offset, GstBuffer * buf2,
 424     guint32 len)
 425 {
 426   GstBuffer *newbuf;
 427
 428   g_return_val_if_fail (buf1 != NULL && buf2 != NULL, FALSE);
 429   g_return_val_if_fail (GST_BUFFER_REFCOUNT_VALUE (buf1) > 0, NULL);
 430   g_return_val_if_fail (GST_BUFFER_REFCOUNT_VALUE (buf2) > 0, NULL);
 431   g_return_val_if_fail (len > 0, NULL);
 432   g_return_val_if_fail (len <= buf1->size + buf2->size - offset, NULL);
 433
 434   /* if the two buffers have the same parent and are adjacent */
 435   if (gst_buffer_is_span_fast (buf1, buf2)) {
 436     GstBuffer *parent = GST_BUFFER (buf1->buffer_private);
 437
 438     /* we simply create a subbuffer of the common parent */
 439     newbuf = gst_buffer_create_sub (parent,
 440         buf1->data - parent->data + offset, len);
 441   } else {
 442     GST_CAT_DEBUG (GST_CAT_BUFFER,
 443         "slow path taken while spanning buffers %p and %p", buf1, buf2);
 444     /* otherwise we simply have to brute-force copy the buffers */
 445     newbuf = gst_buffer_new_and_alloc (len);
 446
 447     /* copy the first buffer's data across */
 448     memcpy (newbuf->data, buf1->data + offset, buf1->size - offset);
 449     /* copy the second buffer's data across */
 450     memcpy (newbuf->data + (buf1->size - offset), buf2->data,
 451         len - (buf1->size - offset));
 452     /* if the offset is 0, the new buffer has the same timestamp as buf1 */
 453     if (offset == 0) {
 454       GST_BUFFER_OFFSET (newbuf) = GST_BUFFER_OFFSET (buf1);
 455       GST_BUFFER_TIMESTAMP (newbuf) = GST_BUFFER_TIMESTAMP (buf1);
 456     }
 457   }
 458   /* if we completely merged the two buffers (appended), we can
 459    * calculate the duration too. Also make sure we's not messing with
 460    * invalid DURATIONS */
 461   if (offset == 0 && buf1->size + buf2->size == len) {
 462     if (GST_BUFFER_DURATION_IS_VALID (buf1) &&
 463         GST_BUFFER_DURATION_IS_VALID (buf2)) {
 464       /* add duration */
 465       GST_BUFFER_DURATION (newbuf) = GST_BUFFER_DURATION (buf1) +
 466           GST_BUFFER_DURATION (buf2);
 467     }
 468     if (GST_BUFFER_OFFSET_END_IS_VALID (buf2)) {
 469       /* add offset_end */
 470       GST_BUFFER_OFFSET_END (newbuf) = GST_BUFFER_OFFSET_END (buf2);
 471     }
 472   }
 473
 474   return newbuf;
 475 }