GstBuffer

GstBuffer — Data-passing buffer type, supporting sub-buffers.

Synopsis

#include <gst/gst.h>

struct              GstBuffer;
enum                GstBufferFlags;
enum                GstBufferCopyFlags;
#define             GST_BUFFER_FLAGS                    (buf)
#define             GST_BUFFER_FLAG_IS_SET              (buf,
                                                         flag)
#define             GST_BUFFER_FLAG_SET                 (buf,
                                                         flag)
#define             GST_BUFFER_FLAG_UNSET               (buf,
                                                         flag)
#define             GST_BUFFER_PTS                      (buf)
#define             GST_BUFFER_DTS                      (buf)
#define             GST_BUFFER_DURATION                 (buf)
#define             GST_BUFFER_OFFSET                   (buf)
#define             GST_BUFFER_OFFSET_END               (buf)
#define             GST_BUFFER_OFFSET_NONE
#define             GST_BUFFER_DURATION_IS_VALID        (buffer)
#define             GST_BUFFER_PTS_IS_VALID             (buffer)
#define             GST_BUFFER_DTS_IS_VALID             (buffer)
#define             GST_BUFFER_OFFSET_IS_VALID          (buffer)
#define             GST_BUFFER_OFFSET_END_IS_VALID      (buffer)
#define             GST_BUFFER_IS_DISCONT               (buffer)
GstBuffer *         gst_buffer_new                      (void);
#define             gst_buffer_new_and_alloc            (s)
GstBuffer *         gst_buffer_new_allocate             (GstAllocator *allocator,
                                                         gsize size,
                                                         GstAllocationParams *params);
GstBuffer *         gst_buffer_new_wrapped              (gpointer data,
                                                         gsize size);
GstBuffer *         gst_buffer_new_wrapped_full         (GstMemoryFlags flags,
                                                         gpointer data,
                                                         gsize maxsize,
                                                         gsize offset,
                                                         gsize size,
                                                         gpointer user_data,
                                                         GDestroyNotify notify);
GstBuffer *         gst_buffer_ref                      (GstBuffer *buf);
void                gst_buffer_unref                    (GstBuffer *buf);
gsize               gst_buffer_get_sizes                (GstBuffer *buffer,
                                                         gsize *offset,
                                                         gsize *maxsize);
#define             gst_buffer_get_size                 (b)
void                gst_buffer_resize                   (GstBuffer *buffer,
                                                         gssize offset,
                                                         gssize size);
#define             gst_buffer_set_size                 (b,
                                                         s)
guint               gst_buffer_n_memory                 (GstBuffer *buffer);
void                gst_buffer_take_memory              (GstBuffer *buffer,
                                                         gint idx,
                                                         GstMemory *mem);
#define             gst_buffer_append_memory            (b,
                                                         m)
GstMemory *         gst_buffer_get_memory               (GstBuffer *buffer,
                                                         gint idx);
#define             gst_buffer_get_merged_memory        (b)
#define             gst_buffer_remove_memory            (b,
                                                         i)
void                gst_buffer_remove_memory_range      (GstBuffer *buffer,
                                                         guint idx,
                                                         gint length);
#define             gst_buffer_remove_all_memory        (b)
#define             gst_buffer_replace_all_memory       (b,
                                                         m)
void                gst_buffer_replace_memory           (GstBuffer *buffer,
                                                         gint idx,
                                                         GstMemory *mem);
GstBuffer *         gst_buffer_join                     (GstBuffer *buf1,
                                                         GstBuffer *buf2);
GstBuffer *         gst_buffer_merge                    (GstBuffer *buf1,
                                                         GstBuffer *buf2);
gboolean            gst_buffer_map                      (GstBuffer *buffer,
                                                         GstMapInfo *info,
                                                         GstMapFlags flags);
void                gst_buffer_unmap                    (GstBuffer *buffer,
                                                         GstMapInfo *info);
gint                gst_buffer_memcmp                   (GstBuffer *buffer,
                                                         gsize offset,
                                                         gconstpointer mem,
                                                         gsize size);
gsize               gst_buffer_extract                  (GstBuffer *buffer,
                                                         gsize offset,
                                                         gpointer dest,
                                                         gsize size);
