SoGLBufferObject Class Reference
[GL device]

VSG extension OpenGL buffer object class. More...

#include <Inventor/devices/SoGLBufferObject.h>

Inheritance diagram for SoGLBufferObject:
SoBufferObject SoRefCounter SoTypedObject

List of all members.

Public Types

enum  BufferObjectTarget {
  PIXEL_PACK_BUFFER,
  PIXEL_UNPACK_BUFFER,
  ARRAY_BUFFER,
  ELEMENT_ARRAY_BUFFER,
  SHADER_STORAGE_BUFFER
}
enum  Usage {
  STREAM_DRAW,
  STREAM_READ,
  STREAM_COPY,
  STATIC_DRAW,
  STATIC_READ,
  STATIC_COPY,
  DYNAMIC_DRAW,
  DYNAMIC_READ,
  DYNAMIC_COPY
}

Public Member Functions

 SoGLBufferObject (Usage usage)
void setTarget (BufferObjectTarget target)
BufferObjectTarget getTarget () const
virtual bool setSize (size_t size)
virtual void map (SoBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
virtual void map (SoGLBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
virtual void map (SoCpuBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
virtual void unmap (SoBufferObject *bufferObject)
virtual void unmap (SoCpuBufferObject *bufferObject)
virtual void unmap (SoGLBufferObject *bufferObject)
void memcpy (SoBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
void memcpy (SoGLBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
void memcpy (SoCpuBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
virtual void memset (void *value, size_t valueSize=1, size_t offset=0, size_t count=SO_BUFFER_SIZE_ALL)
void bind ()
void unbind ()
void * map (AccessMode accessMode)
void * map (AccessMode accessMode, size_t offset, size_t count)
void unmap ()
bool isValid ()
GLuint getId () const
virtual SoBufferObjectcreateInstance () const
virtual void clearInstance ()

Static Public Member Functions

static bool isAvailable ()

Friends

class SoCpuBufferObject

Detailed Description

VSG extension OpenGL buffer object class.

This class provides management functions for OpenGL memory buffers.

NOTES:

See SoBufferObject for general information about buffer objects.

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

EXAMPLE

EXAMPLE

SEE ALSO

SoCpuBufferObject

See related examples:

BufferedShapePicking, GPUGeometry, InterleavedVertexAttribFeedback, SimpleVertexAttribFeedback, VertexAttribFeedback, SimpleCUDAKernel, SimpleOpenCLKernel, ComputeSlice, CudaMarchingCubes


Member Enumeration Documentation

This enum declares the possible targets of the buffer.

Enumerator:
PIXEL_PACK_BUFFER 

The buffer is used as a pixel pack buffer, it can be used as texture.

For instance as a Texture Buffer Object (TBO).

PIXEL_UNPACK_BUFFER 

The buffer is used as a pixel unpack buffer, it can be used for readback operation.

For instance as a Pixel Buffer Object (PBO).

ARRAY_BUFFER 

The buffer is used as an array buffer, it can be used for vertices, normals, colors.

For instance as a Vertex Buffer Object (VBO). Tis is the default value.

ELEMENT_ARRAY_BUFFER 

The buffer is used as a pixel pack buffer, it is used to specify the indices for indexed geometries.

For instance a Vertex Buffer Object (VBO).

SHADER_STORAGE_BUFFER 

The buffer is used as a shader storage buffer, it can be used to perform random access reads, writes and atomic memory operations from a shader.

This enum declares the possible usages of the memory allocated for the buffer.

This is a hint to the OpenGL driver implementation as to how a buffer object's data store will be accessed. This enables the OpenGL implementation to make more intelligent decisions that may significantly impact buffer object performance. It does not, however, constrain the actual usage of the data store. usage can be broken down into two parts: first, the frequency of access (modification and usage - STATIC, STREAM, DYNAMIC), and second, the nature of that access - DRAW, COPY, READ.

Enumerator:
STREAM_DRAW 

The data store contents will be modified once and used at most a few times.

The data store contents are modified by the application, and used as the source for GL drawing and image specification commands.

STREAM_READ 

The data store contents will be modified once and used at most a few times.

The data store contents are modified by reading data from the GL, and used to return that data when queried by the application.

STREAM_COPY 

The data store contents will be modified once and used at most a few times.

The data store contents are modified by reading data from the GL, and used as the source for GL drawing and image specification commands.

STATIC_DRAW 

The data store contents will be modified once and used many times.

The data store contents are modified by the application, and used as the source for GL drawing and image specification commands.

STATIC_READ 

The data store contents will be modified once and used many times.

The data store contents are modified by reading data from the GL, and used to return that data when queried by the application.

STATIC_COPY 

The data store contents will be modified once and used many times.

The data store contents are modified by reading data from the GL, and used as the source for GL drawing and image specification commands.

DYNAMIC_DRAW 

The data store contents will be modified repeatedly and used many times.

The data store contents are modified by the application, and used as the source for GL drawing and image specification commands.

DYNAMIC_READ 

The data store contents will be modified repeatedly and used many times.

The data store contents are modified by reading data from the GL, and used to return that data when queried by the application.

DYNAMIC_COPY 

The data store contents will be modified repeatedly and used many times.

The data store contents are modified by reading data from the GL, and used as the source for GL drawing and image specification commands.


Constructor & Destructor Documentation

SoGLBufferObject::SoGLBufferObject ( Usage  usage  ) 

Constructor.

Parameters:
usage The intended usage of this buffer. Use enum Usage

Member Function Documentation

void SoGLBufferObject::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.
virtual void SoGLBufferObject::clearInstance (  )  [virtual]

Free the memory allocated in the buffer object.

Notes:

  • It is not necessary to bind an OpenGL context to call this method.
  • After this call the buffer is invalid (until memory is allocated again).

Implements SoBufferObject.

virtual SoBufferObject* SoGLBufferObject::createInstance (  )  const [virtual]

Create a new buffer with the same properties as the current one.

The new instance will have the same context and device properties, but no memory is allocated so the new buffer is initially invalid.

Implements SoBufferObject.

GLuint SoGLBufferObject::getId (  )  const

Returns the OpenGL id of the buffer.

BufferObjectTarget SoGLBufferObject::getTarget (  )  const

Returns the current buffer target.

Returns:
The actual buffer target. Use enum BufferObjectTarget
static bool SoGLBufferObject::isAvailable (  )  [static]

Query if SoGLBufferObjects are available on this system.

Returns:
Returns true if SoGLBufferObjects are available on this system.
bool SoGLBufferObject::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().
void* SoGLBufferObject::map ( AccessMode  accessMode,
size_t  offset,
size_t  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:
Pointer to data in the mapped region of the OpenGL buffer.
void* SoGLBufferObject::map ( AccessMode  accessMode  ) 

This function maps the OpenGL buffer memory into CPU memory.

So the returned pointer is usable as a regular pointer. 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:
Pointer to data in the OpenGL buffer.
virtual void SoGLBufferObject::map ( SoCpuBufferObject targetBufferObject,
AccessMode  accessMode,
size_t  startPosition = 0,
size_t  mappingSize = SO_BUFFER_SIZE_ALL 
) [virtual]

Map the current buffer object into the specified CPU 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.

Implements SoBufferObject.

virtual void SoGLBufferObject::map ( SoGLBufferObject targetBufferObject,
AccessMode  accessMode,
size_t  startPosition = 0,
size_t  mappingSize = SO_BUFFER_SIZE_ALL 
) [virtual]

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.

Implements SoBufferObject.

virtual void SoGLBufferObject::map ( SoBufferObject targetBufferObject,
AccessMode  accessMode,
size_t  startPosition = 0,
size_t  mappingSize = SO_BUFFER_SIZE_ALL 
) [virtual]

Map the current buffer object into the specified buffer object.

Parameters:
targetBufferObject The buffer object which will be the mapped version of this buffer.
accessMode The access mode used for the mapping. Use enum AccessMode
startPosition offset in source buffer to map from (default is start of buffer).
mappingSize size from the startPosition, if SO_BUFFER_SIZE_ALL then the whole buffer is mapped.
void SoGLBufferObject::memcpy ( SoCpuBufferObject sourceBufferObject,
size_t  destOffset = 0,
size_t  sourceOffset = 0,
size_t  copySize = SO_BUFFER_SIZE_ALL 
) [virtual]

Copy data from a CPU 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

Implements SoBufferObject.

void SoGLBufferObject::memcpy ( SoGLBufferObject sourceBufferObject,
size_t  destOffset = 0,
size_t  sourceOffset = 0,
size_t  copySize = SO_BUFFER_SIZE_ALL 
) [virtual]

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

Implements SoBufferObject.

void SoGLBufferObject::memcpy ( SoBufferObject sourceBufferObject,
size_t  destOffset = 0,
size_t  sourceOffset = 0,
size_t  copySize = SO_BUFFER_SIZE_ALL 
)

Copy data from any SoBufferObject 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.
Parameters:
sourceBufferObject The source buffer object which contains the data to copy.
destOffset The starting offset in the source buffer.
sourceOffset The starting offset in the source buffer.
copySize The size in bytes of the chunk of data to copy.
virtual void SoGLBufferObject::memset ( void *  value,
size_t  valueSize = 1,
size_t  offset = 0,
size_t  count = SO_BUFFER_SIZE_ALL 
) [virtual]

Set the contents of (or a portion of) this buffer object to the specified value.

The valueSize parameter provides a way to do a memset with float, short, byte, etc values. The number of bytes that will be set is exactly valueSize*count. The first byte changed in this buffer is given by the offset argument.

Parameters:
value is a pointer to the value to set in the buffer.
valueSize The size in bytes of the value. Default is 1 byte.
offset The offset in bytes (where to start setting values). Default is 0.
count The number of values to set. Default is number of bytes in buffer.

Notes:

  • A valid OpenGL context (see SoGLContext) must be bound to perform this operation.
  • The current size of the buffer object must be at least valueSize*count bytes.
    See setSize() to allocate memory.

EXAMPLE

   unsigned char memset_value = 0;
   buffer->memset( &memset_value );

Implements SoBufferObject.

virtual bool SoGLBufferObject::setSize ( size_t  size  )  [virtual]

Set the size of the buffer in bytes.

Parameters:
size New size in bytes of the buffer.

Notes:

  • Causes memory to be allocated for the buffer.
  • A valid OpenGL context (see SoGLContext) must be bound to perform this operation.
  • If the buffer is already allocated, the memory is freed and re-allocated with the new size.
    Therefore if you increase the size of the buffer, the original data is lost!

Reimplemented from SoBufferObject.

void SoGLBufferObject::setTarget ( BufferObjectTarget  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. Use enum BufferObjectTarget
void SoGLBufferObject::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.
void SoGLBufferObject::unmap (  ) 

Unmaps the buffer using the regular unmap function.

virtual void SoGLBufferObject::unmap ( SoGLBufferObject bufferObject  )  [virtual]

Unmap the specified GL buffer object.

It is defined just to speed up the call when the type of the object is known.

Implements SoBufferObject.

virtual void SoGLBufferObject::unmap ( SoCpuBufferObject bufferObject  )  [virtual]

Unmap the specified CPU buffer object.

It is defined just to speed up the call when the type of the object is known.

Implements SoBufferObject.

virtual void SoGLBufferObject::unmap ( SoBufferObject bufferObject  )  [virtual]

Unmap the specified buffer object.


Friends And Related Function Documentation

friend class SoCpuBufferObject [friend]

The documentation for this class was generated from the following file:

Open Inventor Toolkit reference manual, generated on 12 Feb 2024
Copyright © Thermo Fisher Scientific All rights reserved.
http://www.openinventor.com/