gst.buffer

Module for [Buffer] class

Types 1

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

``C 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.Buffer.newAllocate] 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.Buffer.nMemory] and you can get a pointer to memory with [gst.buffer.Buffer.peekMemory]

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.Buffer.copyRegion]. 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.Buffer.append]. Copying of memory will only be done when absolutely needed.

Arbitrary extra metadata can be set on a buffer with [gst.buffer.Buffer.addMeta]. Metadata can be retrieved with [gst.buffer.Buffer.getMeta]. See also #GstMeta.

An element should either unref the buffer or push it out on a src pad using [gst.pad.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)

Methods

void * _cPtr(Flag!"Dup" dup = No.Dup)

GType _getGType()

GType _gType() @property

Buffer self()Returns `this`, for use in `with` statements.

gst.mini_object.MiniObject miniObject() @propertyGet `miniObject` field. Returns: the parent structure

gst.buffer_pool.BufferPool pool() @propertyGet `pool` field. Returns: pointer to the pool owner of the buffer

void pool(gst.buffer_pool.BufferPool propval) @propertySet `pool` field. Params: propval = pointer to the pool owner of the buffer

gst.types.ClockTime pts() @propertyGet `pts` field. Returns: presentation timestamp of the buffer, can be #GSTCLOCKTIME_NONE when the pts is not known or relevant. The pts contains the timestamp when the media should be presented to...

void pts(gst.types.ClockTime propval) @propertySet `pts` field. Params: propval = presentation timestamp of the buffer, can be #GSTCLOCKTIME_NONE when the pts is not known or relevant. The pts contains the timestamp when the media should be pre...

gst.types.ClockTime dts() @propertyGet `dts` field. Returns: decoding timestamp of the buffer, can be #GSTCLOCKTIME_NONE when the dts is not known or relevant. The dts contains the timestamp when the media should be processed.

void dts(gst.types.ClockTime propval) @propertySet `dts` field. Params: propval = decoding timestamp of the buffer, can be #GSTCLOCKTIME_NONE when the dts is not known or relevant. The dts contains the timestamp when the media should be processed.

gst.types.ClockTime duration() @propertyGet `duration` field. Returns: duration in time of the buffer data, can be #GSTCLOCKTIME_NONE when the duration is not known or relevant.

void duration(gst.types.ClockTime propval) @propertySet `duration` field. Params: propval = duration in time of the buffer data, can be #GSTCLOCKTIME_NONE when the duration is not known or relevant.

ulong offset() @propertyGet `offset` field. Returns: 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 thi...

void offset(ulong propval) @propertySet `offset` field. Params: propval = 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 samp...

ulong offsetEnd() @propertyGet `offsetEnd` field. Returns: the last offset contained in this buffer. It has the same format as @offset.

void offsetEnd(ulong propval) @propertySet `offsetEnd` field. Params: propval = the last offset contained in this buffer. It has the same format as @offset.

