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 typedef struct _GstMemory GstMemory;
  33 typedef struct _GstMemoryInfo GstMemoryInfo;
  34 typedef struct _GstAllocator GstAllocator;
  35
  36 extern gsize gst_memory_alignment;
  37
  38 /**
  39  * GstMemoryFlags:
  40  * @GST_MEMORY_FLAG_READONLY: memory is readonly. It is not allowed to map the
  41  * memory with #GST_MAP_WRITE.
  42  * @GST_MEMORY_FLAG_NO_SHARE: memory must not be shared. Copies will have to be
  43  * made when this memory needs to be shared between buffers.
  44  * @GST_MEMORY_FLAG_LAST: first flag that can be used for custom purposes
  45  *
  46  * Flags for wrapped memory.
  47  */
  48 typedef enum {
  49   GST_MEMORY_FLAG_READONLY = (1 << 0),
  50   GST_MEMORY_FLAG_NO_SHARE = (1 << 1),
  51
  52   GST_MEMORY_FLAG_LAST = (1 << 24)
  53 } GstMemoryFlags;
  54
  55 /**
  56  * GST_MEMORY_IS_WRITABLE:
  57  * @mem: a #GstMemory
  58  *
  59  * Check if @mem is writable.
  60  */
  61 #define GST_MEMORY_IS_WRITABLE(mem) (((mem)->refcount == 1) && \
  62     (((mem)->parent == NULL) || ((mem)->parent->refcount == 1)) && \
  63     (((mem)->flags & GST_MEMORY_FLAG_READONLY) == 0))
  64
  65 /**
  66  * GstMemory:
  67  * @allocator: pointer to the #GstAllocator
  68  * @flags: memory flags
  69  * @refcount: refcount
  70  * @parent: parent memory block
  71  *
  72  * Base structure for memory implementations. Custom memory will put this structure
  73  * as the first member of their structure.
  74  */
  75 struct _GstMemory {
  76   const GstAllocator *allocator;
  77
  78   GstMemoryFlags  flags;
  79   gint            refcount;
  80   GstMemory      *parent;
  81 };
  82
  83 /**
  84  * GstMapFlags:
  85  * @GST_MAP_READ: map for read access
  86  * @GST_MAP_WRITE: map for write access
  87  *
  88  * Flags used when mapping memory
  89  */
  90 typedef enum {
  91   GST_MAP_READ =  (1 << 0),
  92   GST_MAP_WRITE = (1 << 1),
  93 } GstMapFlags;
  94
  95 /**
  96  * GST_MAP_READWRITE:
  97  *
  98  * Map for readwrite access
  99  */
 100 #define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)
 101
 102 /**
 103  * GST_ALLOCATOR_SYSMEM:
 104  *
 105  * The allocator name for the default system memory allocator
 106  */
 107 #define GST_ALLOCATOR_SYSMEM   "SystemMemory"
 108
 109 /**
 110  * GstMemoryAllocFunction:
 111  * @allocator: a #GstAllocator
 112  * @maxsize: the maxsize
 113  * @align: the alignment
 114  * @user_data: user data
 115  *
 116  * Allocate a new #GstMemory from @allocator that can hold at least @maxsize bytes
 117  * and is aligned to (@align + 1) bytes.
 118  *
 119  * @user_data is the data that was used when registering @allocator.
 120  *
 121  * Returns: a newly allocated #GstMemory. Free with gst_memory_unref()
 122  */
 123 typedef GstMemory *  (*GstMemoryAllocFunction)  (const GstAllocator *allocator,
 124                                                  gsize maxsize, gsize align,
 125                                                  gpointer user_data);
 126
 127 /**
 128  * GstMemoryGetSizesFunction:
 129  * @mem: a #GstMemory
 130  * @offset: result pointer for offset
 131  * @maxsize: result pointer for maxsize
 132  *
 133  * Retrieve the size, offset and maxsize of @mem.
 134  *
 135  * Returns: the size of @mem, the offset and the maximum allocated size in @maxsize.
 136  */
 137 typedef gsize       (*GstMemoryGetSizesFunction)  (GstMemory *mem, gsize *offset, gsize *maxsize);
 138
 139 /**
 140  * GstMemoryResizeFunction:
 141  * @mem: a #GstMemory
 142  * @offset: the offset adjustement
 143  * @size: the new size
 144  *
 145  * Adjust the size and offset of @mem. @offset bytes will be adjusted from the
 146  * current first byte in @mem as retrieved with gst_memory_map() and the new
 147  * size will be set to @size.
 148  *
 149  * @size can be set to -1, which will only adjust the offset.
 150  */
 151 typedef void        (*GstMemoryResizeFunction)    (GstMemory *mem, gssize offset, gsize size);
 152
 153 /**
 154  * GstMemoryMapFunction:
 155  * @mem: a #GstMemory
 156  * @size: pointer for the size
 157  * @maxsize: pointer for the maxsize
 158  * @flags: access mode for the memory
 159  *
 160  * Get the memory of @mem that can be accessed according to the mode specified
 161  * in @flags. @size and @maxsize will respectively contain the current amount of
 162  * valid bytes in the returned memory and the maximum allocated memory.
 163  * @size and @maxsize can optionally be set to NULL.
 164  *
 165  * Returns: a pointer to memory. @size bytes are currently used from the
 166  * returned pointer and @maxsize bytes can potentially be used.
 167  */
 168 typedef gpointer    (*GstMemoryMapFunction)       (GstMemory *mem, gsize *size, gsize *maxsize,
 169                                                    GstMapFlags flags);
 170
 171 /**
 172  * GstMemoryUnmapFunction:
 173  * @mem: a #GstMemory
 174  * @data: the data pointer
 175  * @size: the new size
 176  *
 177  * Return the pointer previously retrieved with gst_memory_map() and adjust the
 178  * size of the memory with @size. @size can optionally be set to -1 to not
 179  * modify the size.
 180  *
 181  * Returns: %TRUE on success.
 182  */
 183 typedef gboolean    (*GstMemoryUnmapFunction)     (GstMemory *mem, gpointer data, gsize size);
 184
 185 /**
 186  * GstMemoryFreeFunction:
 187  * @mem: a #GstMemory
 188  *
 189  * Free the memory used by @mem. This function is usually called when the
 190  * refcount of the @mem has reached 0.
 191  */
 192 typedef void        (*GstMemoryFreeFunction)      (GstMemory *mem);
 193
 194 /**
 195  * GstMemoryCopyFunction:
 196  * @mem: a #GstMemory
 197  * @offset: an offset
 198  * @size: a size
 199  *
 200  * Copy @size bytes from @mem starting at @offset and return them wrapped in a
 201  * new GstMemory object.
 202  * If @size is set to -1, all bytes starting at @offset are copied.
 203  *
 204  * Returns: a new #GstMemory object wrapping a copy of the requested region in
 205  * @mem.
 206  */
 207 typedef GstMemory * (*GstMemoryCopyFunction)      (GstMemory *mem, gssize offset, gsize size);
 208
 209 /**
 210  * GstMemoryShareFunction:
 211  * @mem: a #GstMemory
 212  * @offset: an offset
 213  * @size: a size
 214  *
 215  * Share @size bytes from @mem starting at @offset and return them wrapped in a
 216  * new GstMemory object. If @size is set to -1, all bytes starting at @offset are
 217  * shared. This function does not make a copy of the bytes in @mem.
 218  *
 219  * Returns: a new #GstMemory object sharing the requested region in @mem.
 220  */
 221 typedef GstMemory * (*GstMemoryShareFunction)     (GstMemory *mem, gssize offset, gsize size);
 222
 223 /**
 224  * GstMemoryIsSpanFunction:
 225  * @mem1: a #GstMemory
 226  * @mem2: a #GstMemory
 227  * @offset: a result offset
 228  *
 229  * Check if @mem1 and @mem2 occupy contiguous memory and return the offset of
 230  * @mem1 in the parent buffer in @offset.
 231  *
 232  * Returns: %TRUE if @mem1 and @mem2 are in contiguous memory.
 233  */
 234 typedef gboolean    (*GstMemoryIsSpanFunction)    (GstMemory *mem1, GstMemory *mem2, gsize *offset);
 235
 236 /**
 237  * GstMemoryInfo:
 238  * @alloc: the implementation of the GstMemoryAllocFunction
 239  * @get_sizes: the implementation of the GstMemoryGetSizesFunction
 240  * @resize: the implementation of the GstMemoryResizeFunction
 241  * @map: the implementation of the GstMemoryMapFunction
 242  * @unmap: the implementation of the GstMemoryUnmapFunction
 243  * @free: the implementation of the GstMemoryFreeFunction
 244  * @copy: the implementation of the GstMemoryCopyFunction
 245  * @share: the implementation of the GstMemoryShareFunction
 246  * @is_span: the implementation of the GstMemoryIsSpanFunction
 247  * @user_data: generic user data for the allocator
 248  *
 249  * The #GstMemoryInfo is used to register new memory allocators and contain
 250  * the implementations for various memory operations.
 251  */
 252 struct _GstMemoryInfo {
 253   GstMemoryAllocFunction    alloc;
 254   GstMemoryGetSizesFunction get_sizes;
 255   GstMemoryResizeFunction   resize;
 256   GstMemoryMapFunction      map;
 257   GstMemoryUnmapFunction    unmap;
 258   GstMemoryFreeFunction     free;
 259
 260   GstMemoryCopyFunction     copy;
 261   GstMemoryShareFunction    share;
 262   GstMemoryIsSpanFunction   is_span;
 263
 264   gpointer user_data;
 265 };
 266
 267 /* allocators */
 268 const GstAllocator *  gst_allocator_register    (const gchar *name, const GstMemoryInfo *info);
 269 const GstAllocator *  gst_allocator_find        (const gchar *name);
 270
 271 void                  gst_allocator_set_default (const GstAllocator * allocator);
 272
 273 /* allocating memory blocks */
 274 GstMemory * gst_allocator_alloc        (const GstAllocator * allocator,
 275                                         gsize maxsize, gsize align);
 276
 277 GstMemory * gst_memory_new_wrapped     (GstMemoryFlags flags, gpointer data, GFreeFunc free_func,
 278                                         gsize maxsize, gsize offset, gsize size);
 279
 280 /* refcounting */
 281 GstMemory * gst_memory_ref        (GstMemory *mem);
 282 void        gst_memory_unref      (GstMemory *mem);
 283
 284 /* getting/setting memory properties */
 285 gsize       gst_memory_get_sizes  (GstMemory *mem, gsize *offset, gsize *maxsize);
 286 void        gst_memory_resize     (GstMemory *mem, gssize offset, gsize size);
 287
 288 /* retrieving data */
 289 gpointer    gst_memory_map        (GstMemory *mem, gsize *size, gsize *maxsize,
 290                                    GstMapFlags flags);
 291 gboolean    gst_memory_unmap      (GstMemory *mem, gpointer data, gsize size);
 292
 293 /* copy and subregions */
 294 GstMemory * gst_memory_copy       (GstMemory *mem, gssize offset, gsize size);
 295 GstMemory * gst_memory_share      (GstMemory *mem, gssize offset, gsize size);
 296
 297 /* span memory */
 298 gboolean    gst_memory_is_span    (GstMemory *mem1, GstMemory *mem2, gsize *offset);
 299
 300 G_END_DECLS
 301
 302 #endif /* __GST_MEMORY_H__ */