GstBufferPool

Name

GstBufferPool -- Create buffers from a pool

Synopsis


#include <gst/gst.h>


struct      GstBufferPool;
GstBuffer*  (*GstBufferPoolBufferNewFunction)
                                            (GstBufferPool *pool,
                                             gint64 location,
                                             gint size,
                                             gpointer user_data);
void        (*GstBufferPoolDestroyHook)     (GstBufferPool *pool,
                                             gpointer user_data);
#define     GST_BUFFER_POOL_UNLOCK          (pool)
#define     GST_BUFFER_POOL_LOCK            (pool)
GstBufferPool* gst_buffer_pool_new          (void);
void        gst_buffer_pool_ref             (GstBufferPool *pool);
void        gst_buffer_pool_ref_by_count    (GstBufferPool *pool,
                                             int count);
void        gst_buffer_pool_unref           (GstBufferPool *pool);
void        gst_buffer_pool_destroy         (GstBufferPool *pool);
GstBufferPool* gst_buffer_pool_get_default  (guint buffer_size,
                                             guint pool_size);
void        gst_buffer_pool_set_user_data   (GstBufferPool *pool,
                                             gpointer user_data);
gpointer    gst_buffer_pool_get_user_data   (GstBufferPool *pool);
void        gst_buffer_pool_set_buffer_copy_function
                                            (GstBufferPool *pool,
                                             GstBufferCopyFunc copy);
void        gst_buffer_pool_set_buffer_free_function
                                            (GstBufferPool *pool,
                                             GstBufferFreeFunc destroy);
void        gst_buffer_pool_set_buffer_new_function
                                            (GstBufferPool *pool,
                                             GstBufferPoolBufferNewFunction create);
void        gst_buffer_pool_set_destroy_hook
                                            (GstBufferPool *pool,
                                             GstBufferPoolDestroyHook destroy);

Description

A bufferpool is used to create buffers in an efficient way. En element can maintain a bufferpool with a fixed number of buffers. This will reduce the g_malloc and g_free overhead.

A bufferpool can also be used to implement direct access. A bufferpool can be sent from one element to another so that the latter can directly write into the memory of the element that maintains the bufferpool. This can greatly reduce the number of memcpy operations.

A bufferpool is created with gst_buffer_pool_new(). You'll have to set the buffer new and free function afterwards with gst_buffer_pool_set_buffer_new_function() and gst_buffer_pool_set_buffer_free_function() so that all buffers created from this pool will be allocated/freed with these functions.

Optionally the default buffer copy function of the buffers allocated from this pool can be overridden with gst_buffer_pool_set_buffer_copy_function().

To create a buffer from the bufferpool use gst_buffer_new_from_pool().

When the buffer is unreffed and has reached a refcount of 0, the bufferpools free function is called with the buffer as an argument.

A bufferpool can store private data in the buffer it creates with the GST_BUFFER_POOL_PRIVATE() macro. To check it a buffer was made by a specific bufferpool, use the GST_BUFFER_BUFFERPOOL() macro to get its bufferpool.

Destroy the bufferpool with gst_buffer_pool_destroy(), optional cleanup of the bufferpool can be triggered in the GstBufferPoolDestroyHook which you can install with gst_buffer_pool_set_destroy_hook().

The owner of the bufferpool can add user data to the pool with gst_buffer_pool_set_user_data() and gst_buffer_pool_get_user_data().

If your plugin is going to need a lot of equally sized memory areas you can use gst_buffer_pool_get_default() to request a pool that will create buffers of that size. These bufferpools will be shared with all plugins needing the same size of buffers so it's quite efficient since it reduces the number of memory allocations.

A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() function. This function is typically used when a plugin wants to write into a memory area provided by another plugin.

Details

struct GstBufferPool

struct GstBufferPool {
  /* locking */
  GMutex *lock;

  /* refcounting */
#ifdef HAVE_ATOMIC_H
  atomic_t refcount;
#define GST_BUFFER_POOL_REFCOUNT(pool)	(atomic_read(&(GST_BUFFER_POOL((pool))->refcount)))
#else
  int refcount;
#define GST_BUFFER_POOL_REFCOUNT(pool)	(GST_BUFFER_POOL(pool)->refcount)
#endif

  GstBufferPoolBufferNewFunction buffer_new;
  GstBufferFreeFunc buffer_free;
  GstBufferCopyFunc buffer_copy;
  GstBufferPoolDestroyHook destroy_hook;
    
  gpointer user_data;
};


GstBufferPoolBufferNewFunction ()

