com.jogamp.common.nio
Class Buffers

java.lang.Object
  extended by com.jogamp.common.nio.Buffers

public class Buffers
extends Object

Utility methods allowing easy Buffer manipulations.

Author:
Kenneth Russel, Sven Gothel, Michael Bien

Field Summary
static int SIZEOF_BYTE
           
static int SIZEOF_CHAR
           
static int SIZEOF_DOUBLE
           
static int SIZEOF_FLOAT
           
static int SIZEOF_INT
           
static int SIZEOF_LONG
           
static int SIZEOF_SHORT
           
 
Constructor Summary
protected Buffers()
           
 
Method Summary
static ByteBuffer copyByteBuffer(ByteBuffer orig)
          Copies the remaining elements (as defined by limit() - position()) in the passed ByteBuffer into a newly-allocated direct ByteBuffer.
static FloatBuffer copyFloatBuffer(FloatBuffer orig)
          Copies the remaining elements (as defined by limit() - position()) in the passed FloatBuffer into a newly-allocated direct FloatBuffer.
static ByteBuffer copyFloatBufferAsByteBuffer(FloatBuffer orig)
          Copies the remaining elements (as defined by limit() - position()) in the passed FloatBuffer into a newly-allocated direct ByteBuffer.
static IntBuffer copyIntBuffer(IntBuffer orig)
          Copies the remaining elements (as defined by limit() - position()) in the passed IntBuffer into a newly-allocated direct IntBuffer.
static ByteBuffer copyIntBufferAsByteBuffer(IntBuffer orig)
          Copies the remaining elements (as defined by limit() - position()) in the passed IntBuffer into a newly-allocated direct ByteBuffer.
static ShortBuffer copyShortBuffer(ShortBuffer orig)
          Copies the remaining elements (as defined by limit() - position()) in the passed ShortBuffer into a newly-allocated direct ShortBuffer.
static ByteBuffer copyShortBufferAsByteBuffer(ShortBuffer orig)
          Copies the remaining elements (as defined by limit() - position()) in the passed ShortBuffer into a newly-allocated direct ByteBuffer.
static Object getArray(Object buf)
          Helper routine to return the array backing store reference from a Buffer object.
static int getDirectBufferByteOffset(Object buf)
          Helper routine to get the Buffer byte offset by taking into account the Buffer position and the underlying type.
static double[] getDoubleArray(float[] source, int soffset, double[] dest, int doffset, int len)
           
static DoubleBuffer getDoubleBuffer(FloatBuffer source, DoubleBuffer dest)
          No rewind or repositioning is performed.
static float[] getFloatArray(double[] source, int soffset, float[] dest, int doffset, int len)
           
static FloatBuffer getFloatBuffer(DoubleBuffer source, FloatBuffer dest)
          No rewind or repositioning is performed.
static int getIndirectBufferByteOffset(Object buf)
          Helper routine to get the full byte offset from the beginning of the array that is the storage for the indirect Buffer object.
static boolean isDirect(Object buf)
          Helper routine to tell whether a buffer is direct or not.
static ByteBuffer nativeOrder(ByteBuffer buf)
          Helper routine to set a ByteBuffer to the native byte order, if that operation is supported by the underlying NIO implementation.
static ByteBuffer newDirectByteBuffer(byte[] values)
           
static ByteBuffer newDirectByteBuffer(byte[] values, int offset)
           
static ByteBuffer newDirectByteBuffer(byte[] values, int offset, int lenght)
           
static ByteBuffer newDirectByteBuffer(int numElements)
          Allocates a new direct ByteBuffer with the specified number of elements.
static CharBuffer newDirectCharBuffer(char[] values)
           
static CharBuffer newDirectCharBuffer(char[] values, int offset)
           
static CharBuffer newDirectCharBuffer(char[] values, int offset, int lenght)
           
static CharBuffer newDirectCharBuffer(int numElements)
          Allocates a new direct CharBuffer with the specified number of elements.
static DoubleBuffer newDirectDoubleBuffer(double[] values)
           
