Open Inventor Release 2024.1.3
 
Loading...
Searching...
No Matches
SoGLBufferObject Class Reference

VSG extension OpenGL buffer object class. More...

#include <Inventor/devices/SoGLBufferObject.h>

+ Inheritance diagram for SoGLBufferObject:

Public Types

enum  BufferObjectTarget {
  PIXEL_PACK_BUFFER ,
  PIXEL_UNPACK_BUFFER ,
  ARRAY_BUFFER ,
  ELEMENT_ARRAY_BUFFER ,
  SHADER_STORAGE_BUFFER
}
 This enum declares the possible targets of the buffer. More...
 
enum  Usage {
  STREAM_DRAW ,
  STREAM_READ ,
  STREAM_COPY ,
  STATIC_DRAW ,
  STATIC_READ ,
  STATIC_COPY ,
  DYNAMIC_DRAW ,
  DYNAMIC_READ ,
  DYNAMIC_COPY
}
 This enum declares the possible usages of the memory allocated for the buffer. More...
 
- Public Types inherited from SoBufferObject
enum  AccessMode {
  READ_ONLY ,
  SET ,
  READ_WRITE
}
 This enum provides the possible access modes for a mapped buffer object. More...
 

Public Member Functions

 SoGLBufferObject (Usage usage)
 Constructor.
 
void setTarget (BufferObjectTarget target)
 Specify the buffer target, which defines possible usage of the buffer.
 
BufferObjectTarget getTarget () const
 Returns the current buffer target.
 
virtual bool setSize (size_t size)
 Set the size of the buffer in bytes.
 
