# Gst::Buffer Class Reference

A data-passing buffer type, supporting sub-buffers. More...

Inherits Gst::MiniObject.

Collaboration diagram for Gst::Buffer:
[legend]

List of all members.

## Public Member Functions
virtual | ~Buffer ()
GstBuffer* | gobj ()
| Provides access to the underlying C GstMiniObject.
const GstBuffer* | gobj () const
| Provides access to the underlying C GstMiniObject.
GstBuffer* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
Glib::RefPtr< Gst::Buffer > | copy () const
| Create a copy of the given buffer.
void | copy_metadata (const Glib::RefPtr< Gst::Buffer >& source_buffer, BufferCopyFlags flags)
| Copies the metadata from src into dest.
bool | is_metadata_writable () const
| Similar to gst_buffer_is_writable, but this only ensures that the refcount of the buffer is 1, indicating that the caller is the sole owner and can change the buffer metadata, such as caps and timestamps.
Glib::RefPtr< Gst::Buffer > | create_writable ()
| Makes a writable buffer from the given buffer.
Glib::RefPtr< Gst::Buffer > | make_metadata_writable () const
| Similar to gst_buffer_make_writable, but does not ensure that the buffer data array is writable.
Glib::RefPtr< Gst::Caps > | get_caps ()
| Gets the media type of the buffer.
Glib::RefPtr< const Gst::Caps > | get_caps () const
| Gets the media type of the buffer.
void | set_caps (const Glib::RefPtr< Gst::Caps >& caps)
| Sets the media type on the buffer.
Glib::RefPtr< Gst::Buffer > | create_sub (const guint& offset, const guint& size)
| Creates a sub-buffer from parent at offset and size.
Glib::RefPtr< const Gst::Buffer > | create_sub (const guint& offset, const guint& size) const
| Creates a sub-buffer from parent at offset and size.
bool | is_span_fast (const Glib::RefPtr< const Gst::Buffer >& other_buffer) const
| Determines whether a span() can be done without copying the contents, that is, whether the data areas are contiguous sub-buffers of the same buffer.
Glib::RefPtr< Gst::Buffer > | span (const guint32& offset, const Glib::RefPtr< Gst::Buffer >& other_buffer, const guint32& len) const
| Creates a new buffer that consists of part of buf1 and buf2.
Glib::RefPtr< Gst::Buffer > | merge (const Glib::RefPtr< const Gst::Buffer >& other_buffer) const
| Create a new buffer that is the concatenation of the two source buffers.
guint8* | get_data () const
| Get the data element of this buffer.
guint | get_size () const
| Get the size of this buffer.
ClockTime | get_timestamp () const
| Get the timestamp of this buffer.
ClockTime | get_duration () const
| Get duration of this buffer.
guint64 | get_offset () const
| Get the offset of this buffer.
guint64 | get_offset_end () const
| Get the offset end of this buffer.
guint8* | get_malloc_data () const
| Get the malloc data of this buffer.
## Static Public Member Functions
static Glib::RefPtr< Gst::Buffer > | create ()
| Creates a newly allocated buffer without any data.
static Glib::RefPtr< Gst::Buffer > | create (guint size)
| Tries to create a newly allocated buffer with data of the given size.
## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gst::Buffer > | wrap (GstBuffer* object, bool take_copy=false)

## Detailed Description

A data-passing buffer type, supporting sub-buffers.

Buffers are the basic unit of data transfer in GStreamer. The Gst::Buffer type provides all the state necessary to define a region of memory as part of a stream. Sub-buffers 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 create(). After a buffer has been created one will typically allocate memory for it and set the size of the buffer data. The following example creates a buffer that can hold a given video frame with a given width, height and bits per plane.

## Constructor & Destructor Documentation

virtual Gst::Buffer::~Buffer | ( |  | ) | `[virtual]`

## Member Function Documentation

