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