A GstBuffer is an lightweight object that is passed from an upstream to a downstream element and contains memory and metadata. It represents the multimedia content that is pushed or pull downstream by elements.

The buffer contains one or more GstMemory objects thet represent the data in the buffer.

Metadata in the buffer consists of:

GstBuffer writability

A buffer is writable when the refcount of the object is exactly 1, meaning that only one object is holding a ref to the buffer. You can only modify anything in the buffer when the buffer is writable. This means that you need to call gst_buffer_make_writable() before changing the timestamps, offsets, metadata or adding and removing memory blocks.

GstBuffer API examples

You can create a buffer with gst_buffer_new () and then add memory objects to it or you can use a convenience function gst_buffer_new_allocate () which combines the two. It's also possible to wrap existing memory with gst_buffer_new_wrapped_full () where you can give the function to call when the memory should be freed.

You can access the memory of the buffer by getting and mapping the GstMemory objects individually or by using gst_buffer_map (). The latter merges all the memory into one big block and then gives you a pointer to this block.

Below is an example of how to create a buffer and access its memory.

  GstBuffer *buffer;
  GstMemory *mem;
  GstMapInfo info;

  /* make empty buffer */
  buffer = gst_buffer_new ();

  /* make memory holding 100 bytes */
  mem = gst_allocator_alloc (NULL, 100, NULL);

  /* add the buffer */
  gst_buffer_append_memory (buffer, mem);


  /* get WRITE access to the memory and fill with 0xff */
  gst_buffer_map (buffer, &info, GST_MAP_WRITE);
  memset (, 0xff, info.size);
  gst_buffer_unmap (buffer, &info);


  /* free the buffer */
  gst_buffer_unref (buffer);