Glib::RefPtr<Gst::Buffer> Gst::Buffer::copy | ( |  | ) | const

Create a copy of the given buffer.

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

Returns:
  The Gst::Buffer copy.

void Gst::Buffer::copy_metadata | ( | const Glib::RefPtr< Gst::Buffer >& | source_buffer,
|  | BufferCopyFlags | flags |
| ) |  |  |

Copies the metadata from src into dest.

The data, size and mallocdata fields are not copied.

flags indicate which fields will be copied. Use Gst::BUFFER_COPY_ALL to copy all the metadata fields.

This function is typically called from a custom buffer copy function after creating dest and setting the data, size, mallocdata.

Since gstreamermm 0.10:
  .13

Parameters:

  | src | A source Gst::Buffer.
  | flags | Flags indicating what metadata fields should be copied.

static Glib::RefPtr<Gst::Buffer> Gst::Buffer::create | ( | guint | size | ) | `[static]`

Tries to create a newly allocated buffer with data of the given size.

If the requested amount of memory can't be allocated, `0` will be returned. The buffer memory is not cleared.

Note that when size == 0, the buffer data pointer will be `0`.

MT safe.

Parameters:

  | size | The size of the new buffer's data.

Returns:
  A new Gst::Buffer, or `0` if the memory couldn't be allocated.

Since gstreamermm 0.10:
  .13.

static Glib::RefPtr<Gst::Buffer> Gst::Buffer::create | ( |  | ) | `[static]`

Creates a newly allocated buffer without any data.

MT safe.

Returns:
  The new Gst::Buffer.

Glib::RefPtr<const Gst::Buffer> Gst::Buffer::create_sub | ( | const guint & | offset,
|  | const guint & | size |
| ) |  |  | const

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. Returns `0` if the arguments were invalid.

Parameters:

  | offset | The offset into parent Gst::Buffer at which the new sub-buffer begins.
  | size | The size of the new Gst::Buffer sub-buffer, in bytes.

Returns:
  `0` if the arguments were invalid.

