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