gsize               gst_buffer_fill                     (GstBuffer *buffer,
                                                         gsize offset,
                                                         gconstpointer src,
                                                         gsize size);
gsize               gst_buffer_memset                   (GstBuffer *buffer,
                                                         gsize offset,
                                                         guint8 val,
                                                         gsize size);
#define             GST_BUFFER_COPY_METADATA
#define             GST_BUFFER_COPY_ALL
GstBuffer *         gst_buffer_copy                     (const GstBuffer *buf);
void                gst_buffer_copy_into                (GstBuffer *dest,
                                                         GstBuffer *src,
                                                         GstBufferCopyFlags flags,
                                                         gsize offset,
                                                         gsize size);
GstBuffer *         gst_buffer_copy_region              (GstBuffer *parent,
                                                         GstBufferCopyFlags flags,
                                                         gsize offset,
                                                         gsize size);
#define             gst_buffer_is_writable              (buf)
#define             gst_buffer_make_writable            (buf)
gboolean            gst_buffer_replace                  (GstBuffer **obuf,
                                                         GstBuffer *nbuf);
gboolean            gst_buffer_is_span_fast             (GstBuffer *buf1,
                                                         GstBuffer *buf2);
GstBuffer *         gst_buffer_span                     (GstBuffer *buf1,
                                                         gsize offset,
                                                         GstBuffer *buf2,
                                                         gsize size);
GstMeta *           gst_buffer_get_meta                 (GstBuffer *buffer,
                                                         GType api);
GstMeta *           gst_buffer_add_meta                 (GstBuffer *buffer,
                                                         const GstMetaInfo *info,
                                                         gpointer params);
gboolean            gst_buffer_remove_meta              (GstBuffer *buffer,
                                                         GstMeta *meta);
GstMeta *           gst_buffer_iterate_meta             (GstBuffer *buffer,
                                                         gpointer *state);

Description

Buffers are the basic unit of data transfer in GStreamer. The GstBuffer type provides all the state necessary to define the regions of memory as part of a stream. Region copies are also supported, allowing a smaller region of a buffer to become its own buffer, with mechanisms in place to ensure that neither memory space goes away prematurely.

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.

Example 3. Creating a buffer for a video frame

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

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 GstCaps set on it). 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.

To efficiently create a smaller buffer out of an existing one, you can use gst_buffer_copy_region().

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 GstBufferFlag is set.

Buffers can be efficiently merged into a larger buffer with gst_buffer_span(), which avoids memory copies when the gst_buffer_is_span_fast() function returns TRUE.

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 data pointed to by the buffer is unreffed as well.

Last reviewed on November 8, 2011 (0.11.2)

Details

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.

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

typedef enum {
  GST_BUFFER_FLAG_LIVE        = (GST_MINI_OBJECT_FLAG_LAST << 0),
  GST_BUFFER_FLAG_DECODE_ONLY = (GST_MINI_OBJECT_FLAG_LAST << 1),
  GST_BUFFER_FLAG_DISCONT     = (GST_MINI_OBJECT_FLAG_LAST << 2),
  GST_BUFFER_FLAG_RESYNC      = (GST_MINI_OBJECT_FLAG_LAST << 3),
  GST_BUFFER_FLAG_CORRUPTED   = (GST_MINI_OBJECT_FLAG_LAST << 4),
  GST_BUFFER_FLAG_MARKER      = (GST_MINI_OBJECT_FLAG_LAST << 5),
  GST_BUFFER_FLAG_HEADER      = (GST_MINI_OBJECT_FLAG_LAST << 6),
  GST_BUFFER_FLAG_GAP         = (GST_MINI_OBJECT_FLAG_LAST << 7),
  GST_BUFFER_FLAG_DROPPABLE   = (GST_MINI_OBJECT_FLAG_LAST << 8),
  GST_BUFFER_FLAG_DELTA_UNIT  = (GST_MINI_OBJECT_FLAG_LAST << 9),

  GST_BUFFER_FLAG_LAST        = (GST_MINI_OBJECT_FLAG_LAST << 16)
} GstBufferFlags;

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

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 end of a talkspurt.

GST_BUFFER_FLAG_HEADER

