"Fossies" - the Fresh Open Source Software Archive

Member "gstreamer-1.16.1/gst/gstbuffer.h" (24 Aug 2019, 29410 Bytes) of package /linux/misc/gstreamer-1.16.1.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "gstbuffer.h" see the Fossies "Dox" file reference documentation and the latest Fossies "Diffs" side-by-side code changes report: 1.16.0_vs_1.16.1.

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