GstBufferPool

Name

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);
#define     gst_buffer_pool_needs_copy_on_write(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.


gst_buffer_pool_needs_copy_on_write()

#define		gst_buffer_pool_needs_copy_on_write(pool)	GST_BUFFER_POOL (gst_data_needs_copy_on_write (GST_DATA (pool)))

Checks if a copy needs to be made of the bufferpool before it can safely be modified.

pool :

The pool to query

See Also

GstBuffer, GstPad