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 typedef enum {
  37   GST_MEMORY_FLAG_READONLY = (1 << 0)
  38 } GstMemoryFlags;
  39
  40
  41 #define GST_MEMORY_IS_WRITABLE(mem) (((mem)->refcount == 1) && \
  42     (((mem)->parent == NULL) || ((mem)->parent->refcount == 1)) && \
  43     (((mem)->flags & GST_MEMORY_FLAG_READONLY) == 0))
  44
  45 /**
  46  * GstMemory:
  47  * @impl: pointer to the #GstMemoryImpl
  48  * @refcount: refcount
  49  * @parent: parent memory block
  50  *
  51  * Base structure for memory implementations. Custom memory will put this structure
  52  * as the first member of their structure.
  53  */
  54 struct _GstMemory {
  55   const GstMemoryImpl *impl;
  56
  57   GstMemoryFlags  flags;
  58   gint            refcount;
  59   GstMemory      *parent;
  60 };
  61
  62 typedef enum {
  63   GST_MAP_READ =  (1 << 0),
  64   GST_MAP_WRITE = (1 << 1),
  65 } GstMapFlags;
  66
  67 #define GST_MAP_READWRITE      (GST_MAP_READ | GST_MAP_WRITE)
  68
  69 /**
  70  * GST_MEMORY_TRACE_NAME:
  71  *
  72  * The name used for tracing memory allocations.
  73  */
  74 #define GST_MEMORY_TRACE_NAME           "GstMemory"
  75
  76 typedef gsize       (*GstMemoryGetSizesFunction)  (GstMemory *mem, gsize *maxsize);
  77 typedef void        (*GstMemoryResizeFunction)    (GstMemory *mem, gsize offset, gsize size);
  78
  79 typedef gpointer    (*GstMemoryMapFunction)       (GstMemory *mem, gsize *size, gsize *maxsize,
  80                                                    GstMapFlags flags);
  81 typedef gboolean    (*GstMemoryUnmapFunction)     (GstMemory *mem, gpointer data, gsize size);
  82 typedef void        (*GstMemoryFreeFunction)      (GstMemory *mem);
  83
  84 typedef GstMemory * (*GstMemoryCopyFunction)      (GstMemory *mem, gsize offset, gsize size);
  85 typedef GstMemory * (*GstMemoryShareFunction)     (GstMemory *mem, gsize offset, gsize size);
  86 typedef gboolean    (*GstMemoryIsSpanFunction)    (GstMemory *mem1, GstMemory *mem2, gsize *offset);
  87
  88 /**
  89  * GstMemoryInfo:
  90  * @get_sizes:
  91  *
  92  * The #GstMemoryInfo is used to register new memory implementations.
  93  */
  94 struct _GstMemoryInfo {
  95   GstMemoryGetSizesFunction get_sizes;
  96   GstMemoryResizeFunction   resize;
  97   GstMemoryMapFunction      map;
  98   GstMemoryUnmapFunction    unmap;
  99   GstMemoryFreeFunction     free;
 100
 101   GstMemoryCopyFunction     copy;
 102   GstMemoryShareFunction    share;
 103   GstMemoryIsSpanFunction   is_span;
 104 };
 105
 106 void _gst_memory_init (void);
 107
 108 /* allocating memory blocks */
 109 GstMemory * gst_memory_new_wrapped (GstMemoryFlags flags, gpointer data, GFreeFunc free_func,
 110                                     gsize maxsize, gsize offset, gsize size);
 111 GstMemory * gst_memory_new_alloc   (gsize maxsize, gsize align);
 112 GstMemory * gst_memory_new_copy    (gsize maxsize, gsize align, gpointer data,
 113                                     gsize offset, gsize size);
 114
 115 /* refcounting */
 116 GstMemory * gst_memory_ref        (GstMemory *mem);
 117 void        gst_memory_unref      (GstMemory *mem);
 118
 119 /* getting/setting memory properties */
 120 gsize       gst_memory_get_sizes  (GstMemory *mem, gsize *maxsize);
 121 void        gst_memory_resize     (GstMemory *mem, gsize offset, gsize size);
 122
 123 /* retriveing data */
 124 gpointer    gst_memory_map        (GstMemory *mem, gsize *size, gsize *maxsize,
 125                                    GstMapFlags flags);
 126 gboolean    gst_memory_unmap      (GstMemory *mem, gpointer data, gsize size);
 127
 128 /* copy and subregions */
 129 GstMemory * gst_memory_copy       (GstMemory *mem, gsize offset, gsize size);
 130 GstMemory * gst_memory_share      (GstMemory *mem, gsize offset, gsize size);
 131
 132 /* span memory */
 133 gboolean    gst_memory_is_span    (GstMemory *mem1, GstMemory *mem2, gsize *offset);
 134
 135 GstMemory * gst_memory_span       (GstMemory **mem1, gsize len1, gsize offset,
 136                                    GstMemory **mem2, gsize len2, gsize size);
 137
 138
 139 const GstMemoryImpl *  gst_memory_register    (const gchar *impl, const GstMemoryInfo *info);
 140
 141 #if 0
 142 const GstMemoryInfo *  gst_memory_get_info    (const gchar * impl);
 143 #endif
 144
 145 G_END_DECLS
 146
 147 #endif /* __GST_MEMORY_H__ */