mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-07-02 20:55:55 +00:00
bd0eb629bf
Add more examples. Add example for implementing new metadata. Add programs to the docs (again?), it seems to contain useful info.
618 lines
21 KiB
XML
618 lines
21 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 magabytes 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>
|
|
<para>
|
|
<classname>GstMemory</classname> objects are created by a
|
|
<classname>GstAllocator</classname> object. To implement support
|
|
for a new kind of memory type, you must implement a new allocator
|
|
object.
|
|
</para>
|
|
<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" xreflabel="GstAllocator">
|
|
<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 thet 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 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 of on buffers. These structures describe extra properties
|
|
of the buffer such as cropping, stride, region of interest etc.
|
|
</para>
|
|
<para>
|
|
Metadata is also used to store, for example, the X image that is
|
|
backing up the memory of the buffer. This makes it easier for elements
|
|
to locate the X image from the buffer.
|
|
</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 thse 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 (meta_info == NULL) {
|
|
meta_info = gst_meta_register (MY_EXAMPLE_META_API_TYPE,
|
|
"MyExampleMeta",
|
|
sizeof (MyExampleMeta),
|
|
my_example_meta_init,
|
|
my_example_meta_free,
|
|
my_example_meta_transform);
|
|
}
|
|
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>
|
|
|
|
<sect2 id="section-allocation-pool-ex" xreflabel="GstBufferPool-ex">
|
|
<title>GstBufferPool API example</title>
|
|
<para>
|
|
WRITEME
|
|
</para>
|
|
</sect2>
|
|
|
|
<sect2 id="section-allocation-pool-new" xreflabel="GstBufferPool-new">
|
|
<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>
|
|
WRITEME
|
|
</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>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|