Package com.jogamp.common.nio

Class Buffers

  • public class Buffers
extends Object
    Utility methods allowing easy Buffer manipulations.
    Author:
    Kenneth Russel, Sven Gothel, Michael Bien

    • 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 length)

      • 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 length)

      • 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 length)

      • 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 length)

      • 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 length)

      • 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 length)

      • 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 length)

      • 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,
                                         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,
                                            int floatStartPos,
                                            int floatSize)
        Slices a ByteBuffer or a FloatBuffer to a FloatBuffer at the given position with the given size in float-space.

        The returned sliced buffer's start position is always zero.

        The returned sliced buffer is marked at it's start position. Hence FloatBuffer.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. Buffer's position is ignored and floatPos is being used.
        floatStartPos - SIZEOF_FLOAT position
        floatSize - SIZEOF_FLOAT size
        Returns:
        FloatBuffer w/ native byte order as given ByteBuffer

      • slice2Float

        public static final FloatBuffer slice2Float​(float[] backing,
                                            int floatStartPos,
                                            int floatSize)
        Slices a primitive float backing array to a FloatBuffer at the given position with the given size in float-space by wrapping the backing array.

        Due to wrapping the backing array, the returned sliced buffer's start position equals the given floatStartPos within the given backing array while it's array-offset is zero. This has the advantage of being able to dismiss the array-offset in user code, while only being required to consider it's position.

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

        Parameters:
        backing - source float array
        floatStartPos - 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​(Object buffer)
        Returns the size of a single element of the given buffer in bytes or 0 if the given buffer is null.

      • remainingElem

        public static int remainingElem​(Object buffer)
                         throws IllegalArgumentException
        Returns the number of remaining elements of the given anonymous buffer.
        Parameters:
        buffer - Anonymous Buffer of type NativeBuffer or a derivation of Buffer.
        Returns:
        If buffer is null, returns 0, otherwise the remaining size in elements.
        Throws:
        IllegalArgumentException - if buffer is of invalid type.

      • remainingBytes

        public static int remainingBytes​(Object buffer)
                          throws IllegalArgumentException
        Returns the number of remaining bytes of the given anonymous buffer.
        Parameters:
        buffer - Anonymous Buffer of type NativeBuffer or a derivation of Buffer.
        Returns:
        If buffer is null, returns 0, otherwise the remaining size in bytes.
        Throws:
        IllegalArgumentException - if buffer is of invalid type.

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

      • 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)

      • 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