com.openinventor.inventor.devices

Class SoGLBufferObject

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.devices.SoBufferObject

com.openinventor.inventor.devices.SoInteropBufferObject

com.openinventor.inventor.devices.SoGLBufferObject

All Implemented Interfaces:

SafeDisposable

public class SoGLBufferObject
extends SoInteropBufferObject

OpenGL buffer object class. This class provides management functions for OpenGL memory buffers.

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)
 glContext.unbind();
 
 // Copy data into the buffer object
 FloatBuffer vertData = gpuBuffer.map( SoBufferObject.AccessModes.SET ).asFloatBuffer();
     vertData.put(vertices);
 gpuBuffer.unmap();

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

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoGLBufferObject.BufferObjectTargets This enum declares the possible targets of the buffer.
static class	SoGLBufferObject.Usages This enum declares the possible usages of the memory allocated for the buffer.

Nested classes/interfaces inherited from class com.openinventor.inventor.devices.SoBufferObject

SoBufferObject.AccessModes

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields inherited from class com.openinventor.inventor.devices.SoBufferObject

SO_BUFFER_SIZE_ALL

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoGLBufferObject(SoGLBufferObject.Usages usage) Constructor.

Method Summary

Modifier and Type	Method and Description
void	bind() Bind the current buffer to the specified target so it's usable by OpenGL operations.
int	getId() Returns the OpenGL id of the buffer.
SoGLBufferObject.BufferObjectTargets	getTarget() Returns the current buffer target.
static boolean	isAvailable() Query if SoGLBufferObjects are available on this system.
boolean	isValid() Query if the buffer is valid in the current context.
void	setTarget(SoGLBufferObject.BufferObjectTargets target) Specify the buffer target, which defines possible usage of the buffer.
void	unbind() Unbind the buffer.

Methods inherited from class com.openinventor.inventor.devices.SoBufferObject

clearInstance, createInstance, dispose, getBufferObjectCache, getContext, getMappedBufferObject, getMappedBufferObjectAccessMode, getMappedBufferObjectPosition, getMappedBufferObjectSize, getSize, isDisposable, lockBuffer, map, map, map, map, map, map, memcpy, memcpy, memcpy, memcpy, setSize, unlockBuffer, unmap, unmap

Methods inherited from class com.openinventor.inventor.Inventor

getNativeResourceHandle

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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().

getTarget

public SoGLBufferObject.BufferObjectTargets getTarget()

Returns the current buffer target.

Returns:

The actual buffer target.