Open Inventor Release 2024.1.3
 
Loading...
Searching...
No Matches
SoBufferObject Class Referenceabstract

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

#include <Inventor/devices/SoBufferObject.h>

+ Inheritance diagram for SoBufferObject:

Public Types

enum  AccessMode {
  READ_ONLY ,
  SET ,
  READ_WRITE
}
 This enum provides the possible access modes for a mapped buffer object. More...
 

Public Member Functions

void lockBuffer ()
 Locks the buffer against concurrent calls from different threads.
 
void unlockBuffer ()
 Unlocks the buffer object.
 
virtual bool setSize (size_t size)
 Sets the size in bytes of 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.
 
virtual SoBufferObjectcreateInstance () const =0
 Create a new buffer with the same properties as the current one.
 
virtual void clearInstance ()=0
 Free the memory allocated by the buffer object.
 
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.
 

Friends

class SoCpuBufferObject
 

Related Symbols

(Note that these are not member symbols.)

#define SO_BUFFER_SIZE_ALL   ((std::numeric_limits<size_t>::max)())
 Used to indicate that we want to use the whole buffer.
 

Additional Inherited Members

- Static Public Member Functions inherited from SoTypedObject
static SoType getClassTypeId ()
 Returns the type identifier for this class.
 

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.

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 a GPU buffer object (SoGpuBufferObject) 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 SoGpuBuffer 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...
{
. . .
cpuObj->unmap();
delete cpuObj; // ILLEGAL
}
@ READ_ONLY
The target buffer initially has the same contents as the source buffer.
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 i...
virtual void unmap()
Unmaps the buffer from CPU address space.
friend class SoCpuBufferObject
<a href="IconLegend.html"><img src="extTGS.gif" alt="VSG extension" border="0"></a> CPU buffer objec...
Use the following code instead:
{
. . .
cpuObj->unmap();
}
// OR...
{
cpuObj->ref();
. . .
cpuObj->unmap();
cpuObj->unref();
}
void unref() const
Removes a reference from an instance.
void ref() const
Adds a reference to an instance.
Smart pointer for any class inheriting SoRefCounter.
Definition SoRef.h:90

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:

  • 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 pointer. 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 pointer. 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.

SEE ALSO

SoCpuBufferObject, SoGpuBufferObject, SoGLBufferObject, SoCpuDevice, SoGLDevice, SoBufferedShape

Definition at line 195 of file SoBufferObject.h.

Member Enumeration Documentation

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

Definition at line 204 of file SoBufferObject.h.

Member Function Documentation

◆ clearInstance()

virtual void SoBufferObject::clearInstance ( )
pure virtual

Free the memory allocated by the buffer object.

Implemented in SoCpuBufferObject, SoGLBufferObject, SoGpuBufferObject, and SoInteropBufferObject.

◆ createInstance()

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, SoGLBufferObject, SoGpuBufferObject, SoCpuBufferBitSet, and SoInteropBufferObject.

◆ getContext()

SoDeviceContext * SoBufferObject::getContext ( ) const

Returns the device context where this buffer is valid.

Returns
A device context.

◆ getMappedBufferObject()

SoBufferObject * SoBufferObject::getMappedBufferObject ( ) const

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

◆ getMappedBufferObjectAccessMode()

AccessMode SoBufferObject::getMappedBufferObjectAccessMode ( )

Returns the access mode used for the buffer mapping.

◆ getMappedBufferObjectPosition()

size_t SoBufferObject::getMappedBufferObjectPosition ( ) const

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

Returns
Returns a position in bytes.

◆ getMappedBufferObjectSize()

size_t SoBufferObject::getMappedBufferObjectSize ( ) const

Returns the size of the mapped area in bytes.

Returns
The size of the mapped area.

◆ getSize()

virtual size_t SoBufferObject::getSize ( ) const
virtual

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

Returns
The size in bytes of the buffer object.