GstBuffer*  (*GstBufferPoolBufferNewFunction)
                                            (GstBufferPool *pool,
                                             gint64 location,
                                             gint size,
                                             gpointer user_data);

The function will be called when a buffer must be allocated from the pool.

pool :The pool allocating the buffer
location :the location (offset) of the buffer to allocate
size :The size of the allocated buffer
user_data :user data as set on the bufferpool
Returns :A new buffer with the given parameters.


GstBufferPoolDestroyHook ()

void        (*GstBufferPoolDestroyHook)     (GstBufferPool *pool,
                                             gpointer user_data);

Will be called when the bufferpool is destroyed so that the owner of the pool can perform necessary cleanup.

pool :The pool that is being destroyed
user_data :user data as set on th bufferpool


GST_BUFFER_POOL_UNLOCK()

#define GST_BUFFER_POOL_UNLOCK(pool)	(g_mutex_unlock(GST_BUFFER_POOL(pool)->lock))

Lock the given bufferpool.

pool :The pool to lock.


GST_BUFFER_POOL_LOCK()

#define GST_BUFFER_POOL_LOCK(pool)	(g_mutex_lock(GST_BUFFER_POOL(pool)->lock))

Unlock the given bufferpool.

pool :the bufferpool to unlock.


gst_buffer_pool_new ()

GstBufferPool* gst_buffer_pool_new          (void);

Create a new buffer pool.

Returns : new buffer pool


gst_buffer_pool_ref ()

void        gst_buffer_pool_ref             (GstBufferPool *pool);

Increment the refcount of this buffer pool.

pool : the GstBufferPool to reference


gst_buffer_pool_ref_by_count ()

void        gst_buffer_pool_ref_by_count    (GstBufferPool *pool,
                                             int count);

Increment the refcount of this buffer pool by the given number.

pool : the GstBufferPool to reference
count : a number


gst_buffer_pool_unref ()

void        gst_buffer_pool_unref           (GstBufferPool *pool);

Decrement the refcount of this buffer pool. If the refcount is zero and the pool is a default implementation, the buffer pool will be destroyed.

pool : the GstBufferPool to unref


gst_buffer_pool_destroy ()

void        gst_buffer_pool_destroy         (GstBufferPool *pool);

Frees the memory for this bufferpool, calls the destroy hook.

pool : the pool to destroy


gst_buffer_pool_get_default ()

GstBufferPool* gst_buffer_pool_get_default  (guint buffer_size,
                                             guint pool_size);

Returns an instance of a buffer pool using the default implementation. If a buffer pool instance with the same buffer_size already exists this will be returned, otherwise a new instance will be created.

buffer_size : the number of bytes this buffer will store
pool_size : the default number of buffers to be preallocated
Returns : an instance of GstBufferPool


gst_buffer_pool_set_user_data ()

void        gst_buffer_pool_set_user_data   (GstBufferPool *pool,
                                             gpointer user_data);

You can put your private data here.

pool : the pool to set the user data for
user_data : any user data to be passed to the create/destroy buffer functions and the destroy hook


gst_buffer_pool_get_user_data ()

gpointer    gst_buffer_pool_get_user_data   (GstBufferPool *pool);

gets user data

pool : the pool to get the user data from
Returns : The user data of this bufferpool


gst_buffer_pool_set_buffer_copy_function ()

void        gst_buffer_pool_set_buffer_copy_function
                                            (GstBufferPool *pool,
                                             GstBufferCopyFunc copy);

Sets the function that will be called when a buffer is copied.

You may use the default GstBuffer implementation (gst_buffer_copy).

pool : the pool to set the buffer copy function for
copy : the copy function


gst_buffer_pool_set_buffer_free_function ()

void        gst_buffer_pool_set_buffer_free_function
                                            (GstBufferPool *pool,
                                             GstBufferFreeFunc destroy);

Sets the function that will be called when a buffer is freed from this pool.

pool : the pool to set the buffer free function for
destroy : the free function


gst_buffer_pool_set_buffer_new_function ()

void        gst_buffer_pool_set_buffer_new_function
                                            (GstBufferPool *pool,
                                             GstBufferPoolBufferNewFunction create);

Sets the function that will be called when a buffer is created from this pool.

pool : the pool to set the buffer create function for
create : the create function


gst_buffer_pool_set_destroy_hook ()

void        gst_buffer_pool_set_destroy_hook
                                            (GstBufferPool *pool,
                                             GstBufferPoolDestroyHook destroy);

Sets the function that will be called before a bufferpool is destroyed. You can take care of you private_data here.

pool : the pool to set the destroy hook for
destroy : the destroy function

See Also

GstBuffer, GstPad