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  * GST_MEMORY_IS_WRITABLE:
  60  * @mem: a #GstMemory
  61  *
  62  * Check if @mem is writable.
  63  */
  64 #define GST_MEMORY_IS_WRITABLE(mem) (((mem)->refcount == 1) && \
  65     (((mem)->parent == NULL) || ((mem)->parent->refcount == 1)) && \
  66     (((mem)->flags & GST_MEMORY_FLAG_READONLY) == 0))
  67
  68 /**
  69  * GstMemory:
  70  * @allocator: pointer to the #GstAllocator
  71  * @flags: memory flags
  72  * @refcount: refcount
  73  * @parent: parent memory block
  74  *
  75  * Base structure for memory implementations. Custom memory will put this structure
  76  * as the first member of their structure.
  77  */
  78 struct _GstMemory {
  79   const GstAllocator *allocator;
  80
  81   GstMemoryFlags  flags;
  82   gint            refcount;
  83   GstMemory      *parent;
  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  * GstMemoryGetSizesFunction:
 135  * @mem: a #GstMemory
 136  * @offset: result pointer for offset
 137  * @maxsize: result pointer for maxsize
 138  *
 139  * Retrieve the size, offset and maxsize of @mem.
 140  *
 141  * Returns: the size of @mem, the offset and the maximum allocated size in @maxsize.
 142  */
 143 typedef gsize       (*GstMemoryGetSizesFunction)  (GstMemory *mem, gsize *offset, gsize *maxsize);
 144
 145 /**
 146  * GstMemoryResizeFunction:
 147  * @mem: a #GstMemory
 148  * @offset: the offset adjustement
 149  * @size: the new size or -1 to just adjust the offset
 150  *
 151  * Adjust the size and offset of @mem. @offset bytes will be adjusted from the
 152  * current first byte in @mem as retrieved with gst_memory_map() and the new
 153  * size will be set to @size.
 154  *
 155  * @size can be set to -1, which will only adjust the offset.
 156  */
 157 typedef void        (*GstMemoryResizeFunction)    (GstMemory *mem, gssize offset, gssize size);
 158
 159 /**
 160  * GstMemoryMapFunction:
 161  * @mem: a #GstMemory
 162  * @size: pointer for the size
 163  * @maxsize: pointer for the maxsize
 164  * @flags: access mode for the memory
 165  *
 166  * Get the memory of @mem that can be accessed according to the mode specified
 167  * in @flags. @size and @maxsize will respectively contain the current amount of
 168  * valid bytes in the returned memory and the maximum allocated memory.
 169  * @size and @maxsize can optionally be set to NULL.
 170  *
 171  * Returns: a pointer to memory. @size bytes are currently used from the
 172  * returned pointer and @maxsize bytes can potentially be used.
 173  */
 174 typedef gpointer    (*GstMemoryMapFunction)       (GstMemory *mem, gsize *size, gsize *maxsize,
 175                                                    GstMapFlags flags);
 176
 177 /**
 178  * GstMemoryUnmapFunction:
 179  * @mem: a #GstMemory
 180  * @data: the data pointer
 181  * @size: the new size, or -1 to not modify the size
 182  *
 183  * Return the pointer previously retrieved with gst_memory_map() and adjust the
 184  * size of the memory with @size. @size can optionally be set to -1 to not
 185  * modify the size.
 186  *
 187  * Returns: %TRUE on success.
 188  */
 189 typedef gboolean    (*GstMemoryUnmapFunction)     (GstMemory *mem, gpointer data, gssize size);
 190
 191 /**
 192  * GstMemoryFreeFunction:
 193  * @mem: a #GstMemory
 194  *
 195  * Free the memory used by @mem. This function is usually called when the
 196  * refcount of the @mem has reached 0.
 197  */
 198 typedef void        (*GstMemoryFreeFunction)      (GstMemory *mem);
 199
 200 /**
 201  * GstMemoryCopyFunction:
 202  * @mem: a #GstMemory
 203  * @offset: an offset
 204  * @size: a size or -1
 205  *
 206  * Copy @size bytes from @mem starting at @offset and return them wrapped in a
 207  * new GstMemory object.
 208  * If @size is set to -1, all bytes starting at @offset are copied.
 209  *
 210  * Returns: a new #GstMemory object wrapping a copy of the requested region in
 211  * @mem.
 212  */
 213 typedef GstMemory * (*GstMemoryCopyFunction)      (GstMemory *mem, gssize offset, gssize size);
 214
 215 /**
 216  * GstMemoryShareFunction:
 217  * @mem: a #GstMemory
 218  * @offset: an offset
 219  * @size: a size or -1
 220  *
 221  * Share @size bytes from @mem starting at @offset and return them wrapped in a
 222  * new GstMemory object. If @size is set to -1, all bytes starting at @offset are
 223  * shared. This function does not make a copy of the bytes in @mem.
 224  *
 225  * Returns: a new #GstMemory object sharing the requested region in @mem.
 226  */
 227 typedef GstMemory * (*GstMemoryShareFunction)     (GstMemory *mem, gssize offset, gssize size);
 228
 229 /**
 230  * GstMemoryIsSpanFunction:
 231  * @mem1: a #GstMemory
 232  * @mem2: a #GstMemory
 233  * @offset: a result offset
 234  *
 235  * Check if @mem1 and @mem2 occupy contiguous memory and return the offset of
 236  * @mem1 in the parent buffer in @offset.
 237  *
 238  * Returns: %TRUE if @mem1 and @mem2 are in contiguous memory.
 239  */
 240 typedef gboolean    (*GstMemoryIsSpanFunction)    (GstMemory *mem1, GstMemory *mem2, gsize *offset);
 241
 242 /**
 243  * GstMemoryInfo:
 244  * @alloc: the implementation of the GstMemoryAllocFunction
 245  * @get_sizes: the implementation of the GstMemoryGetSizesFunction
 246  * @resize: the implementation of the GstMemoryResizeFunction
 247  * @map: the implementation of the GstMemoryMapFunction
 248  * @unmap: the implementation of the GstMemoryUnmapFunction
 249  * @free: the implementation of the GstMemoryFreeFunction
 250  * @copy: the implementation of the GstMemoryCopyFunction
 251  * @share: the implementation of the GstMemoryShareFunction
 252  * @is_span: the implementation of the GstMemoryIsSpanFunction
 253  * @user_data: generic user data for the allocator
 254  *
 255  * The #GstMemoryInfo is used to register new memory allocators and contain
 256  * the implementations for various memory operations.
 257  */
 258 struct _GstMemoryInfo {
 259   GstMemoryAllocFunction    alloc;
 260   GstMemoryGetSizesFunction get_sizes;
 261   GstMemoryResizeFunction   resize;
 262   GstMemoryMapFunction      map;
 263   GstMemoryUnmapFunction    unmap;
 264   GstMemoryFreeFunction     free;
 265
 266   GstMemoryCopyFunction     copy;
 267   GstMemoryShareFunction    share;
 268   GstMemoryIsSpanFunction   is_span;
 269
 270   gpointer user_data;
 271
 272   /*< private >*/
 273   gpointer _gst_reserved[GST_PADDING];
 274 };
 275
 276 /* allocators */
 277 const GstAllocator *  gst_allocator_register    (const gchar *name, const GstMemoryInfo *info);
 278 const GstAllocator *  gst_allocator_find        (const gchar *name);
 279
 280 void                  gst_allocator_set_default (const GstAllocator * allocator);
 281
 282 /* allocating memory blocks */
 283 GstMemory * gst_allocator_alloc        (const GstAllocator * allocator,
 284                                         gsize maxsize, gsize align);
 285
 286 GstMemory * gst_memory_new_wrapped     (GstMemoryFlags flags, gpointer data, GFreeFunc free_func,
 287                                         gsize maxsize, gsize offset, gsize size);
 288
 289 /* refcounting */
 290 GstMemory * gst_memory_ref        (GstMemory *mem);
 291 void        gst_memory_unref      (GstMemory *mem);
 292
 293 /* getting/setting memory properties */
 294 gsize       gst_memory_get_sizes  (GstMemory *mem, gsize *offset, gsize *maxsize);
 295 void        gst_memory_resize     (GstMemory *mem, gssize offset, gsize size);
 296
 297 /* retrieving data */
 298 gpointer    gst_memory_map        (GstMemory *mem, gsize *size, gsize *maxsize,
 299                                    GstMapFlags flags);
 300 gboolean    gst_memory_unmap      (GstMemory *mem, gpointer data, gssize size);
 301
 302 /* copy and subregions */
 303 GstMemory * gst_memory_copy       (GstMemory *mem, gssize offset, gssize size);
 304 GstMemory * gst_memory_share      (GstMemory *mem, gssize offset, gssize size);
 305
 306 /* span memory */
 307 gboolean    gst_memory_is_span    (GstMemory *mem1, GstMemory *mem2, gsize *offset);
 308
 309 G_END_DECLS
 310
 311 #endif /* __GST_MEMORY_H__ */