gst/gstmemory.h

   1 /* GStreamer
   2  * Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
   3  *
   4  * gstmemory.h: Header for memory blocks
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22
  23 #ifndef __GST_MEMORY_H__
  24 #define __GST_MEMORY_H__
  25
  26 #include <gst/gstconfig.h>
  27
  28 #include <glib-object.h>
  29
  30 G_BEGIN_DECLS
  31
  32 #define GST_TYPE_MEMORY (gst_memory_get_type())
  33 GType gst_memory_get_type(void);
  34
  35 typedef struct _GstMemory GstMemory;
  36 typedef struct _GstMemoryInfo GstMemoryInfo;
  37 typedef struct _GstAllocator GstAllocator;
  38
  39 GST_EXPORT gsize gst_memory_alignment;
  40
  41 /**
  42  * GstMemoryFlags:
  43  * @GST_MEMORY_FLAG_READONLY: memory is readonly. It is not allowed to map the
  44  * memory with #GST_MAP_WRITE.
  45  * @GST_MEMORY_FLAG_NO_SHARE: memory must not be shared. Copies will have to be
  46  * made when this memory needs to be shared between buffers.
  47  * @GST_MEMORY_FLAG_LAST: first flag that can be used for custom purposes
  48  *
  49  * Flags for wrapped memory.
  50  */
  51 typedef enum {
  52   GST_MEMORY_FLAG_READONLY = (1 << 0),
  53   GST_MEMORY_FLAG_NO_SHARE = (1 << 1),
  54
  55   GST_MEMORY_FLAG_LAST     = (1 << 16)
  56 } GstMemoryFlags;
  57
  58 /**
  59  * GstMemory:
  60  * @allocator: pointer to the #GstAllocator
  61  * @flags: memory flags
  62  * @refcount: refcount
  63  * @parent: parent memory block
  64  * @state: private state
  65  * @maxsize: the maximum size allocated
  66  * @align: the alignment of the memory
  67  * @offset: the offset where valid data starts
  68  * @size: the size of valid data
  69  *
  70  * Base structure for memory implementations. Custom memory will put this structure
  71  * as the first member of their structure.
  72  */
  73 struct _GstMemory {
  74   const GstAllocator *allocator;
  75
  76   GstMemoryFlags  flags;
  77   gint            refcount;
  78   GstMemory      *parent;
  79   volatile gint   state;
  80   gsize           maxsize;
  81   gsize           align;
  82   gsize           offset;
  83   gsize           size;
  84 };
  85
  86 /**
  87  * GstMapFlags:
  88  * @GST_MAP_READ: map for read access
  89  * @GST_MAP_WRITE: map for write access
  90  * @GST_MAP_FLAG_LAST: first flag that can be used for custom purposes
  91  *
  92  * Flags used when mapping memory
  93  */
  94 typedef enum {
  95   GST_MAP_READ      = (1 << 0),
  96   GST_MAP_WRITE     = (1 << 1),
  97
  98   GST_MAP_FLAG_LAST = (1 << 16)
  99 } GstMapFlags;
 100
 101 /**
 102  * GST_MAP_READWRITE:
 103  *
 104  * Map for readwrite access
 105  */
 106 #define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)
 107
 108 /**
 109  * GST_ALLOCATOR_SYSMEM:
 110  *
 111  * The allocator name for the default system memory allocator
 112  */
 113 #define GST_ALLOCATOR_SYSMEM   "SystemMemory"
 114
 115 /**
 116  * GstMemoryAllocFunction:
 117  * @allocator: a #GstAllocator
 118  * @maxsize: the maxsize
 119  * @align: the alignment
 120  * @user_data: user data
 121  *
 122  * Allocate a new #GstMemory from @allocator that can hold at least @maxsize bytes
 123  * and is aligned to (@align + 1) bytes.
 124  *
 125  * @user_data is the data that was used when registering @allocator.
 126  *
 127  * Returns: a newly allocated #GstMemory. Free with gst_memory_unref()
 128  */
 129 typedef GstMemory *  (*GstMemoryAllocFunction)  (const GstAllocator *allocator,
 130                                                  gsize maxsize, gsize align,
 131                                                  gpointer user_data);
 132
 133 /**
 134  * GstMemoryMapFunction:
 135  * @mem: a #GstMemory
 136  * @maxsize: size to map
 137  * @flags: access mode for the memory
 138  *
 139  * Get the memory of @mem that can be accessed according to the mode specified
 140  * in @flags. The function should return a pointer that contains at least
 141  * @maxsize bytes.
 142  *
 143  * Returns: a pointer to memory of which at least @maxsize bytes can be
 144  * accessed according to the access pattern in @flags.
 145  */
 146 typedef gpointer    (*GstMemoryMapFunction)       (GstMemory *mem, gsize maxsize, GstMapFlags flags);
 147
 148 /**
 149  * GstMemoryUnmapFunction:
 150  * @mem: a #GstMemory
 151  *
 152  * Return the pointer previously retrieved with gst_memory_map().
 153  *
 154  * Returns: %TRUE on success.
 155  */
 156 typedef void        (*GstMemoryUnmapFunction)     (GstMemory *mem);
 157
 158 /**
 159  * GstMemoryFreeFunction:
 160  * @mem: a #GstMemory
 161  *
 162  * Free the memory used by @mem. This function is usually called when the
 163  * refcount of the @mem has reached 0.
 164  */
 165 typedef void        (*GstMemoryFreeFunction)      (GstMemory *mem);
 166
 167 /**
 168  * GstMemoryCopyFunction:
 169  * @mem: a #GstMemory
 170  * @offset: an offset
 171  * @size: a size or -1
 172  *
 173  * Copy @size bytes from @mem starting at @offset and return them wrapped in a
 174  * new GstMemory object.
 175  * If @size is set to -1, all bytes starting at @offset are copied.
 176  *
 177  * Returns: a new #GstMemory object wrapping a copy of the requested region in
 178  * @mem.
 179  */
 180 typedef GstMemory * (*GstMemoryCopyFunction)      (GstMemory *mem, gssize offset, gssize size);
 181
 182 /**
 183  * GstMemoryShareFunction:
 184  * @mem: a #GstMemory
 185  * @offset: an offset
 186  * @size: a size or -1
 187  *
 188  * Share @size bytes from @mem starting at @offset and return them wrapped in a
 189  * new GstMemory object. If @size is set to -1, all bytes starting at @offset are
 190  * shared. This function does not make a copy of the bytes in @mem.
 191  *
 192  * Returns: a new #GstMemory object sharing the requested region in @mem.
 193  */
 194 typedef GstMemory * (*GstMemoryShareFunction)     (GstMemory *mem, gssize offset, gssize size);
 195
 196 /**
 197  * GstMemoryIsSpanFunction:
 198  * @mem1: a #GstMemory
 199  * @mem2: a #GstMemory
 200  * @offset: a result offset
 201  *
 202  * Check if @mem1 and @mem2 occupy contiguous memory and return the offset of
 203  * @mem1 in the parent buffer in @offset.
 204  *
 205  * Returns: %TRUE if @mem1 and @mem2 are in contiguous memory.
 206  */
 207 typedef gboolean    (*GstMemoryIsSpanFunction)    (GstMemory *mem1, GstMemory *mem2, gsize *offset);
 208
 209 /**
 210  * GstMemoryInfo:
 211  * @alloc: the implementation of the GstMemoryAllocFunction
 212  * @map: the implementation of the GstMemoryMapFunction
 213  * @unmap: the implementation of the GstMemoryUnmapFunction
 214  * @free: the implementation of the GstMemoryFreeFunction
 215  * @copy: the implementation of the GstMemoryCopyFunction
 216  * @share: the implementation of the GstMemoryShareFunction
 217  * @is_span: the implementation of the GstMemoryIsSpanFunction
 218  * @user_data: generic user data for the allocator
 219  *
 220  * The #GstMemoryInfo is used to register new memory allocators and contain
 221  * the implementations for various memory operations.
 222  */
 223 struct _GstMemoryInfo {
 224   GstMemoryAllocFunction    alloc;
 225   GstMemoryMapFunction      map;
 226   GstMemoryUnmapFunction    unmap;
 227   GstMemoryFreeFunction     free;
 228
 229   GstMemoryCopyFunction     copy;
 230   GstMemoryShareFunction    share;
 231   GstMemoryIsSpanFunction   is_span;
 232
 233   gpointer user_data;
 234
 235   /*< private >*/
 236   gpointer _gst_reserved[GST_PADDING];
 237 };
 238
 239 /* allocators */
 240 const GstAllocator *  gst_allocator_register    (const gchar *name, const GstMemoryInfo *info);
 241 const GstAllocator *  gst_allocator_find        (const gchar *name);
 242
 243 void                  gst_allocator_set_default (const GstAllocator * allocator);
 244
 245 /* allocating memory blocks */
 246 GstMemory * gst_allocator_alloc        (const GstAllocator * allocator,
 247                                         gsize maxsize, gsize align);
 248
 249 GstMemory * gst_memory_new_wrapped     (GstMemoryFlags flags, gpointer data, GFreeFunc free_func,
 250                                         gsize maxsize, gsize offset, gsize size);
 251
 252 /* refcounting */
 253 GstMemory * gst_memory_ref         (GstMemory *mem);
 254 void        gst_memory_unref       (GstMemory *mem);
 255
 256 /* getting/setting memory properties */
 257 gsize       gst_memory_get_sizes   (GstMemory *mem, gsize *offset, gsize *maxsize);
 258 void        gst_memory_resize      (GstMemory *mem, gssize offset, gsize size);
 259
 260 /* retrieving data */
 261 gboolean    gst_memory_is_writable (GstMemory *mem);
 262
 263 gpointer    gst_memory_map         (GstMemory *mem, gsize *size, gsize *maxsize,
 264                                     GstMapFlags flags);
 265 void        gst_memory_unmap       (GstMemory *mem);
 266
 267 /* copy and subregions */
 268 GstMemory * gst_memory_copy        (GstMemory *mem, gssize offset, gssize size);
 269 GstMemory * gst_memory_share       (GstMemory *mem, gssize offset, gssize size);
 270
 271 /* span memory */
 272 gboolean    gst_memory_is_span     (GstMemory *mem1, GstMemory *mem2, gsize *offset);
 273
 274 G_END_DECLS
 275
 276 #endif /* __GST_MEMORY_H__ */