Buffers are the basic unit of data transfer in GStreamer.
They contain the timing and offset along with other arbitrary metadata that is associated with the
Memory blocks that the buffer contains.
Buffers are usually created with Buffer. After a buffer has been created one
will typically allocate memory for it and add it to the buffer. The following example creates a buffer that can hold a given video frame
with a given width, height and bits per plane.
``` C GstBuffer *buffer; GstMemory *memory; gint size, width, height, bpp; ... size = width * height * bpp; buffer =
Buffer; memory = gst_allocator_alloc (NULL, size, NULL);
gst_buffer_insert_memory (buffer, -1, memory); ... ```
Alternatively, use Buffer.allocate to create a buffer with
preallocated data of a given size.
Buffers can contain a list of Memory objects. You can retrieve how many memory objects with
n_memory and you can get a pointer to memory with
peek_memory
A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to
CLOCK_TIME_NONE). Whenever a meaningful value can be given for these, they should
be set. The timestamps and duration are measured in nanoseconds (they are ClockTime
values).
The buffer DTS refers to the timestamp when the buffer should be decoded and is usually monotonically increasing. The buffer PTS refers
to the timestamp when the buffer content should be presented to the user and is not always monotonically increasing.
A buffer can also have one or both of a start and an end offset. These are media-type specific. For video buffers, the start offset will
generally be the frame number. For audio buffers, it will be the number of samples produced so far. For compressed data, it could be the
byte offset in a source or destination file. Likewise, the end offset will be the offset of the end of the buffer. These can only be
meaningfully interpreted if you know the media type of the buffer (the preceding CAPS event). Either or both can be set to
BUFFER_OFFSET_NONE.
gst_buffer_ref is used to increase the refcount of a buffer. This must be done when you want to keep a handle to the buffer
after pushing it to the next element. The buffer refcount determines the writability of the buffer, a buffer is only writable when the
refcount is exactly 1, i.e. when the caller has the only reference to the buffer.
To efficiently create a smaller buffer out of an existing one, you can use
copy_region. This method tries to share the memory objects between the two buffers.
If a plug-in wants to modify the buffer data or metadata in-place, it should first obtain a buffer that is safe to modify by using
gst_buffer_make_writable. This function is optimized so that a copy will only be made when it is necessary.
Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET and GST_BUFFER_FLAG_UNSET macros.
Use GST_BUFFER_FLAG_IS_SET to test if a certain BufferFlags flag is set.
Buffers can be efficiently merged into a larger buffer with append. Copying of memory
will only be done when absolutely needed.
Arbitrary extra metadata can be set on a buffer with add_meta. Metadata can be
retrieved with get_meta. See also Meta.
An element should either unref the buffer or push it out on a src pad using push (see
Pad).
Buffers are usually freed by unreffing them with gst_buffer_unref. When the refcount drops to 0, any memory and metadata
pointed to by the buffer is unreffed as well. Buffers allocated from a BufferPool will be
returned to the pool when the refcount drops to 0.
The ParentBufferMeta is a meta which can be attached to a
Buffer to hold a reference to another buffer that is only released when the child Buffer is released.
Typically, ParentBufferMeta is used when the child buffer is directly using the
Memory of the parent buffer, and wants to prevent the parent buffer from being returned to a
buffer pool until the Memory is available for re-use. (Since: 1.6)
- public unowned CustomMeta? add_custom_meta (string name)
Creates and adds a
CustomMeta for the desired name.
- public unowned Meta? add_meta (MetaInfo info, void* @params)
Adds metadata for info to this
using the parameters in params.
- public unowned ParentBufferMeta? add_parent_buffer_meta (Buffer @ref)
Adds a
ParentBufferMeta to this that holds a reference on ref until the buffer is freed.
- public unowned ProtectionMeta? add_protection_meta (owned Structure info)
Attaches protection metadata to a Buffer.
- public unowned ReferenceTimestampMeta? add_reference_timestamp_meta (Caps reference, ClockTime timestamp, ClockTime duration)
Adds a
ReferenceTimestampMeta to this that holds a timestamp and optionally
duration based on a specific timestamp reference.
- public Buffer append (owned Buffer buf2)
Appends all the memory from buf2 to
this.
- public void append_memory (owned Memory mem)
Appends the memory block mem to
this.
- public Buffer append_region (owned Buffer buf2, ssize_t offset, ssize_t size)
Appends size bytes at offset from buf2
to this.
- public Buffer copy_deep ()
Creates a copy of the given buffer.
- public bool copy_into (Buffer dst, BufferCopyFlags flags, size_t offset, size_t size)
Copies the information from src into
this.
- public Buffer copy_region (BufferCopyFlags flags, size_t offset, size_t size)
Creates a sub-buffer from this at
offset and size.
- public size_t extract (size_t offset, out unowned uint8[] dest)
Copies dest.length bytes starting from offset
in this to dest.
- public void extract_dup (size_t offset, size_t size, out uint8[] dest)
Extracts a copy of at most size bytes the data at
offset into newly-allocated memory.
- public size_t fill (size_t offset, uint8[] src)
Copies src.length bytes from src to
this at offset.
- public bool find_memory (size_t offset, size_t size, out uint idx, out uint length, out size_t skip)
Finds the memory blocks that span size bytes starting
from offset in this.
- public bool foreach_meta (BufferForeachMetaFunc func)
Calls func with user_data for each meta in
this.
- public Memory? get_all_memory ()
Gets all the memory blocks in this.
- public unowned CustomMeta? get_custom_meta (string name)
Finds the first
CustomMeta on this for the desired name.
- public BufferFlags get_flags ()
- public Memory? get_memory (uint idx)
Gets the memory block at index idx in
this.
- public Memory? get_memory_range (uint idx, int length)
Gets length memory blocks in
this starting at idx.
- public unowned Meta? get_meta (Type api)
Gets the metadata for api on buffer.
- public uint get_n_meta (Type api_type)
- public unowned ReferenceTimestampMeta? get_reference_timestamp_meta (Caps? reference)
- public size_t get_size ()
Gets the total size of the memory blocks in
this.
- public size_t get_sizes (out size_t offset, out size_t maxsize)
Gets the total size of the memory blocks in
this.
- public size_t get_sizes_range (uint idx, int length, out size_t offset, out size_t maxsize)
Gets the total size of length memory blocks stating from
idx in this.
- public bool has_flags (BufferFlags flags)
Gives the status of a specific flag on a buffer.
- public void insert_memory (int idx, owned Memory mem)
Inserts the memory block mem into
this at idx.
- public bool is_all_memory_writable ()
Checks if all memory blocks in this
are writable.
- public bool is_memory_range_writable (uint idx, int length)
Checks if length memory blocks in
this starting from idx are writable.
- public bool map (out MapInfo info, MapFlags flags)
Fills info with the
MapInfo of all merged memory blocks in this.
- public bool map_range (uint idx, int length, out MapInfo info, MapFlags flags)
Fills info with the
MapInfo of length merged memory blocks starting at idx in
this.
- public int memcmp (size_t offset, uint8[] mem)
Compares mem.length bytes starting from offset
in this with the memory in mem.
- public size_t memset (size_t offset, uint8 val, size_t size)
Fills buf with size bytes with val
starting from offset.
- public uint n_memory ()
Gets the amount of memory blocks that this buffer has.
- public unowned Memory? peek_memory (uint idx)
Gets the memory block at idx in
this.
- public void prepend_memory (owned Memory mem)
Prepends the memory block mem to
this.
- public void remove_all_memory ()
Removes all the memory blocks in this
.
- public void remove_memory (uint idx)
Removes the memory block in b at index i.
- public void remove_memory_range (uint idx, int length)
Removes length memory blocks in
this starting from idx.
- public bool remove_meta (Meta meta)
Removes the metadata for meta on
this.
- public void replace_all_memory (owned Memory mem)
Replaces all memory in this with
mem.
- public void replace_memory (uint idx, owned Memory mem)
Replaces the memory block at index idx in
this with mem.
- public void replace_memory_range (uint idx, int length, owned Memory mem)
Replaces length memory blocks in
this starting at idx with mem.
- public void resize (ssize_t offset, ssize_t size)
Sets the offset and total size of the memory blocks in
this.
- public bool resize_range (uint idx, int length, ssize_t offset, ssize_t size)
Sets the total size of the length memory blocks starting
at idx in this
- public bool set_flags (BufferFlags flags)
Sets one or more buffer flags on a buffer.
- public void set_size (ssize_t size)
Sets the total size of the memory blocks in
this.
- public void unmap (MapInfo info)
Releases the memory previously mapped with
map.
- public bool unset_flags (BufferFlags flags)
Clears one or more buffer flags.