GStreamer Library Reference Manual (Core) | |||
---|---|---|---|
<<< Previous Page | Home | Up | Next Page >>> |
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.
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; }; |
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.
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.
#define GST_BUFFER_POOL_UNLOCK(pool) (g_mutex_unlock(GST_BUFFER_POOL(pool)->lock)) |
Lock the given bufferpool.
#define GST_BUFFER_POOL_LOCK(pool) (g_mutex_lock(GST_BUFFER_POOL(pool)->lock)) |
Unlock the given bufferpool.
void gst_buffer_pool_ref (GstBufferPool *pool); |
Increment the refcount of this buffer pool.
void gst_buffer_pool_ref_by_count (GstBufferPool *pool, int count); |
Increment the refcount of this buffer pool by the given number.
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.
void gst_buffer_pool_destroy (GstBufferPool *pool); |
Frees the memory for this bufferpool, calls the destroy hook.
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.
void gst_buffer_pool_set_user_data (GstBufferPool *pool, gpointer user_data); |
You can put your private data here.
gpointer gst_buffer_pool_get_user_data (GstBufferPool *pool); |
gets user data
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).
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.
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.
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.