SoGpuBufferObject Class Reference
[CPU device]

GPU buffer object class More...

#include <Inventor/devices/SoGpuBufferObject.h>

Inheritance diagram for SoGpuBufferObject:

List of all members.

Public Types
enum	BufferAccessFrequency {   STATIC,   DYNAMIC }
enum	BufferAccessNature {   SHARED,   DEVICE }
Public Member Functions
	SoGpuBufferObject (BufferAccessFrequency accessFrequency=STATIC, BufferAccessNature accessNature=SHARED)
virtual bool	setSize (size_t size)
virtual SoBufferObject *	createInstance () const
virtual void	clearInstance ()
BufferAccessFrequency	getAccessFrequency () const
BufferAccessNature	getAccessNature () const
Friends
struct	inventor::renderer::Resource< SoBufferObject >

---

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.

See related examples:

BufferedShapePicking, GPUGeometry, InterleavedVertexAttribFeedback, SimpleVertexAttribFeedback, VertexAttribFeedback

---

Member Enumeration Documentation

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.

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.

---

Constructor & Destructor Documentation

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

virtual void SoGpuBufferObject::clearInstance

(

)

[virtual]

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

Implements SoBufferObject.

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.

BufferAccessFrequency SoGpuBufferObject::getAccessFrequency

(

)

const

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

BufferAccessNature SoGpuBufferObject::getAccessNature

(

)

const

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

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 Function Documentation

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

---

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

• Inventor/devices/SoGpuBufferObject.h