memory: make GstAllocator a miniobject

[platform/upstream/gstreamer.git] / gst / gstmemory.h

diff --git a/gst/gstmemory.h b/gst/gstmemory.h
index f64aef8..701249d 100644 (file)
--- a/gst/gstmemory.h
+++ b/gst/gstmemory.h
@@ -35,10 +35,20 @@ GType gst_memory_get_type(void);
 #define GST_TYPE_ALLOCATOR (gst_allocator_get_type())
 GType gst_allocator_get_type(void);
 
+#define GST_TYPE_ALLOCATION_PARAMS (gst_allocation_params_get_type())
+GType gst_allocation_params_get_type(void);
+
 typedef struct _GstMemory GstMemory;
 typedef struct _GstMemoryInfo GstMemoryInfo;
 typedef struct _GstAllocator GstAllocator;
+typedef struct _GstAllocationParams GstAllocationParams;
 
+/**
+ * gst_memory_alignment:
+ *
+ * The default memory alignment in bytes - 1
+ * an alignment of 7 would be the same as what malloc() guarantees.
+ */
 GST_EXPORT gsize gst_memory_alignment;
 
 #define GST_MEMORY_CAST(mem)   ((GstMemory *)(mem))
@@ -177,6 +187,11 @@ typedef struct {
   gpointer user_data[4];
 } GstMapInfo;
 
+/**
+ * GST_MAP_INFO_INIT:
+ *
+ * Initializer for #GstMapInfo
+ */
 #define GST_MAP_INFO_INIT { NULL, 0, NULL, 0, 0, }
 
 /**
@@ -194,20 +209,36 @@ typedef struct {
 #define GST_ALLOCATOR_SYSMEM   "SystemMemory"
 
 /**
+ * GstAllocationParams:
+ * @flags: flags to control allocation
+ * @align: the desired alignment of the memory
+ * @prefix: the disired prefix
+ * @padding: the desired padding
+ *
+ * Parameters to control the allocation of memory
+ */
+struct _GstAllocationParams {
+  GstMemoryFlags flags;
+  gsize          align;
+  gsize          prefix;
+  gsize          padding;
+
+  /*< private >*/
+  gpointer _gst_reserved[GST_PADDING];
+};
+
+/**
  * GstAllocatorAllocFunction:
  * @allocator: a #GstAllocator
- * @flags: the flags
- * @maxsize: the maxsize
- * @offset: the offset
  * @size: the size
- * @align: the alignment
+ * @params: allocator params
  * @user_data: user data
  *
- * Allocate a new #GstMemory from @allocator that can hold at least @maxsize bytes
- * and is aligned to (@align + 1) bytes.
+ * Allocate a new #GstMemory from @allocator that can hold at least @size
+ * bytes (+ padding) and is aligned to (@align + 1) bytes.
  *
  * The offset and size of the memory should be set and the prefix/padding must
- * be filled with 0 if @flags contains #GST_MEMORY_FLAG_ZERO_PREFIXED and
+ * be filled with 0 if @params flags contains #GST_MEMORY_FLAG_ZERO_PREFIXED and
  * #GST_MEMORY_FLAG_ZERO_PADDED respectively.
  *
  * @user_data is the data that was used when creating @allocator.
@@ -215,9 +246,7 @@ typedef struct {
  * Returns: a newly allocated #GstMemory. Free with gst_memory_unref()
  */
 typedef GstMemory *  (*GstAllocatorAllocFunction)  (GstAllocator *allocator,
-                                                    GstMemoryFlags flags,
-                                                    gsize maxsize, gsize offset,
-                                                    gsize size, gsize align,
+                                                    gsize size, GstAllocationParams *params,
                                                     gpointer user_data);
 
 /**
@@ -327,13 +356,51 @@ struct _GstMemoryInfo {
   gpointer _gst_reserved[GST_PADDING];
 };
 
+/**
+ * GstAllocator:
+ *
+ * An opaque type returned from gst_allocator_new() or gst_allocator_find()
+ * that can be used to allocator memory.
+ */
+
 /* allocators */
 GstAllocator * gst_allocator_new             (const GstMemoryInfo * info,
                                               gpointer user_data, GDestroyNotify notify);
 const gchar *  gst_allocator_get_memory_type (GstAllocator * allocator);
 
-GstAllocator * gst_allocator_ref             (GstAllocator * allocator);
-void           gst_allocator_unref           (GstAllocator * allocator);
+/**
+ * gst_allocator_ref:
+ * @allocator: The allocator to refcount
+ *
+ * Increase the refcount of this allocator.
+ *
+ * Returns: (transfer full): @allocator (for convenience when doing assignments)
+ */
+#ifdef _FOOL_GTK_DOC_
+G_INLINE_FUNC GstAllocator * gst_allocator_ref (GstAllocator * allocator);
+#endif
+
+static inline GstAllocator *
+gst_allocator_ref (GstAllocator * allocator)
+{
+  return (GstAllocator *) gst_mini_object_ref (GST_MINI_OBJECT_CAST (allocator));
+}
+
+/**
+ * gst_allocator_unref:
+ * @allocator: (transfer full): the allocator to refcount
+ *
+ * Decrease the refcount of an allocator, freeing it if the refcount reaches 0.
+ */
+#ifdef _FOOL_GTK_DOC_
+G_INLINE_FUNC void gst_allocator_unref (GstAllocator * allocator);
+#endif
+
+static inline void
+gst_allocator_unref (GstAllocator * allocator)
+{
+  gst_mini_object_unref (GST_MINI_OBJECT_CAST (allocator));
+}
 
 void           gst_allocator_register        (const gchar *name, GstAllocator *allocator);
 GstAllocator * gst_allocator_find            (const gchar *name);
@@ -341,9 +408,13 @@ GstAllocator * gst_allocator_find            (const gchar *name);
 void           gst_allocator_set_default     (GstAllocator * allocator);
 
 /* allocating memory blocks */
-GstMemory *    gst_allocator_alloc           (GstAllocator * allocator, GstMemoryFlags flags,
-                                              gsize maxsize, gsize offset, gsize size,
-                                              gsize align);
+void           gst_allocation_params_init     (GstAllocationParams *params);
+GstAllocationParams *
+               gst_allocation_params_copy     (const GstAllocationParams *params) G_GNUC_MALLOC;
+void           gst_allocation_params_free     (GstAllocationParams *params);
+
+GstMemory *    gst_allocator_alloc           (GstAllocator * allocator, gsize size,
+                                              GstAllocationParams *params);
 
 GstMemory *    gst_memory_new_wrapped  (GstMemoryFlags flags, gpointer data, gsize maxsize,
                                         gsize offset, gsize size, gpointer user_data,