static DoubleBuffer newDirectDoubleBuffer(double[] values, int offset)
           
static DoubleBuffer newDirectDoubleBuffer(double[] values, int offset, int lenght)
           
static DoubleBuffer newDirectDoubleBuffer(int numElements)
          Allocates a new direct DoubleBuffer with the specified number of elements.
static FloatBuffer newDirectFloatBuffer(float[] values)
           
static FloatBuffer newDirectFloatBuffer(float[] values, int offset)
           
static FloatBuffer newDirectFloatBuffer(float[] values, int offset, int lenght)
           
static FloatBuffer newDirectFloatBuffer(int numElements)
          Allocates a new direct FloatBuffer with the specified number of elements.
static IntBuffer newDirectIntBuffer(int numElements)
          Allocates a new direct IntBuffer with the specified number of elements.
static IntBuffer newDirectIntBuffer(int[] values)
           
static IntBuffer newDirectIntBuffer(int[] values, int offset)
           
static IntBuffer newDirectIntBuffer(int[] values, int offset, int lenght)
           
static LongBuffer newDirectLongBuffer(int numElements)
          Allocates a new direct LongBuffer with the specified number of elements.
static LongBuffer newDirectLongBuffer(long[] values)
           
static LongBuffer newDirectLongBuffer(long[] values, int offset)
           
static LongBuffer newDirectLongBuffer(long[] values, int offset, int lenght)
           
static ShortBuffer newDirectShortBuffer(int numElements)
          Allocates a new direct ShortBuffer with the specified number of elements.
static ShortBuffer newDirectShortBuffer(short[] values)
           
static ShortBuffer newDirectShortBuffer(short[] values, int offset)
           
static ShortBuffer newDirectShortBuffer(short[] values, int offset, int lenght)
           
static
<B extends Buffer>
B
put(B dest, Buffer src)
           
static
<B extends Buffer>
B
putb(B dest, byte v)
           
static
<B extends Buffer>
B
putd(B dest, double v)
           
static
<B extends Buffer>
B
putf(B dest, float v)
           
static
<B extends Buffer>
B
puti(B dest, int v)
           
static
<B extends Buffer>
B
putNb(B dest, boolean dSigned, byte v, boolean sSigned)
          Store byte source value in given buffer after normalizing it to the destination value range considering signed and unsigned source and destination representation.
static
<B extends Buffer>
B
putNf(B dest, boolean dSigned, float v)
          Store float source value in given buffer after normalizing it to the destination value range considering signed and unsigned destination representation.
static
<B extends Buffer>
B
putNi(B dest, boolean dSigned, int v, boolean sSigned)
          Store short source value in given buffer after normalizing it to the destination value range considering signed and unsigned source and destination representation.
static
<B extends Buffer>
B
putNs(B dest, boolean dSigned, short v, boolean sSigned)
          Store short source value in given buffer after normalizing it to the destination value range considering signed and unsigned source and destination representation.
static
<B extends Buffer>
B
puts(B dest, short v)
           
static void rangeCheck(Buffer buffer, int minElementsRemaining)
           
static void rangeCheck(byte[] array, int offset, int minElementsRemaining)
           
static void rangeCheck(char[] array, int offset, int minElementsRemaining)
           
static void rangeCheck(double[] array, int offset, int minElementsRemaining)
           
static void rangeCheck(float[] array, int offset, int minElementsRemaining)
           
static void rangeCheck(int[] array, int offset, int minElementsRemaining)
           
static void rangeCheck(long[] array, int offset, int minElementsRemaining)
           
static void rangeCheck(short[] array, int offset, int minElementsRemaining)
           
static void rangeCheckBytes(Object buffer, int minBytesRemaining)
           
static int sizeOfBufferElem(Buffer buffer)
          Returns the size of a single element of this buffer in bytes.
static
<B extends Buffer>
B
slice(B buffer)
          Calls slice on the specified buffer while maintaining the byteorder.
static
<B extends Buffer>
B
slice(B buffer, int offset, int size)
          Slices the specified buffer with offset as position and offset+size as limit while maintaining the byteorder.
