Class Buffer

java.lang.Object

org.javagi.base.ProxyInstance

org.freedesktop.gstreamer.gst.Buffer

All Implemented Interfaces:

Proxy

@Generated("org.javagi.JavaGI")
public class Buffer
extends ProxyInstance

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)

Constructor Summary

Constructors

Constructor	Description
Buffer()	Creates a newly allocated buffer without any data.
Buffer(MemorySegment address)	Create a Buffer proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
@Nullable CustomMeta	addCustomMeta(String name)	Creates and adds a GstCustomMeta for the desired name. name must have been successfully registered with gst_meta_register_custom().
@Nullable Meta	addMeta(MetaInfo info, @Nullable MemorySegment params)	Adds metadata for info to this Buffer using the parameters in params.
@Nullable ParentBufferMeta	addParentBufferMeta(Buffer ref)	Adds a GstParentBufferMeta to this Buffer that holds a reference on ref until the buffer is freed.
ProtectionMeta	addProtectionMeta(Structure info)	Attaches protection metadata to a GstBuffer.
@Nullable ReferenceTimestampMeta	addReferenceTimestampMeta(Caps reference, ClockTime timestamp, ClockTime duration)	Adds a GstReferenceTimestampMeta to this Buffer that holds a timestamp and optionally duration based on a specific timestamp reference. See the documentation of GstReferenceTimestampMeta for details.
static @Nullable Buffer	allocate(@Nullable Allocator allocator, long size, @Nullable 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.
Buffer	append(Buffer buf2)	Appends all the memory from buf2 to buf1. The result buffer will contain a concatenation of the memory of this Buffer and buf2.
void	appendMemory(Memory mem)	Appends the memory block mem to buffer. This function takes ownership of mem and thus doesn't increase its refcount.
Buffer	appendRegion(Buffer buf2, long offset, long size)	Appends size bytes at offset from buf2 to buf1. The result buffer will contain a concatenation of the memory of this Buffer and the requested region of buf2.
@Nullable Buffer	copy()	Creates a copy of the given buffer.
@Nullable Buffer	copyDeep()	Creates a copy of the given buffer.
boolean	copyInto(Buffer src, Set<BufferCopyFlags> flags, long offset, long size)	Copies the information from src into dest.
boolean	copyInto(Buffer src, BufferCopyFlags flags, long offset, long size)	Copies the information from src into dest.
@Nullable Buffer	copyRegion(Set<BufferCopyFlags> flags, long offset, long size)	Creates a sub-buffer from this Buffer at offset and size. This sub-buffer uses the actual memory space of the parent buffer.
@Nullable Buffer	copyRegion(BufferCopyFlags flags, long offset, long size)	Creates a sub-buffer from this Buffer at offset and size. This sub-buffer uses the actual memory space of the parent buffer.
long	extract(long offset, @Nullable Out<byte[]> dest)	Copies size bytes starting from offset in this Buffer to dest.
void	extractDup(long offset, long size, @Nullable Out<byte[]> dest)	Extracts a copy of at most size bytes the data at offset into newly-allocated memory.
long	fill(long offset, @Nullable byte @Nullable [] src)	Copies size bytes from src to this Buffer at offset.
boolean	findMemory(long offset, long size, Out<Integer> idx, Out<Integer> length, Out<Long> skip)	Finds the memory blocks that span size bytes starting from offset in buffer.
boolean	foreachMeta(@Nullable BufferForeachMetaFunc func)	Calls func with userData for each meta in buffer.
@Nullable Memory	getAllMemory()	Gets all the memory blocks in buffer. The memory blocks will be merged into one large GstMemory.
@Nullable CustomMeta	getCustomMeta(String name)	Finds the first GstCustomMeta on this Buffer for the desired name.
Set<BufferFlags>	getFlags()	Gets the GstBufferFlags flags set on this buffer.
static int	getMaxMemory()	Gets the maximum amount of memory blocks that a buffer can hold.
@Nullable Memory	getMemory(int idx)	Gets the memory block at index idx in buffer.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
@Nullable Memory	getMemoryRange(int idx, int length)	Gets length memory blocks in this Buffer starting at idx. The memory blocks will be merged into one large GstMemory.
@Nullable Meta	getMeta(Type api)	Gets the metadata for api on buffer.
int	getNMeta(Type apiType)
@Nullable ReferenceTimestampMeta	getReferenceTimestampMeta(@Nullable Caps reference)	Finds the first GstReferenceTimestampMeta on this Buffer that conforms to reference. Conformance is tested by checking if the meta's reference is a subset of reference.
long	getSize()	Gets the total size of the memory blocks in buffer.
long	getSizes(@Nullable Out<Long> offset, @Nullable Out<Long> maxsize)	Gets the total size of the memory blocks in buffer.
long	getSizesRange(int idx, int length, @Nullable Out<Long> offset, @Nullable Out<Long> maxsize)	Gets the total size of length memory blocks stating from idx in buffer.
static @Nullable Type	getType()	Get the GType of the Buffer class.
boolean	hasFlags(Set<BufferFlags> flags)	Gives the status of a specific flag on a buffer.
boolean	hasFlags(BufferFlags... flags)	Gives the status of a specific flag on a buffer.
void	insertMemory(int idx, Memory mem)	Inserts the memory block mem into this Buffer at idx. This function takes ownership of mem and thus doesn't increase its refcount.
boolean	isAllMemoryWritable()	Checks if all memory blocks in this Buffer are writable.
boolean	isMemoryRangeWritable(int idx, int length)	Checks if length memory blocks in this Buffer starting from idx are writable.
@Nullable Meta	iterateMeta(@Nullable Out<MemorySegment> state)	Retrieves the next GstMeta after current. If state points to null, the first metadata is returned.
@Nullable Meta	iterateMetaFiltered(@Nullable Out<MemorySegment> state, Type metaApiType)	Retrieves the next GstMeta of type metaApiType after the current one according to state. If state points to null, the first metadata of type metaApiType is returned.
boolean	map(MapInfo info, int flags)	Fills info with the GstMapInfo of all merged memory blocks in buffer.
boolean	mapRange(int idx, int length, MapInfo info, int 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(long offset, @Nullable byte @Nullable [] mem)	Compares size bytes starting from offset in this Buffer with the memory in mem.
static Buffer	memdup(@Nullable byte @Nullable [] data)	Creates a new buffer of size size and fills it with a copy of data.
long	memset(long offset, byte val, long size)	Fills buf with size bytes with val starting from offset.
int	nMemory()	Gets the amount of memory blocks that this buffer has.
@Nullable Memory	peekMemory(int idx)	Gets the memory block at idx in buffer. The memory block stays valid until the memory block in this Buffer is removed, replaced or merged, typically with any call that modifies the memory in buffer.
void	prependMemory(Memory mem)	Prepends the memory block mem to buffer. This function takes ownership of mem and thus doesn't increase its refcount.
ClockTime	readDts()	Read the value of the field dts.
ClockTime	readDuration()	Read the value of the field duration.
@Nullable MiniObject	readMiniObject()	Read the value of the field mini_object.
long	readOffset()	Read the value of the field offset.
long	readOffsetEnd()	Read the value of the field offset_end.
BufferPool	readPool()	Read the value of the field pool.
ClockTime	readPts()	Read the value of the field pts.
Buffer	ref()	Increases the refcount of the given buffer by one.
void	removeAllMemory()	Removes all the memory blocks in buffer.
void	removeMemory(int idx)	Removes the memory block in b at index i.
void	removeMemoryRange(int idx, int length)	Removes length memory blocks in this Buffer starting from idx.
boolean	removeMeta(Meta meta)	Removes the metadata for meta on buffer.
static boolean	replace(@Nullable Out<Buffer> obuf, @Nullable Buffer nbuf)	Modifies a pointer to a GstBuffer to point to a different GstBuffer.
void	replaceAllMemory(Memory mem)	Replaces all memory in this Buffer with mem.
void	replaceMemory(int idx, Memory mem)	Replaces the memory block at index idx in this Buffer with mem.
void	replaceMemoryRange(int idx, int length, Memory mem)	Replaces length memory blocks in this Buffer starting at idx with mem.
void	resize(long offset, long size)	Sets the offset and total size of the memory blocks in buffer.
boolean	resizeRange(int idx, int length, long offset, long size)	Sets the total size of the length memory blocks starting at idx in this Buffer
boolean	setFlags(Set<BufferFlags> flags)	Sets one or more buffer flags on a buffer.
boolean	setFlags(BufferFlags... flags)	Sets one or more buffer flags on a buffer.
void	setSize(long size)	Sets the total size of the memory blocks in buffer.
void	unmap(MapInfo info)	Releases the memory previously mapped with gst_buffer_map().
void	unref()	Decreases the refcount of the buffer.
boolean	unsetFlags(Set<BufferFlags> flags)	Clears one or more buffer flags.
boolean	unsetFlags(BufferFlags... flags)	Clears one or more buffer flags.
static Buffer	wrapped(@Nullable byte @Nullable [] data)	Creates a new buffer that wraps the given data. The memory will be freed with g_free() and will be marked writable.
static Buffer	wrappedBytes(byte[] 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.
static Buffer	wrappedFull(Set<MemoryFlags> flags, @Nullable byte @Nullable [] data, long maxsize, long offset)	Allocates a new buffer that wraps the given memory.
static Buffer	wrappedFull(MemoryFlags flags, @Nullable byte @Nullable [] data, long maxsize, long offset)	Allocates a new buffer that wraps the given memory.
void	writeDts(ClockTime dts)	Write a value in the field dts.
void	writeDuration(ClockTime duration)	Write a value in the field duration.
void	writeMiniObject(@Nullable MiniObject miniObject)	Write a value in the field mini_object.
void	writeOffset(long offset)	Write a value in the field offset.
void	writeOffsetEnd(long offsetEnd)	Write a value in the field offset_end.
void	writePool(BufferPool pool)	Write a value in the field pool.
void	writePts(ClockTime pts)	Write a value in the field pts.

Methods inherited from class ProxyInstance

equals, handle, hashCode

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Buffer

public Buffer(MemorySegment address)

Create a Buffer proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Buffer

public Buffer()

Creates a newly allocated buffer without any data.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the Buffer class.

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readMiniObject

public @Nullable MiniObject readMiniObject()

Read the value of the field mini_object.

Returns:

The value of the field mini_object

writeMiniObject

public void writeMiniObject(@Nullable MiniObject miniObject)

Write a value in the field mini_object.

Parameters:

miniObject - The new value for the field mini_object

readPool

public BufferPool readPool()

Read the value of the field pool.

Returns:

The value of the field pool

writePool

public void writePool(BufferPool pool)

Write a value in the field pool.

Parameters:

pool - The new value for the field pool

readPts

public ClockTime readPts()

Read the value of the field pts.

Returns:

The value of the field pts

writePts

public void writePts(ClockTime pts)

Write a value in the field pts.

Parameters:

pts - The new value for the field pts

readDts

public ClockTime readDts()

Read the value of the field dts.

Returns:

The value of the field dts

writeDts

public void writeDts(ClockTime dts)

Write a value in the field dts.

Parameters:

dts - The new value for the field dts

readDuration

public ClockTime readDuration()

Read the value of the field duration.

Returns:

The value of the field duration

writeDuration

public void writeDuration(ClockTime duration)

Write a value in the field duration.

Parameters:

duration - The new value for the field duration

readOffset

public long readOffset()

Read the value of the field offset.

Returns:

The value of the field offset

writeOffset

public void writeOffset(long offset)

Write a value in the field offset.

Parameters:

offset - The new value for the field offset

readOffsetEnd

public long readOffsetEnd()

Read the value of the field offset_end.

Returns:

The value of the field offset_end

writeOffsetEnd

public void writeOffsetEnd(long offsetEnd)

Write a value in the field offset_end.

Parameters:

offsetEnd - The new value for the field offset_end

allocate

public static @Nullable Buffer allocate(@Nullable Allocator allocator,
 long size,
 @Nullable 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.

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.

Parameters:

allocator - the GstAllocator to use, or null to use the default allocator

size - the size in bytes of the new buffer's data.

params - optional parameters

Returns:

a new GstBuffer

memdup

public static Buffer memdup(@Nullable byte @Nullable [] data)

Creates a new buffer of size size and fills it with a copy of data.

Parameters:

data - data to copy into new buffer

Returns:

a new GstBuffer

Since:

1.20

wrapped

public static Buffer wrapped(@Nullable byte @Nullable [] data)

Creates a new buffer that wraps the given data. The memory will be freed with g_free() and will be marked writable.

Parameters:

data - data to wrap

Returns:

a new GstBuffer

wrappedBytes

public static Buffer wrappedBytes(byte[] 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.

Parameters:

bytes - a GBytes to wrap

Returns:

a new GstBuffer wrapping bytes

Since:

1.16

wrappedFull

public static Buffer wrappedFull(Set<MemoryFlags> flags,
 @Nullable byte @Nullable [] data,
 long maxsize,
 long offset)

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

The prefix/padding must be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

Parameters:

flags - GstMemoryFlags

data - data to wrap

maxsize - allocated size of data

offset - offset in data

Returns:

a new GstBuffer

wrappedFull

public static Buffer wrappedFull(MemoryFlags flags,
 @Nullable byte @Nullable [] data,
 long maxsize,
 long offset)

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

The prefix/padding must be filled with 0 if flags contains GST_MEMORY_FLAG_ZERO_PREFIXED and GST_MEMORY_FLAG_ZERO_PADDED respectively.

Parameters:

flags - GstMemoryFlags

data - data to wrap

maxsize - allocated size of data

offset - offset in data

Returns:

a new GstBuffer

getMaxMemory

public static int 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.

When more memory blocks are added, existing memory blocks will be merged together to make room for the new block.

Returns:

the maximum amount of memory blocks that a buffer can hold.

Since:

1.2

replace

public static boolean replace(@Nullable Out<Buffer> obuf,
 @Nullable Buffer nbuf)

Modifies a pointer to a GstBuffer to point to a different GstBuffer. The modification is done atomically (so this is useful for ensuring thread safety in some cases), and the reference counts are updated appropriately (the old buffer is unreffed, the new is reffed).

Either nbuf or the GstBuffer pointed to by obuf may be null.

Parameters:

obuf - pointer to a pointer to a GstBuffer to be replaced.

nbuf - pointer to a GstBuffer that will replace the buffer pointed to by obuf.

Returns:

true when obuf was different from nbuf.

addCustomMeta

public @Nullable CustomMeta addCustomMeta(String name)

Creates and adds a GstCustomMeta for the desired name. name must have been successfully registered with gst_meta_register_custom().

Parameters:

name - the registered name of the desired custom meta

Returns:

The GstCustomMeta that was added to the buffer

Since:

1.20

addMeta

public @Nullable Meta addMeta(MetaInfo info,
 @Nullable MemorySegment params)

Adds metadata for info to this Buffer using the parameters in params.

Parameters:

info - a GstMetaInfo

params - params for info

Returns:

the metadata for the api in info on buffer.

addParentBufferMeta

public @Nullable ParentBufferMeta addParentBufferMeta(Buffer ref)

Adds a GstParentBufferMeta to this Buffer that holds a reference on ref until the buffer is freed.

Parameters:

ref - a GstBuffer to ref

Returns:

The GstParentBufferMeta that was added to the buffer

Since:

1.6

addProtectionMeta

public ProtectionMeta addProtectionMeta(Structure info)

Attaches protection metadata to a GstBuffer.

Parameters:

info - a GstStructure holding cryptographic information relating to the sample contained in buffer. This function takes ownership of info.

Returns:

a pointer to the added GstProtectionMeta if successful

Since:

1.6

addReferenceTimestampMeta

public @Nullable ReferenceTimestampMeta addReferenceTimestampMeta(Caps reference,
 ClockTime timestamp,
 ClockTime duration)

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

Parameters:

reference - identifier for the timestamp reference.

timestamp - timestamp

duration - duration, or GST_CLOCK_TIME_NONE

Returns:

The GstReferenceTimestampMeta that was added to the buffer

Since:

1.14

append

public Buffer append(Buffer buf2)

Appends all the memory from buf2 to buf1. The result buffer will contain a concatenation of the memory of this Buffer and buf2.

Parameters:

buf2 - the second source GstBuffer to append.

Returns:

the new GstBuffer that contains the memory of the two source buffers.

appendMemory

public void appendMemory(Memory mem)

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.

Parameters:

mem - a GstMemory.

appendRegion

public Buffer appendRegion(Buffer buf2,
 long offset,
 long size)

Appends size bytes at offset from buf2 to buf1. The result buffer will contain a concatenation of the memory of this Buffer and the requested region of buf2.

Parameters:

buf2 - the second source GstBuffer to append.

offset - the offset in buf2

size - the size or -1 of buf2

Returns:

the new GstBuffer that contains the memory of the two source buffers.

copy

public @Nullable Buffer copy()

Creates a copy of the given buffer. This will only copy the buffer's data to a newly allocated memory if needed (if the type of memory requires it), otherwise the underlying data is just referenced. Check gst_buffer_copy_deep() if you want to force the data to be copied to newly allocated memory.

Returns:

a new copy of this Buffer if the copy succeeded, null otherwise.

copyDeep

public @Nullable 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 this Buffer if the copy succeeded, null otherwise.

Since:

1.6

copyInto

public boolean copyInto(Buffer src,
 Set<BufferCopyFlags> flags,
 long offset,
 long size)

Copies the information from src into dest.

If this Buffer 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.

Parameters:

src - a source GstBuffer

flags - flags indicating what metadata fields should be copied.

offset - offset to copy from

size - total size to copy. If -1, all data is copied.

Returns:

true if the copying succeeded, false otherwise.

copyInto

public boolean copyInto(Buffer src,
 BufferCopyFlags flags,
 long offset,
 long size)

Copies the information from src into dest.

If this Buffer 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.

Parameters:

src - a source GstBuffer

flags - flags indicating what metadata fields should be copied.

offset - offset to copy from

size - total size to copy. If -1, all data is copied.

Returns:

true if the copying succeeded, false otherwise.

copyRegion

public @Nullable Buffer copyRegion(Set<BufferCopyFlags> flags,
 long offset,
 long size)

Creates a sub-buffer from this Buffer 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.

Parameters:

flags - the GstBufferCopyFlags

offset - the offset into parent GstBuffer at which the new sub-buffer begins.

size - the size of the new GstBuffer sub-buffer, in bytes. If -1, all data is copied.

Returns:

the new GstBuffer or null if copying failed.

copyRegion

public @Nullable Buffer copyRegion(BufferCopyFlags flags,
 long offset,
 long size)

Creates a sub-buffer from this Buffer 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.

Parameters:

flags - the GstBufferCopyFlags

offset - the offset into parent GstBuffer at which the new sub-buffer begins.

size - the size of the new GstBuffer sub-buffer, in bytes. If -1, all data is copied.

Returns:

the new GstBuffer or null if copying failed.

extract

public long extract(long offset,
 @Nullable Out<byte[]> dest)

Copies size bytes starting from offset in this Buffer to dest.

Parameters:

offset - the offset to extract

dest - the destination address

Returns:

The amount of bytes extracted. This value can be lower than size when this Buffer did not contain enough data.

extractDup

public void extractDup(long offset,
 long size,
 @Nullable Out<byte[]> 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.

Parameters:

offset - the offset to extract

size - the size to extract

dest - A pointer where the destination array will be written. Might be null if the size is 0.

Since:

1.0.10

fill

public long fill(long offset,
 @Nullable byte @Nullable [] src)

Copies size bytes from src to this Buffer at offset.

Parameters:

offset - the offset to fill

src - the source address

Returns:

The amount of bytes copied. This value can be lower than size when this Buffer did not contain enough data.

findMemory

public boolean findMemory(long offset,
 long size,
 Out<Integer> idx,
 Out<Integer> length,
 Out<Long> skip)

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.

Parameters:

offset - an offset

size - a size

idx - pointer to index

length - pointer to length

skip - pointer to skip

Returns:

true when size bytes starting from offset could be found in this Buffer and idx, length and skip will be filled.

foreachMeta

public boolean foreachMeta(@Nullable BufferForeachMetaFunc func)

Calls func with userData 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.

Parameters:

func - a GstBufferForeachMetaFunc to call

Returns:

false when func returned false for one of the metadata.

getAllMemory

public @Nullable 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.

getCustomMeta

public @Nullable CustomMeta getCustomMeta(String name)

Finds the first GstCustomMeta on this Buffer for the desired name.

Parameters:

name - the registered name of the custom meta to retrieve.

Returns:

the GstCustomMeta

Since:

1.20

getFlags

public Set<BufferFlags> getFlags()

Gets the GstBufferFlags flags set on this buffer.

Returns:

the flags set on this buffer.

Since:

1.10

getMemory

public @Nullable Memory getMemory(int idx)

Gets the memory block at index idx in buffer.

Parameters:

idx - an index

Returns:

a GstMemory that contains the data of the memory block at idx.

getMemoryRange

public @Nullable Memory getMemoryRange(int idx,
 int length)

Gets length memory blocks in this 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.

Parameters:

idx - an index

length - a length

Returns:

a GstMemory that contains the merged data of length blocks starting at idx.

getMeta

public @Nullable Meta getMeta(Type 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 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.

Parameters:

api - the GType of an API

Returns:

the metadata for api on buffer.

getNMeta

public int getNMeta(Type apiType)

getReferenceTimestampMeta

public @Nullable ReferenceTimestampMeta getReferenceTimestampMeta(@Nullable Caps reference)

Finds the first GstReferenceTimestampMeta on this 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.

Parameters:

reference - a reference GstCaps

Returns:

the GstReferenceTimestampMeta or null when there is no such metadata on buffer.

Since:

1.14

getSize

public long getSize()

Gets the total size of the memory blocks in buffer.

Returns:

total size of the memory blocks in buffer.

getSizes

public long getSizes(@Nullable Out<Long> offset,
 @Nullable Out<Long> maxsize)

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 this 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().

Parameters:

offset - a pointer to the offset

maxsize - a pointer to the maxsize

Returns:

total size of the memory blocks in buffer.

getSizesRange

public long getSizesRange(int idx,
 int length,
 @Nullable Out<Long> offset,
 @Nullable Out<Long> maxsize)

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 this 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().

Parameters:

idx - an index

length - a length

offset - a pointer to the offset

maxsize - a pointer to the maxsize

Returns:

total size of length memory blocks starting at idx in buffer.

hasFlags

public boolean hasFlags(Set<BufferFlags> flags)

Gives the status of a specific flag on a buffer.

Parameters:

flags - the GstBufferFlags flag to check.

Returns:

true if all flags in flags are found on buffer.

Since:

1.10

hasFlags

public boolean hasFlags(BufferFlags... flags)

Gives the status of a specific flag on a buffer.

Parameters:

flags - the GstBufferFlags flag to check.

Returns:

true if all flags in flags are found on buffer.

Since:

1.10

insertMemory

public void insertMemory(int idx,
 Memory mem)

Inserts the memory block mem into this 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.

Parameters:

idx - the index to add the memory at, or -1 to append it to the end

mem - a GstMemory.

isAllMemoryWritable

public boolean isAllMemoryWritable()

Checks if all memory blocks in this Buffer are writable.

Note that this function does not check if this Buffer is writable, use gst_buffer_is_writable() to check that if needed.

Returns:

true if all memory blocks in this Buffer are writable

Since:

1.4

isMemoryRangeWritable

public boolean isMemoryRangeWritable(int idx,
 int length)

Checks if length memory blocks in this 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 this Buffer is writable, use gst_buffer_is_writable() to check that if needed.

Parameters:

idx - an index

length - a length, should not be 0

Returns:

true if the memory range is writable

Since:

1.4

iterateMeta

public @Nullable Meta iterateMeta(@Nullable Out<MemorySegment> state)

Retrieves the next GstMeta after current. If state points to null, the first metadata is returned.

state will be updated with an opaque state pointer

Parameters:

state - an opaque state pointer

Returns:

The next GstMeta or null when there are no more items.

iterateMetaFiltered

public @Nullable Meta iterateMetaFiltered(@Nullable Out<MemorySegment> state,
 Type metaApiType)

Retrieves the next GstMeta of type metaApiType after the current one according to state. If state points to null, the first metadata of type metaApiType is returned.

state will be updated with an opaque state pointer

Parameters:

state - an opaque state pointer

metaApiType - only return GstMeta of this type

Returns:

The next GstMeta of type metaApiType or null when there are no more items.

Since:

1.12

map

public boolean map(MapInfo info,
 int flags)

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, this Buffer should be writable (as returned from gst_buffer_is_writable()).

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

Parameters:

info - info about the mapping

flags - flags for the mapping

Returns:

true if the map succeeded and info contains valid data.

mapRange

public boolean mapRange(int idx,
 int length,
 MapInfo info,
 int 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.

flags describe the desired access of the memory. When flags is GST_MAP_WRITE, this Buffer should be writable (as returned from gst_buffer_is_writable()).

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

Parameters:

idx - an index

length - a length

info - info about the mapping

flags - flags for the mapping

Returns:

true if the map succeeded and info contains valid data.

memcmp

public int memcmp(long offset,
 @Nullable byte @Nullable [] mem)

Compares size bytes starting from offset in this Buffer with the memory in mem.

Parameters:

offset - the offset in this Buffer

mem - the memory to compare

Returns:

0 if the memory is equal.

memset

public long memset(long offset,
 byte val,
 long size)

Fills buf with size bytes with val starting from offset.

Parameters:

offset - the offset in this Buffer

val - the value to set

size - the size to set

Returns:

The amount of bytes filled. This value can be lower than size when this Buffer did not contain enough data.

nMemory

public int nMemory()

Gets the amount of memory blocks that this buffer has. This amount is never larger than what gst_buffer_get_max_memory() returns.

Returns:

the number of memory blocks this buffer is made of.

peekMemory

public @Nullable Memory peekMemory(int idx)

Gets the memory block at idx in buffer. The memory block stays valid until the memory block in this Buffer is removed, replaced or merged, typically with any call that modifies the memory in buffer.

Parameters:

idx - an index

Returns:

the GstMemory at idx.

prependMemory

public void prependMemory(Memory mem)

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.

Parameters:

mem - a GstMemory.

ref

public Buffer ref()

Increases the refcount of the given buffer by one.

Note that the refcount affects the writability of this Buffer and its metadata, see gst_buffer_is_writable(). It is important to note that keeping additional references to GstBuffer instances can potentially increase the number of memcpy operations in a pipeline.

Returns:

this Buffer

removeAllMemory

public void removeAllMemory()

Removes all the memory blocks in buffer.

removeMemory

public void removeMemory(int idx)

Removes the memory block in b at index i.

Parameters:

idx - an index

removeMemoryRange

public void removeMemoryRange(int idx,
 int length)

Removes length memory blocks in this Buffer starting from idx.

length can be -1, in which case all memory starting from idx is removed.

Parameters:

idx - an index

length - a length

removeMeta

public boolean removeMeta(Meta meta)

Removes the metadata for meta on buffer.

Parameters:

meta - a GstMeta

Returns:

true if the metadata existed and was removed, false if no such metadata was on buffer.

replaceAllMemory

public void replaceAllMemory(Memory mem)

Replaces all memory in this Buffer with mem.

Parameters:

mem - a GstMemory

replaceMemory

public void replaceMemory(int idx,
 Memory mem)

Replaces the memory block at index idx in this Buffer with mem.

Parameters:

idx - an index

mem - a GstMemory

replaceMemoryRange

public void replaceMemoryRange(int idx,
 int length,
 Memory mem)

Replaces length memory blocks in this Buffer starting at idx with mem.

If length is -1, all memory starting from idx will be removed and replaced with mem.

this Buffer should be writable.

Parameters:

idx - an index

length - a length, should not be 0

mem - a GstMemory

resize

public void resize(long offset,
 long size)

Sets the offset and total size of the memory blocks in buffer.

Parameters:

offset - the offset adjustment

size - the new size or -1 to just adjust the offset

resizeRange

public boolean resizeRange(int idx,
 int length,
 long offset,
 long size)

Sets the total size of the length memory blocks starting at idx in this Buffer

Parameters:

idx - an index

length - a length

offset - the offset adjustment

size - the new size or -1 to just adjust the offset

Returns:

true if resizing succeeded, false otherwise.

setFlags

public boolean setFlags(Set<BufferFlags> flags)

Sets one or more buffer flags on a buffer.

Parameters:

flags - the GstBufferFlags to set.

Returns:

true if flags were successfully set on buffer.

Since:

1.10

setFlags

public boolean setFlags(BufferFlags... flags)

Sets one or more buffer flags on a buffer.

Parameters:

flags - the GstBufferFlags to set.

Returns:

true if flags were successfully set on buffer.

Since:

1.10

setSize

public void setSize(long size)

Sets the total size of the memory blocks in buffer.

Parameters:

size - the new size

unmap

public void unmap(MapInfo info)

Releases the memory previously mapped with gst_buffer_map().

Parameters:

info - a GstMapInfo

unref

public void unref()

Decreases the refcount of the buffer. If the refcount reaches 0, the buffer with the associated metadata and memory will be freed.

unsetFlags

public boolean unsetFlags(Set<BufferFlags> flags)

Clears one or more buffer flags.

Parameters:

flags - the GstBufferFlags to clear

Returns:

true if flags is successfully cleared from buffer.

Since:

1.10

unsetFlags

public boolean unsetFlags(BufferFlags... flags)

Clears one or more buffer flags.

Parameters:

flags - the GstBufferFlags to clear

Returns:

true if flags is successfully cleared from buffer.

Since:

1.10