GstBuffer

GstBuffer — Data-passing buffer type

Functions

#define GST_BUFFER_FLAGS()
#define GST_BUFFER_FLAG_IS_SET()
#define GST_BUFFER_FLAG_SET()
#define GST_BUFFER_FLAG_UNSET()
#define GST_BUFFER_PTS()
#define GST_BUFFER_DTS()
#define GST_BUFFER_DURATION()
#define GST_BUFFER_OFFSET()
#define GST_BUFFER_OFFSET_END()
#define GST_BUFFER_OFFSET_NONE
#define GST_BUFFER_DURATION_IS_VALID()
#define GST_BUFFER_PTS_IS_VALID()
#define GST_BUFFER_DTS_IS_VALID()
#define GST_BUFFER_OFFSET_IS_VALID()
#define GST_BUFFER_OFFSET_END_IS_VALID()
#define GST_BUFFER_IS_DISCONT()
GstBuffer * gst_buffer_new ()
GstBuffer * gst_buffer_new_allocate ()
GstBuffer * gst_buffer_new_wrapped ()
GstBuffer * gst_buffer_new_wrapped_full ()
GstBuffer * gst_buffer_ref ()
void gst_buffer_unref ()
gsize gst_buffer_get_sizes ()
gsize gst_buffer_get_size ()
gsize gst_buffer_get_sizes_range ()
gboolean gst_buffer_resize_range ()
void gst_buffer_resize ()
void gst_buffer_set_size ()
guint gst_buffer_get_max_memory ()
GstMemory * gst_buffer_peek_memory ()
guint gst_buffer_n_memory ()
void gst_buffer_insert_memory ()
void gst_buffer_replace_memory_range ()
GstMemory * gst_buffer_get_memory_range ()
void gst_buffer_remove_memory_range ()
gboolean gst_buffer_find_memory ()
void gst_buffer_prepend_memory ()
void gst_buffer_append_memory ()
void gst_buffer_replace_memory ()
void gst_buffer_replace_all_memory ()
GstMemory * gst_buffer_get_memory ()
GstMemory * gst_buffer_get_all_memory ()
void gst_buffer_remove_memory ()
void gst_buffer_remove_all_memory ()
gboolean gst_buffer_is_all_memory_writable ()
gboolean gst_buffer_is_memory_range_writable ()
gboolean gst_buffer_map ()
gboolean gst_buffer_map_range ()
void gst_buffer_unmap ()
gint gst_buffer_memcmp ()
gsize gst_buffer_extract ()
void gst_buffer_extract_dup ()
gsize gst_buffer_fill ()
gsize gst_buffer_memset ()
#define GST_BUFFER_COPY_METADATA
#define GST_BUFFER_COPY_ALL
GstBuffer * gst_buffer_copy ()
gboolean gst_buffer_copy_into ()
GstBuffer * gst_buffer_copy_region ()
#define gst_buffer_is_writable()
#define gst_buffer_make_writable()
gboolean gst_buffer_replace ()
GstBuffer * gst_buffer_append ()
GstBuffer * gst_buffer_append_region ()
GstMeta * gst_buffer_get_meta ()
GstMeta * gst_buffer_add_meta ()
gboolean gst_buffer_remove_meta ()
GstMeta * gst_buffer_iterate_meta ()
gboolean (*GstBufferForeachMetaFunc) ()
gboolean gst_buffer_foreach_meta ()

Types and Values

Object Hierarchy

    GBoxed
    ╰── GstBuffer

Includes

#include <gst/gst.h>

Description

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 GstMemory blocks that the buffer contains.

Buffers are usually created with gst_buffer_new(). 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.

1
2
3
4
5
6
7
8
9
GstBuffer *buffer;
GstMemory *memory;
gint size, width, height, bpp;
...
size = width * height * bpp;
buffer = gst_buffer_new ();
memory = gst_allocator_alloc (NULL, size, NULL);
gst_buffer_insert_memory (buffer, -1, memory);
...

Alternatively, use gst_buffer_new_allocate() to create a buffer with preallocated data of a given size.

Buffers can contain a list of GstMemory objects. You can retrieve how many memory objects with gst_buffer_n_memory() and you can get a pointer to memory with gst_buffer_peek_memory()

A buffer will usually have timestamps, and a duration, but neither of these are guaranteed (they may be set to GST_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 GstClockTime 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 GST_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 gst_buffer_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 GstBufferFlags flag is set.

Buffers can be efficiently merged into a larger buffer with gst_buffer_append(). Copying of memory will only be done when absolutely needed.

Arbitrary extra metadata can be set on a buffer with gst_buffer_add_meta(). Metadata can be retrieved with gst_buffer_get_meta(). See also GstMeta

An element should either unref the buffer or push it out on a src pad using gst_pad_push() (see GstPad).

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 GstBufferPool will be returned to the pool when the refcount drops to 0.

Functions

GST_BUFFER_FLAGS()

#define GST_BUFFER_FLAGS(buf)                   GST_MINI_OBJECT_FLAGS(buf)

A flags word containing GstBufferFlags flags set on this buffer.

Parameters

buf

a GstBuffer.

 

GST_BUFFER_FLAG_IS_SET()

#define GST_BUFFER_FLAG_IS_SET(buf,flag)        GST_MINI_OBJECT_FLAG_IS_SET (buf, flag)

Gives the status of a specific flag on a buffer.

Parameters

buf

a GstBuffer.

 

flag

the GstBufferFlags flag to check.

 

GST_BUFFER_FLAG_SET()

#define GST_BUFFER_FLAG_SET(buf,flag)           GST_MINI_OBJECT_FLAG_SET (buf, flag)

Sets a buffer flag on a buffer.

Parameters

buf

a GstBuffer.

 

flag

the GstBufferFlags flag to set.

 

GST_BUFFER_FLAG_UNSET()

#define GST_BUFFER_FLAG_UNSET(buf,flag)         GST_MINI_OBJECT_FLAG_UNSET (buf, flag)

Clears a buffer flag.

Parameters

buf

a GstBuffer.

 

flag

the GstBufferFlags flag to clear.

 

GST_BUFFER_PTS()

#define GST_BUFFER_PTS(buf)                     (GST_BUFFER_CAST(buf)->pts)

The presentation timestamp (pts) in nanoseconds (as a GstClockTime) of the data in the buffer. This is the timestamp when the media should be presented to the user. Value will be GST_CLOCK_TIME_NONE if the pts is unknown.

Parameters

buf

a GstBuffer.:

 

GST_BUFFER_DTS()

#define GST_BUFFER_DTS(buf)                     (GST_BUFFER_CAST(buf)->dts)

The decoding timestamp (dts) in nanoseconds (as a GstClockTime) of the data in the buffer. This is the timestamp when the media should be decoded or processed otherwise. Value will be GST_CLOCK_TIME_NONE if the dts is unknown.

Parameters

buf

a GstBuffer.:

 

GST_BUFFER_DURATION()

#define GST_BUFFER_DURATION(buf)                (GST_BUFFER_CAST(buf)->duration)

The duration in nanoseconds (as a GstClockTime) of the data in the buffer. Value will be GST_CLOCK_TIME_NONE if the duration is unknown.

Parameters

buf

a GstBuffer.

 

GST_BUFFER_OFFSET()

#define GST_BUFFER_OFFSET(buf)                  (GST_BUFFER_CAST(buf)->offset)

The offset in the source file of the beginning of this buffer.

Parameters

buf

a GstBuffer.

 

GST_BUFFER_OFFSET_END()

#define GST_BUFFER_OFFSET_END(buf)              (GST_BUFFER_CAST(buf)->offset_end)

The offset in the source file of the end of this buffer.

Parameters

buf

a GstBuffer.

 

GST_BUFFER_OFFSET_NONE

#define GST_BUFFER_OFFSET_NONE  ((guint64)-1)

Constant for no-offset return results.


GST_BUFFER_DURATION_IS_VALID()

#define GST_BUFFER_DURATION_IS_VALID(buffer)    (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))

Tests if the duration is known.

Parameters

buffer

a GstBuffer

 

GST_BUFFER_PTS_IS_VALID()

#define GST_BUFFER_PTS_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_PTS (buffer)))

Tests if the pts is known.

Parameters

buffer

a GstBuffer

 

GST_BUFFER_DTS_IS_VALID()

#define GST_BUFFER_DTS_IS_VALID(buffer)   (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DTS (buffer)))

Tests if the dts is known.

Parameters

buffer

a GstBuffer

 

GST_BUFFER_OFFSET_IS_VALID()

#define GST_BUFFER_OFFSET_IS_VALID(buffer)      (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)

Tests if the start offset is known.

Parameters

buffer

a GstBuffer

 

GST_BUFFER_OFFSET_END_IS_VALID()

#define GST_BUFFER_OFFSET_END_IS_VALID(buffer)  (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)

Tests if the end offset is known.

Parameters

buffer

a GstBuffer

 

GST_BUFFER_IS_DISCONT()

#define GST_BUFFER_IS_DISCONT(buffer)   (GST_BUFFER_FLAG_IS_SET (buffer, GST_BUFFER_FLAG_DISCONT))

Tests if the buffer marks a discontinuity in the stream.

Parameters

buffer

a GstBuffer

 

gst_buffer_new ()

GstBuffer *
gst_buffer_new (void);

Creates a newly allocated buffer without any data.

MT safe.

Returns

the new GstBuffer.

[transfer full]


gst_buffer_new_allocate ()

GstBuffer *
gst_buffer_new_allocate (GstAllocator *allocator,
                         gsize size,
                         GstAllocationParams *params);

Tries to create a newly allocated buffer with data of the given size and extra parameters from allocator . If the requested amount of memory can't be allocated, NULL will be returned. The allocated buffer memory is not cleared.

When allocator is NULL, the default memory allocator will be used.

Note that when size == 0, the buffer will not have memory associated with it.

MT safe.

Parameters

allocator

the GstAllocator to use, or NULL to use the default allocator.

[transfer none][allow-none]

size

the size in bytes of the new buffer's data.

 

params

optional parameters.

[transfer none][allow-none]

Returns

a new GstBuffer, or NULL if the memory couldn't be allocated.

[transfer full][nullable]


gst_buffer_new_wrapped ()

GstBuffer *
gst_buffer_new_wrapped (gpointer data,
                        gsize size);

Creates a new buffer that wraps the given data . The memory will be freed with g_free and will be marked writable.

MT safe.

Parameters

data

data to wrap.

[array length=size][element-type guint8][transfer full]

size

allocated size of data

 

Returns

a new GstBuffer.

[transfer full]


gst_buffer_new_wrapped_full ()

GstBuffer *
gst_buffer_new_wrapped_full (GstMemoryFlags flags,
                             gpointer data,
                             gsize maxsize,
                             gsize offset,
                             gsize size,
                             gpointer user_data,
                             GDestroyNotify notify);

Allocate a new buffer that wraps the given memory. data must point to maxsize of memory, the wrapped buffer will have the region from offset and size visible.

When the buffer is destroyed, notify will be called with user_data .

The prefix/padding must be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

Parameters

flags

GstMemoryFlags

 

data

data to wrap.

[array length=size][element-type guint8][transfer none]

maxsize

allocated size of data

 

offset

offset in data

 

size

size of valid data

 

user_data

user_data.

[allow-none]

notify

called with user_data when the memory is freed.

[allow-none][scope async][closure user_data]

Returns

a new GstBuffer.

[transfer full]


gst_buffer_ref ()

GstBuffer *
gst_buffer_ref (GstBuffer *buf);

Increases the refcount of the given buffer by one.

Note that the refcount affects the writability of buf and its metadata, see gst_buffer_is_writable(). It is important to note that keeping additional references to GstBuffer instances can potentially increase the number of memcpy operations in a pipeline.

Parameters

buf

a GstBuffer.

 

Returns

buf .

[transfer full]


gst_buffer_unref ()

void
gst_buffer_unref (GstBuffer *buf);

Decreases the refcount of the buffer. If the refcount reaches 0, the buffer with the associated metadata and memory will be freed.

Parameters

buf

a GstBuffer.

[transfer full]

gst_buffer_get_sizes ()

gsize
gst_buffer_get_sizes (GstBuffer *buffer,
                      gsize *offset,
                      gsize *maxsize);

Get the total size of the memory blocks in b .

When not NULL, offset will contain the offset of the data in the first memory block in buffer and maxsize will contain the sum of the size and offset and the amount of extra padding on the last memory block. offset and maxsize can be used to resize the buffer memory blocks with gst_buffer_resize().

Parameters

buffer

a GstBuffer.

 

offset

a pointer to the offset.

[out][allow-none]

maxsize

a pointer to the maxsize.

[out][allow-none]

Returns

total size of the memory blocks in buffer .


gst_buffer_get_size ()

gsize
gst_buffer_get_size (GstBuffer *buffer);

Get the total size of the memory blocks in buffer .

Parameters

buffer

a GstBuffer.

 

Returns

total size of the memory blocks in buffer .


gst_buffer_get_sizes_range ()

gsize
gst_buffer_get_sizes_range (GstBuffer *buffer,
                            guint idx,
                            gint length,
                            gsize *offset,
                            gsize *maxsize);

Get the total size of length memory blocks stating from idx in buffer .

When not NULL, offset will contain the offset of the data in the memory block in buffer at idx and maxsize will contain the sum of the size and offset and the amount of extra padding on the memory block at idx + length -1. offset and maxsize can be used to resize the buffer memory blocks with gst_buffer_resize_range().

Parameters

buffer

a GstBuffer.

 

idx

an index

 

length

a length

 

offset

a pointer to the offset.

[out][allow-none]

maxsize

a pointer to the maxsize.

[out][allow-none]

Returns

total size of length memory blocks starting at idx in buffer .


gst_buffer_resize_range ()

gboolean
gst_buffer_resize_range (GstBuffer *buffer,
                         guint idx,
                         gint length,
                         gssize offset,
                         gssize size);

Set the total size of the length memory blocks starting at idx in buffer

Parameters

buffer

a GstBuffer.

 

idx

an index

 

length

a length

 

offset

the offset adjustment

 

size

the new size or -1 to just adjust the offset

 

Returns

TRUE if resizing succeeded, FALSE otherwise.


gst_buffer_resize ()

void
gst_buffer_resize (GstBuffer *buffer,
                   gssize offset,
                   gssize size);

Set the offset and total size of the memory blocks in buffer .

Parameters

buffer

a GstBuffer.

 

offset

the offset adjustment

 

size

the new size or -1 to just adjust the offset

 

gst_buffer_set_size ()

void
gst_buffer_set_size (GstBuffer *buffer,
                     gssize size);

Set the total size of the memory blocks in buffer .

Parameters

buffer

a GstBuffer.

 

size

the new size

 

gst_buffer_get_max_memory ()

guint
gst_buffer_get_max_memory (void);

Get the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function.

When more memory blocks are added, existing memory blocks will be merged together to make room for the new block.

Returns

the maximum amount of memory blocks that a buffer can hold.

Since 1.2


gst_buffer_peek_memory ()

GstMemory *
gst_buffer_peek_memory (GstBuffer *buffer,
                        guint idx);

Get the memory block at idx in buffer . The memory block stays valid until the memory block in buffer is removed, replaced or merged, typically with any call that modifies the memory in buffer .

Parameters

buffer

a GstBuffer.

 

idx

an index

 

Returns

the GstMemory at idx .

[transfer none]


gst_buffer_n_memory ()

guint
gst_buffer_n_memory (GstBuffer *buffer);

Get the amount of memory blocks that this buffer has. This amount is never larger than what gst_buffer_get_max_memory() returns.

Parameters

buffer

a GstBuffer.

 

Returns

the amount of memory block in this buffer.

[transfer full]


gst_buffer_insert_memory ()

void
gst_buffer_insert_memory (GstBuffer *buffer,
                          gint idx,
                          GstMemory *mem);

Insert the memory block mem to buffer at idx . This function takes ownership of mem and thus doesn't increase its refcount.

Only gst_buffer_get_max_memory() can be added to a buffer. If more memory is added, existing memory blocks will automatically be merged to make room for the new memory.

Parameters

buffer

a GstBuffer.

 

idx

the index to add the memory at, or -1 to append it to the end

 

mem

a GstMemory.

[transfer full]

gst_buffer_replace_memory_range ()

void
gst_buffer_replace_memory_range (GstBuffer *buffer,
                                 guint idx,
                                 gint length,
                                 GstMemory *mem);

Replaces length memory blocks in buffer starting at idx with mem .

If length is -1, all memory starting from idx will be removed and replaced with mem .

buffer should be writable.

Parameters

buffer

a GstBuffer.

 

idx

an index

 

length

a length should not be 0

 

mem

a GstMemory.

[transfer full]

gst_buffer_get_memory_range ()

GstMemory *
gst_buffer_get_memory_range (GstBuffer *buffer,
                             guint idx,
                             gint length);

Get length memory blocks in buffer starting at idx . The memory blocks will be merged into one large GstMemory.

If length is -1, all memory starting from idx is merged.

Parameters

buffer

a GstBuffer.

 

idx

an index

 

length

a length

 

Returns

a GstMemory that contains the merged data of length blocks starting at idx . Use gst_memory_unref() after usage.

[transfer full]


gst_buffer_remove_memory_range ()

void
gst_buffer_remove_memory_range (GstBuffer *buffer,
                                guint idx,
                                gint length);

Remove length memory blocks in buffer starting from idx .

length can be -1, in which case all memory starting from idx is removed.

Parameters

buffer

a GstBuffer.

 

idx

an index

 

length

a length

 

gst_buffer_find_memory ()

gboolean
gst_buffer_find_memory (GstBuffer *buffer,
                        gsize offset,
                        gsize size,
                        guint *idx,
                        guint *length,
                        gsize *skip);

Find the memory blocks that span size bytes starting from offset in buffer .

When this function returns TRUE, idx will contain the index of the first memory bock where the byte for offset can be found and length contains the number of memory blocks containing the size remaining bytes. skip contains the number of bytes to skip in the memory bock at idx to get to the byte for offset .

size can be -1 to get all the memory blocks after idx .

Parameters

buffer

a GstBuffer.

 

offset

an offset

 

size

a size

 

idx

pointer to index.

[out]

length

pointer to length.

[out]

skip

pointer to skip.

[out]

Returns

TRUE when size bytes starting from offset could be found in buffer and idx , length and skip will be filled.


gst_buffer_prepend_memory ()

void
gst_buffer_prepend_memory (GstBuffer *buffer,
                           GstMemory *mem);

Prepend the memory block mem to buffer . This function takes ownership of mem and thus doesn't increase its refcount.

This function is identical to gst_buffer_insert_memory() with an index of 0. See gst_buffer_insert_memory() for more details.

Parameters

buffer

a GstBuffer.

 

mem

a GstMemory.

[transfer full]

gst_buffer_append_memory ()

void
gst_buffer_append_memory (GstBuffer *buffer,
                          GstMemory *mem);

Append the memory block mem to buffer . This function takes ownership of mem and thus doesn't increase its refcount.

This function is identical to gst_buffer_insert_memory() with an index of -1. See gst_buffer_insert_memory() for more details.

Parameters

buffer

a GstBuffer.

 

mem

a GstMemory.

[transfer full]

gst_buffer_replace_memory ()

void
gst_buffer_replace_memory (GstBuffer *buffer,
                           guint idx,
                           GstMemory *mem);

Replaces the memory block at index idx in buffer with mem .

Parameters

buffer

a GstBuffer.

 

idx

an index

 

mem

a GstMemory.

[transfer full]

gst_buffer_replace_all_memory ()

void
gst_buffer_replace_all_memory (GstBuffer *buffer,
                               GstMemory *mem);

Replaces all memory in buffer with mem .

Parameters

buffer

a GstBuffer.

 

mem

a GstMemory.

[transfer full]

gst_buffer_get_memory ()

GstMemory *
gst_buffer_get_memory (GstBuffer *buffer,
                       guint idx);

Get the memory block at index idx in buffer .

Parameters

buffer

a GstBuffer.

 

idx

an index

 

Returns

a GstMemory that contains the data of the memory block at idx . Use gst_memory_unref() after usage.

[transfer full]


gst_buffer_get_all_memory ()

GstMemory *
gst_buffer_get_all_memory (GstBuffer *buffer);

Get all the memory block in buffer . The memory blocks will be merged into one large GstMemory.

Parameters

buffer

a GstBuffer.

 

Returns

a GstMemory that contains the merged memory. Use gst_memory_unref() after usage.

[transfer full]


gst_buffer_remove_memory ()

void
gst_buffer_remove_memory (GstBuffer *buffer,
                          guint idx);

Remove the memory block in b at index i .

Parameters

buffer

a GstBuffer.

 

idx

an index

 

gst_buffer_remove_all_memory ()

void
gst_buffer_remove_all_memory (GstBuffer *buffer);

Remove all the memory blocks in buffer .

Parameters

buffer

a GstBuffer.

 

gst_buffer_is_all_memory_writable ()

gboolean
gst_buffer_is_all_memory_writable (GstBuffer *buffer);

Check if all memory blocks in buffer are writable.

Note that this function does not check if buffer is writable, use gst_buffer_is_writable() to check that if needed.

Parameters

buffer

a GstBuffer.

 

Returns

TRUE if all memory blocks in buffer are writable

Since 1.4


gst_buffer_is_memory_range_writable ()

gboolean
gst_buffer_is_memory_range_writable (GstBuffer *buffer,
                                     guint idx,
                                     gint length);

Check if length memory blocks in buffer starting from idx are writable.

length can be -1 to check all the memory blocks after idx .

Note that this function does not check if buffer is writable, use gst_buffer_is_writable() to check that if needed.

Parameters

buffer

a GstBuffer.

 

idx

an index

 

length

a length should not be 0

 

Returns

TRUE if the memory range is writable

Since 1.4


gst_buffer_map ()

gboolean
gst_buffer_map (GstBuffer *buffer,
                GstMapInfo *info,
                GstMapFlags flags);

This function fills info with the GstMapInfo of all merged memory blocks in buffer .

flags describe the desired access of the memory. When flags is GST_MAP_WRITE, buffer should be writable (as returned from gst_buffer_is_writable()).

When buffer is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

The memory in info should be unmapped with gst_buffer_unmap() after usage.

Parameters

buffer

a GstBuffer.

 

info

info about the mapping.

[out]

flags

flags for the mapping

 

Returns

TRUE if the map succeeded and info contains valid data.


gst_buffer_map_range ()

gboolean
gst_buffer_map_range (GstBuffer *buffer,
                      guint idx,
                      gint length,
                      GstMapInfo *info,
                      GstMapFlags flags);

This function fills info with the GstMapInfo of length merged memory blocks starting at idx in buffer . When length is -1, all memory blocks starting from idx are merged and mapped.

flags describe the desired access of the memory. When flags is GST_MAP_WRITE, buffer should be writable (as returned from gst_buffer_is_writable()).

When buffer is writable but the memory isn't, a writable copy will automatically be created and returned. The readonly copy of the buffer memory will then also be replaced with this writable copy.

The memory in info should be unmapped with gst_buffer_unmap() after usage.

Parameters

buffer

a GstBuffer.

 

idx

an index

 

length

a length

 

info

info about the mapping.

[out]

flags

flags for the mapping

 

Returns

TRUE if the map succeeded and info contains valid data.


gst_buffer_unmap ()

void
gst_buffer_unmap (GstBuffer *buffer,
                  GstMapInfo *info);

Release the memory previously mapped with gst_buffer_map().

Parameters

buffer

a GstBuffer.

 

info

a GstMapInfo

 

gst_buffer_memcmp ()

gint
gst_buffer_memcmp (GstBuffer *buffer,
                   gsize offset,
                   gconstpointer mem,
                   gsize size);

Compare size bytes starting from offset in buffer with the memory in mem .

Parameters

buffer

a GstBuffer.

 

offset

the offset in buffer

 

mem

the memory to compare.

[array length=size][element-type guint8]

size

the size to compare

 

Returns

0 if the memory is equal.


gst_buffer_extract ()

gsize
gst_buffer_extract (GstBuffer *buffer,
                    gsize offset,
                    gpointer dest,
                    gsize size);

Copy size bytes starting from offset in buffer to dest .

Parameters

buffer

a GstBuffer.

 

offset

the offset to extract

 

dest

the destination address

 

size

the size to extract

 

Returns

The amount of bytes extracted. This value can be lower than size when buffer did not contain enough data.


gst_buffer_extract_dup ()

void
gst_buffer_extract_dup (GstBuffer *buffer,
                        gsize offset,
                        gsize size,
                        gpointer *dest,
                        gsize *dest_size);

Extracts a copy of at most size bytes the data at offset into a GBytes. dest must be freed using g_free() when done.

Parameters

buffer

a GstBuffer

 

offset

the offset to extract

 

size

the size to extract

 

dest

A pointer where the destination array will be written.

[array length=dest_size][element-type guint8][out]

dest_size

A location where the size of dest can be written.

[out]

Since 1.0.10


gst_buffer_fill ()

gsize
gst_buffer_fill (GstBuffer *buffer,
                 gsize offset,
                 gconstpointer src,
                 gsize size);

Copy size bytes from src to buffer at offset .

Parameters

buffer

a GstBuffer.

 

offset

the offset to fill

 

src

the source address.

[array length=size][element-type guint8]

size

the size to fill

 

Returns

The amount of bytes copied. This value can be lower than size when buffer did not contain enough data.


gst_buffer_memset ()

gsize
gst_buffer_memset (GstBuffer *buffer,
                   gsize offset,
                   guint8 val,
                   gsize size);

Fill buf with size bytes with val starting from offset .

Parameters

buffer

a GstBuffer.

 

offset

the offset in buffer

 

val

the value to set

 

size

the size to set

 

Returns

The amount of bytes filled. This value can be lower than size when buffer did not contain enough data.


GST_BUFFER_COPY_METADATA

#define             GST_BUFFER_COPY_METADATA

Combination of all possible metadata fields that can be copied with gst_buffer_copy_into().


GST_BUFFER_COPY_ALL

#define GST_BUFFER_COPY_ALL  ((GstBufferCopyFlags)(GST_BUFFER_COPY_METADATA | GST_BUFFER_COPY_MEMORY))

Combination of all possible fields that can be copied with gst_buffer_copy_into().


gst_buffer_copy ()

GstBuffer *
gst_buffer_copy (const GstBuffer *buf);

Create a copy of the given buffer. This will also make a newly allocated copy of the data the source buffer contains.

Parameters

buf

a GstBuffer.

 

Returns

a new copy of buf .

[transfer full]


gst_buffer_copy_into ()

gboolean
gst_buffer_copy_into (GstBuffer *dest,
                      GstBuffer *src,
                      GstBufferCopyFlags flags,
                      gsize offset,
                      gsize size);

Copies the information from src into dest .

If dest already contains memory and flags contains GST_BUFFER_COPY_MEMORY, the memory from src will be appended to dest .

flags indicate which fields will be copied.

Parameters

dest

a destination GstBuffer

 

src

a source GstBuffer

 

flags

flags indicating what metadata fields should be copied.

 

offset

offset to copy from

 

size

total size to copy. If -1, all data is copied.

 

Returns

TRUE if the copying succeeded, FALSE otherwise.


gst_buffer_copy_region ()

GstBuffer *
gst_buffer_copy_region (GstBuffer *parent,
                        GstBufferCopyFlags flags,
                        gsize offset,
                        gsize size);

Creates a sub-buffer from parent at offset and size . This sub-buffer uses the actual memory space of the parent buffer. This function will copy the offset and timestamp fields when the offset is 0. If not, they will be set to GST_CLOCK_TIME_NONE and GST_BUFFER_OFFSET_NONE. If offset equals 0 and size equals the total size of buffer , the duration and offset end fields are also copied. If not they will be set to GST_CLOCK_TIME_NONE and GST_BUFFER_OFFSET_NONE.

MT safe.

Parameters

parent

a GstBuffer.

 

flags

the GstBufferCopyFlags

 

offset

the offset into parent GstBuffer at which the new sub-buffer begins.

 

size

the size of the new GstBuffer sub-buffer, in bytes.

 

Returns

the new GstBuffer or NULL if the arguments were invalid.

[transfer full]


gst_buffer_is_writable()

#define         gst_buffer_is_writable(buf)     gst_mini_object_is_writable (GST_MINI_OBJECT_CAST (buf))

Tests if you can safely write to a buffer's metadata or its memory array. It is only safe to change buffer metadata when the current reference is writable, i.e. nobody can see the modifications you will make.

Parameters

buf

a GstBuffer

 

gst_buffer_make_writable()

#define         gst_buffer_make_writable(buf)   GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT_CAST (buf)))

Makes a writable buffer from the given buffer. If the source buffer is already writable, this will simply return the same buffer. A copy will otherwise be made using gst_buffer_copy().

Parameters

buf

a GstBuffer.

[transfer full]

Returns

a writable buffer which may or may not be the same as buf .

[transfer full]


gst_buffer_replace ()

gboolean
gst_buffer_replace (GstBuffer **obuf,
                    GstBuffer *nbuf);

Modifies a pointer to a GstBuffer to point to a different GstBuffer. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old buffer is unreffed, the new is reffed).

Either nbuf or the GstBuffer pointed to by obuf may be NULL.

Parameters

obuf

pointer to a pointer to a GstBuffer to be replaced.

[inout][transfer full][nullable]

nbuf

pointer to a GstBuffer that will replace the buffer pointed to by obuf .

[transfer none][allow-none]

Returns

TRUE when obuf was different from nbuf .


gst_buffer_append ()

GstBuffer *
gst_buffer_append (GstBuffer *buf1,
                   GstBuffer *buf2);

Append all the memory from buf2 to buf1 . The result buffer will contain a concatenation of the memory of buf1 and buf2 .

Parameters

buf1

the first source GstBuffer to append.

[transfer full]

buf2

the second source GstBuffer to append.

[transfer full]

Returns

the new GstBuffer that contains the memory of the two source buffers.

[transfer full]


gst_buffer_append_region ()

GstBuffer *
gst_buffer_append_region (GstBuffer *buf1,
                          GstBuffer *buf2,
                          gssize offset,
                          gssize size);

Append size bytes at offset from buf2 to buf1 . The result buffer will contain a concatenation of the memory of buf1 and the requested region of buf2 .

Parameters

buf1

the first source GstBuffer to append.

[transfer full]

buf2

the second source GstBuffer to append.

[transfer full]

offset

the offset in buf2

 

size

the size or -1 of buf2

 

Returns

the new GstBuffer that contains the memory of the two source buffers.

[transfer full]


gst_buffer_get_meta ()

GstMeta *
gst_buffer_get_meta (GstBuffer *buffer,
                     GType api);

Get the metadata for api on buffer. When there is no such metadata, NULL is returned.

Parameters

buffer

a GstBuffer

 

api

the GType of an API

 

Returns

the metadata for api on buffer .

[transfer none][nullable]


gst_buffer_add_meta ()

GstMeta *
gst_buffer_add_meta (GstBuffer *buffer,
                     const GstMetaInfo *info,
                     gpointer params);

Add metadata for info to buffer using the parameters in params .

Parameters

buffer

a GstBuffer

 

info

a GstMetaInfo

 

params

params for info

 

Returns

the metadata for the api in info on buffer .

[transfer none]


gst_buffer_remove_meta ()

gboolean
gst_buffer_remove_meta (GstBuffer *buffer,
                        GstMeta *meta);

Remove the metadata for meta on buffer .

Parameters

buffer

a GstBuffer

 

meta

a GstMeta

 

Returns

TRUE if the metadata existed and was removed, FALSE if no such metadata was on buffer .


gst_buffer_iterate_meta ()

GstMeta *
gst_buffer_iterate_meta (GstBuffer *buffer,
                         gpointer *state);

Retrieve the next GstMeta after current . If state points to NULL, the first metadata is returned.

state will be updated with an opaque state pointer

Parameters

buffer

a GstBuffer

 

state

an opaque state pointer

 

Returns

The next GstMeta or NULL when there are no more items.

[transfer none][nullable]


GstBufferForeachMetaFunc ()

gboolean
(*GstBufferForeachMetaFunc) (GstBuffer *buffer,
                             GstMeta **meta,
                             gpointer user_data);

A function that will be called from gst_buffer_foreach_meta(). The meta field will point to a the reference of the meta.

buffer should not be modified from this callback.

When this function returns TRUE, the next meta will be returned. When FALSE is returned, gst_buffer_foreach_meta() will return.

When meta is set to NULL, the item will be removed from the buffer.

Parameters

buffer

a GstBuffer

 

meta

a pointer to a GstMeta.

[out][nullable]

user_data

user data passed to gst_buffer_foreach_meta()

 

Returns

FALSE when gst_buffer_foreach_meta() should stop


gst_buffer_foreach_meta ()

gboolean
gst_buffer_foreach_meta (GstBuffer *buffer,
                         GstBufferForeachMetaFunc func,
                         gpointer user_data);

Call func with user_data for each meta in buffer .

func can modify the passed meta pointer or its contents. The return value of func define if this function returns or if the remaining metadata items in the buffer should be skipped.

Parameters

buffer

a GstBuffer

 

func

a GstBufferForeachMetaFunc to call.

[scope call]

user_data

user data passed to func .

[closure]

Returns

FALSE when func returned FALSE for one of the metadata.

Types and Values

struct GstBuffer

struct GstBuffer {
  GstMiniObject          mini_object;

  GstBufferPool         *pool;

  /* timestamp */
  GstClockTime           pts;
  GstClockTime           dts;
  GstClockTime           duration;

  /* media specific offset */
  guint64                offset;
  guint64                offset_end;
};

The structure of a GstBuffer. Use the associated macros to access the public variables.

Members

GstMiniObject mini_object;

the parent structure

 

GstBufferPool *pool;

pointer to the pool owner of the buffer

 

GstClockTime pts;

presentation timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the pts is not known or relevant. The pts contains the timestamp when the media should be presented to the user.

 

GstClockTime dts;

decoding timestamp of the buffer, can be GST_CLOCK_TIME_NONE when the dts is not known or relevant. The dts contains the timestamp when the media should be processed.

 

GstClockTime duration;

duration in time of the buffer data, can be GST_CLOCK_TIME_NONE when the duration is not known or relevant.

 

guint64 offset;

a media specific offset for the buffer data. For video frames, this is the frame number of this buffer. For audio samples, this is the offset of the first sample in this buffer. For file data or compressed data this is the byte offset of the first byte in this buffer.

 

guint64 offset_end;

the last offset contained in this buffer. It has the same format as offset .

 

enum GstBufferFlags

A set of buffer flags used to describe properties of a GstBuffer.

Members

GST_BUFFER_FLAG_LIVE

the buffer is live data and should be discarded in the PAUSED state.

 

GST_BUFFER_FLAG_DECODE_ONLY

the buffer contains data that should be dropped because it will be clipped against the segment boundaries or because it does not contain data that should be shown to the user.

 

GST_BUFFER_FLAG_DISCONT

the buffer marks a data discontinuity in the stream. This typically occurs after a seek or a dropped buffer from a live or network source.

 

GST_BUFFER_FLAG_RESYNC

the buffer timestamps might have a discontinuity and this buffer is a good point to resynchronize.

 

GST_BUFFER_FLAG_CORRUPTED

the buffer data is corrupted.

 

GST_BUFFER_FLAG_MARKER

the buffer contains a media specific marker. for video this is typically the end of a frame boundary, for audio this is usually the start of a talkspurt.

 

GST_BUFFER_FLAG_HEADER

the buffer contains header information that is needed to decode the following data.

 

GST_BUFFER_FLAG_GAP

the buffer has been created to fill a gap in the stream and contains media neutral data (elements can switch to optimized code path that ignores the buffer content).

 

GST_BUFFER_FLAG_DROPPABLE

the buffer can be dropped without breaking the stream, for example to reduce bandwidth.

 

GST_BUFFER_FLAG_DELTA_UNIT

this unit cannot be decoded independently.

 

GST_BUFFER_FLAG_TAG_MEMORY

this flag is set when memory of the buffer is added/removed

 

GST_BUFFER_FLAG_LAST

additional media specific flags can be added starting from this flag.

 

enum GstBufferCopyFlags

A set of flags that can be provided to the gst_buffer_copy_into() function to specify which items should be copied.

Members

GST_BUFFER_COPY_NONE

copy nothing

 

GST_BUFFER_COPY_FLAGS

flag indicating that buffer flags should be copied

 

GST_BUFFER_COPY_TIMESTAMPS

flag indicating that buffer pts, dts, duration, offset and offset_end should be copied

 

GST_BUFFER_COPY_META

flag indicating that buffer meta should be copied

 

GST_BUFFER_COPY_MEMORY

flag indicating that buffer memory should be reffed and appended to already existing memory. Unless the memory is marked as NO_SHARE, no actual copy of the memory is made but it is simply reffed. Add GST_BUFFER_COPY_DEEP to force a real copy.

 

GST_BUFFER_COPY_MERGE

flag indicating that buffer memory should be merged

 

GST_BUFFER_COPY_DEEP

flag indicating that memory should always be copied instead of reffed (Since 1.2)

 

See Also

GstPad, GstMiniObject, GstMemory, GstMeta, GstBufferPool