mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-12-12 03:16:33 +00:00
817 lines
29 KiB
XML
817 lines
29 KiB
XML
<chapter id="chapter-allocation" xreflabel="Memory allocation">
|
|
<title>Memory allocation</title>
|
|
<para>
|
|
Memory allocation and management is a very important topic in
|
|
multimedia. High definition video uses many megabytes to store
|
|
one single frame of video. It is important to reuse the memory
|
|
when possible instead of constantly allocating and freeing
|
|
the memory.
|
|
</para>
|
|
<para>
|
|
Multimedia systems usually use special purpose chips, such as
|
|
DSPs or GPUs to perform the heavy lifting (especially for video).
|
|
These special purpose chips have usually strict requirements
|
|
for the memory that they can operate on and how the memory
|
|
is accessed.
|
|
</para>
|
|
<para>
|
|
This chapter talks about the memory management features that
|
|
&GStreamer; plugins can use. We will first talk about the
|
|
lowlevel <classname>GstMemory</classname> object that manages
|
|
access to a piece of memory. We then continue with
|
|
<classname>GstBuffer</classname> that is used to exchange data
|
|
between plugins (and the application) and that uses
|
|
<classname>GstMemory</classname>. We talk about
|
|
<classname>GstMeta</classname> that can be placed on buffers to
|
|
give extra info about the buffer and its memory.
|
|
For efficiently managing buffers of the same size, we take a
|
|
look at <classname>GstBufferPool</classname>. To conclude this
|
|
chapter we take a look at the GST_QUERY_ALLOCATION query that
|
|
is used to negotiate memory management options between elements.
|
|
</para>
|
|
|
|
<sect1 id="section-allocation-memory" xreflabel="GstMemory">
|
|
<title>GstMemory</title>
|
|
<para>
|
|
<classname>GstMemory</classname> is an object that manages a region
|
|
of memory. The memory object points to a region of memory of
|
|
<quote>maxsize</quote>. The area in this memory starting at
|
|
<quote>offset</quote> and for <quote>size</quote> bytes is the
|
|
accessible region in the memory. the maxsize of the memory can
|
|
never be changed after the object is created, however, the offset
|
|
and size can be changed.
|
|
</para>
|
|
<sect2 id="section-allocation-allocator" xreflabel="GstAllocator">
|
|
<title>GstAllocator</title>
|
|
<para>
|
|
<classname>GstMemory</classname> objects are created by a
|
|
<classname>GstAllocator</classname> object. Most allocators implement the
|
|
default <function>gst_allocator_alloc()</function> method but some allocator
|
|
might implement a different method, for example when additional parameters
|
|
are needed to allocate the specific memory.
|
|
</para>
|
|
<para>
|
|
Different allocators exist for, for example, system memory, shared memory
|
|
and memory backed by a DMAbuf file descriptor. To implement support for a
|
|
new kind of memory type, you must implement a new allocator object as shown
|
|
below.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="section-allocation-memory-ex" xreflabel="GstMemory-ex">
|
|
<title>GstMemory API example</title>
|
|
<para>
|
|
Data access to the memory wrapped by the <classname>GstMemory</classname>
|
|
object is always protected with a <function>gst_memory_map()</function>
|
|
and <function>gst_memory_unmap()</function> pair. An access mode
|
|
(read/write) must be given when mapping memory. The map
|
|
function returns a pointer to the valid memory region that can
|
|
then be accessed according to the requested access mode.
|
|
</para>
|
|
<para>
|
|
Below is an example of making a <classname>GstMemory</classname>
|
|
object and using the <function>gst_memory_map()</function> to
|
|
access the memory region.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
[...]
|
|
|
|
GstMemory *mem;
|
|
GstMapInfo info;
|
|
gint i;
|
|
|
|
/* allocate 100 bytes */
|
|
mem = gst_allocator_alloc (NULL, 100, NULL);
|
|
|
|
/* get access to the memory in write mode */
|
|
gst_memory_map (mem, &info, GST_MAP_WRITE);
|
|
|
|
/* fill with pattern */
|
|
for (i = 0; i < info.size; i++)
|
|
info.data[i] = i;
|
|
|
|
/* release memory */
|
|
gst_memory_unmap (mem, &info);
|
|
|
|
[...]
|
|
]]>
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="section-allocation-allocator-ex" xreflabel="GstAllocator-ex">
|
|
<title>Implementing a GstAllocator</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="section-allocation-buffer" xreflabel="GstBuffer">
|
|
<title>GstBuffer</title>
|
|
<para>
|
|
A <classname>GstBuffer</classname> is an lightweight object that
|
|
is passed from an upstream to a downstream element and contains
|
|
memory and metadata. It represents the multimedia content that
|
|
is pushed or pull downstream by elements.
|
|
</para>
|
|
<para>
|
|
The buffer contains one or more <classname>GstMemory</classname>
|
|
objects that represent the data in the buffer.
|
|
</para>
|
|
<para>
|
|
Metadata in the buffer consists of:
|
|
</para>
|
|
<itemizedlist mark="opencircle">
|
|
<listitem>
|
|
<para>
|
|
DTS and PTS timestamps. These represent the decoding and
|
|
presentation timestamps of the buffer content and is used by
|
|
synchronizing elements to schedule buffers. Both these timestamps
|
|
can be GST_CLOCK_TIME_NONE when unknown/undefined.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The duration of the buffer contents. This duration can be
|
|
GST_CLOCK_TIME_NONE when unknown/undefined.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Media specific offsets and offset_end. For video this is the
|
|
frame number in the stream and for audio the sample number. Other
|
|
definitions for other media exist.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Arbitrary structures via <classname>GstMeta</classname>, see below.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<sect2 id="section-allocation-writability" xreflabel="GstBuffer-write">
|
|
<title>GstBuffer writability</title>
|
|
<para>
|
|
A buffer is writable when the refcount of the object is exactly 1, meaning
|
|
that only one object is holding a ref to the buffer. You can only
|
|
modify anything in the buffer when the buffer is writable. This means
|
|
that you need to call <function>gst_buffer_make_writable()</function>
|
|
before changing the timestamps, offsets, metadata or adding and
|
|
removing memory blocks.
|
|
</para>
|
|
</sect2>
|
|
<sect2 id="section-allocation-buffer-ex" xreflabel="GstBuffer-ex">
|
|
<title>GstBuffer API examples</title>
|
|
<para>
|
|
You can create a buffer with <function>gst_buffer_new ()</function>
|
|
and then add memory objects to it or you can use a convenience function
|
|
<function>gst_buffer_new_allocate ()</function> which combines the
|
|
two. It's also possible to wrap existing memory with
|
|
<function>gst_buffer_new_wrapped_full () </function> where you can
|
|
give the function to call when the memory should be freed.
|
|
</para>
|
|
<para>
|
|
You can access the memory of the buffer by getting and mapping the
|
|
<classname>GstMemory</classname> objects individually or by using
|
|
<function>gst_buffer_map ()</function>. The latter merges all the
|
|
memory into one big block and then gives you a pointer to this block.
|
|
</para>
|
|
<para>
|
|
Below is an example of how to create a buffer and access its memory.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
[...]
|
|
GstBuffer *buffer;
|
|
GstMemory *mem;
|
|
GstMapInfo info;
|
|
|
|
/* make empty buffer */
|
|
buffer = gst_buffer_new ();
|
|
|
|
/* make memory holding 100 bytes */
|
|
mem = gst_allocator_alloc (NULL, 100, NULL);
|
|
|
|
/* add the buffer */
|
|
gst_buffer_append_memory (buffer, mem);
|
|
|
|
[...]
|
|
|
|
/* get WRITE access to the memory and fill with 0xff */
|
|
gst_buffer_map (buffer, &info, GST_MAP_WRITE);
|
|
memset (info.data, 0xff, info.size);
|
|
gst_buffer_unmap (buffer, &info);
|
|
|
|
[...]
|
|
|
|
/* free the buffer */
|
|
gst_buffer_unref (buffer);
|
|
|
|
[...]
|
|
]]>
|
|
</programlisting>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="section-allocation-meta" xreflabel="GstMeta">
|
|
<title>GstMeta</title>
|
|
<para>
|
|
With the <classname>GstMeta</classname> system you can add arbitrary
|
|
structures on buffers. These structures describe extra properties
|
|
of the buffer such as cropping, stride, region of interest etc.
|
|
</para>
|
|
<para>
|
|
The metadata system separates API specification (what the metadata
|
|
and its API look like) and the implementation (how it works). This makes
|
|
it possible to make different implementations of the same API,
|
|
for example, depending on the hardware you are running on.
|
|
</para>
|
|
|
|
<sect2 id="section-allocation-meta-ex" xreflabel="GstMeta-ex">
|
|
<title>GstMeta API example</title>
|
|
<para>
|
|
After allocating a new buffer, you can add metadata to the buffer
|
|
with the metadata specific API. This means that you will need to
|
|
link to the header file where the metadata is defined to use
|
|
its API.
|
|
</para>
|
|
<para>
|
|
By convention, a metadata API with name <classname>FooBar</classname>
|
|
should provide two methods, a
|
|
<function>gst_buffer_add_foo_bar_meta ()</function> and a
|
|
<function>gst_buffer_get_foo_bar_meta ()</function>. Both functions
|
|
should return a pointer to a <classname>FooBarMeta</classname>
|
|
structure that contains the metadata fields. Some of the
|
|
<function>_add_*_meta ()</function> can have extra parameters that
|
|
will usually be used to configure the metadata structure for you.
|
|
</para>
|
|
<para>
|
|
Let's have a look at the metadata that is used to specify a cropping
|
|
region for video frames.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
#include <gst/video/gstvideometa.h>
|
|
|
|
[...]
|
|
GstVideoCropMeta *meta;
|
|
|
|
/* buffer points to a video frame, add some cropping metadata */
|
|
meta = gst_buffer_add_video_crop_meta (buffer);
|
|
|
|
/* configure the cropping metadata */
|
|
meta->x = 8;
|
|
meta->y = 8;
|
|
meta->width = 120;
|
|
meta->height = 80;
|
|
[...]
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
An element can then use the metadata on the buffer when rendering
|
|
the frame like this:
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
#include <gst/video/gstvideometa.h>
|
|
|
|
[...]
|
|
GstVideoCropMeta *meta;
|
|
|
|
/* buffer points to a video frame, get the cropping metadata */
|
|
meta = gst_buffer_get_video_crop_meta (buffer);
|
|
|
|
if (meta) {
|
|
/* render frame with cropping */
|
|
_render_frame_cropped (buffer, meta->x, meta->y, meta->width, meta->height);
|
|
} else {
|
|
/* render frame */
|
|
_render_frame (buffer);
|
|
}
|
|
[...]
|
|
|
|
]]>
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="section-allocation-meta-new" xreflabel="GstMeta-new">
|
|
<title>Implementing new GstMeta</title>
|
|
<para>
|
|
In the next sections we show how you can add new metadata to the
|
|
system and use it on buffers.
|
|
</para>
|
|
|
|
<sect3 id="section-allocation-meta-api" xreflabel="GstMeta-api">
|
|
<title>Define the metadata API</title>
|
|
<para>
|
|
First we need to define what our API will look like and we
|
|
will have to register this API to the system. This is important
|
|
because this API definition will be used when elements negotiate
|
|
what kind of metadata they will exchange. The API definition
|
|
also contains arbitrary tags that give hints about what the
|
|
metadata contains. This is important when we see how metadata
|
|
is preserved when buffers pass through the pipeline.
|
|
</para>
|
|
<para>
|
|
If you are making a new implementation of an existing API,
|
|
you can skip this step and move on to the implementation step.
|
|
</para>
|
|
<para>
|
|
First we start with making the
|
|
<filename>my-example-meta.h</filename> header file that will contain
|
|
the definition of the API and structure for our metadata.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
#include <gst/gst.h>
|
|
|
|
typedef struct _MyExampleMeta MyExampleMeta;
|
|
|
|
struct _MyExampleMeta {
|
|
GstMeta meta;
|
|
|
|
gint age;
|
|
gchar *name;
|
|
};
|
|
|
|
GType my_example_meta_api_get_type (void);
|
|
#define MY_EXAMPLE_META_API_TYPE (my_example_meta_api_get_type())
|
|
|
|
#define gst_buffer_get_my_example_meta(b) \
|
|
((MyExampleMeta*)gst_buffer_get_meta((b),MY_EXAMPLE_META_API_TYPE))
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The metadata API definition consists of the definition of the
|
|
structure that holds a gint and a string. The first field in
|
|
the structure must be <classname>GstMeta</classname>.
|
|
</para>
|
|
<para>
|
|
We also define a <function>my_example_meta_api_get_type ()</function>
|
|
function that will register out metadata API definition. We
|
|
also define a convenience macro
|
|
<function>gst_buffer_get_my_example_meta ()</function> that simply
|
|
finds and returns the metadata with our new API.
|
|
</para>
|
|
<para>
|
|
Next let's have a look at how the
|
|
<function>my_example_meta_api_get_type ()</function> function is
|
|
implemented in the <filename>my-example-meta.c</filename> file.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
#include "my-example-meta.h"
|
|
|
|
GType
|
|
my_example_meta_api_get_type (void)
|
|
{
|
|
static volatile GType type;
|
|
static const gchar *tags[] = { "foo", "bar", NULL };
|
|
|
|
if (g_once_init_enter (&type)) {
|
|
GType _type = gst_meta_api_type_register ("MyExampleMetaAPI", tags);
|
|
g_once_init_leave (&type, _type);
|
|
}
|
|
return type;
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
As you can see, it simply uses the
|
|
<function>gst_meta_api_type_register ()</function> function to
|
|
register a name for the api and some tags. The result is a
|
|
new pointer GType that defines the newly registered API.
|
|
</para>
|
|
</sect3>
|
|
|
|
<sect3 id="section-allocation-meta-impl" xreflabel="GstMeta-impl">
|
|
<title>Implementing a metadata API</title>
|
|
<para>
|
|
Next we can make an implementation for a registered metadata
|
|
API GType. The implementation detail of a metadata API
|
|
are kept in a <classname>GstMetaInfo</classname> structure
|
|
that you will make available to the users of your metadata
|
|
API implementation with a <function>my_example_meta_get_info ()</function>
|
|
function and a convenience <function>MY_EXAMPLE_META_INFO</function>
|
|
macro. You will also make a method to add your metadata
|
|
implementation to a <classname>GstBuffer</classname>.
|
|
Your <filename>my-example-meta.h</filename> header file will
|
|
need these additions:
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
[...]
|
|
|
|
/* implementation */
|
|
const GstMetaInfo *my_example_meta_get_info (void);
|
|
#define MY_EXAMPLE_META_INFO (my_example_meta_get_info())
|
|
|
|
MyExampleMeta * gst_buffer_add_my_example_meta (GstBuffer *buffer,
|
|
gint age,
|
|
const gchar *name);
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
Let's have a look at how these functions are
|
|
implemented in the <filename>my-example-meta.c</filename> file.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
[...]
|
|
|
|
static gboolean
|
|
my_example_meta_init (GstMeta * meta, gpointer params, GstBuffer * buffer)
|
|
{
|
|
MyExampleMeta *emeta = (MyExampleMeta *) meta;
|
|
|
|
emeta->age = 0;
|
|
emeta->name = NULL;
|
|
|
|
return TRUE;
|
|
}
|
|
|
|
static gboolean
|
|
my_example_meta_transform (GstBuffer * transbuf, GstMeta * meta,
|
|
GstBuffer * buffer, GQuark type, gpointer data)
|
|
{
|
|
MyExampleMeta *emeta = (MyExampleMeta *) meta;
|
|
|
|
/* we always copy no matter what transform */
|
|
gst_buffer_add_my_example_meta (transbuf, emeta->age, emeta->name);
|
|
|
|
return TRUE;
|
|
}
|
|
|
|
static void
|
|
my_example_meta_free (GstMeta * meta, GstBuffer * buffer)
|
|
{
|
|
MyExampleMeta *emeta = (MyExampleMeta *) meta;
|
|
|
|
g_free (emeta->name)
|
|
emeta->name = NULL;
|
|
}
|
|
|
|
const GstMetaInfo *
|
|
my_example_meta_get_info (void)
|
|
{
|
|
static const GstMetaInfo *meta_info = NULL;
|
|
|
|
if (g_once_init_enter (&meta_info)) {
|
|
const GstMetaInfo *mi = gst_meta_register (MY_EXAMPLE_META_API_TYPE,
|
|
"MyExampleMeta",
|
|
sizeof (MyExampleMeta),
|
|
my_example_meta_init,
|
|
my_example_meta_free,
|
|
my_example_meta_transform);
|
|
g_once_init_leave (&meta_info, mi);
|
|
}
|
|
return meta_info;
|
|
}
|
|
|
|
MyExampleMeta *
|
|
gst_buffer_add_my_example_meta (GstBuffer *buffer,
|
|
gint age,
|
|
const gchar *name)
|
|
{
|
|
MyExampleMeta *meta;
|
|
|
|
g_return_val_if_fail (GST_IS_BUFFER (buffer), NULL);
|
|
|
|
meta = (MyExampleMeta *) gst_buffer_add_meta (buffer,
|
|
MY_EXAMPLE_META_INFO, NULL);
|
|
|
|
meta->age = age;
|
|
meta->name = g_strdup (name);
|
|
|
|
return meta;
|
|
}
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
<function>gst_meta_register ()</function> registers the implementation
|
|
details, like the API that you implement and the size of the
|
|
metadata structure along with methods to initialize and free the
|
|
memory area. You can also implement a transform function that will
|
|
be called when a certain transformation (identified by the quark and
|
|
quark specific data) is performed on a buffer.
|
|
</para>
|
|
<para>
|
|
Lastly, you implement a <function>gst_buffer_add_*_meta()</function>
|
|
that adds the metadata implementation to a buffer and sets the
|
|
values of the metadata.
|
|
</para>
|
|
</sect3>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="section-allocation-bufferpool" xreflabel="GstBufferPool">
|
|
<title>GstBufferPool</title>
|
|
<para>
|
|
The <classname>GstBufferPool</classname> 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.
|
|
</para>
|
|
<para>
|
|
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 <classname>GstAllocator</classname> for
|
|
the memory of the buffers. There is support in the bufferpool to enable
|
|
bufferpool specific options, such as adding <classname>GstMeta</classname>
|
|
to the buffers in the pool or such as enabling specific padding on
|
|
the memory in the buffers.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
In the following sections we take a look at how you can use
|
|
a bufferpool.
|
|
</para>
|
|
|
|
<sect2 id="section-allocation-pool-ex" xreflabel="GstBufferPool-ex">
|
|
<title>GstBufferPool API example</title>
|
|
<para>
|
|
Many different bufferpool implementations can exist; they are all
|
|
subclasses of the base class <classname>GstBufferPool</classname>.
|
|
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
|
|
see below.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
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);
|
|
|
|
[...]
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
The configuration of the bufferpool is maintained in a generic
|
|
<classname>GstStructure</classname> that can be obtained with
|
|
<function>gst_buffer_pool_get_config()</function>. Convenience
|
|
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
|
|
<function>gst_buffer_pool_set_config()</function>.
|
|
</para>
|
|
<para>
|
|
The following options can be configured on a bufferpool:
|
|
</para>
|
|
<itemizedlist mark="opencircle">
|
|
<listitem>
|
|
<para>
|
|
The caps of the buffers to allocate.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The allocator and parameters to use. Some bufferpools might
|
|
ignore the allocator and use its internal one.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Other arbitrary bufferpool options identified with a string.
|
|
a bufferpool lists the supported options with
|
|
<function>gst_buffer_pool_get_options()</function> and you
|
|
can ask if an option is supported with
|
|
<function>gst_buffer_pool_has_option()</function>. The option
|
|
can be enabled by adding it to the configuration structure
|
|
with <function>gst_buffer_pool_config_add_option ()</function>.
|
|
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.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
After the configuration is set on the bufferpool, the pool can
|
|
be activated with
|
|
<function>gst_buffer_pool_set_active (pool, TRUE)</function>. From
|
|
that point on you can use
|
|
<function>gst_buffer_pool_acquire_buffer ()</function> to retrieve
|
|
a buffer from the pool, like this:
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
[...]
|
|
|
|
GstFlowReturn ret;
|
|
GstBuffer *buffer;
|
|
|
|
ret = gst_buffer_pool_acquire_buffer (pool, &buffer, NULL);
|
|
if (G_UNLIKELY (ret != GST_FLOW_OK))
|
|
goto pool_failed;
|
|
|
|
[...]
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
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
|
|
<function>gst_buffer_pool_release_buffer()</function> 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
|
|
unref it.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="section-allocation-pool-impl" xreflabel="GstBufferPool-impl">
|
|
<title>Implementing a new GstBufferPool</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
<sect1 id="section-allocation-query" xreflabel="GST_QUERY_ALLOCATION">
|
|
<title>GST_QUERY_ALLOCATION</title>
|
|
<para>
|
|
The ALLOCATION query is used to negotiate
|
|
<classname>GstMeta</classname>, <classname>GstBufferPool</classname>
|
|
and <classname>GstAllocator</classname> between elements. Negotiation
|
|
of the allocation strategy is always initiated and decided by a srcpad
|
|
after it has negotiated a format and before it decides to push buffers.
|
|
A sinkpad can suggest an allocation strategy but it is ultimately the
|
|
source pad that will decide based on the suggestions of the downstream
|
|
sink pad.
|
|
</para>
|
|
<para>
|
|
The source pad will do a GST_QUERY_ALLOCATION with the negotiated caps
|
|
as a parameter. This is needed so that the downstream element knows
|
|
what media type is being handled. A downstream sink pad can answer the
|
|
allocation query with the following results:
|
|
</para>
|
|
<itemizedlist mark="opencircle">
|
|
<listitem>
|
|
<para>
|
|
An array of possible <classname>GstBufferPool</classname> suggestions
|
|
with suggested size, minimum and maximum amount of buffers.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
An array of GstAllocator objects along with suggested allocation
|
|
parameters such as flags, prefix, alignment and padding. These
|
|
allocators can also be configured in a bufferpool when this is
|
|
supported by the bufferpool.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
An array of supported <classname>GstMeta</classname> implementations
|
|
along with metadata specific parameters.
|
|
It is important that the upstream element knows what kind of
|
|
metadata is supported downstream before it places that metadata
|
|
on buffers.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
When the GST_QUERY_ALLOCATION returns, the source pad will select
|
|
from the available bufferpools, allocators and metadata how it will
|
|
allocate buffers.
|
|
</para>
|
|
|
|
<sect2 id="section-allocation-query-ex" xreflabel="Allocation-ex">
|
|
<title>ALLOCATION query example</title>
|
|
<para>
|
|
Below is an example of the ALLOCATION query.
|
|
</para>
|
|
<programlisting>
|
|
<![CDATA[
|
|
#include <gst/video/video.h>
|
|
#include <gst/video/gstvideometa.h>
|
|
#include <gst/video/gstvideopool.h>
|
|
|
|
GstCaps *caps;
|
|
GstQuery *query;
|
|
GstStructure *structure;
|
|
GstBufferPool *pool;
|
|
GstStructure *config;
|
|
guint size, min, max;
|
|
|
|
[...]
|
|
|
|
/* find a pool for the negotiated caps now */
|
|
query = gst_query_new_allocation (caps, TRUE);
|
|
|
|
if (!gst_pad_peer_query (scope->srcpad, query)) {
|
|
/* query failed, not a problem, we use the query defaults */
|
|
}
|
|
|
|
if (gst_query_get_n_allocation_pools (query) > 0) {
|
|
/* we got configuration from our peer, parse them */
|
|
gst_query_parse_nth_allocation_pool (query, 0, &pool, &size, &min, &max);
|
|
} else {
|
|
pool = NULL;
|
|
size = 0;
|
|
min = max = 0;
|
|
}
|
|
|
|
if (pool == NULL) {
|
|
/* we did not get a pool, make one ourselves then */
|
|
pool = gst_video_buffer_pool_new ();
|
|
}
|
|
|
|
config = gst_buffer_pool_get_config (pool);
|
|
gst_buffer_pool_config_add_option (config, GST_BUFFER_POOL_OPTION_VIDEO_META);
|
|
gst_buffer_pool_config_set_params (config, caps, size, min, max);
|
|
gst_buffer_pool_set_config (pool, config);
|
|
|
|
/* and activate */
|
|
gst_buffer_pool_set_active (pool, TRUE);
|
|
|
|
[...]
|
|
]]>
|
|
</programlisting>
|
|
<para>
|
|
This particular implementation will make a custom
|
|
<classname>GstVideoBufferPool</classname> object that is specialized
|
|
in allocating video buffers. You can also enable the pool to
|
|
put <classname>GstVideoMeta</classname> metadata on the buffers from
|
|
the pool doing
|
|
<function>gst_buffer_pool_config_add_option (config,
|
|
GST_BUFFER_POOL_OPTION_VIDEO_META)</function>.
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="section-allocation-query-base" xreflabel="Allocation-base">
|
|
<title>The ALLOCATION query in base classes</title>
|
|
<para>
|
|
In many baseclasses you will see the following virtual methods for
|
|
influencing the allocation strategy:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<function>propose_allocation ()</function> should suggest
|
|
allocation parameters for the upstream element.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<function>decide_allocation ()</function> should decide the
|
|
allocation parameters from the suggestions received from
|
|
downstream.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
Implementors of these methods should modify the given
|
|
<classname>GstQuery</classname> object by updating the pool options
|
|
and allocation options.
|
|
</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|