Glib::RefPtr<Gst::Buffer> Gst::Buffer::create_sub | ( | const guint & | offset,
|  | const guint & | 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. Returns `0` if the arguments were invalid.

Parameters:

  | offset | The offset into parent Gst::Buffer at which the new sub-buffer begins.
  | size | The size of the new Gst::Buffer sub-buffer, in bytes.

Returns:
  `0` if the arguments were invalid.

Glib::RefPtr<Gst::Buffer> Gst::Buffer::create_writable | ( |  | ) |

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.

Returns:
  A buffer (possibly the same pointer) that is writable.

Reimplemented from Gst::MiniObject.

Glib::RefPtr<const Gst::Caps> Gst::Buffer::get_caps | ( |  | ) | const

Gets the media type of the buffer.

This can be `0` if there is no media type attached to this buffer.

Returns `0` if there were no caps on this buffer.

Returns:
  `0` if there were no caps on this buffer.

Glib::RefPtr<Gst::Caps> Gst::Buffer::get_caps | ( |  | ) |

Gets the media type of the buffer.

This can be `0` if there is no media type attached to this buffer.

Returns `0` if there were no caps on this buffer.

Returns:
  `0` if there were no caps on this buffer.

guint8* Gst::Buffer::get_data | ( |  | ) | const

Get the data element of this buffer.

Returns:
  A pointer to the data element of this buffer.

ClockTime Gst::Buffer::get_duration | ( |  | ) | const

Get duration of this buffer.

Returns:
  he duration in nanoseconds (as a Gst::ClockTime) of the data in the buffer. Value will be Gst::CLOCK_TIME_NONE if the duration is unknown.

guint8* Gst::Buffer::get_malloc_data | ( |  | ) | const

Get the malloc data of this buffer.

Returns:
  A pointer to any data allocated for this buffer using g_malloc(). If this is non-null, this memory will be freed at the end of the buffer's lifecycle (i.e. when its refcount becomes zero).

guint64 Gst::Buffer::get_offset | ( |  | ) | const

Get the offset of this buffer.

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

guint64 Gst::Buffer::get_offset_end | ( |  | ) | const

Get the offset end of this buffer.

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

guint Gst::Buffer::get_size | ( |  | ) | const

Get the size of this buffer.

Returns:
  The size in bytes of the data in this buffer.

ClockTime Gst::Buffer::get_timestamp | ( |  | ) | const

Get the timestamp of this buffer.

Returns:
  The timestamp in nanoseconds (as a Gst::ClockTime) of the data in the buffer. Value will be Gst::CLOCK_TIME_NONE if the timestamp is unknown.

const GstBuffer* Gst::Buffer::gobj | ( |  | ) | const`[inline]`

Provides access to the underlying C GstMiniObject.

Reimplemented from Gst::MiniObject.

GstBuffer* Gst::Buffer::gobj | ( |  | ) | `[inline]`

Provides access to the underlying C GstMiniObject.

Reimplemented from Gst::MiniObject.

GstBuffer* Gst::Buffer::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

Reimplemented from Gst::MiniObject.

bool Gst::Buffer::is_metadata_writable | ( |  | ) | const

Similar to gst_buffer_is_writable, but this only ensures that the refcount of the buffer is 1, indicating that the caller is the sole owner and can change the buffer metadata, such as caps and timestamps.

Returns:
  `true` if the metadata is writable.

bool Gst::Buffer::is_span_fast | ( | const Glib::RefPtr< const Gst::Buffer >& | other_buffer | ) | const

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

MT safe.

Parameters:

  | buf2 | The second Gst::Buffer.

Returns:
  `true` if the buffers are contiguous, `false` if a copy would be required.

Glib::RefPtr<Gst::Buffer> Gst::Buffer::make_metadata_writable | ( |  | ) | const

Similar to gst_buffer_make_writable, but does not ensure that the buffer data array is writable.

Instead, this just ensures that the returned buffer is solely owned by the caller, by creating a subbuffer of the original buffer if necessary.

After calling this function, buf should not be referenced anymore. The result of this function has guaranteed writable metadata.

Returns:
  A new Gst::Buffer with writable metadata.

Glib::RefPtr<Gst::Buffer> Gst::Buffer::merge | ( | const Glib::RefPtr< const Gst::Buffer >& | other_buffer | ) | const

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.

Parameters:

  | buf2 | The second source Gst::Buffer to merge.

Returns:
  The new Gst::Buffer which is the concatenation of the source buffers.

void Gst::Buffer::set_caps | ( | const Glib::RefPtr< Gst::Caps >& | caps | ) |

Sets the media type on the buffer.

The refcount of the caps will be increased and any previous caps on the buffer will be unreffed.

Parameters:

  | caps | A Gst::Caps.

Glib::RefPtr<Gst::Buffer> Gst::Buffer::span | ( | const guint32 & | offset,
|  | const Glib::RefPtr< Gst::Buffer >& | other_buffer,
|  | const guint32 & | len |
| ) |  |  | const

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 is_span_fast() to determine if a memcpy will be needed.

MT safe. Returns `0` if the arguments are invalid.

Parameters:

  | offset | The offset in the first buffer from where the new buffer should start.
  | buf2 | The second source Gst::Buffer to merge.
  | len | The total length of the new buffer.

Returns:
  `0` if the arguments are invalid.

## Friends And Related Function Documentation

Glib::RefPtr< Gst::Buffer > wrap | ( | GstBuffer * | object,
|  | bool | take_copy = `false` |
| ) |  |  | `[related]`

Parameters:

  | object | The C instance
  | take_copy | false if the result should take ownership of the C instance. true if it should take a new copy or ref.

Returns:
  A C++ instance that wraps this C instance.

The documentation for this class was generated from the following file:

- gstreamermm/buffer.h