subprojects/gstreamer/gst/gstbuffer.h

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstbuffer.h: Header for GstBuffer object
   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., 51 Franklin St, Fifth Floor,
  20  * Boston, MA 02110-1301, USA.
  21  */
  22
  23
  24 #ifndef __GST_BUFFER_H__
  25 #define __GST_BUFFER_H__
  26
  27 #include <gst/gstminiobject.h>
  28 #include <gst/gstclock.h>
  29 #include <gst/gstallocator.h>
  30 #include <gst/gstcaps.h>
  31
  32 G_BEGIN_DECLS
  33
  34 GST_API GType _gst_buffer_type;
  35
  36 typedef struct _GstBuffer GstBuffer;
  37 typedef struct _GstBufferPool GstBufferPool;
  38
  39 #include <gst/gstmeta.h>
  40
  41 #define GST_TYPE_BUFFER                         (_gst_buffer_type)
  42 #define GST_IS_BUFFER(obj)                      (GST_IS_MINI_OBJECT_TYPE(obj, GST_TYPE_BUFFER))
  43 #define GST_BUFFER_CAST(obj)                    ((GstBuffer *)(obj))
  44 #define GST_BUFFER(obj)                         (GST_BUFFER_CAST(obj))
  45
  46 /**
  47  * GST_BUFFER_FLAGS:
  48  * @buf: a #GstBuffer.
  49  *
  50  * Returns a flags word containing #GstBufferFlags flags set on this buffer.
  51  */
  52 #define GST_BUFFER_FLAGS(buf)                   GST_MINI_OBJECT_FLAGS(buf)
  53 /**
  54  * GST_BUFFER_FLAG_IS_SET:
  55  * @buf: a #GstBuffer.
  56  * @flag: the #GstBufferFlags flag to check.
  57  *
  58  * Gives the status of a specific flag on a buffer.
  59  */
  60 #define GST_BUFFER_FLAG_IS_SET(buf,flag)        GST_MINI_OBJECT_FLAG_IS_SET (buf, flag)
  61 /**
  62  * GST_BUFFER_FLAG_SET:
  63  * @buf: a #GstBuffer.
  64  * @flag: the #GstBufferFlags flag to set.
  65  *
  66  * Sets a buffer flag on a buffer.
  67  */
  68 #define GST_BUFFER_FLAG_SET(buf,flag)           GST_MINI_OBJECT_FLAG_SET (buf, flag)
  69 /**
  70  * GST_BUFFER_FLAG_UNSET:
  71  * @buf: a #GstBuffer.
  72  * @flag: the #GstBufferFlags flag to clear.
  73  *
  74  * Clears a buffer flag.
  75  */
  76 #define GST_BUFFER_FLAG_UNSET(buf,flag)         GST_MINI_OBJECT_FLAG_UNSET (buf, flag)
  77
  78
  79 /**
  80  * GST_BUFFER_PTS:
  81  * @buf: a #GstBuffer.:
  82  *
  83  * Gets the presentation timestamp (pts) in nanoseconds (as a #GstClockTime)
  84  * of the data in the buffer. This is the timestamp when the media should be
  85  * presented to the user.
  86  *
  87  * Value will be %GST_CLOCK_TIME_NONE if the pts is unknown.
  88  */
  89 #define GST_BUFFER_PTS(buf)                     (GST_BUFFER_CAST(buf)->pts)
  90 /**
  91  * GST_BUFFER_DTS:
  92  * @buf: a #GstBuffer.
  93  *
  94  * Gets the decoding timestamp (dts) in nanoseconds (as a #GstClockTime)
  95  * of the data in the buffer. This is the timestamp when the media should be
  96  * decoded or processed otherwise.
  97  *
  98  * Value will be %GST_CLOCK_TIME_NONE if the dts is unknown.
  99  */
 100 #define GST_BUFFER_DTS(buf)                     (GST_BUFFER_CAST(buf)->dts)
 101 /**
 102  * GST_BUFFER_DTS_OR_PTS:
 103  * @buf: a #GstBuffer.
 104  *
 105  * Returns the buffer decoding timestamp (dts) if valid, else the buffer
 106  * presentation time (pts)
 107  *
 108  * Since: 1.8
 109  */
 110 #define GST_BUFFER_DTS_OR_PTS(buf)              (GST_BUFFER_DTS_IS_VALID(buf) ? GST_BUFFER_DTS(buf) : GST_BUFFER_PTS (buf))
 111 /**
 112  * GST_BUFFER_DURATION:
 113  * @buf: a #GstBuffer.
 114  *
 115  * Gets the duration in nanoseconds (as a #GstClockTime) of the data in the buffer.
 116  *
 117  * Value will be %GST_CLOCK_TIME_NONE if the duration is unknown.
 118  */
 119 #define GST_BUFFER_DURATION(buf)                (GST_BUFFER_CAST(buf)->duration)
 120 /**
 121  * GST_BUFFER_OFFSET:
 122  * @buf: a #GstBuffer.
 123  *
 124  * Gets the offset in the source file of the beginning of this buffer.
 125  */
 126 #define GST_BUFFER_OFFSET(buf)                  (GST_BUFFER_CAST(buf)->offset)
 127 /**
 128  * GST_BUFFER_OFFSET_END:
 129  * @buf: a #GstBuffer.
 130  *
 131  * Gets the offset in the source file of the end of this buffer.
 132  */
 133 #define GST_BUFFER_OFFSET_END(buf)              (GST_BUFFER_CAST(buf)->offset_end)
 134
 135 /**
 136  * GST_BUFFER_OFFSET_NONE:
 137  *
 138  * Constant for no-offset return results.
 139  */
 140 #define GST_BUFFER_OFFSET_NONE  ((guint64)-1)
 141
 142 /**
 143  * GST_BUFFER_DURATION_IS_VALID:
 144  * @buffer: a #GstBuffer
 145  *
 146  * Tests if the duration is known.
 147  */
 148 #define GST_BUFFER_DURATION_IS_VALID(buffer)    (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))
 149 /**
 150  * GST_BUFFER_PTS_IS_VALID:
 151  * @buffer: a #GstBuffer
 152  *
 153  * Tests if the pts is known.
 154  */
 155 #define GST_BUFFER_PTS_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_PTS (buffer)))
 156 /**
 157  * GST_BUFFER_DTS_IS_VALID:
 158  * @buffer: a #GstBuffer
 159  *
 160  * Tests if the dts is known.
 161  */
 162 #define GST_BUFFER_DTS_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DTS (buffer)))
 163 /**
 164  * GST_BUFFER_OFFSET_IS_VALID:
 165  * @buffer: a #GstBuffer
 166  *
 167  * Tests if the start offset is known.
 168  */
 169 #define GST_BUFFER_OFFSET_IS_VALID(buffer)      (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)
 170 /**
 171  * GST_BUFFER_OFFSET_END_IS_VALID:
 172  * @buffer: a #GstBuffer
 173  *
 174  * Tests if the end offset is known.
 175  */
 176 #define GST_BUFFER_OFFSET_END_IS_VALID(buffer)  (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)
 177 /**
 178  * GST_BUFFER_IS_DISCONT:
 179  * @buffer: a #GstBuffer
 180  *
 181  * Tests if the buffer marks a discontinuity in the stream.
 182  */
 183 #define GST_BUFFER_IS_DISCONT(buffer)   (GST_BUFFER_FLAG_IS_SET (buffer, GST_BUFFER_FLAG_DISCONT))
 184
 185 /**
 186  * GstBufferFlags:
 187  * @GST_BUFFER_FLAG_LIVE:          the buffer is live data and should be discarded in
 188  *                                 the PAUSED state.
 189  * @GST_BUFFER_FLAG_DECODE_ONLY:   the buffer contains data that should be dropped
 190  *                                 because it will be clipped against the segment
 191  *                                 boundaries or because it does not contain data
 192  *                                 that should be shown to the user.
 193  * @GST_BUFFER_FLAG_DISCONT:       the buffer marks a data discontinuity in the stream.
 194  *                                 This typically occurs after a seek or a dropped buffer
 195  *                                 from a live or network source.
 196  * @GST_BUFFER_FLAG_RESYNC:        the buffer timestamps might have a discontinuity
 197  *                                 and this buffer is a good point to resynchronize.
 198  * @GST_BUFFER_FLAG_CORRUPTED:     the buffer data is corrupted.
 199  * @GST_BUFFER_FLAG_MARKER:        the buffer contains a media specific marker. for
 200  *                                 video this is the end of a frame boundary, for audio
 201  *                                 this is the start of a talkspurt.
 202  * @GST_BUFFER_FLAG_HEADER:        the buffer contains header information that is
 203  *                                 needed to decode the following data.
 204  * @GST_BUFFER_FLAG_GAP:           the buffer has been created to fill a gap in the
 205  *                                 stream and contains media neutral data (elements can
 206  *                                 switch to optimized code path that ignores the buffer
 207  *                                 content).
 208  * @GST_BUFFER_FLAG_DROPPABLE:     the buffer can be dropped without breaking the
 209  *                                 stream, for example to reduce bandwidth.
 210  * @GST_BUFFER_FLAG_DELTA_UNIT:    this unit cannot be decoded independently.
 211  * @GST_BUFFER_FLAG_TAG_MEMORY:    this flag is set when memory of the buffer
 212  *                                 is added/removed
 213  * @GST_BUFFER_FLAG_LAST:          additional media specific flags can be added starting from
 214  *                                 this flag.
 215  *
 216  * A set of buffer flags used to describe properties of a #GstBuffer.
 217  */
 218 typedef enum {
 219   GST_BUFFER_FLAG_LIVE          = (GST_MINI_OBJECT_FLAG_LAST << 0),
 220   GST_BUFFER_FLAG_DECODE_ONLY   = (GST_MINI_OBJECT_FLAG_LAST << 1),
 221   GST_BUFFER_FLAG_DISCONT       = (GST_MINI_OBJECT_FLAG_LAST << 2),
 222   GST_BUFFER_FLAG_RESYNC        = (GST_MINI_OBJECT_FLAG_LAST << 3),
 223   GST_BUFFER_FLAG_CORRUPTED     = (GST_MINI_OBJECT_FLAG_LAST << 4),
 224   GST_BUFFER_FLAG_MARKER        = (GST_MINI_OBJECT_FLAG_LAST << 5),
 225   GST_BUFFER_FLAG_HEADER        = (GST_MINI_OBJECT_FLAG_LAST << 6),
 226   GST_BUFFER_FLAG_GAP           = (GST_MINI_OBJECT_FLAG_LAST << 7),
 227   GST_BUFFER_FLAG_DROPPABLE     = (GST_MINI_OBJECT_FLAG_LAST << 8),
 228   GST_BUFFER_FLAG_DELTA_UNIT    = (GST_MINI_OBJECT_FLAG_LAST << 9),
 229   GST_BUFFER_FLAG_TAG_MEMORY    = (GST_MINI_OBJECT_FLAG_LAST << 10),
 230
 231   /**
 232    * GST_BUFFER_FLAG_SYNC_AFTER:
 233    *
 234    * Elements which write to disk or permanent storage should ensure the data
 235    * is synced after writing the contents of this buffer.
 236    *
 237    * Since: 1.6
 238    */
 239   GST_BUFFER_FLAG_SYNC_AFTER    = (GST_MINI_OBJECT_FLAG_LAST << 11),
 240
 241   /**
 242    * GST_BUFFER_FLAG_NON_DROPPABLE:
 243    *
 244    * This buffer is important and should not be dropped.
 245    *
 246    * This can be used to mark important buffers, e.g. to flag RTP packets
 247    * carrying keyframes or codec setup data for RTP Forward Error Correction
 248    * purposes, or to prevent still video frames from being dropped by elements
 249    * due to QoS.
 250    *
 251    * Since: 1.14
 252    */
 253   GST_BUFFER_FLAG_NON_DROPPABLE = (GST_MINI_OBJECT_FLAG_LAST << 12),
 254
 255   GST_BUFFER_FLAG_LAST          = (GST_MINI_OBJECT_FLAG_LAST << 16)
 256 } GstBufferFlags;
 257
 258 /**
 259  * GstBuffer:
 260  * @mini_object: the parent structure
 261  * @pool: pointer to the pool owner of the buffer
 262  * @pts: presentation timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the
 263  *     pts is not known or relevant. The pts contains the timestamp when the
 264  *     media should be presented to the user.
 265  * @dts: decoding timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the
 266  *     dts is not known or relevant. The dts contains the timestamp when the
 267  *     media should be processed.
 268  * @duration: duration in time of the buffer data, can be #GST_CLOCK_TIME_NONE
 269  *     when the duration is not known or relevant.
 270  * @offset: a media specific offset for the buffer data.
 271  *     For video frames, this is the frame number of this buffer.
 272  *     For audio samples, this is the offset of the first sample in this buffer.
 273  *     For file data or compressed data this is the byte offset of the first
 274  *       byte in this buffer.
 275  * @offset_end: the last offset contained in this buffer. It has the same
 276  *     format as @offset.
 277  *
 278  * The structure of a #GstBuffer. Use the associated macros to access the public
 279  * variables.
 280  */
 281 struct _GstBuffer {
 282   GstMiniObject          mini_object;
 283
 284   /*< public >*/ /* with COW */
 285   GstBufferPool         *pool;
 286
 287   /* timestamp */
 288   GstClockTime           pts;
 289   GstClockTime           dts;
 290   GstClockTime           duration;
 291
 292   /* media specific offset */
 293   guint64                offset;
 294   guint64                offset_end;
 295 };
 296
 297 GST_API
 298 GType       gst_buffer_get_type            (void);
 299
 300 GST_API
 301 guint       gst_buffer_get_max_memory      (void);
 302
 303 /* allocation */
 304
 305 GST_API
 306 GstBuffer * gst_buffer_new                 (void);
 307
 308 GST_API
 309 GstBuffer * gst_buffer_new_allocate        (GstAllocator * allocator, gsize size,
 310                                             GstAllocationParams * params);
 311 GST_API
 312 GstBuffer * gst_buffer_new_wrapped_full    (GstMemoryFlags flags, gpointer data, gsize maxsize,
 313                                             gsize offset, gsize size, gpointer user_data,
 314                                             GDestroyNotify notify);
 315 GST_API
 316 GstBuffer * gst_buffer_new_wrapped         (gpointer data, gsize size);
 317
 318 GST_API
 319 GstBuffer * gst_buffer_new_wrapped_bytes   (GBytes * bytes);
 320
 321 GST_API
 322 GstBuffer * gst_buffer_new_memdup           (gconstpointer data, gsize size);
 323
 324 /* memory blocks */
 325
 326 GST_API
 327 guint       gst_buffer_n_memory             (GstBuffer *buffer);
 328
 329 GST_API
 330 void        gst_buffer_insert_memory        (GstBuffer *buffer, gint idx, GstMemory *mem);
 331
 332 GST_API
 333 void        gst_buffer_replace_memory_range (GstBuffer *buffer, guint idx, gint length, GstMemory *mem);
 334
 335 GST_API
 336 GstMemory * gst_buffer_peek_memory          (GstBuffer *buffer, guint idx);
 337
 338 GST_API
 339 GstMemory * gst_buffer_get_memory_range     (GstBuffer *buffer, guint idx, gint length);
 340
 341 GST_API
 342 void        gst_buffer_remove_memory_range  (GstBuffer *buffer, guint idx, gint length);
 343
 344 GST_API
 345 void        gst_buffer_prepend_memory       (GstBuffer *buffer, GstMemory *mem);
 346
 347 GST_API
 348 void        gst_buffer_append_memory        (GstBuffer *buffer, GstMemory *mem);
 349
 350 GST_API
 351 void        gst_buffer_replace_memory       (GstBuffer *buffer, guint idx, GstMemory *mem);
 352
 353 GST_API
 354 void        gst_buffer_replace_all_memory   (GstBuffer *buffer, GstMemory *mem);
 355
 356 GST_API
 357 GstMemory * gst_buffer_get_memory           (GstBuffer *buffer, guint idx);
 358
 359 GST_API
 360 GstMemory * gst_buffer_get_all_memory       (GstBuffer *buffer);
 361
 362 GST_API
 363 void        gst_buffer_remove_memory        (GstBuffer *buffer, guint idx);
 364
 365 GST_API
 366 void        gst_buffer_remove_all_memory    (GstBuffer *buffer);
 367
 368 GST_API
 369 gboolean    gst_buffer_find_memory         (GstBuffer *buffer, gsize offset, gsize size,
 370                                             guint *idx, guint *length, gsize *skip);
 371 GST_API
 372 gboolean    gst_buffer_is_memory_range_writable  (GstBuffer *buffer, guint idx, gint length);
 373
 374 GST_API
 375 gboolean    gst_buffer_is_all_memory_writable    (GstBuffer *buffer);
 376
 377 GST_API
 378 gsize       gst_buffer_fill                (GstBuffer *buffer, gsize offset,
 379                                             gconstpointer src, gsize size);
 380 GST_API
 381 gsize       gst_buffer_extract             (GstBuffer *buffer, gsize offset,
 382                                             gpointer dest, gsize size);
 383 GST_API
 384 gint        gst_buffer_memcmp              (GstBuffer *buffer, gsize offset,
 385                                             gconstpointer mem, gsize size);
 386 GST_API
 387 gsize       gst_buffer_memset              (GstBuffer *buffer, gsize offset,
 388                                             guint8 val, gsize size);
 389 GST_API
 390 gsize       gst_buffer_get_sizes_range     (GstBuffer *buffer, guint idx, gint length,
 391                                             gsize *offset, gsize *maxsize);
 392 GST_API
 393 gboolean    gst_buffer_resize_range        (GstBuffer *buffer, guint idx, gint length,
 394                                             gssize offset, gssize size);
 395 GST_API
 396 gsize       gst_buffer_get_sizes           (GstBuffer *buffer, gsize *offset, gsize *maxsize);
 397
 398 GST_API
 399 gsize       gst_buffer_get_size            (GstBuffer *buffer);
 400
 401 GST_API
 402 void        gst_buffer_resize              (GstBuffer *buffer, gssize offset, gssize size);
 403
 404 GST_API
 405 void        gst_buffer_set_size            (GstBuffer *buffer, gssize size);
 406
 407 GST_API
 408 gboolean    gst_buffer_map_range           (GstBuffer *buffer, guint idx, gint length,
 409                                             GstMapInfo *info, GstMapFlags flags);
 410 GST_API
 411 gboolean    gst_buffer_map                 (GstBuffer *buffer, GstMapInfo *info, GstMapFlags flags);
 412
 413 GST_API
 414 void        gst_buffer_unmap               (GstBuffer *buffer, GstMapInfo *info);
 415
 416 GST_API
 417 void        gst_buffer_extract_dup         (GstBuffer *buffer, gsize offset,
 418                                             gsize size, gpointer *dest,
 419                                             gsize *dest_size);
 420 GST_API
 421 GstBufferFlags gst_buffer_get_flags        (GstBuffer * buffer);
 422
 423 GST_API
 424 gboolean       gst_buffer_has_flags        (GstBuffer * buffer, GstBufferFlags flags);
 425
 426 GST_API
 427 gboolean       gst_buffer_set_flags        (GstBuffer * buffer, GstBufferFlags flags);
 428
 429 GST_API
 430 gboolean       gst_buffer_unset_flags      (GstBuffer * buffer, GstBufferFlags flags);
 431
 432
 433 #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
 434 /* refcounting */
 435 static inline GstBuffer *
 436 gst_buffer_ref (GstBuffer * buf)
 437 {
 438   return (GstBuffer *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (buf));
 439 }
 440
 441 static inline void
 442 gst_buffer_unref (GstBuffer * buf)
 443 {
 444   gst_mini_object_unref (GST_MINI_OBJECT_CAST (buf));
 445 }
 446
 447 static inline void
 448 gst_clear_buffer (GstBuffer ** buf_ptr)
 449 {
 450   gst_clear_mini_object ((GstMiniObject **) buf_ptr);
 451 }
 452
 453 /* copy buffer */
 454 static inline GstBuffer *
 455 gst_buffer_copy (const GstBuffer * buf)
 456 {
 457   return GST_BUFFER (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (buf)));
 458 }
 459 #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 460 GST_API
 461 GstBuffer * gst_buffer_ref       (GstBuffer * buf);
 462
 463 GST_API
 464 void        gst_buffer_unref     (GstBuffer * buf);
 465
 466 GST_API
 467 void        gst_clear_buffer     (GstBuffer ** buf_ptr);
 468
 469 GST_API
 470 GstBuffer * gst_buffer_copy      (const GstBuffer * buf);
 471 #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 472
 473 GST_API
 474 GstBuffer * gst_buffer_copy_deep (const GstBuffer * buf);
 475
 476 /**
 477  * GstBufferCopyFlags:
 478  * @GST_BUFFER_COPY_NONE: copy nothing
 479  * @GST_BUFFER_COPY_FLAGS: flag indicating that buffer flags should be copied
 480  * @GST_BUFFER_COPY_TIMESTAMPS: flag indicating that buffer pts, dts,
 481  *   duration, offset and offset_end should be copied
 482  * @GST_BUFFER_COPY_MEMORY: flag indicating that buffer memory should be reffed
 483  *   and appended to already existing memory. Unless the memory is marked as
 484  *   NO_SHARE, no actual copy of the memory is made but it is simply reffed.
 485  *   Add @GST_BUFFER_COPY_DEEP to force a real copy.
 486  * @GST_BUFFER_COPY_MERGE: flag indicating that buffer memory should be
 487  *   merged
 488  * @GST_BUFFER_COPY_META: flag indicating that buffer meta should be
 489  *   copied
 490  *
 491  * A set of flags that can be provided to the gst_buffer_copy_into()
 492  * function to specify which items should be copied.
 493  */
 494 typedef enum {
 495   GST_BUFFER_COPY_NONE           = 0,
 496   GST_BUFFER_COPY_FLAGS          = (1 << 0),
 497   GST_BUFFER_COPY_TIMESTAMPS     = (1 << 1),
 498   GST_BUFFER_COPY_META           = (1 << 2),
 499   GST_BUFFER_COPY_MEMORY         = (1 << 3),
 500   GST_BUFFER_COPY_MERGE          = (1 << 4),
 501
 502   /**
 503    * GST_BUFFER_COPY_DEEP:
 504    *
 505    * flag indicating that memory should always be copied instead of reffed
 506    *
 507    * Since: 1.2
 508    */
 509   GST_BUFFER_COPY_DEEP           = (1 << 5)
 510 } GstBufferCopyFlags;
 511
 512 /**
 513  * GST_BUFFER_COPY_METADATA: (value 7) (type GstBufferCopyFlags)
 514  *
 515  * Combination of all possible metadata fields that can be copied with
 516  * gst_buffer_copy_into().
 517  */
 518 #define GST_BUFFER_COPY_METADATA       ((GstBufferCopyFlags) (GST_BUFFER_COPY_FLAGS |\
 519                                           GST_BUFFER_COPY_TIMESTAMPS | GST_BUFFER_COPY_META))
 520
 521 /**
 522  * GST_BUFFER_COPY_ALL: (value 15) (type GstBufferCopyFlags)
 523  *
 524  * Combination of all possible fields that can be copied with
 525  * gst_buffer_copy_into().
 526  */
 527 #define GST_BUFFER_COPY_ALL  ((GstBufferCopyFlags)(GST_BUFFER_COPY_METADATA | GST_BUFFER_COPY_MEMORY))
 528
 529 /* copies memory or metadata into newly allocated buffer */
 530
 531 GST_API
 532 gboolean        gst_buffer_copy_into            (GstBuffer *dest, GstBuffer *src,
 533                                                  GstBufferCopyFlags flags,
 534                                                  gsize offset, gsize size);
 535
 536 /**
 537  * gst_buffer_is_writable:
 538  * @buf: a #GstBuffer
 539  *
 540  * Tests if you can safely write to a buffer's metadata or its memory array.
 541  * It is only safe to change buffer metadata when the current reference is
 542  * writable, i.e. nobody can see the modifications you will make.
 543  */
 544 #define         gst_buffer_is_writable(buf)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf))
 545 /**
 546  * gst_buffer_make_writable:
 547  * @buf: (transfer full): a #GstBuffer
 548  *
 549  * Returns a writable copy of @buf. If the source buffer is
 550  * already writable, this will simply return the same buffer.
 551  *
 552  * Use this function to ensure that a buffer can be safely modified before
 553  * making changes to it, including changing the metadata such as PTS/DTS.
 554  *
 555  * If the reference count of the source buffer @buf is exactly one, the caller
 556  * is the sole owner and this function will return the buffer object unchanged.
 557  *
 558  * If there is more than one reference on the object, a copy will be made using
 559  * gst_buffer_copy(). The passed-in @buf will be unreffed in that case, and the
 560  * caller will now own a reference to the new returned buffer object. Note
 561  * that this just copies the buffer structure itself, the underlying memory is
 562  * not copied if it can be shared amongst multiple buffers.
 563  *
 564  * In short, this function unrefs the buf in the argument and refs the buffer
 565  * that it returns. Don't access the argument after calling this function unless
 566  * you have an additional reference to it.
 567  *
 568  * Returns: (transfer full): a writable buffer which may or may not be the
 569  *     same as @buf
 570  */
 571 #define         gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf)))
 572
 573 #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
 574 static inline gboolean
 575 gst_buffer_replace (GstBuffer **obuf, GstBuffer *nbuf)
 576 {
 577   return gst_mini_object_replace ((GstMiniObject **) obuf, (GstMiniObject *) nbuf);
 578 }
 579 #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 580 GST_API
 581 gboolean        gst_buffer_replace              (GstBuffer ** obuf,
 582                                                  GstBuffer * nbuf);
 583 #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 584
 585 /* creating a region */
 586
 587 GST_API
 588 GstBuffer*      gst_buffer_copy_region          (GstBuffer *parent, GstBufferCopyFlags flags,
 589                                                  gsize offset, gsize size);
 590
 591 /* append two buffers */
 592
 593 GST_API
 594 GstBuffer*      gst_buffer_append_region        (GstBuffer *buf1, GstBuffer *buf2,
 595                                                  gssize offset, gssize size);
 596 GST_API
 597 GstBuffer*      gst_buffer_append               (GstBuffer *buf1, GstBuffer *buf2);
 598
 599 /* metadata */
 600 #include <gst/gstmeta.h>
 601
 602 /**
 603  * GstBufferForeachMetaFunc:
 604  * @buffer: a #GstBuffer
 605  * @meta: (out) (nullable): a pointer to a #GstMeta
 606  * @user_data: user data passed to gst_buffer_foreach_meta()
 607  *
 608  * A function that will be called from gst_buffer_foreach_meta(). The @meta
 609  * field will point to a the reference of the meta.
 610  *
 611  * @buffer should not be modified from this callback.
 612  *
 613  * When this function returns %TRUE, the next meta will be
 614  * returned. When %FALSE is returned, gst_buffer_foreach_meta() will return.
 615  *
 616  * When @meta is set to %NULL, the item will be removed from the buffer.
 617  *
 618  * Returns: %FALSE when gst_buffer_foreach_meta() should stop
 619  */
 620 typedef gboolean (*GstBufferForeachMetaFunc)    (GstBuffer *buffer, GstMeta **meta,
 621                                                  gpointer user_data);
 622
 623 GST_API
 624 GstMeta *       gst_buffer_get_meta             (GstBuffer *buffer, GType api);
 625
 626 GST_API
 627 guint           gst_buffer_get_n_meta           (GstBuffer *buffer, GType api_type);
 628
 629 GST_API
 630 GstMeta *       gst_buffer_add_meta             (GstBuffer *buffer, const GstMetaInfo *info,
 631                                                  gpointer params);
 632 GST_API
 633 gboolean        gst_buffer_remove_meta          (GstBuffer *buffer, GstMeta *meta);
 634
 635 GST_API
 636 GstMeta *       gst_buffer_iterate_meta         (GstBuffer *buffer, gpointer *state);
 637
 638 GST_API
 639 GstMeta *       gst_buffer_iterate_meta_filtered (GstBuffer * buffer,
 640                                                   gpointer  * state,
 641                                                   GType       meta_api_type);
 642 GST_API
 643 gboolean        gst_buffer_foreach_meta         (GstBuffer *buffer,
 644                                                  GstBufferForeachMetaFunc func,
 645                                                  gpointer user_data);
 646
 647 GST_API
 648 GstCustomMeta * gst_buffer_add_custom_meta      (GstBuffer *buffer,
 649                                                  const gchar *name);
 650
 651 GST_API
 652 GstCustomMeta * gst_buffer_get_custom_meta      (GstBuffer *buffer,
 653                                                  const gchar *name);
 654
 655 /**
 656  * gst_value_set_buffer:
 657  * @v: a #GValue to receive the data
 658  * @b: (transfer none): a #GstBuffer to assign to the GstValue
 659  *
 660  * Sets @b as the value of @v.  Caller retains reference to buffer.
 661  */
 662 #define         gst_value_set_buffer(v,b)       g_value_set_boxed((v),(b))
 663 /**
 664  * gst_value_take_buffer:
 665  * @v: a #GValue to receive the data
 666  * @b: (transfer full): a #GstBuffer to assign to the GstValue
 667  *
 668  * Sets @b as the value of @v.  Caller gives away reference to buffer.
 669  */
 670 #define         gst_value_take_buffer(v,b)      g_value_take_boxed(v,(b))
 671 /**
 672  * gst_value_get_buffer:
 673  * @v: a #GValue to query
 674  *
 675  * Receives a #GstBuffer as the value of @v. Does not return a reference to
 676  * the buffer, so the pointer is only valid for as long as the caller owns
 677  * a reference to @v.
 678  *
 679  * Returns: (transfer none): buffer
 680  */
 681 #define         gst_value_get_buffer(v)         GST_BUFFER_CAST (g_value_get_boxed(v))
 682
 683 typedef struct _GstParentBufferMeta GstParentBufferMeta;
 684
 685 /**
 686  * GstParentBufferMeta:
 687  * @parent: the parent #GstMeta structure
 688  * @buffer: the #GstBuffer on which a reference is being held.
 689  *
 690  * The #GstParentBufferMeta is a #GstMeta which can be attached to a #GstBuffer
 691  * to hold a reference to another buffer that is only released when the child
 692  * #GstBuffer is released.
 693  *
 694  * Typically, #GstParentBufferMeta is used when the child buffer is directly
 695  * using the #GstMemory of the parent buffer, and wants to prevent the parent
 696  * buffer from being returned to a buffer pool until the #GstMemory is available
 697  * for re-use.
 698  *
 699  * Since: 1.6
 700  */
 701 struct _GstParentBufferMeta
 702 {
 703   GstMeta parent;
 704
 705   /*< public >*/
 706   GstBuffer *buffer;
 707 };
 708
 709 GST_API
 710 GType gst_parent_buffer_meta_api_get_type (void);
 711 #ifndef GST_DISABLE_DEPRECATED
 712 #define GST_TYPE_PARENT_BUFFER_META_API_TYPE GST_PARENT_BUFFER_META_API_TYPE
 713 #endif
 714 #define GST_PARENT_BUFFER_META_API_TYPE (gst_parent_buffer_meta_api_get_type())
 715
 716 /**
 717  * gst_buffer_get_parent_buffer_meta:
 718  * @b: a #GstBuffer
 719  *
 720  * Finds and returns a #GstParentBufferMeta if one exists on the
 721  * buffer
 722  */
 723 #define gst_buffer_get_parent_buffer_meta(b) \
 724   ((GstParentBufferMeta*)gst_buffer_get_meta((b),GST_PARENT_BUFFER_META_API_TYPE))
 725
 726 GST_API
 727 const GstMetaInfo *gst_parent_buffer_meta_get_info (void);
 728 #define GST_PARENT_BUFFER_META_INFO (gst_parent_buffer_meta_get_info())
 729
 730 /* implementation */
 731
 732 GST_API
 733 GstParentBufferMeta *gst_buffer_add_parent_buffer_meta (GstBuffer *buffer,
 734     GstBuffer *ref);
 735
 736 typedef struct _GstReferenceTimestampMeta GstReferenceTimestampMeta;
 737
 738 /**
 739  * GstReferenceTimestampMeta:
 740  * @parent: the parent #GstMeta structure
 741  * @reference: identifier for the timestamp reference.
 742  * @timestamp: timestamp
 743  * @duration: duration, or %GST_CLOCK_TIME_NONE
 744  *
 745  * #GstReferenceTimestampMeta can be used to attach alternative timestamps and
 746  * possibly durations to a #GstBuffer. These are generally not according to
 747  * the pipeline clock and could be e.g. the NTP timestamp when the media was
 748  * captured.
 749  *
 750  * The reference is stored as a #GstCaps in @reference. Examples of valid
 751  * references would be `timestamp/x-drivername-stream` for timestamps that are locally
 752  * generated by some driver named `drivername` when generating the stream,
 753  * e.g. based on a frame counter, or `timestamp/x-ntp, host=pool.ntp.org,
 754  * port=123` for timestamps based on a specific NTP server.
 755  *
 756  * Since: 1.14
 757  */
 758 struct _GstReferenceTimestampMeta
 759 {
 760   GstMeta parent;
 761
 762   /*< public >*/
 763   GstCaps *reference;
 764   GstClockTime timestamp, duration;
 765 };
 766
 767 GST_API
 768 GType gst_reference_timestamp_meta_api_get_type (void);
 769 #define GST_REFERENCE_TIMESTAMP_META_API_TYPE (gst_reference_timestamp_meta_api_get_type())
 770
 771 GST_API
 772 const GstMetaInfo *gst_reference_timestamp_meta_get_info (void);
 773 #define GST_REFERENCE_TIMESTAMP_META_INFO (gst_reference_timestamp_meta_get_info())
 774
 775 /* implementation */
 776
 777 GST_API
 778 GstReferenceTimestampMeta * gst_buffer_add_reference_timestamp_meta (GstBuffer  * buffer,
 779                                                                      GstCaps    * reference,
 780                                                                      GstClockTime timestamp,
 781                                                                      GstClockTime duration);
 782
 783 GST_API
 784 GstReferenceTimestampMeta * gst_buffer_get_reference_timestamp_meta (GstBuffer * buffer,
 785                                                                      GstCaps   * reference);
 786
 787 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBuffer, gst_buffer_unref)
 788
 789 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBufferPool, gst_object_unref)
 790
 791 G_END_DECLS
 792
 793 #endif /* __GST_BUFFER_H__ */