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
  29 G_BEGIN_DECLS
  30
  31 typedef struct _GstBuffer GstBuffer;
  32 typedef struct _GstBufferPool GstBufferPool;
  33
  34 extern GType _gst_buffer_type;
  35 extern GType _gst_buffer_pool_type;
  36
  37 #define GST_TYPE_BUFFER                         (_gst_buffer_type)
  38 #define GST_TYPE_BUFFER_POOL                    (_gst_buffer_pool_type)
  39
  40 #define GST_BUFFER(buf)                         ((GstBuffer *)(buf))
  41 #define GST_BUFFER_POOL(pool)                   ((GstBufferPool *)(pool))
  42 #define GST_IS_BUFFER(buf)                      (GST_DATA_TYPE(buf) == GST_TYPE_BUFFER)
  43 #define GST_IS_BUFFER_POOL(buf)                 (GST_DATA_TYPE(buf) == GST_TYPE_BUFFER_POOL)
  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_FORMAT(buf)                  (GST_BUFFER(buf)->format)
  60 #define GST_BUFFER_OFFSET(buf)                  (GST_BUFFER(buf)->offset)
  61 #define GST_BUFFER_BUFFERPOOL(buf)              (GST_BUFFER(buf)->pool)
  62 #define GST_BUFFER_POOL_PRIVATE(buf)            (GST_BUFFER(buf)->pool_private)
  63
  64 typedef enum {
  65   GST_BUFFER_READONLY   = GST_DATA_READONLY,
  66   GST_BUFFER_SUBBUFFER  = GST_DATA_FLAG_LAST,
  67   GST_BUFFER_ORIGINAL,
  68   GST_BUFFER_DONTFREE,
  69   GST_BUFFER_DISCONTINUOUS,
  70   GST_BUFFER_KEY_UNIT,
  71   GST_BUFFER_PREROLL,
  72   GST_BUFFER_FLAG_LAST  = GST_DATA_FLAG_LAST + 8
  73 } GstBufferFlag;
  74
  75 struct _GstBuffer {
  76   GstData                data_type;
  77
  78   /* pointer to data and its size */
  79   guint8                *data;                  /* pointer to buffer data */
  80   guint                  size;                  /* size of buffer data */
  81   guint64                maxsize;               /* max size of this buffer */
  82
  83   /* timestamp */
  84   guint64                timestamp;
  85   /* media specific offset */
  86   guint64                offset;
  87
  88   /* this is a pointer to the buffer pool (if any) */
  89   GstBufferPool         *pool;
  90   /* pointer to pool private data of parent buffer in case of a subbuffer */
  91   gpointer               pool_private;
  92 };
  93
  94 /* bufferpools */
  95
  96 typedef GstBuffer*      (*GstBufferPoolBufferNewFunction)       (GstBufferPool *pool, guint64 offset,
  97                                                                  guint size, gpointer user_data);
  98 typedef GstBuffer*      (*GstBufferPoolBufferCopyFunction)      (GstBufferPool *pool,
  99                                                                  const GstBuffer *buffer,
 100                                                                  gpointer user_data);
 101 typedef void            (*GstBufferPoolBufferFreeFunction)      (GstBufferPool *pool,
 102                                                                  GstBuffer *buffer,
 103                                                                  gpointer user_data);
 104
 105 struct _GstBufferPool {
 106   GstData                               data;
 107
 108   gboolean                              active;
 109
 110   GstBufferPoolBufferNewFunction        buffer_new;
 111   GstBufferPoolBufferCopyFunction       buffer_copy;
 112   GstBufferPoolBufferFreeFunction       buffer_free;
 113
 114   gpointer                              user_data;
 115 };
 116
 117 /* allocation */
 118 GstBuffer*      gst_buffer_new                  (void);
 119 GstBuffer*      gst_buffer_new_and_alloc        (guint size);
 120
 121 /* creating a new buffer from a pool */
 122 GstBuffer*      gst_buffer_new_from_pool        (GstBufferPool *pool,
 123                                                  guint64 offset, guint size);
 124
 125 #define         gst_buffer_set_data(buf, data, size)    \
 126 G_STMT_START {                                          \
 127   GST_BUFFER_DATA (buf) = data;                         \
 128   GST_BUFFER_SIZE (buf) = size;                         \
 129 } G_STMT_END
 130
 131 /* refcounting */
 132 #define         gst_buffer_ref(buf)             GST_BUFFER (gst_data_ref (GST_DATA (buf)))
 133 #define         gst_buffer_ref_by_count(buf,c)  GST_BUFFER (gst_data_ref_by_count (GST_DATA (buf), c))
 134 #define         gst_buffer_unref(buf)           gst_data_unref (GST_DATA (buf))
 135 /* copy buffer */
 136 #define         gst_buffer_copy(buf)            GST_BUFFER (gst_data_copy (GST_DATA (buf)))
 137 #define         gst_buffer_needs_copy_on_write(buf)     GST_BUFFER (gst_data_needs_copy_on_write (GST_DATA (buf)))
 138 #define         gst_buffer_copy_on_write(buf)   GST_BUFFER (gst_data_copy_on_write (GST_DATA (buf)))
 139 #define         gst_buffer_free(buf)            gst_data_free (GST_DATA (buf))
 140
 141 /* creating a subbuffer */
 142 GstBuffer*      gst_buffer_create_sub           (GstBuffer *parent, guint offset, guint size);
 143
 144 /* merge, span, or append two buffers, intelligently */
 145 GstBuffer*      gst_buffer_merge                (GstBuffer *buf1, GstBuffer *buf2);
 146 gboolean        gst_buffer_is_span_fast         (GstBuffer *buf1, GstBuffer *buf2);
 147 GstBuffer*      gst_buffer_span                 (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len);
 148
 149 /* --- private --- */
 150 void            _gst_buffer_initialize          (void);
 151
 152 /* functions used by subclasses and bufferpools */
 153 void            gst_buffer_default_free         (GstBuffer *buffer);
 154 GstBuffer*      gst_buffer_default_copy         (GstBuffer *buffer);
 155
 156 void            gst_buffer_print_stats          (void);
 157
 158
 159 /* creating a new buffer pools */
 160 GstBufferPool*  gst_buffer_pool_new                     (GstDataFreeFunction free,
 161                                                          GstDataCopyFunction copy,
 162                                                          GstBufferPoolBufferNewFunction buffer_new,
 163                                                          GstBufferPoolBufferCopyFunction buffer_copy,
 164                                                          GstBufferPoolBufferFreeFunction buffer_free,
 165                                                          gpointer user_data);
 166
 167 /* function used by subclasses and bufferpools */
 168 void            gst_buffer_pool_default_free            (GstBufferPool *pool);
 169
 170 /* check if pool is usable */
 171 gboolean        gst_buffer_pool_is_active               (GstBufferPool *pool);
 172 void            gst_buffer_pool_set_active              (GstBufferPool *pool, gboolean active);
 173
 174 #define         gst_buffer_pool_ref(pool)               GST_BUFFER_POOL (gst_data_ref (GST_DATA (pool)))
 175 #define         gst_buffer_pool_ref_by_count(pool,c)    GST_BUFFER_POOL (gst_data_ref_by_count (GST_DATA (pool), c))
 176 #define         gst_buffer_pool_unref(pool)             gst_data_unref (GST_DATA (pool))
 177
 178 /* bufferpool operations */
 179 #define         gst_buffer_pool_copy(pool)              GST_BUFFER_POOL (gst_data_copy (GST_DATA (pool)))
 180 #define         gst_buffer_pool_needs_copy_on_write(pool)       GST_BUFFER_POOL (gst_data_needs_copy_on_write (GST_DATA (pool)))
 181 #define         gst_buffer_pool_copy_on_write(pool)     GST_BUFFER_POOL (gst_data_copy_on_write (GST_DATA (pool)))
 182 #define         gst_buffer_pool_free(pool)              gst_data_free (GST_DATA (pool))
 183
 184 void            gst_buffer_pool_set_user_data           (GstBufferPool *pool, gpointer user_data);
 185 gpointer        gst_buffer_pool_get_user_data           (GstBufferPool *pool);
 186
 187 G_END_DECLS
 188
 189
 190 #endif /* __GST_BUFFER_H__ */