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., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22
  23 #ifndef __GST_ALLOCATOR_H__
  24 #define __GST_ALLOCATOR_H__
  25
  26 #include <gst/gstmemory.h>
  27
  28 G_BEGIN_DECLS
  29
  30 typedef struct _GstAllocatorPrivate GstAllocatorPrivate;
  31 typedef struct _GstAllocatorClass GstAllocatorClass;
  32
  33 #define GST_TYPE_ALLOCATOR                 (gst_allocator_get_type())
  34 #define GST_IS_ALLOCATOR(obj)              (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_ALLOCATOR))
  35 #define GST_IS_ALLOCATOR_CLASS(klass)      (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_ALLOCATOR))
  36 #define GST_ALLOCATOR_GET_CLASS(obj)       (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_ALLOCATOR, GstAllocatorClass))
  37 #define GST_ALLOCATOR(obj)                 (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_ALLOCATOR, GstAllocator))
  38 #define GST_ALLOCATOR_CLASS(klass)         (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_ALLOCATOR, GstAllocatorClass))
  39 #define GST_ALLOCATOR_CAST(obj)            ((GstAllocator *)(obj))
  40
  41 #define GST_TYPE_ALLOCATION_PARAMS (gst_allocation_params_get_type())
  42 GType gst_allocation_params_get_type(void);
  43
  44 typedef struct _GstAllocationParams GstAllocationParams;
  45
  46 /**
  47  * gst_memory_alignment:
  48  *
  49  * The default memory alignment in bytes - 1
  50  * an alignment of 7 would be the same as what malloc() guarantees.
  51  */
  52 GST_EXPORT gsize gst_memory_alignment;
  53
  54 /**
  55  * GST_ALLOCATOR_SYSMEM:
  56  *
  57  * The allocator name for the default system memory allocator
  58  */
  59 #define GST_ALLOCATOR_SYSMEM   "SystemMemory"
  60
  61 /**
  62  * GstAllocationParams:
  63  * @flags: flags to control allocation
  64  * @align: the desired alignment of the memory
  65  * @prefix: the desired prefix
  66  * @padding: the desired padding
  67  *
  68  * Parameters to control the allocation of memory
  69  */
  70 struct _GstAllocationParams {
  71   GstMemoryFlags flags;
  72   gsize          align;
  73   gsize          prefix;
  74   gsize          padding;
  75
  76   /*< private >*/
  77   gpointer _gst_reserved[GST_PADDING];
  78 };
  79
  80 #if 0
  81 /**
  82  * GstAllocatorAllocFunction:
  83  * @allocator: a #GstAllocator
  84  * @size: the size
  85  * @params: allocator params
  86  * @user_data: user data
  87  *
  88  * Allocate a new #GstMemory from @allocator that can hold at least @size
  89  * bytes (+ padding) and is aligned to (@align + 1) bytes.
  90  *
  91  * The offset and size of the memory should be set and the prefix/padding must
  92  * be filled with 0 if @params flags contains #GST_MEMORY_FLAG_ZERO_PREFIXED and
  93  * #GST_MEMORY_FLAG_ZERO_PADDED respectively.
  94  *
  95  * @user_data is extra data passed to this function. The default
  96  * gst_allocator_alloc() passes the NULL but other implementations could pass
  97  * custom data.
  98  *
  99  * Returns: a newly allocated #GstMemory. Free with gst_memory_unref()
 100  */
 101 typedef GstMemory *  (*GstAllocatorAllocFunction)  (GstAllocator *allocator,
 102                                                     gsize size, GstAllocationParams *params,
 103                                                     gpointer user_data);
 104 #endif
 105
 106 /**
 107  * GstAllocatorFlags:
 108  * @GST_ALLOCATOR_CUSTOM_ALLOC: The allocator has a custom alloc function.
 109  * @GST_ALLOCATOR_FLAG_LAST: first flag that can be used for custom purposes
 110  *
 111  * Flags for allocators.
 112  */
 113 typedef enum {
 114   GST_ALLOCATOR_FLAG_CUSTOM_ALLOC  = (GST_OBJECT_FLAG_LAST << 0),
 115
 116   GST_ALLOCATOR_FLAG_LAST          = (GST_OBJECT_FLAG_LAST << 16)
 117 } GstAllocatorFlags;
 118
 119 /**
 120  * GstAllocator:
 121  * @mini_object: parent structure
 122  * @mem_type: the memory type this allocator provides
 123  * @mem_map: the implementation of the GstMemoryMapFunction
 124  * @mem_unmap: the implementation of the GstMemoryUnmapFunction
 125  * @mem_free: the implementation of the GstMemoryFreeFunction
 126  * @mem_copy: the implementation of the GstMemoryCopyFunction
 127  * @mem_share: the implementation of the GstMemoryShareFunction
 128  * @mem_is_span: the implementation of the GstMemoryIsSpanFunction
 129  *
 130  * The #GstAllocator is used to create new memory.
 131  */
 132 struct _GstAllocator
 133 {
 134   GstObject  object;
 135
 136   const gchar              *mem_type;
 137
 138   GstMemoryMapFunction      mem_map;
 139   GstMemoryUnmapFunction    mem_unmap;
 140
 141   GstMemoryCopyFunction     mem_copy;
 142   GstMemoryShareFunction    mem_share;
 143   GstMemoryIsSpanFunction   mem_is_span;
 144
 145   gpointer _gst_reserved[GST_PADDING];
 146
 147   /*< private >*/
 148   GstAllocatorPrivate *priv;
 149 };
 150
 151 struct _GstAllocatorClass {
 152   GstObjectClass object_class;
 153
 154   GstMemory *  (*alloc)      (GstAllocator *allocator, gsize size,
 155                               GstAllocationParams *params, gpointer user_data);
 156   void         (*free)       (GstAllocator *allocator, GstMemory *memory);
 157
 158   /*< private >*/
 159   gpointer _gst_reserved[GST_PADDING];
 160 };
 161
 162 GType gst_allocator_get_type(void);
 163
 164 /* allocators */
 165 void           gst_allocator_register        (const gchar *name, GstAllocator *allocator);
 166 GstAllocator * gst_allocator_find            (const gchar *name);
 167 void           gst_allocator_set_default     (GstAllocator * allocator);
 168
 169 /* allocation parameters */
 170 void           gst_allocation_params_init    (GstAllocationParams *params);
 171 GstAllocationParams *
 172                gst_allocation_params_copy    (const GstAllocationParams *params) G_GNUC_MALLOC;
 173 void           gst_allocation_params_free    (GstAllocationParams *params);
 174
 175 /* allocating memory blocks */
 176 GstMemory *    gst_allocator_alloc           (GstAllocator * allocator, gsize size,
 177                                               GstAllocationParams *params);
 178 void           gst_allocator_free            (GstAllocator * allocator, GstMemory *mem);
 179
 180 GstMemory *    gst_memory_new_wrapped  (GstMemoryFlags flags, gpointer data, gsize maxsize,
 181                                         gsize offset, gsize size, gpointer user_data,
 182                                         GDestroyNotify notify);
 183
 184 G_END_DECLS
 185
 186 #endif /* __GST_ALLOCATOR_H__ */