gst.buffer.Buffer newAllocate(gst.allocator.Allocator allocator,  size_t size,  gst.allocation_params.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 ...

gst.buffer.Buffer newMemdup(ubyte[] data)Creates a new buffer of size size and fills it with a copy of data.

gst.buffer.Buffer newWrappedBytes(glib.bytes.Bytes bytes)Creates a new #GstBuffer that wraps the given bytes. The data inside bytes cannot be null and the resulting buffer will be marked as read only.

gst.buffer.Buffer newWrappedFull(gst.types.MemoryFlags flags,  ubyte[]  data,  size_t maxsize,  size_t offset,  glib.types.DestroyNotify notify =  null)

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

gst.custom_meta.CustomMeta addCustomMeta(string name)Creates and adds a #GstCustomMeta for the desired name. name must have been successfully registered with [gst.meta.Meta.registerCustom].

gst.meta.Meta addMeta(gst.meta_info.MetaInfo info, void * params = null)Adds metadata for info to buffer using the parameters in params.

gst.parent_buffer_meta.ParentBufferMeta addParentBufferMeta(gst.buffer.Buffer ref_)Adds a #GstParentBufferMeta to buffer that holds a reference on ref until the buffer is freed.

gst.protection_meta.ProtectionMeta addProtectionMeta(gst.structure.Structure info)Attaches protection metadata to a #GstBuffer.

gst.reference_timestamp_meta.ReferenceTimestampMeta addReferenceTimestampMeta(gst.caps.Caps reference,  gst.types.ClockTime timestamp,  gst.types.ClockTime duration)

Adds a #GstReferenceTimestampMeta to buffer that holds a timestamp and optionally duration based on a specific timestamp reference. See the documentation of #GstReferenceTimestampMeta for details.

gst.buffer.Buffer append(gst.buffer.Buffer buf2)Appends all the memory from buf2 to buf1. The result buffer will contain a concatenation of the memory of buf1 and buf2.

void appendMemory(gst.memory.Memory mem)Appends the memory block mem to buffer. This function takes ownership of mem and thus doesn't increase its refcount.

gst.buffer.Buffer appendRegion(gst.buffer.Buffer buf2, ptrdiff_t offset, ptrdiff_t size)Appends 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.Buffer copyDeep()Creates a copy of the given buffer. This will make a newly allocated copy of the data the source buffer contains. Returns: a new copy of buf if the copy succeeded, null otherwise.

bool copyInto(gst.buffer.Buffer src, gst.types.BufferCopyFlags flags, size_t offset, size_t size)Copies the information from src into dest.

gst.buffer.Buffer copyRegion(gst.types.BufferCopyFlags 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....

void extractDup(size_t offset, size_t size, out ubyte[] dest)Extracts a copy of at most size bytes the data at offset into newly-allocated memory. dest must be freed using [glib.global.gfree] when done.

size_t fill(size_t offset, ubyte[] src)Copies size bytes from src to buffer at offset.

bool findMemory(size_t offset, size_t size, out uint idx, out uint length, out size_t skip)Finds the memory blocks that span size bytes starting from offset in buffer.

bool foreachMeta(gst.types.BufferForeachMetaFunc func)Calls func with user_data for each meta in buffer.

gst.memory.Memory getAllMemory()Gets all the memory blocks in buffer. The memory blocks will be merged into one large #GstMemory. Returns: a #GstMemory that contains the merged memory.

gst.custom_meta.CustomMeta getCustomMeta(string name)Finds the first #GstCustomMeta on buffer for the desired name.

gst.types.BufferFlags getFlags()Gets the #GstBufferFlags flags set on this buffer. Returns: the flags set on this buffer.

gst.memory.Memory getMemory(uint idx)Gets the memory block at index idx in buffer.

gst.memory.Memory getMemoryRange(uint idx, int length)Gets length memory blocks in buffer starting at idx. The memory blocks will be merged into one large #GstMemory.

gst.meta.Meta getMeta(gobject.types.GType api)Gets 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...

uint getNMeta(gobject.types.GType apiType)

gst.reference_timestamp_meta.ReferenceTimestampMeta getReferenceTimestampMeta(gst.caps.Caps reference = null)Finds the first #GstReferenceTimestampMeta on buffer that conforms to reference. Conformance is tested by checking if the meta's reference is a subset of reference.

size_t getSize()Gets the total size of the memory blocks in buffer. Returns: total size of the memory blocks in buffer.

size_t getSizes(out size_t offset, out size_t maxsize)Gets the total size of the memory blocks in buffer.

size_t getSizesRange(uint idx, int length, out size_t offset, out size_t maxsize)Gets the total size of length memory blocks stating from idx in buffer.

bool hasFlags(gst.types.BufferFlags flags)Gives the status of a specific flag on a buffer.

void insertMemory(int idx, gst.memory.Memory mem)Inserts the memory block mem into buffer at idx. This function takes ownership of mem and thus doesn't increase its refcount.

bool isAllMemoryWritable()Checks if all memory blocks in buffer are writable.

bool isMemoryRangeWritable(uint idx, int length)Checks if length memory blocks in buffer starting from idx are writable.

bool map(out gst.map_info.MapInfo info, gst.types.MapFlags flags)Fills info with the #GstMapInfo of all merged memory blocks in buffer.

bool mapRange(uint idx, int length, out gst.map_info.MapInfo info, gst.types.MapFlags flags)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.

int memcmp(size_t offset, ubyte[] mem)Compares size bytes starting from offset in buffer with the memory in mem.

size_t memset(size_t offset, ubyte val, size_t size)Fills buf with size bytes with val starting from offset.

uint nMemory()Gets the amount of memory blocks that this buffer has. This amount is never larger than what [gst.buffer.Buffer.getMaxMemory] returns. Returns: the number of memory blocks this buffer is made of.

gst.memory.Memory peekMemory(uint idx)Gets 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.

void prependMemory(gst.memory.Memory mem)Prepends the memory block mem to buffer. This function takes ownership of mem and thus doesn't increase its refcount.

void removeAllMemory()Removes all the memory blocks in buffer.

void removeMemory(uint idx)Removes the memory block in b at index i.

void removeMemoryRange(uint idx, int length)Removes length memory blocks in buffer starting from idx.

bool removeMeta(gst.meta.Meta meta)Removes the metadata for meta on buffer.

void replaceAllMemory(gst.memory.Memory mem)Replaces all memory in buffer with mem.

void replaceMemory(uint idx, gst.memory.Memory mem)Replaces the memory block at index idx in buffer with mem.

void replaceMemoryRange(uint idx, int length, gst.memory.Memory mem)Replaces length memory blocks in buffer starting at idx with mem.

void resize(ptrdiff_t offset, ptrdiff_t size)Sets the offset and total size of the memory blocks in buffer.

bool resizeRange(uint idx, int length, ptrdiff_t offset, ptrdiff_t size)Sets the total size of the length memory blocks starting at idx in buffer

bool setFlags(gst.types.BufferFlags flags)Sets one or more buffer flags on a buffer.

void setSize(ptrdiff_t size)Sets the total size of the memory blocks in buffer.

void unmap(gst.map_info.MapInfo info)Releases the memory previously mapped with [gst.buffer.Buffer.map].

bool unsetFlags(gst.types.BufferFlags flags)Clears one or more buffer flags.

uint getMaxMemory()Gets the maximum amount of memory blocks that a buffer can hold. This is a compile time constant that can be queried with the function.

Constructors

this(void * ptr, Flag!"Take" take)

this()Creates a newly allocated buffer without any data. Returns: the new #GstBuffer.