SoBufferObject Class Reference
[Devices]

VSG extension Abstract base class for buffer object management More...

#include <Inventor/devices/SoBufferObject.h>

Inheritance diagram for SoBufferObject:
SoRefCounter SoTypedObject SoCpuBufferObject SoCudaBufferObject SoGLBufferObject SoOpenCLBufferObject SoCpuBufferBasicProperty SoCpuBufferBitSet SoCpuBufferCompressed SoCpuBufferFromVolumeReader SoCpuBufferUniform SoCpuBufferAsyncBasicProperty

List of all members.

Public Types

enum  AccessMode {
  READ_ONLY,
  SET,
  READ_WRITE
}

Public Member Functions

void lockBuffer ()
void unlockBuffer ()
virtual bool setSize (size_t size)
virtual size_t getSize () const
virtual void map (SoBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)=0
virtual void map (SoCpuBufferObject *targetBufferObject, AccessMode accessMode, size_t startPosition=0, size_t mappingSize=SO_BUFFER_SIZE_ALL)=0
virtual void unmap (SoBufferObject *bufferObject)=0
virtual void unmap (SoCpuBufferObject *bufferObject)=0
virtual void memcpy (SoBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)=0
virtual void memcpy (SoCpuBufferObject *sourceBufferObject, size_t destOffset=0, size_t sourceOffset=0, size_t copySize=SO_BUFFER_SIZE_ALL)=0
virtual void memset (void *value, size_t valueSize=1, size_t offset=0, size_t count=SO_BUFFER_SIZE_ALL)=0
virtual SoBufferObject * createInstance () const =0
virtual void clearInstance ()=0
SoDeviceContext * getContext () const
SoBufferObject * getMappedBufferObject ()
void setMappedBufferObject (SoBufferObject *bufferObject)
void setMappingAccessMode (AccessMode accessMode)
AccessMode getMappingAccessMode ()
void setMappingZoneInformation (size_t startPosition, size_t size)
size_t getMappingStartPosition () const
size_t getMappingSize () const

Static Public Member Functions

static SoCpuBufferObjectCache * getBufferObjectCache ()

Detailed Description

VSG extension Abstract base class for buffer object management

This class provides generic functions to manage buffer objects.

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

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.
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. For example, the following code will NOT compile: 
    {
      SoCpuBufferObject cpuObj; // ILLEGAL
      . . .
    }
    // OR...
    {
      SoCpuBufferObject* cpuObj = new SoCpuBufferObject;
      cpuObj->map(SoBufferObject::READ_ONLY);
      . . .
      cpuObj->unmap();
      delete cpuObj;  // ILLEGAL
    }
Use the following code instead: 
    {
      SoRef<SoCpuBufferObject> cpuObj = new SoCpuBufferObject;
      cpuObj->map(SoBufferObject::READ_ONLY);
      . . .
      cpuObj->unmap();
    }
    // OR...
    {
      SoCpuBufferObject* cpuObj = new SoCpuBufferObject;
      cpuObj->ref();
      cpuObj->map(SoBufferObject::READ_ONLY);
      . . .
      cpuObj->unmap();
      cpuObj->unref();
    }

Allocating memory in a buffer object:

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 pointer . Memory is automatically allocated, if necessary, when a buffer object is mapped into another buffer object.

Loading data and retrieving data:

SEE ALSO

SoCpuBufferObject, SoGLBufferObject, SoCudaBufferObject, SoOpenCLBufferObject

SoCpuDevice, SoCudaDevice, SoGLDevice, SoOpenCLDevice

See related examples:

AnimatedShape, SoBufferedShape, MultiInstancingBufferedShape

Member Enumeration Documentation

enum SoBufferObject::AccessMode

This enum provides the possible access modes for a mapped buffer object.

Enumerator:
READ_ONLY 

The target buffer initially has the same contents as the source buffer.

SET 

The target buffer contents are initially undefined (although they may be the same as the source buffer) but the source buffer will contain the contents of the target buffer after the unmap.

READ_WRITE 

The target buffer initially has the same contents as the source buffer and the source buffer will contain the contents of the target buffer after the unmap.

Member Function Documentation

virtual void SoBufferObject::clearInstance (  )  [pure virtual]

Free the memory allocated by the buffer object.

Implemented in SoCpuBufferObject, SoCudaBufferObject, SoGLBufferObject, and SoOpenCLBufferObject.