the buffer contains header information that is needed to decode the following data. The buffer is also part of the headers of the STREAM_CONFIG event.

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_LAST

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

enum GstBufferCopyFlags

typedef enum {
  GST_BUFFER_COPY_NONE           = 0,
  GST_BUFFER_COPY_FLAGS          = (1 << 0),
  GST_BUFFER_COPY_TIMESTAMPS     = (1 << 1),
  GST_BUFFER_COPY_META           = (1 << 2),
  GST_BUFFER_COPY_MEMORY         = (1 << 3),
  GST_BUFFER_COPY_MERGE          = (1 << 4)
} 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_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 copied and appended to already existing memory

GST_BUFFER_COPY_MERGE

flag indicating that buffer memory should be merged

GST_BUFFER_FLAGS()

#define GST_BUFFER_FLAGS(buf)                   GST_MINI_OBJECT_FLAGS(buf)

A flags word containing GstBufferFlag flags set on this buffer.

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.

buf :

a GstBuffer.

flag :

the GstBufferFlag 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.

buf :

a GstBuffer.

flag :

the GstBufferFlag to set.

GST_BUFFER_FLAG_UNSET()

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

Clears a buffer flag.

buf :

a GstBuffer.

flag :

the GstBufferFlag 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

buffer :

a GstBuffer

Since 0.10.9


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

#define gst_buffer_new_and_alloc(s)            gst_buffer_new_allocate(NULL, s, NULL)

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.

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]

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.

data :

data to wrap

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.

flags :

GstMemoryFlags

data :

data to wrap

maxsize :

allocated size of data

offset :

offset in data

size :

size of valid data

user_data :

user_data

notify :

called with user_data when the memory is freed

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 writeability of buf and its metadata, see gst_buffer_is_writable() and gst_buffer_is_metadata_writable(). It is important to note that keeping additional references to GstBuffer instances can potentially increase the number of memcpy operations in a pipeline.

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.

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 all memory blocks in buffer.

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

buffer :

a GstBuffer.

offset :

a pointer to the offset

maxsize :

a pointer to the maxsize

Returns :

the total size of the memory in buffer.

gst_buffer_get_size()

#define     gst_buffer_get_size(b)         gst_buffer_get_sizes ((b), NULL, NULL)

Get the size of b.

b :

a GstBuffer.

gst_buffer_resize ()

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

Set the total size of the buffer

buffer :

a GstBuffer.

offset :

the offset adjustement

size :

the new size or -1 to just adjust the offset

gst_buffer_set_size()

#define     gst_buffer_set_size(b,s)       gst_buffer_resize ((b), 0, (s))

Set the size of b to s. This will remove or trim the memory blocks in the buffer.

b :

a GstBuffer.

s :

a new size

gst_buffer_n_memory ()

guint               gst_buffer_n_memory                 (GstBuffer *buffer);

Get the amount of memory blocks that this buffer has.

buffer :

a GstBuffer.

Returns :

the amount of memory block in this buffer. [transfer full]

gst_buffer_take_memory ()

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

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

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

#define     gst_buffer_append_memory(b,m)      gst_buffer_take_memory ((b), -1, (m))

gst_buffer_get_memory ()

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

Get the memory block in buffer at idx. If idx is -1, all memory is merged into one large GstMemory object that is then returned.

buffer :

a GstBuffer.

idx :

an index

Returns :

a GstMemory at idx. Use gst_memory_unref() after usage. [transfer full]

gst_buffer_get_merged_memory()

#define     gst_buffer_get_merged_memory(b)    gst_buffer_get_memory ((b), -1)

gst_buffer_remove_memory()

#define     gst_buffer_remove_memory(b,i)      gst_buffer_remove_memory_range ((b), (i), 1)

Remove the memory block in b at i.

b :

a GstBuffer.

i :

an index

gst_buffer_remove_memory_range ()

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

Remove len memory blocks in buffer starting from idx.

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

buffer :

a GstBuffer.

idx :

an index

length :

a length

gst_buffer_remove_all_memory()

#define     gst_buffer_remove_all_memory(b)    gst_buffer_remove_memory_range ((b), 0, -1)

gst_buffer_replace_all_memory()

