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., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23
  24 #ifndef __GST_BUFFER_H__
  25 #define __GST_BUFFER_H__
  26
  27 #include <gst/gstdata.h>
  28 #include <gst/gstclock.h>
  29 #include <gst/gstcaps.h>
  30
  31 G_BEGIN_DECLS
  32
  33 typedef struct _GstBuffer GstBuffer;
  34
  35 typedef void (*GstBufferFreeDataFunc) (GstBuffer *buffer);
  36
  37 #define GST_BUFFER_TRACE_NAME           "GstBuffer"
  38
  39 extern GType _gst_buffer_type;
  40
  41 #define GST_TYPE_BUFFER                         (gst_buffer_get_type())
  42
  43 #define GST_BUFFER(buf)                         ((GstBuffer *)(buf))
  44 #define GST_IS_BUFFER(buf)                      (GST_DATA_TYPE(buf) == GST_TYPE_BUFFER)
  45
  46 #define GST_BUFFER_REFCOUNT(buf)                GST_DATA_REFCOUNT(buf)
  47 #define GST_BUFFER_REFCOUNT_VALUE(buf)          GST_DATA_REFCOUNT_VALUE(buf)
  48 #define GST_BUFFER_COPY_FUNC(buf)               GST_DATA_COPY_FUNC(buf)
  49 #define GST_BUFFER_FREE_FUNC(buf)               GST_DATA_FREE_FUNC(buf)
  50
  51 #define GST_BUFFER_FLAGS(buf)                   GST_DATA_FLAGS(buf)
  52 #define GST_BUFFER_FLAG_IS_SET(buf,flag)        GST_DATA_FLAG_IS_SET (buf, flag)
  53 #define GST_BUFFER_FLAG_SET(buf,flag)           GST_DATA_FLAG_SET (buf, flag)
  54 #define GST_BUFFER_FLAG_UNSET(buf,flag)         GST_DATA_FLAG_UNSET (buf, flag)
  55
  56 #define GST_BUFFER_DATA(buf)                    (GST_BUFFER(buf)->data)
  57 #define GST_BUFFER_SIZE(buf)                    (GST_BUFFER(buf)->size)
  58 #define GST_BUFFER_MAXSIZE(buf)                 (GST_BUFFER(buf)->maxsize)
  59 #define GST_BUFFER_TIMESTAMP(buf)               (GST_BUFFER(buf)->timestamp)
  60 #define GST_BUFFER_DURATION(buf)                (GST_BUFFER(buf)->duration)
  61 #define GST_BUFFER_CAPS(buf)                    (GST_BUFFER(buf)->caps)
  62 #define GST_BUFFER_OFFSET(buf)                  (GST_BUFFER(buf)->offset)
  63 #define GST_BUFFER_OFFSET_END(buf)              (GST_BUFFER(buf)->offset_end)
  64 #define GST_BUFFER_FREE_DATA_FUNC(buf)          (GST_BUFFER(buf)->free_data)
  65 #define GST_BUFFER_PRIVATE(buf)                 (GST_BUFFER(buf)->buffer_private)
  66
  67 #define GST_BUFFER_OFFSET_NONE  ((guint64)-1)
  68 #define GST_BUFFER_MAXSIZE_NONE ((guint)0)
  69
  70 #define GST_BUFFER_DURATION_IS_VALID(buffer)    (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))
  71 #define GST_BUFFER_TIMESTAMP_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer)))
  72 #define GST_BUFFER_OFFSET_IS_VALID(buffer)      (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)
  73 #define GST_BUFFER_OFFSET_END_IS_VALID(buffer)  (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)
  74 #define GST_BUFFER_MAXSIZE_IS_VALID(buffer)     (GST_BUFFER_MAXSIZE (buffer) != GST_BUFFER_MAXSIZE_NONE)
  75
  76 /**
  77  * GstBufferFlag:
  78  * @GST_BUFFER_READONLY: the buffer is read-only.
  79  * @GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be
  80  * found with the GST_BUFFER_POOL_PRIVATE() macro.
  81  * @GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer.
  82  * @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is
  83  * unreferenced.
  84  * @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
  85  * decoded independently of other buffers.
  86  * This flag has been deprecated, see #GST_BUFFER_DELTA_UNIT.
  87  * @GST_BUFFER_DONTKEEP: the buffer should not be ref()ed, but copied instead
  88  * before doing anything with it (for specially allocated hw buffers and such)
  89  * @GST_BUFFER_IN_CAPS: the buffer has been added as a field in a #GstCaps.
  90  * @GST_BUFFER_GAP: the buffer has been created to fill a gap in the stream.
  91  * @GST_BUFFER_DELTA_UNIT: this unit cannot be decoded independently.
  92  * Since 0.8.5
  93  * @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
  94  *
  95  * A set of buffer flags used to describe properties of a #GstBuffer.
  96  */
  97 typedef enum {
  98   GST_BUFFER_READONLY   = GST_DATA_READONLY,
  99   GST_BUFFER_SUBBUFFER  = GST_DATA_FLAG_LAST,
 100   GST_BUFFER_ORIGINAL,          /* original data, not copied, not currently used  */
 101   GST_BUFFER_DONTFREE,          /* buffer data is managed by somebody else and cannot be freeed */
 102   GST_BUFFER_PREROLL,           /* sample should not be displayed */
 103   GST_BUFFER_DISCONT,           /* buffer is first after discontinuity in the stream */
 104   GST_BUFFER_IN_CAPS,           /* buffer is also part of caps */
 105   GST_BUFFER_GAP,               /* buffer has been created to fill a gap in the stream */
 106   GST_BUFFER_DELTA_UNIT,        /* can't be used as sync point in stream */
 107   GST_BUFFER_FLAG_LAST  = GST_DATA_FLAG_LAST + 8
 108 } GstBufferFlag;
 109
 110 struct _GstBuffer {
 111   GstData                data_type;
 112
 113   /*< public >*/ /* with COW */
 114   /* pointer to data and its size */
 115   guint8                *data;                  /* pointer to buffer data */
 116   guint                  size;                  /* size of buffer data */
 117   guint                  maxsize;               /* max size of this buffer */
 118
 119   /* timestamp */
 120   GstClockTime           timestamp;
 121   GstClockTime           duration;
 122
 123   /* the media type of this buffer */
 124   GstCaps               *caps;
 125
 126   /* media specific offset
 127    * for video frames, this could be the number of frames,
 128    * for audio data, this could be the number of audio samples,
 129    * for file data or compressed data, this could be the number of bytes
 130    * offset_end is the last offset contained in the buffer. The format specifies
 131    * the meaning of both of them exactly.
 132    */
 133   guint64                offset;
 134   guint64                offset_end;
 135
 136   /*< protected >*/
 137   GstBufferFreeDataFunc  free_data;
 138   gpointer               buffer_private;
 139
 140   /*< private >*/
 141   gpointer _gst_reserved[GST_PADDING];
 142 };
 143
 144 /* allocation */
 145 GType           gst_buffer_get_type             (void);
 146 GstBuffer*      gst_buffer_new                  (void);
 147 GstBuffer*      gst_buffer_new_and_alloc        (guint size);
 148
 149 #define         gst_buffer_set_data(buf, data, size)    \
 150 G_STMT_START {                                          \
 151   GST_BUFFER_DATA (buf) = data;                         \
 152   GST_BUFFER_SIZE (buf) = size;                         \
 153 } G_STMT_END
 154
 155 /* refcounting */
 156 #define         gst_buffer_ref(buf)             GST_BUFFER (gst_data_ref (GST_DATA (buf)))
 157 #define         gst_buffer_ref_by_count(buf,c)  GST_BUFFER (gst_data_ref_by_count (GST_DATA (buf), c))
 158 #define         gst_buffer_unref(buf)           gst_data_unref (GST_DATA (buf))
 159 /* copy buffer */
 160 #define         gst_buffer_copy(buf)            GST_BUFFER (gst_data_copy (GST_DATA (buf)))
 161 #define         gst_buffer_is_writable(buf)     gst_data_is_writable (GST_DATA (buf))
 162 #define         gst_buffer_copy_on_write(buf)   GST_BUFFER (gst_data_copy_on_write (GST_DATA (buf)))
 163
 164 GstCaps*        gst_buffer_get_caps             (GstBuffer *buffer);
 165 void            gst_buffer_set_caps             (GstBuffer *buffer, GstCaps *caps);
 166
 167 /* creating a subbuffer */
 168 GstBuffer*      gst_buffer_create_sub           (GstBuffer *parent, guint offset, guint size);
 169
 170 /* span, two buffers, intelligently */
 171 gboolean        gst_buffer_is_span_fast         (GstBuffer *buf1, GstBuffer *buf2);
 172 GstBuffer*      gst_buffer_span                 (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len);
 173
 174 /* --- protected --- */
 175 void            _gst_buffer_initialize          (void);
 176
 177 void            gst_buffer_default_free         (GstBuffer *buffer);
 178 GstBuffer*      gst_buffer_default_copy         (GstBuffer *buffer);
 179
 180 G_END_DECLS
 181
 182 #endif /* __GST_BUFFER_H__ */