static FloatBuffer slice2Float(Buffer buf, float[] backing, int floatPos, int floatSize)
          Slices a ByteBuffer or a primitive float array to a FloatBuffer at the given position with the given size in float-space.
static StringBuilder toString(StringBuilder sb, String f, Buffer buffer)
          Appends Buffer details inclusive data to a StringBuilder instance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SIZEOF_BYTE

public static final int SIZEOF_BYTE
See Also:
Constant Field Values

SIZEOF_SHORT

public static final int SIZEOF_SHORT
See Also:
Constant Field Values

SIZEOF_CHAR

public static final int SIZEOF_CHAR
See Also:
Constant Field Values

SIZEOF_INT

public static final int SIZEOF_INT
See Also:
Constant Field Values

SIZEOF_FLOAT

public static final int SIZEOF_FLOAT
See Also:
Constant Field Values

SIZEOF_LONG

public static final int SIZEOF_LONG
See Also:
Constant Field Values

SIZEOF_DOUBLE

public static final int SIZEOF_DOUBLE
See Also:
Constant Field Values
Constructor Detail

Buffers

protected Buffers()
Method Detail

newDirectByteBuffer

public static ByteBuffer newDirectByteBuffer(int numElements)
Allocates a new direct ByteBuffer with the specified number of elements. The returned buffer will have its byte order set to the host platform's native byte order.


newDirectByteBuffer

public static ByteBuffer newDirectByteBuffer(byte[] values,
                                             int offset,
                                             int lenght)

newDirectByteBuffer

public static ByteBuffer newDirectByteBuffer(byte[] values,
                                             int offset)

newDirectByteBuffer

public static ByteBuffer newDirectByteBuffer(byte[] values)

newDirectDoubleBuffer

public static DoubleBuffer newDirectDoubleBuffer(int numElements)
Allocates a new direct DoubleBuffer with the specified number of elements. The returned buffer will have its byte order set to the host platform's native byte order.


newDirectDoubleBuffer

public static DoubleBuffer newDirectDoubleBuffer(double[] values,
                                                 int offset,
                                                 int lenght)

newDirectDoubleBuffer

public static DoubleBuffer newDirectDoubleBuffer(double[] values,
                                                 int offset)

newDirectDoubleBuffer

public static DoubleBuffer newDirectDoubleBuffer(double[] values)

newDirectFloatBuffer

public static FloatBuffer newDirectFloatBuffer(int numElements)
Allocates a new direct FloatBuffer with the specified number of elements. The returned buffer will have its byte order set to the host platform's native byte order.


newDirectFloatBuffer

public static FloatBuffer newDirectFloatBuffer(float[] values,
                                               int offset,
                                               int lenght)

newDirectFloatBuffer

public static FloatBuffer newDirectFloatBuffer(float[] values,
                                               int offset)

newDirectFloatBuffer

public static FloatBuffer newDirectFloatBuffer(float[] values)

newDirectIntBuffer

public static IntBuffer newDirectIntBuffer(int numElements)
Allocates a new direct IntBuffer with the specified number of elements. The returned buffer will have its byte order set to the host platform's native byte order.


newDirectIntBuffer

public static IntBuffer newDirectIntBuffer(int[] values,
                                           int offset,
                                           int lenght)

newDirectIntBuffer

public static IntBuffer newDirectIntBuffer(int[] values,
                                           int offset)

newDirectIntBuffer

public static IntBuffer newDirectIntBuffer(int[] values)

newDirectLongBuffer

public static LongBuffer newDirectLongBuffer(int numElements)
Allocates a new direct LongBuffer with the specified number of elements. The returned buffer will have its byte order set to the host platform's native byte order.


newDirectLongBuffer

public static LongBuffer newDirectLongBuffer(long[] values,
                                             int offset,
                                             int lenght)

newDirectLongBuffer

public static LongBuffer newDirectLongBuffer(long[] values,
                                             int offset)

newDirectLongBuffer

