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
  30 G_BEGIN_DECLS
  31
  32 typedef struct _GstBuffer GstBuffer;
  33
  34 typedef void (*GstBufferFreeDataFunc) (GstBuffer *buffer);
  35
  36 #define GST_BUFFER_TRACE_NAME           "GstBuffer"
  37
  38 extern GType _gst_buffer_type;
  39
  40 #define GST_TYPE_BUFFER                         (_gst_buffer_type)
  41
  42 #define GST_BUFFER(buf)                         ((GstBuffer *)(buf))
  43 #define GST_IS_BUFFER(buf)                      (GST_DATA_TYPE(buf) == GST_TYPE_BUFFER)
  44
  45 #define GST_BUFFER_REFCOUNT(buf)                GST_DATA_REFCOUNT(buf)
  46 #define GST_BUFFER_REFCOUNT_VALUE(buf)          GST_DATA_REFCOUNT_VALUE(buf)
  47 #define GST_BUFFER_COPY_FUNC(buf)               GST_DATA_COPY_FUNC(buf)
  48 #define GST_BUFFER_FREE_FUNC(buf)               GST_DATA_FREE_FUNC(buf)
  49
  50 #define GST_BUFFER_FLAGS(buf)                   GST_DATA_FLAGS(buf)
  51 #define GST_BUFFER_FLAG_IS_SET(buf,flag)        GST_DATA_FLAG_IS_SET (buf, flag)
  52 #define GST_BUFFER_FLAG_SET(buf,flag)           GST_DATA_FLAG_SET (buf, flag)
  53 #define GST_BUFFER_FLAG_UNSET(buf,flag)         GST_DATA_FLAG_UNSET (buf, flag)
  54
  55 #define GST_BUFFER_DATA(buf)                    (GST_BUFFER(buf)->data)
  56 #define GST_BUFFER_SIZE(buf)                    (GST_BUFFER(buf)->size)
  57 #define GST_BUFFER_MAXSIZE(buf)                 (GST_BUFFER(buf)->maxsize)
  58 #define GST_BUFFER_TIMESTAMP(buf)               (GST_BUFFER(buf)->timestamp)
  59 #define GST_BUFFER_DURATION(buf)                (GST_BUFFER(buf)->duration)
  60 #define GST_BUFFER_FORMAT(buf)                  (GST_BUFFER(buf)->format)
  61 #define GST_BUFFER_OFFSET(buf)                  (GST_BUFFER(buf)->offset)
  62 #define GST_BUFFER_OFFSET_END(buf)              (GST_BUFFER(buf)->offset_end)
  63 #define GST_BUFFER_FREE_DATA_FUNC(buf)          (GST_BUFFER(buf)->free_data)
  64 #define GST_BUFFER_PRIVATE(buf)                 (GST_BUFFER(buf)->buffer_private)
  65
  66 #define GST_BUFFER_OFFSET_NONE  ((guint64)-1)
  67 #define GST_BUFFER_MAXSIZE_NONE ((guint)0)
  68
  69 #define GST_BUFFER_DURATION_IS_VALID(buffer)    (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))
  70 #define GST_BUFFER_TIMESTAMP_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer)))
  71 #define GST_BUFFER_OFFSET_IS_VALID(buffer)      (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)
  72 #define GST_BUFFER_OFFSET_END_IS_VALID(buffer)  (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)
  73 #define GST_BUFFER_MAXSIZE_IS_VALID(buffer)     (GST_BUFFER_MAXSIZE (buffer) != GST_BUFFER_MAXSIZE_NONE)
  74
  75 typedef enum {
  76   GST_BUFFER_READONLY   = GST_DATA_READONLY,
  77   GST_BUFFER_SUBBUFFER  = GST_DATA_FLAG_LAST,
  78   GST_BUFFER_ORIGINAL,
  79   GST_BUFFER_DONTFREE,
  80   GST_BUFFER_KEY_UNIT,
  81   GST_BUFFER_DONTKEEP,
  82   GST_BUFFER_FLAG_LAST  = GST_DATA_FLAG_LAST + 8
  83 } GstBufferFlag;
  84
  85 struct _GstBuffer {
  86   GstData                data_type;
  87
  88   /* pointer to data and its size */
  89   guint8                *data;                  /* pointer to buffer data */
  90   guint                  size;                  /* size of buffer data */
  91   guint                  maxsize;               /* max size of this buffer */
  92
  93   /* timestamp */
  94   GstClockTime           timestamp;
  95   GstClockTime           duration;
  96
  97   /* media specific offset
  98    * for video frames, this could be the number of frames,
  99    * for audio data, this could be the number of audio samples,
 100    * for file data or compressed data, this could be the number of bytes
 101    * offset_end is the last offset contained in the buffer. The format specifies
 102    * the meaning of both of them exactly.
 103    */
 104   guint64                offset;
 105   guint64                offset_end;
 106
 107   GstBufferFreeDataFunc  free_data;
 108   gpointer               buffer_private;
 109
 110   gpointer _gst_reserved[GST_PADDING];
 111 };
 112
 113 /* allocation */
 114 GType           gst_buffer_get_type             (void);
 115 GstBuffer*      gst_buffer_new                  (void);
 116 GstBuffer*      gst_buffer_new_and_alloc        (guint size);
 117
 118 #define         gst_buffer_set_data(buf, data, size)    \
 119 G_STMT_START {                                          \
 120   GST_BUFFER_DATA (buf) = data;                         \
 121   GST_BUFFER_SIZE (buf) = size;                         \
 122 } G_STMT_END
 123
 124 /* refcounting */
 125 #define         gst_buffer_ref(buf)             GST_BUFFER (gst_data_ref (GST_DATA (buf)))
 126 #define         gst_buffer_ref_by_count(buf,c)  GST_BUFFER (gst_data_ref_by_count (GST_DATA (buf), c))
 127 #define         gst_buffer_unref(buf)           gst_data_unref (GST_DATA (buf))
 128 /* copy buffer */
 129 void            gst_buffer_stamp                (GstBuffer *dest, const GstBuffer *src);
 130 #define         gst_buffer_copy(buf)            GST_BUFFER (gst_data_copy (GST_DATA (buf)))
 131 #define         gst_buffer_is_writable(buf)     gst_data_is_writable (GST_DATA (buf))
 132 #define         gst_buffer_copy_on_write(buf)   GST_BUFFER (gst_data_copy_on_write (GST_DATA (buf)))
 133 #define         gst_buffer_free(buf)            gst_data_free (GST_DATA (buf))
 134
 135 /* creating a subbuffer */
 136 GstBuffer*      gst_buffer_create_sub           (GstBuffer *parent, guint offset, guint size);
 137
 138 /* merge, span, or append two buffers, intelligently */
 139 GstBuffer*      gst_buffer_merge                (GstBuffer *buf1, GstBuffer *buf2);
 140 gboolean        gst_buffer_is_span_fast         (GstBuffer *buf1, GstBuffer *buf2);
 141 GstBuffer*      gst_buffer_span                 (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len);
 142
 143 /* --- private --- */
 144 void            _gst_buffer_initialize          (void);
 145
 146 void            gst_buffer_default_free         (GstBuffer *buffer);
 147 GstBuffer*      gst_buffer_default_copy         (GstBuffer *buffer);
 148
 149 G_END_DECLS
 150
 151 #endif /* __GST_BUFFER_H__ */