gstreamer/docs/gst/tmpl/gstbufferpool.sgml

<!-- ##### SECTION Title ##### -->
GstBufferPool

<!-- ##### SECTION Short_Description ##### -->
Create buffers from a pool

<!-- ##### SECTION Long_Description ##### -->
<para>
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.
</para>
<para>
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.
</para>
<para>
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.
</para>
<para>
Optionally the default buffer copy function of the buffers allocated from this pool
can be overridden with gst_buffer_pool_set_buffer_copy_function().
</para>
<para>
To create a buffer from the bufferpool use gst_buffer_new_from_pool().
</para>
<para>
When the buffer is unreffed and has reached a refcount of 0, the bufferpools free
function is called with the buffer as an argument.
</para>
<para>
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.
</para>
<para>
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().
</para>
<para>
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().
</para>
<para>
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.
</para>

<para>
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.
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GstBuffer, #GstPad
</para>

<!-- ##### STRUCT GstBufferPool ##### -->
<para>

</para>

@lock: 
@buffer_free: 
@buffer_copy: 
@destroy_hook: 
@user_data: 

<!-- ##### USER_FUNCTION GstBufferPoolBufferNewFunction ##### -->
<para>
The function will be called when a buffer must be allocated from the pool.
</para>

@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.


<!-- ##### USER_FUNCTION GstBufferPoolDestroyHook ##### -->
<para>
Will be called when the bufferpool is destroyed so that the owner of the pool
can perform necessary cleanup.
</para>

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


<!-- ##### MACRO GST_BUFFER_POOL_UNLOCK ##### -->
<para>
Lock the given bufferpool.
</para>

@pool: The pool to lock.


<!-- ##### MACRO GST_BUFFER_POOL_LOCK ##### -->
<para>
Unlock the given bufferpool.
</para>

@pool: the bufferpool to unlock.


<!-- ##### FUNCTION gst_buffer_pool_new ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION gst_buffer_pool_ref ##### -->
<para>

</para>

@pool: 


<!-- ##### FUNCTION gst_buffer_pool_ref_by_count ##### -->
<para>

</para>

@pool: 
@count: 


<!-- ##### FUNCTION gst_buffer_pool_unref ##### -->
<para>

</para>

@pool: 
<!-- # Unused Parameters # -->
@buffer: 


<!-- ##### FUNCTION gst_buffer_pool_destroy ##### -->
<para>

</para>

@pool: 


<!-- ##### FUNCTION gst_buffer_pool_get_default ##### -->
<para>

</para>

@buffer_size: 
@pool_size: 
@Returns: 
<!-- # Unused Parameters # -->
@oldpool: 


<!-- ##### FUNCTION gst_buffer_pool_set_user_data ##### -->
<para>

</para>

@pool: 
@user_data: 


<!-- ##### FUNCTION gst_buffer_pool_get_user_data ##### -->
<para>

</para>

@pool: 
@Returns: 
<!-- # Unused Parameters # -->
@user_data: 


<!-- ##### FUNCTION gst_buffer_pool_set_buffer_copy_function ##### -->
<para>

</para>

@pool: 
@copy: 


<!-- ##### FUNCTION gst_buffer_pool_set_buffer_free_function ##### -->
<para>

</para>

@pool: 
@destroy: 


<!-- ##### FUNCTION gst_buffer_pool_set_buffer_new_function ##### -->
<para>

</para>

@pool: 
@create: 


<!-- ##### FUNCTION gst_buffer_pool_set_destroy_hook ##### -->
<para>

</para>

@pool: 
@destroy: