GST_BUFFER_FLAGS()

#define GST_BUFFER_FLAGS(buf)                   GST_MINI_OBJECT_FLAGS(buf)

A flags word containing GstBufferFlags flags set on this buffer.

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.

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.

GST_BUFFER_FLAG_UNSET()

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

Clears a buffer flag.

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.

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.

GST_BUFFER_DTS_OR_PTS()

#define GST_BUFFER_DTS_OR_PTS(buf)              (GST_BUFFER_DTS_IS_VALID(buf) ? GST_BUFFER_DTS(buf) : GST_BUFFER_PTS (buf))

Returns the buffer decoding timestamp (dts) if valid, else the buffer presentation time (pts)

Since: 1.8

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.

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.

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.

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.

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.

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.

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.

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.

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.

gst_buffer_new ()

GstBuffer *
gst_buffer_new (void);

Creates a newly allocated buffer without any data.

MT safe.

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.

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.

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.

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.

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.

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().

gst_buffer_get_size ()

gsize
gst_buffer_get_size (GstBuffer *buffer);

Get the 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().

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

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 .

gst_buffer_set_size ()

void
gst_buffer_set_size (GstBuffer *buffer,
                     gssize size);

Set the total size of the memory blocks in buffer .

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.

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 .

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.

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.

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.

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.

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.

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 block 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 block at idx to get to the byte for offset .

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

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.

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.

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 .

gst_buffer_replace_all_memory ()

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

Replaces all memory in buffer with mem .

gst_buffer_get_memory ()

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

Get the memory block at index idx in buffer .

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.

gst_buffer_remove_memory ()

void
gst_buffer_remove_memory (GstBuffer *buffer,
                          guint idx);

Remove the memory block in b at index i .

gst_buffer_remove_all_memory ()

void
gst_buffer_remove_all_memory (GstBuffer *buffer);

Remove all the memory blocks in buffer .

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.

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.

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.

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.

gst_buffer_unmap ()

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

Release the memory previously mapped with gst_buffer_map().

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 .

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 .

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 newly-allocated memory. dest must be freed using g_free() when done.

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 .

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 .

gst_buffer_copy ()

GstBuffer *
gst_buffer_copy (const GstBuffer *buf);

Create a copy of the given buffer. This will only copy the buffer's data to a newly allocated memory if needed (if the type of memory requires it), otherwise the underlying data is just referenced. Check gst_buffer_copy_deep() if you want to force the data to be copied to newly allocated memory.

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.

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.

gst_buffer_copy_deep ()

GstBuffer *
gst_buffer_copy_deep (const GstBuffer *buf);

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

Since: 1.6

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.

gst_buffer_make_writable()

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

Returns a writable copy of buf . If the source buffer is already writable, this will simply return the same buffer.

Use this function to ensure that a buffer can be safely modified before making changes to it, including changing the metadata such as PTS/DTS.

If the reference count of the source buffer buf is exactly one, the caller is the sole owner and this function will return the buffer object unchanged.

If there is more than one reference on the object, a copy will be made using gst_buffer_copy(). The passed-in buf will be unreffed in that case, and the caller will now own a reference to the new returned buffer object. Note that this just copies the buffer structure itself, the underlying memory is not copied if it can be shared amongst multiple buffers.

In short, this function unrefs the buf in the argument and refs the buffer that it returns. Don't access the argument after calling this function unless you have an additional reference to it.

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.

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 .

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 .

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. If multiple metadata with the given api are attached to this buffer only the first one is returned. To handle multiple metadata with a given API use gst_buffer_iterate_meta() or gst_buffer_foreach_meta() instead and check the meta->info.api member for the API type.

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 .

gst_buffer_remove_meta ()

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

Remove the metadata for meta 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

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.

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.

gst_buffer_add_parent_buffer_meta ()

GstParentBufferMeta *
gst_buffer_add_parent_buffer_meta (GstBuffer *buffer,
                                   GstBuffer *ref);

Add a GstParentBufferMeta to buffer that holds a reference on ref until the buffer is freed.

Since: 1.6

gst_buffer_get_parent_buffer_meta()

#define             gst_buffer_get_parent_buffer_meta(b)

Find and return a GstParentBufferMeta if one exists on the buffer

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.

enum GstBufferFlags

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

GST_BUFFER_OFFSET_NONE

#define GST_BUFFER_OFFSET_NONE  ((guint64)-1)

Constant for no-offset return results.

enum GstBufferCopyFlags

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

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().

struct GstParentBufferMeta

struct GstParentBufferMeta {
  GstMeta parent;

  GstBuffer *buffer;
};

The GstParentBufferMeta is a GstMeta which can be attached to a GstBuffer to hold a reference to another buffer that is only released when the child GstBuffer is released.

Typically, GstParentBufferMeta is used when the child buffer is directly using the GstMemory of the parent buffer, and wants to prevent the parent buffer from being returned to a buffer pool until the GstMemory is available for re-use.

Since: 1.6