GstAllocator

## GstAllocator GstAllocator — allocate memory blocks |

## Synopsis

    #include <gst/gst.h>

                        GstAllocator;
    enum                GstAllocatorFlags;
    struct              GstAllocationParams;
    #define             GST_ALLOCATOR_SYSMEM
    GstAllocator *      gst_allocator_find                  (const gchar *name);
    void                gst_allocator_register              (const gchar *name,
                                                             GstAllocator *allocator);
    void                gst_allocator_set_default           (GstAllocator *allocator);
    void                gst_allocation_params_init          (GstAllocationParams *params);
    GstAllocationParams * gst_allocation_params_copy        (const GstAllocationParams *params);
    void                gst_allocation_params_free          (GstAllocationParams *params);
    GstMemory *         gst_allocator_alloc                 (GstAllocator *allocator,
                                                             gsize size,
                                                             GstAllocationParams *params);
    void                gst_allocator_free                  (GstAllocator *allocator,
                                                             GstMemory *memory);
    GstMemory *         gst_memory_new_wrapped              (GstMemoryFlags flags,
                                                             gpointer data,
                                                             gsize maxsize,
                                                             gsize offset,
                                                             gsize size,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

## Object Hierarchy

      GObject
       +----GInitiallyUnowned
             +----GstObject
                   +----GstAllocator

## Description

Memory is usually created by allocators with a `gst_allocator_alloc()` method call. When NULL is used as the allocator, the default allocator will be used.

New allocators can be registered with `gst_allocator_register()`. Allocators are identified by name and can be retrieved with `gst_allocator_find()`. `gst_allocator_set_default()` can be used to change the default allocator.

New memory can be created with `gst_memory_new_wrapped()` that wraps the memory allocated elsewhere.

Last reviewed on 2012-07-09 (0.11.3)

## Details

### GstAllocator

    typedef struct _GstAllocator GstAllocator;

The GstAllocator is used to create new memory.

### enum GstAllocatorFlags

    typedef enum {
      GST_ALLOCATOR_FLAG_CUSTOM_ALLOC  = (GST_OBJECT_FLAG_LAST << 0),

      GST_ALLOCATOR_FLAG_LAST          = (GST_OBJECT_FLAG_LAST << 16)
    } GstAllocatorFlags;

Flags for allocators.

`GST_ALLOCATOR_FLAG_CUSTOM_ALLOC` | The allocator has a custom alloc function.
`GST_ALLOCATOR_FLAG_LAST` | first flag that can be used for custom purposes

### struct GstAllocationParams

    struct GstAllocationParams {
      GstMemoryFlags flags;
      gsize          align;
      gsize          prefix;
      gsize          padding;
    };

Parameters to control the allocation of memory

GstMemoryFlags `flags`; | flags to control allocation
gsize `align`; | the desired alignment of the memory
gsize `prefix`; | the desired prefix
gsize `padding`; | the desired padding

### GST_ALLOCATOR_SYSMEM

    #define GST_ALLOCATOR_SYSMEM   "SystemMemory"

The allocator name for the default system memory allocator

### gst_allocator_find ()

    GstAllocator *      gst_allocator_find                  (const gchar *name);

Find a previously registered allocator with `name`. When `name` is NULL, the default allocator will be returned.

`name` : | the name of the allocator
Returns : | a GstAllocator or NULL when the allocator with `name` was not registered. Use `gst_object_unref()` to release the allocator after usage. [transfer full]

### gst_allocator_register ()

    void                gst_allocator_register              (const gchar *name,
                                                             GstAllocator *allocator);

Registers the memory `allocator` with `name`. This function takes ownership of `allocator`.

`name` : | the name of the allocator
`allocator` : | GstAllocator. [transfer full]

### gst_allocator_set_default ()

    void                gst_allocator_set_default           (GstAllocator *allocator);

Set the default allocator. This function takes ownership of `allocator`.

`allocator` : | a GstAllocator. [transfer full]

### gst_allocation_params_init ()

    void                gst_allocation_params_init          (GstAllocationParams *params);

Initialize `params` to its default values

`params` : | a GstAllocationParams

### gst_allocation_params_copy ()

    GstAllocationParams * gst_allocation_params_copy        (const GstAllocationParams *params);

Create a copy of `params`.

Free-function: gst_allocation_params_free

`params` : | a GstAllocationParams. [transfer none]
Returns : | a new #GstAllocationParams, free with `gst_allocation_params_free()`. [transfer full]

### gst_allocation_params_free ()

    void                gst_allocation_params_free          (GstAllocationParams *params);

Free `params`

`params` : | a GstAllocationParams. [in][transfer full]

### gst_allocator_alloc ()

    GstMemory *         gst_allocator_alloc                 (GstAllocator *allocator,
                                                             gsize size,
                                                             GstAllocationParams *params);

Use `allocator` to allocate a new memory block with memory that is at least `size` big.

The optional `params` can specify the prefix and padding for the memory. If NULL is passed, no flags, no extra prefix/padding and a default alignment is used.

The prefix/padding will be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

When `allocator` is NULL, the default allocator will be used.

The alignment in `params` is given as a bitmask so that `align` + 1 equals the amount of bytes to align to. For example, to align to 8 bytes, use an alignment of 7.

`allocator` : | a GstAllocator to use. [transfer none][allow-none]
`size` : | size of the visible memory area
`params` : | optional parameters. [transfer none][allow-none]
Returns : | a new GstMemory. [transfer full]

### gst_allocator_free ()

    void                gst_allocator_free                  (GstAllocator *allocator,
                                                             GstMemory *memory);

Free `memory` that was previously allocated with `gst_allocator_alloc()`.

`allocator` : | a GstAllocator to use. [transfer none]
`memory` : | the memory to free. [transfer full]

### gst_memory_new_wrapped ()

    GstMemory *         gst_memory_new_wrapped              (GstMemoryFlags flags,
                                                             gpointer data,
                                                             gsize maxsize,
                                                             gsize offset,
                                                             gsize size,
                                                             gpointer user_data,
                                                             GDestroyNotify notify);

Allocate a new memory block that wraps the given `data`.

The prefix/padding must be filled with 0 if `flags` contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

`flags` : | GstMemoryFlags
`data` : | data to wrap
`maxsize` : | allocated size of `data`
`offset` : | offset in `data`
`size` : | size of valid data
`user_data` : | user_data
`notify` : | called with `user_data` when the memory is freed
Returns : | a new GstMemory.

## See Also

GstMemory