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