◆ lockBuffer()

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.

◆ map() [1/2]

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

Map the buffer to a system memory address and allows the mapping of a sub part of the buffer object into CPU memory.

Notes:

  • The unmap() method must be called before using the buffer.
Returns
Pointer to data in the mapped region of the buffer memory.

Reimplemented in SoGLBufferObject, SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

◆ map() [2/2]

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

Maps the current buffer object into the specified buffer object.


This is useful in order to use a buffer in multiple contexts. The default is to map the entire contents of this buffer, but it is also possible to map a subset of this buffer's memory using the startPosition and mappingSize parameters.

A source buffer may be mapped into multiple target buffers. However a target buffer can only be mapped from one source buffer at a time. If a different source buffer is currently mapped into the target buffer, it is automatically unmapped and may be left in an undefined state.

Note: If the current buffer is empty or startPosition is beyond the end of the managed memory, the buffer is not mapped (and an error message is issued in debug builds).

Parameters
targetBufferObjectThe buffer object which will be the mapped version of this buffer.
accessModeThe access mode used for the mapping.
startPositionOffset (in bytes) in source buffer to map from (default is start of buffer).
mappingSizeSize (in bytes) from the startPosition, if SO_BUFFER_SIZE_ALL then the whole buffer is mapped.

Reimplemented in SoGLBufferObject, SoCpuBufferFromVolumeReader, SoCpuBufferBitSet, SoCpuBufferCompressed, and SoCpuBufferUniform.

◆ memcpy()

virtual void SoBufferObject::memcpy ( SoBufferObject sourceBufferObject,
size_t  destOffset = 0,
size_t  sourceOffset = 0,
size_t  copySize = SO_BUFFER_SIZE_ALL 
)
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
sourceBufferObjectThe 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 in SoGLBufferObject, SoCpuBufferUniform, and SoCpuBufferBitSet.

◆ memset()

virtual void SoBufferObject::memset ( void *  value,
size_t  valueSize = 1,
size_t  offset = 0,
size_t  count = SO_BUFFER_SIZE_ALL 
)
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
valueis a pointer to the value to set in the buffer.
valueSizeThe size in bytes of the value. Default is 1 byte.
offsetThe offset in bytes (where to start setting values). Default is 0.
countThe number of values to set. Default is number of bytes in buffer.

EXAMPLE

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

Reimplemented in SoCpuBufferUniform, and SoCpuBufferBitSet.

◆ setSize()

virtual bool SoBufferObject::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
sizeThe requested size in bytes.
Returns
true if the operation was successful.

Reimplemented in SoGLBufferObject, and SoGpuBufferObject.

◆ unlockBuffer()

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.

◆ unmap() [1/2]

virtual void SoBufferObject::unmap ( )
virtual

Unmaps the buffer from CPU address space.

Reimplemented in SoGLBufferObject, SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

◆ unmap() [2/2]

virtual void SoBufferObject::unmap ( SoBufferObject bufferObject)
virtual

Unmap this buffer from the specified buffer object.


In other words, remove the specified target buffer from the list of buffers which this buffer is mapped to. If the access mode supports writing, the specified buffer is sync'd with the current buffer. An error is reported (in debug builds) if the buffer is not mapped to the specified buffer

Parameters
bufferObjectBuffer to be unmapped.

Reimplemented in SoGLBufferObject, SoCpuBufferBitSet, SoCpuBufferCompressed, SoCpuBufferFromVolumeReader, and SoCpuBufferUniform.

Friends And Related Symbol Documentation

◆ SO_BUFFER_SIZE_ALL

#define SO_BUFFER_SIZE_ALL   ((std::numeric_limits<size_t>::max)())
related

Used to indicate that we want to use the whole buffer.

Definition at line 49 of file SoBufferObject.h.

◆ SoCpuBufferObject

friend class SoCpuBufferObject
friend

Definition at line 484 of file SoBufferObject.h.


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