public static LongBuffer newDirectLongBuffer(long[] values)

newDirectShortBuffer

public static ShortBuffer newDirectShortBuffer(int numElements)
Allocates a new direct ShortBuffer with the specified number of elements. The returned buffer will have its byte order set to the host platform's native byte order.


newDirectShortBuffer

public static ShortBuffer newDirectShortBuffer(short[] values,
                                               int offset,
                                               int lenght)

newDirectShortBuffer

public static ShortBuffer newDirectShortBuffer(short[] values,
                                               int offset)

newDirectShortBuffer

public static ShortBuffer newDirectShortBuffer(short[] values)

newDirectCharBuffer

public static CharBuffer newDirectCharBuffer(int numElements)
Allocates a new direct CharBuffer with the specified number of elements. The returned buffer will have its byte order set to the host platform's native byte order.


newDirectCharBuffer

public static CharBuffer newDirectCharBuffer(char[] values,
                                             int offset,
                                             int lenght)

newDirectCharBuffer

public static CharBuffer newDirectCharBuffer(char[] values,
                                             int offset)

newDirectCharBuffer

public static CharBuffer newDirectCharBuffer(char[] values)

slice

public static <B extends Buffer> B slice(B buffer)
Calls slice on the specified buffer while maintaining the byteorder.

See Also:
slice(java.nio.Buffer, int, int)

slice

public static <B extends Buffer> B slice(B buffer,
                                         int offset,
                                         int size)
Slices the specified buffer with offset as position and offset+size as limit while maintaining the byteorder. Concurrency warning: this method changes the buffers position and limit but will restore it before return.


slice2Float

public static final FloatBuffer slice2Float(Buffer buf,
                                            float[] backing,
                                            int floatPos,
                                            int floatSize)
Slices a ByteBuffer or a primitive float array to a FloatBuffer at the given position with the given size in float-space.

The returned sliced buffer's start position is not necessarily zero, but the float position within the host ByteBuffer.

The returned sliced buffer is marked at it's starting position. Hence Buffer.reset() will rewind it to start after applying relative operations like FloatBuffer.get().

Using a ByteBuffer as the source guarantees keeping the source native order programmatically. This works around Honeycomb / Android 3.0 Issue 16434. This bug is resolved at least in Android 3.2.

Parameters:
buf - source Buffer, maybe ByteBuffer (recommended) or FloatBuffer or null. Buffer's position is ignored and floatPos is being used.
backing - source float array or null
floatPos - SIZEOF_FLOAT position
floatSize - SIZEOF_FLOAT size
Returns:
FloatBuffer w/ native byte order as given ByteBuffer

nativeOrder

public static ByteBuffer nativeOrder(ByteBuffer buf)
Helper routine to set a ByteBuffer to the native byte order, if that operation is supported by the underlying NIO implementation.


sizeOfBufferElem

public static int sizeOfBufferElem(Buffer buffer)
Returns the size of a single element of this buffer in bytes.


isDirect

public static boolean isDirect(Object buf)
Helper routine to tell whether a buffer is direct or not. Null pointers are considered direct.


getDirectBufferByteOffset

public static int getDirectBufferByteOffset(Object buf)
Helper routine to get the Buffer byte offset by taking into account the Buffer position and the underlying type. This is the total offset for Direct Buffers.


getArray

public static Object getArray(Object buf)
                       throws UnsupportedOperationException,
                              IllegalArgumentException
Helper routine to return the array backing store reference from a Buffer object.

Throws:
UnsupportedOperationException - if the passed Object does not have an array backing store
IllegalArgumentException - if the passed Object is neither of type Buffer or NativeBuffer.

getIndirectBufferByteOffset

public static int getIndirectBufferByteOffset(Object buf)
Helper routine to get the full byte offset from the beginning of the array that is the storage for the indirect Buffer object. The array offset also includes the position offset within the buffer, in addition to any array offset.


copyByteBuffer

