Package org.jocl

Class Pointer


  • public final class Pointer
    extends NativePointerObject
    A Java representation of a void pointer.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        Pointer()
      Creates a new (null) Pointer
      protected Pointer​(java.nio.Buffer buffer)
      Creates a Pointer to the given Buffer
      private Pointer​(NativePointerObject[] pointers)
      Creates a Pointer to the given array of pointers
      protected Pointer​(Pointer other)
      Copy constructor
      protected Pointer​(Pointer other, long byteOffset)
      Creates a copy of the given pointer, with an additional byte offset
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private static Pointer computePointer​(java.nio.ByteBuffer buffer)
      Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
      private static Pointer computePointer​(java.nio.DoubleBuffer buffer)
      Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
      private static Pointer computePointer​(java.nio.FloatBuffer buffer)
      Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
      private static Pointer computePointer​(java.nio.IntBuffer buffer)
      Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
      private static Pointer computePointer​(java.nio.LongBuffer buffer)
      Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
      private static Pointer computePointer​(java.nio.ShortBuffer buffer)
      Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
      java.nio.ByteBuffer getByteBuffer​(long byteOffset, long byteSize)
      Returns a ByteBuffer that corresponds to the specified segment of the memory that this pointer points to.

      This function is solely intended for pointers that that have been allocated with CL.clSVMAlloc(org.jocl.cl_context, long, long, int).
      (package private) boolean isDirectBufferPointer()
      Returns whether this Pointer is a Pointer to a direct Buffer.
      static Pointer to​(byte[] values)
      Creates a new Pointer to the given values.
      static Pointer to​(char[] values)
      Creates a new Pointer to the given values.
      static Pointer to​(double[] values)
      Creates a new Pointer to the given values.
      static Pointer to​(float[] values)
      Creates a new Pointer to the given values.
      static Pointer to​(int[] values)
      Creates a new Pointer to the given values.
      static Pointer to​(long[] values)
      Creates a new Pointer to the given values.
      static Pointer to​(short[] values)
      Creates a new Pointer to the given values.
      static Pointer to​(java.nio.Buffer buffer)
      NOTE: This method does not take into account the position and array offset of the given buffer.
      static Pointer to​(NativePointerObject pointer)
      Creates a new Pointer to the given Pointer.
      static Pointer to​(NativePointerObject... pointers)
      Creates a new Pointer to the given Pointers.
      static Pointer toBuffer​(java.nio.Buffer buffer)
      Creates a new Pointer to the given buffer.

      Note that this method takes into account the array offset and position of the given buffer, in contrast to the to(Buffer) method.
      Pointer withByteOffset​(long byteOffset)
      Returns a new pointer with an offset of the given number of bytes
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • BUFFER_MAY_NOT_BE_NULL

        private static final java.lang.String BUFFER_MAY_NOT_BE_NULL
        The error message that will be part of the IllegalArgumentException when a null buffer is passed to the to(Buffer) or toBuffer(Buffer) method
        See Also:
        Constant Field Values
      • BUFFER_MUST_HAVE_ARRAY_OR_BE_DIRECT

        private static final java.lang.String BUFFER_MUST_HAVE_ARRAY_OR_BE_DIRECT
        The error message that will be part of the IllegalArgumentException when a buffer is passed to the toBuffer(Buffer) method neither has an array nor is direct
        See Also:
        Constant Field Values
    • Constructor Detail

      • Pointer

        public Pointer()
        Creates a new (null) Pointer
      • Pointer

        protected Pointer​(java.nio.Buffer buffer)
        Creates a Pointer to the given Buffer
        Parameters:
        buffer - The buffer to point to
      • Pointer

        private Pointer​(NativePointerObject[] pointers)
        Creates a Pointer to the given array of pointers
        Parameters:
        pointers - The array the pointer points to
      • Pointer

        protected Pointer​(Pointer other)
        Copy constructor
        Parameters:
        other - The other Pointer
      • Pointer

        protected Pointer​(Pointer other,
                          long byteOffset)
        Creates a copy of the given pointer, with an additional byte offset
        Parameters:
        other - The other pointer
        byteOffset - The additional byte offset
    • Method Detail

      • to

        public static Pointer to​(byte[] values)
        Creates a new Pointer to the given values. The values may not be null.
        Parameters:
        values - The values the pointer should point to
        Returns:
        The pointer
      • to

        public static Pointer to​(char[] values)
        Creates a new Pointer to the given values. The values may not be null.
        Parameters:
        values - The values the pointer should point to
        Returns:
        The pointer
      • to

        public static Pointer to​(short[] values)
        Creates a new Pointer to the given values. The values may not be null.
        Parameters:
        values - The values the pointer should point to
        Returns:
        The pointer
      • to

        public static Pointer to​(int[] values)
        Creates a new Pointer to the given values. The values may not be null.
        Parameters:
        values - The values the pointer should point to
        Returns:
        The pointer
      • to

        public static Pointer to​(float[] values)
        Creates a new Pointer to the given values. The values may not be null.
        Parameters:
        values - The values the pointer should point to
        Returns:
        The pointer
      • to

        public static Pointer to​(long[] values)
        Creates a new Pointer to the given values. The values may not be null.
        Parameters:
        values - The values the pointer should point to
        Returns:
        The pointer
      • to

        public static Pointer to​(double[] values)
        Creates a new Pointer to the given values. The values may not be null.
        Parameters:
        values - The values the pointer should point to
        Returns:
        The pointer
      • to

        public static Pointer to​(java.nio.Buffer buffer)
        NOTE: This method does not take into account the position and array offset of the given buffer. In order to create a pointer that takes the position and array offset into account, use the toBuffer(Buffer) method.

        If the given buffer has a backing array, then the returned pointer will in any case point to the start of the array, even if the buffer has been created using the slice method (like ByteBuffer.slice()). If the buffer is direct, then this method will return a Pointer to the address of the direct buffer. If the buffer has been created using the slice method, then this will be the actual start of the slice. Although this implies a different treatment of direct- and non direct buffers, the method is kept for backward compatibility.

        In both cases, for direct and array-based buffers, this method does not take into account the position of the given buffer.

        The buffer must not be null, and either be a direct buffer, or have a backing array
        Parameters:
        buffer - The buffer the pointer should point to
        Returns:
        The pointer
        Throws:
        java.lang.IllegalArgumentException - If the given buffer is null or is neither direct nor has a backing array
      • toBuffer

        public static Pointer toBuffer​(java.nio.Buffer buffer)
        Creates a new Pointer to the given buffer.

        Note that this method takes into account the array offset and position of the given buffer, in contrast to the to(Buffer) method.
        Parameters:
        buffer - The buffer
        Returns:
        The new pointer
        Throws:
        java.lang.IllegalArgumentException - If the given buffer is null or is neither direct nor has a backing array
      • computePointer

        private static Pointer computePointer​(java.nio.ByteBuffer buffer)
        Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
        Parameters:
        buffer - The buffer
        Returns:
        The pointer
        Throws:
        java.lang.IllegalArgumentException - If the given buffer is neither direct nor has a backing array
      • computePointer

        private static Pointer computePointer​(java.nio.ShortBuffer buffer)
        Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
        Parameters:
        buffer - The buffer
        Returns:
        The pointer
        Throws:
        java.lang.IllegalArgumentException - If the given buffer is neither direct nor has a backing array
      • computePointer

        private static Pointer computePointer​(java.nio.IntBuffer buffer)
        Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
        Parameters:
        buffer - The buffer
        Returns:
        The pointer
        Throws:
        java.lang.IllegalArgumentException - If the given buffer is neither direct nor has a backing array
      • computePointer

        private static Pointer computePointer​(java.nio.LongBuffer buffer)
        Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
        Parameters:
        buffer - The buffer
        Returns:
        The pointer
        Throws:
        java.lang.IllegalArgumentException - If the given buffer is neither direct nor has a backing array
      • computePointer

        private static Pointer computePointer​(java.nio.FloatBuffer buffer)
        Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
        Parameters:
        buffer - The buffer
        Returns:
        The pointer
        Throws:
        java.lang.IllegalArgumentException - If the given buffer is neither direct nor has a backing array
      • computePointer

        private static Pointer computePointer​(java.nio.DoubleBuffer buffer)
        Creates a new Pointer to the given buffer, taking into account the position and array offset of the given buffer.
        Parameters:
        buffer - The buffer
        Returns:
        The pointer
        Throws:
        java.lang.IllegalArgumentException - If the given buffer is neither direct nor has a backing array
      • to

        public static Pointer to​(NativePointerObject pointer)
        Creates a new Pointer to the given Pointer. The pointer may not be null.
        Parameters:
        pointer - The pointer the pointer should point to
        Returns:
        The new pointer
        Throws:
        java.lang.IllegalArgumentException - If the given pointer is null
      • to

        public static Pointer to​(NativePointerObject... pointers)
        Creates a new Pointer to the given Pointers. The array of pointers may not be null, and may not contain null elements.
        Parameters:
        pointers - The pointers the pointer should point to
        Returns:
        The new pointer
        Throws:
        java.lang.IllegalArgumentException - If the given array is null
      • isDirectBufferPointer

        boolean isDirectBufferPointer()
        Returns whether this Pointer is a Pointer to a direct Buffer.
        Returns:
        Whether this pointer is a Pointer to a direct Buffer
      • withByteOffset

        public Pointer withByteOffset​(long byteOffset)
        Returns a new pointer with an offset of the given number of bytes
        Overrides:
        withByteOffset in class NativePointerObject
        Parameters:
        byteOffset - The byte offset for the pointer
        Returns:
        The new pointer with the given byte offset
      • getByteBuffer

        public java.nio.ByteBuffer getByteBuffer​(long byteOffset,
                                                 long byteSize)
        Returns a ByteBuffer that corresponds to the specified segment of the memory that this pointer points to.

        This function is solely intended for pointers that that have been allocated with CL.clSVMAlloc(org.jocl.cl_context, long, long, int).
        (It will work for all pointers to ByteBuffers, but for other pointer types, null will be returned)
        Parameters:
        byteOffset - The offset in bytes
        byteSize - The size of the byte buffer, in bytes
        Returns:
        The byte buffer