gst/gstallocator.h

   1 /* GStreamer
   2  * Copyright (C) 2009 Wim Taymans <wim.taymans@gmail.be>
   3  *
   4  * gstallocator.h: Header for memory allocation
   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., 51 Franklin St, Fifth Floor,
  19  * Boston, MA 02110-1301, USA.
  20  */
  21
  22
  23 #ifndef __GST_ALLOCATOR_H__
  24 #define __GST_ALLOCATOR_H__
  25
  26 #include <gst/gstmemory.h>
  27 #include <gst/gstobject.h>
  28
  29 G_BEGIN_DECLS
  30
  31 typedef struct _GstAllocatorPrivate GstAllocatorPrivate;
  32 typedef struct _GstAllocatorClass GstAllocatorClass;
  33
  34 #define GST_TYPE_ALLOCATOR                 (gst_allocator_get_type())
  35 #define GST_IS_ALLOCATOR(obj)              (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_ALLOCATOR))
  36 #define GST_IS_ALLOCATOR_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_ALLOCATOR))
  37 #define GST_ALLOCATOR_GET_CLASS(obj)       (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_ALLOCATOR, GstAllocatorClass))
  38 #define GST_ALLOCATOR(obj)                 (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_ALLOCATOR, GstAllocator))
  39 #define GST_ALLOCATOR_CLASS(klass)         (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_ALLOCATOR, GstAllocatorClass))
  40 #define GST_ALLOCATOR_CAST(obj)            ((GstAllocator *)(obj))
  41
  42 #define GST_TYPE_ALLOCATION_PARAMS (gst_allocation_params_get_type())
  43
  44 GST_API
  45 GType gst_allocation_params_get_type(void);
  46
  47 typedef struct _GstAllocationParams GstAllocationParams;
  48
  49 /**
  50  * gst_memory_alignment:
  51  *
  52  * The default memory alignment in bytes - 1
  53  * an alignment of 7 would be the same as what malloc() guarantees.
  54  */
  55
  56 GST_API gsize gst_memory_alignment;
  57
  58 /**
  59  * GST_ALLOCATOR_SYSMEM:
  60  *
  61  * The allocator name for the default system memory allocator
  62  */
  63 #define GST_ALLOCATOR_SYSMEM   "SystemMemory"
  64
  65 /**
  66  * GstAllocationParams:
  67  * @flags: flags to control allocation
  68  * @align: the desired alignment of the memory
  69  * @prefix: the desired prefix
  70  * @padding: the desired padding
  71  *
  72  * Parameters to control the allocation of memory
  73  */
  74 struct _GstAllocationParams {
  75   GstMemoryFlags flags;
  76   gsize          align;
  77   gsize          prefix;
  78   gsize          padding;
  79
  80   /*< private >*/
  81   gpointer _gst_reserved[GST_PADDING];
  82 };
  83
  84 /**
  85  * GstAllocatorFlags:
  86  * @GST_ALLOCATOR_FLAG_CUSTOM_ALLOC: The allocator has a custom alloc function.
  87  * @GST_ALLOCATOR_FLAG_LAST: first flag that can be used for custom purposes
  88  *
  89  * Flags for allocators.
  90  */
  91 typedef enum {
  92   GST_ALLOCATOR_FLAG_CUSTOM_ALLOC  = (GST_OBJECT_FLAG_LAST << 0),
  93
  94   GST_ALLOCATOR_FLAG_LAST          = (GST_OBJECT_FLAG_LAST << 16)
  95 } GstAllocatorFlags;
  96
  97 /**
  98  * GstAllocator:
  99  * @mem_map: the implementation of the GstMemoryMapFunction
 100  * @mem_unmap: the implementation of the GstMemoryUnmapFunction
 101  * @mem_copy: the implementation of the GstMemoryCopyFunction
 102  * @mem_share: the implementation of the GstMemoryShareFunction
 103  * @mem_is_span: the implementation of the GstMemoryIsSpanFunction
 104  * @mem_map_full: the implementation of the GstMemoryMapFullFunction.
 105  *      Will be used instead of @mem_map if present. (Since 1.6)
 106  * @mem_unmap_full: the implementation of the GstMemoryUnmapFullFunction.
 107  *      Will be used instead of @mem_unmap if present. (Since 1.6)
 108  *
 109  * The #GstAllocator is used to create new memory.
 110  */
 111 struct _GstAllocator
 112 {
 113   GstObject  object;
 114
 115   const gchar               *mem_type;
 116
 117   /*< public >*/
 118   GstMemoryMapFunction       mem_map;
 119   GstMemoryUnmapFunction     mem_unmap;
 120
 121   GstMemoryCopyFunction      mem_copy;
 122   GstMemoryShareFunction     mem_share;
 123   GstMemoryIsSpanFunction    mem_is_span;
 124
 125   GstMemoryMapFullFunction   mem_map_full;
 126   GstMemoryUnmapFullFunction mem_unmap_full;
 127
 128   /*< private >*/
 129   gpointer _gst_reserved[GST_PADDING - 2];
 130
 131   GstAllocatorPrivate *priv;
 132 };
 133
 134 /**
 135  * GstAllocatorClass:
 136  * @object_class:  Object parent class
 137  * @alloc: implementation that acquires memory
 138  * @free: implementation that releases memory
 139  *
 140  * The #GstAllocator is used to create new memory.
 141  */
 142 struct _GstAllocatorClass {
 143   GstObjectClass object_class;
 144
 145   /*< public >*/
 146   GstMemory *  (*alloc)      (GstAllocator *allocator, gsize size,
 147                               GstAllocationParams *params);
 148   void         (*free)       (GstAllocator *allocator, GstMemory *memory);
 149
 150   /*< private >*/
 151   gpointer _gst_reserved[GST_PADDING];
 152 };
 153
 154 GST_API
 155 GType          gst_allocator_get_type (void);
 156
 157 /* allocators */
 158
 159 GST_API
 160 void           gst_allocator_register        (const gchar *name, GstAllocator *allocator);
 161
 162 GST_API
 163 GstAllocator * gst_allocator_find            (const gchar *name);
 164
 165 GST_API
 166 void           gst_allocator_set_default     (GstAllocator * allocator);
 167
 168 /* allocation parameters */
 169
 170 GST_API
 171 void           gst_allocation_params_init    (GstAllocationParams *params);
 172
 173 GST_API
 174 GstAllocationParams *
 175                gst_allocation_params_copy    (const GstAllocationParams *params) G_GNUC_MALLOC;
 176
 177 GST_API
 178 void           gst_allocation_params_free    (GstAllocationParams *params);
 179
 180 /* allocating memory blocks */
 181
 182 GST_API
 183 GstMemory *    gst_allocator_alloc           (GstAllocator * allocator, gsize size,
 184                                               GstAllocationParams *params);
 185
 186 GST_API
 187 void           gst_allocator_free            (GstAllocator * allocator, GstMemory *memory);
 188
 189 GST_API
 190 GstMemory *    gst_memory_new_wrapped  (GstMemoryFlags flags, gpointer data, gsize maxsize,
 191                                         gsize offset, gsize size, gpointer user_data,
 192                                         GDestroyNotify notify);
 193
 194 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 195 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstAllocationParams, gst_allocation_params_free)
 196 #endif
 197
 198 G_END_DECLS
 199
 200 #endif /* __GST_ALLOCATOR_H__ */