GstAllocator

GstAllocator — allocate memory blocks

Synopsis

#include <gst/gst.h>

                    GstAllocator;
struct              GstAllocatorClass;
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

  GBoxed
   +----GstAllocationParams

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.

Details

GstAllocator

typedef struct {
  GstMemoryMapFunction       mem_map;
  GstMemoryUnmapFunction     mem_unmap;

  GstMemoryCopyFunction      mem_copy;
  GstMemoryShareFunction     mem_share;
  GstMemoryIsSpanFunction    mem_is_span;

  GstMemoryMapFullFunction   mem_map_full;
  GstMemoryUnmapFullFunction mem_unmap_full;
} GstAllocator;

The GstAllocator is used to create new memory.

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

GstMemoryMapFullFunction mem_map_full;

 the implementation of the GstMemoryMapFullFunction. Will be used instead of mem_map if present. (Since 1.6)

GstMemoryUnmapFullFunction mem_unmap_full;

 the implementation of the GstMemoryUnmapFullFunction. Will be used instead of mem_unmap if present. (Since 1.6)

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.

GstObjectClass object_class;

 Object parent class

alloc ()

 implementation that acquires memory

free ()

 implementation that releases 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. [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.

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. [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]

See Also

GstMemory
Generated by GTK-Doc V1.19