com.openinventor.inventor.devices

Class SoGLBufferObject

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.devices.SoBufferObject

com.openinventor.inventor.devices.SoGLBufferObject

All Implemented Interfaces:

SafeDisposable

public class SoGLBufferObject
extends SoBufferObject

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

Modifier and Type	Field and Description
static int	ARRAY_BUFFER Deprecated. Use SoGLBufferObject.BufferObjectTargets.ARRAY_BUFFER instead.
static int	DYNAMIC_COPY Deprecated. Use SoGLBufferObject.Usages.DYNAMIC_COPY instead.
static int	DYNAMIC_DRAW Deprecated. Use SoGLBufferObject.Usages.DYNAMIC_DRAW instead.
static int	DYNAMIC_READ Deprecated. Use SoGLBufferObject.Usages.DYNAMIC_READ instead.
static int	ELEMENT_ARRAY_BUFFER Deprecated. Use SoGLBufferObject.BufferObjectTargets.ELEMENT_ARRAY_BUFFER instead.
static int	PIXEL_PACK_BUFFER Deprecated. Use SoGLBufferObject.BufferObjectTargets.PIXEL_PACK_BUFFER instead.
static int	PIXEL_UNPACK_BUFFER Deprecated. Use SoGLBufferObject.BufferObjectTargets.PIXEL_UNPACK_BUFFER instead.
static int	SHADER_STORAGE_BUFFER Deprecated. Use SoGLBufferObject.BufferObjectTargets.SHADER_STORAGE_BUFFER instead.
static int	STATIC_COPY Deprecated. Use SoGLBufferObject.Usages.STATIC_COPY instead.
static int	STATIC_DRAW Deprecated. Use SoGLBufferObject.Usages.STATIC_DRAW instead.
static int	STATIC_READ Deprecated. Use SoGLBufferObject.Usages.STATIC_READ instead.
static int	STREAM_COPY Deprecated. Use SoGLBufferObject.Usages.STREAM_COPY instead.
static int	STREAM_DRAW Deprecated. Use SoGLBufferObject.Usages.STREAM_DRAW instead.
static int	STREAM_READ Deprecated. Use SoGLBufferObject.Usages.STREAM_READ instead.

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

READ_ONLY, READ_WRITE, SET, 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.
java.nio.ByteBuffer	map(SoBufferObject.AccessModes accessMode) This function maps the OpenGL buffer memory into CPU memory.
java.nio.ByteBuffer	map(SoBufferObject.AccessModes accessMode, long offset, long count) This function extends the map(AccessMode) method by allowing the mapping of a sub part of the buffer object into CPU memory.
void	map(SoGLBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode) Calls map(targetBufferObject, accessMode, (long)0, (long)SO_BUFFER_SIZE_ALL).
void	map(SoGLBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode, long startPosition) Calls map(targetBufferObject, accessMode, startPosition, (long)SO_BUFFER_SIZE_ALL).
void	map(SoGLBufferObject targetBufferObject, SoBufferObject.AccessModes accessMode, long startPosition, long mappingSize) Map the current buffer object into the specified GL buffer object.
void	memcpy(SoGLBufferObject sourceBufferObject) Calls memcpy(sourceBufferObject, (long)0, (long)0, (long)SO_BUFFER_SIZE_ALL).
void	memcpy(SoGLBufferObject sourceBufferObject, long destOffset) Calls memcpy(sourceBufferObject, destOffset, (long)0, (long)SO_BUFFER_SIZE_ALL).
void	memcpy(SoGLBufferObject sourceBufferObject, long destOffset, long sourceOffset) Calls memcpy(sourceBufferObject, destOffset, sourceOffset, (long)SO_BUFFER_SIZE_ALL).
void	memcpy(SoGLBufferObject sourceBufferObject, long destOffset, long sourceOffset, long copySize) Copy data from a GL buffer into this buffer.
void	setTarget(SoGLBufferObject.BufferObjectTargets target) Specify the buffer target, which defines possible usage of the buffer.
void	unbind() Unbind the buffer.
void	unmap() Unmaps the buffer using the regular unmap function.
void	unmap(SoGLBufferObject bufferObject) Unmap the specified GL buffer object.

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

clearInstance, createInstance, dispose, getBufferObjectCache, getContext, getMappedBufferObject, getMappingAccessMode, getMappingSize, getMappingStartPosition, getSize, isDisposable, lockBuffer, map, map, map, map, map, map, memcpy, memcpy, memcpy, memcpy, memcpy, memcpy, memcpy, memcpy, setMappedBufferObject, setMappingAccessMode, setMappingZoneInformation, setSize, unlockBuffer, unmap, unmap

Methods inherited from class com.openinventor.inventor.Inventor

getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

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

Field Detail

PIXEL_PACK_BUFFER

@Deprecated
public static final int PIXEL_PACK_BUFFER

Deprecated. Use SoGLBufferObject.BufferObjectTargets.PIXEL_PACK_BUFFER instead.

PIXEL_UNPACK_BUFFER

@Deprecated
public static final int PIXEL_UNPACK_BUFFER

Deprecated. Use SoGLBufferObject.BufferObjectTargets.PIXEL_UNPACK_BUFFER instead.

ARRAY_BUFFER

@Deprecated
public static final int ARRAY_BUFFER

Deprecated. Use SoGLBufferObject.BufferObjectTargets.ARRAY_BUFFER instead.

ELEMENT_ARRAY_BUFFER

@Deprecated
public static final int ELEMENT_ARRAY_BUFFER

