GStreamer 1.0 Core Reference Manual: GstAllocator

## GstAllocator GstAllocator — allocate memory blocks |

## Functions

GstAllocator * | gst_allocator_find ()
void | gst_allocator_register ()
void | gst_allocator_set_default ()
void | gst_allocation_params_init ()
GstAllocationParams * | gst_allocation_params_copy ()
void | gst_allocation_params_free ()
GstMemory * | gst_allocator_alloc ()
void | gst_allocator_free ()
GstMemory * | gst_memory_new_wrapped ()

## Types and Values

extern | gst_memory_alignment
| GstAllocator
struct | GstAllocatorClass
enum | GstAllocatorFlags
struct | GstAllocationParams
#define | GST_ALLOCATOR_SYSMEM

## Object Hierarchy

        GBoxed
        ╰── GstAllocationParams
        GObject
        ╰── GInitiallyUnowned
            ╰── GstObject
                ╰── GstAllocator

## Includes

    #include <gst/gst.h>

## 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.

## Functions

### 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.

#### Parameters

name | the name of the allocator. | [allow-none]

#### 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][nullable]

### gst_allocator_register ()

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

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

#### Parameters

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` .

#### Parameters

allocator | a GstAllocator. | [transfer full]

### gst_allocation_params_init ()

    void
    gst_allocation_params_init (GstAllocationParams *params);

Initialize `params` to its default values

#### Parameters

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

#### Parameters

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`

#### Parameters

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.

#### Parameters

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()`.

#### Parameters

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.

#### Parameters

flags | GstMemoryFlags |
data | data to wrap. | [array length=size][element-type guint8][transfer none]
maxsize | allocated size of `data` |
offset | offset in `data` |
size | size of valid data |
user_data | user_data. | [allow-none]
notify | called with `user_data` when the memory is freed. | [allow-none][scope async][closure user_data]

#### Returns

a new GstMemory.

[transfer full]

## Types and Values

### gst_memory_alignment

    GST_EXPORT gsize gst_memory_alignment;

The default memory alignment in bytes - 1 an alignment of 7 would be the same as what `malloc()` guarantees.

### GstAllocator

    typedef struct {
      GstMemoryMapFunction      mem_map;
      GstMemoryUnmapFunction    mem_unmap;

      GstMemoryCopyFunction     mem_copy;
      GstMemoryShareFunction    mem_share;
      GstMemoryIsSpanFunction   mem_is_span;
    } GstAllocator;

The GstAllocator is used to create new memory.

#### Members

GstMemoryMapFunction `mem_map`; | the implementation of the GstMemoryMapFunction |
GstMemoryUnmapFunction `mem_unmap`; | the implementation of the GstMemoryUnmapFunction |
GstMemoryCopyFunction `mem_copy`; | the implementation of the GstMemoryCopyFunction |
GstMemoryShareFunction `mem_share`; | the implementation of the GstMemoryShareFunction |
GstMemoryIsSpanFunction `mem_is_span`; | the implementation of the GstMemoryIsSpanFunction |

### struct GstAllocatorClass

    struct GstAllocatorClass {
      GstObjectClass object_class;

      GstMemory *  (*alloc)      (GstAllocator *allocator, gsize size,
                                  GstAllocationParams *params);
      void         (*free)       (GstAllocator *allocator, GstMemory *memory);
    };

The GstAllocator is used to create new memory.

#### Members

GstObjectClass `object_class`; | Object parent class |
`alloc` () | implementation that acquires memory |
`free` () | implementation that releases memory |

### enum GstAllocatorFlags

Flags for allocators.

#### Members

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

#### Members

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

## See Also

GstMemory