public static ByteBuffer copyByteBuffer(ByteBuffer orig)
Copies the remaining elements (as defined by limit() - position()) in the passed ByteBuffer into a newly-allocated direct ByteBuffer. The returned buffer will have its byte order set to the host platform's native byte order. The position of the newly-allocated buffer will be zero, and the position of the passed buffer is unchanged.


copyFloatBuffer

public static FloatBuffer copyFloatBuffer(FloatBuffer orig)
Copies the remaining elements (as defined by limit() - position()) in the passed FloatBuffer into a newly-allocated direct FloatBuffer. The returned buffer will have its byte order set to the host platform's native byte order. The position of the newly-allocated buffer will be zero, and the position of the passed buffer is unchanged.


copyIntBuffer

public static IntBuffer copyIntBuffer(IntBuffer orig)
Copies the remaining elements (as defined by limit() - position()) in the passed IntBuffer into a newly-allocated direct IntBuffer. The returned buffer will have its byte order set to the host platform's native byte order. The position of the newly-allocated buffer will be zero, and the position of the passed buffer is unchanged.


copyShortBuffer

public static ShortBuffer copyShortBuffer(ShortBuffer orig)
Copies the remaining elements (as defined by limit() - position()) in the passed ShortBuffer into a newly-allocated direct ShortBuffer. The returned buffer will have its byte order set to the host platform's native byte order. The position of the newly-allocated buffer will be zero, and the position of the passed buffer is unchanged.


copyFloatBufferAsByteBuffer

public static ByteBuffer copyFloatBufferAsByteBuffer(FloatBuffer orig)
Copies the remaining elements (as defined by limit() - position()) in the passed FloatBuffer into a newly-allocated direct ByteBuffer. The returned buffer will have its byte order set to the host platform's native byte order. The position of the newly-allocated buffer will be zero, and the position of the passed buffer is unchanged.


copyIntBufferAsByteBuffer

public static ByteBuffer copyIntBufferAsByteBuffer(IntBuffer orig)
Copies the remaining elements (as defined by limit() - position()) in the passed IntBuffer into a newly-allocated direct ByteBuffer. The returned buffer will have its byte order set to the host platform's native byte order. The position of the newly-allocated buffer will be zero, and the position of the passed buffer is unchanged.


copyShortBufferAsByteBuffer

public static ByteBuffer copyShortBufferAsByteBuffer(ShortBuffer orig)
Copies the remaining elements (as defined by limit() - position()) in the passed ShortBuffer into a newly-allocated direct ByteBuffer. The returned buffer will have its byte order set to the host platform's native byte order. The position of the newly-allocated buffer will be zero, and the position of the passed buffer is unchanged.


getFloatArray

public static float[] getFloatArray(double[] source,
                                    int soffset,
                                    float[] dest,
                                    int doffset,
                                    int len)
Parameters:
source - the source array
soffset - the offset
dest - the target array, if null, a new array is being created with size len.
doffset - the offset in the dest array
len - the payload of elements to be copied, if len < 0 then len = source.length - soffset
Returns:
the passed or newly created target array

getFloatBuffer

public static FloatBuffer getFloatBuffer(DoubleBuffer source,
                                         FloatBuffer dest)
No rewind or repositioning is performed.

Parameters:
source - the source buffer, which elements from it's current position and it's limit are being copied
dest - the target buffer, if null, a new buffer is being created with size source.remaining()
Returns:
the passed or newly created target buffer

getDoubleArray

public static double[] getDoubleArray(float[] source,
                                      int soffset,
                                      double[] dest,
                                      int doffset,
                                      int len)
Parameters:
source - the source array
soffset - the offset
dest - the target array, if null, a new array is being created with size len.
doffset - the offset in the dest array
len - the payload of elements to be copied, if len < 0 then len = source.length - soffset
Returns:
the passed or newly created target array

getDoubleBuffer

public static DoubleBuffer getDoubleBuffer(FloatBuffer source,
                                           DoubleBuffer dest)
No rewind or repositioning is performed.

Parameters:
source - the source buffer, which elements from it's current position and it's limit are being copied
dest - the target buffer, if null, a new buffer is being created with size source.remaining()
Returns:
the passed or newly created target buffer