Deprecated. Use SoGLBufferObject.BufferObjectTargets.ELEMENT_ARRAY_BUFFER instead.

SHADER_STORAGE_BUFFER

@Deprecated
public static final int SHADER_STORAGE_BUFFER

Deprecated. Use SoGLBufferObject.BufferObjectTargets.SHADER_STORAGE_BUFFER instead.

STREAM_DRAW

@Deprecated
public static final int STREAM_DRAW

Deprecated. Use SoGLBufferObject.Usages.STREAM_DRAW instead.

STREAM_READ

@Deprecated
public static final int STREAM_READ

Deprecated. Use SoGLBufferObject.Usages.STREAM_READ instead.

STREAM_COPY

@Deprecated
public static final int STREAM_COPY

Deprecated. Use SoGLBufferObject.Usages.STREAM_COPY instead.

STATIC_DRAW

@Deprecated
public static final int STATIC_DRAW

Deprecated. Use SoGLBufferObject.Usages.STATIC_DRAW instead.

STATIC_READ

@Deprecated
public static final int STATIC_READ

Deprecated. Use SoGLBufferObject.Usages.STATIC_READ instead.

STATIC_COPY

@Deprecated
public static final int STATIC_COPY

Deprecated. Use SoGLBufferObject.Usages.STATIC_COPY instead.

DYNAMIC_DRAW

@Deprecated
public static final int DYNAMIC_DRAW

Deprecated. Use SoGLBufferObject.Usages.DYNAMIC_DRAW instead.

DYNAMIC_READ

@Deprecated
public static final int DYNAMIC_READ

Deprecated. Use SoGLBufferObject.Usages.DYNAMIC_READ instead.

DYNAMIC_COPY

@Deprecated
public static final int DYNAMIC_COPY

Deprecated. Use SoGLBufferObject.Usages.DYNAMIC_COPY instead.

Constructor Detail

SoGLBufferObject

public SoGLBufferObject(SoGLBufferObject.Usages usage)

Constructor.

Parameters:

usage - The intended usage of this buffer.

Method Detail

memcpy

public void memcpy(SoGLBufferObject sourceBufferObject)

Calls memcpy(sourceBufferObject, (long)0, (long)0, (long)SO_BUFFER_SIZE_ALL).

memcpy

public void memcpy(SoGLBufferObject sourceBufferObject,
                   long destOffset)

Calls memcpy(sourceBufferObject, destOffset, (long)0, (long)SO_BUFFER_SIZE_ALL).

map

public void map(SoGLBufferObject targetBufferObject,
                SoBufferObject.AccessModes accessMode)

Calls map(targetBufferObject, accessMode, (long)0, (long)SO_BUFFER_SIZE_ALL).

map

public void map(SoGLBufferObject targetBufferObject,
                SoBufferObject.AccessModes accessMode,
                long startPosition)

Calls map(targetBufferObject, accessMode, startPosition, (long)SO_BUFFER_SIZE_ALL).

memcpy

public void memcpy(SoGLBufferObject sourceBufferObject,
                   long destOffset,
                   long sourceOffset)

Calls memcpy(sourceBufferObject, destOffset, sourceOffset, (long)SO_BUFFER_SIZE_ALL).

getTarget

public SoGLBufferObject.BufferObjectTargets getTarget()

Returns the current buffer target.

Returns:

The actual buffer target.

map

public java.nio.ByteBuffer map(SoBufferObject.AccessModes accessMode,
                               long offset,
                               long count)

This function extends the map(AccessMode) method by allowing the mapping of a sub part of the buffer object into CPU memory. On some systems this method has better performance.

Notes:

• It is not necessary to bind an OpenGL context before calling this method.
• The unmap() method must be called before using the buffer for any OpenGL operation, otherwise the operation will produce an error.

Returns:

Reference to data in the mapped region of the OpenGL buffer.

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.

map

public void map(SoGLBufferObject targetBufferObject,
                SoBufferObject.AccessModes accessMode,
                long startPosition,
                long mappingSize)

Map the current buffer object into the specified GL buffer object. It is defined just to speed up the call when the type of the object is known.

See the general map function for more information.

map

public java.nio.ByteBuffer map(SoBufferObject.AccessModes accessMode)

This function maps the OpenGL buffer memory into CPU memory. So the returned pointer is usable as a regular reference. See the example code in the class description.

Notes:

• It is not necessary to bind an OpenGL context before calling this method.
• After calling this map() method, the unmap() method must be called before using the buffer for any OpenGL operation, including rendering (e.g. SoBufferedShape), otherwise the operation will produce an OpenGL error.

Returns:

Reference to data in the OpenGL buffer.

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.

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

unmap

public void unmap()

Unmaps the buffer using the regular unmap function.

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.

getId

public int getId()

Returns the OpenGL id of the buffer.

unmap

public void unmap(SoGLBufferObject bufferObject)

Unmap the specified GL buffer object. It is defined just to speed up the call when the type of the object is known.

isAvailable

public static boolean isAvailable()

Query if SoGLBufferObjects are available on this system.

Returns:

Returns true if SoGLBufferObjects are available on this system.

memcpy

public void memcpy(SoGLBufferObject sourceBufferObject,
                   long destOffset,
                   long sourceOffset,
                   long copySize)

Copy data from a GL buffer into this buffer. Notes:

• A valid OpenGL context (see SoGLContext) must be bound to perform this operation.
• The current buffer object must be large enough to hold the data that will be copied. See setSize() to allocate memory.
• Warning: Source and destination overlaping is NOT supported.

This function is a specialized function for speed-up.
See the general memcpy function for more information