#define     gst_buffer_replace_all_memory(b,m) gst_buffer_replace_memory ((b), -1, (m))

gst_buffer_replace_memory ()

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

Replaces the memory block in buffer at idx with mem. If idx is -1, all memory will be removed and replaced with mem.

buffer should be writable.

buffer :

a GstBuffer.

idx :

an index

mem :

a GstMemory. [transfer full]

gst_buffer_join ()

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

Create a new buffer that is the concatenation of the two source buffers, and unrefs the original source buffers.

If the buffers point to contiguous areas of memory, the buffer is created without copying the data.

This is a convenience function for C programmers. See also gst_buffer_merge(), which does the same thing without unreffing the input parameters. Language bindings without explicit reference counting should not wrap this function.

buf1 :

the first source GstBuffer. [transfer full]

buf2 :

the second source GstBuffer. [transfer full]

Returns :

the new GstBuffer which is the concatenation of the source buffers. [transfer full]

gst_buffer_merge ()

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

Create a new buffer that is the concatenation of the two source buffers. The original source buffers will not be modified or unref'd. Make sure you unref the source buffers if they are not used anymore afterwards.

If the buffers point to contiguous areas of memory, the buffer is created without copying the data.

Free-function: gst_buffer_unref

buf1 :

the first source GstBuffer to merge. [transfer none]

buf2 :

the second source GstBuffer to merge. [transfer none]

Returns :

the new GstBuffer which is the concatenation of the source buffers. [transfer full]

gst_buffer_map ()

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

This function fills info with a pointer to the merged memory 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.

When the buffer contains multiple memory blocks, the returned pointer will be a concatenation of the memory blocks.

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

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. [transfer full]

gst_buffer_unmap ()

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

Release the memory previously mapped with gst_buffer_map().

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.

buffer :

a GstBuffer.

offset :

the offset in buffer

mem :

the memory to compare

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.

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

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

Copy size bytes from src to buffer at offset.

buffer :

a GstBuffer.

offset :

the offset to fill

src :

the source address

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.

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.

buf :

a GstBuffer.

Returns :

a new copy of buf. [transfer full]

gst_buffer_copy_into ()

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

Copies the information from src into dest.

flags indicate which fields will be copied.

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.

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.

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 data into a buffer's data array or validly modify the caps and timestamp metadata. Metadata in a GstBuffer is always writable, but it is only safe to change it when there is only one owner of the buffer - ie, the refcount is 1.

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

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.

obuf :

pointer to a pointer to a GstBuffer to be replaced. [inout][transfer full]

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

gboolean            gst_buffer_is_span_fast             (GstBuffer *buf1,
                                                         GstBuffer *buf2);

Determines whether a gst_buffer_span() can be done without copying the contents, that is, whether the data areas are contiguous sub-buffers of the same buffer.

MT safe.

buf1 :

the first GstBuffer.

buf2 :

the second GstBuffer.

Returns :

TRUE if the buffers are contiguous, FALSE if a copy would be required.

gst_buffer_span ()

GstBuffer *         gst_buffer_span                     (GstBuffer *buf1,
                                                         gsize offset,
                                                         GstBuffer *buf2,
                                                         gsize size);

Creates a new buffer that consists of part of buf1 and buf2. Logically, buf1 and buf2 are concatenated into a single larger buffer, and a new buffer is created at the given offset inside this space, with a given length.

If the two source buffers are children of the same larger buffer, and are contiguous, the new buffer will be a child of the shared parent, and thus no copying is necessary. you can use gst_buffer_is_span_fast() to determine if a memcpy will be needed.

MT safe.

buf1 :

the first source GstBuffer to merge.

offset :

the offset in the first buffer from where the new buffer should start.

buf2 :

the second source GstBuffer to merge.

size :

the total size of the new buffer.

Returns :

the new GstBuffer that spans the two source buffers, or NULL if the arguments are invalid. [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.

buffer :

a GstBuffer

api :

the GType of an API

Returns :

the metadata for api on buffer.

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.

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.

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 opage state pointer

buffer :

a GstBuffer

state :

an opaque state pointer

Returns :

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

See Also

GstPad, GstMiniObject, GstBufferPool