virtual void map (SoBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
 Map the current buffer object into the specified buffer object.
 
virtual void unmap (SoBufferObject *bufferObject)
 Unmap the specified buffer object.
 
void bind ()
 Bind the current buffer to the specified target so it's usable by OpenGL operations.
 
void unbind ()
 Unbind the buffer.
 
virtual void * map (AccessMode accessMode, size_t offset=0, size_t count=SO_BUFFER_SIZE_ALL)
 This function extends the map(AccessMode) method by allowing the mapping of a sub part of the buffer object into CPU memory.
 
virtual void unmap ()
 Unmaps the buffer using the regular unmap function.
 
bool isValid ()
 Query if the buffer is valid in the current context.
 
GLuint getId () const
 Returns the OpenGL id of the buffer.
 
virtual SoBufferObjectcreateInstance () const
 Create a new buffer with the same properties as the current one.
 
virtual void clearInstance ()
 Free the memory allocated in the buffer object.
 
void memcpy (SoBufferObject *source, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
 Copy data from a buffer into this GL buffer.
 
- Public Member Functions inherited from SoInteropBufferObject
 SoInteropBufferObject ()
 Default constructor.
 
- Public Member Functions inherited from SoBufferObject
void lockBuffer ()
 Locks the buffer against concurrent calls from different threads.
 
void unlockBuffer ()
 Unlocks the buffer object.
 
virtual size_t getSize () const
 Returns the size, in bytes, of the buffer object.
 
virtual void memset (void *value, size_t valueSize=1, size_t offset=0, size_t count=SO_BUFFER_SIZE_ALL)
 This function sets the contents of (or a portion of) this buffer object to the specified value.
 
SoDeviceContextgetContext () const
 Returns the device context where this buffer is valid.
 
SoBufferObjectgetMappedBufferObject () const
 Returns a pointer to the buffer object which is mapped by the actual object.
 
AccessMode getMappedBufferObjectAccessMode ()
 Returns the access mode used for the buffer mapping.
 
size_t getMappedBufferObjectPosition () const
 Returns the position in the source buffer mapped in this buffer.
 
size_t getMappedBufferObjectSize () const
 Returns the size of the mapped area in bytes.
 
- Public Member Functions inherited from SoRefCounter
void ref () const
 Adds a reference to an instance.
 
void unref () const
 Removes a reference from an instance.
 
void unrefNoDelete () const
 unrefNoDelete() should be called when it is desired to decrement the reference count, but not delete the instance if this brings the reference count to zero.
 
int getRefCount () const
 Returns current reference count.
 
void lock () const
 lock this instance.
 
void unlock () const
 unlock this instance.
 
- Public Member Functions inherited from SoTypedObject
virtual SoType getTypeId () const =0
 Returns the type identifier for a specific instance.
 
SbBool isOfType (const SoType &type) const
 Returns TRUE if this object is of the type specified in type or is derived from that type.
 
template<typename TypedObjectClass >
SbBool isOfType () const
 Returns TRUE if this object is of the type of class TypedObjectClass or is derived from that class.
 

Static Public Member Functions

static bool isAvailable ()
 Query if SoGLBufferObjects are available on this system.
 
- Static Public Member Functions inherited from SoTypedObject
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 

Additional Inherited Members

Detailed Description

VSG extension 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).
  • SoBufferObject classes are reference counted objects (just like nodes, paths, etc). Therefore you cannot create an SoBufferObject on the stack. And to delete an SoBufferObject you must ref and unref the object. The SoRef smart pointer is a safe and convenient way to create buffer objects. See examples in SoBufferObject.

See SoBufferObject for general information about buffer objects.

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

EXAMPLE

EXAMPLE

    Access data stored in a GPU buffer object.

    float* data = (float*)gpuBuffer->map( SoBufferObject::READ_ONLY );
    float value = data[0];
    value = data[1];
    . . .
    gpuBuffer->unmap();

SEE ALSO

SoCpuBufferObject

Definition at line 227 of file SoGLBufferObject.h.

Member Enumeration Documentation

◆ BufferObjectTarget

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.

Definition at line 237 of file SoGLBufferObject.h.

◆ Usage

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.

Definition at line 279 of file SoGLBufferObject.h.

Constructor & Destructor Documentation

◆ SoGLBufferObject()

SoGLBufferObject::SoGLBufferObject ( Usage  usage)

Constructor.

Parameters
usageThe intended usage of this buffer. Use enum Usage

Member Function Documentation

◆ bind()

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.

◆ clearInstance()

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 SoInteropBufferObject.

◆ createInstance()

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 SoInteropBufferObject.

◆ getId()

GLuint SoGLBufferObject::getId ( ) const

Returns the OpenGL id of the buffer.

◆ getTarget()

BufferObjectTarget SoGLBufferObject::getTarget ( ) const

Returns the current buffer target.

Returns
The actual buffer target. Use enum BufferObjectTarget

◆ isAvailable()

static bool SoGLBufferObject::isAvailable ( )
static

Query if SoGLBufferObjects are available on this system.

Returns
Returns true if SoGLBufferObjects are available on this system.

◆ isValid()

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

◆ map() [1/2]

virtual void * SoGLBufferObject::map ( AccessMode  accessMode,
size_t  offset = 0,
size_t  count = SO_BUFFER_SIZE_ALL 
)
virtual

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.

Reimplemented from SoBufferObject.

◆ map() [2/2]

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
targetBufferObjectThe buffer object which will be the mapped version of this buffer.
accessModeThe access mode used for the mapping. Use enum AccessMode
startPositionoffset in source buffer to map from (default is start of buffer).
mappingSizesize from the startPosition, if SO_BUFFER_SIZE_ALL then the whole buffer is mapped.

Reimplemented from SoBufferObject.

◆ memcpy()

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

Copy data from a buffer into this GL buffer.

Notes:

  • It is not necessary to bind an OpenGL context before calling this method.
  • The current buffer object must be large enough to hold the data that will be copied. See setSize() to allocate memory.
  • If the size or the offset are not valid an error is reported (SoDebugError).
  • This buffer is not resized, if it is too small an error is reported.

This function is a specialized function for speed-up.

Parameters
sourceThe buffer object to be copied.
destOffsetThe starting offset in the destination buffer object, useful for data subsets.
sourceOffsetThe starting offset in the source buffer object, useful for data subsets.
copySizeThe number of bytes to copy from the source buffer object (SO_BUFFER_SIZE_ALL means all).

Reimplemented from SoBufferObject.

◆ setSize()

virtual bool SoGLBufferObject::setSize ( size_t  size)
virtual

Set the size of the buffer in bytes.

Parameters
sizeNew 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.

◆ setTarget()

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
targetThe new target of the buffer. Use enum BufferObjectTarget

◆ unbind()

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.

◆ unmap() [1/2]

virtual void SoGLBufferObject::unmap ( )
virtual

Unmaps the buffer using the regular unmap function.

Reimplemented from SoBufferObject.

◆ unmap() [2/2]

virtual void SoGLBufferObject::unmap ( SoBufferObject bufferObject)
virtual

Unmap the specified buffer object.

Reimplemented from SoBufferObject.


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