A GstBuffer
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.
The buffer contains one or more GstMemory
objects thet represent the data in the buffer.
Metadata in the buffer consists of:
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.
The duration of the buffer contents. This duration can be GST_CLOCK_TIME_NONE when unknown/undefined.
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.
Arbitrary structures via GstMeta
, see below.
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 gst_buffer_make_writable()
before changing the timestamps, offsets, metadata or adding and
removing memory blocks.
You can create a buffer with gst_buffer_new ()
and then add memory objects to it or you can use a convenience function
gst_buffer_new_allocate ()
which combines the
two. It's also possible to wrap existing memory with
gst_buffer_new_wrapped_full ()
where you can
give the function to call when the memory should be freed.
You can access the memory of the buffer by getting and mapping the
GstMemory
objects individually or by using
gst_buffer_map ()
. The latter merges all the
memory into one big block and then gives you a pointer to this block.
Below is an example of how to create a buffer and access its memory.
[...] 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); [...]