org.gstreamer
Class Buffer

java.lang.Object
  extended by org.gstreamer.lowlevel.NativeValue
      extended by org.gstreamer.lowlevel.Handle
          extended by org.gstreamer.lowlevel.NativeObject
              extended by org.gstreamer.lowlevel.RefCountedObject
                  extended by org.gstreamer.MiniObject
                      extended by org.gstreamer.Buffer

public class Buffer
extends MiniObject

Data-passing buffer type, supporting sub-buffers. Ssee 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.


Nested Class Summary
 
Nested classes/interfaces inherited from class org.gstreamer.lowlevel.NativeObject
NativeObject.Initializer
 
Field Summary
 
Fields inherited from class org.gstreamer.lowlevel.NativeObject
defaultInit, LIFECYCLE, ownsHandle
 
Constructor Summary
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)
           
 
Method Summary
 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.
 
Methods inherited from class org.gstreamer.MiniObject
disposeNativeHandle, makeWritable, ref, unref
 
Methods inherited from class org.gstreamer.lowlevel.NativeObject
classFor, disown, dispose, equals, finalize, getNativeAddress, handle, hashCode, initializer, initializer, instanceFor, invalidate, isDisposed, nativeValue, objectFor, objectFor, objectFor, objectFor, toString
 
Methods inherited from class java.lang.Object
clone, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Buffer

public Buffer(NativeObject.Initializer init)

Buffer

public Buffer()
Creates a newly allocated buffer without any data.


Buffer

public Buffer(int size)
Creates a newly allocated buffer with data of the given size. The buffer memory is not cleared. If the requested amount of memory cannot be allocated, an exception will be thrown. Note that when size == 0, the buffer data pointer will be NULL.

Parameters:
size -
Method Detail

getAddress

public com.sun.jna.Pointer getAddress()
Gets the native address of this Buffer

Returns:
a pointer

createSubBuffer

public Buffer createSubBuffer(int offset,
                              int 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 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.

Parameters:
offset - The offset into parent Buffer at which the new sub-buffer begins.
size - the size of the new Buffer sub-buffer, in bytes.
Returns:
The new Buffer, or null if the arguments were invalid.

isWritable

public boolean isWritable()
Tests if you can safely write data into a buffer's data array or validly modify the caps and timestamp metadata. Metadata in a GstBuffer is always writable, but it is only safe to change it when there is only one owner of the buffer - ie, the refcount is 1.

Overrides:
isWritable in class MiniObject
Returns:
true if the Buffer is writable.

makeWritable

public Buffer makeWritable()
Makes a writable buffer from this buffer. If the this buffer is already writable, this will simply return the same buffer. A copy will otherwise be made and returned.

Returns:
A writable Buffer referring to the same memory as this one.

isMetadataWritable

public boolean isMetadataWritable()

getSize

public int getSize()
Gets the size of the buffer data

Returns:
the size of the buffer data in bytes.

getDuration

public ClockTime getDuration()
Gets the duration in time of the buffer data, can be ClockTime.NONE when the duration is not known or relevant.

Returns:
a ClockTime representing the duration.

setDuration

public void setDuration(ClockTime dur)

getTimestamp

public ClockTime getTimestamp()
Gets the timestamp in time of the buffer data, can be ClockTime.NONE when the timestamp is not known or relevant.

Returns:
a ClockTime representing the timestamp.

setTimestamp

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


getCaps

public Caps getCaps()
Gets the media type of the buffer. This can be null if there is no media type attached to this buffer.

Returns:
a Caps describing the media type, or null if there was no media type associated with the buffer.

setCaps

public void setCaps(Caps caps)
Sets the media type on the buffer.

Parameters:
caps - the Caps describing the media type.

getByteBuffer

public java.nio.ByteBuffer getByteBuffer()
Gets a ByteBuffer that can access the native memory associated with this Buffer.

Returns:
A ByteBuffer that can access this Buffer's data.

getOffset

public long getOffset()
Gets the offset for the buffer data in the stream.

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.

Returns:
the offset

setOffset

public void setOffset(long offset)
Sets the offset of the buffer in the media stream.

Parameters:
offset -
See Also:
getOffset()

getLastOffset

public long getLastOffset()
Gets the last offset contained in this buffer.

It has the same format as getOffset

Returns:
the last offset

setLastOffset

public void setLastOffset(long offset)
Sets the last offset contained in this buffer.

It has the same format as getOffset


getFlags

public int getFlags()
Gets GstBuffer flags

Returns:
an integer value containing flags