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.
duration in time of the buffer data, can be #GST_CLOCK_TIME_NONE when the duration is not known or relevant.
the parent structure
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.
the last offset contained in this buffer. It has the same
format as offset.
pointer to the pool owner of the buffer
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.
Creates and adds a #GstCustomMeta for the desired name. name must have
been successfully registered with gst_meta_register_custom().
the registered name of the desired custom meta
Adds a #GstParentBufferMeta to buffer that holds a reference on
ref until the buffer is freed.
Attaches protection metadata to a #GstBuffer.
a #GstStructure holding cryptographic information relating to the sample contained in buffer. This function takes ownership of info.
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.
identifier for the timestamp reference.
timestamp
duration, or %GST_CLOCK_TIME_NONE
Appends the memory block mem to buffer. This function takes
ownership of mem and thus doesn't increase its refcount.
This function is identical to gst_buffer_insert_memory() with an index of -1. See gst_buffer_insert_memory() for more details.
a #GstMemory.
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.
the second source #GstBuffer to append.
the offset in buf2
the size or -1 of buf2
Copies the information from src into dest.
If dest already contains memory and flags contains GST_BUFFER_COPY_MEMORY,
the memory from src will be appended to dest.
flags indicate which fields will be copied.
a source #GstBuffer
flags indicating what metadata fields should be copied.
offset to copy from
total size to copy. If -1, all data is copied.
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.
the #GstBufferCopyFlags
the offset into parent #GstBuffer at which the new sub-buffer begins.
the size of the new #GstBuffer sub-buffer, in bytes. If -1, all data is copied.
Copies size bytes starting from offset in buffer to dest.
the offset to extract
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.
the offset to extract
the size to extract
Copies size bytes from src to buffer at offset.
the offset to fill
the source address
Finds the memory blocks that span size bytes starting from offset
in buffer.
When this function returns %TRUE, idx will contain the index of the first
memory block where the byte for offset can be found and length contains the
number of memory blocks containing the size remaining bytes. skip contains
the number of bytes to skip in the memory block at idx to get to the byte
for offset.
size can be -1 to get all the memory blocks after idx.
an offset
a size
Calls func with user_data for each meta in buffer.
func can modify the passed meta pointer or its contents. The return value
of func defines if this function returns or if the remaining metadata items
in the buffer should be skipped.
a #GstBufferForeachMetaFunc to call
Gets all the memory blocks in buffer. The memory blocks will be merged
into one large #GstMemory.
Finds the first #GstCustomMeta on buffer for the desired name.
the registered name of the custom meta to retrieve.
Gets the #GstBufferFlags flags set on this buffer.
Gets the memory block at index idx in buffer.
an index
Gets length memory blocks in buffer starting at idx. The memory blocks will
be merged into one large #GstMemory.
If length is -1, all memory starting from idx is merged.
an index
a length
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 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.
the #GType of an API
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.
Buffers can contain multiple #GstReferenceTimestampMeta metadata items.
Gets the total size of the memory blocks in buffer.
Gets the total size of the 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 memory blocks with gst_buffer_resize().
Gets the total size of length memory blocks stating from idx in buffer.
When not %NULL, offset will contain the offset of the data in the
memory block in buffer at idx and maxsize will contain the sum of the size
and offset and the amount of extra padding on the memory block at idx +
length -1.
offset and maxsize can be used to resize the buffer memory blocks with
gst_buffer_resize_range().
an index
a length
Gives the status of a specific flag on a buffer.
the #GstBufferFlags flag to check.
Inserts the memory block mem into buffer at idx. This function takes ownership
of mem and thus doesn't increase its refcount.
Only gst_buffer_get_max_memory() can be added to a buffer. If more memory is added, existing memory blocks will automatically be merged to make room for the new memory.
the index to add the memory at, or -1 to append it to the end
a #GstMemory.
Checks if all memory blocks in buffer are writable.
Note that this function does not check if buffer is writable, use
gst_buffer_is_writable() to check that if needed.
Checks if length memory blocks in buffer starting from idx are writable.
length can be -1 to check all the memory blocks after idx.
Note that this function does not check if buffer is writable, use
gst_buffer_is_writable() to check that if needed.
an index
a length, should not be 0
Fills info with the #GstMapInfo of all merged memory blocks 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.
The memory in info should be unmapped with gst_buffer_unmap() after
usage.
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.
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.
The memory in info should be unmapped with gst_buffer_unmap() after usage.
Compares size bytes starting from offset in buffer with the memory in mem.
the offset in buffer
the memory to compare
Fills buf with size bytes with val starting from offset.
the offset in buffer
the value to set
the size to set
Gets the amount of memory blocks that this buffer has. This amount is never larger than what gst_buffer_get_max_memory() returns.
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.
an index
Prepends the memory block mem to buffer. This function takes
ownership of mem and thus doesn't increase its refcount.
This function is identical to gst_buffer_insert_memory() with an index of 0. See gst_buffer_insert_memory() for more details.
a #GstMemory.
Removes all the memory blocks in buffer.
Removes the memory block in b at index i.
an index
Removes length memory blocks in buffer starting from idx.
length can be -1, in which case all memory starting from idx is removed.
an index
a length
Removes the metadata for meta on buffer.
a #GstMeta
Replaces all memory in buffer with mem.
a #GstMemory
Replaces the memory block at index idx in buffer with mem.
an index
a #GstMemory
Replaces length memory blocks in buffer starting at idx with mem.
If length is -1, all memory starting from idx will be removed and
replaced with mem.
buffer should be writable.
an index
a length, should not be 0
a #GstMemory
Sets the offset and total size of the memory blocks in buffer.
the offset adjustment
the new size or -1 to just adjust the offset
Sets the total size of the length memory blocks starting at idx in
buffer
an index
a length
the offset adjustment
the new size or -1 to just adjust the offset
Sets one or more buffer flags on a buffer.
the #GstBufferFlags to set.
Sets the total size of the memory blocks in buffer.
the new size
Releases the memory previously mapped with gst_buffer_map().
a #GstMapInfo
Clears one or more buffer flags.
the #GstBufferFlags to clear
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.
When more memory blocks are added, existing memory blocks will be merged together to make room for the new block.
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.
the #GstAllocator to use, or %NULL to use the default allocator
the size in bytes of the new buffer's data.
optional parameters
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.
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.
#GstMemoryFlags
data to wrap
allocated size of data
offset in data
called with user_data when the memory is freed
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.
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)