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/gstminiobject.h>
  28 #include <gst/gstclock.h>
  29 #include <gst/gstcaps.h>
  30
  31 G_BEGIN_DECLS
  32
  33 typedef struct _GstBuffer GstBuffer;
  34 typedef struct _GstBufferClass GstBufferClass;
  35
  36 /**
  37  * GST_BUFFER_TRACE_NAME:
  38  *
  39  * The name used for tracing memory allocations.
  40  */
  41 #define GST_BUFFER_TRACE_NAME           "GstBuffer"
  42
  43 #define GST_TYPE_BUFFER                         (gst_buffer_get_type())
  44 #define GST_IS_BUFFER(obj)                      (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_BUFFER))
  45 #define GST_IS_BUFFER_CLASS(klass)              (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_BUFFER))
  46 #define GST_BUFFER_GET_CLASS(obj)               (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_BUFFER, GstBufferClass))
  47 #define GST_BUFFER(obj)                         (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_BUFFER, GstBuffer))
  48 #define GST_BUFFER_CLASS(klass)                 (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_BUFFER, GstBufferClass))
  49 #define GST_BUFFER_CAST(obj)                    ((GstBuffer *)(obj))
  50
  51 /**
  52  * GST_BUFFER_FLAGS:
  53  * @buf: a #GstBuffer to retrieve the flags from.
  54  *
  55  * Gets the #GstBufferFlag flags from this buffer.
  56  */
  57 #define GST_BUFFER_FLAGS(buf)                   GST_MINI_OBJECT_FLAGS(buf)
  58 /**
  59  * GST_BUFFER_FLAG_IS_SET:
  60  * @buf: a #GstBuffer to query flags of.
  61  * @flag: the #GstBufferFlag to check.
  62  *
  63  * Gives the status of a given flag of a buffer.
  64  */
  65 #define GST_BUFFER_FLAG_IS_SET(buf,flag)        GST_MINI_OBJECT_FLAG_IS_SET (buf, flag)
  66 /**
  67  * GST_BUFFER_FLAG_SET:
  68  * @buf: a #GstBuffer to modify flags of.
  69  * @flag: the #GstBufferFlag to set.
  70  *
  71  * Sets a buffer flag.
  72  */
  73 #define GST_BUFFER_FLAG_SET(buf,flag)           GST_MINI_OBJECT_FLAG_SET (buf, flag)
  74 /**
  75  * GST_BUFFER_FLAG_UNSET:
  76  * @buf: a #GstBuffer to modify flags of.
  77  * @flag: the #GstBufferFlag to clear.
  78  *
  79  * Clears a buffer flag.
  80  */
  81 #define GST_BUFFER_FLAG_UNSET(buf,flag)         GST_MINI_OBJECT_FLAG_UNSET (buf, flag)
  82
  83 /**
  84  * GST_BUFFER_DATA:
  85  * @buf: a #GstBuffer to get data pointer of.
  86  *
  87  * Retrieves a pointer to the data element of this buffer.
  88  */
  89 #define GST_BUFFER_DATA(buf)                    (GST_BUFFER_CAST(buf)->data)
  90 /**
  91  * GST_BUFFER_SIZE:
  92  * @buf: a #GstBuffer to get data size of.
  93  *
  94  * Gets the size of the data in this buffer.
  95  */
  96 #define GST_BUFFER_SIZE(buf)                    (GST_BUFFER_CAST(buf)->size)
  97 /**
  98  * GST_BUFFER_TIMESTAMP:
  99  * @buf: a #GstBuffer to get the timestamp of.:
 100  *
 101  * Gets the timestamp for this buffer.
 102  */
 103 #define GST_BUFFER_TIMESTAMP(buf)               (GST_BUFFER_CAST(buf)->timestamp)
 104 /**
 105  * GST_BUFFER_DURATION:
 106  * @buf: a #GstBuffer to get the duration from.
 107  *
 108  * Gets the duration in nanoseconds of the data in the buffer.
 109  * Value will be %GST_CLOCK_TIME_NONE if the duration is unknown.
 110  */
 111 #define GST_BUFFER_DURATION(buf)                (GST_BUFFER_CAST(buf)->duration)
 112 /**
 113  * GST_BUFFER_CAPS:
 114  * @buf: a #GstBuffer to get the caps of.
 115  *
 116  * Gets the caps for this buffer.
 117  */
 118 #define GST_BUFFER_CAPS(buf)                    (GST_BUFFER_CAST(buf)->caps)
 119 /**
 120  * GST_BUFFER_OFFSET:
 121  * @buf: a #GstBuffer to get the offset of.
 122  *
 123  * Gets the offset in the source file of the beginning of this buffer.
 124  */
 125 #define GST_BUFFER_OFFSET(buf)                  (GST_BUFFER_CAST(buf)->offset)
 126 /**
 127  * GST_BUFFER_OFFSET_END:
 128  * @buf: a #GstBuffer to get the offset of.
 129  *
 130  * Gets the offset in the source file of the end of this buffer.
 131  */
 132 #define GST_BUFFER_OFFSET_END(buf)              (GST_BUFFER_CAST(buf)->offset_end)
 133 /**
 134  * GST_BUFFER_MALLOCDATA:
 135  * @buf: a #GstBuffer to get access to the malloc_data field
 136  *
 137  * If the buffers data should be automatically freed by buffer management at the
 138  * end of the buffers lifecycle, also set the data to the mallocdata field.
 139  */
 140 #define GST_BUFFER_MALLOCDATA(buf)              (GST_BUFFER_CAST(buf)->malloc_data)
 141
 142 /**
 143  * GST_BUFFER_OFFSET_NONE:
 144  *
 145  * Constant for no-offset return results.
 146  */
 147 #define GST_BUFFER_OFFSET_NONE  ((guint64)-1)
 148
 149 /**
 150  * GST_BUFFER_DURATION_IS_VALID:
 151  * @buffer: the #GstBuffer to check for the duration
 152  *
 153  * Tests if the duration is known.
 154  */
 155 #define GST_BUFFER_DURATION_IS_VALID(buffer)    (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))
 156 /**
 157  * GST_BUFFER_TIMESTAMP_IS_VALID:
 158  * @buffer: the #GstBuffer to check for the timestamp
 159  *
 160  * Tests if the timestamp is known.
 161  */
 162 #define GST_BUFFER_TIMESTAMP_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer)))
 163 /**
 164  * GST_BUFFER_OFFSET_IS_VALID:
 165  * @buffer: the #GstBuffer to check for the start offset
 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: the #GstBuffer to check for the end offset
 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 /**
 179  * GstBufferFlag:
 180  * @GST_BUFFER_FLAG_READONLY: the buffer is read-only.
 181  * @GST_BUFFER_FLAG_ORIGINAL: buffer is not a copy of another buffer.
 182  * @GST_BUFFER_FLAG_PREROLL: the buffer is part of a preroll and should not be
 183  * displayed.
 184  * @GST_BUFFER_FLAG_DISCONT: the buffer marks a discontinuity in the stream.
 185  * @GST_BUFFER_FLAG_IN_CAPS: the buffer has been added as a field in a #GstCaps.
 186  * @GST_BUFFER_FLAG_GAP: the buffer has been created to fill a gap in the stream.
 187  * @GST_BUFFER_FLAG_DELTA_UNIT: this unit cannot be decoded independently.
 188  * Since 0.8.5
 189  * @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
 190  *
 191  * A set of buffer flags used to describe properties of a #GstBuffer.
 192  */
 193 typedef enum {
 194   GST_BUFFER_FLAG_READONLY = GST_MINI_OBJECT_FLAG_READONLY,
 195   GST_BUFFER_FLAG_ORIGINAL = (GST_MINI_OBJECT_FLAG_LAST << 0),          /* original data, not copied, not currently used  */
 196   GST_BUFFER_FLAG_PREROLL = (GST_MINI_OBJECT_FLAG_LAST << 1),           /* sample should not be displayed */
 197   GST_BUFFER_FLAG_DISCONT = (GST_MINI_OBJECT_FLAG_LAST << 2),           /* buffer is first after discontinuity in the stream */
 198   GST_BUFFER_FLAG_IN_CAPS = (GST_MINI_OBJECT_FLAG_LAST << 3),           /* buffer is also part of caps */
 199   GST_BUFFER_FLAG_GAP = (GST_MINI_OBJECT_FLAG_LAST << 4),               /* buffer has been created to fill a gap in the stream */
 200   GST_BUFFER_FLAG_DELTA_UNIT = (GST_MINI_OBJECT_FLAG_LAST << 5),        /* can't be used as sync point in stream */
 201   GST_BUFFER_FLAG_LAST = (GST_MINI_OBJECT_FLAG_LAST << 8)
 202 } GstBufferFlag;
 203
 204 struct _GstBuffer {
 205   GstMiniObject          mini_object;
 206
 207   /*< public >*/ /* with COW */
 208   /* pointer to data and its size */
 209   guint8                *data;                  /* pointer to buffer data */
 210   guint                  size;                  /* size of buffer data */
 211
 212   /* timestamp */
 213   GstClockTime           timestamp;
 214   GstClockTime           duration;
 215
 216   /* the media type of this buffer */
 217   GstCaps               *caps;
 218
 219   /* media specific offset
 220    * for video frames, this could be the number of frames,
 221    * for audio data, this could be the number of audio samples,
 222    * for file data or compressed data, this could be the number of bytes
 223    * offset_end is the last offset contained in the buffer. The format specifies
 224    * the meaning of both of them exactly.
 225    */
 226   guint64                offset;
 227   guint64                offset_end;
 228
 229   guint8                *malloc_data;
 230
 231   /*< private >*/
 232   gpointer _gst_reserved[GST_PADDING];
 233 };
 234
 235 struct _GstBufferClass {
 236   GstMiniObjectClass    mini_object_class;
 237
 238 };
 239
 240 /* allocation */
 241 GType           gst_buffer_get_type             (void);
 242 GstBuffer*      gst_buffer_new                  (void);
 243 GstBuffer*      gst_buffer_new_and_alloc        (guint size);
 244
 245 /**
 246  * gst_buffer_set_data:
 247  * @buf: The buffer to modify
 248  * @data: The data to set on the buffer
 249  * @size: The size to set on the buffer
 250  *
 251  * A convenience function to set the data and size on a buffer.
 252  */
 253 #define         gst_buffer_set_data(buf, data, size)    \
 254 G_STMT_START {                                          \
 255   GST_BUFFER_DATA (buf) = data;                         \
 256   GST_BUFFER_SIZE (buf) = size;                         \
 257 } G_STMT_END
 258
 259 /* refcounting */
 260 /**
 261  * gst_buffer_ref:
 262  * @buf: a #GstBuffer to increase the refcount of.
 263  *
 264  * Increases the refcount of the given buffer by one.
 265  */
 266 #define         gst_buffer_ref(buf)             GST_BUFFER_CAST (gst_mini_object_ref (GST_MINI_OBJECT (buf)))
 267 /**
 268  * gst_buffer_unref:
 269  * @buf: a #GstBuffer to decrease the refcount of.
 270  *
 271  * Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
 272  * will be freed.
 273  */
 274 #define         gst_buffer_unref(buf)           gst_mini_object_unref (GST_MINI_OBJECT (buf))
 275
 276 /* copy buffer */
 277 /**
 278  * gst_buffer_copy:
 279  * @buf: a #GstBuffer to copy.
 280  *
 281  * Copies the given buffer using the copy function of the parent #GstData
 282  * structure.
 283  */
 284 #define         gst_buffer_copy(buf)            GST_BUFFER_CAST (gst_mini_object_copy (GST_MINI_OBJECT (buf)))
 285 /**
 286  * gst_buffer_is_writable:
 287  * @buf: a #GstBuffer to check
 288  *
 289  * Tests if you can safely write data into a buffer's data array.
 290  */
 291 #define         gst_buffer_is_writable(buf)     gst_mini_object_is_writable (GST_MINI_OBJECT (buf))
 292 /**
 293  * gst_buffer_make_writable:
 294  * @buf: a #GstBuffer to make writable
 295  *
 296  * Makes a writable buffer from the given buffer.
 297  */
 298 #define         gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT (buf)))
 299
 300 /**
 301  * gst_buffer_replace:
 302  * @obuf: a #GstBuffer to receive the data
 303  * @nbuf: a #GstBuffer to take the data from
 304  *
 305  * Replaces the data in @obuf with the one in @nbuf
 306  */
 307 #define         gst_buffer_replace(obuf,nbuf)   gst_mini_object_replace ((GstMiniObject **)(obuf), GST_MINI_OBJECT (nbuf))
 308
 309 GstCaps*        gst_buffer_get_caps             (GstBuffer *buffer);
 310 void            gst_buffer_set_caps             (GstBuffer *buffer, GstCaps *caps);
 311
 312 /* creating a subbuffer */
 313 GstBuffer*      gst_buffer_create_sub           (GstBuffer *parent, guint offset, guint size);
 314
 315 /* span, two buffers, intelligently */
 316 gboolean        gst_buffer_is_span_fast         (GstBuffer *buf1, GstBuffer *buf2);
 317 GstBuffer*      gst_buffer_span                 (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len);
 318
 319 #define         gst_value_set_buffer(v,b)       gst_value_set_mini_object(v, GST_MINI_OBJECT(b))
 320 #define         gst_value_take_buffer(v,b)      gst_value_take_mini_object(v, GST_MINI_OBJECT(b))
 321 #define         gst_value_get_buffer(v)         GST_BUFFER (gst_value_get_mini_object(v))
 322
 323 /* --- protected --- */
 324 void            _gst_buffer_initialize          (void);
 325
 326 G_END_DECLS
 327
 328 #endif /* __GST_BUFFER_H__ */