SoGpuBufferObject Class Reference

GPU buffer object class More...

#include <Inventor/devices/SoGpuBufferObject.h>

Inheritance diagram for SoGpuBufferObject:

Public Types
enum	BufferAccessFrequency {   STATIC ,   DYNAMIC }
	Available values for hints on how frequently the application will be changing the buffer's data. More...
enum	BufferAccessNature {   SHARED ,   DEVICE }
	Available values for hints on the nature of the application's access to 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
	SoGpuBufferObject (BufferAccessFrequency accessFrequency=STATIC, BufferAccessNature accessNature=SHARED)
	Constructor.
virtual bool	setSize (size_t size)
	Sets the size in bytes of the buffer object.
virtual SoBufferObject *	createInstance () const
	Create a new buffer with the same properties as the current one.
virtual void	clearInstance ()
	This function clears the content of the buffer, it frees the memory if the mode was COPY.
BufferAccessFrequency	getAccessFrequency () const
	Returns the current buffer access frequency hint for this buffer object.
BufferAccessNature	getAccessNature () const
	Returns the current buffer access nature hint for this buffer object.
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 *	map (AccessMode accessMode, size_t offset=0, size_t count=SO_BUFFER_SIZE_ALL)
	Map the buffer to a system memory address and allows the mapping of a sub part of the buffer object into CPU memory.
virtual void	unmap ()
	Unmaps the buffer from CPU address space.
virtual void	map (SoBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)
	Maps the current buffer object into the specified buffer object.
virtual void	unmap (SoBufferObject *bufferObject)
	Unmap this buffer from the specified buffer object.
virtual void	memcpy (SoBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)
	Copies data from the specified buffer object into this 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.
SoDeviceContext *	getContext () const
	Returns the device context where this buffer is valid.
SoBufferObject *	getMappedBufferObject () 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.

Friends
struct	inventor::renderer::Resource< SoBufferObject >

Additional Inherited Members
Static Public Member Functions inherited from SoTypedObject
static SoType	getClassTypeId ()
	Returns the type identifier for this class.
Related Symbols inherited from SoBufferObject
#define	SO_BUFFER_SIZE_ALL   ((std::numeric_limits<size_t>::max)())
	Used to indicate that we want to use the whole buffer.

Detailed Description

GPU buffer object class

This class provides management functions for GPU 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.

See SoBufferObject for general information about buffer objects.

NOTES:

• Creating a GPU buffer requires a current GPU context (like OpenGL).
  For example, regarding the historical viewers the method SoWinGLWidget::bindNormalContext() must be called before using a SoGpuBufferObject. Concerning the viewer components, the window containing the RenderArea must be exposed before using a SoGpuBufferObject.
• Modifying the properties of an GPU buffer require a current GPU context.
  This includes mapping and unmapping the buffer (map()/unmap()), allocating memory (setSize()) and copying data into the buffer (e.g. memcpy()).
• The same instance of SoGpuBufferObject can not be used inside two GPU contexts that are not shared. For example, if an instance of SoBufferedShape contains SoGpuBufferObjects in its fields, this instance can be used in multiple viewers only if their contexts are shared.

• 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 a GPU buffer.

EXAMPLE

Load data into a buffer object.

Create a GPU buffer object and load data from an array in memory:

const float vertices[][3] = {
     1,0.5,0, 0,1,0, -1,0.5,0,
    -1,-1,0, 1,-1,0, 1,0,0, -1,0,0,
    -1,-1.5,0, 1,-1.5,0
};
const int NUM_COORDS = sizeof(vertices) / sizeof(SbVec3f);
 
// Wrap coordinate array in a CPU buffer object
SoRef<SoCpuBufferObject> cpuBuffer = new SoCpuBufferObject( (void*)coords, NUM_COORDS * sizeof(SbVec3f) );
 
// Create a GPU buffer and load data from CPU buffer
// Ensure that a context is created and bound before this step !
//   - If using the historical viewers call the SoWinGLWidget::bindNormalContext() method here
//   - If using viewer components, make sure the window containing the RenderArea is already exposed
SoRef<SoGpuBufferObject> gpuBuffer = new SoGpuBufferObject( SoGpuBufferObject::STATIC, SoGpuBufferObject::SHARED );
gpuBuffer->setSize( cpuBuffer->getSize() ); // Set the buffer size (allocate memory)
gpuBuffer->memcpy( cpuBuffer.ptr() );      // Copy data into the buffer

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

NOTE: Class available since Open Inventor 10.0.

Definition at line 197 of file SoGpuBufferObject.h.

Member Enumeration Documentation

BufferAccessFrequency

enum SoGpuBufferObject::BufferAccessFrequency

Available values for hints on how frequently the application will be changing the buffer's data.

Enumerator
STATIC	The application will set the data once.
DYNAMIC	The application will set the data multiple times.

Definition at line 208 of file SoGpuBufferObject.h.

BufferAccessNature

enum SoGpuBufferObject::BufferAccessNature

Available values for hints on the nature of the application's access to the buffer.

They indicate whether the application will be directly reading or writing the buffer's data.

Enumerator
SHARED	The application will be writing data to the buffer, but will not read it.
DEVICE	The application will be neither writing nor reading the data. Only GPU commands will interact with the buffer. This is typically used when a buffer object is used to pass data from one place to another on GPU side.

Definition at line 223 of file SoGpuBufferObject.h.

Constructor & Destructor Documentation

SoGpuBufferObject()

SoGpuBufferObject::SoGpuBufferObject	(	BufferAccessFrequency	accessFrequency = STATIC,
		BufferAccessNature	accessNature = SHARED
	)

Constructor.

Parameters

accessFrequency	The intended access frequency of this buffer. Use enum BufferAccessFrequency
accessNature	The intended access nature of this buffer. Use enum BufferAccessNature

Member Function Documentation

clearInstance()

virtual void SoGpuBufferObject::clearInstance ( )

virtual

This function clears the content of the buffer, it frees the memory if the mode was COPY.

Implements SoBufferObject.

createInstance()

virtual SoBufferObject * SoGpuBufferObject::createInstance ( ) const

virtual

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

The new instance will have the same context or device properties, but no memory is allocated.

Implements SoBufferObject.

getAccessFrequency()

BufferAccessFrequency SoGpuBufferObject::getAccessFrequency

(

)

const

Returns the current buffer access frequency hint for this buffer object.

getAccessNature()

BufferAccessNature SoGpuBufferObject::getAccessNature

(

)

const

Returns the current buffer access nature hint for this buffer object.

setSize()

virtual bool SoGpuBufferObject::setSize ( size_t  size )

virtual

Sets the size in bytes of the buffer object.

If the requested size is the same as the current size, this method does nothing and returns true. If there is existing memory that is owned by the buffer object, that memory is released. If the requested size is zero, the buffer object is now empty.

Parameters

size	The requested size in bytes.

Returns

true if the operation was successful.

Reimplemented from SoBufferObject.

Friends And Related Symbol Documentation

inventor::renderer::Resource< SoBufferObject >

friend struct inventor::renderer::Resource< SoBufferObject >

friend

Definition at line 280 of file SoGpuBufferObject.h.

---

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

• Inventor/devices/SoGpuBufferObject.h