Class SoCpuBufferObject

  • All Implemented Interfaces:
    SafeDisposable
    Direct Known Subclasses:
    SoCpuBufferBasicProperty, SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, SoCpuBufferUniform

    public class SoCpuBufferObject
    extends SoBufferObject
    CPU buffer object class. This class provides management functions for CPU memory buffers.

    By default memory allocations have the maximum possible alignment to allow use with (for example) SSE instructions.

    Memory is managed using the new/delete operators. On Microsoft Windows platforms it is possible to use VirtualAlloc/VirtualFree instead by setting OIV_BUFFER_USE_VIRTUAL_ALLOC (see SoPreferences).

    See SoBufferObject for general information about buffer objects.

    See SoBufferedShape for an example of storing vertices in a CPU buffer.

    EXAMPLE

    Load data into a buffer object from an array in memory:

     float[] vertices = {
             1.0f, 0.5f,0.0f, 0.0f, 1.0f,0.0f, -1.0f,0.5f,0.0f,
            -1.0f,-1.0f,0.0f, 1.0f,-1.0f,0.0f,  1.0f,0.0f,0.0f, -1.0f,0.0f,0.0f,
            -1.0f,-1.5f,0.0f, 1.0f,-1.5f,0.0f
     };
     
     // Create a CPU buffer object and set its size (allocate memory)
     SoCpuBufferObject cpuBuffer = new SoCpuBufferObject();
     cpuBuffer.setSize( vertices.length * Float.SIZE/8 );
     
     // Copy vertex data into the buffer object
     FloatBuffer vertData = cpuBuffer.map( SoBufferObject.AccessModes.SET ).asFloatBuffer();
     vertData.put(vertices);
     cpuBuffer.unmap();

    EXAMPLE

    Access data stored in a buffer object.

     ByteBuffer data = cpuBuffer.map( SoBufferObject.AccessModes.READ_ONLY );
     byte value = data.get(0);
         . . .
     cpuBuffer.unmap();

    See Also:
    SoGLBufferObject
    • Constructor Detail

      • SoCpuBufferObject

        public SoCpuBufferObject()
        Default constructor. The contents of the buffer are initially empty.
      • SoCpuBufferObject

        public SoCpuBufferObject​(java.nio.ByteBuffer buffer)
        Constructor that takes an existing block of CPU memory.
        This memory is owned, and should be freed by, the application.

        The specified byte buffer must be a direct buffer with native byte order else an IllegalArgumentException is thrown. See below for an example of direct buffer allocation.

         ByteBuffer buffer = ByteBuffer.allocateDirect(numBytes);
         buffer.order(ByteOrder.nativeOrder());
         buffer.put(bytes);
         SoCpuBufferObject cpuBuffer = new SoCpuBufferObject(buffer);

        Parameters:
        buffer - the buffer to manage.
    • Method Detail

      • setSize

        public boolean setSize​(long size)
        Description copied from class: SoBufferObject
        Sets the size in bytes of the buffer object.

        If the requested size is the same as the current size, this method does nothing and returns true. If there is existing memory that is owned by the buffer object, that memory is released. If the requested size is zero, the buffer object is now empty.

        Overrides:
        setSize in class SoBufferObject
        Parameters:
        size - The requested size in bytes.

        Returns:
        true if the operation was successful.

      • setBuffer

        public void setBuffer​(java.nio.ByteBuffer buffer)
        Request that the buffer object manage an existing block of memory.
        The application still owns this memory and is responsible for releasing the memory (when no SoCpuBufferObjects have a reference on it).

        We recommend to use the most aligned memory pointer possible to enable optimized algorithm usage.

        The specified byte buffer must be a direct buffer with native byte order else an IllegalArgumentException is thrown. See below for an example of direct buffer allocation.

         ByteBuffer buffer = ByteBuffer.allocateDirect(numBytes);
         buffer.order(ByteOrder.nativeOrder());
         buffer.put(bytes);
         cpuBuffer.setBuffer(buffer);

        NOTE: If another buffer object is currently mapped into another buffer, the other buffer is automatically unmapped and its contents are undefined.