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. An element
can, for example, 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 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.
</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 pool, the buffer and the user_data as arguments.
</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>
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.
</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.
Use gst_buffer_pool_unref() is you no longer require the bufferpool.
</para>

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

<!-- ##### MACRO GST_BUFFER_POOL ##### -->
<para>
Cast a pointer to a GstBufferPool
</para>

@pool: The pointer to cast


<!-- ##### MACRO GST_BUFFER_POOL_TRACE_NAME ##### -->
<para>
The name used for memory tracing.
</para>



<!-- ##### MACRO GST_IS_BUFFER_POOL ##### -->
<para>
Check if the given pointer is a bufferpool
</para>

@buf: The pointer to check


<!-- ##### STRUCT GstBufferPool ##### -->
<para>
The bufferpool structure
</para>

@data: 
@active: 
@buffer_new: 
@buffer_copy: 
@buffer_free: 
@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
@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.


<!-- ##### USER_FUNCTION GstBufferPoolBufferCopyFunction ##### -->
<para>
The function that will be called when a buffer from the given pool is copied.
</para>

@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


<!-- ##### USER_FUNCTION GstBufferPoolBufferFreeFunction ##### -->
<para>
The function that will be called when a buffer is to be freed into the
pool.
</para>

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


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

</para>

@free: 
@copy: 
@buffer_new: 
@buffer_copy: 
@buffer_free: 
@user_data: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_pool_is_active ##### -->
<para>

</para>

@pool: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_pool_set_active ##### -->
<para>

</para>

@pool: 
@active: 


<!-- ##### MACRO gst_buffer_pool_ref ##### -->
<para>
Increase the refcount of the given pool
</para>

@pool: The pool to refcount


<!-- ##### MACRO gst_buffer_pool_ref_by_count ##### -->
<para>
Increase the refcount of the given pool by c
</para>

@pool: The pool to refcount
@c: The value to add to the refcount


<!-- ##### MACRO gst_buffer_pool_unref ##### -->
<para>
Decrease the refcount of the given pool. If the refcount reaches
0, the free function of the pool will be called.
</para>

@pool: The pool to unref.


<!-- ##### MACRO gst_buffer_pool_copy ##### -->
<para>
Copy the pool
</para>

@pool: The pool to copy.


<!-- ##### MACRO gst_buffer_pool_copy_on_write ##### -->
<para>
Copy the pool if the refcount > 1
</para>

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


<!-- ##### MACRO gst_buffer_pool_free ##### -->
<para>
Free the given pool. This is dangerous, use gst_buffer_pool_unref() instead.
</para>

@pool: The pool to free


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

@pool: 
@user_data: 


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

@pool: 
@Returns: 


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

</para>

@buffer_size: 
@pool_size: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_pool_default_free ##### -->
<para>

</para>

@pool: 


<!-- ##### MACRO gst_buffer_pool_needs_copy_on_write ##### -->
<para>
Checks if a copy needs to be made of the bufferpool before it can
safely be modified.
</para>

@pool: The pool to query