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