GstBufferPool object provides a convenient
base class for managing lists of reusable buffers. Essential for this
object is that all the buffers have the same properties such as size,
padding, metadata and alignment.
A bufferpool object can be configured to manage a minimum and maximum
amount of buffers of a specific size. A bufferpool can also be
configured to use a specific
the memory of the buffers. There is support in the bufferpool to enable
bufferpool specific options, such as adding
to the buffers in the pool or such as enabling specific padding on
the memory in the buffers.
A Bufferpool can be inactivate and active. In the inactive state, you can configure the pool. In the active state, you can't change the configuration anymore but you can acquire and release buffers from/to the pool.
In the following sections we take a look at how you can use a bufferpool.
Many different bufferpool implementations can exist; they are all
subclasses of the base class
For this example, we will assume we somehow have access to a
bufferpool, either because we created it ourselves or because
we were given one as a result of the ALLOCATION query as we will
The bufferpool is initially in the inactive state so that we can configure it. Trying to configure a bufferpool that is not in the inactive state will fail. Likewise, trying to activate a bufferpool that is not configured will fail.
GstStructure *config; [...] /* get config structure */ config = gst_buffer_pool_get_config (pool); /* set caps, size, minimum and maximum buffers in the pool */ gst_buffer_pool_config_set_params (config, caps, size, min, max); /* configure allocator and parameters */ gst_buffer_pool_config_set_allocator (config, allocator, ¶ms); /* store the updated configuration again */ gst_buffer_pool_set_config (pool, config); [...]
The configuration of the bufferpool is maintained in a generic
GstStructure that can be obtained with
methods exist to get and set the configuration options in this
structure. After updating the structure, it is set as the current
configuration in the bufferpool again with
The following options can be configured on a bufferpool:
The caps of the buffers to allocate.
The size of the buffers. This is the suggested size of the buffers in the pool. The pool might decide to allocate larger buffers to add padding.
The minimum and maximum amount of buffers in the pool. When minimum is set to > 0, the bufferpool will pre-allocate this amount of buffers. When maximum is not 0, the bufferpool will allocate up to maximum amount of buffers.
The allocator and parameters to use. Some bufferpools might ignore the allocator and use its internal one.
Other arbitrary bufferpool options identified with a string.
a bufferpool lists the supported options with
gst_buffer_pool_get_options() and you
can ask if an option is supported with
gst_buffer_pool_has_option(). The option
can be enabled by adding it to the configuration structure
These options are used to enable things like letting the
pool set metadata on the buffers or to add extra configuration
options for padding, for example.
After the configuration is set on the bufferpool, the pool can
be activated with
gst_buffer_pool_set_active (pool, TRUE). From
that point on you can use
gst_buffer_pool_acquire_buffer () to retrieve
a buffer from the pool, like this:
[...] GstFlowReturn ret; GstBuffer *buffer; ret = gst_buffer_pool_acquire_buffer (pool, &buffer, NULL); if (G_UNLIKELY (ret != GST_FLOW_OK)) goto pool_failed; [...]
It is important to check the return value of the acquire function because it is possible that it fails: When your element shuts down, it will deactivate the bufferpool and then all calls to acquire will return GST_FLOW_FLUSHNG.
All buffers that are acquired from the pool will have their pool
member set to the original pool. When the last ref is decremented
on the buffer, GStreamer will automatically call
gst_buffer_pool_release_buffer() to release
the buffer back to the pool. You (or any other downstream element)
don't need to know if a buffer came from a pool, you can just