Buffer

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. |[ 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.

The #GstParentBufferMeta is a meta 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)

class Buffer {

protected

GstBuffer* gstBuffer;

protected

bool ownedRef;

GstBuffer* getBufferStruct(bool transferOwnership);

void* getStruct();

this(GstBuffer* gstBuffer, bool ownedRef);

static GType getType();

this();

this(Allocator allocator, size_t size, AllocationParams params);

this(ubyte[] data);

this(GstMemoryFlags flags, ubyte[] data, size_t maxsize, size_t offset, void* userData, GDestroyNotify notify);

GstMeta* addMeta(GstMetaInfo* info, void* params);

GstParentBufferMeta* addParentBufferMeta(Buffer doref);

ProtectionMeta addProtectionMeta(Structure info);

Buffer append(Buffer buf2);

void appendMemory(Memory mem);

Buffer appendRegion(Buffer buf2, ptrdiff_t offset, ptrdiff_t size);

Buffer copyDeep();

bool copyInto(Buffer src, GstBufferCopyFlags flags, size_t offset, size_t size);

Buffer copyRegion(GstBufferCopyFlags flags, size_t offset, size_t size);

size_t extract(size_t offset, void* dest, size_t size);

void extractDup(size_t offset, size_t size, ubyte[] dest);

size_t fill(size_t offset, ubyte[] src);

bool findMemory(size_t offset, size_t size, uint idx, uint length, size_t skip);

bool foreachMeta(GstBufferForeachMetaFunc func, void* userData);

Memory getAllMemory();

GstBufferFlags getFlags();

Memory getMemory(uint idx);

Memory getMemoryRange(uint idx, int length);

GstMeta* getMeta(GType api);

size_t getSize();

size_t getSizes(size_t offset, size_t maxsize);

size_t getSizesRange(uint idx, int length, size_t offset, size_t maxsize);

bool hasFlags(GstBufferFlags flags);

void insertMemory(int idx, Memory mem);

bool isAllMemoryWritable();

bool isMemoryRangeWritable(uint idx, int length);

GstMeta* iterateMeta(void** state);

GstMeta* iterateMetaFiltered(void** state, GType metaApiType);

bool map(GstMapInfo info, GstMapFlags flags);

bool mapRange(uint idx, int length, GstMapInfo info, GstMapFlags flags);

int memcmp(size_t offset, ubyte[] mem);

size_t memset(size_t offset, ubyte val, size_t size);

uint nMemory();

Memory peekMemory(uint idx);

void prependMemory(Memory mem);

void removeAllMemory();

void removeMemory(uint idx);

void removeMemoryRange(uint idx, int length);

bool removeMeta(GstMeta* meta);

void replaceAllMemory(Memory mem);

void replaceMemory(uint idx, Memory mem);

void replaceMemoryRange(uint idx, int length, Memory mem);

void resize(ptrdiff_t offset, ptrdiff_t size);

bool resizeRange(uint idx, int length, ptrdiff_t offset, ptrdiff_t size);

bool setFlags(GstBufferFlags flags);

void setSize(ptrdiff_t size);

void unmap(GstMapInfo* info);

bool unsetFlags(GstBufferFlags flags);

static uint getMaxMemory();

}

Constructors

this this(GstBuffer* gstBuffer, bool ownedRef): Sets our main struct and passes it to the parent class.
this this(): Creates a newly allocated buffer without any data.
this this(Allocator allocator, size_t size, AllocationParams 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.
this this(ubyte[] data): Creates a new buffer that wraps the given @data. The memory will be freed with g_free and will be marked writable.
this this(GstMemoryFlags flags, ubyte[] data, size_t maxsize, size_t offset, void* userData, 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.

Members

Functions

addMeta GstMeta* addMeta(GstMetaInfo* info, void* params): Add metadata for @info to @buffer using the parameters in @params.
addParentBufferMeta GstParentBufferMeta* addParentBufferMeta(Buffer doref): Add a #GstParentBufferMeta to @buffer that holds a reference on @ref until the buffer is freed.
addProtectionMeta ProtectionMeta addProtectionMeta(Structure info): Attaches protection metadata to a #GstBuffer.
append Buffer append(Buffer buf2): Append all the memory from @buf2 to @buf1. The result buffer will contain a concatenation of the memory of @buf1 and @buf2.
appendMemory void appendMemory(Memory mem): Append the memory block @mem to @buffer. This function takes ownership of @mem and thus doesn't increase its refcount.
appendRegion Buffer appendRegion(Buffer buf2, ptrdiff_t offset, ptrdiff_t 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.
copyDeep Buffer copyDeep(): Create a copy of the given buffer. This will make a newly allocated copy of the data the source buffer contains.
copyInto bool copyInto(Buffer src, GstBufferCopyFlags flags, size_t offset, size_t size): Copies the information from @src into @dest.
copyRegion Buffer copyRegion(GstBufferCopyFlags flags, size_t offset, size_t 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.
extract size_t extract(size_t offset, void* dest, size_t size): Copy @size bytes starting from @offset in @buffer to @dest.
extractDup void extractDup(size_t offset, size_t size, ubyte[] dest): 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.
fill size_t fill(size_t offset, ubyte[] src): Copy @size bytes from @src to @buffer at @offset.
findMemory bool findMemory(size_t offset, size_t size, uint idx, uint length, size_t skip): Find the memory blocks that span @size bytes starting from @offset in @buffer.
foreachMeta bool foreachMeta(GstBufferForeachMetaFunc func, void* userData): Call @func with @user_data for each meta in @buffer.
getAllMemory Memory getAllMemory(): Get all the memory block in @buffer. The memory blocks will be merged into one large #GstMemory.
getBufferStruct GstBuffer* getBufferStruct(bool transferOwnership): Get the main Gtk struct
getFlags GstBufferFlags getFlags(): Get the #GstBufferFlags flags set on this buffer.
getMemory Memory getMemory(uint idx): Get the memory block at index @idx in @buffer.
getMemoryRange Memory getMemoryRange(uint idx, int length): Get @length memory blocks in @buffer starting at @idx. The memory blocks will be merged into one large #GstMemory.
getMeta GstMeta* getMeta(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.
getSize size_t getSize(): Get the total size of the memory blocks in @buffer.
getSizes size_t getSizes(size_t offset, size_t maxsize): Get the total size of the memory blocks in @b.
getSizesRange size_t getSizesRange(uint idx, int length, size_t offset, size_t maxsize): Get the total size of @length memory blocks stating from @idx in @buffer.
getStruct void* getStruct(): the main Gtk struct as a void*
hasFlags bool hasFlags(GstBufferFlags flags)
insertMemory void insertMemory(int idx, Memory mem): Insert the memory block @mem to @buffer at @idx. This function takes ownership of @mem and thus doesn't increase its refcount.
isAllMemoryWritable bool isAllMemoryWritable(): Check if all memory blocks in @buffer are writable.
isMemoryRangeWritable bool isMemoryRangeWritable(uint idx, int length): Check if @length memory blocks in @buffer starting from @idx are writable.
iterateMeta
GstMeta* iterateMeta(void** state): Retrieve the next #GstMeta after @current. If @state points to %NULL, the first metadata is returned.
iterateMetaFiltered
GstMeta* iterateMetaFiltered(void** state, GType metaApiType): Retrieve the next #GstMeta of type @meta_api_type after the current one according to @state. If @state points to %NULL, the first metadata of type @meta_api_type is returned.
map bool map(GstMapInfo info, GstMapFlags flags): This function fills @info with the #GstMapInfo of all merged memory blocks in @buffer.
mapRange bool mapRange(uint idx, int 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.
memcmp int memcmp(size_t offset, ubyte[] mem): Compare @size bytes starting from @offset in @buffer with the memory in @mem.
memset size_t memset(size_t offset, ubyte val, size_t size): Fill @buf with @size bytes with @val starting from @offset.
nMemory uint nMemory(): Get the amount of memory blocks that this buffer has. This amount is never larger than what gst_buffer_get_max_memory() returns.
peekMemory Memory peekMemory(uint 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.
prependMemory void prependMemory(Memory mem): Prepend the memory block @mem to @buffer. This function takes ownership of @mem and thus doesn't increase its refcount.
removeAllMemory void removeAllMemory(): Remove all the memory blocks in @buffer.
removeMemory void removeMemory(uint idx): Remove the memory block in @b at index @i.
removeMemoryRange void removeMemoryRange(uint idx, int length): Remove @length memory blocks in @buffer starting from @idx.
removeMeta bool removeMeta(GstMeta* meta): Remove the metadata for @meta on @buffer.
replaceAllMemory void replaceAllMemory(Memory mem): Replaces all memory in @buffer with @mem.
replaceMemory void replaceMemory(uint idx, Memory mem): Replaces the memory block at index @idx in @buffer with @mem.
replaceMemoryRange void replaceMemoryRange(uint idx, int length, Memory mem): Replaces @length memory blocks in @buffer starting at @idx with @mem.
resize void resize(ptrdiff_t offset, ptrdiff_t size): Set the offset and total size of the memory blocks in @buffer.
resizeRange bool resizeRange(uint idx, int length, ptrdiff_t offset, ptrdiff_t size): Set the total size of the @length memory blocks starting at @idx in @buffer
setFlags bool setFlags(GstBufferFlags flags): Sets one or more buffer flags on a buffer.
setSize void setSize(ptrdiff_t size): Set the total size of the memory blocks in @buffer.
unmap void unmap(GstMapInfo* info): Release the memory previously mapped with gst_buffer_map().
unsetFlags bool unsetFlags(GstBufferFlags flags): Clears one or more buffer flags.

Static functions

getMaxMemory uint getMaxMemory(): 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.
getType GType getType()

Variables

gstBuffer GstBuffer* gstBuffer;: the main Gtk struct
ownedRef bool ownedRef;: Undocumented in source.