## GstBufferPool

GstBufferPool — Create buffers from a pool

## Synopsis

    #include <gst/gst.h>

    #define     GST_BUFFER_POOL                 (pool)
    #define     GST_IS_BUFFER_POOL              (buf)
    struct      GstBufferPool;
    GstBuffer*  (*GstBufferPoolBufferNewFunction)
                                                (GstBufferPool *pool,
                                                 guint64 offset,
                                                 guint size,
                                                 gpointer user_data);
    GstBuffer*  (*GstBufferPoolBufferCopyFunction)
                                                (GstBufferPool *pool,
                                                 const GstBuffer *buffer,
                                                 gpointer user_data);
    void        (*GstBufferPoolBufferFreeFunction)
                                                (GstBufferPool *pool,
                                                 GstBuffer *buffer,
                                                 gpointer user_data);
    GstBufferPool* gst_buffer_pool_new          (GstDataFreeFunction free,
                                                 GstDataCopyFunction copy,
                                                 GstBufferPoolBufferNewFunction buffer_new,
                                                 GstBufferPoolBufferCopyFunction buffer_copy,
                                                 GstBufferPoolBufferFreeFunction buffer_free,
                                                 gpointer user_data);
    gboolean    gst_buffer_pool_is_active       (GstBufferPool *pool);
    void        gst_buffer_pool_set_active      (GstBufferPool *pool,
                                                 gboolean active);
    #define     gst_buffer_pool_ref             (pool)
    #define     gst_buffer_pool_ref_by_count    (pool,c)
    #define     gst_buffer_pool_unref           (pool)
    #define     gst_buffer_pool_copy            (pool)
    #define     gst_buffer_pool_copy_on_write   (pool)
    #define     gst_buffer_pool_free            (pool)
    void        gst_buffer_pool_set_user_data   (GstBufferPool *pool,
                                                 gpointer user_data);
    gpointer    gst_buffer_pool_get_user_data   (GstBufferPool *pool);
    GstBufferPool* gst_buffer_pool_get_default  (guint buffer_size,
                                                 guint pool_size);
    void        gst_buffer_pool_default_free    (GstBufferPool *pool);

## Description

A bufferpool is used to create buffers in an efficient way. An element can, for example, 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 provide a free and copy function to handle the refcounting of the bufferpool as well as functions to create, free and copy buffers created from this pool. All buffer functions will receive the user_data you provide in the constructor. When no free and copy function is provided for the pool, a default implementation will be used.

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 pool, the buffer and the user_data as arguments.

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.

All plugins should unref the bufferpool if it is no longer required. When the bufferpool reaches a refcount of 0, the free function will be called.

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. Use gst_buffer_pool_unref() is you no longer require the bufferpool.

## Details

### GST_BUFFER_POOL()

    #define GST_BUFFER_POOL(pool)   		((GstBufferPool *)(pool))

Cast a pointer to a GstBufferPool

`pool` : | The pointer to cast

### GST_IS_BUFFER_POOL()

    #define GST_IS_BUFFER_POOL(buf) 		(GST_DATA_TYPE(buf) == GST_TYPE_BUFFER_POOL)

Check if the given pointer is a bufferpool

`buf` : | The pointer to check

### struct GstBufferPool

    struct GstBufferPool {

      GstData 				data;

      gboolean				active;

      GstBufferPoolBufferNewFunction 	buffer_new;
      GstBufferPoolBufferCopyFunction	buffer_copy;
      GstBufferPoolBufferFreeFunction	buffer_free;

      gpointer				user_data;
    };

The bufferpool structure

### GstBufferPoolBufferNewFunction ()

    GstBuffer*  (*GstBufferPoolBufferNewFunction)
                                                (GstBufferPool *pool,
                                                 guint64 offset,
                                                 guint size,
                                                 gpointer user_data);

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

`pool` : | The pool allocating the buffer
`offset` : | An offset for the requested buffer, this can be a TIMESTAMP for example so that the bufferpool owner can implement double buffering or return a suitable position in a DMA buffer.
`size` : | The size of the allocated buffer
`user_data` : | user data as set on the bufferpool
Returns : | A new buffer with the given parameters.

### GstBufferPoolBufferCopyFunction ()

    GstBuffer*  (*GstBufferPoolBufferCopyFunction)
                                                (GstBufferPool *pool,
                                                 const GstBuffer *buffer,
                                                 gpointer user_data);

The function that will be called when a buffer from the given pool is copied.

