public class Buffer extends MiniObject
Pad
, MiniObject
Buffers are the basic unit of data transfer in GStreamer. The 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.
Non-plugins will usually not need to allocate buffers, but they can be allocated
using new Buffer(int)
to create a buffer with preallocated data of a given size.
The data pointed to by the buffer can be accessed with the getByteBuffer()
method. For buffers of size 0, the data pointer is undefined (usually NULL)
and should never be used.
If an element knows what pad you will push the buffer out on, it should use gst_pad_alloc_buffer() instead to create a buffer. This allows downstream elements to provide special buffers to write in, like hardware buffers.
A buffer has a pointer to a Caps
describing the media type of the data
in the buffer. Attach caps to the buffer with setCaps(org.gstreamer.Caps)
; this
is typically done before pushing out a buffer using gst_pad_push() so that
the downstream element knows the type of the buffer.
A buffer will usually have a timestamp, and a duration, but neither of these are guaranteed (they may be set to -1). Whenever a meaningful value can be given for these, they should be set. The timestamp and duration are measured in nanoseconds (they are long values).
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 #GstCaps set on it). Either or both can be set to -1.
To efficiently create a smaller buffer out of an existing one, you can
use createSubBuffer(int, int)
.
If a plug-in wants to modify the buffer data in-place, it should first obtain
a buffer that is safe to modify by using makeWritable()
. This
function is optimized so that a copy will only be made when it is necessary.
A plugin that only wishes to modify the metadata of a buffer, such as the offset, timestamp or caps, should use gst_buffer_make_metadata_writable(), which will create a subbuffer of the original buffer to ensure the caller has sole ownership, and not copy the buffer data.
Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE.
NativeObject.Initializer
defaultInit, LIFECYCLE, ownsHandle
Constructor and Description |
---|
Buffer()
Creates a newly allocated buffer without any data.
|
Buffer(int size)
Creates a newly allocated buffer with data of the given size.
|
Buffer(NativeObject.Initializer init) |
Modifier and Type | Method and Description |
---|---|
Buffer |
createSubBuffer(int offset,
int size)
Creates a sub-buffer from this buffer at offset and size.
|
com.sun.jna.Pointer |
getAddress()
Gets the native address of this Buffer
|
java.nio.ByteBuffer |
getByteBuffer()
Gets a
ByteBuffer that can access the native memory
associated with this Buffer. |
Caps |
getCaps()
Gets the media type of the buffer.
|
ClockTime |
getDuration()
Gets the duration in time of the buffer data, can be
ClockTime.NONE
when the duration is not known or relevant. |
int |
getFlags()
Gets GstBuffer flags
|
long |
getLastOffset()
Gets the last offset contained in this buffer.
|
long |
getOffset()
Gets the offset for the buffer data in the stream.
|
int |
getSize()
Gets the size of the buffer data
|
ClockTime |
getTimestamp()
Gets the timestamp in time of the buffer data, can be
ClockTime.NONE
when the timestamp is not known or relevant. |
boolean |
isMetadataWritable() |
boolean |
isWritable()
Tests if you can safely write data into a buffer's data array or validly
modify the caps and timestamp metadata.
|
Buffer |
makeWritable()
Makes a writable buffer from this buffer.
|
void |
setCaps(Caps caps)
Sets the media type on the buffer.
|
void |
setDuration(ClockTime dur) |
void |
setLastOffset(long offset)
Sets the last offset contained in this buffer.
|
void |
setOffset(long offset)
Sets the offset of the buffer in the media stream.
|
void |
setTimestamp(ClockTime timestamp)
Sets the timestamp in time of the buffer data, can be
ClockTime.NONE
when the timestamp is not known or relevant. |
disposeNativeHandle, makeWritable, ref, unref
classFor, disown, dispose, equals, finalize, getNativeAddress, handle, hashCode, initializer, initializer, instanceFor, invalidate, isDisposed, nativeValue, objectFor, objectFor, objectFor, objectFor, toString
public Buffer(NativeObject.Initializer init)
public Buffer()
public Buffer(int size)
size
- public com.sun.jna.Pointer getAddress()
public Buffer createSubBuffer(int offset, int 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 both be set to -1.
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 -1.
offset
- The offset into parent Buffer at which the new sub-buffer begins.size
- the size of the new Buffer sub-buffer, in bytes.public boolean isWritable()
isWritable
in class MiniObject
public Buffer makeWritable()
public boolean isMetadataWritable()
public int getSize()
public ClockTime getDuration()
ClockTime.NONE
when the duration is not known or relevant.public void setDuration(ClockTime dur)
public ClockTime getTimestamp()
ClockTime.NONE
when the timestamp is not known or relevant.public void setTimestamp(ClockTime timestamp)
ClockTime.NONE
when the timestamp is not known or relevant.public Caps getCaps()
Caps
describing the media type, or null if there was no
media type associated with the buffer.public void setCaps(Caps caps)
caps
- the Caps
describing the media type.public java.nio.ByteBuffer getByteBuffer()
ByteBuffer
that can access the native memory
associated with this Buffer.ByteBuffer
that can access this Buffer's data.public long getOffset()
The offset is 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.
public void setOffset(long offset)
offset
- getOffset()
public long getLastOffset()
It has the same format as getOffset
public void setLastOffset(long offset)
It has the same format as getOffset
public int getFlags()