This class provides generic functions to manage buffer objects.

There are specific implementations of this class for buffer objects on each type of device:

• SoCpuBufferObject: A buffer in CPU system memory.

• SoGLBufferObject: A buffer in GPU memory managed through the OpenGL API.

• SoCudaBufferObject: A buffer in GPU memory managed through Nvidia's CUDA API.

• SoOpenCLBufferObject: A buffer (usually) in GPU memory managed through the OpenCL API.

In many cases the abstract SoBufferObject methods allow the application to handle buffer objects without knowing the specific type of the buffer. This is very convenient when computation is implemented on multiple devices. For example if computation is done using CUDA when available, but using the CPU when a CUDA device is not available.

Since version 8.0, some Open Inventor classes take or return data using an SoBufferObject (or derived class). For example texture images (see SoSFImage), geometry data (see SoBufferedShape) and tiles of volume data (see SoLDMDataAccess).

Creating a buffer object

Before creating a non-CPU buffer object you must bind (then unbind) a valid context for the target device. For example, to create an OpenGL buffer object SoGLBufferObject) you can bind the viewer's context using methods in the view class or you can use the class SoGLContext. See the example on the SoGLBuffer page. For an existing buffer object you can use the buffer's Bind()/Unbind()methods or get a valid context to bind using the GetContext()method. Binding this context is necessary before changing buffer properties or calling SetSize(), Memcpy(), Memset(), etc.

Use the SetSize()method to allocate memory in a buffer object. (Note that you must bind a valid context before calling this method on non-CPU buffer objects.) Generally buffer objects have zero size when created. However some buffer object classes have a constructor that takes an existing block of memory as a parameter. In that case the initial size is non-zero. You must allocate memory before copying data into a buffer object using either the Memcpy()method or a direct reference . Memory is automatically allocated, if necessary, when a buffer object is mapped into another buffer object.

• Some buffer objects, e.g. SoCpuBufferObject, have a constructor that takes an existing block of memory as a parameter. In this case the buffer object is automatically set to the necessary size to contain the specified data. Creating an SoCpuBufferObect that "wraps" the existing data is usually the first step in loading data into a non-CPU buffer using Memcpy() or Map().

• The Memcpy()methods copy data into a buffer object from another buffer object. For example to copy data into an OpenGL buffer from a CPU buffer. Before using these methods on a non-CPU buffer object, you must bind (then unbind) a valid context for the target device. The buffer object must be large enough (have enough memory allocated) to hold the data. See the allocating memory topic above.

• The Memset()methods fill a buffer object with a specified value. Before using these methods on a non-CPU buffer object, you must bind (then unbind) a valid context for the target device. The buffer object must be large enough (have enough memory allocated) to hold the data. See the allocating memory topic above.

• The Map()methods that have a buffer object parameter "map" one buffer object into another, usually to allow the data to be accessed on a different device. When the access mode is READ_ONLY or READ_WRITE, the contents of the source buffer are available through the target buffer object after the Map()call. If necessary, Open Inventor will automatically do an inter-device transfer of the data. When the access mode is SET or READ_WRITE, the contents of the modified target buffer object are available through the source buffer object after the Unmap() call. If necessary, Open Inventor will automatically do an inter-device data transfer.

• Some buffer object classes provide a Map()method that maps the buffer's data into CPU memory and returns a reference. If necessary, Open Inventor will automatically do an inter-device transfer of the data. While the buffer is mapped the application can directly modify its data using the returned reference. If the access mode is SET or READ_WRITE, the modified data will be available through the buffer object after the Unmap()call. If necessary, Open Inventor will automatically do an inter-device data transfer.

Reference