`pool` : | The pool that owns the buffer
`buffer` : | The buffer to copy
`user_data` : | any user data associated with the pool
Returns : | A new buffer that is a copy of the original

### GstBufferPoolBufferFreeFunction ()

    void        (*GstBufferPoolBufferFreeFunction)
                                                (GstBufferPool *pool,
                                                 GstBuffer *buffer,
                                                 gpointer user_data);

The function that will be called when a buffer is to be freed into the pool.

`pool` : | The pool that owns the buffer
`buffer` : | The buffer to free
`user_data` : | Any user data associated with the pool

### gst_buffer_pool_new ()

    GstBufferPool* gst_buffer_pool_new          (GstDataFreeFunction free,
                                                 GstDataCopyFunction copy,
                                                 GstBufferPoolBufferNewFunction buffer_new,
                                                 GstBufferPoolBufferCopyFunction buffer_copy,
                                                 GstBufferPoolBufferFreeFunction buffer_free,
                                                 gpointer user_data);

Creates a new buffer pool with the given functions.

`free` : | the GstDataFreeFunction to free the buffer pool.
`copy` : | the GstDataCopyFunction to copy the buffer pool.
`buffer_new` : | the GstBufferPoolBufferNewFunction to create a new buffer from this pool
`buffer_copy` : | the GstBufferPoolBufferCopyFunction to copy a buffer from this pool
`buffer_free` : | the GstBufferPoolBufferFreeFunction to free a buffer in this pool
`user_data` : | the user data gpointer passed to buffer_* functions.
Returns : | a new GstBufferPool, or NULL on error.

### gst_buffer_pool_is_active ()

    gboolean    gst_buffer_pool_is_active       (GstBufferPool *pool);

Queries if the given buffer pool is active.

`pool` : | the GstBufferPool to query.
Returns : | TRUE if the pool is active.

### gst_buffer_pool_set_active ()

    void        gst_buffer_pool_set_active      (GstBufferPool *pool,
                                                 gboolean active);

Sets the given pool to the active or inactive state depending on the active parameter.

`pool` : | a GstBufferPool to set the activity status on.
`active` : | the new status of the pool.

### gst_buffer_pool_ref()

    #define		gst_buffer_pool_ref(pool)		GST_BUFFER_POOL (gst_data_ref (GST_DATA (pool)))

Increase the refcount of the given pool

`pool` : | The pool to refcount

### gst_buffer_pool_ref_by_count()

    #define		gst_buffer_pool_ref_by_count(pool,c)	GST_BUFFER_POOL (gst_data_ref_by_count (GST_DATA (pool), c))

Increase the refcount of the given pool by c

`pool` : | The pool to refcount
`c` : | The value to add to the refcount

### gst_buffer_pool_unref()

    #define		gst_buffer_pool_unref(pool)		gst_data_unref (GST_DATA (pool))

Decrease the refcount of the given pool. If the refcount reaches 0, the free function of the pool will be called.

`pool` : | The pool to unref.

### gst_buffer_pool_copy()

    #define		gst_buffer_pool_copy(pool)		GST_BUFFER_POOL (gst_data_copy (GST_DATA (pool)))

Copy the pool

`pool` : | The pool to copy.

### gst_buffer_pool_copy_on_write()

    #define		gst_buffer_pool_copy_on_write(pool)	GST_BUFFER_POOL (gst_data_copy_on_write (GST_DATA (pool)))

Copy the pool if the refcount > 1

`pool` : | A copy of the pool or the pool itself if the refcount is 1

### gst_buffer_pool_free()

    #define		gst_buffer_pool_free(pool)		gst_data_free (GST_DATA (pool))

Free the given pool. This is dangerous, use gst_buffer_pool_unref() instead.

`pool` : | The pool to free

### gst_buffer_pool_set_user_data ()

    void        gst_buffer_pool_set_user_data   (GstBufferPool *pool,
                                                 gpointer user_data);

Sets the given user data on the buffer pool.

`pool` : | the GstBufferPool to set the user data for.
`user_data` : | the user_data to set on the buffer pool.

### gst_buffer_pool_get_user_data ()

    gpointer    gst_buffer_pool_get_user_data   (GstBufferPool *pool);

Gets the user data of the buffer pool.

`pool` : | the GstBufferPool to get the user data for.
Returns : | the user data associated with this buffer pool.

### 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_default_free ()

    void        gst_buffer_pool_default_free    (GstBufferPool *pool);

Frees the memory associated with the bufferpool.

`pool` : | a GstBufferPool to free.

## See Also

GstBuffer, GstPad