put

public static <B extends Buffer> B put(B dest,
                                       Buffer src)

putb

public static <B extends Buffer> B putb(B dest,
                                        byte v)

puts

public static <B extends Buffer> B puts(B dest,
                                        short v)

puti

public static <B extends Buffer> B puti(B dest,
                                        int v)

putf

public static <B extends Buffer> B putf(B dest,
                                        float v)

putd

public static <B extends Buffer> B putd(B dest,
                                        double v)

putNb

public static <B extends Buffer> B putNb(B dest,
                                         boolean dSigned,
                                         byte v,
                                         boolean sSigned)
Store byte source value in given buffer after normalizing it to the destination value range considering signed and unsigned source and destination representation.

Parameters:
dest - One of ByteBuffer, ShortBuffer, IntBuffer, FloatBuffer
dSigned - true if destination buffer holds signed values, false if destination buffer holds unsigned values
v - source byte value to be put in dest buffer
sSigned - true if source represents a signed value, false if source represents an unsigned value

putNs

public static <B extends Buffer> B putNs(B dest,
                                         boolean dSigned,
                                         short v,
                                         boolean sSigned)
Store short source value in given buffer after normalizing it to the destination value range considering signed and unsigned source and destination representation.

Parameters:
dest - One of ByteBuffer, ShortBuffer, IntBuffer, FloatBuffer
dSigned - true if destination buffer holds signed values, false if destination buffer holds unsigned values
v - source short value to be put in dest buffer
sSigned - true if source represents a signed value, false if source represents an unsigned value

putNi

public static <B extends Buffer> B putNi(B dest,
                                         boolean dSigned,
                                         int v,
                                         boolean sSigned)
Store short source value in given buffer after normalizing it to the destination value range considering signed and unsigned source and destination representation.

Parameters:
dest - One of ByteBuffer, ShortBuffer, IntBuffer, FloatBuffer
dSigned - true if destination buffer holds signed values, false if destination buffer holds unsigned values
v - source short value to be put in dest buffer
sSigned - true if source represents a signed value, false if source represents an unsigned value

putNf

public static <B extends Buffer> B putNf(B dest,
                                         boolean dSigned,
                                         float v)
Store float source value in given buffer after normalizing it to the destination value range considering signed and unsigned destination representation.

Parameters:
dest - One of ByteBuffer, ShortBuffer, IntBuffer, FloatBuffer
dSigned - true if destination buffer holds signed values, false if destination buffer holds unsigned values
v - source float value to be put in dest buffer

rangeCheck

public static void rangeCheck(byte[] array,
                              int offset,
                              int minElementsRemaining)

rangeCheck

public static void rangeCheck(char[] array,
                              int offset,
                              int minElementsRemaining)

rangeCheck

public static void rangeCheck(short[] array,
                              int offset,
                              int minElementsRemaining)

rangeCheck

public static void rangeCheck(int[] array,
                              int offset,
                              int minElementsRemaining)

rangeCheck

public static void rangeCheck(long[] array,
                              int offset,
                              int minElementsRemaining)

rangeCheck

public static void rangeCheck(float[] array,
                              int offset,
                              int minElementsRemaining)

rangeCheck

public static void rangeCheck(double[] array,
                              int offset,
                              int minElementsRemaining)

rangeCheck

public static void rangeCheck(Buffer buffer,
                              int minElementsRemaining)

rangeCheckBytes

public static void rangeCheckBytes(Object buffer,
                                   int minBytesRemaining)

toString

public static StringBuilder toString(StringBuilder sb,
                                     String f,
                                     Buffer buffer)
Appends Buffer details inclusive data to a StringBuilder instance.

Parameters:
sb - optional pass through StringBuilder
f - optional format string of one element, i.e. "%10.5f" for FloatBuffer, see Formatter, or null for unformatted output. Note: Caller is responsible to match the format string w/ the data type as expected in the given buffer.
buffer - Any valid Buffer instance
Returns:
the modified StringBuilder containing the Buffer details