Package com.openinventor.inventor.devices

Class SoGLBufferObject

  • All Implemented Interfaces:
    SafeDisposable
    public class SoGLBufferObject
extends SoInteropBufferObject
    OpenGL buffer object class. This class provides management functions for OpenGL memory buffers.

    NOTE: Since Open Inventor 10.4, applications should use SoGPUBufferObject, instead of SoGLBufferObject, in most cases. For example to store vertex data in GPU memory for use with SoBufferedShape or SoVertexShaderParameterBufferObject.

    This class can be used as a wrapper for GL memory buffer management when the application manages OpenGL code directly.

    NOTES:

    • Creating a OpenGL buffer requires a current OpenGL context.
      For example, by calling the viewer's bindNormalContext() method or by creating an SoGLContext object and binding (then unbinding) it.
    • Modifying the properties of an OpenGL buffer require a current OpenGL context.
      This includes changing properties (e.g. setTarget()), allocating memory (setSize()) and copying data into the buffer (e.g. memcpy()). Mapping a buffer does not require explicitly binding a context.
    • The setTarget() method must be called before any operation, as long as OpenGL requires the target for that operation.
    • For detailed use of this class it may be helpful to review and understand the use of OpenGL Buffer Objects, particularly Vertex Buffer Objects (VBO).

    See SoBufferObject for general information about buffer objects.

    See SoBufferedShape for an example of storing vertices in an OpenGL buffer.

    EXAMPLE

    Load data into a buffer object.

    Create a GPU buffer object and load data 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 GPU (OpenGL) buffer and allocate memory
 SoGLContext glContext = new SoGLContext( true );
 glContext.bind();
     SoGLBufferObject gpuBuffer = new SoGLBufferObject( SoGLBufferObject.Usages.STATIC_DRAW );
     gpuBuffer.setTarget( SoGLBufferObject.BufferObjectTargets.ARRAY_BUFFER );
     gpuBuffer.setSize( vertices.length * Float.SIZE/8 ); // Set the buffer size (allocate memory)
 
 // Copy data into the buffer object
 FloatBuffer vertData = gpuBuffer.map( SoBufferObject.AccessModes.SET ).asFloatBuffer();
     vertData.put(vertices);
 gpuBuffer.unmap();
 
 glContext.unbind();
    Load data into an existing GPU buffer from a CPU buffer: 
     SoGLContext ctx = (SoGLContext)gpuBuffer.getContext();
 ctx.bind();
     gpuBuffer.setSize( cpuBuffer.getSize() ); // Set the buffer size (allocate memory)
     gpuBuffer.memcpy ( cpuBuffer );           // Copy data into the buffer
 ctx.unbind();
    Or 
     cpuBuffer.map( gpuBuffer, SoBufferObject.AccessModes.READ_ONLY );
 cpuBuffer.unmap();

    EXAMPLE

    Access data stored in a GPU buffer object. 

     FloatBuffer data = gpuBuffer.map( SoBufferObject.AccessModes.READ_ONLY ).asFloatBuffer();
 float value = data.get(0);
 value = data.get(1);
     . . .
 gpuBuffer.unmap();

    See Also:
    SoCpuBufferObject

    • Constructor Detail

      • SoGLBufferObject

        public SoGLBufferObject​(SoGLBufferObject.Usages usage)
        Constructor.

        Parameters:
        usage - The intended usage of this buffer.

    • Method Detail

      • unbind

        public void unbind()
        Unbind the buffer. Notes:
        • A valid OpenGL context (see SoGLContext) must be bound before calling this method.
        • Most applications will not need to use this method, because the other methods in this class (map, memcpy, etc) unbind the buffer automatically. It may be useful when making direct calls to OpenGL. It corresponds to the glBindBuffer() call with an id of 0.

      • bind

        public void bind()
        Bind the current buffer to the specified target so it's usable by OpenGL operations. Notes:
        • Most applications will not need to use this method, because the other methods in this class (map, memcpy, etc) bind the buffer to its target automatically. It may be useful when making direct calls to OpenGL. It corresponds to the glBindBuffer() call.
        • A valid OpenGL context (see SoGLContext) must be bound before calling this method.

      • setTarget

        public void setTarget​(SoGLBufferObject.BufferObjectTargets target)
        Specify the buffer target, which defines possible usage of the buffer. WARNING: The function setTarget must be called before any operation for which OpenGL requires the target to be specified.

        Parameters:
        target - The new target of the buffer.

      • isAvailable

        public static boolean isAvailable()
        Query if SoGLBufferObjects are available on this system.

        Returns:
        Returns true if SoGLBufferObjects are available on this system.

      • getId

        public int getId()
        Returns the OpenGL id of the buffer.

      • isValid

        public boolean isValid()
        Query if the buffer is valid in the current context. Notes:
        • It is not necessary to bind an OpenGL context to call this method.
        • The buffer object will be invalid until memory is allocated, either explicitly (see setSize()) or implicitly (e.g. mapping from another buffer).
        • The buffer object will be invalid after calling clearInstance().