2002-01-15 00:41:22 +00:00
|
|
|
<!-- ##### 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>
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
@data:
|
|
|
|
@active:
|
|
|
|
@buffer_new:
|
2002-01-15 00:41:22 +00:00
|
|
|
@buffer_copy:
|
2002-07-11 19:40:06 +00:00
|
|
|
@buffer_free:
|
2002-01-15 00:41:22 +00:00
|
|
|
@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
|
2002-07-11 19:40:06 +00:00
|
|
|
@offset:
|
2002-01-15 00:41:22 +00:00
|
|
|
@size: The size of the allocated buffer
|
|
|
|
@user_data: user data as set on the bufferpool
|
|
|
|
@Returns: A new buffer with the given parameters.
|
2002-07-11 19:40:06 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
|
|
|
@location: the location (offset) of the buffer to allocate
|
2002-01-15 00:41:22 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gst_buffer_pool_new ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
@free:
|
|
|
|
@copy:
|
|
|
|
@buffer_create:
|
|
|
|
@buffer_copy:
|
|
|
|
@buffer_free:
|
|
|
|
@user_data:
|
2002-01-15 00:41:22 +00:00
|
|
|
@Returns:
|
|
|
|
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
<!-- ##### MACRO gst_buffer_pool_ref ##### -->
|
2002-01-15 00:41:22 +00:00
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
@buf:
|
|
|
|
<!-- # Unused Parameters # -->
|
2002-01-15 00:41:22 +00:00
|
|
|
@pool:
|
|
|
|
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
<!-- ##### MACRO gst_buffer_pool_ref_by_count ##### -->
|
2002-01-15 00:41:22 +00:00
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
@buf:
|
|
|
|
@c:
|
|
|
|
<!-- # Unused Parameters # -->
|
2002-01-15 00:41:22 +00:00
|
|
|
@pool:
|
|
|
|
@count:
|
|
|
|
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
<!-- ##### MACRO gst_buffer_pool_unref ##### -->
|
2002-01-15 00:41:22 +00:00
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
@buf:
|
2002-01-15 00:41:22 +00:00
|
|
|
<!-- # Unused Parameters # -->
|
|
|
|
@pool:
|
2002-07-11 19:40:06 +00:00
|
|
|
@buffer:
|
2002-01-15 00:41:22 +00:00
|
|
|
|
|
|
|
|
|
|
|
<!-- ##### FUNCTION gst_buffer_pool_get_default ##### -->
|
|
|
|
<para>
|
|
|
|
|
|
|
|
</para>
|
|
|
|
|
2002-07-11 19:40:06 +00:00
|
|
|
@size:
|
|
|
|
@numbuffers:
|
2002-01-15 00:41:22 +00:00
|
|
|
@Returns:
|
|
|
|
<!-- # Unused Parameters # -->
|
2002-07-11 19:40:06 +00:00
|
|
|
@buffer_size:
|
|
|
|
@pool_size:
|
2002-01-15 00:41:22 +00:00
|
|
|
@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:
|
|
|
|
|
|
|
|
|