virtual SoBufferObject* SoBufferObject::createInstance (  )  const [pure 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.

Implemented in SoCpuBufferObject, SoCudaBufferObject, SoGLBufferObject, SoOpenCLBufferObject, and SoCpuBufferBitSet.

static SoCpuBufferObjectCache* SoBufferObject::getBufferObjectCache (  )  [static]

Returns the cache manager object.

This object manages a cache of SoCpuBufferObject objects. SoBufferObject creates an instance of this class that is primarily used for the LDM tile cache (see SoLDMGlobalResourceParameters for more information). The buffer object cache can be accessed using the SoBufferObject static method getBufferObjectCache. Default size is 50 or the value of OIV_BUFFER_OBJECT_CACHE_SIZE.

SoDeviceContext * SoBufferObject::getContext (  )  const [inline]

Returns the device context where this buffer is valid.

Returns:
A device context.
SoBufferObject * SoBufferObject::getMappedBufferObject (  )  [inline]

Returns a pointer to the buffer object which is mapped by the actual object.

SoBufferObject::AccessMode SoBufferObject::getMappingAccessMode (  )  [inline]

Returns the access mode used for the buffer mapping.

size_t SoBufferObject::getMappingSize (  )  const [inline]

Returns the size of the mapped area in bytes.

Returns:
The size of the mapped area.
size_t SoBufferObject::getMappingStartPosition (  )  const [inline]

Returns the position in the source buffer mapped in this buffer.

Returns:
Returns a position in bytes.
size_t SoBufferObject::getSize (  )  const [inline, virtual]

Returns the size, in bytes, of the buffer object.

Returns:
The size in bytes of the buffer object.
void SoBufferObject::lockBuffer (  ) 

Locks the buffer against concurrent calls from different threads.


This is a blocking call. In other words it will not return immediately if another thread currently has the buffer locked.

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

Maps the current buffer object into the specified CPU buffer object.


See the general map method for more information.

Implemented in SoCudaBufferObject, SoGLBufferObject, SoOpenCLBufferObject, SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

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

Maps the current buffer object into the specified buffer object.


It is useful in order to use a buffer in multiple contexts (e.g. OpenGL and CUDA).

Parameters:
targetBufferObject The buffer object which will be the mapped version of this buffer.
accessMode The access mode used for the mapping.
startPosition Offset in source buffer to map from (default is start of buffer).
mappingSize Number of bytes from the startPosition to map (default is SO_BUFFER_SIZE_ALL meaning the whole buffer is mapped.

Implemented in SoCpuBufferObject, SoCudaBufferObject, SoGLBufferObject, and SoOpenCLBufferObject.

virtual void SoBufferObject::memcpy ( SoCpuBufferObject *  sourceBufferObject,
size_t  destOffset = 0,
size_t  sourceOffset = 0,
size_t  copySize = SO_BUFFER_SIZE_ALL 
) [pure virtual]

Copies data from the specified CPU buffer object into this buffer object.


See the general memcpy method for more information.

Implemented in SoCudaBufferObject, SoGLBufferObject, and SoOpenCLBufferObject.

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

Copies data from the specified buffer object into this buffer object.


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.

Warning:
: Source and destination overlaping support is implementation dependent, if not supported an error is reported.
Parameters:
sourceBufferObject The buffer object to be copied.
destOffset The starting offset in the destination buffer object, useful for data subsets.
sourceOffset The starting offset in the source buffer object, useful for data subsets.
copySize The number of bytes to copy from the source buffer object (SO_BUFFER_SIZE_ALL means all).

Implemented in SoCpuBufferObject, SoCudaBufferObject, SoGLBufferObject, and SoOpenCLBufferObject.

virtual void SoBufferObject::memset ( void *  value,
size_t  valueSize = 1,
size_t  offset = 0,
size_t  count = SO_BUFFER_SIZE_ALL 
) [pure virtual]

This function sets 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 set in this buffer object 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.

EXAMPLE 

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

Implemented in SoCpuBufferObject, SoCudaBufferObject, SoGLBufferObject, SoOpenCLBufferObject, SoCpuBufferBitSet, and SoCpuBufferUniform.

void SoBufferObject::setMappedBufferObject ( SoBufferObject *  bufferObject  ) 

This function is used when the instance of buffer object is used to map a buffer.

It stores the pointer on the buffer which is mapped by *this*.

Parameters:
bufferObject The buffer object which is mapped.
void SoBufferObject::setMappingAccessMode ( SoBufferObject::AccessMode  accessMode  )  [inline]

Sets the mapping mode used for the mapping of a buffer object.

Parameters:
accessMode The accessMode used for the mapping.
void SoBufferObject::setMappingZoneInformation ( size_t  startPosition,
size_t  size 
) [inline]

Stores information about the mapping in order to know the subset of the data mapped in the buffer.

bool SoBufferObject::setSize ( size_t  size  )  [inline, virtual]

Sets the size in bytes of the buffer object.


Parameters:
size The requested size in bytes.
Returns:
True if the operation was successful.

Reimplemented in SoCpuBufferObject, SoCudaBufferObject, SoGLBufferObject, SoOpenCLBufferObject, SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

void SoBufferObject::unlockBuffer (  ) 

Unlocks the buffer object.


If a thread calls lockBuffer() then it must call unlockBuffer() to allow other threads to lock the buffer.

virtual void SoBufferObject::unmap ( SoCpuBufferObject *  bufferObject  )  [pure virtual]

Unmap the specified CPU buffer.


See the general unmap method for more information.

Implemented in SoCudaBufferObject, SoGLBufferObject, SoOpenCLBufferObject, SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

virtual void SoBufferObject::unmap ( SoBufferObject *  bufferObject  )  [pure virtual]

Remove the specified bufferObject from the list of buffers which map the current buffer.

If the access mode supports writing the specified buffer is sync'd with the buffer.

Parameters:
bufferObject Buffer to be unmapped.

Implemented in SoCpuBufferObject, SoCudaBufferObject, SoGLBufferObject, and SoOpenCLBufferObject.

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/