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. for RTP
 202  *                                 packets this matches the marker flag in the
 203  *                                 RTP packet header.
 204  * @GST_BUFFER_FLAG_HEADER:        the buffer contains header information that is
 205  *                                 needed to decode the following data.
 206  * @GST_BUFFER_FLAG_GAP:           the buffer has been created to fill a gap in the
 207  *                                 stream and contains media neutral data (elements can
 208  *                                 switch to optimized code path that ignores the buffer
 209  *                                 content).
 210  * @GST_BUFFER_FLAG_DROPPABLE:     the buffer can be dropped without breaking the
 211  *                                 stream, for example to reduce bandwidth.
 212  * @GST_BUFFER_FLAG_DELTA_UNIT:    this unit cannot be decoded independently.
 213  * @GST_BUFFER_FLAG_TAG_MEMORY:    this flag is set when memory of the buffer
 214  *                                 is added/removed
 215  * @GST_BUFFER_FLAG_LAST:          additional media specific flags can be added starting from
 216  *                                 this flag.
 217  *
 218  * A set of buffer flags used to describe properties of a #GstBuffer.
 219  */
 220 typedef enum {
 221   GST_BUFFER_FLAG_LIVE          = (GST_MINI_OBJECT_FLAG_LAST << 0),
 222   GST_BUFFER_FLAG_DECODE_ONLY   = (GST_MINI_OBJECT_FLAG_LAST << 1),
 223   GST_BUFFER_FLAG_DISCONT       = (GST_MINI_OBJECT_FLAG_LAST << 2),
 224   GST_BUFFER_FLAG_RESYNC        = (GST_MINI_OBJECT_FLAG_LAST << 3),
 225   GST_BUFFER_FLAG_CORRUPTED     = (GST_MINI_OBJECT_FLAG_LAST << 4),
 226   GST_BUFFER_FLAG_MARKER        = (GST_MINI_OBJECT_FLAG_LAST << 5),
 227   GST_BUFFER_FLAG_HEADER        = (GST_MINI_OBJECT_FLAG_LAST << 6),
 228   GST_BUFFER_FLAG_GAP           = (GST_MINI_OBJECT_FLAG_LAST << 7),
 229   GST_BUFFER_FLAG_DROPPABLE     = (GST_MINI_OBJECT_FLAG_LAST << 8),
 230   GST_BUFFER_FLAG_DELTA_UNIT    = (GST_MINI_OBJECT_FLAG_LAST << 9),
 231   GST_BUFFER_FLAG_TAG_MEMORY    = (GST_MINI_OBJECT_FLAG_LAST << 10),
 232
 233   /**
 234    * GST_BUFFER_FLAG_SYNC_AFTER:
 235    *
 236    * Elements which write to disk or permanent storage should ensure the data
 237    * is synced after writing the contents of this buffer.
 238    *
 239    * Since: 1.6
 240    */
 241   GST_BUFFER_FLAG_SYNC_AFTER    = (GST_MINI_OBJECT_FLAG_LAST << 11),
 242
 243   /**
 244    * GST_BUFFER_FLAG_NON_DROPPABLE:
 245    *
 246    * This buffer is important and should not be dropped.
 247    *
 248    * This can be used to mark important buffers, e.g. to flag RTP packets
 249    * carrying keyframes or codec setup data for RTP Forward Error Correction
 250    * purposes, or to prevent still video frames from being dropped by elements
 251    * due to QoS.
 252    *
 253    * Since: 1.14
 254    */
 255   GST_BUFFER_FLAG_NON_DROPPABLE = (GST_MINI_OBJECT_FLAG_LAST << 12),
 256
 257   GST_BUFFER_FLAG_LAST          = (GST_MINI_OBJECT_FLAG_LAST << 16)
 258 } GstBufferFlags;
 259
 260 /**
 261  * GstBuffer:
 262  * @mini_object: the parent structure
 263  * @pool: pointer to the pool owner of the buffer
 264  * @pts: presentation timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the
 265  *     pts is not known or relevant. The pts contains the timestamp when the
 266  *     media should be presented to the user.
 267  * @dts: decoding timestamp of the buffer, can be #GST_CLOCK_TIME_NONE when the
 268  *     dts is not known or relevant. The dts contains the timestamp when the
 269  *     media should be processed.
 270  * @duration: duration in time of the buffer data, can be #GST_CLOCK_TIME_NONE
 271  *     when the duration is not known or relevant.
 272  * @offset: a media specific offset for the buffer data.
 273  *     For video frames, this is the frame number of this buffer.
 274  *     For audio samples, this is the offset of the first sample in this buffer.
 275  *     For file data or compressed data this is the byte offset of the first
 276  *       byte in this buffer.
 277  * @offset_end: the last offset contained in this buffer. It has the same
 278  *     format as @offset.
 279  *
 280  * The structure of a #GstBuffer. Use the associated macros to access the public
 281  * variables.
 282  */
 283 struct _GstBuffer {
 284   GstMiniObject          mini_object;
 285
 286   /*< public >*/ /* with COW */
 287   GstBufferPool         *pool;
 288
 289   /* timestamp */
 290   GstClockTime           pts;
 291   GstClockTime           dts;
 292   GstClockTime           duration;
 293
 294   /* media specific offset */
 295   guint64                offset;
 296   guint64                offset_end;
 297 };
 298
 299 GST_API
 300 GType       gst_buffer_get_type            (void);
 301
 302 GST_API
 303 guint       gst_buffer_get_max_memory      (void);
 304
 305 /* allocation */
 306
 307 GST_API
 308 GstBuffer * gst_buffer_new                 (void);
 309
 310 GST_API
 311 GstBuffer * gst_buffer_new_allocate        (GstAllocator * allocator, gsize size,
 312                                             GstAllocationParams * params);
 313 GST_API
 314 GstBuffer * gst_buffer_new_wrapped_full    (GstMemoryFlags flags, gpointer data, gsize maxsize,
 315                                             gsize offset, gsize size, gpointer user_data,
 316                                             GDestroyNotify notify);
 317 GST_API
 318 GstBuffer * gst_buffer_new_wrapped         (gpointer data, gsize size);
 319
 320 GST_API
 321 GstBuffer * gst_buffer_new_wrapped_bytes   (GBytes * bytes);
 322
 323 GST_API
 324 GstBuffer * gst_buffer_new_memdup           (gconstpointer data, gsize size);
 325
 326 /* memory blocks */
 327
 328 GST_API
 329 guint       gst_buffer_n_memory             (GstBuffer *buffer);
 330
 331 GST_API
 332 void        gst_buffer_insert_memory        (GstBuffer *buffer, gint idx, GstMemory *mem);
 333
 334 GST_API
 335 void        gst_buffer_replace_memory_range (GstBuffer *buffer, guint idx, gint length, GstMemory *mem);
 336
 337 GST_API
 338 GstMemory * gst_buffer_peek_memory          (GstBuffer *buffer, guint idx);
 339
 340 GST_API
 341 GstMemory * gst_buffer_get_memory_range     (GstBuffer *buffer, guint idx, gint length);
 342
 343 GST_API
 344 void        gst_buffer_remove_memory_range  (GstBuffer *buffer, guint idx, gint length);
 345
 346 GST_API
 347 void        gst_buffer_prepend_memory       (GstBuffer *buffer, GstMemory *mem);
 348
 349 GST_API
 350 void        gst_buffer_append_memory        (GstBuffer *buffer, GstMemory *mem);
 351
 352 GST_API
 353 void        gst_buffer_replace_memory       (GstBuffer *buffer, guint idx, GstMemory *mem);
 354
 355 GST_API
 356 void        gst_buffer_replace_all_memory   (GstBuffer *buffer, GstMemory *mem);
 357
 358 GST_API
 359 GstMemory * gst_buffer_get_memory           (GstBuffer *buffer, guint idx);
 360
 361 GST_API
 362 GstMemory * gst_buffer_get_all_memory       (GstBuffer *buffer);
 363
 364 GST_API
 365 void        gst_buffer_remove_memory        (GstBuffer *buffer, guint idx);
 366
 367 GST_API
 368 void        gst_buffer_remove_all_memory    (GstBuffer *buffer);
 369
 370 GST_API
 371 gboolean    gst_buffer_find_memory         (GstBuffer *buffer, gsize offset, gsize size,
 372                                             guint *idx, guint *length, gsize *skip);
 373 GST_API
 374 gboolean    gst_buffer_is_memory_range_writable  (GstBuffer *buffer, guint idx, gint length);
 375
 376 GST_API
 377 gboolean    gst_buffer_is_all_memory_writable    (GstBuffer *buffer);
 378
 379 GST_API
 380 gsize       gst_buffer_fill                (GstBuffer *buffer, gsize offset,
 381                                             gconstpointer src, gsize size);
 382 GST_API
 383 gsize       gst_buffer_extract             (GstBuffer *buffer, gsize offset,
 384                                             gpointer dest, gsize size);
 385 GST_API
 386 gint        gst_buffer_memcmp              (GstBuffer *buffer, gsize offset,
 387                                             gconstpointer mem, gsize size);
 388 GST_API
 389 gsize       gst_buffer_memset              (GstBuffer *buffer, gsize offset,
 390                                             guint8 val, gsize size);
 391 GST_API
 392 gsize       gst_buffer_get_sizes_range     (GstBuffer *buffer, guint idx, gint length,
 393                                             gsize *offset, gsize *maxsize);
 394 GST_API
 395 gboolean    gst_buffer_resize_range        (GstBuffer *buffer, guint idx, gint length,
 396                                             gssize offset, gssize size);
 397 GST_API
 398 gsize       gst_buffer_get_sizes           (GstBuffer *buffer, gsize *offset, gsize *maxsize);
 399
 400 GST_API
 401 gsize       gst_buffer_get_size            (GstBuffer *buffer);
 402
 403 GST_API
 404 void        gst_buffer_resize              (GstBuffer *buffer, gssize offset, gssize size);
 405
 406 GST_API
 407 void        gst_buffer_set_size            (GstBuffer *buffer, gssize size);
 408
 409 GST_API
 410 gboolean    gst_buffer_map_range           (GstBuffer *buffer, guint idx, gint length,
 411                                             GstMapInfo *info, GstMapFlags flags);
 412 GST_API
 413 gboolean    gst_buffer_map                 (GstBuffer *buffer, GstMapInfo *info, GstMapFlags flags);
 414
 415 GST_API
 416 void        gst_buffer_unmap               (GstBuffer *buffer, GstMapInfo *info);
 417
 418 GST_API
 419 void        gst_buffer_extract_dup         (GstBuffer *buffer, gsize offset,
 420                                             gsize size, gpointer *dest,
 421                                             gsize *dest_size);
 422 GST_API
 423 GstBufferFlags gst_buffer_get_flags        (GstBuffer * buffer);
 424
 425 GST_API
 426 gboolean       gst_buffer_has_flags        (GstBuffer * buffer, GstBufferFlags flags);
 427
 428 GST_API
 429 gboolean       gst_buffer_set_flags        (GstBuffer * buffer, GstBufferFlags flags);
 430
 431 GST_API
 432 gboolean       gst_buffer_unset_flags      (GstBuffer * buffer, GstBufferFlags flags);
 433
 434
 435 #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
 436 /* refcounting */
 437 static inline GstBuffer *
 438 gst_buffer_ref (GstBuffer * buf)
 439 {
 440   return (GstBuffer *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (buf));
 441 }
 442
 443 static inline void
 444 gst_buffer_unref (GstBuffer * buf)
 445 {
 446   gst_mini_object_unref (GST_MINI_OBJECT_CAST (buf));
 447 }
 448
 449 static inline void
 450 gst_clear_buffer (GstBuffer ** buf_ptr)
 451 {
 452   gst_clear_mini_object ((GstMiniObject **) buf_ptr);
 453 }
 454
 455 /* copy buffer */
 456 static inline GstBuffer *
 457 gst_buffer_copy (const GstBuffer * buf)
 458 {
 459   return GST_BUFFER (gst_mini_object_copy (GST_MINI_OBJECT_CONST_CAST (buf)));
 460 }
 461 #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 462 GST_API
 463 GstBuffer * gst_buffer_ref       (GstBuffer * buf);
 464
 465 GST_API
 466 void        gst_buffer_unref     (GstBuffer * buf);
 467
 468 GST_API
 469 void        gst_clear_buffer     (GstBuffer ** buf_ptr);
 470
 471 GST_API
 472 GstBuffer * gst_buffer_copy      (const GstBuffer * buf);
 473 #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 474
 475 GST_API
 476 GstBuffer * gst_buffer_copy_deep (const GstBuffer * buf);
 477
 478 /**
 479  * GstBufferCopyFlags:
 480  * @GST_BUFFER_COPY_NONE: copy nothing
 481  * @GST_BUFFER_COPY_FLAGS: flag indicating that buffer flags should be copied
 482  * @GST_BUFFER_COPY_TIMESTAMPS: flag indicating that buffer pts, dts,
 483  *   duration, offset and offset_end should be copied
 484  * @GST_BUFFER_COPY_MEMORY: flag indicating that buffer memory should be reffed
 485  *   and appended to already existing memory. Unless the memory is marked as
 486  *   NO_SHARE, no actual copy of the memory is made but it is simply reffed.
 487  *   Add @GST_BUFFER_COPY_DEEP to force a real copy.
 488  * @GST_BUFFER_COPY_MERGE: flag indicating that buffer memory should be
 489  *   merged
 490  * @GST_BUFFER_COPY_META: flag indicating that buffer meta should be
 491  *   copied
 492  *
 493  * A set of flags that can be provided to the gst_buffer_copy_into()
 494  * function to specify which items should be copied.
 495  */
 496 typedef enum {
 497   GST_BUFFER_COPY_NONE           = 0,
 498   GST_BUFFER_COPY_FLAGS          = (1 << 0),
 499   GST_BUFFER_COPY_TIMESTAMPS     = (1 << 1),
 500   GST_BUFFER_COPY_META           = (1 << 2),
 501   GST_BUFFER_COPY_MEMORY         = (1 << 3),
 502   GST_BUFFER_COPY_MERGE          = (1 << 4),
 503
 504   /**
 505    * GST_BUFFER_COPY_DEEP:
 506    *
 507    * flag indicating that memory should always be copied instead of reffed
 508    *
 509    * Since: 1.2
 510    */
 511   GST_BUFFER_COPY_DEEP           = (1 << 5)
 512 } GstBufferCopyFlags;
 513
 514 /**
 515  * GST_BUFFER_COPY_METADATA: (value 7) (type GstBufferCopyFlags)
 516  *
 517  * Combination of all possible metadata fields that can be copied with
 518  * gst_buffer_copy_into().
 519  */
 520 #define GST_BUFFER_COPY_METADATA       ((GstBufferCopyFlags) (GST_BUFFER_COPY_FLAGS |\
 521                                           GST_BUFFER_COPY_TIMESTAMPS | GST_BUFFER_COPY_META))
 522
 523 /**
 524  * GST_BUFFER_COPY_ALL: (value 15) (type GstBufferCopyFlags)
 525  *
 526  * Combination of all possible fields that can be copied with
 527  * gst_buffer_copy_into().
 528  */
 529 #define GST_BUFFER_COPY_ALL  ((GstBufferCopyFlags)(GST_BUFFER_COPY_METADATA | GST_BUFFER_COPY_MEMORY))
 530
 531 /* copies memory or metadata into newly allocated buffer */
 532
 533 GST_API
 534 gboolean        gst_buffer_copy_into            (GstBuffer *dest, GstBuffer *src,
 535                                                  GstBufferCopyFlags flags,
 536                                                  gsize offset, gsize size);
 537
 538 /**
 539  * gst_buffer_is_writable:
 540  * @buf: a #GstBuffer
 541  *
 542  * Tests if you can safely write to a buffer's metadata or its memory array.
 543  * It is only safe to change buffer metadata when the current reference is
 544  * writable, i.e. nobody can see the modifications you will make.
 545  */
 546 #define         gst_buffer_is_writable(buf)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf))
 547 /**
 548  * gst_buffer_make_writable:
 549  * @buf: (transfer full): a #GstBuffer
 550  *
 551  * Returns a writable copy of @buf. If the source buffer is
 552  * already writable, this will simply return the same buffer.
 553  *
 554  * Use this function to ensure that a buffer can be safely modified before
 555  * making changes to it, including changing the metadata such as PTS/DTS.
 556  *
 557  * If the reference count of the source buffer @buf is exactly one, the caller
 558  * is the sole owner and this function will return the buffer object unchanged.
 559  *
 560  * If there is more than one reference on the object, a copy will be made using
 561  * gst_buffer_copy(). The passed-in @buf will be unreffed in that case, and the
 562  * caller will now own a reference to the new returned buffer object. Note
 563  * that this just copies the buffer structure itself, the underlying memory is
 564  * not copied if it can be shared amongst multiple buffers.
 565  *
 566  * In short, this function unrefs the buf in the argument and refs the buffer
 567  * that it returns. Don't access the argument after calling this function unless
 568  * you have an additional reference to it.
 569  *
 570  * Returns: (transfer full) (nullable): a writable buffer (which may or may not be the
 571  *     same as @buf) or %NULL if copying is required but not possible.
 572  */
 573 #define         gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf)))
 574
 575 #ifndef GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS
 576 static inline gboolean
 577 gst_buffer_replace (GstBuffer **obuf, GstBuffer *nbuf)
 578 {
 579   return gst_mini_object_replace ((GstMiniObject **) obuf, (GstMiniObject *) nbuf);
 580 }
 581 #else /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 582 GST_API
 583 gboolean        gst_buffer_replace              (GstBuffer ** obuf,
 584                                                  GstBuffer * nbuf);
 585 #endif /* GST_DISABLE_MINIOBJECT_INLINE_FUNCTIONS */
 586
 587 /* creating a region */
 588
 589 GST_API
 590 GstBuffer*      gst_buffer_copy_region          (GstBuffer *parent, GstBufferCopyFlags flags,
 591                                                  gsize offset, gsize size);
 592
 593 /* append two buffers */
 594
 595 GST_API
 596 GstBuffer*      gst_buffer_append_region        (GstBuffer *buf1, GstBuffer *buf2,
 597                                                  gssize offset, gssize size);
 598 GST_API
 599 GstBuffer*      gst_buffer_append               (GstBuffer *buf1, GstBuffer *buf2);
 600
 601 /* metadata */
 602 #include <gst/gstmeta.h>
 603
 604 /**
 605  * GstBufferForeachMetaFunc:
 606  * @buffer: a #GstBuffer
 607  * @meta: (out) (nullable): a pointer to a #GstMeta
 608  * @user_data: user data passed to gst_buffer_foreach_meta()
 609  *
 610  * A function that will be called from gst_buffer_foreach_meta(). The @meta
 611  * field will point to a the reference of the meta.
 612  *
 613  * @buffer should not be modified from this callback.
 614  *
 615  * When this function returns %TRUE, the next meta will be
 616  * returned. When %FALSE is returned, gst_buffer_foreach_meta() will return.
 617  *
 618  * When @meta is set to %NULL, the item will be removed from the buffer.
 619  *
 620  * Returns: %FALSE when gst_buffer_foreach_meta() should stop
 621  */
 622 typedef gboolean (*GstBufferForeachMetaFunc)    (GstBuffer *buffer, GstMeta **meta,
 623                                                  gpointer user_data);
 624
 625 GST_API
 626 GstMeta *       gst_buffer_get_meta             (GstBuffer *buffer, GType api);
 627
 628 GST_API
 629 guint           gst_buffer_get_n_meta           (GstBuffer *buffer, GType api_type);
 630
 631 GST_API
 632 GstMeta *       gst_buffer_add_meta             (GstBuffer *buffer, const GstMetaInfo *info,
 633                                                  gpointer params);
 634 GST_API
 635 gboolean        gst_buffer_remove_meta          (GstBuffer *buffer, GstMeta *meta);
 636
 637 GST_API
 638 GstMeta *       gst_buffer_iterate_meta         (GstBuffer *buffer, gpointer *state);
 639
 640 GST_API
 641 GstMeta *       gst_buffer_iterate_meta_filtered (GstBuffer * buffer,
 642                                                   gpointer  * state,
 643                                                   GType       meta_api_type);
 644 GST_API
 645 gboolean        gst_buffer_foreach_meta         (GstBuffer *buffer,
 646                                                  GstBufferForeachMetaFunc func,
 647                                                  gpointer user_data);
 648
 649 GST_API
 650 GstCustomMeta * gst_buffer_add_custom_meta      (GstBuffer *buffer,
 651                                                  const gchar *name);
 652
 653 GST_API
 654 GstCustomMeta * gst_buffer_get_custom_meta      (GstBuffer *buffer,
 655                                                  const gchar *name);
 656
 657 /**
 658  * gst_value_set_buffer:
 659  * @v: a #GValue to receive the data
 660  * @b: (transfer none): a #GstBuffer to assign to the GstValue
 661  *
 662  * Sets @b as the value of @v.  Caller retains reference to buffer.
 663  */
 664 #define         gst_value_set_buffer(v,b)       g_value_set_boxed((v),(b))
 665 /**
 666  * gst_value_take_buffer:
 667  * @v: a #GValue to receive the data
 668  * @b: (transfer full): a #GstBuffer to assign to the GstValue
 669  *
 670  * Sets @b as the value of @v.  Caller gives away reference to buffer.
 671  */
 672 #define         gst_value_take_buffer(v,b)      g_value_take_boxed(v,(b))
 673 /**
 674  * gst_value_get_buffer:
 675  * @v: a #GValue to query
 676  *
 677  * Receives a #GstBuffer as the value of @v. Does not return a reference to
 678  * the buffer, so the pointer is only valid for as long as the caller owns
 679  * a reference to @v.
 680  *
 681  * Returns: (transfer none): buffer
 682  */
 683 #define         gst_value_get_buffer(v)         GST_BUFFER_CAST (g_value_get_boxed(v))
 684
 685 typedef struct _GstParentBufferMeta GstParentBufferMeta;
 686
 687 /**
 688  * GstParentBufferMeta:
 689  * @parent: the parent #GstMeta structure
 690  * @buffer: the #GstBuffer on which a reference is being held.
 691  *
 692  * The #GstParentBufferMeta is a #GstMeta which can be attached to a #GstBuffer
 693  * to hold a reference to another buffer that is only released when the child
 694  * #GstBuffer is released.
 695  *
 696  * Typically, #GstParentBufferMeta is used when the child buffer is directly
 697  * using the #GstMemory of the parent buffer, and wants to prevent the parent
 698  * buffer from being returned to a buffer pool until the #GstMemory is available
 699  * for re-use.
 700  *
 701  * Since: 1.6
 702  */
 703 struct _GstParentBufferMeta
 704 {
 705   GstMeta parent;
 706
 707   /*< public >*/
 708   GstBuffer *buffer;
 709 };
 710
 711 GST_API
 712 GType gst_parent_buffer_meta_api_get_type (void);
 713 #ifndef GST_DISABLE_DEPRECATED
 714 #define GST_TYPE_PARENT_BUFFER_META_API_TYPE GST_PARENT_BUFFER_META_API_TYPE
 715 #endif
 716 #define GST_PARENT_BUFFER_META_API_TYPE (gst_parent_buffer_meta_api_get_type())
 717
 718 /**
 719  * gst_buffer_get_parent_buffer_meta:
 720  * @b: a #GstBuffer
 721  *
 722  * Finds and returns a #GstParentBufferMeta if one exists on the
 723  * buffer
 724  */
 725 #define gst_buffer_get_parent_buffer_meta(b) \
 726   ((GstParentBufferMeta*)gst_buffer_get_meta((b),GST_PARENT_BUFFER_META_API_TYPE))
 727
 728 GST_API
 729 const GstMetaInfo *gst_parent_buffer_meta_get_info (void);
 730 #define GST_PARENT_BUFFER_META_INFO (gst_parent_buffer_meta_get_info())
 731
 732 /* implementation */
 733
 734 GST_API
 735 GstParentBufferMeta *gst_buffer_add_parent_buffer_meta (GstBuffer *buffer,
 736     GstBuffer *ref);
 737
 738 typedef struct _GstReferenceTimestampMeta GstReferenceTimestampMeta;
 739
 740 /**
 741  * GstReferenceTimestampMeta:
 742  * @parent: the parent #GstMeta structure
 743  * @reference: identifier for the timestamp reference.
 744  * @timestamp: timestamp
 745  * @duration: duration, or %GST_CLOCK_TIME_NONE
 746  *
 747  * #GstReferenceTimestampMeta can be used to attach alternative timestamps and
 748  * possibly durations to a #GstBuffer. These are generally not according to
 749  * the pipeline clock and could be e.g. the NTP timestamp when the media was
 750  * captured.
 751  *
 752  * The reference is stored as a #GstCaps in @reference. Examples of valid
 753  * references would be
 754  *
 755  *  * `timestamp/x-drivername-stream`: for timestamps that are locally
 756  *    generated by some driver named `drivername` when generating the stream,
 757  *    e.g. based on a frame counter
 758  *  * `timestamp/x-ntp, host=pool.ntp.org, port=123`: for timestamps based on a
 759  *    specific NTP server. Note that the host/port parameters might not always
 760  *    be given.
 761  *  * `timestamp/x-ptp, version=IEEE1588-2008, domain=1`: for timestamps based
 762  *    on a given PTP clock.
 763  *  * `timestamp/x-unix`: for timestamps based on the UNIX epoch according to
 764  *    the local clock.
 765  *
 766  * Since: 1.14
 767  */
 768 struct _GstReferenceTimestampMeta
 769 {
 770   GstMeta parent;
 771
 772   /*< public >*/
 773   GstCaps *reference;
 774   GstClockTime timestamp, duration;
 775 };
 776
 777 GST_API
 778 GType gst_reference_timestamp_meta_api_get_type (void);
 779 #define GST_REFERENCE_TIMESTAMP_META_API_TYPE (gst_reference_timestamp_meta_api_get_type())
 780
 781 GST_API
 782 const GstMetaInfo *gst_reference_timestamp_meta_get_info (void);
 783 #define GST_REFERENCE_TIMESTAMP_META_INFO (gst_reference_timestamp_meta_get_info())
 784
 785 /* implementation */
 786
 787 GST_API
 788 GstReferenceTimestampMeta * gst_buffer_add_reference_timestamp_meta (GstBuffer  * buffer,
 789                                                                      GstCaps    * reference,
 790                                                                      GstClockTime timestamp,
 791                                                                      GstClockTime duration);
 792
 793 GST_API
 794 GstReferenceTimestampMeta * gst_buffer_get_reference_timestamp_meta (GstBuffer * buffer,
 795                                                                      GstCaps   * reference);
 796
 797 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBuffer, gst_buffer_unref)
 798
 799 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstBufferPool, gst_object_unref)
 800
 801 /**
 802  * GstBufferMapInfo: (skip):
 803  *
 804  * Alias for #GstMapInfo to be used with g_auto():
 805  * ```c
 806  * void my_func(GstBuffer *buf)
 807  * {
 808  *   g_auto(GstBufferMapInfo) map = GST_MAP_INFO_INIT;
 809  *   if (!gst_buffer_map(buf, &map, GST_MAP_READWRITE))
 810  *     return;
 811  *   ...
 812  *   // No need to call gst_buffer_unmap()
 813  * }
 814  * ```
 815  *
 816  * #GstMapInfo cannot be used with g_auto() because it is ambiguous whether it
 817  * needs to be unmapped using gst_buffer_unmap() or gst_memory_unmap().
 818  *
 819  * See also #GstMemoryMapInfo.
 820  *
 821  * Since: 1.22
 822  */
 823 typedef GstMapInfo GstBufferMapInfo;
 824
 825 static inline void _gst_buffer_map_info_clear(GstBufferMapInfo *info)
 826 {
 827   /* we need to check for NULL, it is possible that we tried to map a buffer
 828    * without memory and we should be able to unmap that fine */
 829   if (G_LIKELY (info->memory)) {
 830     gst_memory_unmap (info->memory, info);
 831     gst_memory_unref (info->memory);
 832   }
 833 }
 834
 835 G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GstBufferMapInfo, _gst_buffer_map_info_clear)
 836
 837 G_END_DECLS
 838
 839 #endif /* __GST_BUFFER_H__ */